Reorganize repo structure and standards references
This commit is contained in:
1 parent
3cb93a81be
commit
be2054274d
5885 files changed
+2588
-195
No files matched your search
@@ -0,0 +1,188 @@
|
||||
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
|
||||
import {
|
||||
configureSessionStorage,
|
||||
rehydrateAuth,
|
||||
persistSession,
|
||||
clearSession,
|
||||
createMobileApiClient,
|
||||
type MobileSession,
|
||||
type SessionStorage,
|
||||
} from "./auth.js";
|
||||
|
||||
function createMemoryStorage(): SessionStorage & { _value: MobileSession | null } {
|
||||
const state: { value: MobileSession | null } = { value: null };
|
||||
return {
|
||||
async read() {
|
||||
return state.value;
|
||||
},
|
||||
async write(session) {
|
||||
state.value = session;
|
||||
},
|
||||
async clear() {
|
||||
state.value = null;
|
||||
},
|
||||
get _value() {
|
||||
return state.value;
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
describe("rehydrateAuth", () => {
|
||||
beforeEach(() => {
|
||||
configureSessionStorage(null);
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
vi.unstubAllGlobals();
|
||||
});
|
||||
|
||||
it("returns null when no storage adapter is configured and Capacitor is absent", async () => {
|
||||
// Force the default path; node + no Capacitor + no localStorage seed.
|
||||
// Some node test runners surface a `localStorage` global without the
|
||||
// full API surface, so we only call methods we know exist.
|
||||
const ls = (globalThis as { localStorage?: { removeItem?: (k: string) => void } }).localStorage;
|
||||
if (typeof ls?.removeItem === "function") {
|
||||
ls.removeItem("toolctrl.session.v1");
|
||||
}
|
||||
const result = await rehydrateAuth();
|
||||
expect(result).toBeNull();
|
||||
});
|
||||
|
||||
it("returns the stored session when one exists", async () => {
|
||||
const storage = createMemoryStorage();
|
||||
configureSessionStorage(storage);
|
||||
await persistSession({ token: "abc", userId: "u-1", tenantId: "t-1" });
|
||||
const result = await rehydrateAuth();
|
||||
expect(result).toEqual({ token: "abc", userId: "u-1", tenantId: "t-1" });
|
||||
});
|
||||
|
||||
it("swallows storage errors and returns null", async () => {
|
||||
configureSessionStorage({
|
||||
async read() {
|
||||
throw new Error("keychain locked");
|
||||
},
|
||||
async write() {
|
||||
/* noop */
|
||||
},
|
||||
async clear() {
|
||||
/* noop */
|
||||
},
|
||||
});
|
||||
expect(await rehydrateAuth()).toBeNull();
|
||||
});
|
||||
|
||||
it("rehydrates a valid session from the web localStorage fallback", async () => {
|
||||
const localStorage = createLocalStorageStub({
|
||||
"toolctrl.session.v1": JSON.stringify({
|
||||
token: "tok-local",
|
||||
userId: "user-local",
|
||||
tenantId: "tenant-local",
|
||||
expiresAt: 1_800_000_000_000,
|
||||
}),
|
||||
});
|
||||
vi.stubGlobal("localStorage", localStorage);
|
||||
|
||||
await expect(rehydrateAuth()).resolves.toEqual({
|
||||
token: "tok-local",
|
||||
userId: "user-local",
|
||||
tenantId: "tenant-local",
|
||||
expiresAt: 1_800_000_000_000,
|
||||
});
|
||||
});
|
||||
|
||||
it("ignores corrupt or incomplete localStorage sessions", async () => {
|
||||
const localStorage = createLocalStorageStub({
|
||||
"toolctrl.session.v1": JSON.stringify({ token: "", userId: "user-local", tenantId: "tenant-local" }),
|
||||
});
|
||||
vi.stubGlobal("localStorage", localStorage);
|
||||
|
||||
await expect(rehydrateAuth()).resolves.toBeNull();
|
||||
|
||||
localStorage.setItem("toolctrl.session.v1", "not-json");
|
||||
await expect(rehydrateAuth()).resolves.toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
describe("persistSession / clearSession", () => {
|
||||
it("writes the session via the configured storage and clears it on demand", async () => {
|
||||
const storage = createMemoryStorage();
|
||||
configureSessionStorage(storage);
|
||||
await persistSession({ token: "x", userId: "u", tenantId: null });
|
||||
expect(storage._value).toEqual({ token: "x", userId: "u", tenantId: null });
|
||||
await clearSession();
|
||||
expect(storage._value).toBeNull();
|
||||
});
|
||||
|
||||
it("uses the web localStorage fallback when no native storage bridge is available", async () => {
|
||||
configureSessionStorage(null);
|
||||
const localStorage = createLocalStorageStub();
|
||||
vi.stubGlobal("localStorage", localStorage);
|
||||
|
||||
await persistSession({ token: "tok-web", userId: "user-web", tenantId: "" });
|
||||
expect(JSON.parse(localStorage.getItem("toolctrl.session.v1") ?? "{}")).toEqual({
|
||||
token: "tok-web",
|
||||
userId: "user-web",
|
||||
tenantId: "",
|
||||
});
|
||||
|
||||
await expect(rehydrateAuth()).resolves.toEqual({ token: "tok-web", userId: "user-web", tenantId: null });
|
||||
|
||||
await clearSession();
|
||||
expect(localStorage.getItem("toolctrl.session.v1")).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
describe("createMobileApiClient", () => {
|
||||
it("creates a client whose Authorization header rehydrates from storage on each call", async () => {
|
||||
const storage = createMemoryStorage();
|
||||
configureSessionStorage(storage);
|
||||
|
||||
let observedAuth: string | null = null;
|
||||
const fakeFetch: typeof fetch = async (_input, init) => {
|
||||
const headers = new Headers(init?.headers);
|
||||
observedAuth = headers.get("authorization");
|
||||
return new Response(JSON.stringify({ ok: true }), { status: 200, headers: { "content-type": "application/json" } });
|
||||
};
|
||||
|
||||
const client = await createMobileApiClient({
|
||||
baseUrl: "https://api.example.test",
|
||||
storage,
|
||||
fetchImpl: fakeFetch,
|
||||
});
|
||||
expect(client).toBeDefined();
|
||||
|
||||
// First call has no session => bearer is empty (Headers normalizes
|
||||
// trailing whitespace, so the observed value is just "Bearer").
|
||||
await client.request({ method: "GET", path: "/v1/status" });
|
||||
expect(observedAuth).toBe("Bearer");
|
||||
|
||||
// Persist a session => the same client now forwards the live token
|
||||
await persistSession({ token: "tok-42", userId: "u-1", tenantId: "t-1" });
|
||||
await client.request({ method: "GET", path: "/v1/status" });
|
||||
expect(observedAuth).toBe("Bearer tok-42");
|
||||
});
|
||||
});
|
||||
|
||||
function createLocalStorageStub(seed: Record<string, string> = {}): Storage {
|
||||
const values = new Map(Object.entries(seed));
|
||||
return {
|
||||
get length() {
|
||||
return values.size;
|
||||
},
|
||||
clear() {
|
||||
values.clear();
|
||||
},
|
||||
getItem(key: string) {
|
||||
return values.get(key) ?? null;
|
||||
},
|
||||
key(index: number) {
|
||||
return [...values.keys()][index] ?? null;
|
||||
},
|
||||
removeItem(key: string) {
|
||||
values.delete(key);
|
||||
},
|
||||
setItem(key: string, value: string) {
|
||||
values.set(key, value);
|
||||
},
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,216 @@
|
||||
/**
|
||||
* Native auth wrapper for the Capacitor mobile shell.
|
||||
*
|
||||
* Bridges three concerns:
|
||||
*
|
||||
* 1. Persistent session-token storage via `@capacitor/preferences` (backed by
|
||||
* UserDefaults on iOS and SharedPreferences on Android — see the plugin's
|
||||
* docs). Web fallback uses plain `localStorage` so the same code path works
|
||||
* in the Vite dev server. This adapter is not encrypted storage; use
|
||||
* short-lived bearer material or swap in a native secure-storage adapter
|
||||
* before persisting long-lived refresh tokens.
|
||||
* 2. Construction of a `@toolctrl/api-client-ts` client wired to the
|
||||
* stored token via the `getToken` callback the SDK exposes — this is
|
||||
* the only sanctioned way to inject a refresh-aware bearer.
|
||||
* 3. Login / logout helpers that the React Router v7 web app calls from
|
||||
* its `nativeAuth.server` adapter when `Capacitor.isNativePlatform()`
|
||||
* returns true.
|
||||
*
|
||||
* The plugin import is intentionally dynamic — Vitest under node resolves
|
||||
* `@capacitor/preferences` against a fallback so unit tests can swap
|
||||
* implementations without dragging the native bridge into the bundle.
|
||||
*
|
||||
* @see ./auth.test.ts for the contract surface
|
||||
* @see packages/api-client-ts/src/client.ts ToolctrlAuthConfig
|
||||
*/
|
||||
import { createToolctrlClient, type ToolctrlClient } from "@toolctrl/api-client-ts";
|
||||
|
||||
const SESSION_PREF_KEY = "toolctrl.session.v1";
|
||||
|
||||
export interface MobileSession {
|
||||
/** Bearer token forwarded as `Authorization: Bearer <token>`. */
|
||||
token: string;
|
||||
/** Owning user id (denormalized so we can render an account page offline). */
|
||||
userId: string;
|
||||
/** Active tenant scope; `null` when the user is in tenant-picker state. */
|
||||
tenantId: string | null;
|
||||
/** Optional expiry epoch-ms — when set, callers should refresh before this. */
|
||||
expiresAt?: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* Pluggable secure-storage adapter. The default implementation lazy-loads
|
||||
* `@capacitor/preferences`; tests inject a Map-backed adapter via
|
||||
* `configureSessionStorage()`.
|
||||
*/
|
||||
export interface SessionStorage {
|
||||
read(): Promise<MobileSession | null>;
|
||||
write(session: MobileSession): Promise<void>;
|
||||
clear(): Promise<void>;
|
||||
}
|
||||
|
||||
let storageOverride: SessionStorage | null = null;
|
||||
|
||||
/** Test-seam — swap the storage implementation. */
|
||||
export function configureSessionStorage(adapter: SessionStorage | null): void {
|
||||
storageOverride = adapter;
|
||||
}
|
||||
|
||||
async function getStorage(): Promise<SessionStorage> {
|
||||
if (storageOverride) return storageOverride;
|
||||
return defaultCapacitorStorage;
|
||||
}
|
||||
|
||||
/**
|
||||
* Default storage adapter. Uses dynamic import so the native bridge is
|
||||
* only required at runtime — unit tests that never call `getStorage()`
|
||||
* never load the native package.
|
||||
*/
|
||||
const defaultCapacitorStorage: SessionStorage = {
|
||||
async read(): Promise<MobileSession | null> {
|
||||
const prefs = await loadPreferencesPlugin();
|
||||
if (!prefs) return readFromLocalStorage();
|
||||
const { value } = await prefs.get({ key: SESSION_PREF_KEY });
|
||||
if (!value) return null;
|
||||
return parseSession(value);
|
||||
},
|
||||
async write(session: MobileSession): Promise<void> {
|
||||
const prefs = await loadPreferencesPlugin();
|
||||
const serialized = JSON.stringify(session);
|
||||
if (!prefs) {
|
||||
writeToLocalStorage(serialized);
|
||||
return;
|
||||
}
|
||||
await prefs.set({ key: SESSION_PREF_KEY, value: serialized });
|
||||
},
|
||||
async clear(): Promise<void> {
|
||||
const prefs = await loadPreferencesPlugin();
|
||||
if (!prefs) {
|
||||
removeFromLocalStorage();
|
||||
return;
|
||||
}
|
||||
await prefs.remove({ key: SESSION_PREF_KEY });
|
||||
},
|
||||
};
|
||||
|
||||
interface PreferencesPlugin {
|
||||
get(opts: { key: string }): Promise<{ value: string | null }>;
|
||||
set(opts: { key: string; value: string }): Promise<void>;
|
||||
remove(opts: { key: string }): Promise<void>;
|
||||
}
|
||||
|
||||
async function loadPreferencesPlugin(): Promise<PreferencesPlugin | null> {
|
||||
// Skip the native plugin entirely when Capacitor reports a non-native
|
||||
// platform (incl. our Vitest node-runner unit tests). The web proxy
|
||||
// of @capacitor/preferences throws an "UNIMPLEMENTED" error if we
|
||||
// call get/set without a native bridge attached.
|
||||
try {
|
||||
const core: { Capacitor?: { isNativePlatform?: () => boolean } } = await import(
|
||||
/* @vite-ignore */ "@capacitor/core"
|
||||
);
|
||||
if (typeof core.Capacitor?.isNativePlatform === "function" && !core.Capacitor.isNativePlatform()) {
|
||||
return null;
|
||||
}
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
try {
|
||||
const mod: { Preferences?: PreferencesPlugin } = await import(
|
||||
/* @vite-ignore */ "@capacitor/preferences"
|
||||
);
|
||||
return mod.Preferences ?? null;
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
function parseSession(value: string): MobileSession | null {
|
||||
try {
|
||||
const parsed: unknown = JSON.parse(value);
|
||||
if (!parsed || typeof parsed !== "object") return null;
|
||||
const record = parsed as Record<string, unknown>;
|
||||
if (typeof record.token !== "string" || record.token === "") return null;
|
||||
if (typeof record.userId !== "string" || record.userId === "") return null;
|
||||
const tenantId = typeof record.tenantId === "string" && record.tenantId !== "" ? record.tenantId : null;
|
||||
const expiresAt = typeof record.expiresAt === "number" ? record.expiresAt : undefined;
|
||||
return { token: record.token, userId: record.userId, tenantId, expiresAt };
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
function readFromLocalStorage(): MobileSession | null {
|
||||
if (typeof globalThis === "undefined") return null;
|
||||
const ls = (globalThis as { localStorage?: Storage }).localStorage;
|
||||
if (!ls || typeof ls.getItem !== "function") return null;
|
||||
const value = ls.getItem(SESSION_PREF_KEY);
|
||||
return value ? parseSession(value) : null;
|
||||
}
|
||||
|
||||
function writeToLocalStorage(value: string): void {
|
||||
if (typeof globalThis === "undefined") return;
|
||||
const ls = (globalThis as { localStorage?: Storage }).localStorage;
|
||||
if (ls && typeof ls.setItem === "function") {
|
||||
ls.setItem(SESSION_PREF_KEY, value);
|
||||
}
|
||||
}
|
||||
|
||||
function removeFromLocalStorage(): void {
|
||||
if (typeof globalThis === "undefined") return;
|
||||
const ls = (globalThis as { localStorage?: Storage }).localStorage;
|
||||
if (ls && typeof ls.removeItem === "function") {
|
||||
ls.removeItem(SESSION_PREF_KEY);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Loads the stored session (if any) at app cold-start. Errors are swallowed
|
||||
* — a missing/corrupt session simply lands the user on the login screen.
|
||||
*/
|
||||
export async function rehydrateAuth(): Promise<MobileSession | null> {
|
||||
try {
|
||||
const storage = await getStorage();
|
||||
return await storage.read();
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
export async function persistSession(session: MobileSession): Promise<void> {
|
||||
const storage = await getStorage();
|
||||
await storage.write(session);
|
||||
}
|
||||
|
||||
export async function clearSession(): Promise<void> {
|
||||
const storage = await getStorage();
|
||||
await storage.clear();
|
||||
}
|
||||
|
||||
export interface MobileClientOptions {
|
||||
/** API base URL, e.g. `https://api.toolctrl.de`. */
|
||||
baseUrl: string;
|
||||
/** Override the default storage adapter — primarily for tests. */
|
||||
storage?: SessionStorage;
|
||||
/** Custom fetch implementation (Capacitor-Http bridge in production). */
|
||||
fetchImpl?: typeof fetch;
|
||||
}
|
||||
|
||||
/**
|
||||
* Builds a `ToolctrlClient` whose `Authorization` header is rehydrated
|
||||
* from persistent mobile storage on every call. The client transparently handles
|
||||
* the "no session yet" case by emitting an empty bearer that the API
|
||||
* rejects with 401 — callers should branch on that to show the login UI.
|
||||
*/
|
||||
export async function createMobileApiClient(options: MobileClientOptions): Promise<ToolctrlClient> {
|
||||
const storage = options.storage ?? (await getStorage());
|
||||
return createToolctrlClient({
|
||||
baseUrl: options.baseUrl,
|
||||
auth: {
|
||||
getToken: async () => {
|
||||
const session = await storage.read();
|
||||
return session?.token ?? "";
|
||||
},
|
||||
},
|
||||
fetch: options.fetchImpl,
|
||||
});
|
||||
}
|
||||
@@ -0,0 +1,22 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
import { readLiveReloadUrl } from "../capacitor.config.js";
|
||||
|
||||
describe("readLiveReloadUrl", () => {
|
||||
it("returns undefined when live reload is not configured", () => {
|
||||
expect(readLiveReloadUrl(undefined)).toBeUndefined();
|
||||
expect(readLiveReloadUrl(" ")).toBeUndefined();
|
||||
});
|
||||
|
||||
it("preserves valid http and https URLs", () => {
|
||||
expect(readLiveReloadUrl(" http://10.0.2.2:3000 ")).toBe("http://10.0.2.2:3000");
|
||||
expect(readLiveReloadUrl("https://staging.example.test")).toBe("https://staging.example.test");
|
||||
});
|
||||
|
||||
it("rejects unsupported protocols", () => {
|
||||
expect(() => readLiveReloadUrl("ftp://example.test")).toThrow(/http/);
|
||||
});
|
||||
|
||||
it("rejects relative URLs", () => {
|
||||
expect(() => readLiveReloadUrl("localhost:3000")).toThrow(/absolute/);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,78 @@
|
||||
import { describe, expect, it, vi } from "vitest";
|
||||
import { bootstrapMobileShell, type MobileBootstrapDeps } from "./index.js";
|
||||
import type { MobileSession } from "./auth.js";
|
||||
import type { registerPushNotifications } from "./pushRegistration.js";
|
||||
|
||||
const baseOptions = {
|
||||
apiBaseUrl: "https://api.example.test",
|
||||
environment: "test",
|
||||
release: "mobile-test",
|
||||
sentryDsn: "https://sentry.example/1",
|
||||
};
|
||||
|
||||
function createDeps(session: MobileSession | null): Required<MobileBootstrapDeps> {
|
||||
return {
|
||||
initSentry: vi.fn(async () => true),
|
||||
rehydrate: vi.fn(async () => session),
|
||||
registerPush: vi.fn<typeof registerPushNotifications>(async () => ({ status: "skipped", reason: "web-platform" })),
|
||||
};
|
||||
}
|
||||
|
||||
describe("bootstrapMobileShell", () => {
|
||||
it("does not request push registration without a stored session", async () => {
|
||||
const deps = createDeps(null);
|
||||
|
||||
const result = await bootstrapMobileShell(baseOptions, deps);
|
||||
|
||||
expect(result).toEqual({ sentryInitialized: true, hasStoredSession: false });
|
||||
expect(deps.initSentry).toHaveBeenCalledWith({
|
||||
dsn: baseOptions.sentryDsn,
|
||||
environment: baseOptions.environment,
|
||||
release: baseOptions.release,
|
||||
});
|
||||
expect(deps.rehydrate).toHaveBeenCalledOnce();
|
||||
expect(deps.registerPush).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("fires push registration after a stored session is rehydrated", async () => {
|
||||
const deps = createDeps({ token: "tok_1", userId: "user_1", tenantId: "tenant_1" });
|
||||
|
||||
const result = await bootstrapMobileShell(baseOptions, deps);
|
||||
|
||||
expect(result).toEqual({ sentryInitialized: true, hasStoredSession: true });
|
||||
expect(deps.registerPush).toHaveBeenCalledWith({ apiBaseUrl: baseOptions.apiBaseUrl });
|
||||
});
|
||||
|
||||
it("does not request push registration for a stored session without an API base URL", async () => {
|
||||
const deps = createDeps({ token: "tok_1", userId: "user_1", tenantId: "tenant_1" });
|
||||
|
||||
const result = await bootstrapMobileShell({ ...baseOptions, apiBaseUrl: "" }, deps);
|
||||
|
||||
expect(result).toEqual({ sentryInitialized: true, hasStoredSession: true });
|
||||
expect(deps.registerPush).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("swallows bootstrap dependency failures so the WebView can still start", async () => {
|
||||
const deps: Required<MobileBootstrapDeps> = {
|
||||
initSentry: vi.fn(async () => {
|
||||
throw new Error("sentry unavailable");
|
||||
}),
|
||||
rehydrate: vi.fn(async () => {
|
||||
throw new Error("keychain locked");
|
||||
}),
|
||||
registerPush: vi.fn<typeof registerPushNotifications>(async () => ({ status: "registered", platform: "ios", pushProvider: "apns" })),
|
||||
};
|
||||
|
||||
const result = await bootstrapMobileShell(baseOptions, deps);
|
||||
|
||||
expect(result).toEqual({ sentryInitialized: false, hasStoredSession: false });
|
||||
expect(deps.registerPush).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("does not await or surface push registration failures", async () => {
|
||||
const deps = createDeps({ token: "tok_1", userId: "user_1", tenantId: null });
|
||||
vi.mocked(deps.registerPush).mockRejectedValue(new Error("native prompt failed"));
|
||||
|
||||
await expect(bootstrapMobileShell(baseOptions, deps)).resolves.toEqual({ sentryInitialized: true, hasStoredSession: true });
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,83 @@
|
||||
/**
|
||||
* Entry point for the Capacitor native wrapper.
|
||||
*
|
||||
* The actual UI is the React Router v7 web app at `apps/web/`. This
|
||||
* file only handles bootstrap concerns that are specific to the native
|
||||
* shell — Sentry init, auth-token rehydration from Capacitor Preferences,
|
||||
* push-notification permission flow.
|
||||
*
|
||||
* It is intentionally side-effect free in test environments; the
|
||||
* `bootstrapMobileShell()` export is invoked from the platform
|
||||
* AppDelegate.swift / MainActivity.java bridge once the WebView is
|
||||
* available.
|
||||
*
|
||||
* @see ./auth.ts
|
||||
* @see ./sentry.ts
|
||||
* @see ./pushRegistration.ts
|
||||
*/
|
||||
import { initMobileSentry } from "./sentry.js";
|
||||
import { rehydrateAuth, type MobileSession } from "./auth.js";
|
||||
import { registerPushNotifications } from "./pushRegistration.js";
|
||||
|
||||
export interface MobileBootstrapOptions {
|
||||
/** Sentry DSN, falls back to the same DSN as the web client. */
|
||||
sentryDsn?: string;
|
||||
/** API base URL for the TS-SDK client. */
|
||||
apiBaseUrl: string;
|
||||
/** Build identifier used as Sentry release. */
|
||||
release?: string;
|
||||
/** Environment tag (`production` / `staging` / `development`). */
|
||||
environment?: string;
|
||||
}
|
||||
|
||||
export interface MobileBootstrapResult {
|
||||
sentryInitialized: boolean;
|
||||
hasStoredSession: boolean;
|
||||
}
|
||||
|
||||
export interface MobileBootstrapDeps {
|
||||
initSentry?: typeof initMobileSentry;
|
||||
rehydrate?: typeof rehydrateAuth;
|
||||
registerPush?: typeof registerPushNotifications;
|
||||
}
|
||||
|
||||
/**
|
||||
* Boots the native shell. Idempotent — safe to call from re-entrant
|
||||
* lifecycle hooks. Errors in any sub-step are swallowed so the WebView
|
||||
* always starts; failures are reported via Sentry when the SDK is up.
|
||||
*/
|
||||
export async function bootstrapMobileShell(options: MobileBootstrapOptions, deps: MobileBootstrapDeps = {}): Promise<MobileBootstrapResult> {
|
||||
const initSentry = deps.initSentry ?? initMobileSentry;
|
||||
const rehydrate = deps.rehydrate ?? rehydrateAuth;
|
||||
const registerPush = deps.registerPush ?? registerPushNotifications;
|
||||
|
||||
const sentryInitialized = await swallowBootstrapStep(false, () =>
|
||||
initSentry({
|
||||
dsn: options.sentryDsn,
|
||||
release: options.release,
|
||||
environment: options.environment,
|
||||
})
|
||||
);
|
||||
|
||||
const session = await swallowBootstrapStep<MobileSession | null>(null, () => rehydrate());
|
||||
const hasStoredSession = Boolean(session);
|
||||
|
||||
// Push registration is opt-in: only register when we already have an
|
||||
// auth token, otherwise we'd ask for the permission prompt on the
|
||||
// very first cold start which is poor UX. The web app's login flow
|
||||
// is responsible for calling `registerPushNotifications()` after
|
||||
// authentication completes.
|
||||
if (hasStoredSession && options.apiBaseUrl) {
|
||||
void registerPush({ apiBaseUrl: options.apiBaseUrl }).catch(() => undefined);
|
||||
}
|
||||
|
||||
return { sentryInitialized, hasStoredSession };
|
||||
}
|
||||
|
||||
async function swallowBootstrapStep<T>(fallback: T, task: () => Promise<T>): Promise<T> {
|
||||
try {
|
||||
return await task();
|
||||
} catch {
|
||||
return fallback;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,271 @@
|
||||
import { beforeEach, describe, expect, it, vi } from "vitest";
|
||||
import { type MobileSession, type SessionStorage } from "./auth.js";
|
||||
import { registerPushNotifications, type PushNotificationsBridge } from "./pushRegistration.js";
|
||||
|
||||
function createMemoryStorage(session: MobileSession | null): SessionStorage {
|
||||
return {
|
||||
async read() {
|
||||
return session;
|
||||
},
|
||||
async write(nextSession) {
|
||||
session = nextSession;
|
||||
},
|
||||
async clear() {
|
||||
session = null;
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
function createFailingStorage(): SessionStorage {
|
||||
return {
|
||||
async read() {
|
||||
throw new Error("keychain locked");
|
||||
},
|
||||
async write() {
|
||||
/* noop */
|
||||
},
|
||||
async clear() {
|
||||
/* noop */
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
function createPushPlugin(
|
||||
options: {
|
||||
currentPermission?: "prompt" | "prompt-with-rationale" | "granted" | "denied";
|
||||
requestedPermission?: "prompt" | "prompt-with-rationale" | "granted" | "denied";
|
||||
token?: string;
|
||||
failRegistration?: boolean;
|
||||
} = {}
|
||||
): PushNotificationsBridge & { calls: string[] } {
|
||||
const calls: string[] = [];
|
||||
let registrationListener: ((token: { value: string }) => void) | null = null;
|
||||
let errorListener: ((error: unknown) => void) | null = null;
|
||||
|
||||
return {
|
||||
calls,
|
||||
async checkPermissions() {
|
||||
calls.push("checkPermissions");
|
||||
return { receive: options.currentPermission ?? "granted" };
|
||||
},
|
||||
async requestPermissions() {
|
||||
calls.push("requestPermissions");
|
||||
return { receive: options.requestedPermission ?? "granted" };
|
||||
},
|
||||
async register() {
|
||||
calls.push("register");
|
||||
queueMicrotask(() => {
|
||||
if (options.failRegistration) {
|
||||
errorListener?.(new Error("native registration failed"));
|
||||
return;
|
||||
}
|
||||
registrationListener?.({ value: options.token ?? "native-token-1" });
|
||||
});
|
||||
},
|
||||
async addListener(eventName, listenerFunc) {
|
||||
calls.push(`addListener:${eventName}`);
|
||||
if (eventName === "registration") {
|
||||
registrationListener = listenerFunc as (token: { value: string }) => void;
|
||||
} else {
|
||||
errorListener = listenerFunc as (error: unknown) => void;
|
||||
}
|
||||
return {
|
||||
async remove() {
|
||||
calls.push(`remove:${eventName}`);
|
||||
},
|
||||
};
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
describe("registerPushNotifications", () => {
|
||||
beforeEach(() => {
|
||||
vi.restoreAllMocks();
|
||||
});
|
||||
|
||||
it("keeps apiBaseUrl as a required caller contract", async () => {
|
||||
await expect(registerPushNotifications({ apiBaseUrl: "" })).rejects.toThrow("apiBaseUrl is required");
|
||||
});
|
||||
|
||||
it("skips defensively when running on web", async () => {
|
||||
const pushPlugin = createPushPlugin();
|
||||
const result = await registerPushNotifications({
|
||||
apiBaseUrl: "https://api.example.test",
|
||||
platform: "web",
|
||||
pushPlugin,
|
||||
storage: createMemoryStorage({ token: "bearer-1", userId: "u-1", tenantId: "t-1" }),
|
||||
});
|
||||
|
||||
expect(result).toEqual({ status: "skipped", reason: "web-platform" });
|
||||
expect(pushPlugin.calls).toEqual([]);
|
||||
});
|
||||
|
||||
it("skips when no mobile session is stored", async () => {
|
||||
const pushPlugin = createPushPlugin();
|
||||
const result = await registerPushNotifications({
|
||||
apiBaseUrl: "https://api.example.test",
|
||||
platform: "ios",
|
||||
pushPlugin,
|
||||
storage: createMemoryStorage(null),
|
||||
});
|
||||
|
||||
expect(result).toEqual({ status: "skipped", reason: "no-session" });
|
||||
expect(pushPlugin.calls).toEqual([]);
|
||||
});
|
||||
|
||||
it("skips when the stored session cannot be read", async () => {
|
||||
const pushPlugin = createPushPlugin();
|
||||
const result = await registerPushNotifications({
|
||||
apiBaseUrl: "https://api.example.test",
|
||||
platform: "ios",
|
||||
pushPlugin,
|
||||
storage: createFailingStorage(),
|
||||
});
|
||||
|
||||
expect(result).toEqual({ status: "skipped", reason: "no-session" });
|
||||
expect(pushPlugin.calls).toEqual([]);
|
||||
});
|
||||
|
||||
it("skips unsupported native platforms before touching the push bridge", async () => {
|
||||
const pushPlugin = createPushPlugin();
|
||||
const result = await registerPushNotifications({
|
||||
apiBaseUrl: "https://api.example.test",
|
||||
platform: "electron" as "ios",
|
||||
pushPlugin,
|
||||
storage: createMemoryStorage({ token: "bearer-1", userId: "u-1", tenantId: null }),
|
||||
});
|
||||
|
||||
expect(result).toEqual({ status: "skipped", reason: "unsupported-platform" });
|
||||
expect(pushPlugin.calls).toEqual([]);
|
||||
});
|
||||
|
||||
it("requests permission and skips when the user denies push access", async () => {
|
||||
const pushPlugin = createPushPlugin({ currentPermission: "prompt", requestedPermission: "denied" });
|
||||
const result = await registerPushNotifications({
|
||||
apiBaseUrl: "https://api.example.test",
|
||||
platform: "android",
|
||||
pushPlugin,
|
||||
storage: createMemoryStorage({ token: "bearer-1", userId: "u-1", tenantId: null }),
|
||||
});
|
||||
|
||||
expect(result).toEqual({ status: "skipped", reason: "permission-denied" });
|
||||
expect(pushPlugin.calls).toEqual(["checkPermissions", "requestPermissions"]);
|
||||
});
|
||||
|
||||
it("registers an iOS APNs token through the mobile API client", async () => {
|
||||
const requests: Array<{ url: string; authorization: string | null; body: unknown }> = [];
|
||||
const fakeFetch: typeof fetch = async (input, init) => {
|
||||
requests.push({
|
||||
url: String(input),
|
||||
authorization: new Headers(init?.headers).get("authorization"),
|
||||
body: init?.body ? JSON.parse(String(init.body)) : null,
|
||||
});
|
||||
return new Response(JSON.stringify({ success: true, data: { id: "dt-1" } }), {
|
||||
status: 200,
|
||||
headers: { "content-type": "application/json" },
|
||||
});
|
||||
};
|
||||
|
||||
const pushPlugin = createPushPlugin({ currentPermission: "prompt", requestedPermission: "granted", token: " apns-token-1 " });
|
||||
const result = await registerPushNotifications({
|
||||
apiBaseUrl: "https://api.example.test/",
|
||||
appVersion: "1.2.3",
|
||||
platform: "ios",
|
||||
pushPlugin,
|
||||
storage: createMemoryStorage({ token: "bearer-1", userId: "u-1", tenantId: "t-1" }),
|
||||
fetchImpl: fakeFetch,
|
||||
});
|
||||
|
||||
expect(result).toEqual({ status: "registered", platform: "ios", pushProvider: "apns" });
|
||||
expect(pushPlugin.calls).toEqual([
|
||||
"checkPermissions",
|
||||
"requestPermissions",
|
||||
"addListener:registration",
|
||||
"addListener:registrationError",
|
||||
"register",
|
||||
"remove:registration",
|
||||
"remove:registrationError",
|
||||
]);
|
||||
expect(requests).toEqual([
|
||||
{
|
||||
url: "https://api.example.test/v1/devices/register",
|
||||
authorization: "Bearer bearer-1",
|
||||
body: {
|
||||
token: "apns-token-1",
|
||||
userId: "u-1",
|
||||
tenantId: "t-1",
|
||||
platform: "ios",
|
||||
provider: "apns",
|
||||
pushProvider: "apns",
|
||||
appVersion: "1.2.3",
|
||||
},
|
||||
},
|
||||
]);
|
||||
});
|
||||
|
||||
it("registers Android with the FCM provider", async () => {
|
||||
const bodies: unknown[] = [];
|
||||
const fakeFetch: typeof fetch = async (_input, init) => {
|
||||
bodies.push(init?.body ? JSON.parse(String(init.body)) : null);
|
||||
return new Response(JSON.stringify({ success: true }), {
|
||||
status: 200,
|
||||
headers: { "content-type": "application/json" },
|
||||
});
|
||||
};
|
||||
|
||||
const pushPlugin = createPushPlugin({ token: "fcm-token-1" });
|
||||
const result = await registerPushNotifications({
|
||||
apiBaseUrl: "https://api.example.test",
|
||||
platform: "android",
|
||||
pushPlugin,
|
||||
storage: createMemoryStorage({ token: "bearer-1", userId: "u-1", tenantId: null }),
|
||||
fetchImpl: fakeFetch,
|
||||
});
|
||||
|
||||
expect(result).toEqual({ status: "registered", platform: "android", pushProvider: "fcm" });
|
||||
expect(pushPlugin.calls).not.toContain("requestPermissions");
|
||||
expect(bodies).toEqual([
|
||||
{
|
||||
token: "fcm-token-1",
|
||||
userId: "u-1",
|
||||
tenantId: null,
|
||||
platform: "android",
|
||||
provider: "fcm",
|
||||
pushProvider: "fcm",
|
||||
},
|
||||
]);
|
||||
});
|
||||
|
||||
it("skips when the native registration callback fails", async () => {
|
||||
const result = await registerPushNotifications({
|
||||
apiBaseUrl: "https://api.example.test",
|
||||
platform: "ios",
|
||||
pushPlugin: createPushPlugin({ failRegistration: true }),
|
||||
storage: createMemoryStorage({ token: "bearer-1", userId: "u-1", tenantId: "t-1" }),
|
||||
timeoutMs: 10,
|
||||
});
|
||||
|
||||
expect(result).toEqual({ status: "skipped", reason: "registration-failed" });
|
||||
});
|
||||
|
||||
it("skips when native registration returns an empty token", async () => {
|
||||
const pushPlugin = createPushPlugin({ token: " " });
|
||||
const result = await registerPushNotifications({
|
||||
apiBaseUrl: "https://api.example.test",
|
||||
platform: "ios",
|
||||
pushPlugin,
|
||||
storage: createMemoryStorage({ token: "bearer-1", userId: "u-1", tenantId: "t-1" }),
|
||||
timeoutMs: 10,
|
||||
});
|
||||
|
||||
expect(result).toEqual({ status: "skipped", reason: "registration-failed" });
|
||||
expect(pushPlugin.calls).toEqual([
|
||||
"checkPermissions",
|
||||
"addListener:registration",
|
||||
"addListener:registrationError",
|
||||
"register",
|
||||
"remove:registration",
|
||||
"remove:registrationError",
|
||||
]);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,212 @@
|
||||
import { createMobileApiClient, rehydrateAuth, type MobileSession, type SessionStorage } from "./auth.js";
|
||||
|
||||
type DevicePlatform = "ios" | "android";
|
||||
type PushProvider = "apns" | "fcm";
|
||||
type PermissionState = "prompt" | "prompt-with-rationale" | "granted" | "denied";
|
||||
|
||||
export interface PushRegistrationOptions {
|
||||
apiBaseUrl: string;
|
||||
/** Deprecated direct-token hook kept for old callers; persisted mobile auth is preferred. */
|
||||
bearerToken?: string;
|
||||
/** Optional app version forwarded to the device-token endpoint. */
|
||||
appVersion?: string;
|
||||
/** Override the default auth storage adapter, primarily for tests. */
|
||||
storage?: SessionStorage;
|
||||
/** Custom fetch implementation, primarily for tests or a Capacitor HTTP bridge. */
|
||||
fetchImpl?: typeof fetch;
|
||||
/** Native bridge override, primarily for tests. */
|
||||
pushPlugin?: PushNotificationsBridge;
|
||||
/** Platform override, primarily for tests. */
|
||||
platform?: "ios" | "android" | "web";
|
||||
/** Native registration timeout. Defaults to 15 seconds. */
|
||||
timeoutMs?: number;
|
||||
}
|
||||
|
||||
export type PushRegistrationResult =
|
||||
| { status: "registered"; platform: DevicePlatform; pushProvider: PushProvider }
|
||||
| {
|
||||
status: "skipped";
|
||||
reason:
|
||||
| "capacitor-unavailable"
|
||||
| "web-platform"
|
||||
| "unsupported-platform"
|
||||
| "push-plugin-unavailable"
|
||||
| "no-session"
|
||||
| "permission-denied"
|
||||
| "registration-failed";
|
||||
};
|
||||
|
||||
export interface PushNotificationsBridge {
|
||||
checkPermissions(): Promise<{ receive: PermissionState }>;
|
||||
requestPermissions(): Promise<{ receive: PermissionState }>;
|
||||
register(): Promise<void>;
|
||||
addListener(eventName: "registration", listenerFunc: (token: { value: string }) => void): Promise<PluginListenerHandle>;
|
||||
addListener(eventName: "registrationError", listenerFunc: (error: unknown) => void): Promise<PluginListenerHandle>;
|
||||
}
|
||||
|
||||
interface PluginListenerHandle {
|
||||
remove(): Promise<void>;
|
||||
}
|
||||
|
||||
interface CapacitorRuntime {
|
||||
isNativePlatform?: () => boolean;
|
||||
getPlatform?: () => string;
|
||||
}
|
||||
|
||||
const DEFAULT_TIMEOUT_MS = 15_000;
|
||||
const DEVICE_REGISTER_PATH = "/v1/devices/register";
|
||||
|
||||
export async function registerPushNotifications(options: PushRegistrationOptions): Promise<PushRegistrationResult> {
|
||||
const apiBaseUrl = options.apiBaseUrl.trim();
|
||||
if (!apiBaseUrl) {
|
||||
throw new Error("apiBaseUrl is required to register push notifications.");
|
||||
}
|
||||
|
||||
const session = await readMobileSession(options.storage);
|
||||
if (!session?.token || !session.userId) {
|
||||
return { status: "skipped", reason: "no-session" };
|
||||
}
|
||||
|
||||
const platformResult = options.platform ?? (await readNativePlatform());
|
||||
if (platformResult === null) {
|
||||
return { status: "skipped", reason: "capacitor-unavailable" };
|
||||
}
|
||||
if (platformResult === "web") {
|
||||
return { status: "skipped", reason: "web-platform" };
|
||||
}
|
||||
const platform = normalizeDevicePlatform(platformResult);
|
||||
if (!platform) {
|
||||
return { status: "skipped", reason: "unsupported-platform" };
|
||||
}
|
||||
|
||||
const pushPlugin = options.pushPlugin ?? (await loadPushNotificationsPlugin());
|
||||
if (!pushPlugin) {
|
||||
return { status: "skipped", reason: "push-plugin-unavailable" };
|
||||
}
|
||||
|
||||
const permission = await ensurePushPermission(pushPlugin);
|
||||
if (permission !== "granted") {
|
||||
return { status: "skipped", reason: "permission-denied" };
|
||||
}
|
||||
|
||||
let token: string;
|
||||
try {
|
||||
token = await waitForNativePushToken(pushPlugin, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
|
||||
} catch {
|
||||
return { status: "skipped", reason: "registration-failed" };
|
||||
}
|
||||
|
||||
const pushProvider = providerForPlatform(platform);
|
||||
const client = await createMobileApiClient({
|
||||
baseUrl: apiBaseUrl,
|
||||
storage: options.storage,
|
||||
fetchImpl: options.fetchImpl,
|
||||
});
|
||||
|
||||
await client.request({
|
||||
method: "POST",
|
||||
path: DEVICE_REGISTER_PATH,
|
||||
body: {
|
||||
token,
|
||||
userId: session.userId,
|
||||
tenantId: session.tenantId,
|
||||
platform,
|
||||
provider: pushProvider,
|
||||
pushProvider,
|
||||
appVersion: options.appVersion,
|
||||
},
|
||||
});
|
||||
|
||||
return { status: "registered", platform, pushProvider };
|
||||
}
|
||||
|
||||
async function readMobileSession(storage?: SessionStorage): Promise<MobileSession | null> {
|
||||
try {
|
||||
return storage ? await storage.read() : await rehydrateAuth();
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
async function readNativePlatform(): Promise<string | null> {
|
||||
try {
|
||||
const mod: { Capacitor?: CapacitorRuntime } = await import(/* @vite-ignore */ "@capacitor/core");
|
||||
const capacitor = mod.Capacitor;
|
||||
if (!capacitor) return null;
|
||||
if (typeof capacitor.isNativePlatform === "function" && !capacitor.isNativePlatform()) {
|
||||
return "web";
|
||||
}
|
||||
return typeof capacitor.getPlatform === "function" ? capacitor.getPlatform() : null;
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
async function loadPushNotificationsPlugin(): Promise<PushNotificationsBridge | null> {
|
||||
try {
|
||||
const mod: { PushNotifications?: PushNotificationsBridge } = await import(
|
||||
/* @vite-ignore */ "@capacitor/push-notifications"
|
||||
);
|
||||
return mod.PushNotifications ?? null;
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
function normalizeDevicePlatform(platform: string): DevicePlatform | null {
|
||||
if (platform === "ios" || platform === "android") return platform;
|
||||
return null;
|
||||
}
|
||||
|
||||
function providerForPlatform(platform: DevicePlatform): PushProvider {
|
||||
return platform === "ios" ? "apns" : "fcm";
|
||||
}
|
||||
|
||||
async function ensurePushPermission(pushPlugin: PushNotificationsBridge): Promise<PermissionState> {
|
||||
const current = await pushPlugin.checkPermissions();
|
||||
if (current.receive === "granted") {
|
||||
return current.receive;
|
||||
}
|
||||
const requested = await pushPlugin.requestPermissions();
|
||||
return requested.receive;
|
||||
}
|
||||
|
||||
async function waitForNativePushToken(pushPlugin: PushNotificationsBridge, timeoutMs: number): Promise<string> {
|
||||
const handles: PluginListenerHandle[] = [];
|
||||
let timer: ReturnType<typeof setTimeout> | undefined;
|
||||
let resolveToken: (value: string) => void = () => undefined;
|
||||
let rejectToken: (reason?: unknown) => void = () => undefined;
|
||||
|
||||
const tokenPromise = new Promise<string>((resolve, reject) => {
|
||||
resolveToken = resolve;
|
||||
rejectToken = reject;
|
||||
timer = setTimeout(() => reject(new Error("Push registration timed out.")), timeoutMs);
|
||||
});
|
||||
|
||||
const listenersReady = (async () => {
|
||||
handles.push(
|
||||
await pushPlugin.addListener("registration", (token) => {
|
||||
const value = token.value.trim();
|
||||
if (value) {
|
||||
resolveToken(value);
|
||||
} else {
|
||||
rejectToken(new Error("Push registration returned an empty token."));
|
||||
}
|
||||
}),
|
||||
);
|
||||
handles.push(await pushPlugin.addListener("registrationError", rejectToken));
|
||||
})();
|
||||
|
||||
try {
|
||||
await listenersReady;
|
||||
await pushPlugin.register();
|
||||
return await tokenPromise;
|
||||
} catch (error) {
|
||||
rejectToken(error);
|
||||
void tokenPromise.catch(() => undefined);
|
||||
throw error;
|
||||
} finally {
|
||||
if (timer) clearTimeout(timer);
|
||||
await Promise.all(handles.map((handle) => handle.remove().catch(() => undefined)));
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,94 @@
|
||||
import { describe, it, expect, beforeEach, vi } from "vitest";
|
||||
import { initMobileSentry, __resetMobileSentryForTests } from "./sentry.js";
|
||||
|
||||
beforeEach(() => {
|
||||
__resetMobileSentryForTests();
|
||||
});
|
||||
|
||||
describe("initMobileSentry", () => {
|
||||
it("returns false when no DSN is provided", async () => {
|
||||
const result = await initMobileSentry({ dsn: undefined, release: undefined, environment: undefined });
|
||||
expect(result).toBe(false);
|
||||
});
|
||||
|
||||
it("returns false on the web platform even with a DSN", async () => {
|
||||
const load = vi.fn();
|
||||
const result = await initMobileSentry(
|
||||
{ dsn: "https://abc@sentry.example/1", release: "v1", environment: "prod" },
|
||||
{ load, getPlatform: async () => "web" }
|
||||
);
|
||||
expect(result).toBe(false);
|
||||
expect(load).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
it("returns false when the SDK fails to load", async () => {
|
||||
const result = await initMobileSentry(
|
||||
{ dsn: "https://abc@sentry.example/1", release: "v1", environment: "prod" },
|
||||
{ load: async () => null, getPlatform: async () => "ios" }
|
||||
);
|
||||
expect(result).toBe(false);
|
||||
});
|
||||
|
||||
it("initializes the SDK with the documented config on native platforms", async () => {
|
||||
const init = vi.fn();
|
||||
const setTag = vi.fn();
|
||||
const result = await initMobileSentry(
|
||||
{ dsn: "https://abc@sentry.example/1", release: "1.0.0", environment: "staging", tracesSampleRate: 0.25 },
|
||||
{ load: async () => ({ init, setTag }), getPlatform: async () => "android" }
|
||||
);
|
||||
expect(result).toBe(true);
|
||||
expect(init).toHaveBeenCalledWith(
|
||||
expect.objectContaining({
|
||||
dsn: "https://abc@sentry.example/1",
|
||||
release: "1.0.0",
|
||||
environment: "staging",
|
||||
sendDefaultPii: false,
|
||||
tracesSampleRate: 0.25,
|
||||
})
|
||||
);
|
||||
expect(setTag).toHaveBeenCalledWith("platform", "android");
|
||||
});
|
||||
|
||||
it("falls back to the default 0.1 sample rate when none is provided", async () => {
|
||||
const init = vi.fn();
|
||||
await initMobileSentry(
|
||||
{ dsn: "https://abc@sentry.example/1", release: undefined, environment: undefined },
|
||||
{ load: async () => ({ init, setTag: vi.fn() }), getPlatform: async () => "ios" }
|
||||
);
|
||||
expect(init).toHaveBeenCalledWith(expect.objectContaining({ tracesSampleRate: 0.1 }));
|
||||
});
|
||||
|
||||
it("is idempotent — a second call short-circuits", async () => {
|
||||
const init = vi.fn();
|
||||
const deps = { load: async () => ({ init, setTag: vi.fn() }), getPlatform: async () => "ios" as const };
|
||||
await initMobileSentry({ dsn: "https://abc@sentry.example/1", release: undefined, environment: undefined }, deps);
|
||||
await initMobileSentry({ dsn: "https://abc@sentry.example/1", release: undefined, environment: undefined }, deps);
|
||||
expect(init).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
|
||||
it("clamps a sample rate above 1.0 down to 1.0", async () => {
|
||||
const init = vi.fn();
|
||||
await initMobileSentry(
|
||||
{ dsn: "https://abc@sentry.example/1", release: undefined, environment: undefined, tracesSampleRate: 5 },
|
||||
{ load: async () => ({ init, setTag: vi.fn() }), getPlatform: async () => "ios" }
|
||||
);
|
||||
expect(init).toHaveBeenCalledWith(expect.objectContaining({ tracesSampleRate: 1 }));
|
||||
});
|
||||
|
||||
it("clamps negative and non-finite sample rates to safe values", async () => {
|
||||
const negativeInit = vi.fn();
|
||||
await initMobileSentry(
|
||||
{ dsn: "https://abc@sentry.example/1", release: undefined, environment: undefined, tracesSampleRate: -1 },
|
||||
{ load: async () => ({ init: negativeInit, setTag: vi.fn() }), getPlatform: async () => "ios" }
|
||||
);
|
||||
expect(negativeInit).toHaveBeenCalledWith(expect.objectContaining({ tracesSampleRate: 0 }));
|
||||
|
||||
__resetMobileSentryForTests();
|
||||
const nanInit = vi.fn();
|
||||
await initMobileSentry(
|
||||
{ dsn: "https://abc@sentry.example/1", release: undefined, environment: undefined, tracesSampleRate: Number.NaN },
|
||||
{ load: async () => ({ init: nanInit, setTag: vi.fn() }), getPlatform: async () => "ios" }
|
||||
);
|
||||
expect(nanInit).toHaveBeenCalledWith(expect.objectContaining({ tracesSampleRate: 0.1 }));
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,111 @@
|
||||
/**
|
||||
* Sentry-Capacitor bootstrap for the native shell (Phase 08 #65).
|
||||
*
|
||||
* Mirrors the web client at `apps/web/app/sentry.client.ts`:
|
||||
* - Same DSN catalogue: `VITE_SENTRY_DSN_WEB` is reused so the mobile
|
||||
* wrapper does not need a second Sentry project — events land in
|
||||
* the same dashboard, distinguished by `Capacitor.getPlatform()`
|
||||
* forwarded as a tag.
|
||||
* - `sendDefaultPii: false` matches the web policy.
|
||||
* - Trace + replay sample rates default to the same conservative
|
||||
* 0.1 / 0 / 1.0 split (capacitor SDK does not ship replay; we keep
|
||||
* trace + uncaughtException coverage).
|
||||
*
|
||||
* The integration is loaded dynamically so unit tests under Vitest's
|
||||
* node runner never resolve the native module graph. The exported
|
||||
* `initMobileSentry()` returns true when the SDK was actually
|
||||
* initialized and false in the no-op path (missing DSN or web platform).
|
||||
*
|
||||
* @see apps/web/app/sentry.client.ts for the web sibling
|
||||
* @see docs/improvement-plan/02-observability/sentry-wiring-web.md
|
||||
*/
|
||||
|
||||
export interface MobileSentryConfig {
|
||||
dsn: string | undefined;
|
||||
release: string | undefined;
|
||||
environment: string | undefined;
|
||||
tracesSampleRate?: number;
|
||||
}
|
||||
|
||||
export interface MobileSentryDeps {
|
||||
/** Resolves the Sentry-Capacitor SDK; injectable for tests. */
|
||||
load?: () => Promise<{
|
||||
init: (config: Record<string, unknown>) => void;
|
||||
setTag?: (key: string, value: string) => void;
|
||||
} | null>;
|
||||
/** Returns the runtime platform — `ios` / `android` / `web`. */
|
||||
getPlatform?: () => Promise<"ios" | "android" | "web">;
|
||||
}
|
||||
|
||||
let initialized = false;
|
||||
|
||||
/**
|
||||
* Initializes the Sentry-Capacitor SDK. Idempotent. Returns true when the
|
||||
* SDK was actually wired (i.e. DSN present + native runtime + load
|
||||
* succeeded); false in the no-op fallback. Safe to call from cold start
|
||||
* before the WebView is attached.
|
||||
*/
|
||||
export async function initMobileSentry(config: MobileSentryConfig, deps: MobileSentryDeps = {}): Promise<boolean> {
|
||||
if (initialized) return true;
|
||||
if (!config.dsn) return false;
|
||||
|
||||
const platform = await (deps.getPlatform?.() ?? defaultGetPlatform());
|
||||
if (platform === "web") {
|
||||
// The web bundle is already initialized via apps/web/app/sentry.client.ts;
|
||||
// we never re-init from the native wrapper to avoid double-reporting.
|
||||
return false;
|
||||
}
|
||||
|
||||
const sdk = await (deps.load?.() ?? defaultLoad());
|
||||
if (!sdk) return false;
|
||||
|
||||
sdk.init({
|
||||
dsn: config.dsn,
|
||||
environment: config.environment,
|
||||
release: config.release,
|
||||
sendDefaultPii: false,
|
||||
tracesSampleRate: clampSampleRate(config.tracesSampleRate, 0.1),
|
||||
});
|
||||
sdk.setTag?.("platform", platform);
|
||||
|
||||
initialized = true;
|
||||
return true;
|
||||
}
|
||||
|
||||
/** Test-only: reset the init guard. */
|
||||
export function __resetMobileSentryForTests(): void {
|
||||
initialized = false;
|
||||
}
|
||||
|
||||
function clampSampleRate(value: number | undefined, fallback: number): number {
|
||||
if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
|
||||
if (value < 0) return 0;
|
||||
if (value > 1) return 1;
|
||||
return value;
|
||||
}
|
||||
|
||||
async function defaultLoad(): Promise<MobileSentryDeps["load"] extends () => Promise<infer R> ? R : never> {
|
||||
try {
|
||||
const mod = (await import(/* @vite-ignore */ "@sentry/capacitor")) as {
|
||||
init?: (config: Record<string, unknown>) => void;
|
||||
setTag?: (key: string, value: string) => void;
|
||||
};
|
||||
if (typeof mod.init !== "function") return null as never;
|
||||
return { init: mod.init.bind(mod), setTag: mod.setTag?.bind(mod) } as never;
|
||||
} catch {
|
||||
return null as never;
|
||||
}
|
||||
}
|
||||
|
||||
async function defaultGetPlatform(): Promise<"ios" | "android" | "web"> {
|
||||
try {
|
||||
const core = (await import(/* @vite-ignore */ "@capacitor/core")) as {
|
||||
Capacitor?: { getPlatform?: () => string };
|
||||
};
|
||||
const value = core.Capacitor?.getPlatform?.();
|
||||
if (value === "ios" || value === "android") return value;
|
||||
return "web";
|
||||
} catch {
|
||||
return "web";
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user