@apex-inc/capacitor-plugin 0.1.0

package/dist/definitions.d.ts

@@ -0,0 +1,224 @@
+/**
+ * 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.
+ */
+import type { PluginListenerHandle } from "@capacitor/core";
+/** iOS App Tracking Transparency authorization status. */
+export type AttStatus = "authorized" | "denied" | "restricted" | "not-determined";
+/** Supported tracking platforms. */
+export type ApexPlatform = "ios" | "android" | "web";
+/** Fallback source when the primary advertising identifier is unavailable. */
+export type AdvertisingIdFallback = "idfv" | "android_id" | null;
+/** Coarse SKAN 4.0 conversion value. */
+export type SkanCoarseValue = "low" | "medium" | "high";
+/**
+ * Cross-platform tracking event mirroring the server `TrackingEvent` shape.
+ * The plugin batches and sends these to `/api/events` via {@link ApexCapacitorPlugin.track}.
+ */
+export interface ApexEvent {
+    /** Event type — matches server `TrackingEventType`. */
+    type: string;
+    /** Client-generated UUIDv4. Auto-filled by `track()` if omitted. */
+    id?: string;
+    /** Session ID — auto-managed by session manager when omitted. */
+    sessionId?: string;
+    /** ISO timestamp of when the event occurred (client clock). Auto-filled if omitted. */
+    timestamp?: string;
+    /** URL or deep-link path associated with the event (default: current route). */
+    url?: string;
+    utmSource?: string;
+    utmMedium?: string;
+    utmCampaign?: string;
+    experimentId?: string;
+    variant?: string;
+    /** Typed payload for in-app purchases. */
+    purchase?: {
+        productId: string;
+        amount: number;
+        currency: string;
+        transactionId: string;
+        receiptData?: string;
+        isRestored?: boolean;
+    };
+    /** Typed payload for subscription lifecycle. */
+    subscription?: {
+        productId: string;
+        action: "started" | "renewed" | "cancelled" | "expired" | "grace_period" | "paused" | "resumed" | "trial_started" | "trial_converted" | "trial_expired";
+        amount?: number;
+        currency?: string;
+        periodType?: "monthly" | "yearly" | "weekly" | "custom";
+        transactionId?: string;
+        expiresAt?: string;
+        isTrial?: boolean;
+    };
+    /** Unstructured additional context. */
+    data?: Record<string, unknown>;
+}
+/** Options for {@link ApexCapacitorPlugin.initialize}. */
+export interface InitializeOptions {
+    /** Project key from the Apex dashboard. Required. */
+    projectKey: string;
+    /** API base URL. Defaults to `https://api.apex.inc`. */
+    apiUrl?: string;
+    /** Tag subsequent events as test mode (excluded from production analytics). */
+    testMode?: boolean;
+    /** Session timeout in minutes. Default 30. */
+    sessionTimeoutMinutes?: number;
+    /** Maximum queued events before FIFO eviction kicks in. Default 1000. */
+    offlineQueueMaxSize?: number;
+    /** Enable verbose console logging. Default false. */
+    debug?: boolean;
+}
+/** Return value of {@link ApexCapacitorPlugin.getAdvertisingId}. */
+export interface AdvertisingIdResult {
+    /** The advertising identifier, or null when completely unavailable. */
+    id: string | null;
+    /** When `id` is null/zero, indicates which fallback is in use. */
+    fallback: AdvertisingIdFallback;
+}
+/** Device metadata returned by {@link ApexCapacitorPlugin.getDeviceInfo}. */
+export interface DeviceInfo {
+    platform: "ios" | "android";
+    osVersion: string;
+    model: string;
+    appVersion: string;
+    bundleId: string;
+    timezone: string;
+    locale: string;
+}
+/** Summary of offline-queue state. */
+export interface QueueStatus {
+    /** Number of events currently pending send. */
+    count: number;
+    /** ISO timestamp of the oldest queued event, or null if queue is empty. */
+    oldestEventAt: string | null;
+}
+/** Outcome of {@link ApexCapacitorPlugin.flushQueue}. */
+export interface FlushResult {
+    /** Events successfully sent during this flush. */
+    flushed: number;
+    /** Events that remain in the queue (failed + not attempted). */
+    remaining: number;
+}
+/** Current session summary. */
+export interface SessionInfo {
+    sessionId: string | null;
+    startedAt: string | null;
+}
+/**
+ * The primary plugin contract. Matches Phase 1b API surface locked in
+ * `plans/mobile-measurement-platform.md`.
+ */
+export interface ApexCapacitorPlugin {
+    /**
+     * Initializes the plugin. Must be called once before any other method.
+     * Registers push notification handlers, seeds the offline queue from native
+     * storage, and starts the session manager.
+     */
+    initialize(options: InitializeOptions): Promise<void>;
+    /**
+     * Requests ATT permission on iOS (presents the system prompt once per
+     * install). No-op on Android — returns `"authorized"`.
+     */
+    requestTrackingAuthorization(): Promise<{
+        status: AttStatus;
+    }>;
+    /**
+     * Returns the current ATT status without prompting. Android always returns
+     * `"authorized"`.
+     */
+    getTrackingStatus(): Promise<{
+        status: AttStatus;
+    }>;
+    /**
+     * Returns IDFA (iOS) or GAID (Android). When unavailable (ATT denied or LAT
+     * enabled), returns a fallback with `fallback` indicating which identifier
+     * was substituted.
+     */
+    getAdvertisingId(): Promise<AdvertisingIdResult>;
+    /**
+     * Android: returns decoded Play Install Referrer string on first launch.
+     * iOS: returns `{ referrer: null }` (no equivalent).
+     */
+    getInstallReferrer(): Promise<{
+        referrer: string | null;
+    }>;
+    /** Gets the plugin-managed visitor ID. */
+    getVisitorId(): Promise<{
+        visitorId: string;
+    }>;
+    /** Overrides the visitor ID (e.g. after login). Persists to native storage. */
+    setVisitorId(options: {
+        visitorId: string;
+    }): Promise<void>;
+    /**
+     * Updates the SKAdNetwork 4.0 postback conversion value. No-op on Android.
+     * `fineValue` is 0-63 (fine conversion value); `coarseValue` is optional
+     * for SKAN 4.0's coarse-grained reporting.
+     */
+    updateConversionValue(options: {
+        fineValue: number;
+        coarseValue?: SkanCoarseValue;
+    }): Promise<void>;
+    /**
+     * Returns the URL the app was opened with on cold start (Universal Link on
+     * iOS, App Link on Android). Returns `{ url: null }` if launched without a
+     * link. Use the `deepLink` listener for subsequent warm-start links.
+     */
+    getInitialDeepLink(): Promise<{
+        url: string | null;
+    }>;
+    getDeviceInfo(): Promise<DeviceInfo>;
+    /** Force-starts a new session, ending any current one. */
+    startSession(): Promise<{
+        sessionId: string;
+    }>;
+    /** Ends the current session immediately. */
+    endSession(): Promise<void>;
+    /** Returns info about the current session, or null fields if none. */
+    getCurrentSession(): Promise<SessionInfo>;
+    /**
+     * Enqueues an event for delivery. If network is available, events are
+     * batched and sent within ~1s; otherwise they persist in the offline queue
+     * until `flushQueue()` succeeds.
+     */
+    track(event: ApexEvent): Promise<void>;
+    /** Current offline queue status (event count + oldest timestamp). */
+    getQueueSize(): Promise<QueueStatus>;
+    /** Attempts to send all queued events. Returns counts of flushed + remaining. */
+    flushQueue(): Promise<FlushResult>;
+    /**
+     * Toggles test mode at runtime. Test-mode events are tagged so the server
+     * routes them to the TESTEVT# store, excluded from production analytics.
+     */
+    setTestMode(options: {
+        enabled: boolean;
+    }): Promise<void>;
+    /** Fires when a deep link opens the app while it is already running. */
+    addListener(eventName: "deepLink", listenerFunc: (event: {
+        url: string;
+    }) => void): Promise<PluginListenerHandle>;
+    /** Fires when the app moves between foreground and background. */
+    addListener(eventName: "appStateChange", listenerFunc: (event: {
+        isActive: boolean;
+    }) => void): Promise<PluginListenerHandle>;
+    /** Fires when a new session starts. */
+    addListener(eventName: "sessionStart", listenerFunc: (event: {
+        sessionId: string;
+    }) => void): Promise<PluginListenerHandle>;
+    /** Fires when the current session ends. */
+    addListener(eventName: "sessionEnd", listenerFunc: (event: {
+        sessionId: string;
+        durationSeconds: number;
+    }) => void): Promise<PluginListenerHandle>;
+    /** Removes all listeners registered by this plugin instance. */
+    removeAllListeners(): Promise<void>;
+}
+//# sourceMappingURL=definitions.d.ts.map

