@burdenoff/website-sdk 2026.829.8 → 2026.921.1

package/dist/use-explore-chat-CvW-kyIm.d.mts

@@ -0,0 +1,145 @@
+import { a as ExploreLimits, b as ExploreCatalog, c as ExploreMessage } from './explore-types-CLw19R76.mjs';
+
+/** What travels on the wire — mirrors `ExploreAttachmentInput`. */
+interface ExploreAttachmentPayload {
+    name: string;
+    mimeType: string;
+    size: number;
+    textContent: string | null;
+}
+
+/**
+ * Where the conversation is right now.
+ *
+ * - `loading`   — catalog request in flight (the fallback catalog is already
+ *                 rendered, so this is a refinement, not a blank screen).
+ * - `ready`     — idle; the composer accepts input.
+ * - `sending`   — `sendExploreMessage` in flight.
+ * - `streaming` — polling the assistant turn; `activity` is live.
+ * - `error`     — the last turn failed; `retry()` is meaningful and the
+ *                 composer stays usable.
+ * - `limited`   — rate limited; the composer is disabled.
+ * - `disabled`  — `exploreCatalog.enabled === false`.
+ */
+type ExploreChatPhase = "loading" | "ready" | "sending" | "streaming" | "error" | "limited" | "disabled";
+/** Coarse bucket the UI switches its banner copy and affordances on. */
+type ExploreChatErrorKind = "rate-limit" | "captcha" | "timeout" | "scope" | "network" | "disabled" | "validation" | "unknown";
+interface ExploreChatError {
+    /** UI bucket. */
+    kind: ExploreChatErrorKind;
+    /** Raw `extensions.code` (or a client-side code such as `TIMEOUT`). */
+    code: string;
+    /** Human-readable, safe to render. */
+    message: string;
+    /** Whether re-sending the same message could plausibly succeed. */
+    retryable: boolean;
+}
+interface UseExploreChatOptions {
+    /** Slug of the product site this page is on — a soft hint to the harness. */
+    productSlug?: string;
+    /** Full URL of the page, forwarded as `pageUrl`. */
+    pageUrl?: string;
+    /** BCP-47 locale, forwarded as `locale`. */
+    locale?: string;
+    /** Poll cadence in ms. Default 1500 (CONTRACT.md §1). */
+    pollIntervalMs?: number;
+    /** Give up on a turn after this long. Default 90000 (the edge poll timeout). */
+    pollTimeoutMs?: number;
+    /**
+     * Prompts to offer when `exploreCatalog` supplies none. Resolution order is
+     * catalog → this option → {@link DEFAULT_EXPLORE_EXAMPLE_PROMPTS}, so a site
+     * can ship product-specific prompts without waiting on the backend and still
+     * be overridden centrally once the catalog carries them.
+     */
+    examplePrompts?: string[];
+    /**
+     * Welcome copy for the fallback catalog, used only when `exploreCatalog` cannot be reached.
+     *
+     * The hook's own built-in fallback is English. `ExplorePage` passes the strings for the
+     * visitor's locale, so a catalog outage degrades to a translated page rather than an
+     * English one — the whole point of shipping six locales is that the failure paths speak
+     * them too.
+     */
+    fallbackWelcome?: {
+        title: string;
+        body: string;
+    };
+    /** localStorage key for the ACTIVE conversation. Default `boff.explore.v1`. */
+    storageKey?: string;
+    /** Persist the conversation across reloads within the tab. Default true. */
+    persist?: boolean;
+    /** Called with the message text each time a send is accepted locally. */
+    onSend?: (message: string) => void;
+}
+interface UseExploreChatResult {
+    phase: ExploreChatPhase;
+    /** Never null — starts as the static fallback, upgraded by the server. */
+    catalog: ExploreCatalog;
+    messages: ExploreMessage[];
+    /** Latest progress line of the in-flight turn, or null when idle. */
+    activity: string | null;
+    /** Messages left today for this visitor, when the server reports it. */
+    remainingToday: number | null;
+    error: ExploreChatError | null;
+    /** Product the visitor pinned the conversation to, or null for "all". */
+    focusProduct: string | null;
+    setFocusProduct: (slug: string | null) => void;
+    send: (message: string, attachments?: readonly ExploreAttachmentPayload[]) => Promise<void>;
+    /** Stop polling and keep whatever text has streamed so far. */
+    stop: () => void;
+    /** Re-send the last message after a failed turn. */
+    retry: () => void;
+    /** Clear the conversation and the persisted session. */
+    reset: () => void;
+    /** Past conversations held in THIS browser, newest first. */
+    history: ArchivedExploreConversation[];
+    /** Reopen a past conversation and continue it. */
+    openConversation: (token: string) => void;
+    /** Forget one past conversation (local only). */
+    deleteConversation: (token: string) => void;
+    /** Forget every past conversation held in this browser. */
+    clearHistory: () => void;
+    /**
+     * Record that the visitor followed a link this answer offered. Fire-and-forget — never
+     * awaited, never throws, and must never delay the navigation it is reporting on.
+     */
+    recordClick: (messageId: string, kind: "CTA" | "REFERENCE", url: string) => void;
+    /**
+     * Mint a read-only link to this conversation, or null when there is nothing to share yet.
+     * The secret returned is not the conversation token and cannot continue the thread.
+     */
+    createShareLink: () => Promise<string | null>;
+    /**
+     * True when the transcript on screen came from a shared link rather than this visitor's own
+     * conversation. A shared view is read-only: the share secret cannot continue the thread.
+     */
+    isSharedView: boolean;
+    canSend: boolean;
+}
+/** Fallback limits, mirroring the server defaults in CONTRACT.md §3. */
+declare const FALLBACK_EXPLORE_LIMITS: ExploreLimits;
+/**
+ * Prompts shown when neither the catalog nor the consumer supplies any.
+ * Deliberately product-agnostic — this SDK renders on 38 different sites.
+ */
+declare const DEFAULT_EXPLORE_EXAMPLE_PROMPTS: string[];
+/**
+ * Map a `extensions.code` (or a client-side transport code) onto the bucket the
+ * UI renders. Unknown codes are treated as retryable — a transient backend
+ * condition we have not enumerated is far more likely than a permanent one.
+ */
+declare function classifyExploreError(code: string | null | undefined, serverMessage?: string | null): ExploreChatError;
+/** One past conversation, as shown in the history list and restored on click. */
+interface ArchivedExploreConversation {
+    token: string;
+    /** First thing the visitor asked — the human-readable label for the thread. */
+    title: string;
+    /** ISO timestamp of the last message in the thread. */
+    updatedAt: string;
+    messageCount: number;
+    focusProduct: string | null;
+    messages: ExploreMessage[];
+}
+declare function useExploreChat(options?: UseExploreChatOptions): UseExploreChatResult;
+
+export { DEFAULT_EXPLORE_EXAMPLE_PROMPTS as D, type ExploreChatError as E, FALLBACK_EXPLORE_LIMITS as F, type UseExploreChatOptions as U, type ExploreChatErrorKind as a, type ExploreChatPhase as b, type UseExploreChatResult as c, classifyExploreError as d, useExploreChat as u };

