@apex-inc/capacitor-plugin 0.1.0

package/dist/esm/definitions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"definitions.d.ts","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"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"}

package/dist/esm/definitions.js

@@ -0,0 +1,13 @@
+/**
+ * Public TypeScript interface for `@apex-inc/capacitor-plugin`.
+ *
+ * These types define the contract between the JS layer (this package) and
+ * the native iOS (Swift, MMP-004) and Android (Kotlin, MMP-005) implementations.
+ * Shape changes are breaking after 1.0.0.
+ *
+ * Pairs with `apex.js` (the web snippet) when loaded inside a Capacitor
+ * WebView — shared visitor ID, shared session, shared events via one backend.
+ * See `plans/mobile-measurement-platform.md` Phase 1b for scope and rationale.
+ */
+export {};
+//# sourceMappingURL=definitions.js.map

package/dist/esm/definitions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/dist/esm/event-id.d.ts

@@ -0,0 +1,17 @@
+/**
+ * UUIDv4 generator for client-assigned event IDs.
+ *
+ * Used by the Apex Capacitor plugin to stamp every event with an idempotency
+ * key before it hits the network. The server dedupes on this ID within a
+ * 24-hour window — without it, mobile retry storms would double-count installs
+ * and waste client ad budget.
+ *
+ * Prefers `crypto.randomUUID()` when available (modern browsers, Node 14.17+,
+ * Capacitor WebViews on iOS 14+/Android 10+). Falls back to a manual
+ * implementation using `crypto.getRandomValues` for older environments.
+ */
+/** Generates a RFC 4122 v4 UUID. */
+export declare function generateEventId(): string;
+/** Validates a string looks like a UUIDv4. Useful in tests and sanity checks. */
+export declare function isValidEventId(value: string): boolean;
+//# sourceMappingURL=event-id.d.ts.map

package/dist/esm/event-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-id.d.ts","sourceRoot":"","sources":["../../src/event-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,oCAAoC;AACpC,wBAAgB,eAAe,IAAI,MAAM,CAcxC;AAED,iFAAiF;AACjF,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAErD"}

package/dist/esm/event-id.js

@@ -0,0 +1,57 @@
+/**
+ * UUIDv4 generator for client-assigned event IDs.
+ *
+ * Used by the Apex Capacitor plugin to stamp every event with an idempotency
+ * key before it hits the network. The server dedupes on this ID within a
+ * 24-hour window — without it, mobile retry storms would double-count installs
+ * and waste client ad budget.
+ *
+ * Prefers `crypto.randomUUID()` when available (modern browsers, Node 14.17+,
+ * Capacitor WebViews on iOS 14+/Android 10+). Falls back to a manual
+ * implementation using `crypto.getRandomValues` for older environments.
+ */
+/** Generates a RFC 4122 v4 UUID. */
+export function generateEventId() {
+    const g = globalThis;
+    if (g.crypto && typeof g.crypto.randomUUID === "function") {
+        return g.crypto.randomUUID();
+    }
+    if (g.crypto && typeof g.crypto.getRandomValues === "function") {
+        return generateUuidFromRandomBytes(g.crypto);
+    }
+    // Last-resort fallback: Math.random() (not cryptographically secure, but
+    // still satisfies the uniqueness requirement at our scale).
+    return generateUuidFromMath();
+}
+/** Validates a string looks like a UUIDv4. Useful in tests and sanity checks. */
+export function isValidEventId(value) {
+    return /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+}
+function generateUuidFromRandomBytes(crypto) {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    // Set version (4) and variant (RFC 4122) bits.
+    bytes[6] = (bytes[6] & 0x0f) | 0x40;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const hex = [];
+    for (let i = 0; i < bytes.length; i++) {
+        hex.push(bytes[i].toString(16).padStart(2, "0"));
+    }
+    return (hex.slice(0, 4).join("") +
+        "-" +
+        hex.slice(4, 6).join("") +
+        "-" +
+        hex.slice(6, 8).join("") +
+        "-" +
+        hex.slice(8, 10).join("") +
+        "-" +
+        hex.slice(10, 16).join(""));
+}
+function generateUuidFromMath() {
+    return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+        const r = (Math.random() * 16) | 0;
+        const v = c === "x" ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+    });
+}
+//# sourceMappingURL=event-id.js.map

