@userflow-tech/react-native 0.1.0

package/lib/typescript/commonjs/src/expo-router/useUserflowExpoRouter.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Tracks Expo Router pathname changes for Userflow screen detection and
+ * registers `router.push` for path-like flow NAVIGATE actions.
+ *
+ * Mount via {@link UserflowExpoRouterScreenTracker} from
+ * `@userflow-tech/react-native/expo-router` under {@link UserflowProvider}. Do not
+ * import this hook from the package root — that would force every host app to
+ * install the `expo-router` peer.
+ *
+ * Pathnames are reported as `{ path }` and mapped to wire `screenPath`
+ * (not `screenName`).
+ *
+ * Screen tracking ≠ action routing: NAVIGATE for in-app paths uses the router
+ * handle registered here; http(s)/mailto/tel still go through Linking.
+ */
+export declare function useUserflowExpoRouter(): void;
+//# sourceMappingURL=useUserflowExpoRouter.d.ts.map

package/lib/typescript/commonjs/src/expo-router/useUserflowExpoRouter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useUserflowExpoRouter.d.ts","sourceRoot":"","sources":["../../../../../src/expo-router/useUserflowExpoRouter.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAkB5C"}

package/lib/typescript/commonjs/src/index.d.ts

@@ -0,0 +1,112 @@
+/**
+ * @userflow-tech/react-native — public API for the Userflow React Native SDK.
+ *
+ * Exposes the `Userflow` singleton host apps import. Auth/identity and the
+ * transport live in `@userflow-tech/core`; this binding is a thin facade that
+ * delegates to the core engine, wires React Native app lifecycle
+ * (background/foreground + idle) to the connection, hosts the flow session
+ * engine + provider overlay for Phase 3 rendering, and tracks screen changes.
+ */
+import type { UserflowAttributes, UserflowConfig, UserflowEventAttributes, UserflowGroupOptions, UserflowIdentifyOptions, UserflowInitOptions, UserflowTrackOptions } from '@userflow-tech/core';
+import './anchors/autoAnchor';
+import { type CustomScrollIntoView, type ScrollPadding } from './anchors/scrollConfig';
+import { type FlowNavigateHandler } from './navigation/openFlowNavigateUrl';
+export { SDK_VERSION } from './version';
+export { UserflowProvider, useUserflow } from './runtime/UserflowProvider';
+export type { UserflowProviderProps, UserflowContextValue } from './runtime/UserflowProvider';
+export { useFlowSessionState } from './runtime/useFlowSessionState';
+export type { FlowSessionState } from './runtime/useFlowSessionState';
+export { useUserflowScreen } from './useUserflowScreen';
+export { useUserflowAnchor } from './anchors/useUserflowAnchor';
+export { __userflowAutoAnchor } from './anchors/autoAnchor';
+export { useUserflowScrollContainer } from './anchors/useUserflowScrollContainer';
+export type { UserflowScrollContainerProps } from './anchors/useUserflowScrollContainer';
+export type { CustomScrollIntoView, ScrollIntoViewTarget, ScrollPadding, } from './anchors/scrollConfig';
+export { INACTIVITY_TIMEOUT_MS, SESSION_STALE_AFTER_BACKGROUND_MS, SUSPEND_GRACE_MS, } from './lifecycle';
+export { inspectPairingDeepLink, isPairingAttempt, parsePairingDeepLink, isUserflowPairingUrl, PreviewModeBanner, } from './pairing';
+export type { PairingAttemptRejection, PairingDeepLink, PairingDeepLinkRejection, PairingDeepLinkResult, } from './pairing';
+/** Configuration passed to {@link Userflow.init}. */
+export type UserflowInitConfig = UserflowInitOptions & {
+    /**
+     * Optional host handler for flow NAVIGATE actions. When set, wins over
+     * React Navigation / Expo Router / Linking.
+     */
+    onNavigate?: FlowNavigateHandler;
+    /**
+     * Override the US-pinned Builder pairing websocket host (local/staging).
+     * Defaults to `https://e.userflow.com`.
+     */
+    pairingEndpoint?: string;
+};
+export type { UserflowAttributes, UserflowConfig, UserflowEventAttributes, UserflowGroupOptions, UserflowIdentifyOptions, UserflowInitOptions, UserflowTrackOptions, } from '@userflow-tech/core';
+/**
+ * Public SDK entry point. Delegates to the platform-agnostic engine in
+ * `@userflow-tech/core` and manages the app-lifecycle subscription.
+ */
+export declare const Userflow: {
+    /** Validate credentials, store configuration, and wire app-lifecycle handling. */
+    init(config: UserflowInitConfig): Promise<UserflowConfig>;
+    /**
+     * Forward a Userflow pairing deep link into the SDK.
+     * Prefer automatic Linking interception from {@link Userflow.init}; use this
+     * when the host app owns URL routing.
+     */
+    handlePairingUrl(url: string): Promise<boolean>;
+    /** Exit Builder preview mode and disconnect the pairing websocket. */
+    exitPreview(): Promise<void>;
+    /**
+     * Override or clear the host NAVIGATE handler (same as `init({ onNavigate })`).
+     * Wins over React Navigation / Expo Router / Linking when set.
+     */
+    setOnNavigate(handler: FlowNavigateHandler | null | undefined): void;
+    /** Identify the current user and upsert their attributes. */
+    identify(userId: string, attributes?: UserflowAttributes, options?: UserflowIdentifyOptions): Promise<void>;
+    /** Identify an anonymous user with a stable auto-generated id stored on device. */
+    identifyAnonymous(attributes?: UserflowAttributes, options?: UserflowIdentifyOptions): Promise<void>;
+    /**
+     * Handle an inbound URL. Returns `true` when it was a Userflow preview deep
+     * link (`userflow-*://?token=...`).
+     * Prefer letting {@link init} auto-listen; call this when the host app already
+     * owns Linking.
+     */
+    didHandleURL(url: string): Promise<boolean>;
+    /** Associate the current user with a group and upsert group/membership attributes. */
+    group(groupId: string | number, attributes?: UserflowAttributes, options?: UserflowGroupOptions): Promise<void>;
+    /** Record a custom analytics event for the current user (and group, unless `userOnly`). */
+    track(name: string, attributes?: UserflowEventAttributes, options?: UserflowTrackOptions): Promise<void>;
+    /** The currently identified user id, or `null` before identify. */
+    getUserId(): string | null;
+    /** A copy of the attributes recorded for the current user. */
+    getAttributes(): UserflowAttributes;
+    /** The flow session engine (created lazily; attach runs after identify). */
+    getFlowSessionEngine(): import("@userflow-tech/core").FlowSessionEngine;
+    /** Clears the current user identity and disconnects from Userflow. */
+    reset(): Promise<void>;
+    /** Remove app-lifecycle, network, and deep-link subscriptions (call on unmount / teardown). */
+    teardown(): void;
+    /**
+     * Signal user activity so the foreground idle timer resets and an
+     * idle-suspended socket reconnects. Prefer automatic signals from
+     * {@link updateScreen} / identify / group; call this for touch or other
+     * host-app activity the SDK does not observe.
+     */
+    reportActivity(): void;
+    /**
+     * Report the active React Navigation (or manual) screen name. Prefer
+     * {@link useUserflowScreen} in React trees; use this for imperative updates
+     * outside hooks. When a user is identified, pushes `UpdateClientContext`
+     * with `screen` set (Expo Router pathnames use `path` via the Expo helper).
+     */
+    updateScreen(screenName: string | undefined): void;
+    /**
+     * Sticky header/footer insets applied when scrolling tooltip targets into
+     * view (mirrors web `userflow.setScrollPadding`).
+     */
+    setScrollPadding(padding: ScrollPadding | null | undefined): void;
+    /**
+     * Replace the SDK's scroll-into-view behavior. Pass `null` to restore the
+     * default fiber / registry path (mirrors web `userflow.setCustomScrollIntoView`).
+     */
+    setCustomScrollIntoView(fn: CustomScrollIntoView | null | undefined): void;
+};
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/commonjs/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAClB,cAAc,EACd,uBAAuB,EACvB,oBAAoB,EACpB,uBAAuB,EACvB,mBAAmB,EACnB,oBAAoB,EACrB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,sBAAsB,CAAC;AAG9B,OAAO,EAGL,KAAK,oBAAoB,EACzB,KAAK,aAAa,EACnB,MAAM,wBAAwB,CAAC;AAShC,OAAO,EAAqB,KAAK,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAsB/F,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAC3E,YAAY,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAC9F,OAAO,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AACpE,YAAY,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,0BAA0B,EAAE,MAAM,sCAAsC,CAAC;AAClF,YAAY,EAAE,4BAA4B,EAAE,MAAM,sCAAsC,CAAC;AACzF,YAAY,EACV,oBAAoB,EACpB,oBAAoB,EACpB,aAAa,GACd,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,qBAAqB,EACrB,iCAAiC,EACjC,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,sBAAsB,EACtB,gBAAgB,EAChB,oBAAoB,EACpB,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,WAAW,CAAC;AACnB,YAAY,EACV,uBAAuB,EACvB,eAAe,EACf,wBAAwB,EACxB,qBAAqB,GACtB,MAAM,WAAW,CAAC;AAEnB,qDAAqD;AACrD,MAAM,MAAM,kBAAkB,GAAG,mBAAmB,GAAG;IACrD;;;OAGG;IACH,UAAU,CAAC,EAAE,mBAAmB,CAAC;IACjC;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,YAAY,EACV,kBAAkB,EAClB,cAAc,EACd,uBAAuB,EACvB,oBAAoB,EACpB,uBAAuB,EACvB,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,qBAAqB,CAAC;AAsE7B;;;GAGG;AACH,eAAO,MAAM,QAAQ;IACnB,kFAAkF;iBACrE,kBAAkB,GAAG,OAAO,CAAC,cAAc,CAAC;IAkCzD;;;;OAIG;0BACmB,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAG/C,sEAAsE;mBACvD,OAAO,CAAC,IAAI,CAAC;IAG5B;;;OAGG;2BACoB,mBAAmB,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI;IAGpE,6DAA6D;qBAEnD,MAAM,eACD,kBAAkB,YACrB,uBAAuB,GAChC,OAAO,CAAC,IAAI,CAAC;IAYhB,mFAAmF;mCAEpE,kBAAkB,YACrB,uBAAuB,GAChC,OAAO,CAAC,IAAI,CAAC;IAUhB;;;;;OAKG;sBACe,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAG3C,sFAAsF;mBAE3E,MAAM,GAAG,MAAM,eACX,kBAAkB,YACrB,oBAAoB,GAC7B,OAAO,CAAC,IAAI,CAAC;IAIhB,2FAA2F;gBAEnF,MAAM,eACC,uBAAuB,YAC1B,oBAAoB,GAC7B,OAAO,CAAC,IAAI,CAAC;IAIhB,mEAAmE;iBACtD,MAAM,GAAG,IAAI;IAG1B,8DAA8D;qBAC7C,kBAAkB;IAGnC,4EAA4E;;IAI5E,sEAAsE;aACvD,OAAO,CAAC,IAAI,CAAC;IAM5B,+FAA+F;gBACnF,IAAI;IAOhB;;;;;OAKG;sBACe,IAAI;IAGtB;;;;;OAKG;6BACsB,MAAM,GAAG,SAAS,GAAG,IAAI;IAGlD;;;OAGG;8BACuB,aAAa,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI;IAGjE;;;OAGG;gCACyB,oBAAoB,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI;CAG3E,CAAC"}

