@guidelytech/sdk-core 0.15.0 → 0.17.0

package/dist/http-Cb6KYYFv.d.cts

@@ -1,61 +0,0 @@
-import { S as ServerHealth } from './health-sbP9JwTE.cjs';
-
-interface ApiResponse<T> {
-    status: number;
-    ok: boolean;
-    data: T | null;
-    etag: string | null;
-}
-type FetchLike = typeof fetch;
-/** Thin HTTP client for the public SDK API. Adds the public key as query + header. */
-declare class Api {
-    private readonly baseUrl;
-    private readonly key;
-    private readonly fetchImpl?;
-    /** Reachability of the API, fed by every answer (see {@link ServerHealth}). */
-    readonly health: ServerHealth;
-    constructor(baseUrl: string, key: string, fetchImpl?: FetchLike | undefined, health?: ServerHealth);
-    /** Feeds an answer (or a failed request, `null`) into {@link health}. */
-    private observe;
-    url(path: string, params?: Record<string, string | undefined>): string;
-    private get fetcher();
-    request<T>(method: "GET" | "POST", path: string, options?: {
-        body?: unknown;
-        etag?: string | null;
-        params?: Record<string, string | undefined>;
-        keepalive?: boolean;
-        timeoutMs?: number;
-        headers?: Record<string, string>;
-    }): Promise<ApiResponse<T>>;
-    get<T>(path: string, options?: {
-        etag?: string | null;
-        params?: Record<string, string | undefined>;
-        headers?: Record<string, string>;
-    }): Promise<ApiResponse<T>>;
-    post<T>(path: string, body: unknown, options?: {
-        params?: Record<string, string | undefined>;
-        keepalive?: boolean;
-        headers?: Record<string, string>;
-    }): Promise<ApiResponse<T>>;
-    /** Multipart POST (file uploads). No Content-Type header: the browser adds it with the boundary. */
-    postForm<T>(path: string, form: FormData, options?: {
-        params?: Record<string, string | undefined>;
-        timeoutMs?: number;
-    }): Promise<ApiResponse<T>>;
-    /**
-     * POST that may answer with server-sent events. Each event is passed to `onEvent`; a JSON answer is
-     * returned instead. Scout replies can take a while, so there is no overall timeout: the response
-     * must start within 30 s and then never go quiet for more than 60 s (the server sends keepalives),
-     * otherwise the request is aborted and rejects.
-     */
-    stream<T>(path: string, body: unknown, onEvent: (event: string, data: unknown) => void, headers?: Record<string, string>): Promise<ApiResponse<T>>;
-    /** `navigator.sendBeacon` when available (page unload); returns false when it could not be queued. */
-    beacon(path: string, body: unknown): boolean;
-}
-declare const sleep: (ms: number) => Promise<void>;
-/** Exponential backoff helper: 1s → 2s → 4s … capped. */
-declare function backoffMs(attempt: number, baseMs?: number, maxMs?: number): number;
-/** Fire-and-forget POST with bounded retries (used for state sync; never blocks UI). */
-declare function postWithRetry<T>(api: Api, path: string, body: unknown, attempts?: number, baseMs?: number): Promise<ApiResponse<T> | null>;
-
-export { Api as A, type FetchLike as F, type ApiResponse as a, backoffMs as b, postWithRetry as p, sleep as s };

package/dist/http-D047Ngxk.d.ts