package/dist/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/definitions.js

@@ -0,0 +1,14 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=definitions.js.map

package/dist/definitions.js.map

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

package/dist/esm/batch-sender.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Batch sender with exponential-backoff retries.
+ *
+ * Drains the offline queue by sending events in batches to `/api/events`.
+ * Retries on 5xx and network errors with exponential backoff (1s, 2s, 4s).
+ * Gives up after 3 attempts per batch — events remain in the queue for a
+ * future flush attempt but are marked with incremented `attempts` so old
+ * failing events don't block new ones indefinitely.
+ *
+ * The fetch function is injectable for testing and to allow future runtimes
+ * to swap in native HTTP clients (e.g. on restricted networks).
+ */
+import type { OfflineQueue } from "./offline-queue";
+export interface BatchSenderOptions {
+    /** API base URL. Default `https://api.apex.inc`. */
+    apiUrl?: string;
+    /** Project key attached to each request. Required. */
+    projectKey: string;
+    /** Max events sent per batch. Default 50. */
+    batchSize?: number;
+    /** Max retry attempts before giving up on a batch. Default 3. */
+    maxRetries?: number;
+    /** Base backoff delay in milliseconds. Default 1000. */
+    baseBackoffMs?: number;
+    /** Injectable fetch (Node, test mocks, custom runtimes). */
+    fetchFn?: typeof fetch;
+    /** Injectable sleep for testing (must return a Promise that resolves). */
+    sleepFn?: (ms: number) => Promise<void>;
+    /** Platform header to include (`ios` / `android`). */
+    platformHeader?: "ios" | "android" | "web";
+    /** Enable verbose logs. */
+    debug?: boolean;
+}
+export interface FlushResult {
+    flushed: number;
+    remaining: number;
+    attemptedBatches: number;
+    lastError?: string;
+}
+export declare class BatchSender {
+    private readonly apiUrl;
+    private readonly projectKey;
+    private readonly batchSize;
+    private readonly maxRetries;
+    private readonly baseBackoffMs;
+    private readonly fetchFn;
+    private readonly sleepFn;
+    private readonly platformHeader?;
+    private readonly debug;
+    constructor(options: BatchSenderOptions);
+    /**
+     * Flushes as many events from the queue as possible, one batch at a time,
+     * with exponential backoff on retryable failures. Stops early on
+     * non-retryable errors (400/401/403) and leaves remaining events queued.
+     */
+    flush(queue: OfflineQueue): Promise<FlushResult>;
+    private sendBatchWithRetry;
+    private postBatch;
+}
+//# sourceMappingURL=batch-sender.d.ts.map