package/lib/typescript/commonjs/src/lifecycle.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Mobile connection lifecycle policy.
+ *
+ * - Background / inactive → arm a short grace timer, then suspend the socket.
+ *   Returning to active before grace elapses avoids suspend/resume churn: resume
+ *   if already idle-suspended, otherwise probe liveness (`ensureAlive`) so a
+ *   silently-dead socket recovers without waiting for the next heartbeat.
+ * - Foreground after grace but < {@link SESSION_STALE_AFTER_BACKGROUND_MS}
+ *   (5 min) → resume and keep the mid-flow session (short-background “resume”).
+ * - Foreground after ≥ 5 min → clear local flow session, then resume
+ *   (long-background reconnect without stale mid-flow UI).
+ * - Foreground idle for 5 min → suspend (skip while any flow session is active).
+ * - Activity while foreground → reset idle timer and resume if idle-suspended.
+ *
+ * This 5-minute policy is the ticket meaning of FLOW_RENDERING_SPEC “resume”:
+ * short backgrounds continue the active flow; long backgrounds clear then reconnect.
+ */
+import type { AppStateStatus } from 'react-native';
+/** Match web `INACTIVITY_TIMEOUT` — disconnect after this much idle time in foreground. */
+export declare const INACTIVITY_TIMEOUT_MS: number;
+/** Away this long → drop local mid-flow session before reconnecting. */
+export declare const SESSION_STALE_AFTER_BACKGROUND_MS: number;
+/**
+ * Delay before suspending on leave. Covers transient iOS `inactive` (Control
+ * Center, biometric prompts, app-switcher peek) and quick app-switches.
+ */
+export declare const SUSPEND_GRACE_MS = 3000;
+export type TimerHandle = ReturnType<typeof setTimeout>;
+export interface LifecycleScheduler {
+    setTimeout(handler: () => void, ms: number): TimerHandle;
+    clearTimeout(handle: TimerHandle): void;
+}
+export interface LifecycleControllerDeps {
+    suspend: () => void;
+    resume: () => void;
+    clearLocalSession: () => void;
+    /**
+     * Verify the socket is alive without a full suspend/resume. Called on a quick
+     * foreground (blur under grace) when the socket was never lifecycle-suspended
+     * but may have died silently. No-op if the transport is not connected.
+     * Do not call while lifecycle-suspended — use {@link resume} instead.
+     */
+    ensureAlive: () => void;
+    /** True while any mid-flow session (live or draft/preview) is on screen. */
+    hasActiveSession: () => boolean;
+    scheduler?: LifecycleScheduler;
+    now?: () => number;
+    /** Override for tests; defaults to {@link SUSPEND_GRACE_MS}. */
+    suspendGraceMs?: number;
+    /** Override for tests; defaults to React Native `AppState.currentState`. */
+    getCurrentAppState?: () => AppStateStatus;
+    /** Override for tests; defaults to React Native `AppState`. */
+    subscribeAppState?: (handler: (status: AppStateStatus) => void) => () => void;
+}
+/**
+ * Owns AppState subscription, background duration tracking, and the foreground
+ * idle timer. Call {@link start} from `Userflow.init` and {@link stop} from
+ * `Userflow.teardown`.
+ */
+export declare class LifecycleController {
+    private readonly suspend;
+    private readonly resume;
+    private readonly clearLocalSession;
+    private readonly ensureAlive;
+    private readonly hasActiveSession;
+    private readonly scheduler;
+    private readonly now;
+    private readonly suspendGraceMs;
+    private readonly getCurrentAppState;
+    private readonly subscribeAppState;
+    private unsubscribeAppState;
+    private idleTimer;
+    private graceTimer;
+    private backgroundedAt;
+    private appIsActive;
+    private started;
+    /** True once the grace timer has fired (or we suspended on long-away resume). */
+    private suspended;
+    constructor(deps: LifecycleControllerDeps);
+    start(): void;
+    stop(): void;
+    /**
+     * Signal user/SDK activity while the app is foregrounded. Resets the idle
+     * timer and reconnects if the socket was idle-suspended.
+     */
+    reportActivity(): void;
+    /** Visible for tests. */
+    handleAppStateChange(status: AppStateStatus): void;
+    private onBackground;
+    private onForeground;
+    private scheduleGraceTimer;
+    private clearGraceTimer;
+    private scheduleIdleTimer;
+    private clearIdleTimer;
+}
+//# sourceMappingURL=lifecycle.d.ts.map