@@ -1,61 +0,0 @@
-import { S as ServerHealth } from './health-sbP9JwTE.js';
-
-interface ApiResponse<T> {
-    status: number;
-    ok: boolean;
-    data: T | null;
-    etag: string | null;
-}
-type FetchLike = typeof fetch;
-/** Thin HTTP client for the public SDK API. Adds the public key as query + header. */
-declare class Api {
-    private readonly baseUrl;
-    private readonly key;
-    private readonly fetchImpl?;
-    /** Reachability of the API, fed by every answer (see {@link ServerHealth}). */
-    readonly health: ServerHealth;
-    constructor(baseUrl: string, key: string, fetchImpl?: FetchLike | undefined, health?: ServerHealth);
-    /** Feeds an answer (or a failed request, `null`) into {@link health}. */
-    private observe;
-    url(path: string, params?: Record<string, string | undefined>): string;
-    private get fetcher();
-    request<T>(method: "GET" | "POST", path: string, options?: {
-        body?: unknown;
-        etag?: string | null;
-        params?: Record<string, string | undefined>;
-        keepalive?: boolean;
-        timeoutMs?: number;
-        headers?: Record<string, string>;
-    }): Promise<ApiResponse<T>>;
-    get<T>(path: string, options?: {
-        etag?: string | null;
-        params?: Record<string, string | undefined>;
-        headers?: Record<string, string>;
-    }): Promise<ApiResponse<T>>;
-    post<T>(path: string, body: unknown, options?: {
-        params?: Record<string, string | undefined>;
-        keepalive?: boolean;
-        headers?: Record<string, string>;
-    }): Promise<ApiResponse<T>>;
-    /** Multipart POST (file uploads). No Content-Type header: the browser adds it with the boundary. */
-    postForm<T>(path: string, form: FormData, options?: {
-        params?: Record<string, string | undefined>;
-        timeoutMs?: number;
-    }): Promise<ApiResponse<T>>;
-    /**
-     * POST that may answer with server-sent events. Each event is passed to `onEvent`; a JSON answer is
-     * returned instead. Scout replies can take a while, so there is no overall timeout: the response
-     * must start within 30 s and then never go quiet for more than 60 s (the server sends keepalives),
-     * otherwise the request is aborted and rejects.
-     */
-    stream<T>(path: string, body: unknown, onEvent: (event: string, data: unknown) => void, headers?: Record<string, string>): Promise<ApiResponse<T>>;
-    /** `navigator.sendBeacon` when available (page unload); returns false when it could not be queued. */
-    beacon(path: string, body: unknown): boolean;
-}
-declare const sleep: (ms: number) => Promise<void>;
-/** Exponential backoff helper: 1s → 2s → 4s … capped. */
-declare function backoffMs(attempt: number, baseMs?: number, maxMs?: number): number;
-/** Fire-and-forget POST with bounded retries (used for state sync; never blocks UI). */
-declare function postWithRetry<T>(api: Api, path: string, body: unknown, attempts?: number, baseMs?: number): Promise<ApiResponse<T> | null>;
-
-export { Api as A, type FetchLike as F, type ApiResponse as a, backoffMs as b, postWithRetry as p, sleep as s };

package/dist/types-BDlebXrm.d.ts

