@guidelytech/sdk-core 0.2.0 → 0.4.0

package/dist/index.d.cts

@@ -1,168 +1,12 @@
 import * as _guidelytech_guide_runtime from '@guidelytech/guide-runtime';
-import { PublishedGuide, FrequencyConfig, ProjectTheme, SdkConfigResponse, ChecklistTask, MessengerMessage, MessengerConversation, SdkEvent, TargetingContext, SelectorStrategy, AuthoringPick, AppSnapshot } from '@guidelytech/shared';
-export { AppSnapshot, GuideConfig, GuideStep, PublishedGuide, SdkConfigResponse, SdkEvent, TargetingContext } from '@guidelytech/shared';
+import { TargetingContext, PublishedGuide, ProjectTheme, SelectorStrategy, AuthoringPick, AppSnapshot } from '@guidelytech/shared';
+export { AppSnapshot, AutocaptureSettings, ExceptionProperties, GuideConfig, GuideStep, PublishedGuide, SdkConfigResponse, SdkEvent, StackFrame, TargetingContext } from '@guidelytech/shared';
 import { MessengerTab } from '@guidelytech/guide-runtime/messenger';
-
-/** Per-guide state kept locally and merged with the server's `IdentifyResponse.guideState`. */
-interface GuideLocalState {
-    impressions: number;
-    completedAt?: string | null;
-    dismissedAt?: string | null;
-    lastShownAt?: string | null;
-}
-/**
- * Pure frequency evaluation. `shownThisSession` comes from session storage.
- * - `once`: a single impression ever (unless `reshowAfterDismiss` and it was only dismissed).
- * - `once_per_session`: at most once per browser session.
- * - `every_time`: on every trigger (still blocked by completion/dismissal rules below).
- * - `interval`: at most once every `intervalHours`.
- * `maxImpressions` caps total impressions; dismissal blocks re-showing unless `reshowAfterDismiss`
- * (then `cooldownHours` must have elapsed); completion blocks unless mode is `every_time`.
- */
-declare function isFrequencyEligible(freq: FrequencyConfig, state: GuideLocalState | undefined, shownThisSession: boolean, now?: number): boolean;
-/**
- * Exclusive guides (flows, modals, tooltips, announcements, surveys) run one at a time.
- * Banners, checklists and hotspot-only tooltips can coexist with an active flow.
- */
-declare function isExclusiveGuide(guide: PublishedGuide): boolean;
-/** Is `a` mutually exclusive with `b` (by id or key, in either direction)? */
-declare function areMutuallyExclusive(a: PublishedGuide, b: PublishedGuide): boolean;
-/** Survey scheduling window. */
-declare function isWithinSchedule(guide: PublishedGuide, now?: number): boolean;
-
-type StorageKind = "local" | "session" | "memory";
-/** Minimal synchronous key/value store; never throws (private mode, quota, SSR). */
-interface KeyValueStore {
-    get(key: string): string | null;
-    set(key: string, value: string): void;
-    remove(key: string): void;
-}
-/** Creates a store of the requested kind, degrading to memory when unavailable. */
-declare function createStorage(kind?: StorageKind): KeyValueStore;
-/** Storage keys used by the SDK (documented for integrators). */
-declare const KEYS: {
-    readonly anon: "guidely:anon";
-    readonly seen: "guidely:seen";
-    readonly config: (key: string) => string;
-    readonly etag: (key: string) => string;
-    readonly state: (key: string) => string;
-    readonly user: (key: string) => string;
-    readonly queue: (key: string) => string;
-    readonly session: "guidely:session";
-    readonly active: "guidely:active";
-    readonly authoring: "guidely:authoring";
-    /** Messenger conversations this browser can read: [{ id, token }]. */
-    readonly conversations: (key: string) => string;
-};
-
-type GuidelyEnvironment = "development" | "staging" | "production";
-type ConsentState = "granted" | "denied" | "pending";
-interface GuidelyAccount {
-    id: string;
-    traits?: Record<string, unknown>;
-}
-interface GuidelyUser {
-    id: string;
-    traits?: Record<string, unknown>;
-    account?: GuidelyAccount;
-}
-interface GuidelyOptions {
-    /** Environment public key, e.g. `pk_dev_…`. Not a secret. */
-    projectId: string;
-    environment?: GuidelyEnvironment;
-    /** Base URL of the Guidely API (default `https://api.guidely.app`; use `http://localhost:3000` locally). */
-    apiUrl?: string;
-    /** Log trigger decisions and requests to the console. */
-    debug?: boolean;
-    /** Send analytics events (default `true`). Guides still render when disabled. */
-    analytics?: boolean;
-    /** `pending` buffers events until `setConsent("granted")`; `denied` disables analytics. */
-    consent?: ConsentState;
-    /** Where to persist identity, cached config and the event queue (default `local`). */
-    storage?: StorageKind;
-    /** Interval for re-checking element-visibility triggers while the page is idle (default 1000ms). */
-    pollIntervalMs?: number;
-    /** How often to refresh the published config (default 5 minutes). */
-    configRefreshMs?: number;
-    /** Elements whose text must never be captured (authoring snapshots). Merged with the project setting. */
-    maskSelectors?: string[];
-    onError?: (error: Error) => void;
-    /** Overrides for the project theme (colors, radius, font). */
-    theme?: Partial<ProjectTheme>;
-    /** Identify this user as soon as the client initialises. */
-    user?: GuidelyUser;
-    /** Custom fetch (tests / polyfills). */
-    fetch?: typeof fetch;
-    /** Disable the authoring-mode URL parameter detection. */
-    disableAuthoring?: boolean;
-}
-interface ChecklistProgressState {
-    completedTaskIds: string[];
-    completedAt?: string | null;
-    dismissedAt?: string | null;
-}
-/** Everything the client persists per project key (`guidely:state:<key>`). */
-interface PersistedState {
-    guides: Record<string, GuideLocalState>;
-    checklists: Record<string, ChecklistProgressState>;
-    surveysSubmitted: string[];
-    audienceIds: string[];
-    firstSeenAt?: string;
-}
-interface SessionState {
-    id: string;
-    startedAt: string;
-    shownGuides: string[];
-    events: string[];
-}
-interface GuideStepInfo {
-    guide: PublishedGuide;
-    stepId: string;
-    stepIndex: number;
-}
-interface GuidelyEvents {
-    /** Config loaded (from network or cache) and triggers evaluated. */
-    ready: (config: SdkConfigResponse) => void;
-    /** Config (re)loaded. */
-    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;
-    "messenger:open": () => void;
-    /** A Scout or teammate message arrived in the messenger. */
-    "conversation:message": (info: {
-        message: MessengerMessage;
-        conversation: MessengerConversation;
-    }) => void;
-    error: (error: Error) => void;
-    /** Every tracked event (custom and lifecycle). */
-    track: (event: SdkEvent) => void;
-    identify: (info: {
-        userId: string | null;
-        anonymousId: string;
-    }) => void;
-    authoring: (info: {
-        active: boolean;
-    }) => void;
-}
-type GuidelyEventName = keyof GuidelyEvents;
+import { k as GuidelyOptions, c as GuidelyAccount, a as ConsentState, C as ChecklistProgressState, l as GuidelyEvents, e as GuidelyUser, G as GuideLocalState, S as SessionState } from './types-BZ9r3Fs9.cjs';
+export { E as EventQueue, b as EventQueueOptions, n as GuideStepInfo, d as GuidelyEnvironment, o as GuidelyEventName, K as KEYS, f as KeyValueStore, P as PersistedState, p as StorageKind, g as areMutuallyExclusive, q as createStorage, i as isExclusiveGuide, h as isFrequencyEligible, j as isWithinSchedule } from './types-BZ9r3Fs9.cjs';
 
 declare const SDK_NAME = "@guidelytech/sdk-core";