package/lib/typescript/commonjs/src/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../../../src/lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,cAAc,EAA2B,MAAM,cAAc,CAAC;AAE5E,2FAA2F;AAC3F,eAAO,MAAM,qBAAqB,QAAgB,CAAC;AAEnD,wEAAwE;AACxE,eAAO,MAAM,iCAAiC,QAAgB,CAAC;AAE/D;;;GAGG;AACH,eAAO,MAAM,gBAAgB,OAAQ,CAAC;AAEtC,MAAM,MAAM,WAAW,GAAG,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;AAExD,MAAM,WAAW,kBAAkB;IACjC,UAAU,CAAC,OAAO,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,WAAW,CAAC;IACzD,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;CACzC;AAED,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,iBAAiB,EAAE,MAAM,IAAI,CAAC;IAC9B;;;;;OAKG;IACH,WAAW,EAAE,MAAM,IAAI,CAAC;IACxB,4EAA4E;IAC5E,gBAAgB,EAAE,MAAM,OAAO,CAAC;IAChC,SAAS,CAAC,EAAE,kBAAkB,CAAC;IAC/B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,gEAAgE;IAChE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,4EAA4E;IAC5E,kBAAkB,CAAC,EAAE,MAAM,cAAc,CAAC;IAC1C,+DAA+D;IAC/D,iBAAiB,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,cAAc,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;CAC/E;AAYD;;;;GAIG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAa;IACrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;IACpC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAa;IAC/C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAa;IACzC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAgB;IACjD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAC/C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAuB;IAC1D,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA4D;IAE9F,OAAO,CAAC,mBAAmB,CAA6B;IACxD,OAAO,CAAC,SAAS,CAA4B;IAC7C,OAAO,CAAC,UAAU,CAA4B;IAC9C,OAAO,CAAC,cAAc,CAAuB;IAC7C,OAAO,CAAC,WAAW,CAAQ;IAC3B,OAAO,CAAC,OAAO,CAAS;IACxB,iFAAiF;IACjF,OAAO,CAAC,SAAS,CAAS;gBAEd,IAAI,EAAE,uBAAuB;IAazC,KAAK,IAAI,IAAI;IAYb,IAAI,IAAI,IAAI;IAWZ;;;OAGG;IACH,cAAc,IAAI,IAAI;IAOtB,yBAAyB;IACzB,oBAAoB,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI;IAalD,OAAO,CAAC,YAAY;IAkBpB,OAAO,CAAC,YAAY;IAoCpB,OAAO,CAAC,kBAAkB;IAW1B,OAAO,CAAC,eAAe;IAOvB,OAAO,CAAC,iBAAiB;IAczB,OAAO,CAAC,cAAc;CAMvB"}