@@ -1,314 +0,0 @@
-import { SdkEvent, PublishedGuide, FrequencyConfig, GuideThrottlingSettings, AutocaptureSettings, NetworkRequest, ProjectTheme, SdkConfigResponse, ChecklistTask, MessengerMessage, MessengerConversation } from '@guidelytech/shared';
-import { K as KeyValueStore, S as ServerHealth, c as StorageKind } from './health-sbP9JwTE.js';
-import { FlagsClientOptions } from '@guidelytech/flags';
-import { AgentTurnInput } from '@guidelytech/shared/runtime';
-
-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;
-    /** API reachability: sends wait while its circuit is open, and beaconed events are only forgotten while it is reachable. */
-    health?: ServerHealth;
-    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`, and keeps failed events (also across page loads) until the server takes them:
- * retries back off 1s→60s, wait while the API's circuit is open, and start again as soon as it
- * recovers. Drops the oldest events once the queue exceeds 500.
- */
-declare class EventQueue {
-    private readonly opts;
-    private events;
-    private timer;
-    private retryTimer;
-    private inflight;
-    private inflightIds;
-    private attempt;
-    private destroyed;
-    private offRecover;
-    private readonly flushIntervalMs;
-    private readonly maxQueue;
-    private readonly batchSize;
-    private readonly maxAttempts;
-    constructor(opts: EventQueueOptions);
-    /** The API is back: drop any pending backoff and send what is queued. */
-    private retryNow;
-    private retryIn;
-    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;
-}
-
-/** 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;
-    /** Last step reached in a multi-step flow (local only), so the messenger can offer to resume it. */
-    lastStepId?: 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;
-/**
- * Scheduling window: the guide's `schedule` (any kind) and, for surveys, `survey.startAt` / `endAt`.
- * Unparsable dates are ignored.
- */
-declare function isWithinSchedule(guide: Pick<PublishedGuide, "config">, now?: number): boolean;
-/**
- * Does showing this guide automatically count toward (and get limited by) the project's guide
- * throttling? Only exclusive guides (flows, modals, tooltips, announcements, surveys) interrupt;
- * banners, checklists and hotspot-only guides never count, nor does a guide set to ignore throttling.
- * Guides started by the visitor or the app (`startGuide`, buttons, Help) are never throttled.
- */
-declare function countsTowardThrottle(guide: PublishedGuide): boolean;
-/**
- * Pure throttling check. `launches` = ISO times of this visitor's earlier automatic launches of
- * counted guides (any order). Disabled or missing settings never throttle.
- */
-declare function isThrottleEligible(settings: GuideThrottlingSettings | null | undefined, launches: readonly string[], now?: number): boolean;
-/** Launch times worth keeping: those still inside the window or the minimum gap (at most 100). */
-declare function pruneLaunches(launches: readonly string[], settings: GuideThrottlingSettings | null | undefined, now?: number): string[];
-/**
- * A checklist's dismissal after merging server state. A local dismissal normally wins (it may not have
- * synced yet), but when the server reports a reset this device hasn't applied, the server's value wins:
- * null, or a dismissal made on another device after the reset. Compared as tokens, not times, so a
- * skewed device clock can't keep a reset dismissal.
- */
-declare function dismissedAfterMerge(local: {
-    dismissedAt?: string | null;
-    dismissResetAt?: string | null;
-} | undefined, server: {
-    dismissedAt?: string | null;
-    dismissResetAt?: string | null;
-}): string | null;
-
-/**
- * Agent Analytics in the browser: turns of conversations with the app's own AI agent, sent to
- * `POST /api/v1/sdk/agent-events`. Turns are filled in with the visitor's ids and session, passed through
- * the app's `agents.redact` callback, and kept in a persisted outbox until the server accepts them
- * (retried with backoff while it is unreachable; the server ignores turns it already has).
- */
-/** Last say over each turn before it leaves the browser: return a changed copy, or null to drop it. */
-type AgentTurnRedactor = (turn: AgentTurnInput) => AgentTurnInput | null | undefined;
-
-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, click text, session replays). Merged with the project setting. */
-    maskSelectors?: string[];
-    /**
-     * Page views, page leave, clicks and rage clicks are captured when the project enables them.
-     * `false` turns all of them off for this installation; an object turns individual ones off
-     * (`{ clicks: false }`). Options can only switch capture off, never on.
-     */
-    autocapture?: boolean | Partial<AutocaptureSettings>;
-    /** App version or commit SHA (≤100 chars), sent with every `exception` to pick the matching uploaded source maps. */
-    release?: string;
-    /**
-     * Version of the host application (e.g. an Electron app's `app.getVersion()`), used by **App version**
-     * targeting rules and as the `appVersion` flag attribute.
-     */
-    appVersion?: string;
-    /**
-     * Maps the browser URL to the page URL Guidely sees (targeting, URL patterns, page analytics). By
-     * default http(s) URLs are used as they are and `file:` / custom-protocol URLs (Electron, desktop
-     * shells) are made app-relative with `normalizeAppUrl`: `file:///…/index.html#/settings` → `file://app/settings`.
-     */
-    pageUrl?: (href: string) => string;
-    /** `false` stops uncaught errors / unhandled rejections from being reported (`captureException` still works). */
-    captureErrors?: boolean;
-    /**
-     * `false` never records sessions on this installation. An object can only make masking stricter:
-     * `maskAllText` masks every text node, `blockSelectors` replaces matching elements with a placeholder.
-     */
-    sessionReplay?: boolean | {
-        maskAllText?: boolean;
-        blockSelectors?: string[];
-        /** `false`: never record network requests / WebSockets in replays. */
-        recordNetwork?: false;
-        /** `false`: never record request/response headers, bodies or WebSocket frame data. */
-        recordNetworkPayloads?: false;
-        /** Last say over each recorded request (applied after redaction): return a modified copy, or null to drop it. */
-        maskNetworkRequest?: (request: NetworkRequest) => NetworkRequest | null;
-    };
-    onError?: (error: Error) => void;
-    /**
-     * 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 browser language; see also `setLocale()`.
-     */
-    locale?: string;
-    /** 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 and how-to capture URL parameter detection. */
-    disableAuthoring?: boolean;
-    /**
-     * Feature flags (on by default, same key and API URL). `false` turns them off (getters return
-     * fallbacks, nothing is fetched); an object passes options to the flags client, e.g.
-     * `{ payload }` to bootstrap from server rendering, `{ attributes }`, `{ remoteEval: true }`,
-     * `{ pollingMode: "stream" }`. Identity, page and device attributes are maintained for you.
-     */
-    flags?: false | Partial<FlagsClientOptions>;
-    /**
-     * Agent Analytics (`agentConversation()`): `redact` gets each turn before it leaves the browser and
-     * returns a changed copy (e.g. with personal details removed from `text`), or null to drop it.
-     */
-    agents?: {
-        redact?: AgentTurnRedactor;
-    };
-}
-interface ChecklistProgressState {
-    completedTaskIds: string[];
-    completedAt?: string | null;
-    dismissedAt?: string | null;
-    /** The server's last dismissal reset this device applied (see `dismissedAfterMerge`). */
-    dismissResetAt?: 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;
-    /** ISO times of automatic launches that count toward guide throttling (pruned to the window). */
-    throttle?: string[];
-    /** When the visitor last opened the resource center's "What's new" (unread badge). */
-    announcementsSeenAt?: string;
-}
-interface SessionState {
-    id: string;
-    startedAt: string;
-    shownGuides: string[];
-    events: string[];
-    /** Epoch ms of the last tracked activity; the session rotates after `sessionTimeoutMinutes` of inactivity. */
-    lastActivityAt?: number;
-    /** Page views sent in this session (the first one carries the referrer). */
-    pageViews?: number;
-    /** Exceptions reported in this session (capped at 100). */
-    exceptions?: number;
-    /** Replay decision for this session: sampled in / forced (`true`), sampled out or disabled by the server (`false`). */
-    replay?: boolean;
-}
-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;
-    /** How-to capture (recording steps for a how-to guide) started or ended in this tab. */
-    capture: (info: {
-        active: boolean;
-    }) => void;
-    /** Feature flags loaded (bootstrap, cache or network) — or failed to and serve fallbacks. */
-    "flags:ready": () => void;
-    /** New flag rules arrived (attribute changes notify `onFlagsChange` subscribers instead). */
-    "flags:change": () => void;
-}
-type GuidelyEventName = keyof GuidelyEvents;
-
-export { type AgentTurnRedactor as A, type ChecklistProgressState as C, EventQueue as E, type GuideLocalState as G, type PersistedState as P, type SessionState as S, type ConsentState as a, type EventQueueOptions as b, type GuidelyAccount as c, type GuidelyEnvironment as d, type GuidelyUser as e, areMutuallyExclusive as f, countsTowardThrottle as g, dismissedAfterMerge as h, isExclusiveGuide as i, isFrequencyEligible as j, isThrottleEligible as k, isWithinSchedule as l, type GuidelyOptions as m, type GuidelyEvents as n, type GuideStepInfo as o, pruneLaunches as p, type GuidelyEventName as q };