package/dist/esm/event-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-id.js","sourceRoot":"","sources":["../../src/event-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,oCAAoC;AACpC,MAAM,UAAU,eAAe;IAC7B,MAAM,CAAC,GAAG,UAAiC,CAAC;IAE5C,IAAI,CAAC,CAAC,MAAM,IAAI,OAAO,CAAC,CAAC,MAAM,CAAC,UAAU,KAAK,UAAU,EAAE,CAAC;QAC1D,OAAO,CAAC,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC;IAC/B,CAAC;IAED,IAAI,CAAC,CAAC,MAAM,IAAI,OAAO,CAAC,CAAC,MAAM,CAAC,eAAe,KAAK,UAAU,EAAE,CAAC;QAC/D,OAAO,2BAA2B,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IAC/C,CAAC;IAED,yEAAyE;IACzE,4DAA4D;IAC5D,OAAO,oBAAoB,EAAE,CAAC;AAChC,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,OAAO,wEAAwE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAC9F,CAAC;AAED,SAAS,2BAA2B,CAAC,MAAc;IACjD,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,EAAE,CAAC,CAAC;IACjC,MAAM,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;IAC9B,+CAA+C;IAC/C,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;IACpC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;IAEpC,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;IACnD,CAAC;IACD,OAAO,CACL,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;QACxB,GAAG;QACH,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;QACxB,GAAG;QACH,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;QACxB,GAAG;QACH,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;QACzB,GAAG;QACH,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAC3B,CAAC;AACJ,CAAC;AAED,SAAS,oBAAoB;IAC3B,OAAO,sCAAsC,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,EAAE;QACnE,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC;QACnC,MAAM,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC;QAC1C,OAAO,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;IACxB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/esm/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Public entry point for `@apex-inc/capacitor-plugin`.
+ *
+ * Registers the plugin with Capacitor's plugin registry and exports the
+ * proxy. Consumers import like:
+ *
+ * ```ts
+ * import { Apex } from "@apex-inc/capacitor-plugin";
+ *
+ * await Apex.initialize({ projectKey: "prj_..." });
+ * await Apex.track({ type: "app_open" });
+ * ```
+ */
+import type { ApexCapacitorPlugin } from "./definitions";
+/**
+ * Capacitor plugin proxy. In a native app, calls route through the bridge to
+ * the iOS (Swift) or Android (Kotlin) implementation. In a web context
+ * (browser or Capacitor PWA), the web fallback in `./web.ts` takes over.
+ */
+export declare const Apex: ApexCapacitorPlugin;
+export * from "./definitions";
+export { OfflineQueue, InMemoryStorage, IndexedDBStorage } from "./offline-queue";
+export type { OfflineQueueStorage, OfflineQueueOptions, QueuedEvent } from "./offline-queue";
+export { SessionManager } from "./session-manager";
+export type { SessionManagerOptions, SessionSnapshot } from "./session-manager";
+export { BatchSender } from "./batch-sender";
+export type { BatchSenderOptions, FlushResult as BatchFlushResult } from "./batch-sender";
+export { generateEventId, isValidEventId } from "./event-id";
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEzD;;;;GAIG;AACH,eAAO,MAAM,IAAI,EAAE,mBAKlB,CAAC;AAGF,cAAc,eAAe,CAAC;AAG9B,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAClF,YAAY,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC7F,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,YAAY,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAChF,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC7C,YAAY,EAAE,kBAAkB,EAAE,WAAW,IAAI,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAC1F,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}

package/dist/esm/index.js

