@guidelytech/react-native 0.11.0 → 0.13.0

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { SelectorStrategy, AutocaptureSettings, HeatmapPoint, MessengerConfig, MessengerMessage, MessengerConversation, SdkArticlesResponse, ResourceCenterArticle, PublishedGuide, ProjectTheme, GuideStep, SdkConfigResponse, ChecklistTask, SdkEvent, TargetingContext, StepButton, ResourceCenterConfig, RuleGroup, ResourceCenterAnnouncement, Placement } from '@guidelytech/shared';
+import { SelectorStrategy, Placement, AutocaptureSettings, HeatmapPoint, MessengerConfig, MessengerMessage, MessengerConversation, SdkArticlesResponse, ResourceCenterArticle, PublishedGuide, ProjectTheme, GuideStep, SdkConfigResponse, ChecklistTask, SdkEvent, 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';
@@ -77,6 +77,41 @@ declare class TargetRegistry {
 
 type GuideStatus = "idle" | "running" | "waiting_url" | "waiting_target" | "ended";
 
+type Side = "top" | "bottom" | "left" | "right";
+interface Insets {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+}
+interface CardPosition {
+    x: number;
+    y: number;
+    side: Side;
+    /** Arrow centre along the card edge facing the target (px from the card's left/top). */
+    arrow: number;
+}
+/**
+ * Places a card of `size` next to `target` inside `viewport` minus `insets`, honouring the step's
+ * placement when it fits and flipping (then falling back to below/above) when it does not.
+ */
+declare function positionCard(target: Rect, size: {
+    width: number;
+    height: number;
+}, viewport: {
+    width: number;
+    height: number;
+}, insets: Insets, placement: Placement, offset: number): CardPosition;
+
+/**
+ * Where the visitor dragged the Scout bubble on this device: the side edge it snapped to and how
+ * high it sits, as a fraction of the allowed range (0 = the default bottom position, 1 = highest).
+ */
+interface LauncherPlacement {
+    side: "left" | "right";
+    fraction: number;
+}
+
 /** `autocapture` option: `false` turns every capability off, an object turns single ones off. */
 type AutocaptureOption = boolean | Partial<AutocaptureSettings>;
 /** The element a tap resolved to (or the view it hit), as `click` properties need it. */
@@ -289,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.
@@ -333,6 +556,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. */
@@ -362,6 +591,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;
@@ -443,7 +682,7 @@ interface UiState {
 }
 
 declare const SDK_NAME = "@guidelytech/react-native";
-declare const SDK_VERSION = "0.11.0";
+declare const SDK_VERSION = "0.13.0";
 declare const DEFAULT_API_URL = "https://guidelytech.com";
 /** Host-platform services the engine needs; the provider supplies React Native implementations. */
 interface PlatformBridge {
@@ -455,6 +694,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 {
@@ -512,6 +753,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")`. */
@@ -584,6 +829,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;
@@ -729,6 +994,10 @@ declare class GuidelyClient {
     private syncMessenger;
     /** The Scout messenger store when Scout is on for this platform (rendered by the overlay). */
     getMessenger(): Messenger | null;
+    /** Where the visitor dragged the messenger bubble on this device, or null to use the configured spot. */
+    getMessengerLauncherPlacement(): LauncherPlacement | null;
+    /** Remembers the bubble's spot on this device (in memory only when no `storage` was passed). */
+    setMessengerLauncherPlacement(placement: LauncherPlacement): void;
     /** Opens the Scout messenger, optionally on a tab. No-op when Scout is off for this platform. */
     openMessenger(tab?: MessengerTab): void;
     closeMessenger(): void;
@@ -742,6 +1011,8 @@ declare class GuidelyClient {
     getFeatureDetails<T extends JsonValue>(key: string, fallback: T): FlagDetails<FlagValue<T>>;
     /** Calls `cb` whenever flag values may have changed. Returns an unsubscribe function. */
     onFlagsChange(cb: () => void): () => void;
+    /** Device facts on every screen view, read by the Pages devices / browsers breakdowns. */
+    private deviceProperties;
     /** Attributes flags are evaluated with: identity, traits, account, audiences, screen and device. */
     private flagContext;
     private syncFlagAttributes;
@@ -792,32 +1063,6 @@ declare class GuidelyClient {
     private log;
 }
 
-type Side = "top" | "bottom" | "left" | "right";
-interface Insets {
-    top: number;
-    bottom: number;
-    left: number;
-    right: number;
-}
-interface CardPosition {
-    x: number;
-    y: number;
-    side: Side;
-    /** Arrow centre along the card edge facing the target (px from the card's left/top). */
-    arrow: number;
-}
-/**
- * Places a card of `size` next to `target` inside `viewport` minus `insets`, honouring the step's
- * placement when it fits and flipping (then falling back to below/above) when it does not.
- */
-declare function positionCard(target: Rect, size: {
-    width: number;
-    height: number;
-}, viewport: {
-    width: number;
-    height: number;
-}, insets: Insets, placement: Placement, offset: number): CardPosition;
-
 /**
  * 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
@@ -877,8 +1122,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;
 
@@ -1035,4 +1281,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 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, 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, guidelyScreenLayout, htmlToText, noopClient, parseHtml, positionCard, targetIdsFor, useActiveGuide, useChecklistProgress, useFeatureValue, useFlag, useFlagDetails, useFlags, useFlagsClient, useFlagsReady, useGuideState, useGuidely, useGuidelyEvent, useGuidelyIdentify, useGuidelyNavigation, useGuidelyReady, useGuidelyScreen, useGuidelyTarget };