@getuserfeedback/react-native 1.0.0 → 1.3.3

package/README.md

@@ -2,7 +2,7 @@
 
 React Native bindings for getuserfeedback.
 
-This package is currently a scaffold for the Expo/React Native WebView integration. It exports the stable package shape and protocol-typed component APIs; WebView orchestration will land in the next implementation slice.
+This package hosts the existing getuserfeedback WebView runtime from React Native and exposes a provider/hook API for enqueueing widget commands from non-ejected Expo or React Native apps.
 
 ## Install
 
@@ -15,7 +15,154 @@ Requires React, React Native, and `react-native-webview`.
 ## API
 
 - `GetUserFeedbackProvider`
+- `useGetUserFeedback`
 - `WidgetHost`
 - `useGetUserFeedbackNative`
 
+```tsx
+import {
+	GetUserFeedbackProvider,
+	useGetUserFeedback,
+} from "@getuserfeedback/react-native";
+
+function FeedbackActions() {
+	const feedback = useGetUserFeedback();
+
+	return (
+		<Button
+			title="Send feedback"
+			onPress={() => {
+				void feedback.open("flow_123");
+			}}
+		/>
+	);
+}
+
+export function App() {
+	return (
+		<GetUserFeedbackProvider
+			initOptions={{ apiKey: "YOUR_API_KEY" }}
+			loaderUrl="https://cdn.example.com/loader.js"
+		>
+			<FeedbackActions />
+		</GetUserFeedbackProvider>
+	);
+}
+```
+
+`GetUserFeedbackProvider` renders `WidgetHost` internally, auto-enqueues `init`, measures the React Native window for the hosted WebView viewport, shows the hosted WebView inside a native bottom sheet while a flow is loading or open, and resolves command promises when the WebView transport reports command settlement. Pass either `loaderUrl` or a custom WebView `source` so the hosted WebView has a loader runtime to execute commands. Use `onCommandError` to receive automatic setup failures from `init` or `configure`.
+
+`WidgetHost` remains exported for advanced hosts that need direct WebView control.
+
 The host message types are re-exported from `@getuserfeedback/protocol/webview-transport` through package-owned aliases so the React Native package stays aligned with the shared WebView transport contract.
+
+## Local Expo smoke test
+
+Use the repo sandbox when testing a non-ejected Expo app against the local
+loader/core/API stack:
+
+```bash
+bun run start:sandbox
+```
+
+Create a React Native manifest:
+
+```bash
+curl -sS -X POST http://127.0.0.1:3710/api/sandbox/react-native-flow-assignment
+```
+
+For a physical device, use an address the device can reach:
+
+```bash
+curl -sS -X POST "http://127.0.0.1:3710/api/sandbox/react-native-flow-assignment?publicHost=192.168.1.10"
+```
+
+Then pass `manifest.initOptions` and `manifest.loaderUrl` to the provider:
+
+```tsx
+import {
+	type GetUserFeedbackProviderProps,
+	GetUserFeedbackProvider,
+	useGetUserFeedback,
+} from "@getuserfeedback/react-native";
+import { Button, View } from "react-native";
+
+const manifest = {
+	// Paste the sandbox manifest while manually testing on device.
+	initOptions: {
+		apiKey: "gx_sandbox_...",
+		defaultConsent: ["analytics.measurement", "analytics.storage"],
+		disableTelemetry: true,
+		enableDebug: true,
+		runtimeEndpoints: {
+			apiUrl: "http://192.168.1.10:3712/v1",
+			coreUrl: "http://192.168.1.10:3711/widget/core/v1/core.html",
+		},
+	},
+	loaderUrl: "http://192.168.1.10:3711/widget/loader/v1/gx_sandbox_.../loader.js",
+	commands: {
+		identify: {
+			userId: "sandbox-user-...",
+			traits: { email: "sandbox-user-...@example.test" },
+		},
+		open: { flowId: "sur_..." },
+		track: {
+			name: "Checkout Started",
+			properties: { source: "react-native-sandbox" },
+		},
+	},
+} satisfies {
+	commands: {
+		identify: { traits: Record<string, unknown>; userId: string };
+		open: { flowId: string };
+		track: { name: string; properties: Record<string, unknown> };
+	};
+	initOptions: GetUserFeedbackProviderProps["initOptions"];
+	loaderUrl: string;
+};
+
+function SandboxActions() {
+	const feedback = useGetUserFeedback();
+
+	return (
+		<View>
+			<Button
+				title="Identify"
+				onPress={() => {
+					void feedback.identify(
+						manifest.commands.identify.userId,
+						manifest.commands.identify.traits,
+					);
+				}}
+			/>
+			<Button
+				title="Track"
+				onPress={() => {
+					void feedback.track(
+						manifest.commands.track.name,
+						manifest.commands.track.properties,
+					);
+				}}
+			/>
+			<Button
+				title="Open"
+				onPress={() => {
+					void feedback.open(manifest.commands.open.flowId);
+				}}
+			/>
+		</View>
+	);
+}
+
+export function App() {
+	return (
+		<GetUserFeedbackProvider
+			initOptions={manifest.initOptions}
+			loaderUrl={manifest.loaderUrl}
+			onCommandError={console.error}
+		>
+			<SandboxActions />
+		</GetUserFeedbackProvider>
+	);
+}
+```

