@getuserfeedback/react-native 5.12.0 → 5.14.1

package/README.md

@@ -1,17 +1,35 @@
 # @getuserfeedback/react-native
 
-In-product surveys for React Native apps, from [getuserfeedback.com](https://getuserfeedback.com).
+Add in-product surveys, forms, and messages to React Native applications with
+[getuserfeedback.com](https://getuserfeedback.com).
 
 ## Get started
 
-Install the SDK and its WebView peer dependency:
+Install the SDK and its WebView peer dependency.
+
+For Expo projects:
+
+```bash
+npm install @getuserfeedback/react-native
+npx expo install react-native-webview
+```
+
+For other React Native projects:
 
 ```bash
 npm install @getuserfeedback/react-native react-native-webview
 ```
 
-Add the provider near the root of your app. You can find your Public API key in
-[Widget settings](https://getuserfeedback.com/app/_/settings/widget).
+Then link the native dependency in bare iOS projects:
+
+```bash
+npx pod-install
+```
+
+Requires React 18, React Native 0.73, and React Native WebView 13 or later.
+
+Mount the provider near the root of your app using the Public API key from
+[Widget settings](https://getuserfeedback.com/app/_/settings/widget):
 
 ```tsx
 import { GetUserFeedbackProvider } from "@getuserfeedback/react-native";
@@ -25,8 +43,9 @@ export function App() {
 }
 ```
 
-That's it. Flows configured for automatic Widget delivery now appear based on
-the targeting rules you set in the dashboard.
+That is enough to receive flows published for automatic Widget delivery.
 
-For user identity, manual flow controls, and troubleshooting, read the
-[React Native SDK guide](https://getuserfeedback.com/docs/get-started/react-native-sdk).
+- [React Native SDK guide](https://getuserfeedback.com/docs/get-started/react-native-sdk)
+- [React Native SDK reference](https://getuserfeedback.com/docs/reference/react-native-sdk-reference)
+- [Package versions](https://www.npmjs.com/package/@getuserfeedback/react-native?activeTab=versions)
+- [Support](mailto:hello@getuserfeedback.com)

package/dist/client.d.ts

@@ -1,6 +1,6 @@
 import type { AppEventExternalId, PublicCommandPayload } from "@getuserfeedback/protocol";
-import type { ActionRegistration, CapabilitiesInput, ConfigureOptions, EventOptions, EventProperties, FlagsInput, GraphOperations, InitOptions, OpenRequestedCallback } from "@getuserfeedback/sdk";
-export type { CapabilitiesInput, ConfigureOptions, EventOptions, EventProperties, FlagsInput, GraphOperations, GraphRelationship, GraphRelationshipRef, OpenRequestedCallback, OpenRequestedEvent, TrackOptions, } from "@getuserfeedback/sdk";
+import type { ActionRegistration, ActionsConfig, CapabilitiesInput, ConfigureOptions, EventOptions, EventProperties, FlagsInput, GraphOperations, InitOptions, LinksConfig, OpenRequestedCallback } from "@getuserfeedback/sdk";
+export type { ActionsConfig, CapabilitiesInput, ConfigureOptions, EventOptions, EventProperties, FlagsInput, GraphOperations, GraphRelationship, GraphRelationshipRef, LinkRequest, LinkRouter, LinksConfig, OpenRequestedCallback, OpenRequestedEvent, TrackOptions, } from "@getuserfeedback/sdk";
 type IdentifyTraits = Record<string, unknown>;
 type OpenCommand = Extract<PublicCommandPayload, {
     kind: "open";
@@ -26,8 +26,13 @@ export type NativeActionRegistration = Extract<ActionRegistration, {
 }>;
 /** React Native provider initialization options. */
 export type ClientOptions = Omit<InitOptions, "capabilities" | "clientMeta" | "flags" | "hostActions" | "hostCapabilities" | "runtimeEndpoints"> & {
-    /** Widget actions implemented by the current app version. */
-    actions?: NativeActionRegistration[] | undefined;
+    /** Routes authored HTTP(S) links through the native app. */
+    links?: LinksConfig | undefined;
+    /**
+     * Widget actions implemented by the current app version. Prefer the grouped
+     * configuration; the registration array remains for compatibility.
+     */
+    actions?: ActionsConfig | NativeActionRegistration[] | undefined;
     /** Capabilities supported by the current app version. */
     capabilities?: CapabilitiesInput | undefined;
     /** Feature flag evaluations supplied during initialization. */
@@ -68,19 +73,35 @@ export interface Client {
      */
     readonly instanceId: string;
     /**
-     * Updates authentication, consent, and other client configuration.
+     * Updates authentication, consent, and other client configuration. Await the
+     * returned promise or handle its rejection when applying runtime updates.
      *
      * @see https://getuserfeedback.com/docs/security-and-privacy/jwt-auth
      */
     configure: (opts: ConfigureOptions, options?: CommandOptions) => Promise<void>;
+    /**
+     * Associates the current user with a user ID, traits, and optional external
+     * IDs. Some invalid arguments throw synchronously; other validation or
+     * command-processing failures reject the returned promise.
+     *
+     * @see https://getuserfeedback.com/docs/guides/identity-resolution
+     */
     identify: {
         (userId: string, traits?: IdentifyTraits, options?: IdentifyOptions): Promise<void>;
         (traits: IdentifyTraits, placeholder: undefined, options?: IdentifyOptions): Promise<void>;
         (traits: IdentifyTraits, options?: IdentifyOptions): Promise<void>;
     };
-    /** Records a product event for targeting and analysis. */
+    /**
+     * Records a product event for targeting and analysis. Some invalid arguments
+     * throw synchronously; other validation or command-processing failures reject
+     * the returned promise.
+     */
     track: (eventName: string, properties?: EventProperties, options?: EventOptions) => Promise<void>;
-    /** Records a named application screen for targeting and analysis. */
+    /**
+     * Records a named application screen for targeting and analysis. Some invalid
+     * arguments throw synchronously; other validation or command-processing
+     * failures reject the returned promise.
+     */
     screen: (name: string, properties?: EventProperties, options?: EventOptions) => Promise<void>;
     /** Records directed relationship observations through the analytics pipeline. */
     graph: GraphOperations;
@@ -104,6 +125,6 @@ export interface Client {
      * ```
      */
     onOpenRequested: (callback: OpenRequestedCallback) => () => void;
-    /** Resets widget state, authentication, and the current user identity. */
+    /** Closes all open flows, clears JWT authentication, and resets user identity. */
     reset: (options?: CommandOptions) => Promise<void>;
 }

package/dist/core-webview-host.js

@@ -47,7 +47,7 @@ function CoreWebViewHostDocument({ externalCoreUrl, onConnected, onActivationRet
     const controller = controllerRef.current;
     const buildDocumentStartScript = useMemo(() => () => buildCoreWebViewBridgeScript({ bridgeId, phase: "documentStart" }), [bridgeId]);
     const source = useMemo(() => ({ uri: externalCoreUrl }), [externalCoreUrl]);
-    return createElement((WebViewDocumentHost), {
+    return createElement(WebViewDocumentHost, {
         buildDocumentStartScript,
         controller,
         parseMessage: parseCoreWebViewBridgeMessage,

package/dist/flow-container.js

@@ -22,10 +22,7 @@ const renderProjection = (projection, presentationMode) => {
     return createElement(NativeViewHostProjection, Object.assign(Object.assign({}, props), { key,
         presentationMode }));
 };
-const useRecords = (projection) => {
-    var _a, _b, _c;
-    return useSyncExternalStore((_a = projection === null || projection === void 0 ? void 0 : projection.controller.subscribe) !== null && _a !== void 0 ? _a : subscribeNoop, (_b = projection === null || projection === void 0 ? void 0 : projection.controller.getSnapshot) !== null && _b !== void 0 ? _b : getEmptyRecords, (_c = projection === null || projection === void 0 ? void 0 : projection.controller.getSnapshot) !== null && _c !== void 0 ? _c : getEmptyRecords);
-};
+const useRecords = (projection) => { var _a, _b, _c; return useSyncExternalStore((_a = projection === null || projection === void 0 ? void 0 : projection.controller.subscribe) !== null && _a !== void 0 ? _a : subscribeNoop, (_b = projection === null || projection === void 0 ? void 0 : projection.controller.getSnapshot) !== null && _b !== void 0 ? _b : getEmptyRecords, (_c = projection === null || projection === void 0 ? void 0 : projection.controller.getSnapshot) !== null && _c !== void 0 ? _c : getEmptyRecords); };
 export function NativeStandardFlowContainer() {
     const context = useContext(NativeFlowContainerContext);
     return (context === null || context === void 0 ? void 0 : context.contentOwner) === null

package/dist/native-core-command-channel.d.ts

@@ -3,6 +3,7 @@ import { type EventHandleInvalidated } from "@getuserfeedback/protocol/internal/
 import { type EventCommandSettled } from "@getuserfeedback/protocol/internal/core-host-command-settlement";
 import type { CoreWebViewHostConnection } from "./core-webview-host-controller.js";
 import { createNativeHostActionRpcHandler } from "./native-host-action-rpc.js";
+import { createNativeLinkRouterRpcHandler } from "./native-link-router-rpc.js";
 export type NativeCoreCommandChannel = {
     post: (envelope: CoreCommandEnvelope) => void;
     subscribe: (listener: (message: EventCommandSettled) => void) => () => void;
@@ -19,6 +20,12 @@ export declare function createNativeCoreCommandChannel(input: {
         instanceId: string;
         subscribeToViewActivity: (listener: () => void) => () => void;
     };
+    linkRouter?: {
+        getActiveViewIds: () => readonly string[];
+        getRouter: Parameters<typeof createNativeLinkRouterRpcHandler>[0]["getRouter"];
+        instanceId: string;
+    };
+    now?: () => number;
     onHandleInvalidated?: (message: EventHandleInvalidated) => void;
     onHostActionError?: (error: Error) => void;
     onInvalidMessage?: (error: Error, value: unknown) => void;

package/dist/native-core-command-channel.js

@@ -4,6 +4,7 @@ import { eventCommandSettledSchema, } from "@getuserfeedback/protocol/internal/c
 import { CORE_SESSION_FAILED_CODE, eventCoreSessionFailedSchema, } from "@getuserfeedback/protocol/internal/core-session-failure";
 import { buildRpcResponse, rpcRequestSchema, } from "@getuserfeedback/protocol/internal/v3-rpc-messages";
 import { createNativeHostActionRpcHandler } from "./native-host-action-rpc.js";
+import { createNativeLinkRouterRpcHandler } from "./native-link-router-rpc.js";
 const DISPOSED_MESSAGE = "Core command channel is disposed";
 const isRecord = (value) => typeof value === "object" && value !== null;
 export function createNativeCoreCommandChannel(input) {
@@ -11,6 +12,7 @@ export function createNativeCoreCommandChannel(input) {
     const listeners = new Set();
     let disposed = false;
     const hostActions = input.hostActions;
+    const linkRouter = input.linkRouter;
     const hostActionRpcHandler = hostActions
         ? createNativeHostActionRpcHandler({
             generation: input.coreConnection.generation,
@@ -31,6 +33,17 @@ export function createNativeCoreCommandChannel(input) {
         }
         activeViewIds = nextActiveViewIds;
     });
+    const linkRouterRpcHandler = linkRouter
+        ? createNativeLinkRouterRpcHandler({
+            generation: input.coreConnection.generation,
+            getRouter: linkRouter.getRouter,
+            instanceId: linkRouter.instanceId,
+            isViewActive: (viewId) => linkRouter.getActiveViewIds().includes(viewId),
+            now: input.now,
+            onError: input.onHostActionError,
+            postToCore: input.coreConnection.transport.postMessage,
+        })
+        : null;
     const handleMessage = (value) => {
         var _a, _b, _c, _d, _e, _f;
         if (disposed || !isRecord(value)) {
@@ -45,6 +58,9 @@ export function createNativeCoreCommandChannel(input) {
             if (hostActionRpcHandler === null || hostActionRpcHandler === void 0 ? void 0 : hostActionRpcHandler.handle(parsed.data)) {
                 return;
             }
+            if (linkRouterRpcHandler === null || linkRouterRpcHandler === void 0 ? void 0 : linkRouterRpcHandler.handle(parsed.data)) {
+                return;
+            }
             let result;
             if (parsed.data.method === TRAFFIC_TELEMETRY_RPC_METHOD) {
                 const params = trafficTelemetryRpcParamsSchema.safeParse(parsed.data.params);
@@ -161,6 +177,7 @@ export function createNativeCoreCommandChannel(input) {
             disposed = true;
             unsubscribeViewActivity === null || unsubscribeViewActivity === void 0 ? void 0 : unsubscribeViewActivity();
             hostActionRpcHandler === null || hostActionRpcHandler === void 0 ? void 0 : hostActionRpcHandler.dispose();
+            linkRouterRpcHandler === null || linkRouterRpcHandler === void 0 ? void 0 : linkRouterRpcHandler.dispose();
             unsubscribeTransport();
             listeners.clear();
         },

package/dist/native-flow-container-context.d.ts

@@ -1,14 +1,17 @@
 import type { Client } from "./client.js";
+import type { NativeProviderFlowRegistry } from "./native-provider-flow-registry.js";
 import type { NativeViewProjection } from "./native-view-host-projection.js";
 export type NativeFlowContainerContextValue = Readonly<{
     client: Client;
     contentOwner: object | null;
+    flowRegistry: NativeProviderFlowRegistry;
     projection: NativeViewProjection | null;
     registerContent: (owner: object) => () => void;
 }>;
 export declare const NativeFlowContainerContext: import("react").Context<Readonly<{
     client: Client;
     contentOwner: object | null;
+    flowRegistry: NativeProviderFlowRegistry;
     projection: NativeViewProjection | null;
     registerContent: (owner: object) => () => void;
 }> | null>;

package/dist/native-link-router-rpc.d.ts

@@ -0,0 +1,14 @@
+import type { LinkRouter } from "@getuserfeedback/protocol/host";
+import { type RpcRequest } from "@getuserfeedback/protocol/internal/v3-rpc-messages";
+export declare const createNativeLinkRouterRpcHandler: (input: {
+    generation: number;
+    getRouter: () => LinkRouter | undefined;
+    instanceId: string;
+    isViewActive: (viewId: string) => boolean;
+    now?: () => number;
+    onError?: (error: Error) => void;
+    postToCore: (message: unknown) => void;
+}) => {
+    dispose: () => void;
+    handle: (request: RpcRequest) => boolean;
+};

package/dist/native-link-router-rpc.js

@@ -0,0 +1,163 @@
+import { buildFlowActionSucceededV1 } from "@getuserfeedback/protocol";
+import { buildEventFlowActionSucceeded } from "@getuserfeedback/protocol/internal/host-core-flow-action-succeeded";
+import { BROWSER_NAVIGATION_AVAILABILITY_RPC_METHOD, BROWSER_NAVIGATION_OPEN_RPC_METHOD, toBrowserNavigationOpenParams, } from "@getuserfeedback/protocol/internal/navigation-rpc";
+import { buildRpcResponse, } from "@getuserfeedback/protocol/internal/v3-rpc-messages";
+import { invokeLinkRouter } from "@getuserfeedback/sdk/internal/link-router";
+const MAX_SETTLED_NAVIGATION_INVOCATIONS = 256;
+export const createNativeLinkRouterRpcHandler = (input) => {
+    const invocations = new Map();
+    let disposed = false;
+    const reportError = (error) => {
+        var _a;
+        try {
+            (_a = input.onError) === null || _a === void 0 ? void 0 : _a.call(input, error instanceof Error ? error : new Error(String(error)));
+        }
+        catch (_b) {
+            // Diagnostics cannot change navigation settlement.
+        }
+    };
+    const postToCore = (message) => {
+        try {
+            input.postToCore(message);
+        }
+        catch (error) {
+            reportError(error);
+        }
+    };
+    const respond = (request, handled) => {
+        postToCore(buildRpcResponse({
+            gen: request.gen,
+            ok: true,
+            result: { handled },
+            rpcId: request.rpcId,
+            viewId: request.viewId,
+        }));
+    };
+    const reportSuccess = (request, params) => {
+        var _a;
+        const definition = params.definition;
+        const invocationId = params.invocationId;
+        const seed = params.flowActionSucceededSeed;
+        if (!definition || !invocationId || !seed)
+            return;
+        try {
+            postToCore(buildEventFlowActionSucceeded({
+                event: buildFlowActionSucceededV1({
+                    actionInvocationId: invocationId,
+                    actionKey: definition.key,
+                    actionKind: seed.actionKind,
+                    actionPlacementId: seed.actionPlacementId,
+                    actionVersion: definition.version,
+                    flowId: seed.flowId,
+                    flowRunId: seed.flowRunId,
+                    flowSurface: "widget",
+                    flowVersionId: seed.flowVersionId,
+                    flowVersionNumber: seed.flowVersionNumber,
+                }),
+                gen: request.gen,
+                instanceId: input.instanceId,
+                timestamp: ((_a = input.now) !== null && _a !== void 0 ? _a : Date.now)(),
+            }));
+        }
+        catch (error) {
+            reportError(error);
+        }
+    };
+    const trimSettledInvocations = () => {
+        if (invocations.size <= MAX_SETTLED_NAVIGATION_INVOCATIONS)
+            return;
+        for (const [invocationId, invocation] of invocations) {
+            if (invocation.handled === undefined)
+                continue;
+            invocations.delete(invocationId);
+            return;
+        }
+    };
+    return {
+        dispose: () => {
+            disposed = true;
+            invocations.clear();
+        },
+        handle: (request) => {
+            if (disposed)
+                return false;
+            if (request.method === BROWSER_NAVIGATION_AVAILABILITY_RPC_METHOD) {
+                postToCore(buildRpcResponse({
+                    gen: request.gen,
+                    ok: true,
+                    result: { available: input.getRouter() !== undefined },
+                    rpcId: request.rpcId,
+                    viewId: request.viewId,
+                }));
+                return true;
+            }
+            if (request.method !== BROWSER_NAVIGATION_OPEN_RPC_METHOD)
+                return false;
+            const params = toBrowserNavigationOpenParams(request.params);
+            const trustedInvocationId = params !== null &&
+                params.definition !== undefined &&
+                params.flowActionSucceededSeed !== undefined &&
+                params.invocationId !== undefined
+                ? params.invocationId
+                : null;
+            const fingerprint = trustedInvocationId !== null
+                ? JSON.stringify({
+                    gen: request.gen,
+                    idemKey: request.idemKey,
+                    params,
+                    requestViewId: request.viewId,
+                })
+                : null;
+            if (trustedInvocationId !== null && fingerprint !== null) {
+                const existing = invocations.get(trustedInvocationId);
+                if (existing) {
+                    if (existing.fingerprint !== fingerprint) {
+                        respond(request, false);
+                    }
+                    else if (existing.handled === undefined) {
+                        existing.waiters.push(request);
+                    }
+                    else {
+                        respond(request, existing.handled);
+                    }
+                    return true;
+                }
+            }
+            const router = input.getRouter();
+            if (params === null ||
+                params.generation !== input.generation ||
+                !input.isViewActive(params.viewId) ||
+                router === undefined) {
+                respond(request, false);
+                return true;
+            }
+            let invocation = null;
+            if (trustedInvocationId !== null && fingerprint !== null) {
+                invocation = { fingerprint, waiters: [request] };
+                invocations.set(trustedInvocationId, invocation);
+            }
+            let handled = false;
+            try {
+                invokeLinkRouter(router, Object.assign({ url: params.url }, (params.target === undefined ? {} : { target: params.target })));
+                handled = true;
+            }
+            catch (error) {
+                reportError(error);
+            }
+            if (disposed)
+                return true;
+            if (invocation === null) {
+                respond(request, handled);
+                return true;
+            }
+            invocation.handled = handled;
+            for (const waiter of invocation.waiters.splice(0)) {
+                respond(waiter, handled);
+            }
+            if (handled)
+                reportSuccess(request, params);
+            trimSettledInvocations();
+            return true;
+        },
+    };
+};

package/dist/native-provider-client-controller.d.ts

@@ -7,6 +7,7 @@ export declare function createNativeProviderClientController(input: {
 }): {
     client: import("./client.js").Client;
     directSessionController: import("./native-direct-command-session-controller.js").NativeDirectCommandSessionController;
+    flowRegistry: import("./native-provider-flow-registry.js").NativeProviderFlowRegistry;
     getRuntimeConfiguration: () => ConfigureOptions;
     observeOpenRequest: (payload: Parameters<OpenRequestDispatcher["dispatch"]>[0]) => ReturnType<OpenRequestDispatcher["dispatch"]>;
     dispose: () => void;

package/dist/native-provider-client-controller.js

@@ -56,6 +56,7 @@ export function createNativeProviderClientController(input) {
     return {
         client,
         directSessionController: session,
+        flowRegistry: flows,
         getRuntimeConfiguration: () => (Object.assign({}, runtimeConfiguration)),
         observeOpenRequest,
         dispose: () => {

package/dist/native-provider-command-controller.js

@@ -19,7 +19,9 @@ export function createNativeProviderCommandController(input) {
         try {
             (_a = input.onError) === null || _a === void 0 ? void 0 : _a.call(input, error);
         }
-        catch (_b) { }
+        catch (_b) {
+            // Consumer error handlers must not replace the command failure.
+        }
         return error;
     };
     const observe = (promise) => promise.catch((error) => Promise.reject(report(error)));

package/dist/native-provider-flow-registry.d.ts

@@ -1,7 +1,14 @@
 import type { FlowRun } from "./client.js";
 import type { createNativeProviderCommandController } from "./native-provider-command-controller.js";
-export declare function createNativeProviderFlowRegistry(commands: ReturnType<typeof createNativeProviderCommandController>): {
+export type NativeFlowRegistryRecord = Readonly<{
+    flowId: string;
+    isOpening: boolean;
+}>;
+export type NativeProviderFlowRegistry = {
     flow: (flowId: string) => FlowRun;
+    getSnapshot: () => readonly NativeFlowRegistryRecord[];
+    subscribe: (listener: () => void) => () => void;
     invalidate: (handleId: string) => void;
     reset: () => void;
 };
+export declare function createNativeProviderFlowRegistry(commands: ReturnType<typeof createNativeProviderCommandController>): NativeProviderFlowRegistry;

package/dist/native-provider-flow-registry.js

@@ -5,8 +5,23 @@ const isStaleHandleError = (error) => error instanceof CommandSettlementError
     ? error.code === "STALE_HANDLE"
     : error instanceof Error && error.message.includes("flowHandleId is stale");
 export function createNativeProviderFlowRegistry(commands) {
+    const listeners = new Set();
+    let snapshot = Object.freeze([]);
+    const notify = () => {
+        snapshot = Object.freeze(Array.from(controllers.values(), ({ flowId, isOpening }) => Object.freeze({ flowId, isOpening })));
+        for (const listener of listeners)
+            listener();
+    };
     const create = (flowId) => {
         const openRequests = createFlowOpenRequestController();
+        let isOpening = false;
+        let openRevision = 0;
+        const setOpening = (next) => {
+            if (isOpening === next)
+                return;
+            isOpening = next;
+            notify();
+        };
         const handle = createFlowCommandHandleController({
             getHandleIdFromSettlement: (settlement) => { var _a; return (_a = getFlowHandleFromSettlementDetail(settlement)) === null || _a === void 0 ? void 0 : _a.flowHandleId; },
             isStaleHandleError,
@@ -22,6 +37,11 @@ export function createNativeProviderFlowRegistry(commands) {
                 return commands.reject(error);
             }
         };
+        const clearPendingOpen = () => {
+            openRevision += 1;
+            openRequests.clear();
+            setOpening(false);
+        };
         const run = {
             flowId,
             open: (options) => prepare(() => ({
@@ -29,7 +49,17 @@ export function createNativeProviderFlowRegistry(commands) {
                 hideCloseButton: options === null || options === void 0 ? void 0 : options.hideCloseButton,
                 kind: "open",
                 metadata: options === null || options === void 0 ? void 0 : options.metadata,
-            }), (command) => openRequests.run(() => allocation(command))),
+            }), (command) => {
+                openRevision += 1;
+                const revision = openRevision;
+                setOpening(true);
+                return openRequests
+                    .run(() => allocation(command))
+                    .finally(() => {
+                    if (openRevision === revision)
+                        setOpening(false);
+                });
+            }),
             prefetch: () => prepare(() => ({
                 flowId,
                 kind: "prefetch",
@@ -40,13 +70,21 @@ export function createNativeProviderFlowRegistry(commands) {
                 kind: "prerender",
             })),
             close: () => {
-                openRequests.clear();
+                clearPendingOpen();
                 return commands
                     .runOperation((dispatch) => handle.runResolvedHandleCommand((flowHandleId) => ({ flowHandleId, kind: "close" }), async (command) => void (await dispatch(command))))
                     .then(() => undefined);
             },
         };
-        return { clearPendingOpen: openRequests.clear, handle, run };
+        return {
+            clearPendingOpen,
+            flowId,
+            get isOpening() {
+                return isOpening;
+            },
+            handle,
+            run,
+        };
     };
     const controllers = new Map();
     return {
@@ -56,6 +94,11 @@ export function createNativeProviderFlowRegistry(commands) {
             controllers.set(flowId, current);
             return current.run;
         },
+        getSnapshot: () => snapshot,
+        subscribe: (listener) => {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
         invalidate: (handleId) => {
             for (const controller of controllers.values())
                 controller.handle.invalidateResolvedHandle(handleId);

package/dist/native-provider.d.ts

@@ -1,8 +1,10 @@
 import { type ComponentType, type ReactElement, type ReactNode } from "react";
 import type { Client, ClientOptions } from "./client.js";
-export type { CapabilitiesInput, Client, ClientOptions, ConfigureOptions, EventOptions, EventProperties, FlagsInput, FlowRun, GraphOperations, GraphRelationship, GraphRelationshipRef, NativeActionRegistration, OpenFlowOptions, OpenRequestedCallback, OpenRequestedEvent, PrerenderFlowOptions, TrackOptions, } from "./client.js";
+export type { ActionsConfig, CapabilitiesInput, Client, ClientOptions, ConfigureOptions, EventOptions, EventProperties, FlagsInput, FlowRun, GraphOperations, GraphRelationship, GraphRelationshipRef, LinkRequest, LinkRouter, LinksConfig, NativeActionRegistration, OpenFlowOptions, OpenRequestedCallback, OpenRequestedEvent, PrerenderFlowOptions, TrackOptions, } from "./client.js";
 export type { UseFlowContainerReturn } from "./flow-container.js";
 export { FlowContent, useFlowContainer } from "./flow-container.js";
+export type { UseFlowOpenOptions, UseFlowOptions, UseFlowReturn, } from "./use-flow.js";
+export { useFlow } from "./use-flow.js";
 /**
  * Custom WebView implementation used by the native runtime.
  *

package/dist/native-provider.js

@@ -12,6 +12,7 @@ var __rest = (this && this.__rest) || function (s, e) {
 import { parseInitOptions } from "@getuserfeedback/protocol";
 import { createUniqueId } from "@getuserfeedback/protocol/host";
 import { createActionRegistry, } from "@getuserfeedback/sdk/internal/action-registry";
+import { resolveLinkRouter } from "@getuserfeedback/sdk/internal/link-router";
 import { createContext, createElement, Fragment, useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState, } from "react";
 import { NativeStandardFlowContainer } from "./flow-container.js";
 import { NativeFlowContainerContext, } from "./native-flow-container-context.js";
@@ -19,6 +20,7 @@ import { createNativeProviderClientController } from "./native-provider-client-c
 import { REACT_NATIVE_PINNED_CORE_URL } from "./native-runtime-endpoints.js";
 import { NativeProviderRuntime } from "./native-runtime-root.js";
 export { FlowContent, useFlowContainer } from "./flow-container.js";
+export { useFlow } from "./use-flow.js";
 const GetUserFeedbackContext = createContext(null);
 const toClientOptionsKey = (value) => {
     if (value === null || typeof value !== "object") {
@@ -37,6 +39,20 @@ const toClientOptionsKey = (value) => {
 const compareClientOptionsKeys = (left, right) => left < right ? -1 : left > right ? 1 : 0;
 const haveSameActionRegistrations = (left, right) => left.length === right.length &&
     left.every((identity, index) => identity === right[index]);
+const useNativeLinkRouter = (links) => {
+    const router = resolveLinkRouter(links);
+    const hasRouterRef = useRef(router !== undefined);
+    if (hasRouterRef.current !== (router !== undefined)) {
+        throw new Error("links.router presence cannot change after provider mount; keep the router configured for the provider lifetime");
+    }
+    const routerRef = useRef(router);
+    useLayoutEffect(() => {
+        routerRef.current = router;
+    }, [router]);
+    return {
+        getRouter: useCallback(() => routerRef.current, []),
+    };
+};
 const useNativeActionRegistry = (actions) => {
     const nextRegistry = createActionRegistry(actions);
     if (nextRegistry.getOpenUrlHandler() !== undefined) {
@@ -69,7 +85,7 @@ const toInitFlags = (flags) => {
     return normalizedFlags.length === 0 ? undefined : normalizedFlags;
 };
 const parseNativeInitOptions = (_a, hostActions) => {
-    var { actions: _actions, capabilities, flags } = _a, clientOptions = __rest(_a, ["actions", "capabilities", "flags"]);
+    var { actions: _actions, capabilities, flags, links: _links } = _a, clientOptions = __rest(_a, ["actions", "capabilities", "flags", "links"]);
     const normalizedFlags = toInitFlags(flags);
     const initOptions = parseInitOptions(Object.assign(Object.assign(Object.assign(Object.assign({}, clientOptions), (normalizedFlags === undefined ? {} : { flags: normalizedFlags })), (hostActions !== undefined && hostActions.length > 0
         ? { hostActions }
@@ -91,7 +107,8 @@ const parseNativeInitOptions = (_a, hostActions) => {
             : normalizedHostCapabilities });
 };
 export function GetUserFeedbackProvider({ children, clientOptions, instanceId: instanceIdProp, onError, webViewComponent, }) {
-    var _a, _b;
+    var _a;
+    var _b;
     const [instanceId] = useState(() => {
         const normalizedInstanceId = instanceIdProp === null || instanceIdProp === void 0 ? void 0 : instanceIdProp.trim();
         return normalizedInstanceId && normalizedInstanceId.length > 0
@@ -102,6 +119,7 @@ export function GetUserFeedbackProvider({ children, clientOptions, instanceId: i
     const [projection, setProjection] = useState(null);
     const contentOwnerRef = useRef(null);
     const actionRegistry = useNativeActionRegistry(clientOptions.actions);
+    const linkRouter = useNativeLinkRouter(clientOptions.links);
     const normalizedClientOptions = parseNativeInitOptions(clientOptions, actionRegistry.definitions);
     const clientOptionsKey = toClientOptionsKey(normalizedClientOptions);
     const coreUrl = (_b = (_a = normalizedClientOptions.runtimeEndpoints) === null || _a === void 0 ? void 0 : _a.coreUrl) !== null && _b !== void 0 ? _b : REACT_NATIVE_PINNED_CORE_URL;
@@ -148,9 +166,16 @@ export function GetUserFeedbackProvider({ children, clientOptions, instanceId: i
     const flowContainerContext = useMemo(() => ({
         client: controller.client,
         contentOwner,
+        flowRegistry: controller.flowRegistry,
+        projection,
+        registerContent,
+    }), [
+        contentOwner,
+        controller.client,
+        controller.flowRegistry,
         projection,
         registerContent,
-    }), [contentOwner, controller.client, projection, registerContent]);
+    ]);
     const controllerLifecycleTokensRef = useRef(new WeakMap());
     useEffect(() => {
         const lifecycleToken = {};
@@ -182,6 +207,7 @@ export function GetUserFeedbackProvider({ children, clientOptions, instanceId: i
         key: clientOptionsKey,
         getRuntimeConfiguration,
         getHostActionHandler: actionRegistry.getHandler,
+        getLinkRouter: linkRouter.getRouter,
         onCommandSessionChange: handleCommandSessionChange,
         onError: reportError,
         onHandleInvalidated: handleHandleInvalidated,