package/lib/typescript/commonjs/src/navigation/WithUserflowReactNavigation.d.ts

@@ -0,0 +1,21 @@
+import type { NavigationContainerRef, NavigationState, ParamListBase } from '@react-navigation/native';
+import type React from 'react';
+type NavigationContainerChildProps = {
+    ref?: React.Ref<NavigationContainerRef<ParamListBase>>;
+    onReady?: () => void;
+    onStateChange?: (state?: NavigationState) => void;
+};
+export interface WithUserflowReactNavigationProps {
+    children: React.ReactElement<NavigationContainerChildProps>;
+}
+/**
+ * Wraps a React Navigation `NavigationContainer` to report screen changes to
+ * Userflow after {@link Userflow.init} has completed.
+ *
+ * Also registers the container ref for in-app NAVIGATE actions (path-like URLs).
+ * Screen tracking ≠ action routing — without this wrapper, NAVIGATE falls back to
+ * Linking / host `onNavigate`.
+ */
+export declare function WithUserflowReactNavigation({ children, }: WithUserflowReactNavigationProps): React.ReactElement;
+export {};
+//# sourceMappingURL=WithUserflowReactNavigation.d.ts.map

package/lib/typescript/commonjs/src/navigation/WithUserflowReactNavigation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WithUserflowReactNavigation.d.ts","sourceRoot":"","sources":["../../../../../src/navigation/WithUserflowReactNavigation.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,sBAAsB,EACtB,eAAe,EACf,aAAa,EACd,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAQ/B,KAAK,6BAA6B,GAAG;IACnC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,sBAAsB,CAAC,aAAa,CAAC,CAAC,CAAC;IACvD,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,aAAa,CAAC,EAAE,CAAC,KAAK,CAAC,EAAE,eAAe,KAAK,IAAI,CAAC;CACnD,CAAC;AAEF,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,EAAE,KAAK,CAAC,YAAY,CAAC,6BAA6B,CAAC,CAAC;CAC7D;AAkBD;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,EAC1C,QAAQ,GACT,EAAE,gCAAgC,GAAG,KAAK,CAAC,YAAY,CAmCvD"}