-declare const SDK_VERSION = "0.2.0";
+declare const SDK_VERSION = "0.4.0";
 declare const DEFAULT_API_URL = "https://api.guidely.app";
 /**
  * Framework-independent Guidely client. Create one per page with {@link createGuidely} or
@@ -204,6 +48,18 @@ declare class GuidelyClient {
     private lastAudiences;
     /** Set once the app calls identify()/reset(); bootstrap then leaves identity alone instead of re-identifying. */
     private identitySettled;
+    /** Created once the recorder chunk has loaded (it carries the replay controller). */
+    private replay;
+    private replayLoading;
+    private readonly pageTracker;
+    private readonly rage;
+    private readonly heatmap;
+    private readonly exceptionThrottle;
+    /** Exceptions seen before the config was loaded (reported once it is known whether the server accepts them). */
+    private earlyExceptions;
+    private initialPageViewSent;
+    private pageViewUrl;
+    private pageLeft;
     constructor(options: GuidelyOptions);
     /** Loads config (cache first, then network), wires listeners and evaluates triggers. Idempotent. */
     init(): Promise<void>;
@@ -212,6 +68,8 @@ declare class GuidelyClient {
     private bootstrap;
     private fetchConfig;
     private wireListeners;
+    /** Uncaught errors + unhandled rejections; attached before the config loads so boot errors are kept. */
+    private wireErrorListeners;
     /** Re-fetches the published config and re-evaluates triggers. */
     refresh(): Promise<void>;
     /** Tears everything down: guides, widgets, listeners, timers, host element. Re-init is allowed via a new client. */
@@ -239,6 +97,49 @@ declare class GuidelyClient {
     private readonly eventBus;
     private handleNavigation;
     private handleDocumentClick;
+    /** Records activity; starts a new session after `sessionTimeoutMinutes` of inactivity or 24h. */
+    private touchSession;
+    private rotateSession;
+    /** Autocapture, error tracking and replay need analytics on, consent granted and no authoring session. */
+    private captureAllowed;
+    /** A capability is on when the project enables it (absent on old servers → off) and no option turns it off. */
+    private autocaptureOn;
+    /** Page views on SPA navigation predate autocapture: only an explicit opt-out stops them. */
+    private pageviewsOn;
+    private trackPageView;
+    /** Emits `page_leave` for the page being left and starts measuring `nextUrl` (null: page unload). */
+    private leavePage;
+    private autocaptureClick;
+    /** Bins one pointer sample into the heatmap buffer. Not session activity. */
+    private sampleMove;
+    /** Sends the buffered heatmap clicks as one `heatmap` event attributed to the page they happened on. */
+    private flushHeatmap;
+    private captureGlobalException;
+    /**
+     * Reports a caught error as an `exception` event (`source: "manual"`, `handled: true`), grouped
+     * into an issue on the Errors page. Extra properties are attached to the occurrence. Needs the
+     * project's error tracking on (plus analytics + consent); `captureErrors: false` does not stop it.
+     */
+    captureException(error: unknown, properties?: Record<string, unknown>): void;
+    private sendException;
+    private maskSelector;
+    private maskAllText;
+    /** Replay settings for this installation, or null when the project (or an option) disables replay. */
+    private replayConfig;
+    /** Reconciles capture with the current config / consent / authoring state. Idempotent. */
+    private syncCapture;
+    private syncReplay;
+    /**
+     * Records this session even when it was not sampled, provided the project has session replay
+     * enabled (and analytics + consent allow it). The decision sticks for the rest of the session.
+     */
+    startSessionRecording(): void;
+    /** Stops recording for the rest of this session (what was recorded so far is uploaded). */
+    stopSessionRecording(): void;
+    /** True while the session is being recorded. */
+    isRecording(): boolean;
+    /** The current analytics session id (rotates after inactivity; also the replay id). */
+    getSessionId(): string;
     /** Builds the targeting context for the current moment. */
     getContext(): TargetingContext;
     private isTargeted;
@@ -370,61 +271,13 @@ interface ContextInput {
     locale?: string;
     device?: DeviceInfo;
     now?: Date;
+    platform?: string;
+    screen?: string;
+    appVersion?: string;
 }
 /** Builds the `TargetingContext` consumed by `evaluateRules`. */
 declare function buildContext(input: ContextInput): TargetingContext;
 
-interface EventQueueOptions {
-    store: KeyValueStore;
-    storageKey: string;
-    /** Sends one batch. Resolve `{ ok: true }` on success, `{ ok: false, retry }` otherwise. */
-    send: (events: SdkEvent[]) => Promise<{
-        ok: boolean;
-        retry?: boolean;
-    }>;
-    /** Synchronous best-effort send used on page hide. */
-    beacon?: (events: SdkEvent[]) => boolean;
-    /** Should events be flushed right now? (analytics enabled + consent granted). */
-    enabled: () => boolean;
-    flushIntervalMs?: number;
-    maxQueue?: number;
-    batchSize?: number;
-    maxAttempts?: number;
-    onError?: (err: unknown) => void;
-}
-/**
- * Bounded, persisted event queue. Batches ≤50 events every 2s (or on demand), dedupes by
- * `eventId`, retries with exponential backoff (1s→30s, 5 attempts) and keeps failed events for
- * the next flush. Drops the oldest events once the queue exceeds 200.
- */
-declare class EventQueue {
-    private readonly opts;
-    private events;
-    private timer;
-    private retryTimer;
-    private inflight;
-    private inflightIds;
-    private attempt;
-    private destroyed;
-    private readonly flushIntervalMs;
-    private readonly maxQueue;
-    private readonly batchSize;
-    private readonly maxAttempts;
-    constructor(opts: EventQueueOptions);
-    get size(): number;
-    /** Pending events (read-only copy, for debugging). */
-    peek(): SdkEvent[];
-    enqueue(event: SdkEvent): void;
-    private persist;
-    private schedule;
-    /** Sends queued events now (one batch at a time). Safe to call at any time. */
-    flush(): Promise<void>;
-    /** Best-effort synchronous flush on unload using `sendBeacon`. */
-    flushSync(): void;
-    clear(): void;
-    destroy(): void;
-}
-
 type Listener = (url: string) => void;
 /**
  * Detects SPA navigation: patches `history.pushState`/`replaceState` (reference counted, restored
@@ -501,6 +354,26 @@ type AuthoringIncomingMessage = {
  */
 declare function captureSnapshot(doc: Document, maskSelectors: string[], maxBytes?: number): AppSnapshot | null;
 
+/** `click` / `rage_click` event properties. */
+interface ClickProperties {
+    tag: string;
+    text?: string;
+    selector: string;
+    href?: string;
+    x: number;
+    y: number;
+    count?: number;
+}
+
+/** What `page_leave` reports for the page being left. */
+interface PageLeaveInfo {
+    url: string;
+    /** Time the page was visible (pauses while `document.hidden`). */
+    durationMs: number;
+    /** Furthest point scrolled to, as a percentage (0–100) of the page height. */
+    scrollDepth: number;
+}
+
 /**
  * @guidelytech/sdk-core — framework-independent Guidely browser SDK.
  *
@@ -516,4 +389,4 @@ declare const Guidely: {
     version: string;
 };
 
-export { AUTHORING_PARAM, type AuthoringIncomingMessage, type AuthoringOutgoingMessage, type ChecklistProgressState, type ConsentState, type ContextInput, DEFAULT_API_URL, type DeviceInfo, EventQueue, type EventQueueOptions, type GuideLocalState, type GuideStepInfo, Guidely, type GuidelyAccount, GuidelyClient, type GuidelyEnvironment, type GuidelyEventName, type GuidelyEvents, type GuidelyOptions, type GuidelyUser, HEARTBEAT_MS, KEYS, type KeyValueStore, type PersistedState, SDK_NAME, SDK_VERSION, type SessionState, type StorageKind, areMutuallyExclusive, buildContext, captureSnapshot, createGuidely, createStorage, Guidely as default, detectDevice, isExclusiveGuide, isFrequencyEligible, isWithinSchedule, watchNavigation };
+export { AUTHORING_PARAM, type AuthoringIncomingMessage, type AuthoringOutgoingMessage, ChecklistProgressState, type ClickProperties, ConsentState, type ContextInput, DEFAULT_API_URL, type DeviceInfo, GuideLocalState, Guidely, GuidelyAccount, GuidelyClient, GuidelyEvents, GuidelyOptions, GuidelyUser, HEARTBEAT_MS, type PageLeaveInfo, SDK_NAME, SDK_VERSION, SessionState, buildContext, captureSnapshot, createGuidely, Guidely as default, detectDevice, watchNavigation };