@guidelytech/react-native 0.10.0 → 0.12.0

package/dist/index.d.ts

@@ -1,9 +1,10 @@
 import * as react from 'react';
 import { ReactNode } from 'react';
-import { SelectorStrategy, MessengerConfig, MessengerMessage, MessengerConversation, SdkArticlesResponse, ResourceCenterArticle, PublishedGuide, ProjectTheme, GuideStep, SdkConfigResponse, ChecklistTask, SdkEvent, TargetingContext, StepButton, ResourceCenterConfig, Placement } from '@guidelytech/shared';
-export { GuideStep, PublishedGuide, SdkConfigResponse } 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';
+import { ResourceCenterModuleId } from '@guidelytech/shared/runtime';
 import { KeyValueStore, ServerHealth, ChecklistProgressState, GuidelyEnvironment, ConsentState, GuidelyUser, 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';
@@ -50,6 +51,15 @@ declare class TargetRegistry {
     /** Frame of a visible target (the most recently mounted visible one when an id is used twice), else null. */
     measure(id: string): Promise<Rect | null>;
     private measureHandle;
+    /**
+     * The registered target on the current screen whose visible frame contains the point (window
+     * coordinates); the smallest one when targets are nested. Frames that do not answer within
+     * `timeoutMs` are skipped.
+     */
+    hitTest(x: number, y: number, timeoutMs?: number): Promise<{
+        id: string;
+        rect: Rect;
+    } | null>;
     /** First of `ids` that is mounted and visible. */
     resolve(ids: string[]): Promise<{
         id: string;
@@ -67,6 +77,123 @@ 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. */
+interface TapElement {
+    selector: string;
+    /** Component / host name (`Pressable`, `TouchableOpacity`, `Text`, `View`). */
+    tag: string;
+    /** Visible label; already empty for text fields and masked content. */
+    text?: string;
+    /** Window frame of the element, for the position inside it (heatmaps). */
+    measure?: () => Promise<Rect | null>;
+}
+/** One observed tap, reported by the provider's touch observer. */
+interface TapInfo {
+    /** Window coordinates in points. */
+    x: number;
+    y: number;
+    /** When the tap ended (ms since epoch); defaults to now. */
+    t?: number;
+    /** Innermost interactive element under the tap (touchable, `Pressable`, `accessibilityRole="button"`…), if found. */
+    element?: TapElement | null;
+    /** The view the tap hit, used for rage taps and heatmaps when there is no interactive element. */
+    hit?: TapElement | null;
+}
+/** `click` / `rage_click` properties on mobile (`ClickProperties` on the web plus `platform`). */
+interface TapProperties {
+    selector: string;
+    tag: string;
+    text?: string;
+    x: number;
+    y: number;
+    platform: string;
+    count?: number;
+}
+/**
+ * Detects rage taps: 3+ taps within 1s (each within 1s of the previous) and 30pt of the burst's
+ * first tap, reported once per burst. Same semantics as the web SDK's `RageClickDetector`
+ * (conformance vectors: `rageClicks` in `mobile/conformance/vectors.json`).
+ */
+declare class RageClickDetector {
+    private readonly threshold;
+    private readonly windowMs;
+    private readonly radius;
+    private clicks;
+    private fired;
+    constructor(threshold?: number, windowMs?: number, radius?: number);
+    /** Taps in the current burst once it has fired (rage), otherwise 0. */
+    get burst(): number;
+    /** Records a tap; returns the tap count when it completes a burst, otherwise 0. */
+    add(x: number, y: number, t: number): number;
+}
+/** Tap positions on the current screen, sent as one `heatmap` event per batch (40 points, screen change, background). */
+declare class HeatmapBuffer {
+    /** Screen path the buffered points belong to. */
+    url: string;
+    points: HeatmapPoint[];
+    /** Adds a tap (`burst` > 0 marks it and the burst's previous taps as rage); true when the batch is full. */
+    add(url: string, point: HeatmapPoint, burst: number): boolean;
+    /** Empties the buffer, returning what was in it. */
+    take(): {
+        url: string;
+        points: HeatmapPoint[];
+    } | null;
+}
+/**
+ * Tracks one primary-pointer touch and decides whether it was a tap. Feed it the touch events the
+ * provider observes; `end` returns the tap position (window points) or null.
+ */
+declare class TapTracker {
+    private start;
+    private moved;
+    /** A finger went down. A second finger while one is tracked cancels the gesture (not a tap). */
+    begin(x: number, y: number, t: number, touches: number, id?: unknown): void;
+    move(x: number, y: number, id?: unknown): void;
+    /** The finger lifted: the tap position when it moved ≤ 10pt and lasted < 1s, else null. */
+    end(x: number, y: number, t: number, id?: unknown): {
+        x: number;
+        y: number;
+    } | null;
+    cancel(): void;
+}
+
 /**
  * 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.
@@ -137,6 +264,8 @@ interface MessengerDeps {
     onError: (err: unknown) => void;
     /** The SDK API's circuit breaker, told how each reply stream went. */
     health?: ServerHealth;
+    /** The help center's language when it isn't the default; translated articles are fetched with `?locale=`. */
+    locale?: () => string | undefined;
     /** Poll intervals (ms): open thread, and unread badge otherwise. */
     pollMs?: {
         thread: number;
@@ -227,14 +356,29 @@ interface GuidelyOptions {
     /** Send analytics events (default `true`). Guides still render when disabled. */
     analytics?: boolean;
     consent?: ConsentState;
-    /** Host app version for `app.version` targeting rules. */
+    /** Host app version for `app.version` targeting rules and `app_install` / `app_update` events (e.g. from `expo-application`). */
     appVersion?: string;
+    /** Host app build number (`CFBundleVersion` / `versionCode`), sent as `build` with app lifecycle events. */
+    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>;
     /** 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;
@@ -334,13 +478,18 @@ interface UiState {
 }
 
 declare const SDK_NAME = "@guidelytech/react-native";
-declare const SDK_VERSION = "0.10.0";
+declare const SDK_VERSION = "0.12.0";
 declare const DEFAULT_API_URL = "https://guidelytech.com";
 /** Host-platform services the engine needs; the provider supplies React Native implementations. */
 interface PlatformBridge {
     device: DeviceEnvironment;
     /** Opens an external URL (React Native `Linking.openURL`). */
     openExternal(url: string): void;
+    /** Window size in points (React Native `Dimensions.get("window")`), for heatmaps. */
+    windowSize?(): {
+        width: number;
+        height: number;
+    };
 }
 /** Mobile sessions persist across launches and expire after the configured inactivity timeout. */
 interface MobileSession extends SessionState {
@@ -384,6 +533,7 @@ declare class GuidelyClient {
     private activeSurvey;
     private queued;
     private flows;
+    /** Checklists on screen, with the guide as rendered (in the visitor's language). */
     private checklists;
     private expanded;
     private surveyView;
@@ -403,6 +553,26 @@ declare class GuidelyClient {
     readonly flags: FlagsClient;
     /** Experiments already reported this session (`experiment_viewed` is sent once per session). */
     private exposures;
+    private readonly rage;
+    private readonly heatmap;
+    /** Taps are processed in order (target frames are measured asynchronously). */
+    private tapChain;
+    /** When the current screen's foreground measurement started; `screenLeft` once it has been reported. */
+    private screenStartedAt;
+    private screenLeft;
+    /** Last `app_open` (cold start or return to the foreground), for `app_background.foregroundMs`. */
+    private openedAt;
+    private launchChecked;
+    /** An identity was stored before this launch (an existing install adopting lifecycle events). */
+    private hadIdentity;
+    /** Language set with `setLocale()` (or the `locale` option). */
+    private locale;
+    /** Language each shown guide was rendered in; added to its events as `locale`. */
+    private guideLocales;
+    /** The resource center in the visitor's language, recomputed when the config or language changes. */
+    private localizedRc;
+    /** "What's new" last-seen time when the resource center opened (entries after it read as new). */
+    private announcementsSeenAtOpen;
     private readonly customListeners;
     private readonly eventBus;
     constructor(options: GuidelyOptions, bridge: PlatformBridge);
@@ -449,10 +619,54 @@ declare class GuidelyClient {
     /** The current screen name (last value passed to `screen()`). */
     getScreen(): string;
     private handleTap;
+    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;
+    /** `page_view` from `screen()` predates autocapture: only an explicit opt-out stops it. */
+    private pageviewsOn;
+    /** True when taps are worth observing (clicks, rage taps or heatmaps are on); the provider skips resolving views otherwise. */
+    isTapCaptureOn(): boolean;
+    /**
+     * 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
+     * (smallest wins) takes precedence over the resolved element and is reported as `#<id>`.
+     */
+    recordTap(tap: TapInfo): void;
+    private processTap;
+    /** Sends the buffered heatmap taps as one `heatmap` event attributed to the screen they happened on. */
+    private flushHeatmap;
+    private windowSize;
+    /** Ends the foreground measurement of the current screen with a `page_leave` (once per measurement). */
+    private leaveScreen;
+    /** `{ appVersion, build }` of this launch, without unknown keys. */
+    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`.
+     */
+    private checkLaunch;
+    private wentToBackground;
+    private cameToForeground;
     /** Builds the targeting context for the current moment. */
     getContext(): TargetingContext;
     private isTargeted;
     private isEligible;
+    /** Guide throttling: may this guide launch automatically now? */
+    private throttleAllows;
+    private recordLaunch;
+    /** Guides and A/B test control groups, which are evaluated the same way but never render. */
+    private candidates;
+    private holdoutFor;
+    /** The visitor's language candidates, most preferred first: `setLocale()` / `locale` option, traits, device. */
+    private locales;
+    private defaultLocale;
+    /** The guide in the visitor's language (remembered so its events carry `locale`). */
+    private localize;
+    /**
+     * Sets the language for guides and the resource center (`null` = back to the user's traits and
+     * the device language). Guides already on screen keep their language; the resource center re-renders.
+     */
+    setLocale(locale: string | null): void;
     private triggerFires;
     private evaluate;
     private armVisibility;
@@ -502,8 +716,28 @@ declare class GuidelyClient {
     closeSurvey(guideId: string): void;
     /** The visitor's audiences (from the last identify), for audience-targeted help articles. */
     getAudienceIds(): readonly string[];
+    /** The published resource center in the visitor's language, or null when it is off. */
     getResourceCenter(): ResourceCenterConfig | null;
+    /** The resource center in the visitor's language (cached until the config or language changes). */
+    private localizedResourceCenter;
+    /** Evaluates targeting rules (e.g. a resource-center section's) for the current visitor and screen. */
+    matchesTargeting(rules: RuleGroup | null | undefined): boolean;
+    /** Resource-center sections this visitor sees, in order (disabled and non-matching ones left out). */
+    getResourceCenterModules(): ResourceCenterModuleId[];
+    /**
+     * Sections of the messenger's Help tab, in order: the resource center's modules without "What's
+     * new" (the messenger has its own News tab); every section when no resource center is published.
+     */
+    getHelpModules(): ResourceCenterModuleId[];
+    /** "What's new" entries this visitor sees (newest first); empty when the section is off. */
+    getAnnouncements(): ResourceCenterAnnouncement[];
+    /** "What's new" entries published since the visitor last opened the resource center. */
+    getUnreadAnnouncements(): number;
+    /** Whether an entry is new to the visitor in the resource center that is open now. */
+    isAnnouncementNew(a: ResourceCenterAnnouncement): boolean;
     searchResourceCenter(q: string): Promise<ResourceCenterArticle[]>;
+    /** The language of the resource center as shown, when it isn't the default (sent with article fetches). */
+    private articleLocale;
     articleViewed(article: ResourceCenterArticle): void;
     getChecklistProgress(idOrKey: string): ChecklistProgressState;
     completeChecklistTask(idOrKey: string, taskId: string): void;
@@ -530,6 +764,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;
@@ -543,6 +781,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;
@@ -563,7 +803,7 @@ declare class GuidelyClient {
         guides: {
             id: string;
             key: string;
-            kind: "tooltip" | "modal" | "banner" | "checklist" | "survey" | "flow" | "announcement";
+            kind: "banner" | "tooltip" | "modal" | "checklist" | "survey" | "flow" | "announcement";
         }[];
         activeGuide: {
             status: GuideStatus;
@@ -593,32 +833,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
@@ -674,6 +888,15 @@ interface OverlayProps {
  */
 declare function GuidelyOverlay({ client, insets: insetsProp, launcherOffset }: OverlayProps): react.JSX.Element;
 
+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`.
+ */
+declare function GuidelyMask({ children, ...rest }: GuidelyMaskProps): react.JSX.Element;
+
 /**
  * Tiny, tolerant HTML → rich-text converter for guide bodies (already sanitized server-side).
  * Supports p, div, br, strong/b, em/i, u, a, code, ul/ol/li, h1–h6 and blockquote; every other tag
@@ -827,4 +1050,4 @@ declare function useGuideState(idOrKey: string): {
 /** The guide currently running exclusively (flow, modal, survey…), or null. */
 declare function useActiveGuide(): PublishedGuide | null;
 
-export { type ChecklistView, DEFAULT_API_URL, type DeviceEnvironment, Feature, FeatureFlag, type FeatureProps, FeatureValue, type FeatureValueProps, FlagsProvider, type FlagsProviderProps, type GuideStepInfo, GuidelyClient, type GuidelyEventName, type GuidelyEvents, type GuidelyOptions, GuidelyOverlay, GuidelyProvider, type GuidelyProviderProps, GuidelyScreenScope, type GuidelyStorage, GuidelyTarget, type GuidelyTargetProps, type Insets, Messenger, type MessengerSnapshot, type MessengerTab, type MessengerThread, type MessengerView, type PlatformBridge, SDK_NAME, SDK_VERSION, type StepView, type SurveyView, 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, 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 };