package/lib/typescript/commonjs/src/navigation/chainCallbacks.d.ts

@@ -0,0 +1,3 @@
+/** Runs two optional callbacks in sequence, forwarding the same arguments. */
+export declare function chainCallbacks<A extends unknown[]>(first: ((...args: A) => void) | undefined, second: ((...args: A) => void) | undefined): ((...args: A) => void) | undefined;
+//# sourceMappingURL=chainCallbacks.d.ts.map

package/lib/typescript/commonjs/src/navigation/chainCallbacks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chainCallbacks.d.ts","sourceRoot":"","sources":["../../../../../src/navigation/chainCallbacks.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,wBAAgB,cAAc,CAAC,CAAC,SAAS,OAAO,EAAE,EAChD,KAAK,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC,GAAG,SAAS,EACzC,MAAM,EAAE,CAAC,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC,GAAG,SAAS,GACzC,CAAC,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC,GAAG,SAAS,CAOpC"}

package/lib/typescript/commonjs/src/navigation/getActiveRouteName.d.ts

@@ -0,0 +1,6 @@
+import type { NavigationState, PartialState } from '@react-navigation/native';
+type RoutableState = NavigationState | PartialState<NavigationState>;
+/** Returns the deepest active route name from a React Navigation state tree. */
+export declare function getActiveRouteName(state: RoutableState | undefined): string | undefined;
+export {};
+//# sourceMappingURL=getActiveRouteName.d.ts.map

package/lib/typescript/commonjs/src/navigation/getActiveRouteName.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getActiveRouteName.d.ts","sourceRoot":"","sources":["../../../../../src/navigation/getActiveRouteName.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAE9E,KAAK,aAAa,GAAG,eAAe,GAAG,YAAY,CAAC,eAAe,CAAC,CAAC;AAErE,gFAAgF;AAChF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,aAAa,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAYvF"}

package/lib/typescript/commonjs/src/navigation/index.d.ts

@@ -0,0 +1,5 @@
+export { WithUserflowReactNavigation } from './WithUserflowReactNavigation';
+export type { WithUserflowReactNavigationProps } from './WithUserflowReactNavigation';
+export { openFlowNavigateUrl, setHostOnNavigate, setReactNavigationRef, setExpoRouterNavigator, isExternalNavigateUrl, isInAppNavigateUrl, } from './openFlowNavigateUrl';
+export type { FlowNavigateHandler, ExpoRouterLike } from './openFlowNavigateUrl';
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/commonjs/src/navigation/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/navigation/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,2BAA2B,EAAE,MAAM,+BAA+B,CAAC;AAC5E,YAAY,EAAE,gCAAgC,EAAE,MAAM,+BAA+B,CAAC;AACtF,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,qBAAqB,EACrB,sBAAsB,EACtB,qBAAqB,EACrB,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC"}

package/lib/typescript/commonjs/src/navigation/openFlowNavigateUrl.d.ts

@@ -0,0 +1,33 @@
+import type { NavigationContainerRef, ParamListBase } from '@react-navigation/native';
+export type FlowNavigateHandler = (url: string) => void | boolean | Promise<void | boolean>;
+export type ExpoRouterLike = {
+    push: (href: string) => void;
+};
+/** Optional host escape hatch — wins over router / Linking when set. */
+export declare function setHostOnNavigate(handler: FlowNavigateHandler | null | undefined): void;
+/** Register the React Navigation container used by {@link WithUserflowReactNavigation}. */
+export declare function setReactNavigationRef(ref: NavigationContainerRef<ParamListBase> | null | undefined): void;
+/** Register Expo Router push for path-like NAVIGATE actions. */
+export declare function setExpoRouterNavigator(router: ExpoRouterLike | null | undefined): void;
+/** True for http(s) / mailto / tel (external). */
+export declare function isExternalNavigateUrl(url: string): boolean;
+/** Path-like in-app URL: leading slash, or no scheme. */
+export declare function isInAppNavigateUrl(url: string): boolean;
+/**
+ * Open a flow NAVIGATE url.
+ *
+ * Priority:
+ * 1. Host `onNavigate` (custom schemes / exotic routing)
+ * 2. External allowlisted schemes → Linking / `openSafeUrl`
+ * 3. Path-like → Expo Router `push` or React Navigation `navigate`
+ * 4. Fallback → Linking (best-effort)
+ *
+ * Note: screen tracking ≠ action routing. React Navigation hosts must wrap with
+ * `WithUserflowReactNavigation` for in-app NAVIGATE; Expo Router apps get a
+ * navigator handle when the host mounts `UserflowExpoRouterScreenTracker` from
+ * `@userflow-tech/react-native/expo-router` under `UserflowProvider`.
+ */
+export declare function openFlowNavigateUrl(url: string): Promise<void>;
+/** @internal */
+export declare function resetFlowNavigateRegistryForTests(): void;
+//# sourceMappingURL=openFlowNavigateUrl.d.ts.map

