Reorganize repo structure and standards references

This commit is contained in:
david committed 2026-06-29 05:03:42 +02:00
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";
}
}