package/dist/host-viewport.d.ts

@@ -0,0 +1,3 @@
+import type { WidgetHostProps } from "./widget-host.js";
+export type HostViewport = NonNullable<WidgetHostProps["hostViewport"]>;
+export declare function useResolvedHostViewport(explicitHostViewport: HostViewport | undefined): HostViewport | undefined;

package/dist/host-viewport.js

@@ -0,0 +1,69 @@
+import { useEffect, useMemo, useState } from "react";
+function isHostViewport(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "width" in value &&
+        typeof value.width === "number" &&
+        Number.isFinite(value.width) &&
+        value.width > 0 &&
+        "height" in value &&
+        typeof value.height === "number" &&
+        Number.isFinite(value.height) &&
+        value.height > 0);
+}
+function toHostViewport(value) {
+    return isHostViewport(value)
+        ? {
+            height: value.height,
+            width: value.width,
+        }
+        : undefined;
+}
+function resolveReactNativeDimensions() {
+    var _a;
+    try {
+        const reactNativeModule = require("react-native");
+        return (_a = reactNativeModule.Dimensions) !== null && _a !== void 0 ? _a : null;
+    }
+    catch (_b) {
+        return null;
+    }
+}
+function readWindowViewport(dimensions) {
+    if (!dimensions) {
+        return undefined;
+    }
+    return toHostViewport(dimensions.get("window"));
+}
+function useReactNativeWindowViewport(enabled) {
+    const dimensions = useMemo(() => (enabled ? resolveReactNativeDimensions() : null), [enabled]);
+    const [viewport, setViewport] = useState(() => readWindowViewport(dimensions));
+    useEffect(() => {
+        if (!enabled) {
+            setViewport(undefined);
+            return;
+        }
+        setViewport(readWindowViewport(dimensions));
+        if (!(dimensions === null || dimensions === void 0 ? void 0 : dimensions.addEventListener)) {
+            return;
+        }
+        const handleChange = (event) => {
+            var _a;
+            setViewport((_a = toHostViewport(event.window)) !== null && _a !== void 0 ? _a : readWindowViewport(dimensions));
+        };
+        const subscription = dimensions.addEventListener("change", handleChange);
+        return () => {
+            var _a;
+            if (subscription === null || subscription === void 0 ? void 0 : subscription.remove) {
+                subscription.remove();
+                return;
+            }
+            (_a = dimensions.removeEventListener) === null || _a === void 0 ? void 0 : _a.call(dimensions, "change", handleChange);
+        };
+    }, [dimensions, enabled]);
+    return viewport !== null && viewport !== void 0 ? viewport : readWindowViewport(dimensions);
+}
+export function useResolvedHostViewport(explicitHostViewport) {
+    const measuredHostViewport = useReactNativeWindowViewport(explicitHostViewport === undefined);
+    return explicitHostViewport !== null && explicitHostViewport !== void 0 ? explicitHostViewport : measuredHostViewport;
+}