package/lib/typescript/commonjs/src/navigation/openFlowNavigateUrl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openFlowNavigateUrl.d.ts","sourceRoot":"","sources":["../../../../../src/navigation/openFlowNavigateUrl.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAKtF,MAAM,MAAM,mBAAmB,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,GAAG,OAAO,CAAC,IAAI,GAAG,OAAO,CAAC,CAAC;AAE5F,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B,CAAC;AAMF,wEAAwE;AACxE,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,mBAAmB,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAEvF;AAED,2FAA2F;AAC3F,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,sBAAsB,CAAC,aAAa,CAAC,GAAG,IAAI,GAAG,SAAS,GAC5D,IAAI,CAEN;AAED,gEAAgE;AAChE,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAEtF;AAED,kDAAkD;AAClD,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED,yDAAyD;AACzD,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAMvD;AAcD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAiCpE;AAED,gBAAgB;AAChB,wBAAgB,iCAAiC,IAAI,IAAI,CAIxD"}

package/lib/typescript/commonjs/src/network.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Network reachability → eager liveness check (optional enhancement).
+ *
+ * When connectivity returns while the app is foregrounded (and the transport is
+ * not suspended), call {@link NetworkControllerDeps.ensureAlive} so we do not
+ * wait for the adaptive heartbeat / foreground probe to notice the drop.
+ * `ensureAlive` probes a still-open (possibly half-dead) socket and reconnects
+ * eagerly when the transport is already dropped — covering both cases.
+ *
+ * This is layered on top of a complete zero-dependency recovery path (socket
+ * close → reconnect ladder, adaptive heartbeat, and the foreground liveness
+ * probe). `@react-native-community/netinfo` is therefore an *optional* peer: when
+ * present it makes offline→online recovery fast; when absent the baseline still
+ * recovers within a few seconds of the next beat / foreground return.
+ */
+export interface NetworkStatus {
+    isConnected: boolean | null;
+    /** `null` means unknown — treat as reachable when connected. */
+    isInternetReachable: boolean | null;
+}
+export interface NetworkControllerDeps {
+    ensureAlive: () => void;
+    /** Override for tests; defaults to `@react-native-community/netinfo`. */
+    subscribe?: (handler: (status: NetworkStatus) => void) => () => void;
+}
+/**
+ * Owns the NetInfo subscription. Call {@link start} from `Userflow.init` and
+ * {@link stop} from `Userflow.teardown`.
+ */
+export declare class NetworkController {
+    private readonly ensureAlive;
+    private readonly subscribe;
+    private unsubscribe;
+    private started;
+    private wasOnline;
+    constructor(deps: NetworkControllerDeps);
+    start(): void;
+    stop(): void;
+    /** Visible for tests. */
+    handleStatus(status: NetworkStatus): void;
+}
+//# sourceMappingURL=network.d.ts.map

package/lib/typescript/commonjs/src/network.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"network.d.ts","sourceRoot":"","sources":["../../../../src/network.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,OAAO,GAAG,IAAI,CAAC;IAC5B,gEAAgE;IAChE,mBAAmB,EAAE,OAAO,GAAG,IAAI,CAAC;CACrC;AAED,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,MAAM,IAAI,CAAC;IACxB,yEAAyE;IACzE,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,IAAI,KAAK,MAAM,IAAI,CAAC;CACtE;AAuCD;;;GAGG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAa;IACzC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA2D;IAErF,OAAO,CAAC,WAAW,CAA6B;IAChD,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,SAAS,CAAwB;gBAE7B,IAAI,EAAE,qBAAqB;IAKvC,KAAK,IAAI,IAAI;IAQb,IAAI,IAAI,IAAI;IAQZ,yBAAyB;IACzB,YAAY,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI;CAa1C"}

package/lib/typescript/commonjs/src/pairing/PairingController.d.ts

