@sunboard/react 1.0.0 → 2.0.0

package/README.md

@@ -15,7 +15,12 @@ framework with your key already filled in, and a prompt you can hand to your cod
 import "@sunboard/react/styles.css";
 import { SunboardOverlay, SunboardProvider } from "@sunboard/react";
 
-<SunboardProvider connection={{ publishableKey: SUNBOARD_KEY, userId: currentUser.id }}>
+<SunboardProvider
+  connection={{
+    publishableKey: SUNBOARD_KEY,
+    userToken,
+  }}
+>
   <App />
   <SunboardOverlay />
 </SunboardProvider>
@@ -49,7 +54,30 @@ NEXT_PUBLIC_SUNBOARD_KEY=<your publishable key>
 VITE_SUNBOARD_KEY=<your publishable key>
 ```
 
-### 3. Create one Sunboard component
+### 3. Make a user token on your server
+
+Every request carries a token that says who the user is, so nobody can act as another user. Make
+it on your server with an identity secret from **Settings › Keys**. The secret never leaves your
+server: not in client code, not in a `NEXT_PUBLIC_` or `VITE_` variable, not in a repository. In
+Node, with `jsonwebtoken`:
+
+```ts
+import jwt from "jsonwebtoken";
+
+export function sunboardUserToken(user: { id: string; email: string; firstName?: string }) {
+  return jwt.sign(
+    { email: user.email, name: user.firstName },
+    process.env.SUNBOARD_IDENTITY_SECRET!,
+    { subject: user.id, expiresIn: "7d" },
+  );
+}
+```
+
+Set the expiry to about how long a sign-in to your app lasts, because the widget cannot ask for a
+new token on its own. Any language with a JWT library works the same way. Sign with HS256 and the
+secret, put the user's id in `sub`, and add `email` and an optional `name`.
+
+### 4. Create one Sunboard component
 
 It connects to Sunboard, shows tours and the Help launcher, and lets a tour change pages through
 your router. This is the Next.js version:
@@ -63,22 +91,13 @@ import type { ReactNode } from "react";
 import { useRouter } from "next/navigation";
 import { SunboardOverlay, SunboardProvider } from "@sunboard/react";
 
-export function Sunboard({
-  userId,
-  firstName,
-  children,
-}: {
-  userId: string;
-  firstName?: string;
-  children: ReactNode;
-}) {
+export function Sunboard({ userToken, children }: { userToken: string; children: ReactNode }) {
   const router = useRouter();
   return (
     <SunboardProvider
       connection={{
         publishableKey: process.env.NEXT_PUBLIC_SUNBOARD_KEY!,
-        userId,
-        user: { firstName },
+        userToken,
       }}
       navigate={(path) => router.push(path)}
     >
@@ -109,18 +128,17 @@ import sunboardCss from "@sunboard/react/styles.css?url";
 `useRouter` and `useNavigate` work only inside the router, so mount the component where the
 table below says.
 
-### 4. Wrap your signed-in pages
+### 5. Wrap your signed-in pages
 
-Put the component around the pages a signed-in user sees, and pass that user's id. Use an id that
-stays the same for each person. The first name is optional. With it the assistant greets the
-user ("Hey Sam,"), without it it says "Hey there,". The name stays in the browser.
+Put the component around the pages a signed-in user sees, and pass the token from step 3. Use an
+id that stays the same for each person. Your team sees the email when the user writes to them.
+The name is optional. With it the assistant greets the user ("Hey Sam,"), without it it says
+"Hey there,".
 
 ```tsx
 import { Sunboard } from "./sunboard";
 
