@guidelytech/react-native 0.16.0 → 0.17.0

package/dist/index.d.ts

@@ -1,11 +1,12 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { SelectorStrategy, Placement, AutocaptureSettings, HeatmapPoint, MessengerConfig, MessengerMessage, MessengerConversation, SdkArticlesResponse, ResourceCenterArticle, PublishedGuide, ProjectTheme, GuideStep, SdkConfigResponse, ChecklistTask, SdkEvent, TargetingContext, StepButton, ResourceCenterConfig, RuleGroup, ResourceCenterAnnouncement } from '@guidelytech/shared';
+import { SelectorStrategy, Placement, AutocaptureSettings, HeatmapPoint, PublishedGuide, ProjectTheme, GuideStep, SdkConfigResponse, ChecklistTask, MessengerMessage, MessengerConversation, SdkEvent, MessengerConfig, SdkArticlesResponse, ResourceCenterArticle, TargetingContext, StepButton, ResourceCenterConfig, RuleGroup, ResourceCenterAnnouncement } from '@guidelytech/shared';
 export { AutocaptureSettings, GuideStep, HeatmapPoint, PublishedGuide, SdkConfigResponse } from '@guidelytech/shared';
 import { FlagsClientOptions, FlagsClient, JsonValue, FlagValue, FlagDetails, FlagsBootstrap, Attributes } from '@guidelytech/flags';
 export { Attributes, EvaluationResult, FlagDetails, FlagsBootstrap, FlagsClient, FlagsClientOptions, FlagsPayload, InMemoryStickyBucketStore, JsonValue, createFlagsClient } from '@guidelytech/flags';
-import { ResourceCenterModuleId } from '@guidelytech/shared/runtime';
-import { KeyValueStore, ServerHealth, ChecklistProgressState, GuidelyEnvironment, ConsentState, GuidelyUser, GuidelyAccount, GuideLocalState, SessionState } from '@guidelytech/sdk-core/headless';
+import { ErrorLevelName, ExceptionProperties, ExceptionDetail, ErrorFilterPattern, Breadcrumb, ResourceCenterModuleId, StackFrame } from '@guidelytech/shared/runtime';
+export { Breadcrumb, ErrorFilterPattern, ErrorLevelName, ExceptionDetail } from '@guidelytech/shared/runtime';
+import { ChecklistProgressState, GuidelyEnvironment, ConsentState, GuidelyUser, KeyValueStore, ServerHealth, GuidelyAccount, GuideLocalState, SessionState } from '@guidelytech/sdk-core/headless';
 export { ChecklistProgressState, ConsentState, GuidelyAccount, GuidelyEnvironment, GuidelyUser } from '@guidelytech/sdk-core/headless';
 import { ViewProps, StyleProp, ViewStyle, View, GestureResponderEvent } from 'react-native';
 
@@ -194,6 +195,333 @@ declare class TapTracker {
     cancel(): void;
 }
 
