sitepong 0.2.0 → 0.2.2

package/dist/entries/rn.d.ts

@@ -0,0 +1,995 @@
+import React from 'react';
+
+/**
+ * Platform-agnostic storage interface.
+ * Concrete implementations live under src/platforms/{web,rn,node}.
+ */
+interface StorageAdapter {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+
+interface RecaptchaV3 {
+    ready: (cb: () => void) => void;
+    execute: (siteKey: string, options: {
+        action: string;
+    }) => Promise<string>;
+}
+interface HCaptcha {
+    execute: (siteKey: string, options?: {
+        async: boolean;
+    }) => Promise<{
+        response: string;
+    }>;
+    render: (container: string | HTMLElement, options: object) => string;
+}
+declare global {
+    interface Window {
+        grecaptcha?: RecaptchaV3;
+        hcaptcha?: HCaptcha;
+    }
+}
+
+interface TrackProperties {
+    [key: string]: unknown;
+}
+interface UserTraits {
+    email?: string;
+    name?: string;
+    firstName?: string;
+    lastName?: string;
+    phone?: string;
+    avatar?: string;
+    createdAt?: string;
+    [key: string]: unknown;
+}
+interface GroupTraits {
+    name?: string;
+    industry?: string;
+    employees?: number;
+    plan?: string;
+    [key: string]: unknown;
+}
+
+/**
+ * Remote Config Types
+ *
+ * Configuration fetched from SitePong servers to control SDK behavior
+ * without requiring npm updates.
+ */
+interface RemoteConfigFeatures {
+    /** Per-feature on/off toggles */
+    [key: string]: boolean;
+}
+interface RemoteConfigSampling {
+    /** Error sampling rate (0-1) */
+    errors?: number;
+    /** Analytics sampling rate (0-1) */
+    analytics?: number;
+    /** Replay sampling rate (0-1) */
+    replay?: number;
+    /** Performance sampling rate (0-1) */
+    performance?: number;
+}
+interface RemoteConfigTransport {
+    /** Flush interval in ms */
+    flushInterval?: number;
+    /** Max batch size */
+    maxBatchSize?: number;
+    /** Max retry attempts */
+    maxRetries?: number;
+}
+interface RemoteConfigAutocapture {
+    /** Enable click autocapture */
+    clicks?: boolean;
+    /** Enable form autocapture */
+    forms?: boolean;
+    /** Enable pageview autocapture */
+    pageviews?: boolean;
+    /** Enable RN app state tracking */
+    appState?: boolean;
+    /** Enable RN screen view tracking */
+    screenViews?: boolean;
+}
+interface RemoteConfig {
+    /** Feature toggles */
+    features: RemoteConfigFeatures;
+    /** Sampling rates */
+    sampling: RemoteConfigSampling;
+    /** Transport settings */
+    transport: RemoteConfigTransport;
+    /** Autocapture rules per platform */
+    autocapture: RemoteConfigAutocapture;
+    /** TTL in seconds before refetch */
+    ttl: number;
+    /** Minimum SDK version required (semver) */
+    minSdkVersion?: string;
+}
+
+/**
+ * Anonymous ID Management
+ * Generates and persists a unique ID for consistent flag evaluation
+ */
+declare function getAnonymousId(): string;
+/**
+ * Clear the anonymous ID
+ * Useful for testing or when user wants to reset their identity
+ */
+declare function clearAnonymousId(): void;
+/**
+ * Set a custom anonymous ID
+ * Useful when you want to use your own user identifier
+ */
+declare function setAnonymousId(id: string): void;
+
+/**
+ * SuperLink — deferred deep linking / smart links (OneLink/Branch-style).
+ *
+ * These types are platform-agnostic and shared between the web capture path
+ * and the React Native deferred-attribution path. They mirror the database
+ * schema (see supabase/migrations/*_superlink.sql): the redirect engine logs
+ * clicks + device fingerprints, and the mobile SDK matches on first launch to
+ * deliver the original deep link across the install gap.
+ */
+/**
+ * UTM parameters carried on a SuperLink. Keyed without the `utm_` prefix —
+ * the redirect URL's `utm_source`/`utm_medium`/… map to `source`/`medium`/…
+ * (self-contained so the SuperLink module has no cross-module dependencies).
+ */
+interface UtmParams {
+    source?: string;
+    medium?: string;
+    campaign?: string;
+    term?: string;
+    content?: string;
+}
+/** Platforms recognised by the redirect engine (matches superlink_platform). */
+type SuperLinkPlatform = 'ios' | 'android' | 'desktop' | 'other';
+/** How a deferred click was matched to an install (matches superlink_match_type). */
+type SuperLinkMatchType = 'referrer' | 'clipboard' | 'qr' | 'identity' | 'fingerprint' | 'none';
+/** Lifecycle event types (matches superlink_event_type). */
+type SuperLinkEventType = 'clicked' | 'installed' | 'opened' | 'converted';
+/**
+ * Configuration for the SuperLink client.
+ */
+interface SuperLinkConfig {
+    /** Redirect engine base URL. Defaults to the shared short domain. */
+    endpoint?: string;
+    /** Optional SuperLink app id (superlink_apps.id) for store-URL / AASA context. */
+    appId?: string;
+    /** Stable per-install id reported at match time (superlink_clicks.install_id). */
+    installId?: string;
+    /** Emit verbose diagnostics to the console. */
+    debug?: boolean;
+}
+/**
+ * Resolved deep link payload delivered to the app, whether captured directly
+ * on the web (inbound params), via a Universal Link / App Link open, or matched
+ * deferentially on first launch after an install.
+ */
+interface SuperLinkDeepLink {
+    /** In-app route, e.g. "/products/42" (superlink_links.deep_link_path). */
+    deep_link_path: string | null;
+    /** Arbitrary payload delivered on open (superlink_links.deep_link_data). */
+    deep_link_data: Record<string, unknown>;
+    /** Campaign params carried from the click URL. */
+    utm: UtmParams;
+    /** Affiliate / referral params carried from the click URL. */
+    referral: Record<string, unknown>;
+    /** Opaque click token, when known (superlink_clicks.click_id). */
+    click_id?: string | null;
+    /** How this link was resolved. */
+    match_type: SuperLinkMatchType;
+    /** 0..1 confidence — deterministic matches are 1, fingerprint matches lower. */
+    confidence: number;
+}
+/** Handler invoked with a resolved deferred deep link. */
+type DeferredDeepLinkHandler = (link: SuperLinkDeepLink) => void;
+/**
+ * Device fingerprint signals POSTed to /match. Mirrors the fingerprint columns
+ * on superlink_clicks. All fields are best-effort and optional.
+ */
+interface SuperLinkFingerprint {
+    platform: SuperLinkPlatform;
+    os?: string;
+    os_version?: string;
+    device_model?: string;
+    /** Browser name/UA, when known (web/desktop). */
+    browser?: string;
+    /** Coarse device class reported to the engine. */
+    device_type?: string;
+    /** Client IP, when the caller knows it (engine usually fills this in). */
+    ip?: string;
+    /** Raw user-agent string (web/desktop). */
+    user_agent?: string;
+    /** BCP-47 locale tag. */
+    language?: string;
+}
+/** Identity metadata for high-confidence matching against a click's metadata jsonb. */
+interface SuperLinkIdentityMetadata {
+    /** User-supplied email for matching. */
+    email?: string;
+    /** User-supplied phone number for matching. */
+    phone?: string;
+    /** App-level user id for matching. */
+    user_id?: string;
+    /** Generic id for matching. */
+    id?: string;
+    /** Arbitrary user-provided attributes for custom matching. */
+    custom?: Record<string, unknown>;
+}
+
+/**
+ * SuperLink deferred-deep-link registry — platform-agnostic.
+ *
+ * Holds the shared onDeferredDeepLink handler set, the cached last match, and
+ * the SuperLinkMatchResponse → SuperLinkDeepLink normaliser. Both the web/node
+ * recovery path (identify / completeFromScan) and the React Native first-launch
+ * attribution path emit through here so a single handler set sees every match.
+ */
+
+/**
+ * Register a handler fired when a deferred deep link is matched (first-launch
+ * attribution, identify(), or completeFromScan()). If a match already happened
+ * before registration, the handler is invoked immediately with the cached
+ * payload. Returns an unsubscribe fn.
+ */
+declare function onDeferredDeepLink(handler: DeferredDeepLinkHandler): () => void;
+/** The deferred deep link matched so far this process, if any. */
+declare function getMatchedDeepLink(): SuperLinkDeepLink | null;
+
+/**
+ * SuperLink URL parsing — platform-agnostic.
+ *
+ * Extracts the deep link payload encoded in a SuperLink URL: the path, any
+ * `~`-prefixed deep link data, UTM params, and `r_`-prefixed referral params.
+ * Works on both inbound web URLs and Universal Link / App Link opens. Uses the
+ * WHATWG `URL`, which is available on browser, RN (Hermes), and Node.
+ */
+
+/**
+ * Parse a SuperLink (or Universal/App Link) URL into a deep link payload.
+ * Returns null if the URL can't be parsed.
+ *
+ * Conventions carried in the query string:
+ *   - utm_*        → utm
+ *   - r_<key>      → referral (affiliate params)
+ *   - ~<key>       → deep_link_data (Branch-style)
+ *   - click_id     → click token
+ *   - $deep_link_path / dlp → explicit in-app route override
+ */
+declare function parseUniversalLink(url: string): SuperLinkDeepLink | null;
+
+interface SitePongConfig {
+    apiKey: string;
+    endpoint?: string;
+    environment?: string;
+    release?: string;
+    autoCapture?: boolean;
+    maxBatchSize?: number;
+    flushInterval?: number;
+    debug?: boolean;
+}
+interface ErrorContext {
+    user?: {
+        id?: string;
+        email?: string;
+        [key: string]: unknown;
+    };
+    tags?: Record<string, string>;
+    extra?: Record<string, unknown>;
+}
+interface SitePongInitConfig extends SitePongConfig {
+    /** Enable feature flags (default: false) */
+    enableFlags?: boolean;
+    /** Custom endpoint for flags API (default: uses main endpoint) */
+    flagsEndpoint?: string;
+    /** Analytics configuration */
+    analytics?: {
+        enabled?: boolean;
+        autocapturePageviews?: boolean;
+        autocaptureClicks?: boolean;
+        autocaptureForms?: boolean;
+        /** Full autocapture configuration (overrides individual autocapture flags) */
+        autocapture?: {
+            clicks?: boolean;
+            forms?: boolean;
+            pageviews?: boolean;
+            blockSelectors?: string[];
+            allowSelectors?: string[];
+        } | boolean;
+        maxBatchSize?: number;
+        flushInterval?: number;
+        eventsEndpoint?: string;
+    };
+    /** Fingerprint / device intelligence configuration */
+    fingerprint?: {
+        enabled?: boolean;
+        extendedSignals?: boolean;
+        visitorEndpoint?: string;
+    };
+    /** Performance monitoring configuration */
+    performance?: {
+        enabled?: boolean;
+        webVitals?: boolean;
+        navigationTiming?: boolean;
+        resourceTiming?: boolean;
+        capturePageLoadTimings?: boolean;
+        capturePageRenderTimings?: boolean;
+        excludedResourceUrls?: string[];
+        resourceNameSanitizer?: (url: string) => string;
+        sampleRate?: number;
+        flushInterval?: number;
+        performanceEndpoint?: string;
+    };
+    /** Session replay configuration — records a rolling buffer and only sends on error */
+    replay?: {
+        enabled?: boolean;
+        maskInputs?: boolean;
+        blockSelector?: string;
+        maskSelector?: string;
+        sampleRate?: number;
+        maxSessionDuration?: number;
+        flushInterval?: number;
+        replayEndpoint?: string;
+        /** Record network requests (XHR/fetch) in the replay timeline */
+        recordNetwork?: boolean;
+        /** Include request/response headers in network recording */
+        captureNetworkHeaders?: boolean;
+        /** Record console logs in the replay timeline */
+        recordConsole?: boolean;
+        /** Which console levels to record (default: all) */
+        consoleLevels?: Array<'log' | 'info' | 'warn' | 'error' | 'debug'>;
+        /** Rolling buffer duration in ms — how many seconds of replay to keep before an error (default: 20000) */
+        bufferDuration?: number;
+    };
+    /** Watchtower tap capture (web) — tap timeline events + masked screen templates */
+    watchtower?: {
+        enabled?: boolean;
+        /** Project ID sent as X-Project-ID on /api/taps requests (required) */
+        projectId?: string;
+        /** Override base endpoint for /api/taps + /api/taps/template (default: main endpoint) */
+        endpoint?: string;
+        /** Flush at this many buffered events (default: 50) */
+        maxBatchSize?: number;
+        /** Flush interval in ms (default: 10000) */
+        flushInterval?: number;
+        /** Extra CSS selector blocked out of the masked screen template */
+        blockSelector?: string;
+        /** CSS selector whose text is masked in the screen template */
+        maskSelector?: string;
+    };
+    /** Cron monitoring configuration */
+    crons?: {
+        enabled?: boolean;
+    };
+    /** Custom metrics configuration */
+    metrics?: {
+        enabled?: boolean;
+        flushInterval?: number;
+        maxBatchSize?: number;
+    };
+    /** Database query tracking configuration */
+    database?: {
+        enabled?: boolean;
+        slowQueryThreshold?: number;
+        redactParams?: boolean;
+    };
+    /** Production profiling configuration */
+    profiling?: {
+        enabled?: boolean;
+        sampleRate?: number;
+        maxDuration?: number;
+        flushInterval?: number;
+    };
+    /** Remote config options */
+    remoteConfig?: {
+        enabled?: boolean;
+    };
+    /** Storage adapter for caching (auto-detected if not provided) */
+    _storageAdapter?: StorageAdapter;
+}
+declare const initRN: (config: SitePongInitConfig) => void;
+declare const captureError: (error: Error | string, additionalContext?: ErrorContext) => void;
+declare const captureMessage: (message: string, level?: "info" | "warning" | "error", additionalContext?: ErrorContext) => void;
+declare const setContext: (context: ErrorContext) => void;
+declare const setUser: (user: ErrorContext["user"]) => void;
+declare const setTags: (tags: Record<string, string>) => void;
+declare const flush: () => Promise<void>;
+declare const isInitialized: () => boolean;
+declare const clearUser: () => void;
+declare const addBreadcrumb: (breadcrumb: {
+    type?: "default" | "http" | "navigation" | "ui" | "console" | "error";
+    category?: string;
+    message?: string;
+    level?: "fatal" | "error" | "warning" | "info" | "debug";
+    data?: Record<string, unknown>;
+}) => void;
+declare const setCurrentScreen: (name: string | undefined) => void;
+
+declare const getFlag: (key: string, defaultValue?: boolean) => boolean;
+declare const getAllFlags: () => Record<string, boolean>;
+declare const getVariant: (key: string, defaultValue?: string | null) => string | null;
+declare const getVariantPayload: <T = unknown>(key: string, defaultValue?: T | null) => T | null;
+declare const waitForFlags: () => Promise<void>;
+declare const areFlagsReady: () => boolean;
+declare const refreshFlags: () => Promise<void>;
+declare const track: (eventName: string, properties?: TrackProperties) => void;
+declare const identify$1: (userId: string, traits?: UserTraits) => void;
+declare const group: (groupId: string, traits?: GroupTraits) => void;
+declare const resetAnalytics: () => void;
+declare const getRemoteConfig: () => RemoteConfig | null;
+declare const isRemoteConfigFeatureEnabled: (key: string, defaultValue?: boolean) => boolean;
+declare const onRemoteConfigChange: (listener: (config: RemoteConfig) => void) => () => void;
+
+/**
+ * React Native Storage Adapter
+ *
+ * Wraps any AsyncStorage-compatible instance into the SDK's StorageAdapter interface.
+ */
+
+interface AsyncStorageLike {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+declare function createAsyncStorageAdapter(asyncStorage: AsyncStorageLike): StorageAdapter;
+
+/**
+ * React Navigation Tracker
+ *
+ * Integrates with React Navigation's navigationRef to track
+ * $screen_view events and navigation breadcrumbs.
+ */
+interface NavigationRef {
+    addListener: (event: string, callback: (...args: unknown[]) => void) => () => void;
+    getCurrentRoute: () => {
+        name: string;
+        params?: Record<string, unknown>;
+    } | undefined;
+}
+interface NavigationTrackerOptions {
+    /** Track screen view events (default: true) */
+    trackScreenViews?: boolean;
+    /** Add navigation breadcrumbs (default: true) */
+    addBreadcrumbs?: boolean;
+    /** Screen name filter — return null to skip tracking */
+    screenNameFilter?: (name: string) => string | null;
+}
+declare function createNavigationTracker(navigationRef: NavigationRef, options?: NavigationTrackerOptions): () => void;
+
+/**
+ * React Native Performance Manager
+ *
+ * Cold start timing and screen render tracking for RN apps.
+ */
+/**
+ * Call at the very top of your app entry point to capture cold start.
+ * Must be called before any async work.
+ */
+declare function markColdStart(): void;
+declare class RNPerformanceManager {
+    private screenRenderStarts;
+    /**
+     * Track cold start time from markColdStart() to now.
+     * Should be called once the app is interactive (e.g., in the root component's useEffect).
+     */
+    trackColdStart(): void;
+    /**
+     * Start tracking a screen render. Call before rendering starts.
+     */
+    startScreenRender(screenName: string): void;
+    /**
+     * End tracking a screen render. Call after rendering completes.
+     */
+    endScreenRender(screenName: string): number | null;
+    /**
+     * Track a screen render using a useEffect-friendly pattern.
+     * Returns a cleanup function.
+     */
+    trackScreenRender(screenName: string): () => void;
+}
+
+/**
+ * React Native Screen Recorder SDK Integration
+ *
+ * Two modes:
+ * 1. **On error (via provider)**: Recording starts automatically, keeps a 10s
+ *    rolling buffer. On error the buffer is flushed and attached to the error.
+ * 2. **Manual**: Call startScreenRecording / stopScreenRecording / flushScreenRecording
+ *    yourself. Keeps a 60s rolling buffer by default.
+ */
+interface ScreenRecordingConfig {
+    /** Enable screen recording (default: false) */
+    enabled?: boolean;
+    /** Frames per second (default: 1) */
+    fps?: number;
+    /** Video quality preset */
+    quality?: 'low' | 'standard' | 'high';
+    /** Sample rate 0-1: what fraction of sessions to record (default: 1.0) */
+    sampleRate?: number;
+    /** Max recording duration in ms (default: 60 min) */
+    maxDuration?: number;
+    /**
+     * Rolling buffer duration in ms — how much video to keep.
+     * - On-error mode (via provider): default 10_000 (10 seconds)
+     * - Manual mode: default 60_000 (60 seconds)
+     */
+    bufferDuration?: number;
+}
+/**
+ * Start screen recording manually.
+ * Recording runs in a 60s rolling buffer. Call flushScreenRecording() to upload.
+ */
+declare function startScreenRecording(apiKey: string, endpoint: string, sessionId: string, config?: Omit<ScreenRecordingConfig, 'enabled'>): boolean;
+/**
+ * Stop screen recording and discard the buffer.
+ */
+declare function stopScreenRecording(): void;
+/**
+ * Flush the rolling buffer to the server.
+ * In on-error mode this is called automatically by the error handler.
+ * In manual mode, call this yourself to upload the buffer.
+ */
+declare function flushScreenRecording(): Promise<void>;
+/**
+ * @deprecated Use flushScreenRecording() instead.
+ */
+declare const flushScreenRecordingOnError: typeof flushScreenRecording;
+/**
+ * Check if screen recording is currently active.
+ */
+declare function isScreenRecording(): boolean;
+
+/**
+ * SitePong React Native Provider
+ *
+ * Mirrors the react/provider.tsx pattern with RN-specific setup.
+ */
+
+interface SitePongRNContextValue {
+    isInitialized: boolean;
+    performanceManager: RNPerformanceManager | null;
+}
+interface SitePongRNProviderProps {
+    /** API key in format: sp_live_xxx or sp_test_xxx */
+    apiKey: string;
+    /** Additional configuration options */
+    config?: Omit<SitePongInitConfig, 'apiKey'>;
+    /** AsyncStorage instance for persistence */
+    asyncStorage?: AsyncStorageLike;
+    /** React Navigation ref for screen tracking */
+    navigationRef?: NavigationRef;
+    /** Enable network request interception (default: true) */
+    trackNetwork?: boolean;
+    /** Enable app state tracking (default: true) */
+    trackAppState?: boolean;
+    /** Enable error handler setup (default: true) */
+    captureErrors?: boolean;
+    /** Screen recording configuration — records rolling buffer, only sends on error */
+    screenRecording?: ScreenRecordingConfig;
+    /** Native device token (APNs hex string or FCM registration token) for direct push delivery */
+    devicePushToken?: string;
+    /** Device platform — required when using devicePushToken */
+    devicePlatform?: 'ios' | 'android';
+    /** APNs environment for push notifications */
+    pushEnvironment?: 'sandbox' | 'production';
+    /**
+     * @deprecated Ignored. Associate via `POST /api/push/tokens/associate`
+     * from your backend using a `sp_push_xxx` key — see the SDK README.
+     */
+    pushUserId?: string;
+    children: React.ReactNode;
+}
+declare function SitePongRNProvider({ apiKey, config, asyncStorage, navigationRef, trackNetwork, trackAppState, captureErrors, screenRecording, devicePushToken, devicePlatform, pushEnvironment, pushUserId, children, }: SitePongRNProviderProps): React.ReactElement;
+declare function useSitePongRNContext(): SitePongRNContextValue;
+
+/**
+ * React Native Hooks
+ *
+ * RN-specific hooks + re-exported base hooks.
+ */
+
+/**
+ * Track a screen render automatically via useEffect.
+ */
+declare function useScreenTrack(screenName: string): void;
+/**
+ * Track app state with a reactive hook.
+ */
+declare function useAppState(): string;
+/**
+ * Access remote config with reactive updates.
+ */
+declare function useRemoteConfig(): RemoteConfig | null;
+/**
+ * Track screen render performance. Returns duration when render completes.
+ */
+declare function useRNPerformance(screenName: string): {
+    duration: number | null;
+};
+
+/**
+ * React Native Device Info
+ *
+ * Collects device information using only RN built-in APIs.
+ * Zero external dependencies — uses only Platform and Dimensions.
+ */
+interface RNDeviceInfo {
+    platform: 'ios' | 'android';
+    osVersion?: string;
+    deviceName?: string;
+    deviceBrand?: string;
+    deviceModel?: string;
+    appVersion?: string;
+    appBuildNumber?: string;
+    screenWidth?: number;
+    screenHeight?: number;
+    screenScale?: number;
+    isEmulator?: boolean;
+    deviceId?: string;
+}
+declare function collectDeviceInfo(): RNDeviceInfo;
+/** @deprecated No-op, returns null. Kept for API compatibility. */
+declare function fetchPersistentDeviceId(): Promise<string | null>;
+/** @deprecated No-op, returns null. Kept for API compatibility. */
+declare function fetchNativeDeviceSignals(): Promise<null>;
+
+/**
+ * React Native Error Handler
+ *
+ * Enhanced ErrorUtils.setGlobalHandler() + Promise rejection tracking.
+ * Returns a teardown function.
+ */
+interface RNErrorHandlerOptions {
+    /** Capture fatal errors (default: true) */
+    captureFatal?: boolean;
+    /** Capture non-fatal errors (default: true) */
+    captureNonFatal?: boolean;
+    /** Capture unhandled promise rejections (default: true) */
+    capturePromiseRejections?: boolean;
+}
+declare function setupRNErrorHandler(options?: RNErrorHandlerOptions): () => void;
+
+/**
+ * Watchtower tap autocapture — React Native JS layer (spec §4.2).
+ *
+ * This file is intentionally MINIMAL. The hot path — capturing taps, taking
+ * screenshots, perceptual hashing, redaction, and upload — all happens in the
+ * shared native engine `WatchtowerCore` (spec §3), reached through the thin
+ * Expo bridge in `@sitepong/screen-recorder`. capture-core's JS dHash is NOT on
+ * the RN runtime path; the engine hashes natively.
+ *
+ * JS's only jobs here:
+ *   (a) start the native engine with apiKey/projectId/endpoint + platform
+ *       "react-native-ios",
+ *   (b) feed it React-Navigation route names by subscribing to the existing
+ *       navigation tracker (navigation.ts) and calling native setScreen on each
+ *       $screen_view.
+ *
+ * Element identity comes for free: RN maps a component's `testID` to the iOS
+ * view's `accessibilityIdentifier`, which the §3.1 swizzle reads natively.
+ */
+
+interface WatchtowerConfig {
+    /** API key (demo uses key_demo). */
+    apiKey: string;
+    /** Project id (demo uses proj_demo). */
+    projectId: string;
+    /** Ingest endpoint, e.g. http://localhost:8787. */
+    endpoint: string;
+    /** Screenshot sample rate (passed through to the engine; default 0.1). */
+    sampleRate?: number;
+    /**
+     * Platform stamped on every tap event. Defaults to "react-native-ios" and
+     * should not normally be overridden — it is what proves "one engine, two
+     * apps" at the wire level.
+     */
+    platform?: string;
+    /**
+     * Initial user identity, stamped as distinct_id on every event. Update it
+     * later (e.g. after login) with setWatchtowerUser(). Pass the same value
+     * you give the SDK's identify() so users line up across pipelines.
+     */
+    distinctId?: string;
+}
+/**
+ * Start the shared native capture engine for React Native. Idempotent.
+ * Forwards directly to `Watchtower.start(...)` in WatchtowerCore (§3) via the
+ * native bridge — no capture logic in JS.
+ */
+declare function startWatchtower(config: WatchtowerConfig): void;
+/**
+ * Set user identity — stamped as distinct_id on every subsequent event. Call
+ * this wherever you call the SDK's identify(), with the same id.
+ */
+declare function setWatchtowerUser(distinctId: string | null): void;
+/**
+ * The engine's current capture session id (null when not running). Attach it
+ * to error reports/analytics — it is the key that joins an error to its
+ * Watchtower session for replay.
+ */
+declare function getWatchtowerSessionId(): string | null;
+/** Stop the engine; native side flushes pending taps. */
+declare function stopWatchtower(): void;
+/**
+ * Subscribe to React-Navigation screen changes and feed each route name to the
+ * native engine via setScreen. Built on the EXISTING navigation tracker
+ * (navigation.ts): we hook its per-screen-change callback (`screenNameFilter`)
+ * to forward the resolved screen name to native, then return it unchanged so
+ * the normal $screen_view tracking still fires. Returns an unsubscribe fn.
+ */
+declare function subscribeNavigationToWatchtower(navigationRef: NavigationRef): () => void;
+interface WatchtowerProviderProps {
+    config: WatchtowerConfig;
+    /** React Navigation ref — required to feed route names to the engine. */
+    navigationRef: NavigationRef;
+    children?: React.ReactNode;
+}
+/**
+ * Provider that starts the native engine on mount and wires React-Navigation
+ * screen views to native setScreen. Renders children unchanged.
+ */
+declare function WatchtowerProvider(props: WatchtowerProviderProps): React.ReactElement;
+
+/**
+ * React Native Network Interception
+ *
+ * XHR monkey-patch for request tracking + breadcrumbs.
+ * RN fetch is XHR internally, so intercepting XMLHttpRequest captures all network.
+ */
+interface NetworkInterceptionOptions {
+    /** Track request/response as breadcrumbs (default: true) */
+    addBreadcrumbs?: boolean;
+    /** URL patterns to ignore (e.g., SitePong's own endpoints) */
+    ignoreUrls?: (string | RegExp)[];
+    /** Max breadcrumb data size in bytes (default: 1024) */
+    maxDataSize?: number;
+}
+declare function setupNetworkInterception(options?: NetworkInterceptionOptions): () => void;
+
+/**
+ * React Native Autocapture Module
+ *
+ * Tracks AppState changes (foreground/background/inactive) automatically.
+ */
+interface RNAutocaptureOptions {
+    /** Track app state changes (default: true) */
+    trackAppState?: boolean;
+}
+declare class RNAutocaptureModule {
+    private options;
+    private appStateSubscription;
+    private currentAppState;
+    constructor(options?: RNAutocaptureOptions);
+    start(): void;
+    stop(): void;
+    private setupAppStateTracking;
+}
+
+/**
+ * SQLite Query Tracker for expo-sqlite
+ *
+ * Wraps an expo-sqlite database handle to intercept and time all queries.
+ * Slow queries are reported as analytics events and breadcrumbs.
+ */
+interface TrackedDatabaseOptions {
+    /** Threshold in ms — queries slower than this are tracked (default: 100) */
+    slowQueryThreshold?: number;
+    /** If true, track every query regardless of duration (default: false) */
+    trackAll?: boolean;
+}
+/** Minimal interface matching expo-sqlite's SQLiteDatabase */
+interface SQLiteDatabase {
+    execAsync(sql: string): Promise<void>;
+    runAsync(sql: string, ...params: unknown[]): Promise<{
+        changes: number;
+        lastInsertRowId: number;
+    }>;
+    getAllAsync(sql: string, ...params: unknown[]): Promise<unknown[]>;
+    getFirstAsync(sql: string, ...params: unknown[]): Promise<unknown | null>;
+    execSync(sql: string): void;
+    runSync(sql: string, ...params: unknown[]): {
+        changes: number;
+        lastInsertRowId: number;
+    };
+    getAllSync(sql: string, ...params: unknown[]): unknown[];
+    getFirstSync(sql: string, ...params: unknown[]): unknown | null;
+    [key: string]: unknown;
+}
+/**
+ * Wrap an expo-sqlite database with query timing and tracking.
+ *
+ * Returns a proxy that intercepts all query methods. Use it exactly like the
+ * original database — same API, same return values.
+ *
+ * @example
+ * ```ts
+ * import { createTrackedDatabase } from 'sitepong/react-native';
+ * import * as SQLite from 'expo-sqlite';
+ *
+ * const db = SQLite.openDatabaseSync('myapp.db');
+ * const trackedDb = createTrackedDatabase(db, { slowQueryThreshold: 100 });
+ * const users = trackedDb.getAllSync('SELECT * FROM users WHERE active = 1');
+ * ```
+ */
+declare function createTrackedDatabase<T extends SQLiteDatabase>(db: T, options?: TrackedDatabaseOptions): T;
+
+/**
+ * Push Notification & Live Activity token registration for React Native.
+ *
+ * Registers Expo push tokens and APNs Live Activity tokens with the
+ * SitePong ingest server for remote push notification delivery.
+ *
+ * For Live Activities, prefer the turnkey `@sitepong/expo-live-activity`
+ * package — it ships a built-in SwiftUI widget template (SF Symbols,
+ * custom progress bar with sliding icon, visibility-driven slots) and
+ * forwards push tokens to the registration functions in this file
+ * automatically. Use the lower-level `registerLiveActivityToken` and
+ * `registerPushToStartToken` exports below only if you author your own
+ * iOS Widget Extension and `ActivityAttributes` struct in Swift.
+ *
+ * ## User attribution (two-step)
+ *
+ * These register* functions only store (project_id, token, device_id). They
+ * deliberately do not accept or send a user_id — publishable SDK keys are
+ * extractable from compiled apps, so letting the client attach arbitrary
+ * user_ids would let a leaked key shadow-subscribe to another user's pushes.
+ *
+ * After the user authenticates with your backend, have your backend call
+ * `POST /api/push/tokens/associate` (authenticated with your `sp_push_xxx`
+ * server key) to bind the token to the user_id.
+ *
+ * @since 0.1.0
+ */
+interface PushEnvironmentOptions {
+    environment: 'sandbox' | 'production';
+}
+/**
+ * Register an Expo push token for receiving regular push notifications.
+ *
+ * To attach this token to an authenticated user, have your backend call
+ * `POST https://api.sitepong.com/api/push/tokens/associate` with
+ * `Authorization: Bearer sp_push_xxx` and body `{ token, user_id }`.
+ */
+declare function registerPushToken(token: string, options: PushEnvironmentOptions): void;
+/**
+ * Register a native device token (APNs or FCM) for direct push delivery.
+ * This bypasses Expo and sends directly to Apple/Google.
+ *
+ * @param token - The raw device token (hex string for APNs, FCM registration token for Android)
+ * @param options - Platform and environment. `userId` is accepted but ignored
+ *   — see the two-step attribution note at the top of this file.
+ */
+declare function registerDeviceToken(token: string, options: {
+    platform: 'ios' | 'android';
+    environment: 'sandbox' | 'production';
+    /** @deprecated Ignored. Associate via POST /api/push/tokens/associate from your backend. */
+    userId?: string;
+}): void;
+/**
+ * Register a running Live Activity's push token for remote updates.
+ */
+declare function registerLiveActivityToken(activityType: string, activityId: string, pushToken: string, options: PushEnvironmentOptions): void;
+/**
+ * Register a push-to-start token for remotely launching Live Activities (iOS 17.2+).
+ */
+declare function registerPushToStartToken(activityType: string, pushToStartToken: string, options: PushEnvironmentOptions): void;
+/**
+ * Mark a Live Activity as ended (deactivates its token).
+ */
+declare function endLiveActivity(activityType: string, activityId: string): void;
+
+interface WidgetSyncOptions {
+    refreshInterval?: number;
+}
+declare function syncWidgets(options?: WidgetSyncOptions): Promise<void>;
+declare function updateWidgetData(data: Record<string, unknown>): Promise<void>;
+declare function triggerWidgetRefresh(): void;
+declare function stopWidgetSync(): void;
+
+/**
+ * SuperLink — React Native deferred deep linking / attribution.
+ *
+ * On first launch, the SDK resolves the deep link the user originally clicked
+ * before the app was installed ("deferred deep link"), bridging the install
+ * gap that ordinary Universal Links / App Links can't cross:
+ *
+ *   - Android: read the Play Install Referrer to recover the deterministic
+ *     `click_id` the redirect engine stamped on the Play Store URL.
+ *   - iOS: attempt a clipboard read for a click token handed off by the
+ *     interstitial (Safari → App Store → app).
+ *   - Both: gather a minimal device fingerprint (UA/model/os/os_version/locale)
+ *     as a probabilistic fallback.
+ *
+ * It then POSTs /match and, on a hit, invokes any registered
+ * onDeferredDeepLink handler with the resolved payload.
+ *
+ * For apps that are ALREADY installed, use parseUniversalLink() +
+ * createSuperLinkListener() to handle direct opens and report `opened` events.
+ *
+ * Every native dependency is loaded through guarded optional requires, exactly
+ * like the rest of the RN SDK — so an app that hasn't installed
+ * `react-native-play-install-referrer` / `expo-clipboard` still builds and the
+ * SDK degrades to fingerprint-only matching.
+ */
+
+/**
+ * Configure SuperLink and run deferred-attribution on first launch.
+ *
+ * Idempotent: the /match round-trip runs at most once per process. Safe to
+ * call from app bootstrap. Returns the matched deep link, or null.
+ *
+ * Supports identity metadata extraction from the clipboard or from passed options,
+ * enabling deterministic matching when the user has provided email/phone/custom
+ * attributes on the source link.
+ */
+declare function initSuperLinkRN(config?: SuperLinkConfig, identityOverride?: SuperLinkIdentityMetadata): Promise<SuperLinkDeepLink | null>;
+/**
+ * Recover a deferred deep link AFTER the user provides an email/phone (or other
+ * identity) at signup. POSTs /match with { identity, install_id, fingerprint }
+ * so the engine matches the identity against an unmatched click's metadata.
+ * Fires onDeferredDeepLink on a hit. Returns the resolved deep link, or null.
+ */
+declare function identify(identity: SuperLinkIdentityMetadata): Promise<SuperLinkDeepLink | null>;
+/**
+ * Complete attribution from a scanned QR payload. POSTs /match with
+ * { qr_token: scanned, install_id } — the raw scanned string is passed straight
+ * through, and the engine parses a click-token URL (/c/<id>), a raw click_id, a
+ * link URL (pongl.ink/<slug>), or a bare <slug>. Fires onDeferredDeepLink on a
+ * hit. Returns the resolved deep link, or null.
+ */
+declare function completeFromScan(scanned: string): Promise<SuperLinkDeepLink | null>;
+/**
+ * Handle a direct open of an already-installed app via a Universal Link /
+ * App Link URL: parse the payload and report an `opened` event. Returns the
+ * parsed deep link (does NOT fire onDeferredDeepLink handlers — that channel is
+ * reserved for deferred first-launch matches).
+ */
+declare function handleUniversalLink(url: string): SuperLinkDeepLink | null;
+interface LinkingLike {
+    getInitialURL(): Promise<string | null>;
+    addEventListener(type: 'url', handler: (event: {
+        url: string;
+    }) => void): {
+        remove(): void;
+    } | void;
+    removeEventListener?(type: 'url', handler: (event: {
+        url: string;
+    }) => void): void;
+}
+/**
+ * Wire RN Linking to handle already-installed opens. Processes the cold-start
+ * URL (getInitialURL) and subsequent warm opens, calling `onLink` with the
+ * parsed payload and reporting `opened` events. Returns an unsubscribe fn.
+ *
+ * Pass your app's `Linking` module from 'react-native' (kept as a param so this
+ * file has no hard dependency on the Linking native module at import time).
+ */
+declare function createSuperLinkListener(Linking: LinkingLike, onLink: DeferredDeepLinkHandler): () => void;
+/**
+ * Report a downstream conversion (signup, purchase, ...) back to the redirect
+ * engine, attributed to the matched click when available.
+ */
+declare function reportConversion(props?: Record<string, unknown>): Promise<boolean>;
+
+/**
+ * React Native entry point for SitePong SDK.
+ *
+ * Installs the RN EnvironmentAdapter first, then re-exports the RN public
+ * API (SitePongRNProvider + RN-safe SDK functions). Consumers should use
+ * `initRN()` (not `init()`), which does not touch DOM APIs.
+ *
+ * Because this module installs the env adapter at import time, simply
+ * importing `sitepong/react-native` is enough to make shared SDK modules
+ * route all environment access through the RN adapter.
+ */
+
+/**
+ * Advanced: inject a StorageAdapter (e.g. AsyncStorage/MMKV-backed) after app boot.
+ * Typically called by SitePongRNProvider.
+ */
+declare function setRNStorage(storage: StorageAdapter | null): void;
+
+export { type AsyncStorageLike, type DeferredDeepLinkHandler, type ErrorContext, type GroupTraits, type NavigationRef, type NavigationTrackerOptions, type NetworkInterceptionOptions, RNAutocaptureModule, type RNAutocaptureOptions, type RNDeviceInfo, type RNErrorHandlerOptions, RNPerformanceManager, type RemoteConfig, type ScreenRecordingConfig, type SitePongConfig, type SitePongInitConfig, SitePongRNProvider, type SitePongRNProviderProps, type SuperLinkConfig, type SuperLinkDeepLink, type SuperLinkEventType, type SuperLinkFingerprint, type SuperLinkIdentityMetadata, type SuperLinkMatchType, type SuperLinkPlatform, type TrackProperties, type TrackedDatabaseOptions, type UserTraits, type WatchtowerConfig, WatchtowerProvider, type WatchtowerProviderProps, type WidgetSyncOptions, addBreadcrumb, areFlagsReady, captureError, captureMessage, clearAnonymousId, clearUser, collectDeviceInfo, completeFromScan, createAsyncStorageAdapter, createNavigationTracker, createSuperLinkListener, createTrackedDatabase, endLiveActivity, fetchNativeDeviceSignals, fetchPersistentDeviceId, flush, flushScreenRecording, flushScreenRecordingOnError, getAllFlags, getAnonymousId, getFlag, getMatchedDeepLink, getRemoteConfig, getVariant, getVariantPayload, getWatchtowerSessionId, group, handleUniversalLink, identify$1 as identify, initRN, initSuperLinkRN, isInitialized, isRemoteConfigFeatureEnabled, isScreenRecording, markColdStart, onDeferredDeepLink, onRemoteConfigChange, parseUniversalLink, refreshFlags, registerDeviceToken, registerLiveActivityToken, registerPushToStartToken, registerPushToken, reportConversion, resetAnalytics, setAnonymousId, setContext, setCurrentScreen, setRNStorage, setTags, setUser, setWatchtowerUser, setupNetworkInterception, setupRNErrorHandler, startScreenRecording, startWatchtower, stopScreenRecording, stopWatchtower, stopWidgetSync, subscribeNavigationToWatchtower, identify as superlinkIdentify, syncWidgets, track, triggerWidgetRefresh, updateWidgetData, useAppState, useRNPerformance, useRemoteConfig, useScreenTrack, useSitePongRNContext, waitForFlags };