@lucida-analytics/react-native 0.0.0-stage → 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,838 @@
+import { Storage, Transport, Core, WireEvent, FlagValue, Props, FlagResult, Intervention, FlagDefinition, EvalContext } from '@lucida-analytics/sdk-core';
+export { FlagResult, FlagValue, Intervention } from '@lucida-analytics/sdk-core';
+import * as react from 'react';
+import { ReactNode } from 'react';
+
+/**
+ * First-open install attribution for `$app_installed`. Native contract (LucidaReplay.installInfo, a promise method):
+ * Android resolves `{platform: "android", referrer?, clickTs?, beginTs?}` (Google Play Install Referrer),
+ * iOS resolves `{platform: "ios", token?}` (AdServices `AAAttribution` token). The iOS token is resolved here over `fetch`.
+ */
+interface InstallInfo {
+    platform: "android" | "ios";
+    referrer?: string | null;
+    clickTs?: number;
+    beginTs?: number;
+    token?: string | null;
+}
+interface NativeInstallModule {
+    installInfo?(): Promise<InstallInfo | null>;
+}
+type InstallProps = Record<string, unknown>;
+/** Play Install Referrer string (`utm_source=..&gclid=..`) plus timestamps (seconds) -> `$app_installed` props. */
+declare function installReferrerProps(raw: string, clickTs?: number, beginTs?: number): InstallProps;
+/** Apple Search Ads attribution response -> `$app_installed` props; null/garbage -> store only. */
+declare function appStoreInstallProps(json: unknown): InstallProps;
+interface InstallDeps {
+    fetch: typeof fetch;
+    retryDelayMs?: number;
+    attempts?: number;
+    timeoutMs?: number;
+}
+/** Resolves install props from the native module; never rejects (any failure -> `{}` or store only). */
+declare function resolveInstallProps(native: () => Promise<InstallInfo | null>, d: InstallDeps): Promise<InstallProps>;
+
+/** The slice of @react-native-async-storage/async-storage the SDK uses (inject the real module). */
+interface AsyncStorageLike {
+    multiGet(keys: readonly string[]): Promise<ReadonlyArray<readonly [string, string | null]>>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+    /** The real module has it; used to find spilled replay chunks (`lc_replay.<id>`) to hydrate. Without it they are not reloaded after a restart. */
+    getAllKeys?(): Promise<readonly string[]>;
+}
+/** Keys the SDK persists; hydrated up front because the core's Storage port is synchronous. */
+declare const PERSISTED_KEYS: readonly ["lc_identity", "lc_session", "lc_props", "lc_groups", "lc_consent", "lc_flags", "lc_offline", "lc_app_version", "lc_guide_seen", "lc_person_identified"];
+/** Memory cache hydrated from AsyncStorage with write-behind. Await `ready` before use. */
+declare function asyncStorageAdapter(as: AsyncStorageLike): {
+    storage: Storage;
+    ready: Promise<void>;
+};
+/** In-memory storage (tests, no AsyncStorage injected). */
+declare function memoryStorage(): Storage;
+/** fetch-based transport. No gzip: React Native has no CompressionStream; batches are small. */
+declare function fetchTransport(fetchImpl: typeof fetch, timeoutMs?: number): Transport;
+/** Sends batches of at most `max` events: a larger `{api_key, batch, sent_at}` body is split; the first failing status wins. */
+declare function splitBatches(inner: Transport, max: number): Transport;
+type AppStateStatus = "active" | "background" | "inactive" | "unknown" | "extension";
+/** The slice of react-native's AppState the SDK uses. */
+interface AppStateLike {
+    currentState?: AppStateStatus;
+    addEventListener(type: "change", fn: (s: AppStateStatus) => void): {
+        remove(): void;
+    };
+}
+/** Maps foreground/background transitions to callbacks; returns an unsubscribe. */
+declare function appLifecycle(app: AppStateLike, h: {
+    onForeground(): void;
+    onBackground(): void;
+}): () => void;
+/** Aborts nothing (a custom transport owns its sockets) but stops waiting after `ms`: the send then counts as a network failure and retries. */
+declare function withTimeout(inner: Transport, ms: number): Transport;
+/** Port: at-rest encryption for the persisted queue. `nativeQueueCipher()` backs it with the iOS Keychain / Android Keystore. */
+interface QueueCipher {
+    encrypt(plain: string): string;
+    /** null when the value cannot be decrypted (key rotated, corrupt): the queue then starts empty. */
+    decrypt(cipher: string): string | null;
+}
+/** Decorator: values under `keys` (or a key starting with one of `prefixes`) are stored encrypted, everything else passes through. */
+declare function encryptedStorage(inner: Storage, cipher: QueueCipher, keys: readonly string[], prefixes?: readonly string[]): Storage;
+
+interface RageTapConfig {
+    enabled?: boolean;
+    minTaps?: number;
+    windowMs?: number;
+    radius?: number;
+}
+/**
+ * Element autocapture (`$autocapture` taps and changes). Off by default.
+ * Privacy: text-field values are never collected; `propsAllowList` is the only way extra props leave the device.
+ */
+interface AutocaptureConfig {
+    enabled?: boolean;
+    ignoreLabels?: readonly string[];
+    maxElements?: number;
+    propsAllowList?: readonly string[];
+    /** A component with this prop set (`<View lucidaNoCapture />`) and its subtree are never captured. */
+    noCaptureProp?: string;
+    /** Prop read as the element's label, after `accessibilityLabel`. Default `testID`. */
+    customLabelProp?: string;
+    rageTap?: RageTapConfig;
+}
+/** One element in the touched component's ancestor chain (nearest first). */
+interface TapElement {
+    name: string;
+    label?: string | undefined;
+    noCapture?: boolean | undefined;
+    isInput?: boolean | undefined;
+    props?: Record<string, string> | undefined;
+}
+interface Autocapture {
+    tap(chain: readonly TapElement[], x: number, y: number): void;
+    change(chain: readonly TapElement[]): void;
+    readonly config: AutocaptureConfig;
+}
+declare function createAutocapture(core: Core, config: AutocaptureConfig, now?: () => number): Autocapture;
+/** The slice of a React fiber the chain builder reads. */
+interface FiberLike {
+    type?: unknown;
+    memoizedProps?: Record<string, unknown> | null;
+    return?: FiberLike | null;
+}
+/** Touch event shape from a `<View onTouchEnd>`; `_targetInst` is React's own record of the touched fiber. */
+interface TouchEventLike {
+    nativeEvent?: {
+        pageX?: number;
+        pageY?: number;
+    };
+    _targetInst?: FiberLike | null;
+}
+/** Put the result on your root view: `<View onTouchEnd={touchHandler(client.autocapture)} />`. */
+declare function touchHandler(ac: Autocapture): (e: TouchEventLike) => void;
+/**
+ * Builds the ancestor chain from a touched fiber (`event._targetInst`). Only host components and composites that carry
+ * a label (`accessibilityLabel` or `customLabelProp`) or the no-capture prop are kept, so the chain stays readable.
+ * Text-field values are never read: inputs contribute their name only.
+ */
+declare function chainFromFiber(start: FiberLike | null | undefined, cfg: AutocaptureConfig): TapElement[];
+
+interface GuideButton {
+    label: string;
+    /** next | back | dismiss | link | event (start_tour behaves like next on mobile). */
+    action: string;
+    url?: string;
+    event?: string;
+}
+interface GuideStep {
+    id: string;
+    title?: string | null;
+    body?: string | null;
+    buttons?: GuideButton[] | null;
+    /** Anchor view: the `testID` of a `<GuideAnchor>` (tooltip, hotspot and tour steps; web selectors are ignored). */
+    native_id?: string | null;
+    placement?: string | null;
+    /** How long to wait for the anchor (ms, default 3000, max 15000) before showing the step unanchored. */
+    wait_ms?: number | null;
+}
+/** Where an anchored step points. `hotspot`: a pulsing dot on the view opens the step. */
+interface GuideAnchorSpec {
+    nativeId: string;
+    placement?: string;
+    waitMs: number;
+    hotspot: boolean;
+}
+/** A guide as `GET /v1/guides` serves it. */
+interface MobileGuide {
+    id: string;
+    name: string;
+    kind: string;
+    steps: GuideStep[];
+    conditions: Record<string, unknown>;
+    /** A draft served to a QA user: no targeting, shown once per launch, no events. */
+    preview?: boolean;
+    /** Resolved appearance (the gateway merges the project theme in): tokens, dark.tokens, theme_mode, font_family. */
+    appearance?: Record<string, unknown> | null;
+    /** A workflow queued this guide for this person (gateway): it goes first and skips sampling. */
+    queued?: boolean;
+}
+/** What `<LucidaGuides />` draws. */
+interface GuideView {
+    guide: MobileGuide;
+    step: number;
+    buttons: GuideButton[];
+    /** Set when this step points at a view. */
+    anchor?: GuideAnchorSpec;
+}
+interface GuidesService {
+    /** Fetches the live guides (needs analytics consent), then re-evaluates the current screen. */
+    reload(): Promise<void>;
+    /** The app moved to `name`: show the first eligible guide if none is on screen. */
+    show(name: string): void;
+    current(): GuideView | null;
+    subscribe(cb: (v: GuideView | null) => void): () => void;
+    /** The tapped button, or null when the person closed the step (a dismissal). */
+    act(button: GuideButton | null): void;
+    /** How https links open (the view wires Linking.openURL). */
+    setOpener(fn: (url: string) => void): void;
+    /** The view could not find the current step's anchor in time (emits `$guide_target_missing`; it then shows unanchored). */
+    targetMissing(): void;
+}
+interface GuidesDeps {
+    core: Core;
+    fetch: typeof fetch;
+    apiHost: string;
+    apiKey: string;
+    flag(key: string): boolean;
+    random?: () => number;
+}
+declare function matches(screen: string, pattern: string, how: string): boolean;
+declare function guideButtons(g: MobileGuide, i: number): GuideButton[];
+/** Project-wide exclusions matched against the screen name: `*` globs, the same patterns the web matches against URLs. */
+declare function screenExcluded(screen: string, patterns: readonly string[]): boolean;
+/** The anchor of step `i`, when its guide kind anchors and the step names a view. */
+declare function guideAnchor(g: MobileGuide, i: number): GuideAnchorSpec | undefined;
+declare function createGuides(d: GuidesDeps): GuidesService;
+
+/** A `beforeSend` hook: return the (possibly amended) event, or null to drop it. */
+type BeforeSend = (event: WireEvent) => WireEvent | null;
+type PersonProfiles = "always" | "identified_only" | "never";
+/**
+ * Runs hooks in order; each sees the previous hook's output and null stops the chain (the event is dropped).
+ * A hook that throws is logged and skipped: the event continues unchanged (as it was before that hook).
+ */
+declare function runHooks(hooks: readonly BeforeSend[], event: WireEvent, log: (...a: unknown[]) => void): WireEvent | null;
+/** Keeps roughly `rate` (0..1) of events and stamps survivors with `$sample_rate`. Compose it with your own filter hook. */
+declare function sampleHook(rate: number, random?: () => number): BeforeSend;
+/** `personProfiles` state: `identified_only` flips to processing on the first identify/alias/group/person-property write. */
+declare class PersonMode {
+    readonly mode: PersonProfiles;
+    private readonly storage;
+    private identified;
+    constructor(mode: PersonProfiles, storage: Storage);
+    get blocksPersonWrites(): boolean;
+    markIdentified(): void;
+    /** True when an event of this name should carry `$process_person_profile: false`. */
+    personless(event: string): boolean;
+    reset(): void;
+}
+
+/**
+ * P-L12 controlled exposure. The RSA-OAEP-SHA256 encryption runs natively (`encryptSensitive` on the LucidaReplay module,
+ * a blocking synchronous method: iOS SecKey, Android Cipher with MGF1-SHA256), so only an audited reveal on the server can
+ * read the value. Identical values are sent once per session (an in-memory SHA-256 set, never persisted or sent).
+ */
+interface NativeSensitiveModule {
+    /** Standard base64 of the ciphertext of the UTF-8 of `plain`, or "" on failure. */
+    encryptSensitive(pkcs1: string, n: string, e: string, plain: string): string;
+}
+interface ExposureKey {
+    kid: string;
+    /** base64url (no padding) big-endian modulus */
+    n: string;
+    /** base64url (no padding) exponent */
+    e: string;
+    /** standard base64 of the PKCS#1 RSAPublicKey DER */
+    pkcs1: string;
+}
+declare const SENSITIVE_MAX_PLAIN_BYTES = 190;
+/** [value] cut so its UTF-8 is at most [max] bytes, on a code point boundary; `truncated` when cut. */
+declare function truncateUtf8(value: string, max?: number): {
+    text: string;
+    truncated: boolean;
+};
+/** Native encryption, failing closed: null when the module is missing, throws or returns "". */
+declare function encryptSensitive(module: Partial<NativeSensitiveModule> | undefined, key: ExposureKey, plain: string): string | null;
+interface SensitiveCapture {
+    /** `$sensitive_capture` properties, or null when this value was already sent this session or encryption failed. */
+    properties(field: string, value: string, screen: string, key: ExposureKey, sessionId: string): Record<string, unknown> | null;
+}
+declare function createSensitiveCapture(module: Partial<NativeSensitiveModule> | undefined): SensitiveCapture;
+
+/**
+ * Native contract (implemented by ios/LucidaReplay.swift and android/.../LucidaReplayModule.kt, which call the
+ * Lucida iOS / Android SDK wireframe encoders): one capture of the current native view hierarchy.
+ * Resolves to JSON text `{"width": number, "height": number, "events": [meta (type 4), fullSnapshot (type 2)]}`,
+ * or "" when nothing can be captured (no key window / activity). Native code must mask: input values and
+ * secure fields never leave the device, other text is starred when `maskText` is true. Views wrapped in
+ * `<LucidaMask>` / `<LucidaUnmask>` carry the native markers the encoders already honour. See README "Session replay".
+ */
+interface NativeReplayModule extends Partial<NativeSensitiveModule> {
+    captureWireframe(options: {
+        /** P-M17: mask every text, input and image whatever the unmask markers say (present only when true). */
+        maskScreen?: boolean;
+        /** P-M46: regular expressions starred in shown text; screenshots paint matching views (present only when non-empty). */
+        maskTextPatterns?: string[];
+        screen: string;
+        maskText: boolean;
+        maskAllTextInputs: boolean;
+        maskAllImages: boolean;
+        maskSandboxedViews: boolean;
+        /** Present only in screenshot mode: the native side draws the window, paints the mask plan and only then encodes JPEG. */
+        mode?: "screenshot";
+        /** JPEG quality 0..1 (screenshot mode). */
+        screenshotQuality?: number;
+    }): Promise<string>;
+}
+interface ReplayConfig {
+    /** Off by default; also requires the `replay` consent category. */
+    enabled?: boolean;
+    /** The native module (`NativeModules.LucidaReplay`), injected so tests and non-native hosts need no React Native. */
+    module: NativeReplayModule;
+    /** Seconds-level cadence; a snapshot is only sent when the structure changed. Default 5000. */
+    snapshotIntervalMs?: number;
+    /** Starred text unless false. Default true. */
+    maskText?: boolean;
+    /** Text-field values are starred unless false (secure fields are never readable). Default true. */
+    maskAllTextInputs?: boolean;
+    /** Images carry a mask marker unless false. Default true. */
+    maskAllImages?: boolean;
+    /** WebViews / maps / platform views are recorded as an empty frame unless false. Default true. */
+    maskSandboxedViews?: boolean;
+    /** "screenshot" sends masked JPEG frames (masks painted on device before encoding) instead of wireframes. Default "wireframe". */
+    mode?: "wireframe" | "screenshot";
+    /** JPEG quality 0..1 for screenshot mode. Default 0.4. */
+    screenshotQuality?: number;
+    /** 0..1, decided once per session. Default 1. */
+    sampleRate?: number;
+    /** Minimum ms between captures on top of the interval. Default 0. */
+    throttleMs?: number;
+    /** Hold chunks until the session has been recorded this long; a session that ends sooner (or `stop()`) is never sent. Default 0 (off). */
+    minDurationMs?: number;
+    /**
+     * Disk budget for chunks that wait (min duration, offline, upload backoff); over it the oldest whole session is dropped
+     * and `onSpoolDrop` fires. Default 10 MiB. Needs `asyncStorage` to survive a restart.
+     */
+    spoolBudgetBytes?: number;
+    /** A whole session was dropped because the spool exceeded its budget (also logged in debug mode). */
+    onSpoolDrop?: (info: {
+        sessionId: string;
+        chunks: number;
+        bytes: number;
+    }) => void;
+    /** Fetch `GET /v1/config` and honour the project kill switch, sample rate and minimum duration (tightening only). Default true. */
+    useRemoteConfig?: boolean;
+    /** Start recording only while this flag is on. */
+    linkedFlag?: string;
+    /** Only these screens are recorded (empty = all). The deny list wins and pauses recording on a denied screen. */
+    screenAllowList?: string[];
+    screenDenyList?: string[];
+    /** Record taps fed to `client.replay.tap(x, y)` (positions only, never what was typed). Default true. */
+    captureTouches?: boolean;
+    /** P-M17 screen-name patterns (`*` wildcard, case-insensitive, whole name): mask everything there. Union with the project's list. */
+    maskScreens?: string[];
+    /** P-M46 regular expressions starred in any text replay would show. Union with the project's list; invalid ones are ignored. */
+    maskTextPatterns?: string[];
+    /** P-M46 `$dead_swipe` for swipes fed by `<LucidaTouchCapture>` that changed nothing. Default true. */
+    captureDeadSwipes?: boolean;
+    /** How long after a swipe the screen must still look the same (tests). Default 700. */
+    deadSwipeSettleMs?: number;
+    /** Random source for sampling (tests). */
+    random?: () => number;
+    /** Largest chunk sent (the gateway accepts 10 MB decompressed). Default 5_000_000. */
+    maxEventBytes?: number;
+    /** Timer injection for tests. */
+    setInterval?: (fn: () => void, ms: number) => unknown;
+    clearInterval?: (h: unknown) => void;
+}
+interface ReplayService {
+    start(): void;
+    stop(): void;
+    /** Manual pause: ticks capture nothing until resume() (the timer keeps running). */
+    pause(): void;
+    resume(): void;
+    /** Timer running, not paused, both consent categories held, sampled in, flag on and screen allowed. */
+    isRecording(): boolean;
+    /** Screen the next capture is attributed to (also emits a navigation marker on change). */
+    setScreen(name: string): void;
+    /** A tap at screen point (x, y); ignored without consent, before the first snapshot, while paused or on a gated screen. */
+    tap(x: number, y: number): void;
+    /** Erase every spilled chunk (opt-out, reset). */
+    clearSpool(): void;
+    /** One capture pass (the interval calls this); exposed for tests. */
+    tick(): Promise<void>;
+    /** P-M46: a swipe passed the touch slop; its start structure is captured now. */
+    swipeBegan(): void;
+    /** P-M46: the swipe ended (end - start, points); resolves true when a `$dead_swipe` was captured. */
+    swipeEnded(dx: number, dy: number): Promise<boolean>;
+    /** P-L12: see `NativeClient.captureSensitive`; true when a `$sensitive_capture` was captured. */
+    captureSensitive(field: string, value: string): boolean;
+}
+interface ReplayDeps {
+    core: Core;
+    /** Where waiting chunks are spilled (the client's storage, encrypted with the queue cipher when one is set). */
+    storage: Storage;
+    fetch: typeof fetch;
+    apiHost: string;
+    apiKey: string;
+    config: ReplayConfig;
+    now?: () => number;
+    log?: (...a: unknown[]) => void;
+    /** Reads `config.linkedFlag`. */
+    isFlagOn?: (key: string) => boolean;
+}
+type Remote = {
+    session_recording?: boolean;
+    replay_sample_rate?: number;
+    replay_min_duration_ms?: number;
+    replay_mask_screens?: unknown;
+    replay_mask_text_patterns?: unknown;
+    replay_exposure_fields?: unknown;
+    replay_exposure_key?: unknown;
+};
+/** The P-L12 key when all four parts are strings, else null (the feature is off). */
+declare function exposureKeyOf(v: unknown): ExposureKey | null;
+/** Deny wins; an empty allow list allows every screen. */
+declare const screenAllowed: (screen: string, allow?: readonly string[], deny?: readonly string[]) => boolean;
+/** Remote config can only tighten the local settings. */
+declare const effectiveSampleRate: (local: number, remote: Remote | null) => number;
+declare const effectiveMinDurationMs: (local: number, remote: Remote | null) => number;
+/**
+ * Mobile wireframe replay for React Native. The native module encodes the view hierarchy; this side owns what
+ * the native SDKs own for themselves: consent gate (analytics + replay), project kill switch / sample rate /
+ * minimum duration, linked flag, screen allow/deny list, session/window ids, chunk `seq` that resets when the
+ * session rotates, dedupe by structure, and delivery to `POST /v1/replay`.
+ */
+declare function createReplay(d: ReplayDeps): ReplayService;
+
+/** Wireframe replay control; no-ops unless `replay.enabled`. Consent (analytics + replay) is always required. */
+interface ReplayControl {
+    start(): void;
+    stop(): void;
+    pause(): void;
+    resume(): void;
+    /** Emits `$replay_tag` { name, session_id }. */
+    tag(name: string): void;
+    isRecording(): boolean;
+    /** A tap at screen point (x, y) for the replay touch overlay; see `<LucidaTouchCapture>`. Ignored unless recording with `replay.captureTouches`. */
+    tap(x: number, y: number): void;
+    /** P-M46: a swipe passed the touch slop (`<LucidaTouchCapture>` calls this). */
+    swipeBegan(): void;
+    /** P-M46: the swipe ended, `dx`/`dy` = end - start in points; a 48 pt swipe that changed nothing becomes `$dead_swipe`. */
+    swipeEnded(dx: number, dy: number): void;
+}
+/** Identity and flag values known before the first network response (server-rendered, or from a previous launch). */
+interface Bootstrap {
+    distinctId?: string;
+    /** Treat `distinctId` as an identified user (no anonymous merge on the first identify). */
+    isIdentified?: boolean;
+    flags?: Record<string, FlagValue>;
+    payloads?: Record<string, unknown>;
+}
+interface FlagOptions {
+    bootstrap?: Bootstrap | undefined;
+    /** Emit `$feature_flag_called` / `$exposure` when a flag is read. Default true. */
+    sendFeatureFlagEvent?: boolean;
+    /** false: no flag request at launch or on identity changes until `reloadFlags()`. Default true. */
+    preload?: boolean;
+    /** Environment tags sent with the flag request; the server returns only flags whose tags match. */
+    evaluationContexts?: string[];
+    /**
+     * Skip the automatic flag request at launch while the last response for this device and id is younger than this many ms.
+     * `reloadFlags()`, identity changes and property changes always fetch. Default off.
+     */
+    cacheTtlMs?: number;
+}
+interface CaptureOptions {
+    /** Person properties set with this event (`$set`). */
+    set?: Props;
+    /** Person properties set once with this event (`$set_once`). */
+    setOnce?: Props;
+}
+interface NativeClient {
+    readonly distinctId: string;
+    /** Anonymous id of this device; survives `reset()` with `reuseAnonymousId`. */
+    getAnonymousId(): string;
+    isOptedOut(): boolean;
+    /** Runtime debug toggle. */
+    debug(on: boolean): void;
+    capture(event: string, props?: Props, opts?: CaptureOptions): void;
+    /** Updates person properties without an event of your own (sends a `$set` event). */
+    setPersonProperties(set?: Props, setOnce?: Props): void;
+    /** `$deep_link_opened` with the url, its query parameters and the referrer. */
+    openURL(url: string, referrer?: string): void;
+    /** `fetch` that adds `X-Lucida-Distinct-Id` / `X-Lucida-Session-Id` for hosts in `tracingHeaders`. */
+    readonly fetch: typeof fetch;
+    readonly autocapture: Autocapture;
+    /** Screen view: `$screen` with `$screen_name`. */
+    screen(name: string, props?: Props): void;
+    identify(id: string, set?: Props, once?: Props): void;
+    alias(alias: string, original?: string): void;
+    reset(): void;
+    register(p: Props): void;
+    registerOnce(p: Props): void;
+    unregister(key: string): void;
+    group(type: string, key: string, props?: Props): void;
+    optIn(): void;
+    optOut(): void;
+    getFlag(key: string): FlagValue | undefined;
+    getFlagPayload(key: string): unknown;
+    /** Value, variant, payload and reason (evaluator/server reason, or `override`, `bootstrap`, `cached`, `pushed`, `not_found`) in one read. */
+    getFlagResult(key: string, opts?: {
+        sendExposure?: boolean;
+    }): FlagResult;
+    isFeatureEnabled(key: string): boolean;
+    onFlags(cb: (f: Record<string, FlagValue>) => void): () => void;
+    /** In-session interventions (N-ANA-2) fired for this person; polls GET /v1/interventions while a listener is set. Returns unsubscribe. */
+    onIntervention(cb: (i: Intervention) => void): () => void;
+    reloadFlags(): Promise<void>;
+    /** Injects server-evaluated flags (own backend); use with `disableRemoteFeatureFlags`. `merge` keeps existing values. */
+    updateFlags(flags: Record<string, FlagValue>, payloads?: Record<string, unknown>, opts?: {
+        merge?: boolean;
+    }): void;
+    /** Every known flag value, without exposure events. */
+    getAllFlags(): Record<string, FlagValue>;
+    /** Force values on this device; `false` clears. */
+    overrideFlags(map: Record<string, FlagValue> | false): void;
+    /** Person / group properties used only to evaluate flags (no `$set` event). `reload` (default true) re-evaluates now. */
+    setPersonPropertiesForFlags(props: Props, reload?: boolean): Promise<void>;
+    resetPersonPropertiesForFlags(reload?: boolean): Promise<void>;
+    setGroupPropertiesForFlags(type: string, props: Props, reload?: boolean): Promise<void>;
+    resetGroupPropertiesForFlags(reload?: boolean): Promise<void>;
+    readonly replay: ReplayControl;
+    /**
+     * Controlled exposure (P-L12): sends `value` RSA-OAEP-SHA256 encrypted (natively) with the project key as
+     * `$sensitive_capture`, only when `field` (your testID) is listed in the project's exposure fields, the key is present,
+     * analytics + replay consent is held and replay is enabled. Only an audited reveal on the server can read it; identical
+     * values are sent once per session. Never pass a secure (password) field. Returns whether an event was captured.
+     */
+    captureSensitive(field: string, value: string): boolean;
+    /** In-app guides; inert unless `guides.enabled` and a `<LucidaGuides />` is mounted. */
+    readonly guides: GuidesService;
+    flush(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+interface NativeConfig {
+    apiHost?: string;
+    /** Inject @react-native-async-storage/async-storage. Omitted: in-memory only. */
+    asyncStorage?: AsyncStorageLike;
+    /** Inject react-native's AppState for $app_opened / $app_backgrounded and flush on background. */
+    appState?: AppStateLike;
+    fetch?: typeof fetch;
+    transport?: Transport;
+    appVersion?: string;
+    appBuild?: string;
+    /** Send install attribution on the first-open `$app_installed` (default true); needs `installInfo`. */
+    installAttribution?: boolean;
+    /** Native source: `() => NativeModules.LucidaReplay.installInfo()`. Omitted: `$app_installed` is sent immediately without attribution. */
+    installInfo?: () => Promise<InstallInfo | null>;
+    platform?: string;
+    osVersion?: string;
+    consent?: {
+        mode?: "opt_in" | "opt_out";
+        queueBeforeConsent?: boolean;
+        storageKey?: string;
+    };
+    flushAt?: number;
+    flushIntervalMs?: number;
+    maxQueueSize?: number;
+    /** Encrypt the persisted offline queue at rest (Keychain / Keystore backed). */
+    queueCipher?: QueueCipher;
+    /** Largest batch per request; bigger queues are sent in chunks, also for a custom `transport`. Default: no split. */
+    maxBatchSize?: number;
+    maxRetries?: number;
+    /** Base of the exponential retry delay. Default 1000. */
+    retryDelayMs?: number;
+    /** Abort (or, for a custom `transport`, stop waiting for) a request after this long (0 = never). Default 0. */
+    requestTimeoutMs?: number;
+    /** `wifi`: flush only while `network.isWifi()`; events wait in the queue otherwise. */
+    dataMode?: "any" | "wifi";
+    network?: {
+        isWifi(): boolean;
+    };
+    sessionIdleMs?: number;
+    sessionMaxMs?: number;
+    /** Ask the server not to geolocate events (`$geoip_disable`). */
+    disableGeoip?: boolean;
+    /** Ordered hooks run on every event before it is queued; return null to drop. A throwing hook is logged and skipped. */
+    beforeSend?: BeforeSend[];
+    personProfiles?: PersonProfiles;
+    /** Keep the anonymous id across `reset()`. */
+    reuseAnonymousId?: boolean;
+    flagOptions?: FlagOptions;
+    /** Never call POST /v1/flags: use with `flagOptions.bootstrap`, `localFlags` and `updateFlags`. */
+    disableRemoteFeatureFlags?: boolean;
+    /** Attach `$feature/<key>` and `$active_feature_flags` to events (default true). */
+    sendFeatureFlags?: boolean;
+    /** Send $app_version, $os and $lib as person properties with flag requests (default true). */
+    sendDefaultFlagProps?: boolean;
+    autocapture?: AutocaptureConfig;
+    /** Own-backend hosts that receive `X-Lucida-*` headers through `client.fetch`. */
+    tracingHeaders?: string[];
+    disabled?: boolean;
+    debug?: boolean;
+    /** Definitions for on-device evaluation; flags needing the server (cohorts) still use POST /v1/flags. */
+    localFlags?: FlagDefinition[];
+    localFlagsContext?: Partial<EvalContext>;
+    /** Consume /v1/flags/stream with the public key (change notices only) and refetch on notice; falls back to polling (`pollMs`, default 60s) when the runtime cannot stream fetch bodies. Default off. */
+    flagStream?: boolean | {
+        pollMs?: number;
+    };
+    /** Wireframe session replay through the native module (off unless `enabled`). */
+    replay?: ReplayConfig;
+    /** In-app guides (LC-ENG-15). Off by default: no `/v1/guides` request until enabled. */
+    guides?: {
+        enabled?: boolean;
+    };
+}
+
+declare const LIB = "lucida-react-native";
+declare const LIB_VERSION = "0.1.1";
+/**
+ * Hydrates storage, then builds the client. Nothing is persisted before consent in opt_in mode;
+ * `$app_opened` fires on creation and on every foreground, `$app_backgrounded` flushes the queue.
+ */
+declare function createClient(apiKey: string, config?: NativeConfig): Promise<NativeClient>;
+
+/**
+ * Native contract (ios/LucidaReplay.swift -> KeychainQueueCipher, android/.../LucidaReplayModule.kt -> KeystoreQueueCipher):
+ * two blocking synchronous methods (`RCT_EXTERN__BLOCKING_SYNCHRONOUS_METHOD` / `isBlockingSynchronousMethod = true`), because
+ * the core's Storage port is synchronous. AES-256-GCM with a non-exportable key held by the platform (iOS Keychain, Android
+ * Keystore), generated on first use. Ciphertext is base64 of nonce + ciphertext + tag, the same format as the native SDKs.
+ * Blocking synchronous methods need JSI, so they are unavailable while debugging through the remote JS debugger.
+ */
+interface NativeCipherModule {
+    encryptQueue(plain: string): string;
+    /** null or "" when the value cannot be decrypted (key lost or rotated, corrupt data). */
+    decryptQueue(cipher: string): string | null | undefined;
+}
+/**
+ * `queueCipher` backed by the platform key store: `createClient({ queueCipher: nativeQueueCipher(NativeModules.LucidaReplay), ... })`.
+ * The module is injected so tests and non-native hosts need no React Native. Fails closed: a native error on encrypt stores an
+ * empty value (read back as an empty queue), never the plaintext; a native error on decrypt reads as an empty queue.
+ */
+declare function nativeQueueCipher(module: NativeCipherModule | null | undefined): QueueCipher;
+
+/** The slice of a react-navigation container ref used for screen tracking (optional peer). */
+interface NavigationRefLike {
+    getCurrentRoute(): {
+        name: string;
+        params?: Record<string, unknown>;
+    } | undefined;
+}
+/**
+ * Screen tracking for react-navigation. Wire both handlers on `<NavigationContainer>`:
+ * `onReady` records the first screen, `onStateChange` records changes (deduped by route name).
+ * Route params are not sent (they often hold PII); pass `includeParams` to opt in.
+ */
+declare function screenTracker(client: Pick<NativeClient, "screen">, ref: {
+    current: NavigationRefLike | null;
+}, opts?: {
+    includeParams?: boolean;
+}): {
+    onReady(): void;
+    onStateChange(): void;
+};
+
+/**
+ * `X-Lucida-Distinct-Id` / `X-Lucida-Session-Id` for requests to your own backend hosts so server events join this
+ * device's session. Never for the Lucida api host, and only while analytics consent is granted.
+ * Servers must treat these headers as client-controlled, never as authentication.
+ * The same requests carry W3C `baggage: lucida.session_id=<id>` (merged into the app's own baggage) so Watchtower links its
+ * spans, network timings and logs to this session: the Watchtower seam, Lucida itself captures no network or log data.
+ */
+declare function tracingHeaders(hosts: readonly string[], apiHost: string, consent: () => boolean, ids: () => {
+    distinctId: string;
+    sessionId: string;
+}): (url: string, baggage?: string | null) => Record<string, string>;
+/** `lucida.session_id=<id>` appended to `existing` W3C baggage, replacing a stale Lucida entry. */
+declare function withBaggage(existing: string | null | undefined, sessionId: string): string;
+/** A fetch that adds the tracing headers when the target host matches; everything else passes through untouched. */
+declare function tracedFetch(fetchImpl: typeof fetch, headersFor: (url: string, baggage?: string | null) => Record<string, string>): typeof fetch;
+
+interface SpoolEntry {
+    id: number;
+    sid: string;
+    seq: number;
+    /** Waiting for the minimum session duration (dropped if the session ends first); false = waiting for upload. */
+    held: boolean;
+    /** Body size in bytes. */
+    n: number;
+    /** Number of parts the body is split into (`lc_replay.<id>.<i>`). */
+    p: number;
+    /** Body length in UTF-16 units: a torn or truncated body no longer adds up and is discarded. */
+    len: number;
+}
+/**
+ * Durable, ordered spill for replay chunks that cannot be sent yet (min duration, offline, upload backoff).
+ * `lc_replay` is the index (JSON list of entries), `lc_replay.<id>.<i>` holds part i of one chunk body (no api key), split
+ * into parts under 1 MB. Write order: `lc_replay.pending` names the entry in flight, then its parts, then the index, then
+ * pending is cleared; a crash in between leaves parts the index never lists, which load deletes. Pass a storage
+ * wrapped with `encryptedStorage(..., [SPOOL_KEY], [`${SPOOL_KEY}.`])` to encrypt at rest. Over `budget` bytes the oldest
+ * whole session is dropped (never single chunks, so a kept session has no hole) and `onDrop` reports it.
+ */
+declare function createReplaySpool(storage: Storage, budget?: number, onDrop?: (sid: string, chunks: number, bytes: number) => void): {
+    entries: () => readonly SpoolEntry[];
+    totalBytes: () => number;
+    add(sid: string, seq: number, held: boolean, body: string): void;
+    /** The whole body, or null when a part is missing or the length does not add up (torn write): the caller discards it. */
+    read(e: SpoolEntry): string | null;
+    remove(e: SpoolEntry): void;
+    /** Held chunks of every session except `keep`; returned so the caller can give their seq numbers back. */
+    removeHeld(keep?: string): SpoolEntry[];
+    /** The session reached its minimum duration: its held chunks become plain pending uploads. */
+    release(sid: string): void;
+    nextSeq: (sid: string) => number;
+    clear(): void;
+};
+
+/**
+ * P-M17 masked screens and P-M46 text patterns. The native encoders apply both (they receive `maskScreen` and
+ * `maskTextPatterns` with every capture, screenshots included); [maskSnapshotText] re-applies the patterns to the
+ * returned wireframe in JS as well. Remote lists add to the local ones, so they can only tighten.
+ */
+/** Case-insensitive match of the whole screen name; `*` matches any run of characters. Empty list = false. */
+declare function screenMasked(screen: string, patterns: readonly string[]): boolean;
+/** Patterns that fail to compile are dropped, never fatal. No built-in patterns: the server masks emails/cards/phones again. */
+declare function compilePatterns(patterns: readonly string[]): RegExp[];
+/** Every character inside a match of any pattern becomes `*` (whitespace kept), like the native `mask()` helpers. */
+declare function maskPatterns(text: string, patterns: readonly RegExp[]): string;
+/** A copy of a full-snapshot node tree with the patterns applied to text nodes and input `value` attributes. */
+declare function maskSnapshotText(node: unknown, patterns: readonly RegExp[]): unknown;
+
+/**
+ * P-M46 `$dead_swipe`: a swipe of at least 48 points after which nothing on screen scrolled, paged or changed (the
+ * wireframe fingerprint ~700 ms after the gesture equals the one at its start). Carries geometry only, never text.
+ */
+declare const DEAD_SWIPE_MIN_DISTANCE = 48;
+type SwipeDirection = "left" | "right" | "up" | "down";
+/** Dominant axis of end - start; screen y grows downwards. */
+declare const swipeDirection: (dx: number, dy: number) => SwipeDirection;
+interface DeadSwipeInput {
+    screen: string;
+    startScreen: string;
+    startFingerprint: string;
+    endFingerprint: string;
+    dx: number;
+    dy: number;
+    nowMs: number;
+    lastAt?: number | undefined;
+}
+/** The `$dead_swipe` properties when the swipe was dead and the 2 s cooldown has passed, else null. */
+declare function deadSwipeDecision(i: DeadSwipeInput): {
+    $screen_name: string;
+    $swipe_direction: SwipeDirection;
+    $swipe_distance: number;
+} | null;
+
+/**
+ * Draws the current in-app guide step (plain text only). Mount once, as the LAST child of the app root (anchored
+ * steps draw over the app from here); needs `guides.enabled`. Anchored steps (tooltip, hotspot, tour with native_id)
+ * point at a `<GuideAnchor testID>`; a missing anchor shows the step as a modal.
+ */
+declare function LucidaGuides(): react.JSX.Element | null;
+
+interface GuideTokens {
+    background?: string;
+    text?: string;
+    accent?: string;
+    radius?: number;
+    font?: string;
+}
+type Obj = Record<string, unknown>;
+declare function guideTokens(a: Obj | null | undefined, systemDark: boolean): GuideTokens;
+interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Bubble origin: below the target when it fits (or placement is not "top"), else above; centred and clamped. */
+declare function bubbleOrigin(w: number, h: number, r: Rect, bounds: Rect, placement?: string, margin?: number, gap?: number): {
+    x: number;
+    y: number;
+};
+
+/** What a registered anchor must do: React Native host views implement measureInWindow. */
+interface Measurable {
+    measureInWindow(cb: (x: number, y: number, width: number, height: number) => void): void;
+}
+/** Register a view under `id` (the latest mount wins). Returns the unregister. */
+declare function registerAnchor(id: string, m: Measurable): () => void;
+/** The anchor's rect in window coordinates; null when nothing is registered or it has no size (not laid out). */
+declare function measureAnchor(id: string): Promise<Rect | null>;
+/** Wrap a view a guide may anchor to. `testID` is also set on the view (tests / automation keep working). */
+declare function GuideAnchor({ testID, children, style }: {
+    testID: string;
+    children?: ReactNode;
+    style?: unknown;
+}): react.JSX.Element;
+
+/**
+ * Markers the native encoders already honour (iOS accessibilityIdentifier, Android view tag), applied through `testID`
+ * (which also stops React Native from flattening the view away). They replace any `testID` on the wrapper, so put your
+ * own `testID` on a child. Unmask never overrides mask or secure fields, at any depth.
+ */
+declare const REPLAY_MARKERS: {
+    readonly ios: {
+        readonly mask: "lucida-sensitive";
+        readonly unmask: "lucida-unmask";
+    };
+    readonly android: {
+        readonly mask: "lc-mask";
+        readonly unmask: "lc-unmask";
+    };
+};
+declare const replayMarker: (kind: "mask" | "unmask", os?: string) => string;
+interface MarkProps {
+    children?: ReactNode;
+    style?: unknown;
+}
+/** Never show this subtree in replay: text is dropped and images/inputs are masked, whatever the global switches say. */
+declare function LucidaMask({ children, style }: MarkProps): react.JSX.Element;
+/** Show this subtree's text, input values (never secure ones) and images in replay even with the global masks on. */
+declare function LucidaUnmask({ children, style }: MarkProps): react.JSX.Element;
+/**
+ * Wrap the app root to feed taps to `client.replay.tap` (the replay touch overlay) and swipes to the `$dead_swipe` check.
+ * It only observes touch events bubbling up from children; it never becomes the responder, so no touch is cancelled or delayed.
+ */
+declare function LucidaTouchCapture({ children, style }: MarkProps): react.JSX.Element;
+
+type Flags = Record<string, FlagValue>;
+interface LucidaProviderProps {
+    client?: NativeClient;
+    apiKey?: string;
+    options?: NativeConfig;
+    children?: ReactNode;
+}
+declare function LucidaProvider({ client: given, apiKey, options, children }: LucidaProviderProps): react.JSX.Element;
+
+declare function useLucida(): NativeClient | null;
+/** Stable capture function; a no-op until the client is ready. */
+declare function useCapture(): NativeClient["capture"];
+/** Recording control; inert until the client is ready. */
+declare function useReplay(): ReplayControl;
+/** Records a `$screen` event when `name` changes (for apps not using react-navigation). */
+declare function useScreen(name: string, props?: Record<string, unknown>): void;
+/** Flag value from provider state; the exposure is recorded after mount, never during render. */
+declare function useFeatureFlag(key: string): FlagValue | undefined;
+declare function useFeatureFlagVariant(key: string): string | undefined;
+declare function useFeatureFlagPayload(key: string): unknown;
+declare function useActiveFeatureFlags(): string[];
+interface FeatureGateProps {
+    flag: string;
+    variant?: string;
+    fallback?: ReactNode;
+    children?: ReactNode;
+}
+declare function FeatureGate({ flag, variant, fallback, children }: FeatureGateProps): react.JSX.Element;
+
+export { type AppStateLike, type AppStateStatus, type AsyncStorageLike, type Autocapture, type AutocaptureConfig, type Bootstrap, type CaptureOptions, DEAD_SWIPE_MIN_DISTANCE, type DeadSwipeInput, type ExposureKey, FeatureGate, type FeatureGateProps, type FiberLike, type FlagOptions, type Flags, GuideAnchor, type GuideAnchorSpec, type GuideButton, type GuideStep, type GuideTokens, type GuideView, type GuidesDeps, type GuidesService, type InstallInfo, LIB, LIB_VERSION, LucidaGuides, LucidaMask, LucidaProvider, type LucidaProviderProps, LucidaTouchCapture, LucidaUnmask, type Measurable, type MobileGuide, type NativeCipherModule, type NativeClient, type NativeConfig, type NativeInstallModule, type NativeReplayModule, type NativeSensitiveModule, type NavigationRefLike, PERSISTED_KEYS, PersonMode, type QueueCipher, REPLAY_MARKERS, type RageTapConfig, type ReplayConfig, type ReplayControl, type ReplayService, SENSITIVE_MAX_PLAIN_BYTES, type SensitiveCapture, type SpoolEntry, type SwipeDirection, type TapElement, type TouchEventLike, appLifecycle, appStoreInstallProps, asyncStorageAdapter, bubbleOrigin, chainFromFiber, compilePatterns, createAutocapture, createClient, createGuides, createReplay, createReplaySpool, createSensitiveCapture, deadSwipeDecision, effectiveMinDurationMs, effectiveSampleRate, encryptSensitive, encryptedStorage, exposureKeyOf, fetchTransport, guideAnchor, guideButtons, guideTokens, installReferrerProps, maskPatterns, maskSnapshotText, matches as matchGuideScreen, measureAnchor, memoryStorage, nativeQueueCipher, registerAnchor, replayMarker, resolveInstallProps, runHooks, sampleHook, screenAllowed, screenExcluded, screenMasked, screenTracker, splitBatches, swipeDirection, touchHandler, tracedFetch, tracingHeaders, truncateUtf8, useActiveFeatureFlags, useCapture, useFeatureFlag, useFeatureFlagPayload, useFeatureFlagVariant, useLucida, useReplay, useScreen, withBaggage, withTimeout };