package/dist/index.d.ts

@@ -1,25 +1,91 @@
-import type { ConfigureOptions, InitOptions, PublicCommandPayload } from "@getuserfeedback/protocol";
-import type { WebViewCommandEnvelope, WebViewTransportNativeMessage, WebViewTransportWebMessage } from "@getuserfeedback/protocol/webview-transport";
+import type { AppEventExternalId, AppEventJsonValue, PublicCommandPayload } from "@getuserfeedback/protocol";
+import type { WebViewCommandEnvelope, WebViewTransportHostEvent, WebViewTransportNativeMessage, WebViewTransportWebMessage } from "@getuserfeedback/protocol/webview-transport";
+import type { ConfigureOptions, InitOptions } from "@getuserfeedback/sdk";
 import { type ReactElement, type ReactNode } from "react";
-export type ReactNativeWidgetCommand = PublicCommandPayload;
+import { WidgetHost, type WidgetHostProps, type WidgetHostSource } from "./widget-host.js";
+export { REACT_NATIVE_SDK_VERSION } from "./version.js";
+export { buildNativeMessageInjectionScript, buildWebViewBridgeScript, } from "./webview-bridge-script.js";
+export { WidgetHost, type WidgetHostProps, type WidgetHostSource };
 export type ReactNativeWidgetCommandEnvelope = WebViewCommandEnvelope;
+export type ReactNativeWidgetCommand = ReactNativeWidgetCommandEnvelope["command"];
 export type ReactNativeWidgetNativeMessage = WebViewTransportNativeMessage;
 export type ReactNativeWidgetWebMessage = WebViewTransportWebMessage;
