@burdenoff/website-sdk 2026.922.4 → 2026.923.1

package/dist/{use-explore-chat-Dgm-jf96.d.mts → use-progressive-reveal-Cmy8bA7L.d.mts}

@@ -1,4 +1,4 @@
-import { b as ExploreLimits, c as ExploreCatalog, d as ExploreMessage, e as ExploreFeedbackRating, f as ExploreFeedbackReason } from './explore-types-DvQPiL1t.mjs';
+import { b as ExploreLimits, c as ExploreCatalog, d as ExploreMessage, e as ExploreFeedbackRating, f as ExploreFeedbackReason } from './explore-types-B5sdOC5M.mjs';
 
 /** What travels on the wire — mirrors `ExploreAttachmentInput`. */
 interface ExploreAttachmentPayload {
@@ -34,6 +34,34 @@ interface ExploreChatError {
     /** Whether re-sending the same message could plausibly succeed. */
     retryable: boolean;
 }
+/**
+ * What came of handing the conversation to a person.
+ *
+ * `sent` and `already-handed-over` are BOTH successes. The second is the double-clicked
+ * button, the retried request and the reloaded page: the server keeps one handover per
+ * conversation, so a repeat submit returns the first one rather than filing a second ticket.
+ * A visitor who is worried enough to ask for a human must never be told "you already did
+ * that" — the conversation is with a person either way, and the UI says so either way.
+ */
+type ExploreEscalateOutcome = "sent" | "already-handed-over"
+/** The SERVER rejected the address (`INVALID_EMAIL`), after the client let it through. */
+ | "invalid-email" | "rate-limited" | "captcha"
+/** No conversation token — nothing to hand over. The form should not have been offered. */
+ | "no-conversation" | "failed";
+interface ExploreEscalateResult {
+    outcome: ExploreEscalateOutcome;
+    /**
+     * The address the SERVER says the reply is going to, on `sent` and `already-handed-over`;
+     * null otherwise.
+     *
+     * On `already-handed-over` this is the address the FIRST handover used, which may not be
+     * the one just typed — and it is the one the reply actually reaches, so it is the one to
+     * show back.
+     */
+    email: string | null;
+    /** When the handover was filed, as the server holds it. Null unless it exists. */
+    createdAt: string | null;
+}
 interface UseExploreChatOptions {
     /** Slug of the product site this page is on — a soft hint to the harness. */
     productSlug?: string;
@@ -116,6 +144,30 @@ interface UseExploreChatResult {
         reason?: ExploreFeedbackReason | null;
         comment?: string | null;
     }) => Promise<boolean>;
+    /**
+     * Hand this conversation to a person, so they pick it up with the transcript attached.
+     *
+     * Awaited, like {@link submitFeedback} and for the same reason — the visitor is watching
+     * the control they pressed — but this one has more to say than true/false: "we could not
+     * deliver to that address", "you are sending these too fast" and "it is already with a
+     * human" are three different things to a worried visitor, and one boolean flattens them
+     * into a shrug. It never throws; every outcome comes back in
+     * {@link ExploreEscalateResult}.
+     *
+     * `email` is personal data. It goes into the mutation variables and nowhere else — not
+     * into `messages` (which is what this hook persists), not into `onSend`, not into any
+     * analytics call.
+     */
+    escalate: (email: string, note?: string) => Promise<ExploreEscalateResult>;
+    /**
+     * Whether there is a conversation a person could actually be handed.
+     *
+     * False on a fresh page and false in a read-only shared view (a `?c=` secret is not a
+     * conversation token), which are exactly the cases where {@link escalate} could only
+     * answer `no-conversation`. Offer the form on this, rather than offering one that cannot
+     * work.
+     */
+    canEscalate: boolean;
     /**
      * 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.
@@ -141,11 +193,6 @@ declare const FALLBACK_EXPLORE_LIMITS: ExploreLimits;
  * brochure without a single copy change being reviewed.
  */
 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 {
@@ -160,4 +207,38 @@ interface ArchivedExploreConversation {
 }
 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 };
+/**
+ * Stop whatever this SDK is reading aloud, from outside a component.
+ *
+ * A no-op when nothing of ours is speaking — deliberately, rather than calling
+ * `speechSynthesis.cancel()` unconditionally, which would also silence a host page that is
+ * using the same queue for its own reasons.
+ */
+declare function stopSpeaking(): void;
+interface UseSpeechOutputOptions {
+    /** BCP-47 tag to read in. Omit to let the platform pick its default voice. */
+    lang?: string;
+}
+interface UseSpeechOutputResult {
+    /**
+     * False when this browser has no synthesiser, or has one that was asked to speak and did
+     * not. Render no control at all when it is false — see the note at the top of the file.
+     */
+    supported: boolean;
+    speaking: boolean;
+    speak: (text: string) => void;
+    stop: () => void;
+    toggle: (text: string) => void;
+}
+declare function useSpeechOutput({ lang, }?: UseSpeechOutputOptions): UseSpeechOutputResult;
+
+/**
+ * The part of `text` that is currently on screen.
+ *
+ * @param text    everything that has arrived so far — `content` once the turn completes,
+ *                `partialContent` while it runs.
+ * @param settled true once the turn is COMPLETED or FAILED and `text` will not grow again.
+ */
+declare function useProgressiveReveal(text: string, settled: boolean): string;
+
+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 ExploreEscalateOutcome as c, type ExploreEscalateResult as d, type UseExploreChatResult as e, type UseSpeechOutputOptions as f, type UseSpeechOutputResult as g, classifyExploreError as h, useProgressiveReveal as i, useSpeechOutput as j, stopSpeaking as s, useExploreChat as u };