+interface HttpGlobals {
+    fetch?: unknown;
+    XMLHttpRequest?: unknown;
+}
+
+/**
+ * React Native's crash hooks, looked up on the JS global (never imported, so Expo Go, web and tests
+ * without them simply get no automatic capture):
+ *
+ * * `ErrorUtils.setGlobalHandler`: every uncaught JS error, `isFatal` for the ones that kill the
+ *   app in release builds (React Native's default handler shows the red box in development and
+ *   crashes the app in release).
+ * * `HermesInternal.enablePromiseRejectionTracker`, or any tracker with the same `enable()` shape
+ *   (`promise/setimmediate/rejection-tracking` on JavaScriptCore): unhandled promise rejections.
+ */
+type GlobalErrorHandler = (error: unknown, isFatal?: boolean) => void;
+interface ErrorUtilsLike {
+    getGlobalHandler?(): GlobalErrorHandler | undefined;
+    setGlobalHandler(handler: GlobalErrorHandler): void;
+}
+interface RejectionTrackerOptions {
+    allRejections: boolean;
+    onUnhandled: (id: number, rejection: unknown) => void;
+    onHandled: (id: number) => void;
+}
+/** `HermesInternal.enablePromiseRejectionTracker`, or `require("promise/setimmediate/rejection-tracking")`. */
+interface RejectionTracker {
+    enable(options: RejectionTrackerOptions): void;
+}
+interface HermesInternalLike {
+    hasPromise?(): boolean;
+    enablePromiseRejectionTracker?(options: RejectionTrackerOptions): void;
+    getRuntimeProperties?(): Record<string, unknown>;
+}
+/** The globals crash capture and breadcrumbs hook into (`globalThis` in an app; fakes in tests). */
+interface RuntimeGlobals extends HttpGlobals {
+    ErrorUtils?: ErrorUtilsLike;
+    HermesInternal?: HermesInternalLike;
+    console?: Record<string, unknown>;
+    __DEV__?: boolean;
+    addEventListener?: (type: string, listener: (event: unknown) => void) => void;
+    removeEventListener?: (type: string, listener: (event: unknown) => void) => void;
+    nativeFabricUIManager?: unknown;
+    __turboModuleProxy?: unknown;
+    RN$Bridgeless?: unknown;
+    expo?: unknown;
+}
+/** How long a fatal error may hold React Native's handler back while its report is saved and sent. */
+declare const FATAL_FLUSH_MS = 2000;
+
+/**
+ * AsyncStorage-compatible key/value storage (`@react-native-async-storage/async-storage`,
+ * `expo-secure-store` wrappers, MMKV adapters…). Synchronous implementations work too.
+ */
+interface GuidelyStorage {
+    getItem(key: string): Promise<string | null> | string | null;
+    setItem(key: string, value: string): Promise<void> | void;
+    removeItem(key: string): Promise<void> | void;
+}
+/** Device facts the engine needs. The provider fills these in from React Native APIs. */
+interface DeviceEnvironment {
+    platform: "ios" | "android";
+    deviceType: "mobile" | "tablet";
+    locale?: string;
+    /** Host app version, detected from a linked native module (see `core/device.ts`). */
+    appVersion?: string;
+    /** Host app build number (`CFBundleVersion` / `versionCode`). */
+    appBuild?: string;
+    /** OS version: `18.1` on iOS, `14` on Android. */
+    osVersion?: string;
+    /** Device model (`Pixel 8`, `iPhone16,2`), manufacturer and brand, for error reports (see `detectDeviceModel`). */
+    model?: string;
+    manufacturer?: string;
+    brand?: string;
+    /** True on a simulator / emulator, when a linked module says. */
+    simulator?: boolean;
+    /** React Native's version (`Platform.constants.reactNativeVersion`), for error reports. */
+    reactNativeVersion?: string | {
+        major: number;
+        minor?: number;
+        patch?: number;
+        prerelease?: string | number | null;
+    };
+}
+interface GuidelyOptions {
+    /** Environment public key, e.g. `pk_dev_…`. Not a secret. */
+    projectId: string;
+    environment?: GuidelyEnvironment;
+    /** Base URL of your Guidely deployment, e.g. `https://guidelytech.com`. */
+    apiUrl?: string;
+    /**
+     * Where identity, cached config, queued events and unsent survey answers are persisted. Pass AsyncStorage
+     * (`@react-native-async-storage/async-storage`); without it state lasts only for the app session,
+     * so anything not yet sent during a Guidely outage is lost when the app restarts.
+     */
+    storage?: GuidelyStorage;
+    debug?: boolean;
+    /** Send analytics events (default `true`). Guides still render when disabled. */
+    analytics?: boolean;
+    consent?: ConsentState;
+    /**
+     * Host app version for `app.version` targeting rules, every event's `appVersion` and `app_install` /
+     * `app_update`. Detected on iOS and Android when `@guidelytech/react-native-replay`, `expo-application`
+     * or `react-native-device-info` is linked; pass it to override that (or when none is).
+     */
+    appVersion?: string;
+    /** Host app build number (`CFBundleVersion` / `versionCode`), sent as `build` with app lifecycle events. Detected like `appVersion`. */
+    appBuild?: string;
+    /**
+     * Release errors are reported under (`properties.release`), which picks the uploaded source maps:
+     * pass the same value as `--release` to `npx @guidelytech/sourcemaps upload`. Defaults to the app version.
+     */
+    release?: string;
+    /**
+     * Error monitoring, as in Sentry SDKs: `captureErrors`, `sampleRate`, `ignoreErrors`, `denyUrls` /
+     * `allowUrls`, `beforeSend`, `beforeBreadcrumb`, which automatic breadcrumbs to record and `dist`
+     * (docs/error-monitoring/sdks.md). Errors need the project's error tracking on, plus analytics and consent.
+     */
+    errors?: ErrorMonitoringOptions;
+    /**
+     * Product analytics autocapture: taps (`click`), rage taps, heatmaps, time on screen
+     * (`page_leave`) and app lifecycle events. Each capability runs when the project enables it in
+     * Settings → Product analytics; this option can only turn things off: `false` for everything,
+     * or `{ clicks: false, heatmaps: false, … }` per capability. `false` also removes the provider's
+     * touch-observing wrapper view.
+     */
+    autocapture?: boolean | Partial<AutocaptureSettings>;
+    /**
+     * Session replay (off by default). Recording also needs replay enabled in the project settings and
+     * the native `@guidelytech/react-native-replay` module installed; sampling, consent and `analytics`
+     * apply too. Text inputs are always masked; wrap anything else in `<GuidelyMask>`.
+     */
+    sessionReplay?: SessionReplayOptions;
+    /** How often to refresh the published config (default 5 minutes). */
+    configRefreshMs?: number;
+    /** Overrides for the project theme. */
+    theme?: Partial<ProjectTheme>;
+    /** Identify this user as soon as the client initialises. */
+    user?: GuidelyUser;
+    /**
+     * Language for guides and the resource center (BCP 47, e.g. `fr` or `pt-BR`). Defaults to the
+     * user's `language` / `locale` trait, then the device language. Change it later with `setLocale()`.
+     */
+    locale?: string;
+    /** Handles relative and custom-scheme URLs from buttons, links and tasks (deep links, in-app routes). Return `true` when handled. */
+    onNavigate?: (url: string) => boolean | void;
+    onError?: (error: Error) => void;
+    /** Custom fetch (tests / polyfills). */
+    fetch?: typeof fetch;
+    /** Show the floating checklist launcher (default `true`). */
+    showChecklistLauncher?: boolean;
+    /** Show a floating resource-center launcher (default `false`; call `openResourceCenter()` instead). */
+    showResourceCenterLauncher?: boolean;
+    /** Show the Scout chat bubble when the messenger is on for this platform (default `true`). */
+    showMessengerLauncher?: boolean;
+    /**
+     * Feature flags (on by default, same key and API URL; the last payload is kept in `storage` so
+     * flags work offline at cold start). `false` turns them off; an object passes options to the
+     * flags client (`attributes`, `payload`, `remoteEval`, `pollingMode`…).
+     */
+    flags?: false | Partial<FlagsClientOptions>;
+}
+interface SessionReplayOptions {
+    /** Record sessions (when the project setting allows it and the session is sampled). */
+    enabled?: boolean;
+    /** Mask all text; also forced on by the project's "mask all text" setting. */
+    maskAllText?: boolean;
+    /** Mask all images. */
+    maskAllImages?: boolean;
+    /** Time between screenshots in ms (default 1000, minimum 500). */
+    captureIntervalMs?: number;
+}
+interface GuideStepInfo {
+    guide: PublishedGuide;
+    stepId: string;
+    stepIndex: number;
+}
+interface GuidelyEvents {
+    ready: (config: SdkConfigResponse) => void;
+    config: (config: SdkConfigResponse) => void;
+    "guide:start": (guide: PublishedGuide) => void;
+    "guide:step": (info: GuideStepInfo) => void;
+    "guide:complete": (guide: PublishedGuide) => void;
+    "guide:dismiss": (guide: PublishedGuide) => void;
+    "guide:skip": (guide: PublishedGuide) => void;
+    "checklist:task": (info: {
+        guide: PublishedGuide;
+        task: ChecklistTask;
+        progress: ChecklistProgressState;
+    }) => void;
+    "checklist:complete": (guide: PublishedGuide) => void;
+    "survey:submit": (info: {
+        guide: PublishedGuide;
+        answers: Record<string, unknown>;
+        responseId: string;
+    }) => void;
+    "resource-center:open": () => void;
+    /** The Scout messenger opened. */
+    "messenger:open": () => void;
+    /** Scout or a teammate replied in a conversation. */
+    "conversation:message": (info: {
+        message: MessengerMessage;
+        conversation: MessengerConversation;
+    }) => void;
+    error: (error: Error) => void;
+    track: (event: SdkEvent) => void;
+    identify: (info: {
+        userId: string | null;
+        anonymousId: string;
+    }) => void;
+    /** Feature flags loaded (bootstrap, storage or network) — or failed to and serve fallbacks. */
+    "flags:ready": () => void;
+    /** New flag rules arrived. */
+    "flags:change": () => void;
+}
+type GuidelyEventName = keyof GuidelyEvents;
+/** A rendered step, as the overlay sees it. */
+interface StepView {
+    /** Stable per rendered step; changes when the step changes. */
+    key: string;
+    guide: PublishedGuide;
+    step: GuideStep;
+    index: number;
+    total: number;
+    canGoBack: boolean;
+    /** Guidely id of the resolved target, or null for unanchored / fallback-to-modal steps. */
+    targetId: string | null;
+    asModal: boolean;
+    /** Hotspots render collapsed until tapped. */
+    expanded: boolean;
+}
+interface ChecklistView {
+    guide: PublishedGuide;
+    progress: ChecklistProgressState;
+    open: boolean;
+}
+interface SurveyView {
+    key: string;
+    guide: PublishedGuide;
+    submitted: boolean;
+}
+/** Everything the overlay renders. Immutable snapshots; a new object on every change. */
+interface UiState {
+    steps: StepView[];
+    checklists: ChecklistView[];
+    survey: SurveyView | null;
+    resourceCenterOpen: boolean;
+    /** An article to show in the resource center (from a help-article link); `seq` changes per request. */
+    resourceCenterArticle?: {
+        id: string;
+        seq: number;
+    } | null;
+    theme: Partial<ProjectTheme>;
+    /** Scout is on for this platform; the overlay renders the messenger (see `client.getMessenger()`). */
+    messenger: boolean;
+}
+
+/** What `beforeSend` gets (and may change): the indexed properties and the detail. */
+interface ErrorEvent {
+    properties: ExceptionProperties & Record<string, unknown>;
+    detail: ExceptionDetail;
+}
+interface BreadcrumbHint {
+    /** The console arguments or request the breadcrumb came from. */
+    event?: unknown;
+}
+/** `<GuidelyProvider errors={{ … }}>` / `GuidelyOptions.errors`. */
+interface ErrorMonitoringOptions {
+    /**
+     * Automatic capture (default `true`): uncaught JS errors through `ErrorUtils` and unhandled promise
+     * rejections. `false` leaves `captureException` / `captureMessage` working.
+     */
+    captureErrors?: boolean;
+    /** Share of errors sent, 0–1 (default 1). Crashes included. */
+    sampleRate?: number;
+    /** Errors whose `"<type>: <message>"` or message contains a string / matches a RegExp are not sent. */
+    ignoreErrors?: ErrorFilterPattern[];
+    /** Errors whose innermost frame file matches are not sent (`app:///index.android.bundle`, dev-server URLs). */
+    denyUrls?: ErrorFilterPattern[];
+    /** When set, only errors whose innermost frame file matches are sent. */
+    allowUrls?: ErrorFilterPattern[];
+    /** Last say over each error: return it (changed or not), or null to drop it. A hook that throws sends the event unchanged. */
+    beforeSend?: (event: ErrorEvent) => ErrorEvent | null;
+    /** Last say over each breadcrumb: return it (changed or not), or null to drop it. */
+    beforeBreadcrumb?: (crumb: Breadcrumb, hint?: BreadcrumbHint) => Breadcrumb | null;
+    /** Automatic breadcrumbs (all on by default); `false` turns them all off. */
+    breadcrumbs?: false | BreadcrumbOptions;
+    /** Breadcrumbs kept (default and maximum 100). */
+    maxBreadcrumbs?: number;
+    /** Sentry `dist`: tells builds of one release apart (default: the app build number). */
+    dist?: string;
+    /**
+     * Unhandled promise rejections on engines other than Hermes: pass
+     * `require("promise/setimmediate/rejection-tracking")` (React Native's Promise polyfill). Hermes'
+     * own tracker is used without it.
+     */
+    rejectionTracker?: RejectionTracker | null;
+}
+interface BreadcrumbOptions {
+    /** `ui.click`: taps the SDK observes (the element's `selector`; never its text). */
+    taps?: boolean;
+    /** `navigation`: `screen()` changes. */
+    navigation?: boolean;
+    /** `app.lifecycle`: foreground / background. */
+    appLifecycle?: boolean;
+    /** `console`: `console.warn` / `console.error`. */
+    console?: boolean;
+    /** `fetch` / `xhr`: method, URL without query, status, duration. */
+    http?: boolean;
+    /** `guide`: guides shown, stepped through, completed, dismissed. */
+    guides?: boolean;
+}
+/** The second argument of `captureException`; any other key becomes an event property. */
+interface CaptureContext {
+    tags?: Record<string, string | number | boolean>;
+    extra?: Record<string, unknown>;
+    level?: ErrorLevelName;
+    /** `["{{ default }}", "checkout"]` splits an issue, `["checkout-timeout"]` merges errors into one. */
+    fingerprint?: string[];
+    contexts?: Record<string, Record<string, unknown> | null>;
+    user?: {
+        id?: string;
+        email?: string;
+        username?: string;
+    };
+}
+
 /**
  * Scout messenger for React Native: the transport of `@guidelytech/sdk-core`'s messenger-api plus
  * the conversation state the web widget keeps, as a headless store the overlay renders.
@@ -512,191 +840,8 @@ declare class SessionRecorder {
     private onFrame;
 }
 
-/**
- * AsyncStorage-compatible key/value storage (`@react-native-async-storage/async-storage`,
- * `expo-secure-store` wrappers, MMKV adapters…). Synchronous implementations work too.
- */
-interface GuidelyStorage {
-    getItem(key: string): Promise<string | null> | string | null;
-    setItem(key: string, value: string): Promise<void> | void;
-    removeItem(key: string): Promise<void> | void;
-}
-/** Device facts the engine needs. The provider fills these in from React Native APIs. */
-interface DeviceEnvironment {
-    platform: "ios" | "android";
-    deviceType: "mobile" | "tablet";
-    locale?: string;
-    /** Host app version, detected from a linked native module (see `core/device.ts`). */
-    appVersion?: string;
-    /** Host app build number (`CFBundleVersion` / `versionCode`). */
-    appBuild?: string;
-    /** OS version: `18.1` on iOS, `14` on Android. */
-    osVersion?: string;
-}
-interface GuidelyOptions {
-    /** Environment public key, e.g. `pk_dev_…`. Not a secret. */
-    projectId: string;
-    environment?: GuidelyEnvironment;
-    /** Base URL of your Guidely deployment, e.g. `https://guidelytech.com`. */
-    apiUrl?: string;
-    /**
-     * Where identity, cached config, queued events and unsent survey answers are persisted. Pass AsyncStorage
-     * (`@react-native-async-storage/async-storage`); without it state lasts only for the app session,
-     * so anything not yet sent during a Guidely outage is lost when the app restarts.
-     */
-    storage?: GuidelyStorage;
-    debug?: boolean;
-    /** Send analytics events (default `true`). Guides still render when disabled. */
-    analytics?: boolean;
-    consent?: ConsentState;
-    /**
-     * Host app version for `app.version` targeting rules, every event's `appVersion` and `app_install` /
-     * `app_update`. Detected on iOS and Android when `@guidelytech/react-native-replay`, `expo-application`
-     * or `react-native-device-info` is linked; pass it to override that (or when none is).
-     */
-    appVersion?: string;
-    /** Host app build number (`CFBundleVersion` / `versionCode`), sent as `build` with app lifecycle events. Detected like `appVersion`. */
-    appBuild?: string;
-    /**
-     * Product analytics autocapture: taps (`click`), rage taps, heatmaps, time on screen
-     * (`page_leave`) and app lifecycle events. Each capability runs when the project enables it in
-     * Settings → Product analytics; this option can only turn things off: `false` for everything,
-     * or `{ clicks: false, heatmaps: false, … }` per capability. `false` also removes the provider's
-     * touch-observing wrapper view.
-     */
-    autocapture?: boolean | Partial<AutocaptureSettings>;
-    /**
-     * Session replay (off by default). Recording also needs replay enabled in the project settings and
-     * the native `@guidelytech/react-native-replay` module installed; sampling, consent and `analytics`
-     * apply too. Text inputs are always masked; wrap anything else in `<GuidelyMask>`.
-     */
-    sessionReplay?: SessionReplayOptions;
-    /** How often to refresh the published config (default 5 minutes). */
-    configRefreshMs?: number;
-    /** Overrides for the project theme. */
-    theme?: Partial<ProjectTheme>;
-    /** Identify this user as soon as the client initialises. */
-    user?: GuidelyUser;
-    /**
-     * Language for guides and the resource center (BCP 47, e.g. `fr` or `pt-BR`). Defaults to the
-     * user's `language` / `locale` trait, then the device language. Change it later with `setLocale()`.
-     */
-    locale?: string;
-    /** Handles relative and custom-scheme URLs from buttons, links and tasks (deep links, in-app routes). Return `true` when handled. */
-    onNavigate?: (url: string) => boolean | void;
-    onError?: (error: Error) => void;
-    /** Custom fetch (tests / polyfills). */
-    fetch?: typeof fetch;
-    /** Show the floating checklist launcher (default `true`). */
-    showChecklistLauncher?: boolean;
-    /** Show a floating resource-center launcher (default `false`; call `openResourceCenter()` instead). */
-    showResourceCenterLauncher?: boolean;
-    /** Show the Scout chat bubble when the messenger is on for this platform (default `true`). */
-    showMessengerLauncher?: boolean;
-    /**
-     * Feature flags (on by default, same key and API URL; the last payload is kept in `storage` so
-     * flags work offline at cold start). `false` turns them off; an object passes options to the
-     * flags client (`attributes`, `payload`, `remoteEval`, `pollingMode`…).
-     */
-    flags?: false | Partial<FlagsClientOptions>;
-}
-interface SessionReplayOptions {
-    /** Record sessions (when the project setting allows it and the session is sampled). */
-    enabled?: boolean;
-    /** Mask all text; also forced on by the project's "mask all text" setting. */
-    maskAllText?: boolean;
-    /** Mask all images. */
-    maskAllImages?: boolean;
-    /** Time between screenshots in ms (default 1000, minimum 500). */
-    captureIntervalMs?: number;
-}
-interface GuideStepInfo {
-    guide: PublishedGuide;
-    stepId: string;
-    stepIndex: number;
-}
-interface GuidelyEvents {
-    ready: (config: SdkConfigResponse) => void;
-    config: (config: SdkConfigResponse) => void;
-    "guide:start": (guide: PublishedGuide) => void;
-    "guide:step": (info: GuideStepInfo) => void;
-    "guide:complete": (guide: PublishedGuide) => void;
-    "guide:dismiss": (guide: PublishedGuide) => void;
-    "guide:skip": (guide: PublishedGuide) => void;
-    "checklist:task": (info: {
-        guide: PublishedGuide;
-        task: ChecklistTask;
-        progress: ChecklistProgressState;
-    }) => void;
-    "checklist:complete": (guide: PublishedGuide) => void;
-    "survey:submit": (info: {
-        guide: PublishedGuide;
-        answers: Record<string, unknown>;
-        responseId: string;
-    }) => void;
-    "resource-center:open": () => void;
-    /** The Scout messenger opened. */
-    "messenger:open": () => void;
-    /** Scout or a teammate replied in a conversation. */
-    "conversation:message": (info: {
-        message: MessengerMessage;
-        conversation: MessengerConversation;
-    }) => void;
-    error: (error: Error) => void;
-    track: (event: SdkEvent) => void;
-    identify: (info: {
-        userId: string | null;
-        anonymousId: string;
-    }) => void;
-    /** Feature flags loaded (bootstrap, storage or network) — or failed to and serve fallbacks. */
-    "flags:ready": () => void;
-    /** New flag rules arrived. */
-    "flags:change": () => void;
-}
-type GuidelyEventName = keyof GuidelyEvents;
-/** A rendered step, as the overlay sees it. */
-interface StepView {
-    /** Stable per rendered step; changes when the step changes. */
-    key: string;
-    guide: PublishedGuide;
-    step: GuideStep;
-    index: number;
-    total: number;
-    canGoBack: boolean;
-    /** Guidely id of the resolved target, or null for unanchored / fallback-to-modal steps. */
-    targetId: string | null;
-    asModal: boolean;
-    /** Hotspots render collapsed until tapped. */
-    expanded: boolean;
-}
-interface ChecklistView {
-    guide: PublishedGuide;
-    progress: ChecklistProgressState;
-    open: boolean;
-}
-interface SurveyView {
-    key: string;
-    guide: PublishedGuide;
-    submitted: boolean;
-}
-/** Everything the overlay renders. Immutable snapshots; a new object on every change. */
-interface UiState {
-    steps: StepView[];
-    checklists: ChecklistView[];
-    survey: SurveyView | null;
-    resourceCenterOpen: boolean;
-    /** An article to show in the resource center (from a help-article link); `seq` changes per request. */
-    resourceCenterArticle?: {
-        id: string;
-        seq: number;
-    } | null;
-    theme: Partial<ProjectTheme>;
-    /** Scout is on for this platform; the overlay renders the messenger (see `client.getMessenger()`). */
-    messenger: boolean;
-}
-
 declare const SDK_NAME = "@guidelytech/react-native";