package/dist/esm/batch-sender.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch-sender.d.ts","sourceRoot":"","sources":["../../src/batch-sender.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAe,MAAM,iBAAiB,CAAC;AAEjE,MAAM,WAAW,kBAAkB;IACjC,oDAAoD;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wDAAwD;IACxD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,4DAA4D;IAC5D,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;IACvB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,sDAAsD;IACtD,cAAc,CAAC,EAAE,KAAK,GAAG,SAAS,GAAG,KAAK,CAAC;IAC3C,2BAA2B;IAC3B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgC;IACxD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAA4B;IAC5D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAU;gBAEpB,OAAO,EAAE,kBAAkB;IAiBvC;;;;OAIG;IACG,KAAK,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;YAgCxC,kBAAkB;YAyClB,SAAS;CAoBxB"}

package/dist/esm/batch-sender.js

@@ -0,0 +1,111 @@
+/**
+ * Batch sender with exponential-backoff retries.
+ *
+ * Drains the offline queue by sending events in batches to `/api/events`.
+ * Retries on 5xx and network errors with exponential backoff (1s, 2s, 4s).
+ * Gives up after 3 attempts per batch — events remain in the queue for a
+ * future flush attempt but are marked with incremented `attempts` so old
+ * failing events don't block new ones indefinitely.
+ *
+ * The fetch function is injectable for testing and to allow future runtimes
+ * to swap in native HTTP clients (e.g. on restricted networks).
+ */
+export class BatchSender {
+    constructor(options) {
+        this.apiUrl = (options.apiUrl ?? "https://api.apex.inc").replace(/\/+$/, "");
+        this.projectKey = options.projectKey;
+        this.batchSize = options.batchSize ?? 50;
+        this.maxRetries = options.maxRetries ?? 3;
+        this.baseBackoffMs = options.baseBackoffMs ?? 1000;
+        this.fetchFn = options.fetchFn ?? globalThis.fetch?.bind(globalThis);
+        this.sleepFn =
+            options.sleepFn ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+        this.platformHeader = options.platformHeader;
+        this.debug = options.debug ?? false;
+        if (!this.fetchFn) {
+            throw new Error("BatchSender: fetch is not available. Provide options.fetchFn.");
+        }
+    }
+    /**
+     * Flushes as many events from the queue as possible, one batch at a time,
+     * with exponential backoff on retryable failures. Stops early on
+     * non-retryable errors (400/401/403) and leaves remaining events queued.
+     */
+    async flush(queue) {
+        let flushed = 0;
+        let attemptedBatches = 0;
+        let lastError;
+        while (true) {
+            const batch = await queue.peek(this.batchSize);
+            if (batch.length === 0)
+                break;
+            attemptedBatches += 1;
+            const outcome = await this.sendBatchWithRetry(batch);
+            if (outcome.status === "success") {
+                const eventIds = batch.map((q) => q.event.id).filter((id) => !!id);
+                await queue.markSent(eventIds);
+                flushed += batch.length;
+            }
+            else if (outcome.status === "retryable_exhausted") {
+                const eventIds = batch.map((q) => q.event.id).filter((id) => !!id);
+                await queue.markFailed(eventIds);
+                lastError = outcome.error;
+                break; // leave for next flush cycle
+            }
+            else {
+                // Non-retryable: leave events in place but stop flushing.
+                lastError = outcome.error;
+                break;
+            }
+        }
+        const remaining = await queue.size();
+        return { flushed, remaining, attemptedBatches, lastError };
+    }
+    async sendBatchWithRetry(batch) {
+        let lastError = "unknown";
+        for (let attempt = 0; attempt < this.maxRetries; attempt++) {
+            try {
+                const response = await this.postBatch(batch);
+                if (response.ok) {
+                    return { status: "success" };
+                }
+                // Non-retryable client errors — leave events, surface to caller.
+                if (response.status >= 400 && response.status < 500) {
+                    return { status: "non_retryable", error: `HTTP ${response.status}` };
+                }
+                // Retryable: 5xx or unknown. Fall through to backoff.
+                lastError = `HTTP ${response.status}`;
+            }
+            catch (err) {
+                lastError = err instanceof Error ? err.message : String(err);
+            }
+            if (attempt < this.maxRetries - 1) {
+                const backoff = this.baseBackoffMs * 2 ** attempt;
+                if (this.debug) {
+                    console.log(`[apex-capacitor] batch-sender retry ${attempt + 1}/${this.maxRetries - 1} in ${backoff}ms (${lastError})`);
+                }
+                await this.sleepFn(backoff);
+            }
+        }
+        return { status: "retryable_exhausted", error: lastError };
+    }
+    async postBatch(batch) {
+        const body = {
+            projectKey: this.projectKey,
+            events: batch.map((q) => q.event),
+        };
+        const headers = {
+            "Content-Type": "application/json",
+            "X-Apex-Project-Key": this.projectKey,
+        };
+        if (this.platformHeader) {
+            headers["X-Apex-Platform"] = this.platformHeader;
+        }
+        return this.fetchFn(`${this.apiUrl}/api/events`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+        });
+    }
+}
+//# sourceMappingURL=batch-sender.js.map