@@ -0,0 +1,104 @@
+import { PairingEngine, type PairingEngineState, type UserflowCore } from '@userflow-tech/core';
+import { type AppStateStatus } from 'react-native';
+import { type PairingLogger } from './diagnostics';
+import { type PairingTokenStore } from './tokenStorage';
+export type PairingControllerListener = (state: PairingEngineState) => void;
+export interface PairingControllerOptions {
+    core: UserflowCore;
+    /** Override pairing host (local/staging). Defaults to US-pinned production. */
+    pairingEndpoint?: string;
+    tokenStore?: PairingTokenStore;
+    /** Clear mid-flow session when exiting preview. */
+    clearLocalSession?: () => void;
+    LinkingModule?: {
+        getInitialURL(): Promise<string | null>;
+        addEventListener(type: 'url', handler: (event: {
+            url: string;
+        }) => void): {
+            remove(): void;
+        };
+    };
+    AppStateModule?: {
+        addEventListener(type: 'change', handler: (state: AppStateStatus) => void): {
+            remove(): void;
+        };
+    };
+    /** Sink for pairing diagnostics. Injected in tests. */
+    logger?: PairingLogger;
+}
+/**
+ * Inbound deep links → pairing session → preview mode.
+ * Active in all builds (including release); security is the short-lived
+ * signed pairing JWT + Builder ability checks, not `__DEV__`.
+ */
+export declare class PairingController {
+    private engine;
+    private started;
+    private urlSub;
+    private appStateSub;
+    private readonly listeners;
+    private readonly tokenStore;
+    private readonly LinkingModule;
+    private readonly AppStateModule;
+    private readonly clearLocalSession;
+    private readonly core;
+    private readonly pairingEndpoint;
+    private readonly logger;
+    private initPhase;
+    private initFailureReason;
+    /** Pairing token captured before init resolved, replayed once it does. */
+    private deferredPairingToken;
+    /** Diagnostics already emitted for the current init attempt. */
+    private readonly loggedOnce;
+    constructor(options: PairingControllerOptions);
+    getEngine(): PairingEngine | null;
+    /** Whether deep-link / AppState listeners have been started. */
+    hasStarted(): boolean;
+    getState(): PairingEngineState;
+    /**
+     * State for a link we captured but cannot act on because init failed. Without
+     * this the host app shows no sign that a pairing link was ever received.
+     */
+    private blockedState;
+    onStateChange(listener: PairingControllerListener): () => void;
+    /**
+     * Start deep-link listeners. Safe to call multiple times, and never rejects —
+     * `Userflow.init` fires it without awaiting, so a rejection here would become
+     * an unhandled promise rejection.
+     */
+    start(): Promise<void>;
+    private startListening;
+    stop(): void;
+    /**
+     * Host apps that intercept deep links themselves can forward them here.
+     */
+    handleUrl(url: string): Promise<boolean>;
+    /**
+     * Called when `Userflow.init()` begins. Clears a previous failure so a retried
+     * init does not keep reporting the old error.
+     */
+    notifyInitStarted(): void;
+    /**
+     * Called when `Userflow.init()` resolves. Connects a link that arrived while
+     * init was still in flight.
+     */
+    notifyInitialized(): Promise<void>;
+    /**
+     * Called when `Userflow.init()` rejects. Pairing cannot connect without a
+     * session, so surface why instead of failing silently.
+     */
+    notifyInitFailed(error: unknown): void;
+    /**
+     * Log `message` at most once per init attempt. Inbound links can repeat (URL
+     * event plus host forwarding), and these messages are several lines long.
+     */
+    private warnOnce;
+    /** Explicit entry with a raw pairing JWT (tests / advanced hosts). */
+    enterPreview(pairingToken: string): Promise<void>;
+    exitPreview(): Promise<void>;
+    /** Flush queued startFlowWithToken after identify. */
+    notifyIdentified(): void;
+    private ensureEngine;
+    private emit;
+}
+//# sourceMappingURL=PairingController.d.ts.map

package/lib/typescript/commonjs/src/pairing/PairingController.d.ts.map

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

package/lib/typescript/commonjs/src/pairing/PreviewModeBanner.d.ts

@@ -0,0 +1,11 @@
+import type { PairingEngineState } from '@userflow-tech/core';
+import * as React from 'react';
+export interface PreviewModeBannerProps {
+    state: PairingEngineState;
+    onExit: () => void;
+}
+/**
+ * Overlay chrome for Builder pairing preview mode.
+ */
+export declare function PreviewModeBanner({ state, onExit, }: PreviewModeBannerProps): React.ReactElement | null;
+//# sourceMappingURL=PreviewModeBanner.d.ts.map

package/lib/typescript/commonjs/src/pairing/PreviewModeBanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PreviewModeBanner.d.ts","sourceRoot":"","sources":["../../../../../src/pairing/PreviewModeBanner.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC9D,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAG/B,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,kBAAkB,CAAC;IAC1B,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,KAAK,EACL,MAAM,GACP,EAAE,sBAAsB,GAAG,KAAK,CAAC,YAAY,GAAG,IAAI,CAgEpD"}

package/lib/typescript/commonjs/src/pairing/deepLink.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Parse Builder pairing deep links:
+ *   {scheme_id}://?pairing_token=<jwt>
+ *
+ * `scheme_id` is typically `userflow-<digits>`.
+ */
+export interface PairingDeepLink {
+    scheme: string;
+    pairingToken: string;
+}
+/**
+ * Why a URL was not treated as a pairing link.
+ *
+ * `bad-scheme-shape` and `missing-token` are only reported for URLs that
+ * actually target pairing (root with a `pairing_token` query), so callers can
+ * tell a misconfigured pairing attempt apart from an unrelated link. See
+ * {@link isPairingAttempt}.
+ */
+export type PairingDeepLinkRejection = 'not-userflow' | 'foreign-scheme' | 'bad-scheme-shape' | 'unparseable' | 'not-pair-path' | 'missing-token';
+/**
+ * Rejections where the URL was a recognisable pairing attempt that could not be
+ * used. These are worth reporting; everything else belongs to the host app.
+ */
+export type PairingAttemptRejection = 'foreign-scheme' | 'bad-scheme-shape' | 'missing-token';
+export type PairingDeepLinkResult = {
+    ok: true;
+    link: PairingDeepLink;
+} | {
+    ok: false;
+    reason: PairingDeepLinkRejection;
+};
+/**
+ * True when a rejected URL was nonetheless a recognisable pairing attempt rather
+ * than someone else's deep link.
+ *
+ * Callers use this to decide whether a rejection is worth reporting. Preview
+ * links accept any `userflow-*` scheme, so scheme shape alone cannot be the
+ * signal — reporting on it would flag valid preview links as broken pairing.
+ */
+export declare function isPairingAttempt(reason: PairingDeepLinkRejection): reason is PairingAttemptRejection;
+/**
+ * Parse `url` as a pairing deep link, reporting why it was rejected.
+ * Prefer this over {@link parsePairingDeepLink} when the reason matters.
+ */
+export declare function inspectPairingDeepLink(url: string | null | undefined): PairingDeepLinkResult;
+/**
+ * Returns pairing token details when `url` is a Userflow pairing deep link.
+ * Accepts only `userflow-*` schemes.
+ */
+export declare function parsePairingDeepLink(url: string | null | undefined): PairingDeepLink | null;
+/** True when the URL looks like a Userflow pairing deep link. */
+export declare function isUserflowPairingUrl(url: string | null | undefined): boolean;
+//# sourceMappingURL=deepLink.d.ts.map