package/dist/use-explore-chat-DdGBimiz.d.ts

@@ -0,0 +1,145 @@
+import { a as ExploreLimits, b as ExploreCatalog, c as ExploreMessage } from './explore-types-CLw19R76.js';
+
+/** What travels on the wire — mirrors `ExploreAttachmentInput`. */
+interface ExploreAttachmentPayload {
+    name: string;
+    mimeType: string;
+    size: number;
+    textContent: string | null;
+}
+
+/**
+ * Where the conversation is right now.
+ *
+ * - `loading`   — catalog request in flight (the fallback catalog is already
+ *                 rendered, so this is a refinement, not a blank screen).
+ * - `ready`     — idle; the composer accepts input.
+ * - `sending`   — `sendExploreMessage` in flight.
+ * - `streaming` — polling the assistant turn; `activity` is live.
+ * - `error`     — the last turn failed; `retry()` is meaningful and the
+ *                 composer stays usable.
+ * - `limited`   — rate limited; the composer is disabled.
+ * - `disabled`  — `exploreCatalog.enabled === false`.
+ */
+type ExploreChatPhase = "loading" | "ready" | "sending" | "streaming" | "error" | "limited" | "disabled";
+/** Coarse bucket the UI switches its banner copy and affordances on. */
+type ExploreChatErrorKind = "rate-limit" | "captcha" | "timeout" | "scope" | "network" | "disabled" | "validation" | "unknown";
+interface ExploreChatError {
+    /** UI bucket. */
+    kind: ExploreChatErrorKind;
+    /** Raw `extensions.code` (or a client-side code such as `TIMEOUT`). */
+    code: string;
+    /** Human-readable, safe to render. */
+    message: string;
+    /** Whether re-sending the same message could plausibly succeed. */
+    retryable: boolean;
+}
+interface UseExploreChatOptions {
+    /** Slug of the product site this page is on — a soft hint to the harness. */
+    productSlug?: string;
+    /** Full URL of the page, forwarded as `pageUrl`. */
+    pageUrl?: string;
+    /** BCP-47 locale, forwarded as `locale`. */
+    locale?: string;
+    /** Poll cadence in ms. Default 1500 (CONTRACT.md §1). */
+    pollIntervalMs?: number;
+    /** Give up on a turn after this long. Default 90000 (the edge poll timeout). */
+    pollTimeoutMs?: number;
+    /**
+     * Prompts to offer when `exploreCatalog` supplies none. Resolution order is
+     * catalog → this option → {@link DEFAULT_EXPLORE_EXAMPLE_PROMPTS}, so a site
+     * can ship product-specific prompts without waiting on the backend and still
+     * be overridden centrally once the catalog carries them.
+     */
+    examplePrompts?: string[];
+    /**
+     * Welcome copy for the fallback catalog, used only when `exploreCatalog` cannot be reached.
+     *
+     * The hook's own built-in fallback is English. `ExplorePage` passes the strings for the
+     * visitor's locale, so a catalog outage degrades to a translated page rather than an
+     * English one — the whole point of shipping six locales is that the failure paths speak
+     * them too.
+     */
+    fallbackWelcome?: {
+        title: string;
+        body: string;
+    };
+    /** localStorage key for the ACTIVE conversation. Default `boff.explore.v1`. */
+    storageKey?: string;
+    /** Persist the conversation across reloads within the tab. Default true. */
+    persist?: boolean;
+    /** Called with the message text each time a send is accepted locally. */
+    onSend?: (message: string) => void;
+}
+interface UseExploreChatResult {
+    phase: ExploreChatPhase;
+    /** Never null — starts as the static fallback, upgraded by the server. */
+    catalog: ExploreCatalog;
+    messages: ExploreMessage[];
+    /** Latest progress line of the in-flight turn, or null when idle. */
+    activity: string | null;
+    /** Messages left today for this visitor, when the server reports it. */
+    remainingToday: number | null;
+    error: ExploreChatError | null;
+    /** Product the visitor pinned the conversation to, or null for "all". */
+    focusProduct: string | null;
+    setFocusProduct: (slug: string | null) => void;
+    send: (message: string, attachments?: readonly ExploreAttachmentPayload[]) => Promise<void>;
+    /** Stop polling and keep whatever text has streamed so far. */
+    stop: () => void;
+    /** Re-send the last message after a failed turn. */
+    retry: () => void;
+    /** Clear the conversation and the persisted session. */
+    reset: () => void;
+    /** Past conversations held in THIS browser, newest first. */
+    history: ArchivedExploreConversation[];
+    /** Reopen a past conversation and continue it. */
+    openConversation: (token: string) => void;
+    /** Forget one past conversation (local only). */
+    deleteConversation: (token: string) => void;
+    /** Forget every past conversation held in this browser. */
+    clearHistory: () => void;
+    /**
+     * Record that the visitor followed a link this answer offered. Fire-and-forget — never
+     * awaited, never throws, and must never delay the navigation it is reporting on.
+     */
+    recordClick: (messageId: string, kind: "CTA" | "REFERENCE", url: string) => void;
+    /**
+     * Mint a read-only link to this conversation, or null when there is nothing to share yet.
+     * The secret returned is not the conversation token and cannot continue the thread.
+     */
+    createShareLink: () => Promise<string | null>;
+    /**
+     * True when the transcript on screen came from a shared link rather than this visitor's own
+     * conversation. A shared view is read-only: the share secret cannot continue the thread.
+     */
+    isSharedView: boolean;
+    canSend: boolean;
+}
+/** Fallback limits, mirroring the server defaults in CONTRACT.md §3. */
+declare const FALLBACK_EXPLORE_LIMITS: ExploreLimits;
+/**
+ * Prompts shown when neither the catalog nor the consumer supplies any.
+ * Deliberately product-agnostic — this SDK renders on 38 different sites.
+ */
+declare const DEFAULT_EXPLORE_EXAMPLE_PROMPTS: string[];
+/**
+ * Map a `extensions.code` (or a client-side transport code) onto the bucket the
+ * UI renders. Unknown codes are treated as retryable — a transient backend
+ * condition we have not enumerated is far more likely than a permanent one.
+ */
+declare function classifyExploreError(code: string | null | undefined, serverMessage?: string | null): ExploreChatError;
+/** One past conversation, as shown in the history list and restored on click. */
+interface ArchivedExploreConversation {
+    token: string;
+    /** First thing the visitor asked — the human-readable label for the thread. */
+    title: string;
+    /** ISO timestamp of the last message in the thread. */
+    updatedAt: string;
+    messageCount: number;
+    focusProduct: string | null;
+    messages: ExploreMessage[];
+}
+declare function useExploreChat(options?: UseExploreChatOptions): UseExploreChatResult;
+
+export { DEFAULT_EXPLORE_EXAMPLE_PROMPTS as D, type ExploreChatError as E, FALLBACK_EXPLORE_LIMITS as F, type UseExploreChatOptions as U, type ExploreChatErrorKind as a, type ExploreChatPhase as b, type UseExploreChatResult as c, classifyExploreError as d, useExploreChat as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@burdenoff/website-sdk",
-  "version": "2026.829.8",
+  "version": "2026.921.1",
   "description": "Shared SDK for Burdenoff product websites - reusable React components, utilities, and configurations",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",