@@ -0,0 +1,30 @@
+/**
+ * Public entry point for `@apex-inc/capacitor-plugin`.
+ *
+ * Registers the plugin with Capacitor's plugin registry and exports the
+ * proxy. Consumers import like:
+ *
+ * ```ts
+ * import { Apex } from "@apex-inc/capacitor-plugin";
+ *
+ * await Apex.initialize({ projectKey: "prj_..." });
+ * await Apex.track({ type: "app_open" });
+ * ```
+ */
+import { registerPlugin } from "@capacitor/core";
+/**
+ * Capacitor plugin proxy. In a native app, calls route through the bridge to
+ * the iOS (Swift) or Android (Kotlin) implementation. In a web context
+ * (browser or Capacitor PWA), the web fallback in `./web.ts` takes over.
+ */
+export const Apex = registerPlugin("ApexCapacitorPlugin", {
+    web: () => import("./web").then((m) => new m.ApexCapacitorWeb()),
+});
+// Re-export types so consumers can import them cleanly.
+export * from "./definitions";
+// Re-export core modules for advanced/test usage.
+export { OfflineQueue, InMemoryStorage, IndexedDBStorage } from "./offline-queue";
+export { SessionManager } from "./session-manager";
+export { BatchSender } from "./batch-sender";
+export { generateEventId, isValidEventId } from "./event-id";
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAGjD;;;;GAIG;AACH,MAAM,CAAC,MAAM,IAAI,GAAwB,cAAc,CACrD,qBAAqB,EACrB;IACE,GAAG,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,gBAAgB,EAAE,CAAC;CACjE,CACF,CAAC;AAEF,wDAAwD;AACxD,cAAc,eAAe,CAAC;AAE9B,kDAAkD;AAClD,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAElF,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7C,OAAO,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}

