@scalebun-release/react-native 2.5.0

package/lib/typescript/public/ScaleBunFacade.d.ts

@@ -0,0 +1,800 @@
+/**
+ * ScaleBun SDK — Public Facade
+ *
+ * Single clean entry point for the ScaleBun SDK.
+ * Delegates initialization to SDKBootstrapper, which handles config validation,
+ * core service setup, handshake, and feature registration via FeatureRegistry.
+ *
+ * Config model preserved exactly: projectId, publishableKey, apiBaseUrl.
+ * Features are default-on with explicit opt-out via `features: { replay: false }`.
+ */
+import type { BugSubmitResult } from '../features/bugreport/BugReportFeature';
+import type { DebugConfig } from '../debug';
+import type { ReplayUser, ReplayBreadcrumb, ReplayPrivacyOptions } from '../features/replay/public/types';
+import type { SubscriptionInput } from '../analytics/subscription';
+import type { RevenueInput } from '../analytics/revenue';
+import { type SubmitStage } from '../features/engage/EngageTransport';
+import type { EnablePushOptions, EnablePushResult, PushNotification } from '../push/types';
+import type { EngageAttachmentDraft, EngageConfigContext, EngageConfigResponse, EngageEventInput, EngageResponseInput, RatingFunnelEventInput, SurveyImpressionInput } from '../features/engage/engageTypes';
+import { type SkanCoarseValue } from '../features/skan/skanBridge';
+import type { ScaleBunInitConfig, ScaleBunUser, ScaleBunFeatures, SimplifiedInitConfig, PrivacyConfig, BrandingConfig, ExportPresetName, SimplifiedExportOptions, ExportResult } from './types';
+declare class ScaleBunFacade {
+    private initialized;
+    /** In-flight init promise — guards against a second init() racing before the first resolves. */
+    private _initInFlight;
+    private bootstrapper;
+    private _features;
+    private _performanceFeature;
+    private _privacyConfig;
+    private _brandingConfig;
+    private _clientKey;
+    private _apiBaseUrl;
+    private _engageTransport;
+    private _engageTokenUnsubscribe;
+    private _pushManager;
+    /** Phase 1 envelope event-tracking lane (POST /v1/batch). Null until init with appId. */
+    private _eventTracker;
+    /** External identity last supplied through identify(); used by config targeting. */
+    private _identifiedUserId;
+    /** Identity supplied while async initialization is still in flight. */
+    private _pendingIdentity;
+    private _configManager;
+    /**
+     * The ConfigManager that owns /config refreshes for quota: `_configManager` when the event
+     * tracker created one, else a quota-only instance (no appId → no tracker, but a clientKey still
+     * has a plan with limits). Never exposed through the flags/experiments API.
+     */
+    private _configRefresher;
+    private _configForegroundListener;
+    /** The developer's locally-configured replay captureMode — the value to revert to when an
+     *  admin-forced frequency override (from /config) is withdrawn. Default matches the SDK default. */
+    private _devCaptureMode;
+    /** True while an admin frequency override from /config is applied, so we know to revert. */
+    private _replayOverrideActive;
+    /** Signature of the last identity POSTed to the ingestion identify endpoint, to skip redundant re-sends. */
+    private _lastIngestionIdentityKey;
+    /** Phase 3: auto-applies SKAN conversion values from the server schema (iOS only). */
+    private _skanManager;
+    /**
+     * Pre-init memory buffer.
+     * Events tracked before init() completes are buffered here,
+     * then drained into the real persistent queue post-init.
+     */
+    private _preInitBuffer;
+    /** Resolve the active queue (DI container or pre-init buffer) */
+    private _getQueue;
+    /**
+     * Initialize the ScaleBun SDK.
+     *
+     * **Simplified usage** (recommended):
+     * ```ts
+     * await ScaleBun.init({
+     *   projectId: 'proj_xxx',
+     *   publishableKey: 'pk_xxx',
+     *   apiBaseUrl: 'https://api.scalebun.com',
+     *   debug: true,
+     * });
+     * ```
+     *
+     * Accepts both `SimplifiedInitConfig` (new) and `ScaleBunInitConfig` (legacy).
+     * If `debug` key is present, auto-connects to the desktop debugger.
+     */
+    init(rawConfig: SimplifiedInitConfig | ScaleBunInitConfig | any): Promise<void>;
+    /**
+     * Boot the OTA orchestrator when the init config asks for it.
+     *
+     * Signature enforcement is no longer configured from JS. Signed releases are
+     * verified and staged in NATIVE code against RSA keys embedded in the app
+     * package (SB-OTA-RSA-SHA256-V1); unsigned releases keep working on SHA-256
+     * integrity. There are no signing-key or `verifySignature` options to pass
+     * through — the host embeds its trusted keys natively.
+     */
+    private _maybeStartOta;
+    /** Guards against overlapping config-driven OTA checks. */
+    private _otaCheckInFlight;
+    /** Wall clock of the last config-driven check, for the foreground floor. */
+    private _otaLastCheckAt;
+    private _otaForegroundListener;
+    /**
+     * Minimum gap between config-driven checks.
+     *
+     * A foreground transition is cheap to trigger — app switchers, permission
+     * dialogs and share sheets all produce one — so an unthrottled check would
+     * put a request on the hot path every time the user glanced away. Ten
+     * minutes is well below any realistic release cadence and well above that
+     * noise. A host that wants a check on demand calls `useOtaUpdate().sync()`,
+     * which is never throttled.
+     */
+    private static readonly OTA_MIN_CHECK_INTERVAL_MS;
+    /**
+     * Drive OTA checks from init config: once at startup, then on each
+     * foreground when `checkOnForeground` is on (the schema default).
+     *
+     * `appVersion` is resolved from the native bridge rather than asked of the
+     * integrator, because it gates the server's `targetAppVersion` semver check
+     * — sending a wrong or invented value is worse than sending none, and there
+     * is no honest default. If it cannot be resolved, the check is skipped with
+     * a warning instead of guessing.
+     */
+    private _startOtaChecks;
+    private _autoEnableDebug;
+    /**
+     * Keep /config (and with it the per-feature quota state) live for any clientKey-configured app.
+     *
+     *  - Creates a quota-only ConfigManager when the appId-gated event tracker did not create one.
+     *    Its exposure/stamp hooks are inert; it is not the flags API's manager.
+     *  - Registers the FORCED refresh quotaState runs when a block's refresh time is reached (the
+     *    only way a block is lifted — never the device clock alone).
+     *  - Refreshes on foreground, throttled by ConfigManager's 5-minute TTL (ETag-aware), which is how
+     *    a raised limit reaches a long-lived app.
+     *
+     * BEHAVIOUR CHANGE, deliberate (quota contract v1): apps WITHOUT an appId now fetch /config once
+     * per launch, and every clientKey app re-fetches it on foreground after 5 minutes. That fetch is
+     * how a block — and the raising of a limit — reaches the device; it is not an ingestion request.
+     * The quota-only manager applies NOTHING else from /config: no flags API, no experiment
+     * exposure, and no admin replayCapture override (that stays an appId-app behaviour, as before).
+     */
+    private _startConfigLifecycle;
+    /**
+     * Release what _startConfigLifecycle registered (the forced-refresh hook and the foreground
+     * listener). The facade has no teardown path today; this is the one to call when it gets one.
+     */
+    private _stopConfigLifecycle;
+    /** Boot the Phase 1 envelope tracking lane if an appId is configured. */
+    private _maybeStartEventTracker;
+    /**
+     * Fold the native bridge's device facts into the analytics context once it answers.
+     *
+     * Detected values never overwrite a populated one with an empty one — `nativeDeviceContext`
+     * drops absent keys and `applyDetectedContext` ignores an empty patch — so a bridge that
+     * cannot answer leaves whatever `Platform.constants` already found.
+     */
+    private _applyNativeDeviceContext;
+    /**
+     * Apply (or revert) the admin-controlled replay capture override delivered via GET /config.
+     *
+     * When the super-admin has forced timer capture, `override` is `{ mode: 'frequency', intervalMs }`
+     * and we switch replay to frequency at that interval — overriding the developer's local
+     * captureMode (which Part 1 restricts to navigation/interactions). When the override is withdrawn
+     * (`null`) AND we had previously applied one, we revert to the developer's configured mode.
+     *
+     * Non-throwing and a no-op when replay is disabled. Idempotent — re-applying the same override
+     * just re-asserts the native state, which is harmless.
+     */
+    private _applyReplayCaptureOverride;
+    /**
+     * Android-only: read the Play Install Referrer once per install and route it into
+     * attribution. `scalebun_click_id` → the deterministic click path; the full
+     * referrer (utm_source/gclid/…) rides on a one-off `install_referrer` event. A
+     * `null` fetch (Play unavailable/transient) is not marked captured, so a later
+     * launch retries while Play still has the referrer. Never throws.
+     */
+    private _captureInstallReferrer;
+    /**
+     * Phase 1 envelope event tracking API (POST /v1/batch).
+     * Methods are no-ops (never throw) until init() is called with an `appId`.
+     */
+    get events(): {
+        track: (eventName: string, properties?: Record<string, any>) => void | undefined;
+        identify: (userId: string, traits?: Record<string, any>) => void | undefined;
+        trackPurchase: (input: RevenueInput) => void | undefined;
+        trackSubscription: (input: SubscriptionInput) => void | undefined;
+        setIdentifiers: (ids: {
+            idfa?: string;
+            gaid?: string;
+            idfv?: string;
+        }) => void | undefined;
+        setAttributionClickId: (clickId: string) => void | undefined;
+        flush: () => Promise<void>;
+        newSession: () => void | undefined;
+        ids: () => {
+            installationId: string;
+            anonymousId: string;
+            sessionId: string;
+            userId: string | undefined;
+        } | null;
+        /** Pending and dropped event counts for host diagnostics. */
+        stats: () => import("../analytics/EventTracker").EventTrackerStats | null;
+        updateSkanConversionValue: (value: number, coarseValue?: SkanCoarseValue, lockWindow?: boolean) => Promise<boolean>;
+    };
+    /**
+     * Phase 4: runtime config delivered via GET /v1/config. All resolution is local
+     * and non-throwing; values default sensibly until init() runs / config is fetched.
+     *
+     *   ScaleBun.config.get('max_items', 10)
+     *   ScaleBun.flags.isEnabled('new_checkout')
+     *   ScaleBun.rollouts.isOn('beta_paywall')
+     *   ScaleBun.experiments.variant('checkout_cta')   // → 'control' | 'treatment' | null
+     */
+    get config(): {
+        get: <T = any>(key: string, fallback: T) => T;
+        refresh: () => Promise<void>;
+    };
+    get flags(): {
+        isEnabled: (key: string) => boolean;
+    };
+    get rollouts(): {
+        isOn: (key: string) => boolean;
+    };
+    get experiments(): {
+        variant: (key: string) => string | null;
+    };
+    /** Convenience: emit a Phase 1 purchase event (revenue + currency + transaction_id). */
+    /**
+     * Declare which UI state the user is looking at, so taps are attributed to the surface they
+     * happened on rather than averaged across every variant of the screen.
+     *
+     *     ScaleBun.setUiState('filter-sheet', 'open');
+     *     ScaleBun.setUiState('checkout-step', 'payment');
+     *
+     * Call it when the state CHANGES — the value is read at tap time, so it only has to be right by
+     * the time the next tap lands. On React Native this is the ONLY source of UI state: unlike the web,
+     * there is no queryable accessibility tree that says a sheet is up, and guessing would produce a
+     * state key that is right on some apps and silently wrong on others.
+     *
+     * Names and values are identifiers, not content: they become query keys in the dashboard, so a
+     * person's name or a cart total does not belong in one. `;`, `:` and `|` are stripped and both
+     * halves are capped at 32 characters.
+     */
+    setUiState(name: string, value: string): void;
+    /**
+     * Stop reporting a UI state dimension — or, with no argument, all of them.
+     *
+     * Clear on screen unmount. A declaration left behind follows the user onto a surface where it means
+     * nothing, and every tap there is filed under a state that was not on screen.
+     */
+    clearUiState(name?: string): void;
+    trackPurchase(input: RevenueInput): void;
+    /** Record a trial, renewal, plan change or cancellation in the subscription ledger. */
+    trackSubscription(input: SubscriptionInput): void;
+    /**
+     * Phase 3: set the SKAdNetwork fine conversion value (0–63), optionally with a
+     * SKAN 4.0 coarse value and window-lock. iOS only — a no-op on Android / Expo Go.
+     */
+    updateSkanConversionValue(value: number, coarseValue?: SkanCoarseValue, lockWindow?: boolean): void;
+    /** Get the current feature flags (consumed by enableDebug) */
+    getFeatureFlags(): ScaleBunFeatures;
+    /** Identify a user by ID and optional traits */
+    identify(userId: string, traits?: Record<string, any>): void | undefined;
+    /**
+     * Stable public alias for {@link identify}. Part of the minimal public push
+     * API surface (ScaleBun.init / identifyUser / enablePush) that stays
+     * identical across RN versions and future platforms.
+     */
+    identifyUser(userId: string, traits?: Record<string, any>): void | undefined;
+    /** POST user identity to the SaaS ingestion identify endpoint */
+    private _callIngestionIdentify;
+    /** Set user identity (for session context) */
+    setUser(user: ScaleBunUser): void | undefined;
+    /**
+     * Clear user identity.
+     *
+     * SB-11: pass `{ purgeLocal: true }` on logout / consent withdrawal to also
+     * erase all locally-stored SDK data (see {@link eraseLocalData}). Without it,
+     * behaviour is unchanged (identity-only clear).
+     */
+    clearUser(options?: {
+        purgeLocal?: boolean;
+    }): void | undefined;
+    /**
+     * SB-11: erase all locally-stored SDK data from the device — the durable event
+     * queue, the pre-init buffer, and the first-party KV store (cached install /
+     * anonymous / session IDs, plus any queued payloads including SB-26 disk data).
+     *
+     * Order matters: capture is stopped FIRST so nothing is written back in behind
+     * the delete. Best-effort and never throws.
+     *
+     * Note: native replay frames written to disk on iOS are addressed separately
+     * (SB-15); this covers every store reachable from JS today.
+     */
+    eraseLocalData(): Promise<void>;
+    /**
+     * SB-11: record the user's data-collection consent. When `enabled` is false,
+     * capture is stopped immediately; pass `{ purgeLocal: true }` to also erase
+     * everything already stored locally. Never throws.
+     */
+    setConsent(enabled: boolean, options?: {
+        purgeLocal?: boolean;
+    }): void;
+    /**
+     * SB-10: return the effective privacy policy actually in force, resolving the
+     * public config against the SDK's safe defaults. Lets callers and tests assert
+     * what is active rather than guessing from the (previously dead) config object.
+     */
+    getEffectivePrivacyPolicy(): Required<Pick<PrivacyConfig, 'maskTextInputs' | 'maskImages' | 'redactAuth' | 'redactCookies' | 'redactBodies'>>;
+    /**
+     * Submit in-app rating (1-5 stars).
+     * Attaches to current session when available; otherwise sends standalone.
+     * Never throws.
+     */
+    submitRating(input: {
+        rating: number;
+        comment?: string;
+        source?: 'in_app' | 'prompt' | 'manual';
+        /** [ADDITIVE] client-generated UUID for app-rating idempotency (contract §1.4, D8). */
+        clientRatingId?: string;
+    }): Promise<{
+        ok: boolean;
+        reason: "sdk_not_configured";
+        status?: undefined;
+    } | {
+        ok: boolean;
+        reason: "invalid_rating";
+        status?: undefined;
+    } | {
+        ok: boolean;
+        reason: "http_error";
+        status: number;
+    } | {
+        ok: true;
+        reason?: undefined;
+        status?: undefined;
+    } | {
+        ok: boolean;
+        reason: "network_error";
+        status?: undefined;
+    } | undefined>;
+    private getActiveSessionId;
+    /**
+     * Thin feature object; the facade owns the HTTP, mirroring the web SDK split.
+     * Its only job here is raising the 'report' capture signal so replay flushes.
+     */
+    private readonly _bugReport;
+    /**
+     * Submit a bug report against the CURRENT session.
+     *
+     * Mirrors the web SDK's `reportBugDetailed` ordering, which is load-bearing rather than
+     * incidental:
+     *
+     *   1. resolve the session   — a report with no session cannot be joined to its evidence
+     *   2. signal 'report'       — replay flushes its buffer so the report has visual context
+     *   3. snapshot the anchor   — BEFORE the POST. A flush asks the recorder to deliver pending
+     *                              bytes; it cannot retroactively manufacture a frame, so an absent
+     *                              coordinate must stay absent rather than becoming a misleading
+     *                              "start of session" link in the dashboard
+     *   4. build + POST          — bounds enforced by buildBugReportPayload against the server DTO
+     *
+     * Returns the report id, or `{ e }` naming which branch failed — 'init' (SDK not configured)
+     * reads differently from 'send' (network), and that difference is what tells an integrator
+     * whether to check their setup or their connection. It never throws: this is called from a UI
+     * the host app renders, usually from a user gesture, and an exception escaping into a React
+     * Native render tree is a redbox shown to the customer's user over a report they were sending us.
+     */
+    reportBugDetailed(input: {
+        message: string;
+        title?: string;
+        email?: string;
+        clientReportId?: string;
+    }): Promise<BugSubmitResult>;
+    /**
+     * The replay coordinate at submit time, or null.
+     *
+     * Deliberately returns null rather than a zeroed coordinate when replay is disabled, paused, or
+     * has not produced a frame yet — see the anchor note on reportBug.
+     */
+    /**
+     * The replay coordinate at submit time.
+     *
+     * ALWAYS null today, deliberately and visibly.
+     *
+     * The web SDK reads this from its recorder, but the RN replay subsystem exposes no sequence or
+     * segment accessor on its public API (features/replay/public/api.ts) -- there is currently no
+     * supported way to ask it where playback is. Probing for it through an `any` cast would compile,
+     * miss, and leave every report anchor-less while looking wired: the same defect as the existing
+     * reportBug(), which emits an analytics event and looks like it files a report.
+     *
+     * Returning null keeps the payload HONEST -- buildBugReportPayload omits replaySeq entirely, so
+     * the dashboard shows no anchor rather than a false one pointing at the start of the session.
+     * To finish this: expose the current seq + segment id from the replay recorder, then read them
+     * here. The payload builder and its contract tests already handle a real coordinate, including
+     * a genuine seq of 0.
+     */
+    private _replayCoord;
+    /** Recent console breadcrumbs for quick triage. The full set already travels with the session. */
+    private _recentBreadcrumbs;
+    /**
+     * Lazily resolve the Engage transport. Requires a configured SaaS clientKey +
+     * apiBaseUrl (same gate as the rating/ingestion lanes); returns null otherwise.
+     * The transport mirrors the existing BackendSessionAdapter outbox: upload lanes
+     * batch-flush and re-queue on failure, the config GET is a direct fetch.
+     */
+    private _getEngageTransport;
+    /**
+     * Engage surface namespace (foundation: transport + native push-token plumbing).
+     *
+     * Rendering of campaigns/in-app messages is a SHARED cross-platform JS overlay
+     * (D4) built in a later stage. This namespace exposes only the foundation:
+     * versioned config fetch, idempotent response/event upload (via the existing
+     * outbox), and native push-token registration on both platforms.
+     */
+    engage: {
+        /** Current external identity, forwarded by the provider for segment targeting. */
+        getIdentifiedUserId: () => string | undefined;
+        /**
+         * Fetch the versioned Engage config (campaigns + in-app messages).
+         *
+         * slice-agent: the shared cross-platform JS overlay renderer consumes this
+         * payload (EngageConfigResponse.campaigns / .inAppMessages) in a later stage.
+         */
+        fetchConfig: (context?: EngageConfigContext) => Promise<EngageConfigResponse | null>;
+        /** Internal bridge used by the shared renderer to feed standalone tour analytics. */
+        trackCoachmarkEvent: (name: string, properties: Record<string, unknown>) => void;
+        /**
+         * DEBUG/DEV ONLY — clear the persisted in-app/campaign frequency-cap state
+         * (every `scalebun_engage_throttle:*` key: impressions, showOnce/completed, cooldown).
+         * Lets a tester see throttled/dismissed messages again WITHOUT uninstalling the
+         * app. Does NOT change the device id (identity is preserved). Returns the number
+         * of cleared entries. NOT a substitute for the real fix (revision-scoped state +
+         * test-preview bypass already make normal Send Test work without this).
+         */
+        clearInAppMessageCache: () => number;
+        /**
+         * DEBUG/DEV ONLY — alias of {@link clearInAppMessageCache} with the broader name
+         * used in docs. Resets all on-device in-app frequency/dismiss/impression state so
+         * the next config poll can show messages again. Identity (device id) is untouched.
+         */
+        resetInAppState: () => number;
+        /**
+         * Force an immediate flush of queued in-app events. The provider calls this right
+         * after a TEST preview's impression/dismiss ACK so the backend consumes the
+         * one-shot preview row promptly — a fast close→kill→reopen can't re-serve a
+         * still-`delivered` test. Best-effort, never throws.
+         */
+        flushEvents: () => void;
+        /**
+         * DEBUG/DEV ONLY — force a fresh config fetch (deviceId in context) and return the
+         * in-app messages the backend is serving THIS device right now, including any
+         * queued test previews (`preview:true`). Use it to verify Send Test targeting/
+         * delivery without rendering. Logs a one-line summary for the dev console.
+         */
+        debugFetchInAppMessages: (context?: EngageConfigContext) => Promise<EngageConfigResponse["inAppMessages"]>;
+        /** Upload a survey/NPS/feedback response (idempotent, rides the outbox). */
+        submitResponse: (input: EngageResponseInput) => void;
+        /**
+         * [P3-e] Submit a response carrying native attachments (screenshot/voice).
+         * Presigns + PUTs bytes direct to storage, then enqueues the response with
+         * key-only metadata linked by responseId. Falls back to a plain response
+         * (no media) when storage is disabled. Best-effort, never throws.
+         */
+        submitResponseWithAttachments: (input: EngageResponseInput, attachments: EngageAttachmentDraft[]) => void;
+        /**
+         * [Slice D5] CONFIRMED response submit for the in-prompt submitting→success→error
+         * UI. UNLIKE submitResponse*, this AWAITS real server persistence (presign+PUT any
+         * audio/screenshot bytes, then a direct response POST) and REJECTS on failure so the
+         * caller can show a retryable error. Idempotent: pass the SAME `responseId` on retry
+         * — both response and attachments de-dupe server-side. Used by EVERY question type.
+         */
+        submitResponseConfirmed: (input: EngageResponseInput, attachments: EngageAttachmentDraft[], opts: {
+            responseId: string;
+            onStage?: (stage: SubmitStage) => void;
+        }) => Promise<void>;
+        /** Upload an in-app impression/click/dismiss event (idempotent, rides the outbox). */
+        trackEvent: (input: EngageEventInput) => void;
+        /** Upload an idempotent survey shown/started funnel beacon. */
+        trackSurveyImpression: (input: SurveyImpressionInput) => void;
+        /**
+         * Emit a rating-funnel tracking event (ratings-rebuild CONTRACT §1.2). These
+         * are dimensioned FACTS feeding the Overview funnel — NOT campaign responses
+         * (D1) — so they ride their own `/ingestion/rating-events` lane. Idempotent
+         * (client `eventId`, D8). Best-effort, never throws.
+         */
+        emitRatingEvent: (input: RatingFunnelEventInput) => void;
+        /**
+         * Trigger the native in-app review sheet (Play In-App Review on Android,
+         * SKStoreReviewController on iOS) — the genuinely-native leg of the rating
+         * funnel (D5). Resolves `true` ONLY when the OS flow ran/resolved after a
+         * positive route, so the caller emits `store_redirect_clicked` solely on a
+         * `true` result. Fail-soft: resolves `false` when native review is unavailable.
+         */
+        requestStoreReview: () => Promise<boolean>;
+        /**
+         * Submit a 1–5 app-store rating via the EXISTING app-rating lane (D1 keeps
+         * ratings a distinct funnel — NOT submitResponse). Delegates to the
+         * facade's `submitRating`, threading the renderer's `clientRatingId` for
+         * idempotency (D8). Used by the RATING_PROMPT render branch.
+         */
+        submitRating: (input: {
+            rating: number;
+            comment?: string;
+            source?: "in_app" | "prompt" | "manual";
+            clientRatingId?: string;
+        }) => void;
+        /**
+         * Acquire the native push token (FCM/APNs) and register it for delivery.
+         * Subscribes to native token-refresh (rotation) so the backend always holds
+         * the live token. Fail-soft: no-op when native push is unavailable.
+         */
+        registerForPush: () => Promise<void>;
+    };
+    /**
+     * Lazily build the PushManager. Backend token registration is injected and
+     * routes through the existing Engage outbox (EngageTransport.registerDeviceToken),
+     * so push reuses the SDK's single device-token lane rather than a parallel
+     * fetch. Returns {ok:false} when the SDK isn't configured (clientKey absent).
+     */
+    private _getPushManager;
+    /**
+     * Enable push notifications with smart, version-aware adapter selection.
+     *
+     * Detects the RN version, architecture (legacy bridge vs New
+     * Architecture/bridgeless), whether @react-native-firebase/messaging is
+     * installed & compatible, and whether the ScaleBunEngage native token bridge is
+     * linked, then picks the safest supported path automatically: RNFirebase
+     * (full callbacks) → native ScaleBunEngage bridge (token-only fallback that works
+     * under bridgeless regardless of RNFirebase version) → manual → noop.
+     *
+     * Requests OS permission, creates the Android channel, acquires the push
+     * token, keeps it in sync on refresh, registers it with the ScaleBun backend
+     * (via the Engage outbox), and wires foreground/opened callbacks.
+     *
+     * Fails clearly (ok:false + actionable reason) when no usable provider
+     * exists — never silently breaks. Never throws.
+     *
+     * ```ts
+     * await ScaleBun.enablePush({
+     *   onForegroundNotification: (n) => {},
+     *   onNotificationOpened: (n) => {},
+     * });
+     * ```
+     */
+    enablePush(options?: EnablePushOptions): Promise<EnablePushResult>;
+    /**
+     * Subscribe to notifications received while the app is foregrounded. Thin,
+     * platform-agnostic alias for `enablePush({ onForegroundNotification })`; use it
+     * to attach a handler after enablePush. Returns an unsubscribe function. Inert
+     * until push is enabled. (iOS direct APNs delivers these via the native
+     * UNUserNotificationCenter surface.)
+     */
+    onForegroundNotification(cb: (notification: PushNotification) => void): () => void;
+    /**
+     * Subscribe to the user tapping a notification (open / deep-link), including the
+     * cold-start notification that launched the app. Thin alias for
+     * `enablePush({ onNotificationOpened })`. Returns an unsubscribe function. The
+     * event shape ({ data, title?, body? }) matches across Android and iOS.
+     */
+    onNotificationOpened(cb: (notification: PushNotification) => void): () => void;
+    /**
+     * Push control namespace. Most apps only need {@link enablePush}; these are
+     * for the manual/custom provider path and diagnostics.
+     */
+    push: {
+        /** Inject/rotate a token (manual provider) — syncs to the backend. */
+        setToken: (token: string) => void;
+        /** Current push token, if acquired. */
+        getToken: () => string | null;
+        /** Deliver a foreground notification to registered callbacks (manual provider). */
+        emitForeground: (message: PushNotification) => void;
+        /** Deliver a notification-open event to registered callbacks (manual provider). */
+        emitNotificationOpened: (message: PushNotification) => void;
+        /** Current push status: selected adapter, usability, reason, token. */
+        status: () => import("../push/PushManager").PushStatus;
+        /** Tear down all push listeners. */
+        teardown: () => void;
+    };
+    /**
+     * Report the outcome of an OS permission prompt.
+     *
+     * Permission results were state the SDK held privately and never an event, so the core mobile
+     * growth loop — "reached the paywall → was prompted → granted" — could not be expressed as a funnel.
+     *
+     * Notification permission is captured AUTOMATICALLY (the SDK runs that prompt itself, see
+     * PushManager). Every other permission belongs to the host app: the SDK never sees a camera or
+     * location request, so guessing at one would be inventing data. Call this right after the prompt
+     * resolves:
+     *
+     * ```ts
+     * const { status } = await Location.requestForegroundPermissionsAsync();
+     * ScaleBun.trackPermission('location', status === 'granted' ? 'granted' : 'denied');
+     * ```
+     *
+     * `permission` is free-form on purpose — platforms disagree on names and a fixed enum would go
+     * stale — but stick to one spelling per permission or the funnel splits in two.
+     */
+    trackPermission(permission: string, status: 'granted' | 'denied' | 'blocked' | 'undetermined' | 'limited', details?: Record<string, any>): void | undefined;
+    /** Track a named event with optional payload */
+    track(name: string, payload?: Record<string, any>): void | undefined;
+    /**
+     * Log a message. Delivered to BOTH lanes:
+     *  - the Diagnose → Logs lane (tagged `source: 'sdk'`), so an explicit `log()` call shows
+     *    up where a developer looks for logs. The method name promised this, but it previously
+     *    only emitted a `$log` analytics EVENT and never reached the Logs page.
+     *  - the analytics `$log` event (unchanged), so anything already built on it keeps working.
+     * `queueLog` self-gates on `clientKey`, so the Logs-lane write is a no-op outside SaaS mode.
+     */
+    log(level: 'debug' | 'info' | 'warn' | 'error', message: string, data?: Record<string, unknown>): void | undefined;
+    /**
+     * Capture a handled error/exception and deliver it to the backend
+     * errors endpoint (shows up in the dashboard Crashes view).
+     *
+     * No-throw. Routes to: desktop debug stream ($crash event) + SaaS
+     * backend errors ingestion (when a clientKey session is active).
+     */
+    captureError(error: Error | string, context?: {
+        screenName?: string;
+        fatal?: boolean;
+        type?: string;
+        metadata?: Record<string, unknown>;
+    }): void | undefined;
+    /**
+     * DEV/TEST ONLY — trigger a real native crash to validate the native
+     * capture → next-launch drain → backend pipeline. No-op when the native
+     * module is unavailable. Do not ship calls to this in production code.
+     */
+    nativeCrash(): Promise<void> | undefined;
+    /** Report a bug (convenience wrapper over track) */
+    reportBug(description: string, metadata?: Record<string, unknown>): void | undefined;
+    /** Set a custom attribute on the current session */
+    setAttribute(key: string, value: string | number | boolean): void | undefined;
+    /** Force-flush all pending events */
+    flush(): Promise<void | undefined>;
+    /**
+     * Enable the debug subsystem.
+     *
+     * @deprecated Use `ScaleBun.init({ debug: true })` instead.
+     * This method still works for backward compatibility.
+     */
+    enableDebug(config: DebugConfig): void | undefined;
+    /** Disable the debug subsystem and clean up */
+    disableDebug(): void | undefined;
+    /**
+     * Diagnostic-only: stamp the *expected* target for the very next gesture
+     * event. Calibration screens call this immediately before their onPress
+     * fires so SessionManager merges expectedTargetId / expectedNX / expectedNY
+     * into the stored gesture payload. Pure observability — never affects
+     * capture, normalization, or marker placement. TTL ≈ 500 ms.
+     */
+    setCalibrationTarget(target: {
+        targetId: string;
+        expectedNX: number;
+        expectedNY: number;
+    }): void;
+    /**
+     * Debug utilities namespace.
+     * All methods are no-op if debug is not enabled.
+     */
+    debug: {
+        addBreadcrumb: (message: string, data?: Record<string, unknown>) => void;
+        ping: () => void;
+        isEnabled: () => boolean;
+        sendMetric: (name: string, value: number, unit?: string, tags?: Record<string, string>) => void;
+    };
+    /**
+     * Session Replay namespace.
+     * Provides control over session replay: recording, capture,
+     * user identity, privacy, breadcrumbs, and transport.
+     * All methods are no-op if replay feature is disabled.
+     */
+    replay: {
+        start: () => Promise<void>;
+        stop: () => Promise<void>;
+        pause: () => Promise<void>;
+        resume: () => Promise<void>;
+        captureFrame: () => Promise<void>;
+        setUser: (user: ReplayUser) => Promise<void>;
+        clearUser: () => Promise<void>;
+        addBreadcrumb: (breadcrumb: ReplayBreadcrumb) => Promise<void>;
+        setPrivacy: (opts: Partial<ReplayPrivacyOptions>) => Promise<void>;
+        setEnabled: (enabled: boolean) => Promise<void>;
+        setQuality: (quality: any) => Promise<void>;
+        setCaptureMode: (mode: any) => Promise<void>;
+        setScreen: (name: string) => Promise<void>;
+        flush: () => Promise<void>;
+        readonly isRecording: boolean;
+        readonly sessionId: string | null;
+    };
+    /**
+     * Performance monitoring namespace.
+     * Provides control over custom traces, screen load markers,
+     * and access to captured metrics.
+     * All methods are no-op if performance feature is disabled.
+     */
+    performance: {
+        /** Start a custom trace. Returns traceId or null. */
+        startTrace: (name: string) => string | null;
+        /** Stop a custom trace by ID. */
+        stopTrace: (traceId: string) => void;
+        /** Add a span to an active custom trace. */
+        addTraceSpan: (traceId: string, name: string, durationMs: number, data?: Record<string, unknown>) => void;
+        /** Attach a measurement to an active custom trace. */
+        addTraceMeasurement: (traceId: string, name: string, value: number, unit: string) => void;
+        /** Mark the start of a screen load. */
+        markScreenLoadStart: (screenName: string) => void;
+        /** Mark the end of a screen load. */
+        markScreenLoadEnd: (screenName: string) => void;
+        /** Set the current screen for context correlation. */
+        setCurrentScreen: (screenName: string) => void;
+        /** Forward navigation state changes for auto screen load detection. */
+        onNavigationStateChange: (state: unknown) => void;
+        /** Check if performance monitoring is active */
+        isActive: () => boolean;
+        /**
+         * Send a raw performance metric through the transport.
+         * Used for manual/simulated performance metrics.
+         */
+        sendMetric: (name: string, value: number, unit?: string, tags?: Record<string, string>) => void;
+    };
+    /**
+     * Unified Session namespace.
+     * Provides access to the unified SessionManager.
+     * Sessions auto-start on desktop connect.
+     */
+    session: {
+        readonly isActive: boolean;
+        readonly currentSessionId: string | null;
+        start: (metadata?: Record<string, unknown>) => boolean;
+        end: (reason?: "ended" | "timeout") => boolean;
+        emitEvent: (type: string, data?: Record<string, unknown>) => void;
+    };
+    /** Start a session (delegates to session namespace) */
+    startSession(metadata?: Record<string, unknown>): boolean;
+    /** Stop the current session (delegates to session namespace) */
+    stopSession(reason?: 'ended' | 'timeout'): boolean;
+    /**
+     * Report generation and export namespace.
+     *
+     * Usage:
+     * ```ts
+     * // Export with default preset
+     * const result = await ScaleBun.report.export();
+     *
+     * // Export with a named preset
+     * const result = await ScaleBun.report.export('engineering');
+     *
+     * // Export with custom options
+     * const result = await ScaleBun.report.export({ format: 'pdf', detail: 'detailed' });
+     * ```
+     *
+     * Requires an active desktop debug connection (`debug: true` in init).
+     */
+    report: {
+        /**
+         * Trigger a report export on the desktop application.
+         *
+         * @param presetOrOptions - Optional. A preset name ('executive', 'engineering', 'qa',
+         *   'forensic', 'journey', 'compact') or a SimplifiedExportOptions object.
+         * @returns Promise<ExportResult> with success status, file path, or error.
+         */
+        export: (presetOrOptions?: ExportPresetName | SimplifiedExportOptions) => Promise<ExportResult>;
+        /** Set SDK-wide privacy settings for report generation. */
+        setPrivacy: (config: PrivacyConfig) => void;
+        /** Set branding for exported reports. */
+        setBranding: (config: BrandingConfig) => void;
+        /** Get current privacy config. */
+        getPrivacy: () => PrivacyConfig;
+        /** Get current branding config. */
+        getBranding: () => BrandingConfig;
+    };
+    /**
+     * Set the React Navigation container ref for automatic screen detection.
+     *
+     * This is the **recommended** way to enable auto screen detection.
+     * Once set, the SDK automatically detects screen changes and feeds them
+     * to all subsystems (SessionManager, PerformanceFeature, ProfilerFeature).
+     * No per-screen `<ScaleBunScreen>` or `useScaleBunScreen()` needed.
+     *
+     * ```ts
+     * import { NavigationContainer } from '@react-navigation/native';
+     * import ScaleBun from '@scalebun/react-native';
+     *
+     * const navigationRef = React.createRef();
+     *
+     * function App() {
+     *   useEffect(() => {
+     *     ScaleBun.setNavigationRef(navigationRef);
+     *   }, []);
+     *
+     *   return (
+     *     <NavigationContainer ref={navigationRef}>
+     *       ...screens...
+     *     </NavigationContainer>
+     *   );
+     * }
+     * ```
+     */
+    setNavigationRef(ref: any): void;
+}
+/** Singleton Facade instance */
+declare const instance: ScaleBunFacade;
+export default instance;
+export { ScaleBunFacade };
+//# sourceMappingURL=ScaleBunFacade.d.ts.map