@guidelytech/react-native 0.12.0 → 0.14.0

package/dist/index.d.ts

@@ -324,6 +324,194 @@ declare class Messenger {
     destroy(): void;
 }
 
+/** One captured screen: a masked JPEG (base64) at 1 px per point, and the viewport in points. */
+interface ReplayFrame {
+    base64: string;
+    width: number;
+    height: number;
+    /** Window position (points) of the React root view that touch coordinates are relative to. */
+    originX?: number;
+    originY?: number;
+}
+/** What the capturer must paint over in the next frame. */
+interface ReplayCaptureOptions {
+    maskAllText: boolean;
+    maskAllImages: boolean;
+    /** Window rects (points) of targets whose Guidely id is in `settings.replay.blockSelectors`. */
+    blockRects: Rect[];
+}
+/** Captures the app's visible windows; resolves null when there is nothing to capture. */
+type ScreenCapturer = (options: ReplayCaptureOptions) => Promise<ReplayFrame | null>;
+type TouchPhase = "down" | "move" | "up" | "cancel";
+/** Fixed rrweb document (ids 1–8, see the SPEC) whose single `img` (id 8) shows the current screenshot. */
+declare const RrwebEvents: {
+    IMG_ID: number;
+    TOUCH_START: number;
+    TOUCH_END: number;
+    CLICK: number;
+    CSS: string;
+    dataUrl(base64: string): string;
+    meta(timestamp: number, href: string, width: number, height: number): string;
+    fullSnapshot(timestamp: number, dataUrl: string, width: number, height: number): string;
+    frame(timestamp: number, dataUrl: string): string;
+    /** MouseInteraction (source 2): 7 TouchStart, 9 TouchEnd, 2 Click. */
+    interaction(timestamp: number, type: number, x: number, y: number): string;
+    touchMove(timestamp: number, x: number, y: number): string;
+    custom(timestamp: number, tag: string, payload: Record<string, unknown>): string;
+};
+/** Per-upload metadata (`ReplayChunk` minus `sessionId` / `windowId` / `seq` / `events`). */
+interface ReplayChunkMeta {
+    anonymousId: string;
+    userId: string | null;
+    url?: string;
+    device: {
+        type: string;
+        os: string;
+    };
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    sdk: {
+        name: string;
+        version: string;
+    };
+}
+interface Chunk {
+    sessionId: string;
+    meta: ReplayChunkMeta;
+    events: string[];
+    bytes: number;
+    seq?: number;
+}
+interface ReplayUploaderOptions {
+    /** `POST /replay` URL. */
+    url: () => string;
+    fetch: () => typeof fetch | null;
+    meta: () => ReplayChunkMeta;
+    onDisabled: (sessionId: string) => void;
+    health?: ServerHealth;
+    log?: (message: string) => void;
+    flushIntervalMs?: number;
+    maxBufferBytes?: number;
+    maxQueuedBytes?: number;
+    maxAttempts?: number;
+    slowRetryMs?: number;
+}
+/**
+ * Buffers rrweb events (JSON strings) and uploads them with `POST /replay`. The buffer is sealed every
+ * 10 s, above ~1 MB, on {@link flush} (stop, background) and when the session changes. Chunks go out
+ * one at a time as plain JSON (Hermes has no gzip, and base64 JPEGs barely compress); `seq` is
+ * assigned per session on a chunk's first attempt and kept for its retries. 2xx removes the chunk
+ * (`{disabled:true}` drops that session's chunks), 4xx other than 429 drops it, anything else retries
+ * with backoff, then about once a minute. The backlog is capped at ~5 MB (oldest first, never the
+ * chunk in flight).
+ */
+declare class ReplayUploader {
+    private readonly opts;
+    readonly windowId: string;
+    private buffer;
+    private queue;
+    private queuedBytes;
+    private seqs;
+    private inflight;
+    private flushTimer;
+    private retryTimer;
+    private attempt;
+    private destroyed;
+    private readonly offRecover;
+    constructor(opts: ReplayUploaderOptions);
+    get pendingChunks(): number;
+    get bufferedEvents(): number;
+    push(sessionId: string, json: string): void;
+    /** Seals the buffer and uploads the backlog (one chunk at a time). */
+    flush(): void;
+    /** Drops everything buffered or queued (consent withdrawn, server disabled replay). */
+    discard(): void;
+    /** Uploads what is left once; no retries afterwards. */
+    destroy(): void;
+    private clearFlushTimer;
+    private clearRetry;
+    private scheduleRetry;
+    private seal;
+    private nextSeq;
+    body(chunk: Chunk): string;
+    private sendNext;
+    private upload;
+    private onResult;
+    private remove;
+}
+interface SessionRecorderOptions {
+    capturer: ScreenCapturer;
+    uploader: ReplayUploader;
+    /** Time between screenshots (minimum 500 ms). */
+    intervalMs: number;
+    captureOptions: () => Promise<ReplayCaptureOptions> | ReplayCaptureOptions;
+    href: () => string;
+    now?: () => number;
+    onError?: (err: unknown) => void;
+}
+/**
+ * Records one session at a time: a frame every interval while in the foreground, skipping frames
+ * identical to the previous one; keyframes (Meta + FullSnapshot) for the first frame, a viewport
+ * change, the first frame after the foreground returns and after `screen()`, mutations otherwise,
+ * plus touches and Guidely markers. No capture while a finger is down; one {@link TOUCH_SETTLE_MS}
+ * after every touch ends; after {@link IDLE_FRAMES} unchanged captures the interval stretches to
+ * `min(4 × interval, 5 s)` until a changed frame, touch, `screen()` or Guidely event.
+ */
+declare class SessionRecorder {
+    private readonly opts;
+    private readonly intervalMs;
+    private readonly now;
+    private sid;
+    private foreground;
+    private generation;
+    private timer;
+    private timerDue;
+    private capturing;
+    private needKeyframe;
+    private hasKeyframe;
+    private lastFrame;
+    private unchanged;
+    private captureSoon;
+    private pendingCustom;
+    private touchDown;
+    private downX;
+    private downY;
+    private downAt;
+    private maxDistance;
+    private lastMoveAt;
+    private originX;
+    private originY;
+    /** Viewport of the last frame (points), for chunk metadata. */
+    viewportWidth: number;
+    viewportHeight: number;
+    constructor(opts: SessionRecorderOptions);
+    get sessionId(): string | null;
+    get isRecording(): boolean;
+    get currentIntervalMs(): number;
+    /** Starts (or keeps) recording `sessionId`; another session stops the current one first (uploading it). */
+    start(sessionId: string): void;
+    /** Stops recording; buffered events are uploaded unless `discard`. */
+    stop(discard: boolean): void;
+    /** App backgrounded: no captures; uploads what is buffered. */
+    pause(): void;
+    /** App foregrounded: resume with a keyframe. */
+    resume(): void;
+    /** A new screen: the next frame is a keyframe with the new href. */
+    onScreen(): void;
+    private activity;
+    /** Adds the `guidely` marker for an analytics event. */
+    addGuidelyEvent(name: string, customName?: string, guideId?: string): void;
+    /** A primary-pointer touch at (x, y) points from the React root view. */
+    touch(phase: TouchPhase, rootX: number, rootY: number): void;
+    private clearTimer;
+    /** Schedules the next capture `delay` ms from now, or keeps an earlier one when `ifSooner`. */
+    private schedule;
+    private tick;
+    private onFrame;
+}
+
 /**
  * AsyncStorage-compatible key/value storage (`@react-native-async-storage/async-storage`,
  * `expo-secure-store` wrappers, MMKV adapters…). Synchronous implementations work too.
@@ -338,7 +526,12 @@ 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. */
@@ -356,9 +549,13 @@ interface GuidelyOptions {
     /** Send analytics events (default `true`). Guides still render when disabled. */
     analytics?: boolean;
     consent?: ConsentState;
-    /** Host app version for `app.version` targeting rules and `app_install` / `app_update` events (e.g. from `expo-application`). */
+    /**
+     * 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. */
+    /** 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
@@ -368,6 +565,12 @@ interface GuidelyOptions {
      * 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. */
@@ -397,6 +600,16 @@ interface GuidelyOptions {
      */
     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;
@@ -478,7 +691,7 @@ interface UiState {
 }
 
 declare const SDK_NAME = "@guidelytech/react-native";
-declare const SDK_VERSION = "0.12.0";
+declare const SDK_VERSION = "0.14.0";
 declare const DEFAULT_API_URL = "https://guidelytech.com";
 /** Host-platform services the engine needs; the provider supplies React Native implementations. */
 interface PlatformBridge {
@@ -490,6 +703,8 @@ interface PlatformBridge {
         width: number;
         height: number;
     };
+    /** Session-replay screenshots; absent where the native replay module is not installed. */
+    capturer?: ScreenCapturer;
 }
 /** Mobile sessions persist across launches and expire after the configured inactivity timeout. */
 interface MobileSession extends SessionState {
@@ -547,6 +762,10 @@ declare class GuidelyClient {
     private lastAudiences;
     private backgroundedAt;
     private messenger;
+    private replayUploader;
+    private recorder;
+    /** Replay decision for the current session (sampled once; forced by start/stopSessionRecording). */
+    private replayDecision;
     private ui;
     private uiListeners;
     /** Feature flags for this environment: `guidely.flags.isEnabled("new-checkout")`. */
@@ -619,6 +838,26 @@ declare class GuidelyClient {
     /** The current screen name (last value passed to `screen()`). */
     getScreen(): string;
     private handleTap;
+    private replaySettings;
+    /** Reconciles recording with config, consent, readiness, the session and its sample decision. Idempotent. */
+    private syncReplay;
+    private createRecorder;
+    private replayCaptureOptions;
+    /**
+     * Records this session even when it was not sampled (still needs `sessionReplay.enabled`, replay
+     * enabled for the project, analytics consent and the native replay module). Sticks until the session ends.
+     */
+    startSessionRecording(): void;
+    /** Stops recording for the rest of this session; what was recorded is uploaded. */
+    stopSessionRecording(): void;
+    /** True while this session is being recorded. */
+    isRecording(): boolean;
+    /** The current analytics session id (also the replay id). */
+    getSessionId(): string;
+    /** True when touches should be passed to {@link recordTouch}. */
+    isRecordingTouches(): boolean;
+    /** A primary-pointer touch on the app, in window points (the provider's touch observer calls this). */
+    recordTouch(phase: TouchPhase, x: number, y: number): void;
     private captureAllowed;
     /** A capability runs when the project enables it (absent on old servers → off), no option turns it off and analytics are allowed. */
     private autocaptureOn;
@@ -642,7 +881,7 @@ declare class GuidelyClient {
     private appInfo;
     /**
      * Once per launch, as soon as a config is known: `app_install` / `app_update` from the stored
-     * version (when the app passes `appVersion` and `storage`), then `app_open` with `coldStart: true`.
+     * version (when the app version is known and the app passes `storage`), then `app_open` with `coldStart: true`.
      */
     private checkLaunch;
     private wentToBackground;
@@ -833,6 +1072,33 @@ declare class GuidelyClient {
     private log;
 }
 
+/**
+ * Host app and OS versions, read from native modules the app already links (never imported, so none
+ * of them is a dependency): `@guidelytech/react-native-replay`, `expo-application`, then
+ * `react-native-device-info`. React Native itself has no API for the app's own version.
+ */
+interface AppVersionInfo {
+    /** `CFBundleShortVersionString` / `versionName`. */
+    appVersion?: string;
+    /** `CFBundleVersion` / `versionCode`. */
+    appBuild?: string;
+}
+/** Where the lookups read from; the provider passes React Native's objects, tests pass fakes. */
+interface NativeSources {
+    platform: {
+        OS: string;
+        Version?: string | number;
+        constants?: Record<string, unknown>;
+    };
+    nativeModules: Record<string, unknown>;
+    /** `globalThis.expo.modules` in Expo SDK 50+ apps. */
+    expoModules?: Record<string, unknown>;
+}
+/** The host app's version and build, or `{}` when no linked module knows them. */
+declare function detectAppVersion(src: NativeSources): AppVersionInfo;
+/** The OS version: `18.1` on iOS, `14` on Android (falling back to the API level). */
+declare function detectOsVersion(src: NativeSources): string | undefined;
+
 /**
  * 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
@@ -892,8 +1158,9 @@ interface GuidelyMaskProps extends ViewProps {
     children?: ReactNode;
 }
 /**
- * Keeps the text of its children out of product analytics: taps inside it (or on an element that
- * contains it) are captured without `text`. Renders a plain `View`.
+ * Keeps its children out of product analytics and session replay: taps inside it (or on an element
+ * that contains it) are captured without `text`, and recordings paint over it. Renders a plain `View`
+ * (its `nativeID` is how the native recorder finds it).
  */
 declare function GuidelyMask({ children, ...rest }: GuidelyMaskProps): react.JSX.Element;
 
@@ -1050,4 +1317,4 @@ declare function useGuideState(idOrKey: string): {
 /** The guide currently running exclusively (flow, modal, survey…), or null. */
 declare function useActiveGuide(): PublishedGuide | null;
 
-export { 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 PlatformBridge, RageClickDetector, SDK_NAME, SDK_VERSION, type StepView, type SurveyView, type TapElement, type TapInfo, type TapProperties, TapTracker, TargetRegistry, type UiState, createSseParser, 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 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 };