package/dist/esm/offline-queue.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Offline event queue with durable storage and FIFO eviction.
+ *
+ * Every event tracked through the plugin gets enqueued here first. A batch
+ * sender drains the queue in the background (`batch-sender.ts`). When the
+ * user is offline (flights, subways, dead zones), events accumulate safely
+ * up to `maxSize`; the oldest events are dropped rather than crashing the
+ * app or silently failing.
+ *
+ * Pluggable `Storage` interface supports three implementations:
+ *   - `InMemoryStorage` — used in tests and as the default for SSR/Node
+ *   - `IndexedDBStorage` — used in browser + Capacitor WebView contexts
+ *   - `NativeBridgeStorage` — used when Capacitor native plugin is active
+ *     (persists through the native OfflineQueue on iOS Core Data / Android Room)
+ *
+ * This keeps the queue logic pure (no DOM/Native API dependencies in the
+ * algorithmic core), which makes testing trivial.
+ */
+import type { ApexEvent } from "./definitions";
+/** A single queued event ready for delivery to the server. */
+export interface QueuedEvent {
+    event: ApexEvent;
+    /** Attempt count so the batch sender can apply exponential backoff. */
+    attempts: number;
+    /** ISO timestamp when enqueued. Used for queue-age metrics + eviction. */
+    enqueuedAt: string;
+}
+/**
+ * Storage backend for the offline queue. Implementations persist events
+ * across app restarts and may be synchronous (in-memory) or asynchronous
+ * (IndexedDB, native bridge).
+ */
+export interface OfflineQueueStorage {
+    /** Read all queued events in insertion order. */
+    readAll(): Promise<QueuedEvent[]>;
+    /** Append one event to the queue. */
+    append(event: QueuedEvent): Promise<void>;
+    /** Replace the entire queue contents (used for flush + eviction). */
+    replaceAll(events: QueuedEvent[]): Promise<void>;
+    /** Remove all events matching the given event IDs. */
+    removeByIds(eventIds: string[]): Promise<void>;
+    /** Number of events currently persisted. */
+    size(): Promise<number>;
+    /** Best-effort clear — used on test mode toggle + uninstall cleanup. */
+    clear(): Promise<void>;
+}
+/** Options for {@link OfflineQueue}. */
+export interface OfflineQueueOptions {
+    storage: OfflineQueueStorage;
+    /** Maximum events to hold before FIFO eviction. Default 1000. */
+    maxSize?: number;
+    /** Called when an event is evicted due to queue overflow. */
+    onEvicted?: (event: QueuedEvent) => void;
+}
+export declare class OfflineQueue {
+    private readonly storage;
+    private readonly maxSize;
+    private readonly onEvicted?;
+    constructor(options: OfflineQueueOptions);
+    /**
+     * Enqueue an event. If the queue is at `maxSize`, the oldest event is
+     * evicted first (FIFO) so the new event can be recorded.
+     */
+    enqueue(event: ApexEvent): Promise<void>;
+    /** Enqueue many events in a single storage write. */
+    enqueueMany(events: ApexEvent[]): Promise<void>;
+    /** Read the next batch of events without removing them from the queue. */
+    peek(batchSize: number): Promise<QueuedEvent[]>;
+    /** Mark events as successfully delivered and remove them from the queue. */
+    markSent(eventIds: string[]): Promise<void>;
+    /** Increment attempt count for events that failed to send (for backoff). */
+    markFailed(eventIds: string[]): Promise<void>;
+    /** Current queue size. */
+    size(): Promise<number>;
+    /** ISO timestamp of the oldest queued event, or null if queue is empty. */
+    oldestEventAt(): Promise<string | null>;
+    /** Empty the queue. Typically called when toggling test mode. */
+    clear(): Promise<void>;
+}
+/**
+ * In-memory storage. Used in tests and as a fallback where neither IndexedDB
+ * nor the native bridge is available (e.g. SSR contexts).
+ */
+export declare class InMemoryStorage implements OfflineQueueStorage {
+    private events;
+    readAll(): Promise<QueuedEvent[]>;
+    append(event: QueuedEvent): Promise<void>;
+    replaceAll(events: QueuedEvent[]): Promise<void>;
+    removeByIds(eventIds: string[]): Promise<void>;
+    size(): Promise<number>;
+    clear(): Promise<void>;
+}
+/**
+ * IndexedDB-backed storage for browser + Capacitor WebView contexts.
+ * Persists events across app restarts using a single object store keyed by
+ * event ID.
+ */
+export declare class IndexedDBStorage implements OfflineQueueStorage {
+    private readonly dbName;
+    private readonly storeName;
+    private dbPromise?;
+    constructor(dbName?: string, storeName?: string);
+    private openDb;
+    readAll(): Promise<QueuedEvent[]>;
+    append(event: QueuedEvent): Promise<void>;
+    replaceAll(events: QueuedEvent[]): Promise<void>;
+    removeByIds(eventIds: string[]): Promise<void>;
+    size(): Promise<number>;
+    clear(): Promise<void>;
+}
+//# sourceMappingURL=offline-queue.d.ts.map

package/dist/esm/offline-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"offline-queue.d.ts","sourceRoot":"","sources":["../../src/offline-queue.ts"],"names":[],"mappings":"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"}

package/dist/esm/offline-queue.js