package/dist/{use-explore-chat-CNEdKBc1.d.ts → use-progressive-reveal-DHPGGxZu.d.ts}

@@ -1,4 +1,4 @@
-import { b as ExploreLimits, c as ExploreCatalog, d as ExploreMessage, e as ExploreFeedbackRating, f as ExploreFeedbackReason } from './explore-types-DvQPiL1t.js';
+import { b as ExploreLimits, c as ExploreCatalog, d as ExploreMessage, e as ExploreFeedbackRating, f as ExploreFeedbackReason } from './explore-types-B5sdOC5M.js';
 
 /** What travels on the wire — mirrors `ExploreAttachmentInput`. */
 interface ExploreAttachmentPayload {
@@ -34,6 +34,34 @@ interface ExploreChatError {
     /** Whether re-sending the same message could plausibly succeed. */
     retryable: boolean;
 }
+/**
+ * What came of handing the conversation to a person.
+ *
+ * `sent` and `already-handed-over` are BOTH successes. The second is the double-clicked
+ * button, the retried request and the reloaded page: the server keeps one handover per
+ * conversation, so a repeat submit returns the first one rather than filing a second ticket.
+ * A visitor who is worried enough to ask for a human must never be told "you already did
+ * that" — the conversation is with a person either way, and the UI says so either way.
+ */
+type ExploreEscalateOutcome = "sent" | "already-handed-over"
+/** The SERVER rejected the address (`INVALID_EMAIL`), after the client let it through. */
+ | "invalid-email" | "rate-limited" | "captcha"
+/** No conversation token — nothing to hand over. The form should not have been offered. */
+ | "no-conversation" | "failed";
+interface ExploreEscalateResult {
+    outcome: ExploreEscalateOutcome;
+    /**
+     * The address the SERVER says the reply is going to, on `sent` and `already-handed-over`;
+     * null otherwise.
+     *
+     * On `already-handed-over` this is the address the FIRST handover used, which may not be
+     * the one just typed — and it is the one the reply actually reaches, so it is the one to
+     * show back.
+     */
+    email: string | null;
+    /** When the handover was filed, as the server holds it. Null unless it exists. */
+    createdAt: string | null;
+}
 interface UseExploreChatOptions {
     /** Slug of the product site this page is on — a soft hint to the harness. */
     productSlug?: string;
@@ -116,6 +144,30 @@ interface UseExploreChatResult {
         reason?: ExploreFeedbackReason | null;
         comment?: string | null;
     }) => Promise<boolean>;
+    /**
+     * Hand this conversation to a person, so they pick it up with the transcript attached.
+     *
+     * Awaited, like {@link submitFeedback} and for the same reason — the visitor is watching
+     * the control they pressed — but this one has more to say than true/false: "we could not
+     * deliver to that address", "you are sending these too fast" and "it is already with a
+     * human" are three different things to a worried visitor, and one boolean flattens them
+     * into a shrug. It never throws; every outcome comes back in
+     * {@link ExploreEscalateResult}.
+     *
+     * `email` is personal data. It goes into the mutation variables and nowhere else — not
+     * into `messages` (which is what this hook persists), not into `onSend`, not into any
+     * analytics call.
+     */
+    escalate: (email: string, note?: string) => Promise<ExploreEscalateResult>;
+    /**
+     * Whether there is a conversation a person could actually be handed.
+     *
+     * False on a fresh page and false in a read-only shared view (a `?c=` secret is not a
+     * conversation token), which are exactly the cases where {@link escalate} could only
+     * answer `no-conversation`. Offer the form on this, rather than offering one that cannot
+     * work.
+     */
+    canEscalate: boolean;
     /**
      * 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.
@@ -141,11 +193,6 @@ declare const FALLBACK_EXPLORE_LIMITS: ExploreLimits;
  * brochure without a single copy change being reviewed.
  */
 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 {
@@ -160,4 +207,38 @@ interface ArchivedExploreConversation {
 }
 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 };
+/**
+ * Stop whatever this SDK is reading aloud, from outside a component.
+ *
+ * A no-op when nothing of ours is speaking — deliberately, rather than calling
+ * `speechSynthesis.cancel()` unconditionally, which would also silence a host page that is
+ * using the same queue for its own reasons.
+ */
+declare function stopSpeaking(): void;
+interface UseSpeechOutputOptions {
+    /** BCP-47 tag to read in. Omit to let the platform pick its default voice. */
+    lang?: string;
+}
+interface UseSpeechOutputResult {
+    /**
+     * False when this browser has no synthesiser, or has one that was asked to speak and did
+     * not. Render no control at all when it is false — see the note at the top of the file.
+     */
+    supported: boolean;
+    speaking: boolean;
+    speak: (text: string) => void;
+    stop: () => void;
+    toggle: (text: string) => void;
+}
+declare function useSpeechOutput({ lang, }?: UseSpeechOutputOptions): UseSpeechOutputResult;
+
+/**
+ * The part of `text` that is currently on screen.
+ *
+ * @param text    everything that has arrived so far — `content` once the turn completes,
+ *                `partialContent` while it runs.
+ * @param settled true once the turn is COMPLETED or FAILED and `text` will not grow again.
+ */
+declare function useProgressiveReveal(text: string, settled: boolean): string;
+
+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 ExploreEscalateOutcome as c, type ExploreEscalateResult as d, type UseExploreChatResult as e, type UseSpeechOutputOptions as f, type UseSpeechOutputResult as g, classifyExploreError as h, useProgressiveReveal as i, useSpeechOutput as j, stopSpeaking as s, useExploreChat as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@burdenoff/website-sdk",
-  "version": "2026.922.4",
+  "version": "2026.923.1",
   "description": "Shared SDK for Burdenoff product websites - reusable React components, utilities, and configurations",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -74,8 +74,9 @@
     "type-check": "bash scripts/build-limits.sh tsc --noEmit",
     "prepublishOnly": "bun run build",
     "test": "vitest",
+    "test:run": "vitest run --maxWorkers=4",
     "test:coverage": "vitest --coverage",
-    "sanity": "bash scripts/build-limits.sh --gate bash -c 'bun run format:check && bun run lint:sanity && bun run type-check && bun run build'"
+    "sanity": "bash scripts/build-limits.sh --gate bash -c 'bun run format:check && bun run lint:sanity && bun run type-check && bun run test:run && bun run build'"
   },
   "keywords": [
     "burdenoff",