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

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

@@ -0,0 +1,45 @@
+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';
+type UseWebViewPhaseTimersProps = {
+    core: Core;
+    webViewUrl: URL;
+    loadingTimeout: number;
+    recoveryTimeout: number;
+};
+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
+     * source of the failure, not just the current timing state).
+     */
+    getMeta: (args: {
+        phase: WebViewFailedToLoadErrorPhase;
+    }) => WebViewFailedToLoadErrorMeta;
+};
+/**
+ * Tracks how long each step of the WebView load took, so when we raise
+ * `WebViewFailedToLoadError` we can attach the timings to the error log.
+ *
+ * The timings cover the host-side phases of the load — the webview-side
+ * 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.
+ */
+export declare const useWebViewPhaseTimers: ({ core, webViewUrl, loadingTimeout, recoveryTimeout, }: UseWebViewPhaseTimersProps) => WebViewPhaseTimers;
+export {};

package/src/errors/WebViewFailedToLoadError.d.ts

@@ -1,3 +1,86 @@
+/**
+ * Categorical phase the WebView was in when the failure was raised.
+ *
+ * Use this for high-level grouping; the duration fields on
+ * {@link WebViewFailedToLoadErrorMeta} give the granular timing data.
+ */
+export type WebViewFailedToLoadErrorPhase = 'html_load' | 'sdk_bootstrap' | 'after_clear_state' | 'native_error' | 'embedded_native_error' | 'unknown';
+/**
+ * Structured context attached to {@link WebViewFailedToLoadError} so the
+ * resulting error log carries enough information to tell *which* step the
+ * WebView was stuck in when the failure was raised, and how long each step
+ * took.
+ *
+ * The setter on `InitializationModule.error` forwards this object directly
+ * to `logger.error`, so every field below ends up as a structured field on
+ * the same Datadog log as the error message.
+ */
+export type WebViewFailedToLoadErrorMeta = {
+    phase: WebViewFailedToLoadErrorPhase;
+    /**
+     * Milliseconds between RN's `onLoadStart` and `onLoad` callbacks (the
+     * HTML + asset fetch). `null` if `onLoad` never fired.
+     */
+    htmlLoadMs: number | null;
+    /**
+     * Milliseconds between RN's `onLoad` and `onLoadEnd` callbacks. Usually
+     * small; mostly there to flag pathological cases. `null` if `onLoadEnd`
+     * never fired.
+     */
+    onLoadToOnLoadEndMs: number | null;
+    /**
+     * Milliseconds between `onLoadEnd` and the first `manifest` request
+     * received from the webview-side SDK. Proxy for "the JS bundle is alive
+     * and the message bridge works". `null` if the manifest request never
+     * arrived.
+     */
+    manifestReceivedMs: number | null;
+    /**
+     * Milliseconds between `onLoadEnd` and the webview-side SDK signalling
+     * it has finished initialising (via the `sdkHasLoadedEventName` store
+     * change). `null` if the SDK never signalled it was ready.
+     */
+    sdkReadyMs: number | null;
+    /**
+     * Number of `retry` increments in the WebView URL at the time of failure
+     * (covers OS-kill reloads, load_error reloads, and recovery reloads).
+     */
+    retryCount: number;
+    /**
+     * Whether the `clear-state` query parameter was present in the URL when
+     * the failure was raised. `true` indicates we already retried with a
+     * clean state and still couldn't finish loading.
+     */
+    hadClearState: boolean;
+    /**
+     * Number of times RN's `onError` fired across the lifetime of the
+     * WebView component instance.
+     */
+    nativeErrorCount: number;
+    /**
+     * Number of times the OS killed the WebView process (via
+     * `onContentProcessDidTerminate` on iOS or `onRenderProcessGone` on
+     * Android) across the lifetime of the WebView component instance.
+     */
+    osKillCount: number;
+    /** The configured value for `loadingTimeout` (ms). */
+    loadingTimeoutMs: number;
+    /** The configured value for `recoveryTimeout` (ms). */
+    recoveryTimeoutMs: number;
+    /** The URL the WebView was attempting to load when the failure occurred. */
+    webviewUrl?: string;
+    /**
+     * Native error info, only populated when the failure originated from the
+     * embedded native WebView path (iOS WKWebView / Android WebView), where
+     * we get a single `onLoadError` event with these fields.
+     */
+    nativeErrorCode?: number;
+    nativeErrorDescription?: string;
+    nativeErrorDomain?: string;
+    nativeErrorIsProvisional?: boolean;
+    nativeErrorFailedUrl?: string;
+};
 export declare class WebViewFailedToLoadError extends Error {
-    constructor();
+    readonly meta?: WebViewFailedToLoadErrorMeta;
+    constructor(meta?: WebViewFailedToLoadErrorMeta);
 }

package/src/nativeModules/EmbeddedWebView.d.ts

@@ -16,7 +16,32 @@ export type EmbeddedWebViewOnLoadErrorEvent = {
     description: string;
     isProvisional: boolean;
 };
-export type EmbeddedWebViewEventName = 'onMessage' | 'onShouldStartLoad' | 'onLoadError';
+/**
+ * Fired when the native webview starts a provisional navigation — the
+ * request has been issued but no response bytes have arrived yet.
+ * Maps to `WKNavigationDelegate.didStartProvisionalNavigation` on iOS and
+ * `WebViewClient.onPageStarted` on Android.
+ */
+export type EmbeddedWebViewOnLoadStartEvent = {
+    url: string;
+};
+/**
+ * Fired when the response has committed and the native webview has begun
+ * rendering. Maps to `WKNavigationDelegate.didCommit` on iOS and
+ * `WebViewClient.onPageCommitVisible` on Android.
+ */
+export type EmbeddedWebViewOnLoadEvent = {
+    url: string;
+};
+/**
+ * Fired when the native webview finishes loading the page. Maps to
+ * `WKNavigationDelegate.didFinish` on iOS and `WebViewClient.onPageFinished`
+ * on Android.
+ */
+export type EmbeddedWebViewOnLoadEndEvent = {
+    url: string;
+};
+export type EmbeddedWebViewEventName = 'onMessage' | 'onShouldStartLoad' | 'onLoadError' | 'onLoadStart' | 'onLoad' | 'onLoadEnd';
 export type EmbeddedWebViewNativeModule = {
     setUrl: (url: string) => Promise<void>;
     setVisible: (visible: boolean) => Promise<void>;
@@ -24,6 +49,6 @@ export type EmbeddedWebViewNativeModule = {
     destroy: () => Promise<void>;
     postMessage: (message: string) => Promise<void>;
     respondToShouldStartLoad: (id: string, allow: boolean) => Promise<void>;
-    addListener: <T extends EmbeddedWebViewOnMessageEvent | EmbeddedWebViewOnShouldStartLoadEvent | EmbeddedWebViewOnLoadErrorEvent>(eventName: EmbeddedWebViewEventName, listener: (event: T) => void) => EmbeddedWebViewSubscription;
+    addListener: <T extends EmbeddedWebViewOnMessageEvent | EmbeddedWebViewOnShouldStartLoadEvent | EmbeddedWebViewOnLoadErrorEvent | EmbeddedWebViewOnLoadStartEvent | EmbeddedWebViewOnLoadEvent | EmbeddedWebViewOnLoadEndEvent>(eventName: EmbeddedWebViewEventName, listener: (event: T) => void) => EmbeddedWebViewSubscription;
 };
 export declare const getEmbeddedWebView: () => EmbeddedWebViewNativeModule;