@@ -0,0 +1,240 @@
+/**
+ * Offline event queue with durable storage and FIFO eviction.
+ *
+ * Every event tracked through the plugin gets enqueued here first. A batch
+ * sender drains the queue in the background (`batch-sender.ts`). When the
+ * user is offline (flights, subways, dead zones), events accumulate safely
+ * up to `maxSize`; the oldest events are dropped rather than crashing the
+ * app or silently failing.
+ *
+ * Pluggable `Storage` interface supports three implementations:
+ *   - `InMemoryStorage` — used in tests and as the default for SSR/Node
+ *   - `IndexedDBStorage` — used in browser + Capacitor WebView contexts
+ *   - `NativeBridgeStorage` — used when Capacitor native plugin is active
+ *     (persists through the native OfflineQueue on iOS Core Data / Android Room)
+ *
+ * This keeps the queue logic pure (no DOM/Native API dependencies in the
+ * algorithmic core), which makes testing trivial.
+ */
+export class OfflineQueue {
+    constructor(options) {
+        this.storage = options.storage;
+        this.maxSize = options.maxSize ?? 1000;
+        this.onEvicted = options.onEvicted;
+        if (this.maxSize < 1) {
+            throw new Error(`OfflineQueue maxSize must be >= 1, got ${this.maxSize}`);
+        }
+    }
+    /**
+     * Enqueue an event. If the queue is at `maxSize`, the oldest event is
+     * evicted first (FIFO) so the new event can be recorded.
+     */
+    async enqueue(event) {
+        if (!event.id) {
+            throw new Error("OfflineQueue.enqueue: event.id is required (set via event-id.generateEventId)");
+        }
+        const existing = await this.storage.readAll();
+        const queued = {
+            event,
+            attempts: 0,
+            enqueuedAt: new Date().toISOString(),
+        };
+        const next = [...existing, queued];
+        if (next.length > this.maxSize) {
+            const overflow = next.splice(0, next.length - this.maxSize);
+            if (this.onEvicted) {
+                for (const ev of overflow) {
+                    this.onEvicted(ev);
+                }
+            }
+        }
+        await this.storage.replaceAll(next);
+    }
+    /** Enqueue many events in a single storage write. */
+    async enqueueMany(events) {
+        if (events.length === 0)
+            return;
+        const existing = await this.storage.readAll();
+        const now = new Date().toISOString();
+        const queued = events.map((event) => {
+            if (!event.id) {
+                throw new Error("OfflineQueue.enqueueMany: every event must have an id");
+            }
+            return { event, attempts: 0, enqueuedAt: now };
+        });
+        const next = [...existing, ...queued];
+        if (next.length > this.maxSize) {
+            const overflow = next.splice(0, next.length - this.maxSize);
+            if (this.onEvicted) {
+                for (const ev of overflow) {
+                    this.onEvicted(ev);
+                }
+            }
+        }
+        await this.storage.replaceAll(next);
+    }
+    /** Read the next batch of events without removing them from the queue. */
+    async peek(batchSize) {
+        if (batchSize < 1)
+            return [];
+        const all = await this.storage.readAll();
+        return all.slice(0, batchSize);
+    }
+    /** Mark events as successfully delivered and remove them from the queue. */
+    async markSent(eventIds) {
+        if (eventIds.length === 0)
+            return;
+        await this.storage.removeByIds(eventIds);
+    }
+    /** Increment attempt count for events that failed to send (for backoff). */
+    async markFailed(eventIds) {
+        if (eventIds.length === 0)
+            return;
+        const idSet = new Set(eventIds);
+        const all = await this.storage.readAll();
+        const next = all.map((q) => q.event.id && idSet.has(q.event.id) ? { ...q, attempts: q.attempts + 1 } : q);
+        await this.storage.replaceAll(next);
+    }
+    /** Current queue size. */
+    async size() {
+        return this.storage.size();
+    }
+    /** ISO timestamp of the oldest queued event, or null if queue is empty. */
+    async oldestEventAt() {
+        const all = await this.storage.readAll();
+        return all.length > 0 ? all[0].enqueuedAt : null;
+    }
+    /** Empty the queue. Typically called when toggling test mode. */
+    async clear() {
+        await this.storage.clear();
+    }
+}
+// ── Storage implementations ────────────────────────────────────────────────
+/**
+ * In-memory storage. Used in tests and as a fallback where neither IndexedDB
+ * nor the native bridge is available (e.g. SSR contexts).
+ */
+export class InMemoryStorage {
+    constructor() {
+        this.events = [];
+    }
+    async readAll() {
+        return [...this.events];
+    }
+    async append(event) {
+        this.events.push(event);
+    }
+    async replaceAll(events) {
+        this.events = [...events];
+    }
+    async removeByIds(eventIds) {
+        const idSet = new Set(eventIds);
+        this.events = this.events.filter((q) => !q.event.id || !idSet.has(q.event.id));
+    }
+    async size() {
+        return this.events.length;
+    }
+    async clear() {
+        this.events = [];
+    }
+}
+/**
+ * IndexedDB-backed storage for browser + Capacitor WebView contexts.
+ * Persists events across app restarts using a single object store keyed by
+ * event ID.
+ */
+export class IndexedDBStorage {
+    constructor(dbName = "apex-capacitor-queue", storeName = "events") {
+        this.dbName = dbName;
+        this.storeName = storeName;
+    }
+    async openDb() {
+        if (this.dbPromise)
+            return this.dbPromise;
+        const db = await new Promise((resolve, reject) => {
+            const idb = globalThis.indexedDB;
+            if (!idb) {
+                reject(new Error("IndexedDB not available in this environment"));
+                return;
+            }
+            const req = idb.open(this.dbName, 1);
+            req.onupgradeneeded = () => {
+                const database = req.result;
+                if (!database.objectStoreNames.contains(this.storeName)) {
+                    database.createObjectStore(this.storeName, { keyPath: "key", autoIncrement: true });
+                }
+            };
+            req.onsuccess = () => resolve(req.result);
+            req.onerror = () => reject(req.error);
+        });
+        this.dbPromise = Promise.resolve(db);
+        return db;
+    }
+    async readAll() {
+        const db = await this.openDb();
+        return new Promise((resolve, reject) => {
+            const tx = db.transaction(this.storeName, "readonly");
+            const store = tx.objectStore(this.storeName);
+            const req = store.getAll();
+            req.onsuccess = () => {
+                const rows = req.result ?? [];
+                // Strip internal autoIncrement key for caller.
+                resolve(rows
+                    .sort((a, b) => (a.key ?? 0) - (b.key ?? 0))
+                    .map(({ key: _k, ...rest }) => rest));
+            };
+            req.onerror = () => reject(req.error);
+        });
+    }
+    async append(event) {
+        const db = await this.openDb();
+        await new Promise((resolve, reject) => {
+            const tx = db.transaction(this.storeName, "readwrite");
+            const store = tx.objectStore(this.storeName);
+            store.add(event);
+            tx.oncomplete = () => resolve();
+            tx.onerror = () => reject(tx.error);
+        });
+    }
+    async replaceAll(events) {
+        const db = await this.openDb();
+        await new Promise((resolve, reject) => {
+            const tx = db.transaction(this.storeName, "readwrite");
+            const store = tx.objectStore(this.storeName);
+            store.clear();
+            for (const ev of events) {
+                store.add(ev);
+            }
+            tx.oncomplete = () => resolve();
+            tx.onerror = () => reject(tx.error);
+        });
+    }
+    async removeByIds(eventIds) {
+        if (eventIds.length === 0)
+            return;
+        const idSet = new Set(eventIds);
+        const all = await this.readAll();
+        const kept = all.filter((q) => !q.event.id || !idSet.has(q.event.id));
+        await this.replaceAll(kept);
+    }
+    async size() {
+        const db = await this.openDb();
+        return new Promise((resolve, reject) => {
+            const tx = db.transaction(this.storeName, "readonly");
+            const store = tx.objectStore(this.storeName);
+            const req = store.count();
+            req.onsuccess = () => resolve(req.result ?? 0);
+            req.onerror = () => reject(req.error);
+        });
+    }
+    async clear() {
+        const db = await this.openDb();
+        await new Promise((resolve, reject) => {
+            const tx = db.transaction(this.storeName, "readwrite");
+            tx.objectStore(this.storeName).clear();
+            tx.oncomplete = () => resolve();
+            tx.onerror = () => reject(tx.error);
+        });
+    }
+}
+//# sourceMappingURL=offline-queue.js.map

