@dynamic-labs/react-native-extension 4.83.2-alpha.0 → 4.84.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dynamic-labs/react-native-extension",
-  "version": "4.83.2-alpha.0",
+  "version": "4.84.0",
   "main": "./index.cjs",
   "module": "./index.js",
   "types": "./src/index.d.ts",
@@ -18,11 +18,11 @@
     "@turnkey/react-native-passkey-stamper": "1.2.7",
     "@react-native-documents/picker": "^11.0.0",
     "react-native-fs": ">=2.20.0",
-    "@dynamic-labs/assert-package-version": "4.83.2-alpha.0",
-    "@dynamic-labs/client": "4.83.2-alpha.0",
-    "@dynamic-labs/logger": "4.83.2-alpha.0",
-    "@dynamic-labs/message-transport": "4.83.2-alpha.0",
-    "@dynamic-labs/webview-messages": "4.83.2-alpha.0"
+    "@dynamic-labs/assert-package-version": "4.84.0",
+    "@dynamic-labs/client": "4.84.0",
+    "@dynamic-labs/logger": "4.84.0",
+    "@dynamic-labs/message-transport": "4.84.0",
+    "@dynamic-labs/webview-messages": "4.84.0"
   },
   "peerDependencies": {
     "react": ">=18.0.0 <20.0.0",

package/src/components/WebView/EmbeddedWebView/embeddedWebViewPhaseTimers/embeddedWebViewPhaseTimers.d.ts

@@ -1,24 +1,31 @@
 import { Core } from '@dynamic-labs/client';
 import { WebViewFailedToLoadErrorMeta, WebViewFailedToLoadErrorPhase } from '../../../../errors/WebViewFailedToLoadError';
+import { WebViewLoadSuccessMeta, WebViewPhaseEvent } from '../../webViewPhaseTimerCore';
 /**
- * Per-attempt lifecycle event recorded by
- * {@link createEmbeddedWebViewPhaseTimers}. `load_start` resets the per-attempt
- * state (so the timings reflect the current load); `native_error` and
- * `os_kill` increment cumulative counters that persist across reloads.
+ * Path-agnostic success-log meta. Re-exported here for callsite
+ * ergonomics so `setupEmbeddedWebView` doesn't need to reach into
+ * `webViewPhaseTimerCore` directly.
  */
-export type EmbeddedWebViewPhaseEvent = 'load_start' | 'load' | 'load_end' | 'native_error' | 'os_kill';
+export type EmbeddedWebViewLoadSuccessMeta = WebViewLoadSuccessMeta;
+/**
+ * Re-exported for callsite ergonomics: lets `setupEmbeddedWebView` import
+ * a single `EmbeddedWebViewPhaseEvent` type rather than reach into
+ * `webViewPhaseTimerCore` directly.
+ */
+export type EmbeddedWebViewPhaseEvent = WebViewPhaseEvent;
 type EmbeddedWebViewPhaseTimersProps = {
     core: Core;
-    webViewUrl: URL;
     loadingTimeoutMs: number;
     recoveryTimeoutMs: number;
+    webViewUrl: URL;
 };
 export type EmbeddedWebViewPhaseTimers = {
     /**
-     * Record a per-attempt lifecycle event. See {@link EmbeddedWebViewPhaseEvent}
-     * for the semantics of each event.
+     * Detach from the message transport. Call this on teardown so the
+     * embedded webview controller can be re-created without leaking
+     * subscriptions.
      */
-    recordEvent: (event: EmbeddedWebViewPhaseEvent) => void;
+    dispose: () => void;
     /**
      * Build the structured meta to attach to
      * {@link WebViewFailedToLoadError}. The `phase` argument reflects the
@@ -29,24 +36,31 @@ export type EmbeddedWebViewPhaseTimers = {
         phase: WebViewFailedToLoadErrorPhase;
     }) => WebViewFailedToLoadErrorMeta;
     /**
-     * Detach from the message transport. Call this on teardown so the
-     * embedded webview controller can be re-created without leaking
-     * subscriptions.
+     * Build the structured meta to attach to the `webview.load_succeeded`
+     * instrumentation log. Same timing fields as {@link getMeta} but without
+     * the failure-specific `phase` discriminator.
      */
-    dispose: () => void;
+    getSuccessMeta: () => EmbeddedWebViewLoadSuccessMeta;
+    /**
+     * Record a per-attempt lifecycle event. See {@link WebViewPhaseEvent}
+     * for the semantics of each event.
+     */
+    recordEvent: (event: EmbeddedWebViewPhaseEvent) => void;
 };
 /**
  * Non-React equivalent of `useWebViewPhaseTimers` for the embedded native
- * webview path. The embedded path is a singleton wired by `setupEmbeddedWebView`
- * (not a React component), so we expose the same phase-timing surface as a
- * plain factory.
+ * webview path. The embedded path is a singleton wired by
+ * `setupEmbeddedWebView` (not a React component), so we expose the same
+ * phase-timing surface as a plain factory.
+ *
+ * Both this factory and the hook delegate the actual state machine to
+ * {@link createWebViewPhaseTimerCore}; the only path-specific bits are:
  *
- * The hook and the factory are intentionally separate: the embedded path does
- * not have a retry or clear-state model, so `retryCount` is always `0` and
- * `hadClearState` is always `false` in the meta produced here. Sharing one
- * implementation would require either pulling React into a hot non-React path
- * or threading a stateless adapter through both consumers \u2014 the duplication
- * is small enough that keeping them separate stays cleaner.
+ * - `hadClearState` is always `false` (embedded path has no clear-state
+ *   recovery model — that's exclusive to the React `<WebView>` path's
+ *   loading-timeout recovery flow)
+ * - `retryCount` is always `0` (embedded path has no retry counter URL
+ *   query param either)
  */
-export declare const createEmbeddedWebViewPhaseTimers: ({ core, webViewUrl, loadingTimeoutMs, recoveryTimeoutMs, }: EmbeddedWebViewPhaseTimersProps) => EmbeddedWebViewPhaseTimers;
+export declare const createEmbeddedWebViewPhaseTimers: ({ core, loadingTimeoutMs, recoveryTimeoutMs, webViewUrl, }: EmbeddedWebViewPhaseTimersProps) => EmbeddedWebViewPhaseTimers;
 export {};

package/src/components/WebView/successLog/emitSuccessLog.d.ts

@@ -0,0 +1,35 @@
+import { Core } from '@dynamic-labs/client';
+import { SuccessLogCooldown } from './successLogCooldown';
+export declare const SUCCESS_LOG_KEY = "webview.load_succeeded";
+type SuccessLogMeta = Record<string, unknown>;
+type EmitSuccessLogArgs<Meta extends SuccessLogMeta> = {
+    /**
+     * Device-local cooldown gate. If `shouldEmit` returns false the log
+     * is suppressed; on emit, the cooldown is recorded immediately so a
+     * crash between emit and `recordEmitted` doesn't replay the log.
+     */
+    cooldown: SuccessLogCooldown;
+    core: Core;
+    /**
+     * Late-bound meta builder. We call this only after the cooldown
+     * passes so paths that maintain expensive snapshots don't pay the
+     * cost when they're going to be suppressed.
+     */
+    getMeta: () => Meta;
+    /**
+     * Short identifier describing the path. Appears in the log message
+     * (`<name> loaded successfully`) so the two streams are
+     * distinguishable in Datadog without a per-path `key` field.
+     */
+    name: string;
+};
+/**
+ * Shared emission pattern for the `webview.load_succeeded`
+ * instrumentation log. Both the RN `<WebView>` and the embedded
+ * WebView fire the same event with the same payload shape after
+ * checking the same cooldown gate — this helper centralises that
+ * sequence so the two call sites stay aligned and any future field we
+ * add to the success log lands in both places automatically.
+ */
+export declare const emitSuccessLog: <Meta extends SuccessLogMeta>({ cooldown, core, getMeta, name, }: EmitSuccessLogArgs<Meta>) => Promise<void>;
+export {};

package/src/components/WebView/successLog/index.d.ts

@@ -0,0 +1,3 @@
+export { emitSuccessLog, SUCCESS_LOG_KEY } from './emitSuccessLog';
+export { createSuccessLogCooldown, SUCCESS_LOG_COOLDOWN_MS, } from './successLogCooldown';
+export type { SuccessLogCooldown } from './successLogCooldown';

package/src/components/WebView/successLog/successLogCooldown.d.ts

@@ -0,0 +1,39 @@
+export declare const SUCCESS_LOG_COOLDOWN_MS: number;
+export type SuccessLogCooldown = {
+    recordEmitted: (now?: number) => Promise<void>;
+    shouldEmit: (now?: number) => Promise<boolean>;
+};
+type CreateSuccessLogCooldownArgs = {
+    /**
+     * Short identifier used only in warning log messages so storage
+     * failures are distinguishable in Datadog (e.g. `'webview'` vs
+     * `'embedded webview'`).
+     */
+    name: string;
+    /**
+     * Dedicated `expo-secure-store` key under which the timestamp of the
+     * last successful emit is persisted. Each call site MUST use a
+     * distinct key so the two log streams cooldown independently.
+     */
+    storageKey: string;
+};
+/**
+ * Create a device-local cooldown gate for a `webview.load_succeeded`
+ * instrumentation log.
+ *
+ * Both `<WebView>` (RN bridge) and `<EmbeddedWebView>` (native bridge)
+ * emit the same success log; each instantiates its own cooldown with a
+ * dedicated storage key so emitting one log doesn't starve the other
+ * for an app that mounts both.
+ *
+ * - `shouldEmit` returns `true` when the cooldown has elapsed (or no
+ *   timestamp has ever been stored) and `false` while inside the
+ *   window. If secure-store throws on read we default to emitting —
+ *   losing a diagnostic log is worse than the rare duplicate.
+ * - `recordEmitted` persists the current timestamp so subsequent calls
+ *   within the window are suppressed. Write failures are swallowed
+ *   (logged as a warning) so they don't break the host wrapper —
+ *   worst case the next emit also goes through.
+ */
+export declare const createSuccessLogCooldown: ({ name, storageKey, }: CreateSuccessLogCooldownArgs) => SuccessLogCooldown;
+export {};

package/src/components/WebView/useWebViewPhaseTimers/useWebViewPhaseTimers.d.ts

@@ -1,28 +1,14 @@
 import { Core } from '@dynamic-labs/client';
 import { WebViewFailedToLoadErrorMeta, WebViewFailedToLoadErrorPhase } from '../../../errors/WebViewFailedToLoadError';
-/**
- * Wire-format `type` of a webview-side `manifest` request.
- *
- * `requestChannel.request('manifest')` sends a `MessageTransportData` whose
- * `type` is the literal request name. The host replies with `manifest__ack`,
- * which we ignore: receiving the request is sufficient evidence that the
- * webview JS bundle is alive and the message bridge works.
- */
-type WebViewPhaseEvent = 'load_start' | 'load' | 'load_end' | 'native_error' | 'os_kill';
+import { WebViewLoadSuccessMeta, WebViewPhaseEvent } from '../webViewPhaseTimerCore';
+export type { WebViewLoadSuccessMeta };
 type UseWebViewPhaseTimersProps = {
     core: Core;
-    webViewUrl: URL;
     loadingTimeout: number;
     recoveryTimeout: number;
+    webViewUrl: URL;
 };
 export type WebViewPhaseTimers = {
-    /**
-     * Record a per-attempt lifecycle event. `load_start` resets the
-     * per-attempt state (so the timings reflect the current reload), while
-     * `native_error` and `os_kill` increment cumulative counters that
-     * persist across reloads.
-     */
-    recordEvent: (event: WebViewPhaseEvent) => void;
     /**
      * Build the structured meta to attach to {@link WebViewFailedToLoadError}.
      * Pass `phase` explicitly from the callsite (the phase reflects the
@@ -31,6 +17,17 @@ export type WebViewPhaseTimers = {
     getMeta: (args: {
         phase: WebViewFailedToLoadErrorPhase;
     }) => WebViewFailedToLoadErrorMeta;
+    /**
+     * Build the structured meta to attach to the `webview.load_succeeded`
+     * instrumentation log. Same timing fields as {@link getMeta} but without
+     * the failure-specific `phase` discriminator.
+     */
+    getSuccessMeta: () => WebViewLoadSuccessMeta;
+    /**
+     * Record a per-attempt lifecycle event. See {@link WebViewPhaseEvent}
+     * for the semantics of each event.
+     */
+    recordEvent: (event: WebViewPhaseEvent) => void;
 };
 /**
  * Tracks how long each step of the WebView load took, so when we raise
@@ -40,6 +37,10 @@ export type WebViewPhaseTimers = {
  * timings (`webview.time_to_load_manifest`, `webview.time_to_sdk_ready`)
  * still come from the webview itself once it boots, but those don't help
  * when the webview never boots in the first place.
+ *
+ * The actual state machine lives in {@link createWebViewPhaseTimerCore},
+ * which is also reused by the embedded native WebView path. This hook
+ * only layers the React-specific bits (ref-based core lifetime tied to
+ * `useEffect`, URL-derived `hadClearState` / `retryCount`).
  */
-export declare const useWebViewPhaseTimers: ({ core, webViewUrl, loadingTimeout, recoveryTimeout, }: UseWebViewPhaseTimersProps) => WebViewPhaseTimers;
-export {};
+export declare const useWebViewPhaseTimers: ({ core, loadingTimeout, recoveryTimeout, webViewUrl, }: UseWebViewPhaseTimersProps) => WebViewPhaseTimers;

package/src/components/WebView/useWebViewSuccessLog/index.d.ts

@@ -0,0 +1 @@
+export { useWebViewSuccessLog } from './useWebViewSuccessLog';

package/src/components/WebView/useWebViewSuccessLog/useWebViewSuccessLog.d.ts

@@ -0,0 +1,28 @@
+import { Core } from '@dynamic-labs/client';
+import { WebViewLoadSuccessMeta } from '../useWebViewPhaseTimers/useWebViewPhaseTimers';
+type UseWebViewSuccessLogProps = {
+    core: Core;
+    getSuccessMeta: () => WebViewLoadSuccessMeta;
+};
+/**
+ * Emit a `webview.load_succeeded` instrumentation log the first time
+ * the SDK signals it's ready, gated by a device-local 1h cooldown so a
+ * customer with many WebView mounts (or many app launches) doesn't spam
+ * the logs pipeline.
+ *
+ * The error path is unaffected: failures keep going through
+ * `logger.error(WebViewFailedToLoadError, meta)` with no cooldown.
+ *
+ * The hook intentionally fires only once per mount (`hasEmittedRef`):
+ * after a successful boot we don't expect another `sdkHasLoaded` for
+ * the same WebView lifetime, and emitting twice for the same load would
+ * be misleading.
+ *
+ * Cooldown gating + log emission are delegated to the shared
+ * `successLog` helpers so this hook and the embedded native WebView
+ * path stay in lockstep on payload shape and storage semantics; the
+ * dedicated storage key here keeps the RN-path cooldown independent
+ * from the embedded path's.
+ */
+export declare const useWebViewSuccessLog: ({ core, getSuccessMeta, }: UseWebViewSuccessLogProps) => void;
+export {};

package/src/components/WebView/webViewPhaseTimerCore/index.d.ts

@@ -0,0 +1,2 @@
+export { buildSuccessMeta, computePhaseDurations, createWebViewPhaseTimerCore, } from './webViewPhaseTimerCore';
+export type { CumulativeCounters, PerAttemptTimings, PhaseDurations, WebViewLoadSuccessMeta, WebViewPhaseEvent, WebViewPhaseTimerCore, } from './webViewPhaseTimerCore';

package/src/components/WebView/webViewPhaseTimerCore/webViewPhaseTimerCore.d.ts

@@ -0,0 +1,123 @@
+import { Core } from '@dynamic-labs/client';
+/**
+ * Per-attempt lifecycle event recorded by the phase-timer core.
+ *
+ * - `load_start` — native bridge fired `onLoadStart` (resets per-attempt
+ *   state so timings reflect the current attempt)
+ * - `load` — native bridge fired `onLoad` (HTML byte stream received)
+ * - `load_end` — native bridge fired `onLoadEnd` (page finished
+ *   rendering)
+ * - `native_error` — native bridge raised an `onLoadError`; increments a
+ *   counter that persists across reloads
+ * - `os_kill` — host detected an OS-level WebView kill (e.g. backgrounded
+ *   for too long); also a cumulative counter
+ */
+export type WebViewPhaseEvent = 'load' | 'load_end' | 'load_start' | 'native_error' | 'os_kill';
+export type PerAttemptTimings = {
+    htmlLoadStartedAt: number | null;
+    htmlLoadedAt: number | null;
+    manifestReceivedAt: number | null;
+    onLoadEndAt: number | null;
+    sdkReadyAt: number | null;
+};
+export type CumulativeCounters = {
+    nativeErrorCount: number;
+    osKillCount: number;
+};
+export type PhaseDurations = {
+    htmlLoadMs: number | null;
+    manifestReceivedMs: number | null;
+    onLoadToOnLoadEndMs: number | null;
+    sdkReadyMs: number | null;
+};
+/**
+ * Derive cross-phase durations from raw timestamps. The four durations
+ * are what end up in the failure / success log meta:
+ *
+ * - `htmlLoadMs` — `onLoadStart` to `onLoad`; native HTML fetch
+ * - `onLoadToOnLoadEndMs` — `onLoad` to `onLoadEnd`; native render/parse
+ * - `manifestReceivedMs` — `onLoadEnd` to first `manifest` request from
+ *   the webview JS; "JS bundle is alive" signal
+ * - `sdkReadyMs` — `onLoadEnd` to first `sdkHasLoaded` event from the
+ *   webview JS; "SDK fully bootstrapped" signal
+ */
+export declare const computePhaseDurations: (timings: PerAttemptTimings) => PhaseDurations;
+export type WebViewPhaseTimerCore = {
+    /** Detach the message-transport subscription. */
+    dispose: () => void;
+    getCounters: () => CumulativeCounters;
+    getTimings: () => PerAttemptTimings;
+    recordEvent: (event: WebViewPhaseEvent) => void;
+};
+/**
+ * Path-agnostic shape of the `webview.load_succeeded` instrumentation
+ * log meta. Both the React `<WebView>` and the embedded native WebView
+ * paths emit this exact surface so the two log streams can be queried
+ * together in Datadog without per-path field translation.
+ *
+ * The failure meta (`WebViewFailedToLoadErrorMeta`) is this shape plus
+ * a `phase` discriminator — see `buildSuccessMeta` callers.
+ */
+export type WebViewLoadSuccessMeta = {
+    hadClearState: boolean;
+    htmlLoadMs: number | null;
+    loadingTimeoutMs: number;
+    manifestReceivedMs: number | null;
+    nativeErrorCount: number;
+    onLoadToOnLoadEndMs: number | null;
+    osKillCount: number;
+    recoveryTimeoutMs: number;
+    retryCount: number;
+    sdkReadyMs: number | null;
+    webviewUrl: string;
+};
+type BuildSuccessMetaArgs = {
+    /**
+     * Snapshot source for raw timings + cumulative counters. Typically a
+     * live {@link WebViewPhaseTimerCore} instance, but the type only
+     * requires `getTimings` / `getCounters` so callers can fall back to
+     * empty values if the core hasn't been created yet.
+     */
+    core: Pick<WebViewPhaseTimerCore, 'getCounters' | 'getTimings'>;
+    /**
+     * Whether the current attempt was kicked off by the React
+     * `<WebView>`'s clear-state recovery flow. Embedded path is always
+     * `false`.
+     */
+    hadClearState: boolean;
+    loadingTimeoutMs: number;
+    recoveryTimeoutMs: number;
+    /**
+     * Number of times the React `<WebView>` re-mounted via the `?retry=`
+     * URL query param. Embedded path is always `0`.
+     */
+    retryCount: number;
+    webviewUrl: string;
+};
+/**
+ * Build the success-shape meta from a {@link WebViewPhaseTimerCore}
+ * snapshot plus the path-specific fields. Both call sites call this
+ * with their own context (RN reads `hadClearState` / `retryCount` from
+ * the URL; embedded passes constants) so the success-log payload stays
+ * identical across the two paths.
+ */
+export declare const buildSuccessMeta: ({ core, hadClearState, loadingTimeoutMs, recoveryTimeoutMs, retryCount, webviewUrl, }: BuildSuccessMetaArgs) => WebViewLoadSuccessMeta;
+/**
+ * Shared state machine driving WebView load-phase instrumentation.
+ *
+ * Both the React `<WebView>` (RN bridge) and the native embedded WebView
+ * (native bridge) feed lifecycle events into this core and produce
+ * matching meta from the same timings + counters. Each path layers its
+ * own path-specific fields (`hadClearState`, `retryCount`, etc.) on top
+ * of the raw state this core exposes via `getTimings()` / `getCounters()`.
+ *
+ * The core owns the `core.messageTransport` subscription that captures
+ * the two webview-originated signals bracketing SDK bootstrap
+ * (`manifest` once the JS bundle is alive; `sdkHasLoadedEventName`
+ * once the SDK is fully ready). Native bridge lifecycle events come in
+ * via `recordEvent` instead.
+ */
+export declare const createWebViewPhaseTimerCore: ({ core, }: {
+    core: Core;
+}) => WebViewPhaseTimerCore;
+export {};