@sentientui/core 0.16.1 → 0.16.2

package/dist/index-C247KMBw.d.ts

@@ -0,0 +1,394 @@
+import { a as SlotDeclInput } from './session-meta-DU_3mY7U.js';
+import { SlotResult } from '@sentientui/policy';
+
+/** Manages anonymous session identity with cookie + localStorage layers. */
+type SessionConfig = {
+    cookieName?: string;
+    cookieTTLDays?: number;
+    /**
+     * Session ID generated during SSR (e.g. from `loadAdaptiveAssignments`).
+     * Used as the fallback when no existing cookie or localStorage entry is found,
+     * so the client adopts the same session the server used for variant assignment
+     * on first visit rather than generating a new, orphaned ID.
+     */
+    ssrSessionId?: string;
+};
+type SessionManager = {
+    getSessionId(): string | null;
+    /** True when neither cookie nor localStorage could be written — id is in-memory only. */
+    isEphemeral(): boolean;
+    destroy(): void;
+};
+
+/** Batched event queue with reliable transport (fetch + keepalive, localStorage retry). */
+type EventType = 'variant_assigned' | 'goal_achieved' | 'scroll_depth' | 'dwell' | 'cursor_signal' | 'component_visible' | 'component_exited' | 'micro_signal';
+type SentientEvent = {
+    id: string;
+    sessionId: string;
+    projectId: string;
+    componentId: string;
+    variantId?: string;
+    eventType: EventType;
+    goalType?: string;
+    payload: Record<string, unknown>;
+    timestamp: number;
+    timeInSession: number;
+};
+type QueueConfig = {
+    ingestUrl: string;
+    apiKey: string;
+    flushIntervalMs?: number;
+    maxBatchSize?: number;
+    maxRetrySize?: number;
+};
+type EventQueue = {
+    push(event: SentientEvent): void;
+    flush(): void;
+    destroy(): void;
+};
+
+/** Synchronous variant assignment cache (memory + localStorage). */
+type Assignment = {
+    variantId: string;
+    assignedAt: number;
+    segment: string;
+    confidence: number;
+    content?: string;
+};
+type AssignmentCache = {
+    get(componentId: string, segment: string): Assignment | null;
+    set(componentId: string, segment: string, assignment: Assignment): void;
+    invalidate(componentId: string): void;
+    clear(): void;
+};
+
+/** In-memory context graph with persistence and backend sync. */
+type PageNode = {
+    id: string;
+    componentId: string;
+    semanticType: string;
+    answers: string[];
+    prominenceScore: number;
+    depth: number;
+};
+type GraphSnapshot = {
+    pageNodes: PageNode[];
+    capturedAt: number;
+};
+type GraphConfig = {
+    syncUrl?: string;
+    apiKey?: string;
+    projectId?: string;
+    sessionId?: string;
+};
+type StructuralEdge = {
+    fromComponentId: string;
+    toComponentId: string;
+    weight: number;
+};
+type GraphClient = {
+    addPageNode(node: PageNode): void;
+    /** Record a DOM-derived parent/child or sibling relationship between two components. */
+    addStructuralEdge(edge: StructuralEdge): void;
+    /** One-shot batch sync of all current page nodes to the backend. */
+    syncOnce(): void;
+    snapshot(): GraphSnapshot;
+    serialize(): string;
+    restore(data: string): void;
+    destroy(): void;
+};
+
+/**
+ * Decision snapshot: the SPA / return-visit pre-paint source. Written after
+ * every successful decide; read by the inline pre-paint script (before any
+ * framework code runs) and by init() to seed slot/persona state.
+ */
+
+declare const SNAPSHOT_STORAGE_KEY_PREFIX = "_snt_snap:";
+/** Versioned compound locator: resolve id → dataAttr → selector, then verify
+ *  against fingerprint. Lets a slot survive DOM/markup drift. */
+type CompoundLocator = {
+    v?: number;
+    id?: string;
+    dataAttr?: {
+        name: string;
+        value: string;
+    };
+    selector?: string;
+    urlMatch?: string;
+    fingerprint?: {
+        tag?: string;
+        text?: string;
+    };
+    semanticId?: string;
+};
+/** Bounded, declarative operations a registry arm may apply to its element.
+ *  The style set is a fixed whitelist (validated server-side); no arbitrary CSS,
+ *  HTML, or JS ever. `text` is applied via textContent; https-only URLs.
+ *  moveBefore/moveAfter (exactly one) reposition the element relative to a
+ *  uniquely-resolving sibling anchor — post-decide only, never pre-paint. */
+type SlotOps = {
+    text?: string;
+    style?: Record<string, string>;
+    hidden?: boolean;
+    href?: string;
+    imageSrc?: string;
+    imageAlt?: string;
+    moveBefore?: CompoundLocator;
+    moveAfter?: CompoundLocator;
+};
+/** Registry-mode apply info per slot: where to apply and what to set. Stored so
+ *  a returning visitor's pre-paint can reapply it. `target` is the Phase-2 bare
+ *  selector; `locator` (Phase 3) is the compound locator, preferred when present. */
+type SlotConfigEntry = {
+    kind: 'tokens' | 'arms';
+    target?: string;
+    locator?: CompoundLocator;
+    content?: string;
+    ops?: SlotOps;
+};
+type DecisionSnapshot = {
+    v: 1;
+    persona: string;
+    band: 'low' | 'medium' | 'high';
+    slots: Record<string, SlotResult>;
+    layoutOrder: string[] | null;
+    savedAt: number;
+    slotConfig?: Record<string, SlotConfigEntry>;
+};
+/** Returns null on missing, corrupt, or wrong-version data — never throws. */
+declare function readSnapshot(apiKey: string): DecisionSnapshot | null;
+/** Best-effort persist — storage failures are swallowed. */
+declare function writeSnapshot(apiKey: string, snap: DecisionSnapshot): void;
+/**
+ * Inline pre-paint script (Rung 1a): reads the snapshot and sets
+ * `data-sentient-persona` / `data-sentient-confidence` on <html> before
+ * first paint. Single-writer: it never overwrites attributes already set.
+ *
+ * Safety properties (pinned by tests):
+ * - apiKey goes through JSON.stringify, then '<' is escaped to <, so a
+ *   hostile key can neither break the JS string nor terminate the <script>.
+ * - Built by string concatenation and contains no backticks, so the output
+ *   survives being embedded in template-literal-based renderers.
+ */
+declare function renderPrePaintScript(apiKey: string): string;
+
+declare const PROD_KEYLESS_ERROR = "[sentient] No API key configured \u2014 nothing is being learned. Set NEXT_PUBLIC_SENTIENT_API_KEY or pass localMode: true for local development.";
+declare const LOCAL_MODE_BANNER = "[sentient] Local mode \u2014 decisions are simulated on-device and nothing is sent over the network. Add an API key to learn from real traffic.";
+
+type MicroSignalEmitter = (signalType: 'rage_click' | 'text_copy' | 'scroll_hesitation' | 'tab_loss', extra?: Record<string, unknown>) => void;
+type MicroSignalType = Parameters<MicroSignalEmitter>[0];
+/**
+ * Attaches passive behavioral detectors to `node`. Calls `emit` when a signal
+ * fires. Each signal type fires at most once per call to this function.
+ * Returns a cleanup function that removes all listeners.
+ */
+declare function attachMicroSignalDetectors(emit: MicroSignalEmitter, node: Element, variantAssignedAt?: number): () => void;
+
+type SentientConfig = {
+    apiKey: string;
+    context: 'landing' | 'ecommerce' | 'saas' | 'marketplace';
+    /** @internal — not exposed to users; defaults to the hosted SentientUI API. */
+    ingestUrl?: string;
+    debug?: boolean;
+    /**
+     * Pre-seeded assignments from `preloadAssignments()` (SSR).
+     * Seeds the local cache so `assign()` returns without a network call for
+     * listed code variants, guaranteeing server and client render the same
+     * variant on first paint. Managed-text components (assign with no
+     * variantIds) still fetch once when the seed carries no content.
+     */
+    initialAssignments?: Record<string, string>;
+    /**
+     * Segment used for SSR preload (`device:source`). When set with `initialAssignments`,
+     * seeds the assignment cache under this key so hydration matches the server bandit row.
+     */
+    sessionSegment?: string;
+    /**
+     * Consent gate. When `false`, returns a no-op client and performs no tracking.
+     * Defaults to `true`. Re-call `init()` (via `AdaptiveProvider` consent prop) when
+     * the user grants or revokes consent mid-session.
+     */
+    consent?: boolean;
+    /**
+     * Behavior before consent is granted. `'statistical_winner'` fetches the
+     * best-performing variant via `GET /v1/winner` — no session or tracking data
+     * is stored. `'control'` (default) shows `variantIds[0]` with no API call.
+     * Applies when tracking is gated off — either `consent: false` or an active
+     * Do Not Track signal.
+     */
+    preConsentBehavior?: 'statistical_winner' | 'control';
+    /**
+     * Whether to honor the browser's Do Not Track (DNT) signal. Defaults to `true`.
+     * When `true` and the visitor has DNT enabled, the SDK sets no cookies and
+     * sends no tracking data — behaving exactly as `consent: false` (still serving
+     * the read-only `preConsentBehavior` winner if configured), and `grantConsent()`
+     * will not upgrade it. Set `false` to make your own consent gate authoritative.
+     */
+    respectDoNotTrack?: boolean;
+    userId?: string;
+    /**
+     * Session ID generated server-side (from `loadAdaptiveAssignments` / `loadAdaptiveDecision`).
+     * When provided, the client adopts this ID on first visit instead of generating a new one,
+     * ensuring events and goals are attributed to the same session the server used for assignment.
+     */
+    ssrSessionId?: string;
+    /**
+     * ISO 3166-1 alpha-2 country code for the visitor. When provided (e.g. from
+     * the `CF-IPCountry` header in a Next.js server component), it is included in
+     * the session upsert so country-based segmentation works without client-side
+     * geo lookup.
+     */
+    country?: string;
+    /**
+     * Pre-seeded slot results from `preloadDecisions()` / `loadAdaptiveDecision()`
+     * (SSR). Seeds the local slot state so `getSlotResult()` agrees with the
+     * server-rendered markup on first paint.
+     */
+    initialSlots?: Record<string, SlotResult>;
+    /**
+     * Persona decided during SSR. Takes priority over the html-attribute
+     * adoption and the local snapshot.
+     */
+    initialPersona?: {
+        persona: string;
+        confidence: number;
+    };
+    /**
+     * Keyless local mode. 'auto' (default) simulates decisions on-device when no
+     * valid API key is configured — but only in development builds (the
+     * `development` export condition); production bundles physically exclude the
+     * engine. `true` forces the local engine regardless of key (escape hatch);
+     * `false` restores the silent keyless no-op.
+     */
+    localMode?: 'auto' | boolean;
+};
+type AssignResult = {
+    variantId: string;
+    assignmentTtlMs: number;
+    content?: string;
+};
+
+/** An editor-defined goal delivered with a registry-mode decision, for the
+ *  snippet to install delegated listeners from. */
+type GoalDefinition = {
+    goalId: string;
+    event: 'click' | 'form_submit' | 'url_reached';
+    locator?: CompoundLocator;
+    urlPattern?: string;
+    slotId?: string;
+};
+type DecideOutcome = {
+    layoutOrder: string[] | null;
+    assignments: Record<string, string>;
+    slots: Record<string, SlotResult>;
+    persona: string;
+    confidence: number;
+    slotConfig?: Record<string, SlotConfigEntry>;
+    goals?: GoalDefinition[];
+};
+type DecideInput = {
+    sections?: string[];
+    components?: Array<{
+        id: string;
+        variantIds?: string[];
+    }>;
+    slots?: SlotDeclInput[];
+    slotsFrom?: 'request' | 'registry';
+    /**
+     * Caller's build version (e.g. the snippet's `__SNIPPET_VERSION__`), sent
+     * as `v` on the wire. Additive/best-effort: the server persists it for
+     * version-skew reporting (see apps/api decide route) and ignores it
+     * entirely on older deployments. Omit if the caller has no version to report.
+     */
+    v?: string;
+};
+type WeightEntry = {
+    variantId: string;
+    pulls: number;
+    avgReward: number | null;
+};
+type ComponentWeightEntry = {
+    componentId: string;
+    updatedAt: number;
+    variants: WeightEntry[];
+};
+type ComponentGoalOptions = {
+    /** Reward credited to the served variant (0–1). Defaults to 1. */
+    reward?: number;
+    /** Extra fields merged into the event payload. */
+    metadata?: Record<string, unknown>;
+};
+type SentientClient = {
+    track(event: Omit<SentientEvent, 'id' | 'sessionId' | 'timestamp' | 'timeInSession'>): void;
+    goal(name: string, metadata?: Record<string, unknown>, weight?: number, stepIndex?: number): void;
+    /**
+     * Records a conversion attributed to the variant currently served for
+     * `componentId`, so it feeds the per-variant CVR funnel. Resolves the served
+     * variant from the local assignment cache — no need to pass variantId or
+     * projectId. No-ops if the component has not been assigned yet (render its
+     * `<Adaptive>`/call `assign()` first). Prefer this over bare `goal()` for
+     * variant experiments; `goal()` is session-level only (no component attribution).
+     */
+    componentGoal(componentId: string, goalType: string, opts?: ComponentGoalOptions): void;
+    identify(userId: string): void;
+    getAssignment(componentId: string, segment: string): Assignment | null;
+    /** Server-side variant assignment. Caches the result locally per (component, segment). */
+    assign(componentId: string, variantIds?: string[], agentData?: unknown, agentDataByVariant?: Record<string, unknown>): Promise<AssignResult | null>;
+    /**
+     * Single-roundtrip decision for layout sections, component variants, and
+     * adaptive slots. Awaits the session upsert (like `assign`) so the server
+     * never decides for a session row that doesn't exist yet. A response
+     * without a `slots` field means the server predates slots — every declared
+     * slot resolves to its baseline and no retry is made.
+     */
+    decide(input: DecideInput): Promise<DecideOutcome | null>;
+    /** Slot result served this session (decide result, SSR seed, snapshot, or failure baseline). Null when unknown. */
+    getSlotResult(slotId: string): SlotResult | null;
+    /** Current persona estimate. Band is always `confidenceBand(confidence)`. Null when nothing is known yet. */
+    getPersona(): {
+        persona: string;
+        confidence: number;
+        band: 'low' | 'medium' | 'high';
+    } | null;
+    /** Fetches current bandit weights for all components in this project. Used by the provider to keep live-weight polling fresh. */
+    fetchWeights(): Promise<ComponentWeightEntry[]>;
+    getGraph(): GraphSnapshot;
+    /**
+     * Routine teardown: stops timers/listeners and flushes pending events, but
+     * KEEPS the visitor identity, decision snapshot, and retry bucket. Use for
+     * component unmount / re-init (framework providers call this on cleanup).
+     */
+    dispose(): void;
+    /**
+     * Consent-revocation / forget-me teardown: everything `dispose()` does,
+     * plus deletion of the visitor identity (`_snt_uid`), the decision
+     * snapshot, and the persisted retry bucket. The next visit starts as a
+     * brand-new visitor.
+     */
+    destroy(): void;
+    /** True when this client is the keyless local-mode client (dev only). */
+    readonly isLocal?: boolean;
+};
+
+/**
+ * Detects whether the visitor has signalled a tracking opt-out. Honors Global
+ * Privacy Control (`navigator.globalPrivacyControl`) — the legally-enforceable
+ * CCPA/CPRA signal — as well as Do Not Track (`navigator.doNotTrack`, the legacy
+ * `window.doNotTrack` on older Firefox, and `navigator.msDoNotTrack` on old
+ * IE/Edge). GPC is a boolean; DNT is opt-out only when explicitly `'1'`/`'yes'`.
+ */
+declare function isDoNotTrackEnabled(): boolean;
+/**
+ * Upgrades a pre-consent client (created with `consent: false, preConsentBehavior: 'statistical_winner'`)
+ * to a fully-tracking client. Call this from your consent management platform callback.
+ * For React apps, prefer updating the `consent` prop on `<AdaptiveProvider>`.
+ * Pass `apiKey` to target a specific project; omit to upgrade the most-recently-initialized client.
+ */
+declare function grantConsent(apiKey?: string): void;
+/**
+ * Initializes the Sentient client. Returns a no-op client during SSR.
+ */
+declare function init(config: SentientConfig): SentientClient;
+
+export { type AssignResult as A, type ComponentGoalOptions as C, type DecideInput as D, type EventQueue as E, type GoalDefinition as G, LOCAL_MODE_BANNER as L, type MicroSignalEmitter as M, PROD_KEYLESS_ERROR as P, type QueueConfig as Q, SNAPSHOT_STORAGE_KEY_PREFIX as S, type WeightEntry as W, type Assignment as a, type AssignmentCache as b, type ComponentWeightEntry as c, type CompoundLocator as d, type DecideOutcome as e, type DecisionSnapshot as f, type EventType as g, type GraphClient as h, type GraphConfig as i, type GraphSnapshot as j, type MicroSignalType as k, type PageNode as l, type SentientClient as m, type SentientConfig as n, type SentientEvent as o, type SessionConfig as p, type SessionManager as q, type SlotConfigEntry as r, type SlotOps as s, attachMicroSignalDetectors as t, grantConsent as u, init as v, isDoNotTrackEnabled as w, readSnapshot as x, renderPrePaintScript as y, writeSnapshot as z };