@virex-tech/paywallo-sdk 1.5.3 → 2.0.0

package/dist/index.d.mts

@@ -118,6 +118,13 @@ interface CampaignResponse {
     campaignId: string;
     placement: string;
     variantKey: string;
+    /**
+     * UUID estável de `paywall_variants` (sub-fase 2.14). Server sempre
+     * envia; SDK usa pra popular `variant_id` em eventos `$paywall_*`.
+     * Opcional no tipo pra retrocompat com mock responses / SDK 1.x que
+     * possam não ter esse campo — consumer code deve tratar como string.
+     */
+    variantId?: string;
     paywall: {
         id: string;
         placement: string;
@@ -137,6 +144,8 @@ interface CampaignResult {
     restored: boolean;
     campaignId?: string;
     variantKey?: string;
+    /** UUID de `paywall_variants` (sub-fase 2.14). */
+    variantId?: string;
     error?: Error;
     skippedReason?: "subscriber";
 }
@@ -192,7 +201,14 @@ declare class PaywalloError extends Error {
 
 declare class PurchaseError extends PaywalloError {
     readonly userCancelled: boolean;
-    constructor(code: string, message: string, userCancelled?: boolean);
+    /**
+     * Populated when this error stems from an HTTP response (e.g. server
+     * validation rejected the receipt). Lets callers distinguish a permanent
+     * 4xx (drop + finishTransaction) from a transport-level failure that
+     * should be retried via the offline queue.
+     */
+    readonly httpStatus?: number;
+    constructor(code: string, message: string, userCancelled?: boolean, httpStatus?: number);
 }
 declare const PURCHASE_ERROR_CODES: {
     readonly NOT_INITIALIZED: "PURCHASE_NOT_INITIALIZED";
@@ -302,6 +318,13 @@ interface IdentifyOptions {
 interface TrackEventOptions {
     properties?: UserProperties;
     timestamp?: number;
+    /**
+     * Flush priority. `"critical"` flushes the event as a batch-of-1 on the
+     * next microtask (use for install/identify/transaction/subscription/refund
+     * events). `"normal"` (default) batches on a 25-event / 10-second rolling
+     * window.
+     */
+    priority?: "critical" | "normal";
 }
 interface FlagVariant {
     variant: string | null;
@@ -332,8 +355,10 @@ interface PaywallModalProps {
     preloadedProducts?: Map<string, Product>;
     variantKey?: string;
     campaignId?: string;
+    /** UUID de `paywall_variants` (sub-fase 2.14). */
+    variantId?: string;
 }
-declare function PaywallModal({ placement, visible, onResult, paywallConfig: preloadedConfig, preloadedProducts, variantKey, campaignId, }: PaywallModalProps): React__default.ReactElement | null;
+declare function PaywallModal({ placement, visible, onResult, paywallConfig: preloadedConfig, preloadedProducts, variantKey, campaignId, variantId, }: PaywallModalProps): React__default.ReactElement | null;
 
 interface PaywallContextValue {
     nodes: Record<string, PaywallNode>;
@@ -420,6 +445,11 @@ interface HttpClientConfig {
     timeout: number;
     retry: RetryConfig;
     debug: boolean;
+    /**
+     * Headers injected into every outgoing request (e.g. `x-sdk-version`,
+     * `x-sdk-platform`). Per-request headers take precedence on conflict.
+     */
+    globalHeaders: Record<string, string>;
 }
 interface RequestOptions {
     method: "GET" | "POST" | "PUT" | "DELETE";
@@ -438,6 +468,12 @@ interface HttpResponse<T = unknown> {
 declare class HttpClient {
     private config;
     constructor(baseUrl: string, config?: Partial<Omit<HttpClientConfig, "baseUrl">>);
+    /**
+     * Merge additional headers into every subsequent request. Call sites
+     * (e.g. `ApiClient`) use this to update `x-sdk-environment` when the
+     * environment flips from Sandbox to Production at runtime.
+     */
+    setGlobalHeaders(headers: Record<string, string>): void;
     get<T>(path: string, options?: Partial<RequestOptions>): Promise<HttpResponse<T>>;
     post<T>(path: string, body?: unknown, options?: Partial<RequestOptions>): Promise<HttpResponse<T>>;
     request<T>(path: string, options: RequestOptions): Promise<HttpResponse<T>>;
@@ -457,6 +493,54 @@ declare class HttpClient {
     getConfig(): Readonly<HttpClientConfig>;
 }
 
+/**
+ * Shared context resolved once per batch and hoisted out of every individual
+ * event in the V2 ingest envelope. The provider is called at flush time so
+ * each field reflects the most recent SDK state.
+ *
+ * The shape mirrors the server-side `/api/v2/ingest/batch` contract (Phase
+ * 3.1). Fields declared here are deduplicated across the batch — they exist
+ * once on the envelope instead of `N` times on each `events[]` entry.
+ */
+interface EventContext {
+    distinct_id?: string;
+    session_id?: string;
+    device_id?: string;
+    app_version?: string;
+    sdk_version?: string;
+    platform?: string;
+    os_version?: string;
+    device_model?: string;
+    timezone?: string;
+    locale?: string;
+    attribution?: Record<string, unknown>;
+    ids?: Record<string, unknown>;
+}
+
+/**
+ * Event priority controls flush semantics:
+ *
+ * - `"critical"` → flushed as a batch-of-1 on the next microtask (via
+ *   `queueMicrotask`). Used for events where loss is unacceptable:
+ *   `transaction`, `identify`, `lifecycle {type: "install"}`,
+ *   `subscription_*`, `refund`, `checkout_started`.
+ * - `"normal"` → buffered and flushed on a rolling window (whichever fires
+ *   first): `BATCH_MAX_SIZE` events OR `BATCH_FLUSH_MS`. Used for events
+ *   where batching amortizes network cost: `paywall`, non-install
+ *   `lifecycle` (foreground/background/session), `onboarding`,
+ *   `notification`, `custom`.
+ *
+ * Both priorities post to `/api/v2/ingest/batch` (Phase 3.1 envelope) with
+ * automatic fallback to `/api/v1/events/batch` when the V2 endpoint is
+ * absent (old server) or rejects the request. `OfflineQueue` handles
+ * network-failure durability for both queues via the `PostFn` injected by
+ * `ApiClient.postWithQueue`.
+ */
+type EventPriority = "critical" | "normal";
+interface TrackOptions {
+    priority?: EventPriority;
+}
+
 declare class ApiClient {
     private baseUrl;
     private webUrl;
@@ -467,7 +551,17 @@ declare class ApiClient {
     private httpClient;
     private readonly cache;
     private readonly batcher;
+    private eventContextProvider;
+    private onError;
     constructor(appKey: string, apiUrl: string, debug?: boolean, environment?: Environment, offlineQueueEnabled?: boolean, timeout?: number);
+    /**
+     * Inject a context provider so the EventBatcher can hoist global fields
+     * (sdk/platform/version/locale/attribution/ids) out of each event into
+     * the V2 envelope. Allows PaywalloClient to wire in identity/session
+     * state lazily without the batcher depending on those singletons.
+     */
+    setEventContextProvider(provider: () => EventContext | null): void;
+    private resolveEventContext;
     getHttpClient(): HttpClient;
     getBaseUrl(): string;
     getWebUrl(): string;
@@ -476,22 +570,22 @@ declare class ApiClient {
     getQueueSize(): number;
     setofflineQueueEnabled(enabled: boolean): void;
     isofflineQueueEnabled(): boolean;
+    setOnError(callback: ((error: unknown) => void) | null): void;
     setEnvironment(environment: Environment): void;
     setDebug(debug: boolean): void;
+    /**
+     * Build the baseline SDK telemetry headers that every outgoing request
+     * should carry. Keep this tiny — it runs once per ApiClient instance.
+     */
+    private buildSdkHeaders;
     clearQueue(): Promise<void>;
     get<T>(path: string): Promise<HttpResponse<T>>;
     post<T>(path: string, body: unknown, skipRetry?: boolean): Promise<HttpResponse<T>>;
     reportError(errorType: string, message: string, context?: Record<string, unknown>): Promise<void>;
-    trackEvent(eventName: string, distinctId: string, properties?: UserProperties, timestamp?: number): Promise<void>;
+    trackEvent(eventName: string, distinctId: string, properties?: UserProperties, timestamp?: number, options?: TrackOptions): Promise<void>;
     flushEventBatch(): Promise<void>;
     dispose(): void;
     identify(distinctId: string, properties?: UserProperties, email?: string, deviceId?: string): Promise<void>;
-    startSession(distinctId: string, sessionId: string, platform?: string, appVersion?: string, deviceModel?: string, osVersion?: string): Promise<{
-        success: boolean;
-    }>;
-    endSession(sessionId: string, durationSeconds: number): Promise<{
-        success: boolean;
-    }>;
     getVariant(flagKey: string, distinctId: string): Promise<FlagVariant>;
     getPaywall(placement: string): Promise<PaywallConfig | null>;
     getEmergencyPaywall(): Promise<EmergencyPaywallResponse>;
@@ -502,14 +596,64 @@ declare class ApiClient {
     evaluateFlags(keys: string[], distinctId: string): Promise<Record<string, string | null>>;
     getConditionalFlag(flagKey: string, context: ConditionalFlagContext): Promise<ConditionalFlagResult>;
     getVariantFromCache(flagKey: string, distinctId: string): Promise<FlagVariant | null>;
-    private postWithQueue;
-    private log;
+    private flagDeps;
+}
+
+/**
+ * Event payload emitted by the native module whenever StoreKit 2
+ * (`Transaction.updates`) or Google Play Billing (`onPurchasesUpdated` +
+ * refund diff) detects a renewal, refund, or cancellation.
+ */
+interface NativeTransactionUpdate {
+    type: "renewed" | "refunded" | "canceled";
+    transactionId: string;
+    productId: string;
+    amount?: number;
+    currency?: string;
+}
+type TransactionUpdateListener = (update: NativeTransactionUpdate) => void;
+interface TransactionUpdateSubscription {
+    remove(): void;
+}
+declare function isAvailable(): boolean;
+declare const nativeStoreKit: {
+    isAvailable: typeof isAvailable;
+    getProducts(productIds: string[]): Promise<Product[]>;
+    purchase(productId: string): Promise<Purchase | null>;
+    finishTransaction(transactionId: string): Promise<void>;
+    getActiveTransactions(): Promise<Purchase[]>;
+    /**
+     * Subscribes to native transaction update events (renewals, refunds,
+     * cancellations) from StoreKit 2 (`Transaction.updates`) on iOS or
+     * `PurchasesUpdatedListener` + refund diff on Android.
+     *
+     * Returns a subscription with a `remove()` method. The caller is
+     * responsible for cleanup (typically on `Paywallo.reset()`).
+     *
+     * Returns `null` when the native module isn't available (non-mobile env,
+     * native module not linked) — callers should treat null as a no-op.
+     */
+    subscribeToTransactionUpdates(listener: TransactionUpdateListener): TransactionUpdateSubscription | null;
+};
+
+interface ValidateOptions {
+    paywallPlacement?: string;
+    variantKey?: string;
+    paywallId?: string;
+    variantId?: string;
 }
 
 declare class IAPService {
     private productsCache;
     private apiClient;
     private purchaseInFlight;
+    /**
+     * Idempotency guard against double-finish. Populated with transaction IDs
+     * that have already been forwarded to `NativeStoreKit.finishTransaction`.
+     */
+    private finishedTransactions;
+    private validator;
+    private emitter;
     constructor(apiClient?: ApiClient);
     private get debug();
     private getDeviceCountry;
@@ -518,26 +662,16 @@ declare class IAPService {
     loadProducts(productIds: string[]): Promise<Product[]>;
     getProduct(productId: string): Product | undefined;
     getCachedProducts(): Map<string, Product>;
-    private validateWithRetry;
-    private validateWithServer;
     private finishTransaction;
-    purchase(productId: string, options?: {
-        paywallPlacement?: string;
-        variantKey?: string;
-    }): Promise<PurchaseResult>;
+    startTransactionListener(): void;
+    stopTransactionListener(): void;
+    emitTransactionUpdate(update: NativeTransactionUpdate): Promise<void>;
+    purchase(productId: string, options?: ValidateOptions): Promise<PurchaseResult>;
     restore(): Promise<Purchase[]>;
+    reset(): void;
 }
 declare function getIAPService(): IAPService;
 
-declare function isAvailable(): boolean;
-declare const nativeStoreKit: {
-    isAvailable: typeof isAvailable;
-    getProducts(productIds: string[]): Promise<Product[]>;
-    purchase(productId: string): Promise<Purchase | null>;
-    finishTransaction(transactionId: string): Promise<void>;
-    getActiveTransactions(): Promise<Purchase[]>;
-};
-
 type PurchaseState = "idle" | "purchasing" | "restoring" | "error";
 interface IAPProduct {
     productId: string;
@@ -594,6 +728,7 @@ declare class IdentityManager {
     private debug;
     private initialized;
     private initPromise;
+    private distinctId;
     initialize(apiClient: ApiClient, debug?: boolean): Promise<string>;
     private _doInitialize;
     identify(options?: IdentifyOptions | UserProperties): Promise<void>;
@@ -610,6 +745,16 @@ declare class IdentityManager {
 }
 declare const identityManager: IdentityManager;
 
+/**
+ * Guard usado pelo SessionManager.startSession() — aguarda distinctId ficar
+ * disponível antes de criar a sessão. Raiz dos 55% users com total_sessions=0
+ * era session.startSession rodando em paralelo com identity.initialize() e
+ * batendo em distinctId vazio. Agora sessão só inicia depois da identity
+ * estar pronta; este guard é uma defesa extra caso alguém chame startSession
+ * manualmente antes do init terminar.
+ */
+type DistinctIdProvider = () => string;
+
 declare class IdentityError extends PaywalloError {
     constructor(code: string, message: string);
 }
@@ -663,6 +808,231 @@ declare class NetworkMonitorClass {
 }
 declare const networkMonitor: NetworkMonitorClass;
 
+declare class SecureStorage {
+    constructor(_debug?: boolean);
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<boolean>;
+    remove(key: string): Promise<boolean>;
+    hasKeychainSupport(): boolean;
+    private getFromKeychain;
+    private setToKeychain;
+    private removeFromKeychain;
+}
+
+type PushPlatform = "ios" | "android" | "web";
+type PushPermissionStatus = "granted" | "denied" | "provisional" | "notDetermined";
+/**
+ * Canonical push event types — MUST match server `PushEventType` enum 1:1
+ * (see paywallo-server/src/domain/notifications/types/index.ts).
+ * Server Zod (`pushNotificationEventSchema`) rejects anything outside this set.
+ */
+type NotificationEventType = "notification_sent" | "notification_delivered" | "notification_displayed" | "notification_clicked" | "notification_dismissed" | "notification_failed" | "notification_converted";
+/**
+ * Payload sent to `POST /api/v2/push-tokens`. Server schema matches 1:1:
+ * `{ token, platform, distinct_id, app_version, sdk_version }`.
+ *
+ * Optional client-side extras (deviceId/locale/timezone) are kept for context
+ * but the server-critical fields are the five snake_case keys.
+ */
+interface DeviceTokenRegistration {
+    token: string;
+    platform: PushPlatform;
+    distinct_id: string;
+    app_version: string;
+    sdk_version: string;
+    deviceId?: string;
+    locale?: string;
+    timezone?: string;
+}
+interface NotificationPayload {
+    notificationId: string;
+    campaignId: string;
+    variantKey?: string;
+    title: string;
+    body: string;
+    imageUrl?: string;
+    deepLink?: string;
+    data?: Record<string, unknown>;
+}
+type NotificationListener = (event: {
+    type: NotificationEventType;
+    notification: NotificationPayload;
+    messageId: string;
+}) => void;
+
+interface FcmRemoteMessage {
+    messageId?: string;
+    data?: Record<string, string>;
+    notification?: {
+        title?: string;
+        body?: string;
+    };
+    sentTime?: number;
+}
+/**
+ * Minimal interface satisfied by NativePushBridge (and any custom bridge).
+ * Use this type instead of concrete classes to keep code bridge-agnostic.
+ */
+interface IPushBridge {
+    getToken(): Promise<string | null>;
+    getAPNSToken(): Promise<string | null>;
+    requestPermission(options?: {
+        provisional?: boolean;
+    }): Promise<number>;
+    hasPermission(): Promise<number>;
+    onTokenRefresh(cb: (token: string) => void): () => void;
+    onMessage(cb: (message: FcmRemoteMessage) => Promise<void>): () => void;
+    setBackgroundMessageHandler(cb: (message: FcmRemoteMessage) => Promise<void>): void;
+    getInitialNotification(): Promise<FcmRemoteMessage | null>;
+}
+
+/**
+ * Minimal surface the facade needs from the SDK's unified event pipeline.
+ * `PaywalloClient` implements it (forwarding to `ApiClient.trackEvent`
+ * which ends up in the `EventBatcher`).
+ */
+interface EventBatcherLike {
+    trackEvent(eventName: string, distinctId: string, properties?: Record<string, unknown>, timestamp?: number): Promise<void>;
+    getDistinctId(): string;
+}
+
+interface PrePromptOptions {
+    title: string;
+    body: string;
+    acceptLabel?: string;
+    rejectLabel?: string;
+    provisional?: boolean;
+}
+interface PrePromptHandle {
+    title: string;
+    body: string;
+    acceptLabel?: string;
+    rejectLabel?: string;
+    /** Consumer invokes after user taps accept in custom UI. */
+    accept(): Promise<PushPermissionStatus>;
+    /** Consumer invokes after user taps reject in custom UI. */
+    reject(): PushPermissionStatus;
+}
+interface RNPlatform {
+    OS: string;
+    Version?: number | string;
+}
+
+type NotificationsEnvironment = "sandbox" | "production";
+interface NotificationsConfig {
+    debug?: boolean;
+    environment?: NotificationsEnvironment;
+    apiBaseUrl?: string;
+}
+
+interface HandlersConfig {
+    eventBatcher: EventBatcherLike;
+}
+interface NotificationsManagerConfig {
+    appKey: string;
+    apiBaseUrl?: string;
+    debug?: boolean;
+    environment?: NotificationsConfig["environment"];
+}
+interface NotificationsManagerDeps {
+    httpClient?: HttpClient;
+    secureStorage?: SecureStorage;
+    /** Generic bridge — takes precedence over fcmBridge if both are provided. */
+    bridge?: IPushBridge;
+    /** Kept for backwards compatibility — use bridge instead. */
+    fcmBridge?: IPushBridge;
+    getDeviceId?: () => string | null;
+    getDistinctId?: () => string;
+    platform?: RNPlatform;
+}
+declare class NotificationsManager {
+    private isInitialized;
+    private permissionStatus;
+    private currentToken;
+    private debug;
+    private httpClient;
+    private secureStorage;
+    private bridge;
+    private getDeviceId;
+    private getDistinctId;
+    private appKey;
+    private apiBaseUrl;
+    private tokenRefreshCleanup;
+    private foregroundCleanup;
+    private pendingHandlersConfig;
+    private tracker;
+    private permissionManager;
+    private receivedCallbacks;
+    private openedCallbacks;
+    private dismissedCallbacks;
+    constructor(deps?: NotificationsManagerDeps);
+    injectDeps(deps: {
+        httpClient: HttpClient;
+        secureStorage: SecureStorage;
+        getDeviceId: () => string | null;
+        getDistinctId?: () => string;
+    }): void;
+    initialize(config: NotificationsManagerConfig): Promise<void>;
+    private applyConfig;
+    private refreshPermissionStatus;
+    private tokenDeps;
+    private doRegisterToken;
+    private subscribeTokenRefresh;
+    /** Deletes token on server + locally (explicit user opt-out). */
+    optOut(): Promise<void>;
+    /** Clears token locally without server call (used on sign-out/reset). */
+    invalidateLocalToken(): Promise<void>;
+    getPermissionStatus(): Promise<PushPermissionStatus>;
+    requestPermission(options?: {
+        provisional?: boolean;
+    }): Promise<PushPermissionStatus>;
+    /** Requests OS permission and, on success, captures + registers the push token. */
+    requestPushPermission(options?: {
+        provisional?: boolean;
+    }): Promise<PushPermissionStatus>;
+    private captureAndRegisterToken;
+    requestPermissionWithPrePrompt(opts: PrePromptOptions): PrePromptHandle;
+    isReady(): boolean;
+    markInitialized(): void;
+    getCurrentToken(): string | null;
+    setupHandlers(config: HandlersConfig): void;
+    onReceived(cb: (payload: NotificationPayload) => void): void;
+    onOpened(cb: (payload: NotificationPayload) => void): void;
+    onDismissed(cb: (payload: NotificationPayload) => void): void;
+    getInitialNotification(): Promise<NotificationPayload | null>;
+    flushEvents(): Promise<void>;
+    registerBackgroundHandler(cb: (message: FcmRemoteMessage) => Promise<void>): void;
+    destroy(): void;
+}
+
+declare const notificationsManager: NotificationsManager;
+
+declare class NativePushBridge implements IPushBridge {
+    getToken(): Promise<string | null>;
+    getAPNSToken(): Promise<string | null>;
+    requestPermission(options?: {
+        provisional?: boolean;
+    }): Promise<number>;
+    hasPermission(): Promise<number>;
+    onTokenRefresh(cb: (token: string) => void): () => void;
+    onMessage(cb: (message: FcmRemoteMessage) => Promise<void>): () => void;
+    setBackgroundMessageHandler(_cb: (message: FcmRemoteMessage) => Promise<void>): void;
+    getInitialNotification(): Promise<FcmRemoteMessage | null>;
+}
+
+declare const NOTIFICATIONS_ERROR_CODES: {
+    readonly TOKEN_UNAVAILABLE: "TOKEN_UNAVAILABLE";
+    readonly PERMISSION_DENIED: "PERMISSION_DENIED";
+    readonly REGISTRATION_FAILED: "REGISTRATION_FAILED";
+    readonly NOT_INITIALIZED: "NOT_INITIALIZED";
+    readonly ABORTED: "ABORTED";
+};
+type NotificationsErrorCode = (typeof NOTIFICATIONS_ERROR_CODES)[keyof typeof NOTIFICATIONS_ERROR_CODES];
+declare class NotificationsError extends PaywalloError {
+    readonly details?: unknown;
+    constructor(code: NotificationsErrorCode, message: string, details?: unknown);
+}
+
 interface SessionState {
     sessionId: string | null;
     startedAt: Date | null;
@@ -688,7 +1058,8 @@ declare class SessionManager {
     private emergencyPaywallHandler;
     private emergencyPaywallShownInSession;
     private secureStorage;
-    initialize(apiClient: ApiClient, config?: SessionConfig, debug?: boolean): Promise<void>;
+    private distinctIdProvider;
+    initialize(apiClient: ApiClient, config?: SessionConfig, debug?: boolean, distinctIdProvider?: DistinctIdProvider | null): Promise<void>;
     startSession(): Promise<string>;
     endSession(): Promise<void>;
     getSessionId(): string | null;
@@ -697,11 +1068,13 @@ declare class SessionManager {
     getState(): SessionState;
     destroy(): void;
     registerEmergencyPaywallHandler(handler: EmergencyPaywallHandler | null): void;
+    private readSessionKey;
     private restoreSession;
     private setupAppStateListener;
     private handleAppStateChange;
     private handleForeground;
     private handleBackground;
+    private flushEventsWithTimeout;
     private checkEmergencyPaywall;
     private trackSessionStart;
     private trackSessionEnd;
@@ -741,6 +1114,8 @@ interface PaywalloInitConfig extends PaywalloConfig {
     sessionFlags?: string[];
     subscriptionCacheTTL?: number;
     autoPreloadCampaign?: string;
+    /** Called when the SDK silently swallows an API error. Useful for logging/monitoring in production. */
+    onError?: (error: unknown) => void;
 }
 interface IPaywalloClient {
     init(config: PaywalloInitConfig): Promise<void>;
@@ -767,6 +1142,9 @@ interface IPaywalloClient {
     getPreloadedCampaign(placement: string): CampaignResponse | null;
     reset(): Promise<void>;
     fullReset(): Promise<void>;
+    requestPushPermission(options?: {
+        provisional?: boolean;
+    }): Promise<PushPermissionStatus>;
     getConfig(): PaywalloConfig | null;
     getDistinctId(): string;
     getDeviceId(): string | null;
@@ -804,6 +1182,7 @@ interface IPaywalloClient {
 
 declare const PaywalloClient: IPaywalloClient;
 
+type QueuePriority = "critical" | "normal";
 interface QueueItem {
     id: string;
     method: "POST" | "PUT";
@@ -813,23 +1192,87 @@ interface QueueItem {
     timestamp: number;
     attempts: number;
     maxAttempts: number;
+    /**
+     * Priority for this queue item. `"critical"` items are journaled to disk
+     * immediately and trigger an out-of-band flush via listeners; `"normal"`
+     * items are still journaled pre-network but coalesce into batch snapshots.
+     * Optional so pre-existing serialized items (SDK ≤0.10) still load.
+     */
+    priority?: QueuePriority;
+    /**
+     * Epoch ms timestamp before which this item should NOT be retried.
+     * Computed via exponential backoff after each failed attempt.
+     * Absent on first attempt (item eligible immediately).
+     */
+    nextRetryAt?: number;
 }
 interface OfflineQueueConfig {
     maxItems: number;
     maxAge: number;
     maxAttempts: number;
     storageKey: string;
+    /**
+     * Storage key for the pre-write journal. New items are written here first
+     * (append-only) BEFORE any network attempt so a kernel panic between
+     * `enqueue` and the main snapshot save still lets us recover the item on
+     * the next cold start.
+     */
+    journalKey: string;
+    /**
+     * Storage key for the dead-letter queue. Items that exhaust `maxAttempts`
+     * are moved here instead of being silently dropped, enabling diagnostics
+     * and manual replay.
+     */
+    dlqKey: string;
+    /**
+     * Maximum number of items retained in the DLQ. Oldest items are evicted
+     * when the limit is reached (FIFO).
+     */
+    dlqMaxItems: number;
+    /**
+     * Base delay (ms) for exponential backoff on retry.
+     * Delay = min(baseRetryDelayMs * 2^(attempts-1), maxRetryDelayMs).
+     */
+    baseRetryDelayMs: number;
+    /**
+     * Maximum delay cap (ms) for exponential backoff.
+     */
+    maxRetryDelayMs: number;
     debug: boolean;
 }
-type QueueEventType = "item:added" | "item:removed" | "item:success" | "item:failed" | "item:evicted" | "processing:start" | "processing:end";
+type QueueEventType = "item:added" | "item:removed" | "item:success" | "item:failed" | "item:evicted" | "item:expired" | "processing:start" | "processing:end" | "recovery:complete" | "flush:requested";
 interface QueueEvent {
     type: QueueEventType;
     item?: QueueItem;
     error?: Error;
     queueSize: number;
+    /**
+     * Populated on `item:expired` and `recovery:complete` events to surface
+     * counts without forcing listeners to snapshot the queue.
+     */
+    count?: number;
+    /**
+     * Populated on `item:expired` so observability can report WHY items were
+     * dropped (currently always `"max_age"`). Never a silent drop.
+     */
+    reason?: "max_age";
 }
 type QueueListener = (event: QueueEvent) => void;
 
+/**
+ * Durable offline queue with a pre-write journal.
+ *
+ * Durability contract:
+ * 1. `enqueue()` writes the new item to a dedicated journal key in storage
+ *    BEFORE any network attempt and before the item is added to the
+ *    in-memory queue.
+ * 2. The main snapshot is written after the in-memory mutation.
+ * 3. On boot, `initialize()` merges main+journal (dedup by id) and persists
+ *    the union.
+ *
+ * Persistence logic is delegated to `OfflineQueueStorage`.
+ * Retention: items older than `maxAge` (default 7 days) are dropped.
+ */
 declare class OfflineQueueClass {
     private config;
     private queue;
@@ -838,12 +1281,10 @@ declare class OfflineQueueClass {
     private processing;
     private processingLock;
     private cleanupTimer;
+    private storage;
     initialize(config?: Partial<OfflineQueueConfig>): Promise<void>;
-    private loadFromStorage;
-    private saveToStorage;
-    private cleanupExpired;
-    enqueue(method: "POST" | "PUT", url: string, body: unknown, headers?: Record<string, string>, id?: string): Promise<QueueItem>;
-    private findDuplicateIndex;
+    enqueue(method: "POST" | "PUT", url: string, body: unknown, headers?: Record<string, string>, id?: string, priority?: QueuePriority): Promise<QueueItem>;
+    private mergeDuplicate;
     dequeue(): Promise<QueueItem | null>;
     removeItem(id: string): Promise<boolean>;
     processQueue(processor: (item: QueueItem) => Promise<boolean | {
@@ -856,6 +1297,9 @@ declare class OfflineQueueClass {
         failed: number;
     }>;
     private handleItemFailure;
+    private moveToDlq;
+    getDlq(): Promise<QueueItem[]>;
+    clearDlq(): Promise<void>;
     private sleep;
     getQueue(): ReadonlyArray<QueueItem>;
     getSize(): number;
@@ -875,11 +1319,18 @@ declare const offlineQueue: OfflineQueueClass;
 interface QueueProcessorConfig {
     debounceMs: number;
     debug: boolean;
+    /**
+     * Lazy getter for headers that must be fresh at flush time (e.g. `X-App-Key`).
+     * Called just before each batch/item HTTP request — not at enqueue time.
+     * Avoids stale headers when the app key changes after the item was queued.
+     */
+    getFreshHeaders?: () => Record<string, string>;
 }
 declare class QueueProcessorClass {
     private config;
     private httpClient;
     private networkUnsubscribe;
+    private queueUnsubscribe;
     private debounceTimeout;
     private retryIntervalId;
     private initialized;
@@ -903,15 +1354,85 @@ declare class QueueProcessorClass {
 }
 declare const queueProcessor: QueueProcessorClass;
 
-declare class AnalyticsError extends PaywalloError {
+/**
+ * Minimal surface the OnboardingManager needs from the unified event pipeline.
+ * `PaywalloClient` satisfies this interface (forwarding to
+ * `ApiClient.trackEvent` → `EventBatcher` → `/api/v1/events/batch`).
+ */
+interface OnboardingEventPipeline {
+    trackEvent(eventName: string, distinctId: string, properties?: Record<string, unknown>, timestamp?: number): Promise<void>;
+    getDistinctId(): string;
+}
+interface OnboardingDepsConfig {
+    pipeline: OnboardingEventPipeline;
+    debug?: boolean;
+}
+declare class OnboardingManager {
+    private pipeline;
+    private debug;
+    private lastStep;
+    private finished;
+    /**
+     * Injects runtime dependencies. Called by PaywalloClient during init.
+     */
+    injectDeps(config: OnboardingDepsConfig): void;
+    /**
+     * Tracks an onboarding step view.
+     * Saves the step name internally for implicit drop detection on the backend.
+     *
+     * @param stepName - Unique name for this onboarding step.
+     */
+    step(stepName: string): Promise<void>;
+    /**
+     * Tracks successful completion of the onboarding flow.
+     * Marks the flow as finished.
+     */
+    complete(): Promise<void>;
+    /**
+     * Tracks an explicit drop (abandonment) at the given step.
+     * Marks the flow as finished.
+     *
+     * @param stepName - The step name where the user dropped off.
+     */
+    drop(stepName: string): Promise<void>;
+    /** Returns the last step name seen, or null if no step was tracked yet. */
+    getLastStep(): string | null;
+    /** Returns whether the flow has been marked as finished (complete or drop). */
+    isFinished(): boolean;
+    private emit;
+    private assertConfig;
+    private validateStepName;
+}
+declare const onboardingManager: OnboardingManager;
+
+declare class OnboardingError extends PaywalloError {
     constructor(code: string, message: string);
 }
-declare const ANALYTICS_ERROR_CODES: {
-    readonly NOT_INITIALIZED: "ANALYTICS_NOT_INITIALIZED";
-    readonly INVALID_STEP_INDEX: "ANALYTICS_INVALID_STEP_INDEX";
-    readonly INVALID_ACTION_NAME: "ANALYTICS_INVALID_ACTION_NAME";
+declare const ONBOARDING_ERROR_CODES: {
+    readonly NOT_INITIALIZED: "ONBOARDING_NOT_INITIALIZED";
+    readonly INVALID_STEP_NAME: "ONBOARDING_INVALID_STEP_NAME";
 };
 
+/** Payload sent with onboarding.step events. */
+interface OnboardingStepPayload {
+    step_name: string;
+}
+/** Payload sent with onboarding.drop events. */
+interface OnboardingDropPayload {
+    step_name: string;
+}
+
+interface UseOnboardingResult {
+    step: (stepName: string) => Promise<void>;
+    complete: () => Promise<void>;
+    drop: (stepName: string) => Promise<void>;
+}
+/**
+ * React hook that exposes bound onboarding tracking methods.
+ * Wraps `onboardingManager` with stable `useCallback` references.
+ */
+declare function useOnboarding(): UseOnboardingResult;
+
 declare class CampaignError extends PaywalloError {
     constructor(code: string, message: string);
 }
@@ -1089,4 +1610,4 @@ declare function hasVariables(text: string): boolean;
 
 declare const Paywallo: IPaywalloClient;
 
-export { ANALYTICS_ERROR_CODES, AnalyticsError, ApiClient, type ApiClientConfig, type BlockType, type BoxSpacing, CAMPAIGN_ERROR_CODES, type CachedSubscription, CampaignError, type CampaignPresentOptions, type CampaignResponse, type CampaignResult, type ConditionalFlagContext, type ConditionalFlagResult, PURCHASE_ERROR_CODES as ERROR_CODES, type EmergencyPaywallResponse, type Environment, type FlagVariant, HttpClient, type HttpClientConfig, type HttpResponse, type IAPProduct, type IAPPurchase, IAPService, IDENTITY_ERROR_CODES, type IPaywalloClient, type IdentifyOptions, IdentityError, IdentityManager, type IdentityState, type LocalizedText, MetaBridge, type NetworkListener, type NetworkMonitorConfig, type NetworkState, type OfflineQueueConfig, PAYWALL_ERROR_CODES, PURCHASE_ERROR_CODES, type PaywallBlockConfig, type PaywallConfig, PaywallContext, PaywallError, type PaywallErrorStrings$1 as PaywallErrorStrings, PaywallModal, type PaywallNode, type PaywallPresentOptions, type PaywallResult, type PaywallState, Paywallo, PaywalloClient, type PaywalloConfig, PaywalloContext, PaywalloError, type PaywalloInitConfig, PaywalloProvider, type PaywalloProviderProps, type PreloadCampaignResult, type PreloadResult, type Product, type ProductPriceInfo, type Purchase, type PurchaseControllerConfig, PurchaseError, type PurchaseResult, type PurchaseState, type QueueEvent, type QueueItem, type QueueListener, type QueueProcessorConfig, type RequestOptions, type RestoreResult, type RetryConfig, SESSION_ERROR_CODES, type SessionConfig, SessionError, SessionManager, type SessionState, type Subscription, SubscriptionCache, type SubscriptionInfo, type SubscriptionManagerConfig, type SubscriptionPlatform, type SubscriptionStatus$1 as SubscriptionStatus, type SubscriptionStatusResponse$1 as SubscriptionStatusResponse, type TapBehavior, type TrackEventOptions, type UserProperties, type ValidatePurchaseResponse, type VariableContext, createPurchaseError, Paywallo as default, detectDeviceLanguage, getCurrentLanguage, getDefaultLanguage, getIAPService, getLocalizedString, hasVariables, identityManager, initLocalization, metaBridge, nativeStoreKit, networkMonitor, offlineQueue, parseVariables, queueProcessor, resolveText, sessionManager, setCurrentLanguage, setDefaultLanguage, subscriptionManager, usePaywallContext, usePaywallo, useProducts, usePurchase, useSubscription };
+export { ApiClient, type ApiClientConfig, type BlockType, type BoxSpacing, CAMPAIGN_ERROR_CODES, type CachedSubscription, CampaignError, type CampaignPresentOptions, type CampaignResponse, type CampaignResult, type ConditionalFlagContext, type ConditionalFlagResult, type DeviceTokenRegistration, PURCHASE_ERROR_CODES as ERROR_CODES, type EmergencyPaywallResponse, type Environment, type FlagVariant, HttpClient, type HttpClientConfig, type HttpResponse, type IAPProduct, type IAPPurchase, IAPService, IDENTITY_ERROR_CODES, type IPaywalloClient, type IPushBridge, type IdentifyOptions, IdentityError, IdentityManager, type IdentityState, type LocalizedText, MetaBridge, NOTIFICATIONS_ERROR_CODES, NativePushBridge, type NetworkListener, type NetworkMonitorConfig, type NetworkState, type NotificationEventType, type NotificationListener, type NotificationPayload, NotificationsError, NotificationsManager, ONBOARDING_ERROR_CODES, type OfflineQueueConfig, type OnboardingDropPayload, OnboardingError, OnboardingManager, type OnboardingStepPayload, PAYWALL_ERROR_CODES, PURCHASE_ERROR_CODES, type PaywallBlockConfig, type PaywallConfig, PaywallContext, PaywallError, type PaywallErrorStrings$1 as PaywallErrorStrings, PaywallModal, type PaywallNode, type PaywallPresentOptions, type PaywallResult, type PaywallState, Paywallo, PaywalloClient, type PaywalloConfig, PaywalloContext, PaywalloError, type PaywalloInitConfig, PaywalloProvider, type PaywalloProviderProps, type PrePromptHandle, type PrePromptOptions, type PreloadCampaignResult, type PreloadResult, type Product, type ProductPriceInfo, type Purchase, type PurchaseControllerConfig, PurchaseError, type PurchaseResult, type PurchaseState, type PushPermissionStatus, type PushPlatform, type QueueEvent, type QueueItem, type QueueListener, type QueueProcessorConfig, type RequestOptions, type RestoreResult, type RetryConfig, SESSION_ERROR_CODES, type SessionConfig, SessionError, SessionManager, type SessionState, type Subscription, SubscriptionCache, type SubscriptionInfo, type SubscriptionManagerConfig, type SubscriptionPlatform, type SubscriptionStatus$1 as SubscriptionStatus, type SubscriptionStatusResponse$1 as SubscriptionStatusResponse, type TapBehavior, type TrackEventOptions, type UserProperties, type ValidatePurchaseResponse, type VariableContext, createPurchaseError, Paywallo as default, detectDeviceLanguage, getCurrentLanguage, getDefaultLanguage, getIAPService, getLocalizedString, hasVariables, identityManager, initLocalization, metaBridge, nativeStoreKit, networkMonitor, notificationsManager, offlineQueue, onboardingManager, parseVariables, queueProcessor, resolveText, sessionManager, setCurrentLanguage, setDefaultLanguage, subscriptionManager, useOnboarding, usePaywallContext, usePaywallo, useProducts, usePurchase, useSubscription };