-declare const SDK_VERSION = "0.16.0";
+declare const SDK_VERSION = "0.17.0";
 declare const DEFAULT_API_URL = "https://guidelytech.com";
 /** Host-platform services the engine needs; the provider supplies React Native implementations. */
 interface PlatformBridge {
@@ -710,6 +855,12 @@ interface PlatformBridge {
     };
     /** Session-replay screenshots; absent where the native replay module is not installed. */
     capturer?: ScreenCapturer;
+    /**
+     * The JS globals crash capture and breadcrumbs hook into (`ErrorUtils`, `HermesInternal`,
+     * `console`, `fetch`, `XMLHttpRequest`): `globalThis` from the provider. Without it nothing is
+     * patched and only manual captures (`captureException`) are reported.
+     */
+    globals?: RuntimeGlobals;
 }
 /** Mobile sessions persist across launches and expire after the configured inactivity timeout. */
 interface MobileSession extends SessionState {
@@ -737,6 +888,8 @@ declare class GuidelyClient {
     /** Survey answers, guide completions/dismissals and checklist progress, kept until the server has them. */
     private outbox;
     private config;
+    /** The `environment` option as passed (the resolved one is in `options.environment`). */
+    private readonly envOption;
     private configFetchedAt;
     private etag;
     private anonymousId;
@@ -799,6 +952,15 @@ declare class GuidelyClient {
     private localizedRc;
     /** "What's new" last-seen time when the resource center opened (entries after it read as new). */
     private announcementsSeenAtOpen;
+    private readonly errorScope;
+    private readonly exceptionThrottle;
+    /** Errors captured before storage and a config were loaded (whether error tracking is on is unknown until then). */
+    private earlyErrors;
+    /** Crash reports left by earlier launches, sent once a config says error tracking is on. */
+    private storedCrashes;
+    /** This launch's crash reports (normally one: the app ends right after). */
+    private launchCrashes;
+    private lastAppState;
     private readonly customListeners;
     private readonly eventBus;
     constructor(options: GuidelyOptions, bridge: PlatformBridge);
@@ -808,6 +970,9 @@ declare class GuidelyClient {
     ready(): Promise<void>;
     private bootstrap;
     private whenHydrated;
+    /** Environment guides and flags target: the `environment` option, else the one the loaded config names, else a guess from the key. */
+    get environment(): GuidelyEnvironment;
+    private useConfig;
     private fetchConfig;
     private wireTimers;
     /** Re-fetches the published config and re-evaluates triggers. */
@@ -872,6 +1037,8 @@ declare class GuidelyClient {
     private pageviewsOn;
     /** True when taps are worth observing (clicks, rage taps or heatmaps are on); the provider skips resolving views otherwise. */
     isTapCaptureOn(): boolean;
+    /** Taps become `ui.click` breadcrumbs while errors can be reported (even with click autocapture off). */
+    private tapBreadcrumbsOn;
     /**
      * Records a tap observed by the provider: `click` for an interactive element, `rage_click` for
      * bursts and a heatmap point. A registered `<GuidelyTarget>` whose frame contains the point
@@ -893,6 +1060,72 @@ declare class GuidelyClient {
     private checkLaunch;
     private wentToBackground;
     private cameToForeground;
+    /**
+     * Reports a caught error as an `exception` event (`handled: true`), grouped into an issue on the
+     * Errors page. The second argument takes Sentry's capture context (`tags`, `extra`, `level`,
+     * `fingerprint`, `contexts`, `user`); any other key is attached to the occurrence as a property.
+     * Needs the project's error tracking on (plus analytics and consent); `errors.captureErrors: false`
+     * does not stop it. Returns the event id (empty when nothing is sent).
+     */
+    captureException(error: unknown, hint?: CaptureContext & Record<string, unknown>): string;
+    /** Reports a message (default level `info`) as its own issue, grouped by the message. */
+    captureMessage(message: string, level?: ErrorLevelName, hint?: CaptureContext): string;
+    /** Adds a breadcrumb (sent with the next errors; the last 100 are kept). */
+    addBreadcrumb(crumb: Breadcrumb, hint?: BreadcrumbHint): void;
+    /** Tags every later error (searchable on the issue page); `null` removes the tag. */
+    setTag(key: string, value: string | number | boolean | null | undefined): void;
+    setTags(tags: Record<string, string | number | boolean | null | undefined>): void;
+    /** Arbitrary data attached to every later error. */
+    setExtra(key: string, value: unknown): void;
+    setExtras(extras: Record<string, unknown>): void;
+    /** A named context (`setContext("cart", { items: 3 })`) on every later error; `null` removes it. */
+    setContext(name: string, context: Record<string, unknown> | null): void;
+    /**
+     * Sentry's `setUser`: identifies the user by `id` (like `identify`) and keeps `email` / `username`
+     * on their errors. `null` forgets the user (`reset()`).
+     */
+    setUser(user: {
+        id?: string | number;
+        email?: string;
+        username?: string;
+        [trait: string]: unknown;
+    } | null): void;
+    private crumbsOn;
+    private autoBreadcrumb;
+    /** Errors may be captured: analytics on, consent not denied and, once a config says, the project's error tracking on. */
+    private errorsWanted;
+    /** Errors may be queued now (a config is known and allows them). */
+    private errorTrackingAllowed;
+    /** Requests to the Guidely deployment never become breadcrumbs. */
+    private isGuidelyUrl;
+    private release;
+    /** Builds and filters one error (`null` when dropped). */
+    private prepareCapture;
+    /** Queues a prepared error, or holds it until storage and a config are loaded. Returns its event id ("" when dropped). */
+    private deliverError;
+    private sendError;
+    /** Sends what waited for storage and a config: earlier launches' crash reports, then early errors. */
+    private drainErrors;
+    private loadStoredCrashes;
+    /**
+     * Writes the unsent crash reports to storage, directly (not behind other pending writes) so the
+     * write starts before the app ends. Resolves when the storage has it.
+     */
+    private writeCrashes;
+    /**
+     * A fatal JS error: React Native ends a release app right after the global handler, so the report
+     * is written to storage at once (and sent on the next launch), and sent now as well when the
+     * network allows. The promise tells the handler when React Native's own handler may run.
+     */
+    private saveCrash;
+    /** An uncaught JS error from `ErrorUtils` (fatal ones end the app in release builds). */
+    private captureGlobalError;
+    private captureRejection;
+    /**
+     * Guide breadcrumbs, and (with the bridge's JS globals) the global error handler, promise
+     * rejection tracking and console / network breadcrumbs. Undone by `destroy()`.
+     */
+    private installErrorMonitoring;
     /** Builds the targeting context for the current moment. */
     getContext(): TargetingContext;
     private isTargeted;
@@ -1112,9 +1345,36 @@ interface NativeSources {
 }
 /** The host app's version and build, or `{}` when no linked module knows them. */
 declare function detectAppVersion(src: NativeSources): AppVersionInfo;
+interface DeviceModelInfo {
+    model?: string;
+    manufacturer?: string;
+    brand?: string;
+    simulator?: boolean;
+}
+/**
+ * The device model, manufacturer and brand for error reports: from `expo-device`, then
+ * `react-native-device-info`, then React Native's own Android constants (`Model`, `Manufacturer`,
+ * `Brand`). iOS reports no model without one of the modules.
+ */
+declare function detectDeviceModel(src: NativeSources): DeviceModelInfo;
+/** React Native's version from `Platform.constants.reactNativeVersion` (`{ major, minor, patch }`). */
+declare function detectReactNativeVersion(src: NativeSources): {
+    major: number;
+    minor: number;
+    patch: number;
+    prerelease?: string;
+} | undefined;
 /** The OS version: `18.1` on iOS, `14` on Android (falling back to the API level). */
 declare function detectOsVersion(src: NativeSources): string | undefined;
 
+/**
+ * The frame file as the server matches it: dev-server URLs keep origin and path, installed bundles
+ * become `app:///<basename>`, anything else loses `file://` and its query.
+ */
+declare function normalizeBundleFile(file: string): string;
+/** Parses a Hermes, JavaScriptCore or V8 `Error.stack` into frames, innermost first. */
+declare function parseReactNativeStack(stack: string | undefined | null, max?: number): StackFrame[];
+
 /**
  * Declares which screen its children are on, so targets on screens that are mounted but not
  * visible (inactive tabs, screens under a stack) are never used. `name` must match what you pass
@@ -1333,4 +1593,4 @@ declare function useGuideState(idOrKey: string): {
 /** The guide currently running exclusively (flow, modal, survey…), or null. */
 declare function useActiveGuide(): PublishedGuide | null;
 
-export { type AppVersionInfo, type AutocaptureOption, type ChecklistView, DEFAULT_API_URL, type DeviceEnvironment, Feature, FeatureFlag, type FeatureProps, FeatureValue, type FeatureValueProps, FlagsProvider, type FlagsProviderProps, type GuideStepInfo, GuidelyClient, type GuidelyEventName, type GuidelyEvents, GuidelyMask, type GuidelyMaskProps, type GuidelyOptions, GuidelyOverlay, GuidelyProvider, type GuidelyProviderProps, GuidelyScreenScope, type GuidelyStorage, GuidelyTarget, type GuidelyTargetProps, HeatmapBuffer, type Insets, Messenger, type MessengerSnapshot, type MessengerTab, type MessengerThread, type MessengerView, type NativeSources, type PlatformBridge, RageClickDetector, type ReplayCaptureOptions, type ReplayFrame, ReplayUploader, RrwebEvents, SDK_NAME, SDK_VERSION, type ScreenCapturer, SessionRecorder, type SessionReplayOptions, type StepView, type SurveyView, type TapElement, type TapInfo, type TapProperties, TapTracker, TargetRegistry, type TouchPhase, type UiState, createSseParser, detectAppVersion, detectOsVersion, guidelyScreenLayout, htmlToText, noopClient, parseHtml, positionCard, targetIdsFor, useActiveGuide, useChecklistProgress, useFeatureValue, useFlag, useFlagDetails, useFlags, useFlagsClient, useFlagsReady, useGuideState, useGuidely, useGuidelyEvent, useGuidelyIdentify, useGuidelyNavigation, useGuidelyReady, useGuidelyScreen, useGuidelyTarget };
+export { type AppVersionInfo, type AutocaptureOption, type BreadcrumbHint, type BreadcrumbOptions, type CaptureContext, type ChecklistView, DEFAULT_API_URL, type DeviceEnvironment, type DeviceModelInfo, type ErrorEvent, type ErrorMonitoringOptions, FATAL_FLUSH_MS, Feature, FeatureFlag, type FeatureProps, FeatureValue, type FeatureValueProps, FlagsProvider, type FlagsProviderProps, type GuideStepInfo, GuidelyClient, type GuidelyEventName, type GuidelyEvents, GuidelyMask, type GuidelyMaskProps, type GuidelyOptions, GuidelyOverlay, GuidelyProvider, type GuidelyProviderProps, GuidelyScreenScope, type GuidelyStorage, GuidelyTarget, type GuidelyTargetProps, HeatmapBuffer, type Insets, Messenger, type MessengerSnapshot, type MessengerTab, type MessengerThread, type MessengerView, type NativeSources, type PlatformBridge, RageClickDetector, type RejectionTracker, type RejectionTrackerOptions, type ReplayCaptureOptions, type ReplayFrame, ReplayUploader, RrwebEvents, type RuntimeGlobals, SDK_NAME, SDK_VERSION, type ScreenCapturer, SessionRecorder, type SessionReplayOptions, type StepView, type SurveyView, type TapElement, type TapInfo, type TapProperties, TapTracker, TargetRegistry, type TouchPhase, type UiState, createSseParser, detectAppVersion, detectDeviceModel, detectOsVersion, detectReactNativeVersion, guidelyScreenLayout, htmlToText, noopClient, normalizeBundleFile, parseHtml, parseReactNativeStack, positionCard, targetIdsFor, useActiveGuide, useChecklistProgress, useFeatureValue, useFlag, useFlagDetails, useFlags, useFlagsClient, useFlagsReady, useGuideState, useGuidely, useGuidelyEvent, useGuidelyIdentify, useGuidelyNavigation, useGuidelyReady, useGuidelyScreen, useGuidelyTarget };