-export interface GetUserFeedbackProviderProps {
-    children?: ReactNode;
-    initOptions: InitOptions;
-    configureOptions?: ConfigureOptions;
-    onWebMessage?: (message: WebViewTransportWebMessage) => void;
+type IdentifyTraits = Record<string, unknown>;
+type TrackProperties = Record<string, AppEventJsonValue>;
+type OpenCommand = Extract<PublicCommandPayload, {
+    kind: "open";
+}>;
+type PrerenderCommand = Extract<PublicCommandPayload, {
+    kind: "prerender";
+}>;
+type IdentifyOptions = {
+    externalIds?: AppEventExternalId[];
+};
+type TrackOptions = {
+    externalIds?: AppEventExternalId[];
+};
+type OpenOptions = Pick<OpenCommand, "hideCloseButton">;
+type PrerenderOptions = Pick<PrerenderCommand, "hideCloseButton">;
+type HostContext = Extract<PublicCommandPayload, {
+    kind: "updateHostContext";
+}>["context"];
+type CommandSettledEvent = Extract<WebViewTransportHostEvent, {
+    name: "instance:command:settled";
+}>;
+type CommandSettledSuccessDetail = Extract<CommandSettledEvent["detail"], {
+    ok: true;
+}>;
+export interface ReactNativeCommandResult {
+    envelope: ReactNativeWidgetCommandEnvelope;
+    message: ReactNativeWidgetNativeMessage;
+    settlement?: CommandSettledEvent["detail"];
+    settlementResult?: CommandSettledSuccessDetail["result"];
 }
-export interface WidgetHostProps {
-    onWebMessage?: (message: WebViewTransportWebMessage) => void;
-    nativeMessages?: readonly WebViewTransportNativeMessage[];
+export interface ReactNativeCommandOptions {
+    idempotencyKey?: string;
+}
+export interface ReactNativeGetUserFeedbackClient {
+    readonly instanceId: string;
+    readonly nativeMessages: readonly ReactNativeWidgetNativeMessage[];
+    enqueueCommand: (command: ReactNativeWidgetCommand, options?: ReactNativeCommandOptions) => Promise<ReactNativeCommandResult>;
+    configure: (opts: ConfigureOptions, options?: ReactNativeCommandOptions) => Promise<ReactNativeCommandResult>;
+    identify: {
+        (userId: string, traits?: IdentifyTraits, options?: IdentifyOptions): Promise<ReactNativeCommandResult>;
+        (traits: IdentifyTraits, placeholder: undefined, options?: IdentifyOptions): Promise<ReactNativeCommandResult>;
+        (traits: IdentifyTraits, options?: IdentifyOptions): Promise<ReactNativeCommandResult>;
+    };
+    track: (eventName: string, properties?: TrackProperties, options?: TrackOptions) => Promise<ReactNativeCommandResult>;
+    open: (flowId: string, options?: OpenOptions, commandOptions?: ReactNativeCommandOptions) => Promise<ReactNativeCommandResult>;
+    prefetch: (flowId: string, options?: ReactNativeCommandOptions) => Promise<ReactNativeCommandResult>;
+    prerender: (flowId: string, options?: PrerenderOptions, commandOptions?: ReactNativeCommandOptions) => Promise<ReactNativeCommandResult>;
+    close: (flowHandleId?: string, options?: ReactNativeCommandOptions) => Promise<ReactNativeCommandResult>;
+    reset: (options?: ReactNativeCommandOptions) => Promise<ReactNativeCommandResult>;
+    updateHostContext: (context: HostContext, options?: ReactNativeCommandOptions) => Promise<ReactNativeCommandResult>;
+    emitHostSignal: (name: string, data?: unknown, options?: ReactNativeCommandOptions) => Promise<ReactNativeCommandResult>;
+    handleWebMessage: (message: ReactNativeWidgetWebMessage) => void;
 }
-export interface GetUserFeedbackNativeContextValue {
+interface GetUserFeedbackProviderBaseProps {
+    children?: ReactNode;
     initOptions: InitOptions;
     configureOptions?: ConfigureOptions;
+    instanceId?: string;
     onWebMessage?: (message: WebViewTransportWebMessage) => void;
+    onInvalidWebMessage?: (error: Error, rawMessage: unknown) => void;
+    onCommandError?: (error: Error) => void;
+    autoInit?: boolean;
+    commandTimeoutMs?: number;
+    hostViewport?: WidgetHostProps["hostViewport"];
+    webViewComponent?: WidgetHostProps["webViewComponent"];
+    webViewProps?: WidgetHostProps["webViewProps"];
 }
-export declare function GetUserFeedbackProvider({ children, configureOptions, initOptions, onWebMessage, }: GetUserFeedbackProviderProps): ReactElement;
+export type GetUserFeedbackProviderProps = GetUserFeedbackProviderBaseProps & ({
+    loaderUrl: string;
+    source?: WidgetHostSource;
+} | {
+    loaderUrl?: string;
+    source: WidgetHostSource;
+});
+export type GetUserFeedbackNativeContextValue = ReactNativeGetUserFeedbackClient;
+export declare function GetUserFeedbackProvider({ autoInit, children, commandTimeoutMs, configureOptions, hostViewport, instanceId: instanceIdProp, initOptions, loaderUrl, onCommandError, onInvalidWebMessage, onWebMessage, source, webViewComponent, webViewProps, }: GetUserFeedbackProviderProps): ReactElement;
 export declare function useGetUserFeedbackNative(): GetUserFeedbackNativeContextValue;
-export declare function WidgetHost(_props: WidgetHostProps): null;
+export declare const useGetUserFeedback: typeof useGetUserFeedbackNative;