-<Sunboard userId={currentUser.id} firstName={currentUser.firstName}>
-  {children}
-</Sunboard>
+<Sunboard userToken={userToken}>{children}</Sunboard>
 ```
 
 | Framework | Where |
@@ -133,7 +151,7 @@ import { Sunboard } from "./sunboard";
 A Next.js app with route groups, such as `app/(marketing)/layout.tsx` and
 `app/(app)/layout.tsx`, wraps `children` in the signed-in group's layout only.
 
-### 5. Check it works
+### 6. Check it works
 
 Start your app and sign in. **Settings › Install** in the Sunboard app shows **Connected**. Then
 add your app's address under **Settings › Project**, and use **Preview** on any guide to see it
@@ -153,7 +171,7 @@ in your app.
 - **Preview.** The **Preview** button on a guide in the Sunboard app opens your app with
   `?sunboardPreview=<key>` in the address and shows paused guides as well as live ones, in that
   browser only. `?sunboardPreview=off` ends it.
-- **Users.** The active-user limit on your plan counts the ids you pass as `userId`, so give each
+- **Users.** The active-user limit on your plan counts the ids in your user tokens, so give each
   person one id that never changes.
 
 ## Reference
@@ -162,7 +180,7 @@ in your app.
 
 | Prop | Type | Default | What it does |
 | --- | --- | --- | --- |
-| `connection` | `{ publishableKey: string; userId: string; user?: { firstName?: string } }` | required | Your publishable key and the signed-in user's id. `user.firstName` is for the assistant's greeting and stays in the browser. |
+| `connection` | `{ publishableKey: string; userToken: string }` | required | Your publishable key and the user token from step 3. |
 | `navigate` | `(path: string) => void \| Promise<void>` | full page load | How a tour moves to another page. Pass your router. Without it, a tour loads the next page in full and carries on there. |
 | `labels` | `LabelOverrides` | English | Your own words for any of the SDK's buttons and text, for example `labels={{ launcher: { open: "Support" } }}`. The rest stay English. `enLabels` has every one. |
 | `mode` | `"auto" \| "light" \| "dark"` | `"auto"` | Light or dark. `"auto"` follows a `dark` or `light` class, or a `data-theme`, `data-mode` or `data-color-scheme` attribute, on `<html>` or `<body>`, then the system setting, and tracks changes live. |
@@ -207,7 +225,7 @@ Call `useLauncher()` once for your help menu and pass what it returns down.
 | `tourRunning` | `true` while a tour runs. |
 | `opened()` | Call it when your menu opens, so the open counts in Analytics. |
 | `start(guideKey, replyId?)` | Starts a guide. Pass the id of the answer that offered it, and the conversation gets a line after that answer when the tour ends. |
-| `messages` | The conversation with the assistant, oldest first. Each `Message` has an `id` and a `kind`: `question`, `waiting`, `reply`, `error` or `tour`. A `reply` holds an `AskReply` with the answer's text in `answer`, the articles it came from in `sources`, and `guideKey` when it offers a guide to start. |
+| `messages` | The conversation with the assistant, oldest first. Each `Message` has an `id` and a `kind`: `question`, `waiting`, `reply`, `error` or `tour`. A `reply` holds an `AskReply` with the answer's text in `answer` and `guideKey` when it offers a guide to start. |
 | `waiting` | `true` while a question is out and its answer has not come back. |
 | `rateLimitedUntil` | While the user has asked too many questions this hour, the time they can ask again, as an ISO string. Otherwise `undefined`. |
 | `handedOff` | `true` while a tour started from the conversation runs. It turns `false` when the tour ends, the moment to show your panel again. |
@@ -249,6 +267,8 @@ the colors in use as CSS variables to spread onto your menu so it matches the to
 - **Nothing shows in my app.** Add `?sunboardDebug=1` to the page address and open the browser
   console with the Verbose level on. A wrong key shows as a failed request. No lines at all means
   the provider is not mounted around the page you are on.
+- **Every request fails with 401.** The user token is not signed with the identity secret from
+  **Settings › Keys**, has expired, or has no `sub` or `email`.
 - **Settings › Install does not say Connected.** It turns Connected on the first request from your
   app, so load a page where the provider is mounted, signed in, and reload the Install tab.
 - **A tour reloads the page instead of changing route.** Pass `navigate` with your router. Without
@@ -258,9 +278,9 @@ the colors in use as CSS variables to spread onto your menu so it matches the to
 - **Requests to api.sunboardhq.com are blocked.** Your Content Security Policy needs it in
   `connect-src`.
 - **Next.js says the component needs "use client".** Put `"use client"` on the first line of your
-  `sunboard.tsx`, as in step 3. The package itself is already client code.
+  `sunboard.tsx`, as in step 4. The package itself is already client code.
 - **useRouter or useNavigate throws.** Mount the component inside the router, where the table in
-  step 4 says.
+  step 5 says.
 
 ## License
 

package/dist/index.d.mts

@@ -68,6 +68,8 @@ interface ComponentSettings {
   launcher: {
     showBranding: boolean;
     supportUrl: string | null;
+    talkToPerson: boolean;
+    replyTime: string;
   };
   tour: {
     showStepCount: boolean;
@@ -332,39 +334,95 @@ type GuideEventReport = {
 });
 /**
  * ANSWERED is an answer written from the docs and checked against them.
- * UNSUPPORTED is one the check did not back, so the visitor is pointed at the
- * section instead.
- * GUIDE offers a tour, with an answer when sections were found too.
+ * UNSUPPORTED is one the check did not back twice, so the visitor gets the
+ * not-covered reply. NONE found nothing to answer with.
+ * GUIDE offers a tour, with an answer when one was written and backed.
  */
 type AskOutcome = "GUIDE" | "ANSWERED" | "UNSUPPORTED" | "NONE";
-/** One section the answer came from. */
-interface AskArticle {
-  /** The section's id. */
-  id: string;
-  /** The article's title. */
-  title: string;
-  /** Where the article is read. An article written in Sunboard has none. */
-  url?: string;
-  /** The section's heading, when it has one. */
-  heading?: string;
-}
 /** `id` is the stored question's id. `answer` is the whole text to show. */
 interface AskReply {
   id: string;
   /** Sent back with the next question so it is read as a follow-up. */
-  conversationId: string;
-  /** This question opened its conversation, so the widget greets the visitor. */
+  threadId: string;
+  /** This question opened its thread, so the widget greets the visitor. */
   firstTurn: boolean;
   outcome: AskOutcome;
-  /** Plain text with blank lines between paragraphs, `1.` and `-` lists, and `**bold**`. */
+  /**
+   * Plain text with blank lines between paragraphs, `1.` and `-` lists, and
+   * `**bold**`. Empty when a guide is offered with nothing written.
+   */
   answer: string;
-  /** At most three, in the order the answer used them. */
-  sources: AskArticle[];
   guideKey?: string;
+  /** Set when the answer is the not-covered sentence and the project has a support link. */
   supportUrl?: string;
 }
 /** What the server is doing while the visitor waits, in this order. */
 type AskStage = "searching" | "writing" | "checking";
+type ConversationStatus = "OPEN" | "PENDING" | "CLOSED";
+type ConversationAuthor = "END_USER" | "TEAM";
+/** Every conversation route answers this while the plan or the project's Talk to a person is off. */
+interface ConversationOff {
+  off: true;
+}
+/** The end user's conversation that is not closed, as the widget polls it. Dates are ISO. */
+interface ConversationSummary {
+  id: string;
+  status: ConversationStatus;
+  lastMessageAt: string;
+  lastMessageBy: ConversationAuthor;
+  lastMessageText: string;
+  /** The team member who wrote the last message, or null when the end user did. */
+  lastMessageWho: string | null;
+  /** A reply from the team the end user has not opened yet. */
+  unread: boolean;
+}
+/** GET /runtime/conversation. */
+interface ConversationPoll {
+  open: ConversationSummary | null;
+  hasPast: boolean;
+}
+interface ConversationMessageWire {
+  id: string;
+  by: ConversationAuthor;
+  /** The team member's name. Null for the end user's own messages. */
+  who: string | null;
+  text: string;
+  sentAt: string;
+}
+/** A question the end user asked the assistant, shown folded in the conversation. */
+interface FoldedQuestionWire {
+  id: string;
+  text: string;
+  askedAt: string;
+  outcome: AskOutcome;
+}
+/** GET /runtime/conversation/:id. With `after`, `messages` holds only the newer ones. */
+interface ConversationView {
+  id: string;
+  status: ConversationStatus;
+  startedAt: string;
+  closedAt: string | null;
+  closed: boolean;
+  messages: ConversationMessageWire[];
+  /** Asked the assistant before the conversation started, on the thread it started from. */
+  before: FoldedQuestionWire[];
+  /** Asked the assistant while the conversation was not closed. */
+  during: FoldedQuestionWire[];
+}
+/** POST /runtime/conversation and POST /runtime/conversation/:id/messages. */
+interface ConversationSent {
+  summary: ConversationSummary;
+  message: ConversationMessageWire;
+}
+/** One of GET /runtime/conversations, most recently closed first. */
+interface PastConversation {
+  id: string;
+  /** The end user's first message. */
+  title: string;
+  closedAt: string | null;
+  /** The team member who closed it. */
+  closedBy: string | null;
+}
 //#endregion
 //#region ../core/src/anchors.d.ts
 type AnchorPart = {
@@ -402,8 +460,6 @@ interface Labels {
     send: string;
     /** The pill that scrolls back down to the newest message. */
     latest: string;
-    /** On an older reply whose sources are folded away. */
-    sourcesCount: (count: number) => string;
     /** Over the first answer of a conversation. `name` is the connection's `user.firstName`. */
     greeting: (name?: string) => string;
     /** Under an answer that offers a guide, above Show me how. */
@@ -417,7 +473,7 @@ interface Labels {
     /** The line once the visitor picked a star. */
     ratingThanks: string;
     /** The thread's own name, for a screen reader. */
-    conversation: string;
+    thread: string;
     /** Said once to a screen reader while a question is out. */
     writingStatus: string;
     /** While the question is out, one for each stage the server reports. */
@@ -428,8 +484,6 @@ interface Labels {
       /** After six seconds of waiting. */
       slow: string;
     };
-    /** The name of the group of sections an answer came from, for a screen reader. */
-    sources: string;
     /** Over the guides listed before the first question, this page's first. */
     commonQuestions: string;
     /** The one button under an answer that has a guide behind it. */
@@ -447,15 +501,50 @@ interface Labels {
     lostBody: string;
     tryAgain: string;
     /**
-     * What the server answers when nothing was written: no guide and no
-     * section, a section with no backed answer, a guide with no section.
+     * What the server answers when there is nothing to show: no guide and no
+     * section, or no guide and an answer the check did not back twice.
      */
     notCovered: (product: string) => string;
-    coveredBy: (article: string, heading?: string) => string;
-    guideFound: string;
     closeAria: string;
     poweredBy: string;
   };
+  /**
+   * Talk to a person. `company` is the project's name as the launcher shows
+   * it, `name` the connection's `user.firstName`, `who` a team member's name.
+   */
+  support: {
+    talkToPerson: string;
+    /** The header of the conversation. */
+    title: (company: string) => string;
+    back: string;
+    /** The line between the assistant's turns and the conversation. */
+    talking: (company: string) => string;
+    /** The fixed first line of every conversation, and who it is from. */
+    greeting: (name?: string) => string;
+    from: (company: string) => string;
+    boxLabel: (company: string) => string;
+    placeholder: (company: string) => string;
+    /** Over a message from the team. `time` is `clock` today and `ago` before. */
+    teamMessage: (who: string | null, company: string, time: string) => string;
+    /** A question asked of the assistant while the conversation was open, folded. */
+    asked: (question: string) => string;
+    closed: (company: string) => string;
+    reopen: string;
+    /** The bar over the assistant's thread, and the row on the start screen. */
+    conversationWith: (company: string) => string;
+    replied: (who: string) => string;
+    waiting: string;
+    newReply: string;
+    openAriaNewReply: string;
+    past: string;
+    /** Under a past conversation. `when` is from `ago`. */
+    closedWhen: (when: string, who: string | null) => string;
+    ago: (days: number) => string;
+    tooMany: string;
+    writeAgainIn: (minutes: number) => string;
+    lost: string;
+    lostBody: string;
+  };
   tour: {
     back: string;
     next: string;
@@ -520,12 +609,71 @@ export declare function detectThemeMode(): ThemeMode;
  */
 export declare function useThemeMode(setting: ThemeModeSetting): ThemeMode;
 //#endregion
+//#region src/memory-support.d.ts
+interface ScriptedMessage {
+  by: ConversationAuthor;
+  /** The team member, for a message from the team. */
+  who?: string;
+  text: string;
+  sentAt: string;
+}
+interface ScriptedConversation {
+  messages: ScriptedMessage[];
+  /** Asked the assistant before the conversation started. */
+  before?: Omit<FoldedQuestionWire, "id" | "outcome">[];
+  /** Asked the assistant while it was open. */
+  during?: Omit<FoldedQuestionWire, "id" | "outcome">[];
+  /** A reply from the team the end user has not opened. */
+  unread?: boolean;
+  /** Set on a closed conversation. */
+  closedAt?: string;
+  closedBy?: string;
+}
+interface SupportScript {
+  /** Conversations that exist when the page loads, at most one of them not closed. */
+  conversations?: ScriptedConversation[];
+  /** The team answers the first message of a conversation this long after it is sent. */
+  reply?: {
+    who: string;
+    text: string;
+    afterMs: number;
+  };
+  /** Every write is refused this way. */
+  refuse?: ConversationRefused["refused"];
+}
+declare class MemorySupport implements SupportTransport {
+  private readonly script;
+  readonly starts: ConversationStart[];
+  readonly sent: {
+    id: string;
+    text: string;
+  }[];
+  readonly reads: string[];
+  polls: number;
+  views: number;
+  private readonly conversations;
+  constructor(script: SupportScript);
+  conversationPoll(): Promise<ConversationPoll>;
+  conversation(id: string, after?: string): Promise<ConversationView | null>;
+  startConversation(start: ConversationStart): Promise<ConversationWrite>;
+  sendMessage(id: string, text: string): Promise<ConversationWrite>;
+  markRead(id: string): Promise<void>;
+  pastConversations(): Promise<PastConversation[]>;
+  /** The team writes into the open conversation. */
+  teamReplies(text: string, who: string): void;
+  /** The team closes the open conversation. */
+  teamCloses(who: string): void;
+  private write;
+  private open;
+  private find;
+}
+//#endregion
 //#region src/transport.d.ts
 interface AskQuestion {
   question: string;
   pathname: string;
   /** The conversation the last reply named; left out on the first question. */
-  conversationId?: string;
+  threadId?: string;
 }
 /**
  * What one question got. A refusal (the question was too long, or too many
@@ -541,14 +689,52 @@ type AskResult = {
   message: string;
   retryAt?: string;
 };
+/** The first message of a conversation with the project's team. */
+interface ConversationStart {
+  /** The assistant thread the end user was in, so the team sees what they asked first. */
+  threadId: string | null;
+  /** The page they wrote from. */
+  path: string;
+  text: string;
+}
+/**
+ * A message the runtime did not take. `too-many` is the hourly cap and carries
+ * the time it lifts. `another-open` and `lost` both mean the conversation on
+ * screen is not the one the runtime has, or the request never landed.
+ */
+interface ConversationRefused {
+  refused: "too-many" | "another-open" | "lost";
+  retryAt?: string;
+}
+type ConversationWrite = ConversationSent | ConversationRefused | ConversationOff;
+/**
+ * Talk to a person: the end user's side of a conversation with the project's
+ * team. Every call can answer `{ off: true }`, which turns the feature off for
+ * the visit.
+ */
+interface SupportTransport {
+  /** The open conversation, if any, and whether there are closed ones. */
+  conversationPoll(): Promise<ConversationPoll | ConversationOff>;
+  /** Null when the conversation is not this end user's. With `after`, only newer messages. */
+  conversation(id: string, after?: string): Promise<ConversationView | ConversationOff | null>;
+  /** Starts a conversation, or writes into the open one. */
+  startConversation(start: ConversationStart): Promise<ConversationWrite>;
+  /** Writes into a conversation, and reopens it when the team closed it. */
+  sendMessage(id: string, text: string): Promise<ConversationWrite>;
+  markRead(id: string): Promise<void>;
+  /** Closed conversations, newest first. */
+  pastConversations(): Promise<PastConversation[] | ConversationOff>;
+}
 interface GuidesTransport {
   /**
    * The identity a cached bootstrap belongs to. Undefined means this
    * transport's data is never cached.
    */
   readonly cacheKey?: string;
-  /** The visitor's details from the connection. Never sent anywhere. */
-  readonly user?: VisitorDetails;
+  /** The visitor's first name from the user token, for the greetings. */
+  readonly user?: {
+    readonly firstName?: string;
+  };
   bootstrap(): Promise<BootstrapAnswer>;
   /** Persist a user-state mutation; the provider applies it optimistically. */
   mutate(action: StateAction): Promise<void>;
@@ -574,13 +760,18 @@ interface GuidesTransport {
    * provider never looks at the page.
    */
   reportPage?(report: PageReport): Promise<void>;
+  /**
+   * Talk to a person. Optional: without it, the assistant offers the
+   * project's support link as before.
+   */
+  readonly support?: SupportTransport;
 }
 /**
  * A scripted reply. The transport's own conversation id fills in when it names
  * none, and `firstTurn` is true when the question named no conversation.
  */
-type ScriptedReply = Omit<AskReply, "conversationId" | "firstTurn"> & {
-  conversationId?: string;
+type ScriptedReply = Omit<AskReply, "threadId" | "firstTurn"> & {
+  threadId?: string;
   firstTurn?: boolean;
 };
 /**
@@ -597,7 +788,9 @@ type AskScript = (asked: AskQuestion) => {
 };
 interface MemoryTransportOptions {
   cacheKey?: string;
-  user?: VisitorDetails;
+  user?: {
+    firstName?: string;
+  };
   /** Opt in to the question box. Without a script there is no `ask` at all. */
   ask?: AskScript;
   /** Opt in to page reports. Without it there is no `reportPage`, and nothing looks at the page. */
@@ -607,6 +800,8 @@ interface MemoryTransportOptions {
    * script names its own, so every stage of the waiting can be looked at.
    */
   gapMs?: number;
+  /** Opt in to Talk to a person, with the team scripted. */
+  support?: SupportScript;
 }
 export declare class MemoryTransport implements GuidesTransport {
   private readonly data;
@@ -618,9 +813,12 @@ export declare class MemoryTransport implements GuidesTransport {
   readonly questions: AskQuestion[];
   readonly pages: PageReport[];
   readonly cacheKey: string | undefined;
-  readonly user: VisitorDetails | undefined;
+  readonly user: {
+    firstName?: string;
+  } | undefined;
   readonly ask?: GuidesTransport["ask"];
   readonly reportPage?: GuidesTransport["reportPage"];
+  readonly support?: MemorySupport;
   constructor(data: BootstrapData, options?: MemoryTransportOptions);
   bootstrap(): Promise<BootstrapData>;
   mutate(action: StateAction): Promise<void>;
@@ -641,18 +839,14 @@ export declare const DEFAULT_SUNBOARD_API_URL = "https://api.sunboardhq.com";
 export declare const PREVIEW_PARAM = "sunboardPreview";
 export declare const PREVIEW_KEY_STORAGE = "sunboard:preview-key";
 export declare const PREVIEW_EXPIRY_STORAGE = "sunboard:preview-until";
-/** The visitor's details. They stay in the browser: none of them is sent to Sunboard. */
-interface VisitorDetails {
-  /** The visitor's first name, as you want the assistant to greet them ("Hey Sam,"). */
-  firstName?: string;
-}
 interface HttpTransportConfig {
   /** The workspace's publishable key. Safe in client bundles. */
   publishableKey: string;
-  /** Customer-supplied end-user id. */
-  userId: string;
-  /** The visitor's details, kept in the browser. */
-  user?: VisitorDetails;
+  /**
+   * A token your server signs with the project's identity secret. It names the visitor (`sub`),
+   * where your team can reach them (`email`) and their first name (`name`).
+   */
+  userToken: string;
   /** Origin of the runtime API. Defaults to the hosted API. */
   baseUrl?: string;
   /**
@@ -667,8 +861,17 @@ export declare class HttpTransport implements GuidesTransport {
   private readonly baseUrl;
   private readonly previewKey;
   readonly cacheKey: string | undefined;
-  readonly user: VisitorDetails | undefined;
+  readonly user: {
+    readonly firstName?: string;
+  };
+  readonly support: SupportTransport;
   constructor(config: HttpTransportConfig);
+  private identity;
+  private signed;
+  private send;
+  private getJson;
+  private post;
+  private write;
   private headers;
   private request;
   bootstrap(): Promise<BootstrapAnswer>;
@@ -708,7 +911,7 @@ interface GuidesApi {
    * `cacheKey`. Undefined for a preview session, which keeps nothing.
    */
   cacheKey: string | undefined;
-  /** The visitor's first name from the connection, for the assistant's greeting. */
+  /** The visitor's first name from the user token, for the assistant's greeting. */
   firstName: string | undefined;
   reportAnchorMiss: GuidesTransport["reportAnchorMiss"];
   /** Sent only for a step that missed before, once per step and revision per page load. */
@@ -719,6 +922,8 @@ interface GuidesApi {
    * always has it; a `MemoryTransport` needs a script.
    */
   ask: GuidesTransport["ask"];
+  /** Talk to a person's calls. Undefined when the transport has none or Sunboard is off. */
+  support: GuidesTransport["support"];
   /** Record a usage event. Batched, fire-and-forget, never awaited. */
   track: (event: GuideEventReport) => void;
   /**
@@ -821,6 +1026,26 @@ type Message = {
   rating?: TourRating;
 };
 //#endregion
+//#region src/support.d.ts
+type SupportView = "assistant" | "conversation" | "past";
+interface Support {
+  /** A poll or a write answered off: the feature is gone for the rest of the visit. */
+  off: boolean;
+  open: ConversationSummary | null;
+  hasPast: boolean;
+  view: SupportView;
+  /**
+   * The conversation on screen. Null on the conversation view before the
+   * first message, while only the greeting shows.
+   */
+  conversation: ConversationView | null;
+  /** The conversation on screen was opened from Past conversations, so it has no composer. */
+  readOnly: boolean;
+  past: PastConversation[] | null;
+  sending: boolean;
+  failure: ConversationRefused | null;
+}
+//#endregion
 //#region src/hooks.d.ts
 export declare function useGuidesApi(): GuidesApi;
 interface LauncherOptions {
@@ -842,6 +1067,8 @@ interface LauncherList extends LauncherGroups {
   start: (guideKey: string, replyId?: string) => void;
   /** The thread, oldest first. Each hook instance holds its own. */
   messages: readonly Message[];
+  /** The assistant thread the server named, which a conversation with the team starts from. */
+  threadId: string | undefined;
   /** A question is out and its reply has not come back yet. */
   waiting: boolean;
   /** When the visitor may ask again, while the newest question was capped. */
@@ -868,6 +1095,31 @@ interface LauncherList extends LauncherGroups {
   rate: (lineId: string, rating: TourRating) => void;
 }
 export declare function useLauncher({ remember }?: LauncherOptions): LauncherList;
+interface SupportOptions {
+  /** The panel is open, so the conversation view, when it is the view, is on screen. */
+  onScreen: boolean;
+  /** The assistant thread a new conversation starts from. */
+  threadId?: string;
+}
+interface SupportPanel {
+  /** Talk to a person is offered: the project's switch is on and the transport has the calls. */
+  available: boolean;
+  state: Support;
+  /** Open the conversation view: the open conversation, or a new one. */
+  talk: () => void;
+  /** Write to the team. Resolves true when the message was taken. */
+  send: (text: string) => Promise<boolean>;
+  showPast: () => void;
+  openPast: (id: string) => void;
+  back: () => void;
+}
+/**
+ * Talk to a person. Polls the runtime only while it can matter: once on load,
+ * then every 30 seconds while the end user has an open conversation, and the
+ * conversation itself every 5 seconds while it is on screen. Nothing polls
+ * while the tab is hidden.
+ */
+export declare function useSupport({ onScreen, threadId }: SupportOptions): SupportPanel;
 /** One guide's content plus launchTour; call with no key for launch-only. */
 export declare function useGuide(key?: string): {
   guide: GuideContent | undefined;
@@ -970,4 +1222,4 @@ interface LauncherProps {
 }
 export declare function Launcher({ inline }?: LauncherProps): import("react").JSX.Element | null;
 //#endregion
-export type { ActiveTour, Anchor, AnchorElementState, AnchorMatch, AskArticle, AskFailure, AskOutcome, AskQuestion, AskReply, AskResult, AskScript, AskStage, BootstrapAnswer, BootstrapData, BootstrapOff, ComponentSettings, GuideContent, GuideStep, GuideType, GuidesApi, GuidesTransport, HttpTransportConfig, LabelOverrides, Labels, LauncherList, LauncherOptions, LauncherProps, MemoryTransportOptions, Message, Palette, PinPosition, ScriptedReply, StepPlacement, StepPrimitive, SunboardOverlayProps, SunboardProviderProps, Theme, ThemeMode, ThemeModeSetting, TourEnd, TourEnding, UserState, VisitorDetails };
+export type { ActiveTour, Anchor, AnchorElementState, AnchorMatch, AskFailure, AskOutcome, AskQuestion, AskReply, AskResult, AskScript, AskStage, BootstrapAnswer, BootstrapData, BootstrapOff, ComponentSettings, ConversationMessageWire, ConversationOff, ConversationPoll, ConversationRefused, ConversationSent, ConversationStart, ConversationSummary, ConversationView, ConversationWrite, FoldedQuestionWire, GuideContent, GuideStep, GuideType, GuidesApi, GuidesTransport, HttpTransportConfig, LabelOverrides, Labels, LauncherList, LauncherOptions, LauncherProps, MemoryTransportOptions, Message, Palette, PastConversation, PinPosition, ScriptedReply, StepPlacement, StepPrimitive, SunboardOverlayProps, SunboardProviderProps, Support, SupportOptions, SupportPanel, SupportScript, SupportTransport, SupportView, Theme, ThemeMode, ThemeModeSetting, TourEnd, TourEnding, UserState };