package/lib/typescript/commonjs/src/pairing/deepLink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deepLink.d.ts","sourceRoot":"","sources":["../../../../../src/pairing/deepLink.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;CACtB;AAMD;;;;;;;GAOG;AACH,MAAM,MAAM,wBAAwB,GAChC,cAAc,GACd,gBAAgB,GAChB,kBAAkB,GAClB,aAAa,GACb,eAAe,GACf,eAAe,CAAC;AAEpB;;;GAGG;AACH,MAAM,MAAM,uBAAuB,GAAG,gBAAgB,GAAG,kBAAkB,GAAG,eAAe,CAAC;AAE9F,MAAM,MAAM,qBAAqB,GAC7B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,eAAe,CAAA;CAAE,GACnC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,wBAAwB,CAAA;CAAE,CAAC;AAEpD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,wBAAwB,GAC/B,MAAM,IAAI,uBAAuB,CAEnC;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,qBAAqB,CAqD5F;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,eAAe,GAAG,IAAI,CAG3F;AAED,iEAAiE;AACjE,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAE5E"}

package/lib/typescript/commonjs/src/pairing/diagnostics.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Diagnostics for Builder pairing deep links.
+ *
+ * Pairing failures are unusually easy to miss. The URL scheme is registered in
+ * the native project at build time, so the OS launches the host app from a
+ * Builder QR code whether or not the SDK is listening. When the SDK then drops
+ * the link, the app looks like it simply "opened and did nothing".
+ *
+ * Every drop path routes through a message below so the reason is visible.
+ */
+import type { PairingAttemptRejection } from './deepLink';
+/** Sink for pairing diagnostics. Injected in tests. */
+export type PairingLogger = (message: string) => void;
+/**
+ * Default logger. Pairing links only ever arrive from a deliberate developer
+ * action (scanning or opening a Builder QR code), so these warn unconditionally
+ * rather than behind `__DEV__` — a swallowed pairing link is otherwise
+ * undiagnosable, and this cannot fire for real end users.
+ */
+export declare const defaultPairingLogger: PairingLogger;
+/** A pairing link arrived while `Userflow.init()` was still in flight. */
+export declare function pairingLinkDeferredMessage(): string;
+/**
+ * A pairing link arrived but `Userflow.init()` rejected, so there is no session
+ * to attach the preview to.
+ */
+export declare function pairingLinkInitFailedMessage(reason: string): string;
+/**
+ * Pairing was reachable but the connection itself failed (expired token, device
+ * already paired, backend unreachable). Never fatal to the host app.
+ */
+export declare function pairingConnectFailedMessage(reason: string): string;
+/** A pairing link arrived without the `pairing_token` query parameter. */
+export declare function pairingMissingTokenMessage(url: string): string;
+/**
+ * A pairing link arrived on a scheme Userflow does not own — almost always the
+ * host app's own scheme substituted for the environment's `scheme_id`.
+ */
+export declare function pairingForeignSchemeMessage(url: string): string;
+/** Message for a pairing attempt that could not be used. */
+export declare function pairingAttemptRejectionMessage(reason: PairingAttemptRejection, url: string): string;
+/** Clearing the persisted pairing token failed. Best-effort, never fatal. */
+export declare function pairingTokenStoreClearFailedMessage(reason: string): string;
+/** Attaching the deep-link listeners failed, which disables pairing entirely. */
+export declare function pairingListenerSetupFailedMessage(reason: string): string;
+/**
+ * The URL used a `userflow-` scheme that is not a valid `scheme_id`. Pairing
+ * requires `userflow-` followed by digits, so an arbitrary `userflow-*` scheme
+ * can match preview links but not pairing ones.
+ */
+export declare function pairingSchemeShapeMessage(url: string): string;
+//# sourceMappingURL=diagnostics.d.ts.map

package/lib/typescript/commonjs/src/pairing/diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../../../../src/pairing/diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAY1D,uDAAuD;AACvD,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;AAEtD;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,EAAE,aAGlC,CAAC;AAEF,0EAA0E;AAC1E,wBAAgB,0BAA0B,IAAI,MAAM,CAKnD;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAMnE;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAKlE;AAED,0EAA0E;AAC1E,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAM9D;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAS/D;AAED,4DAA4D;AAC5D,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,uBAAuB,EAC/B,GAAG,EAAE,MAAM,GACV,MAAM,CASR;AAED,6EAA6E;AAC7E,wBAAgB,mCAAmC,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAK1E;AAED,iFAAiF;AACjF,wBAAgB,iCAAiC,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAKxE;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAM7D"}