package/dist/esm/batch-sender.js.map

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

package/dist/esm/definitions.d.ts

@@ -0,0 +1,224 @@
+/**
+ * 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.
+ */
+import type { PluginListenerHandle } from "@capacitor/core";
+/** iOS App Tracking Transparency authorization status. */
+export type AttStatus = "authorized" | "denied" | "restricted" | "not-determined";
+/** Supported tracking platforms. */
+export type ApexPlatform = "ios" | "android" | "web";
+/** Fallback source when the primary advertising identifier is unavailable. */
+export type AdvertisingIdFallback = "idfv" | "android_id" | null;
+/** Coarse SKAN 4.0 conversion value. */
+export type SkanCoarseValue = "low" | "medium" | "high";
+/**
+ * Cross-platform tracking event mirroring the server `TrackingEvent` shape.
+ * The plugin batches and sends these to `/api/events` via {@link ApexCapacitorPlugin.track}.
+ */
+export interface ApexEvent {
+    /** Event type — matches server `TrackingEventType`. */
+    type: string;
+    /** Client-generated UUIDv4. Auto-filled by `track()` if omitted. */
+    id?: string;
+    /** Session ID — auto-managed by session manager when omitted. */
+    sessionId?: string;
+    /** ISO timestamp of when the event occurred (client clock). Auto-filled if omitted. */
+    timestamp?: string;
+    /** URL or deep-link path associated with the event (default: current route). */
+    url?: string;
+    utmSource?: string;
+    utmMedium?: string;
+    utmCampaign?: string;
+    experimentId?: string;
+    variant?: string;
+    /** Typed payload for in-app purchases. */
+    purchase?: {
+        productId: string;
+        amount: number;
+        currency: string;
+        transactionId: string;
+        receiptData?: string;
+        isRestored?: boolean;
+    };
+    /** Typed payload for subscription lifecycle. */
+    subscription?: {
+        productId: string;
+        action: "started" | "renewed" | "cancelled" | "expired" | "grace_period" | "paused" | "resumed" | "trial_started" | "trial_converted" | "trial_expired";
+        amount?: number;
+        currency?: string;
+        periodType?: "monthly" | "yearly" | "weekly" | "custom";
+        transactionId?: string;
+        expiresAt?: string;
+        isTrial?: boolean;
+    };
+    /** Unstructured additional context. */
+    data?: Record<string, unknown>;
+}
+/** Options for {@link ApexCapacitorPlugin.initialize}. */
+export interface InitializeOptions {
+    /** Project key from the Apex dashboard. Required. */
+    projectKey: string;
+    /** API base URL. Defaults to `https://api.apex.inc`. */
+    apiUrl?: string;
+    /** Tag subsequent events as test mode (excluded from production analytics). */
+    testMode?: boolean;
+    /** Session timeout in minutes. Default 30. */
+    sessionTimeoutMinutes?: number;
+    /** Maximum queued events before FIFO eviction kicks in. Default 1000. */
+    offlineQueueMaxSize?: number;
+    /** Enable verbose console logging. Default false. */
+    debug?: boolean;
+}
+/** Return value of {@link ApexCapacitorPlugin.getAdvertisingId}. */
+export interface AdvertisingIdResult {
+    /** The advertising identifier, or null when completely unavailable. */
+    id: string | null;
+    /** When `id` is null/zero, indicates which fallback is in use. */
+    fallback: AdvertisingIdFallback;
+}
+/** Device metadata returned by {@link ApexCapacitorPlugin.getDeviceInfo}. */
+export interface DeviceInfo {
+    platform: "ios" | "android";
+    osVersion: string;
+    model: string;
+    appVersion: string;
+    bundleId: string;
+    timezone: string;
+    locale: string;
+}
+/** Summary of offline-queue state. */
+export interface QueueStatus {
+    /** Number of events currently pending send. */
+    count: number;
+    /** ISO timestamp of the oldest queued event, or null if queue is empty. */
+    oldestEventAt: string | null;
+}
+/** Outcome of {@link ApexCapacitorPlugin.flushQueue}. */
+export interface FlushResult {
+    /** Events successfully sent during this flush. */
+    flushed: number;
+    /** Events that remain in the queue (failed + not attempted). */
+    remaining: number;
+}
+/** Current session summary. */
+export interface SessionInfo {
+    sessionId: string | null;
+    startedAt: string | null;
+}
+/**
+ * The primary plugin contract. Matches Phase 1b API surface locked in
+ * `plans/mobile-measurement-platform.md`.
+ */
+export interface ApexCapacitorPlugin {
+    /**
+     * Initializes the plugin. Must be called once before any other method.
+     * Registers push notification handlers, seeds the offline queue from native
+     * storage, and starts the session manager.
+     */
+    initialize(options: InitializeOptions): Promise<void>;
+    /**
+     * Requests ATT permission on iOS (presents the system prompt once per
+     * install). No-op on Android — returns `"authorized"`.
+     */
+    requestTrackingAuthorization(): Promise<{
+        status: AttStatus;
+    }>;
+    /**
+     * Returns the current ATT status without prompting. Android always returns
+     * `"authorized"`.
+     */
+    getTrackingStatus(): Promise<{
+        status: AttStatus;
+    }>;
+    /**
+     * Returns IDFA (iOS) or GAID (Android). When unavailable (ATT denied or LAT
+     * enabled), returns a fallback with `fallback` indicating which identifier
+     * was substituted.
+     */
+    getAdvertisingId(): Promise<AdvertisingIdResult>;
+    /**
+     * Android: returns decoded Play Install Referrer string on first launch.
+     * iOS: returns `{ referrer: null }` (no equivalent).
+     */
+    getInstallReferrer(): Promise<{
+        referrer: string | null;
+    }>;
+    /** Gets the plugin-managed visitor ID. */
+    getVisitorId(): Promise<{
+        visitorId: string;
+    }>;
+    /** Overrides the visitor ID (e.g. after login). Persists to native storage. */
+    setVisitorId(options: {
+        visitorId: string;
+    }): Promise<void>;
+    /**
+     * Updates the SKAdNetwork 4.0 postback conversion value. No-op on Android.
+     * `fineValue` is 0-63 (fine conversion value); `coarseValue` is optional
+     * for SKAN 4.0's coarse-grained reporting.
+     */
+    updateConversionValue(options: {
+        fineValue: number;
+        coarseValue?: SkanCoarseValue;
+    }): Promise<void>;
+    /**
+     * Returns the URL the app was opened with on cold start (Universal Link on
+     * iOS, App Link on Android). Returns `{ url: null }` if launched without a
+     * link. Use the `deepLink` listener for subsequent warm-start links.
+     */
+    getInitialDeepLink(): Promise<{
+        url: string | null;
+    }>;
+    getDeviceInfo(): Promise<DeviceInfo>;
+    /** Force-starts a new session, ending any current one. */
+    startSession(): Promise<{
+        sessionId: string;
+    }>;
+    /** Ends the current session immediately. */
+    endSession(): Promise<void>;
+    /** Returns info about the current session, or null fields if none. */
+    getCurrentSession(): Promise<SessionInfo>;
+    /**
+     * Enqueues an event for delivery. If network is available, events are
+     * batched and sent within ~1s; otherwise they persist in the offline queue
+     * until `flushQueue()` succeeds.
+     */
+    track(event: ApexEvent): Promise<void>;
+    /** Current offline queue status (event count + oldest timestamp). */
+    getQueueSize(): Promise<QueueStatus>;
+    /** Attempts to send all queued events. Returns counts of flushed + remaining. */
+    flushQueue(): Promise<FlushResult>;
+    /**
+     * Toggles test mode at runtime. Test-mode events are tagged so the server
+     * routes them to the TESTEVT# store, excluded from production analytics.
+     */
+    setTestMode(options: {
+        enabled: boolean;
+    }): Promise<void>;
+    /** Fires when a deep link opens the app while it is already running. */
+    addListener(eventName: "deepLink", listenerFunc: (event: {
+        url: string;
+    }) => void): Promise<PluginListenerHandle>;
+    /** Fires when the app moves between foreground and background. */
+    addListener(eventName: "appStateChange", listenerFunc: (event: {
+        isActive: boolean;
+    }) => void): Promise<PluginListenerHandle>;
+    /** Fires when a new session starts. */
+    addListener(eventName: "sessionStart", listenerFunc: (event: {
+        sessionId: string;
+    }) => void): Promise<PluginListenerHandle>;
+    /** Fires when the current session ends. */
+    addListener(eventName: "sessionEnd", listenerFunc: (event: {
+        sessionId: string;
+        durationSeconds: number;
+    }) => void): Promise<PluginListenerHandle>;
+    /** Removes all listeners registered by this plugin instance. */
+    removeAllListeners(): Promise<void>;
+}
+//# sourceMappingURL=definitions.d.ts.map