package/dist/esm/offline-queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"offline-queue.js","sourceRoot":"","sources":["../../src/offline-queue.ts"],"names":[],"mappings":"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"}

package/dist/esm/session-manager.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Mobile session manager.
+ *
+ * Defines the boundaries of a user's interaction with the app. A session
+ * starts on the first event after inactivity and ends when either
+ *   (a) no events arrive for `timeoutMinutes` (default 30), or
+ *   (b) the app is force-backgrounded and the OS reclaims memory.
+ *
+ * Emits `session_start` and `session_end` events that plug directly into the
+ * server's MSESSION# rollup (Phase 1c). The timeout is configurable and the
+ * clock is injectable for deterministic testing.
+ */
+export interface SessionSnapshot {
+    sessionId: string;
+    startedAt: string;
+    lastActivityAt: string;
+    eventCount: number;
+    endedAt?: string;
+    durationSeconds?: number;
+}
+export interface SessionManagerOptions {
+    /** Inactivity window after which a session ends. Default 30 minutes. */
+    timeoutMinutes?: number;
+    /** Called when a new session starts (emits `session_start` server-side). */
+    onSessionStart?: (session: SessionSnapshot) => void;
+    /** Called when a session ends (emits `session_end` server-side). */
+    onSessionEnd?: (session: SessionSnapshot) => void;
+    /** Injectable clock for deterministic testing. Defaults to `Date.now()`. */
+    now?: () => number;
+    /** Injectable `setTimeout` / `clearTimeout` for deterministic testing. */
+    scheduler?: {
+        setTimeout: (callback: () => void, ms: number) => number;
+        clearTimeout: (handle: number) => void;
+    };
+}
+export declare class SessionManager {
+    private readonly timeoutMs;
+    private readonly onSessionStart?;
+    private readonly onSessionEnd?;
+    private readonly now;
+    private readonly setTimeoutFn;
+    private readonly clearTimeoutFn;
+    private current;
+    private timeoutHandle;
+    constructor(options?: SessionManagerOptions);
+    /**
+     * Records user activity. Starts a new session if none is active, otherwise
+     * resets the inactivity timeout. Returns the current session snapshot.
+     */
+    recordActivity(): SessionSnapshot;
+    /**
+     * Explicitly ends the current session immediately. Fires `onSessionEnd`.
+     * No-op if no session is active.
+     */
+    endSession(): void;
+    /** Returns the current session snapshot, or null. */
+    getCurrent(): SessionSnapshot | null;
+    /** Force-starts a new session, ending any current one. */
+    forceStart(): SessionSnapshot;
+    private scheduleTimeout;
+    private clearTimeout;
+}
+//# sourceMappingURL=session-manager.d.ts.map

package/dist/esm/session-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-manager.d.ts","sourceRoot":"","sources":["../../src/session-manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,qBAAqB;IACpC,wEAAwE;IACxE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,4EAA4E;IAC5E,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,IAAI,CAAC;IACpD,oEAAoE;IACpE,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,IAAI,CAAC;IAClD,4EAA4E;IAC5E,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,0EAA0E;IAC1E,SAAS,CAAC,EAAE;QACV,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC;QACzD,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;KACxC,CAAC;CACH;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAqC;IACrE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAqC;IACnE,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAyC;IACtE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA2B;IAC1D,OAAO,CAAC,OAAO,CAAgC;IAC/C,OAAO,CAAC,aAAa,CAAuB;gBAEhC,OAAO,GAAE,qBAA0B;IAgB/C;;;OAGG;IACH,cAAc,IAAI,eAAe;IAwBjC;;;OAGG;IACH,UAAU,IAAI,IAAI;IAkBlB,qDAAqD;IACrD,UAAU,IAAI,eAAe,GAAG,IAAI;IAIpC,0DAA0D;IAC1D,UAAU,IAAI,eAAe;IAK7B,OAAO,CAAC,eAAe;IAOvB,OAAO,CAAC,YAAY;CAMrB"}