andy-widget-react 2.3.2 → 3.0.0-next.10

package/README.md

@@ -5,13 +5,14 @@ The official React Widget for Andy. Its canonical source is
 
 ## Install
 
-Pin an exact reviewed release:
+Pin an exact reviewed release. 3.0 prereleases are on the npm `next` tag:
 
 ```bash
-bun add andy-widget-react@2.3.2
+bun add andy-widget-react@3.0.0-next.10
 ```
 
-React and React DOM 18 or 19 are required peer dependencies.
+React and React DOM 18 or 19 are peer dependencies. `andy-widget-core` (the `<andy-chat>` element) comes with
+it as a dependency at the same exact version; the wrapper never inlines it.
 
 ## Use
 
@@ -23,61 +24,80 @@ import { AndyChat, setApiBaseUrl } from 'andy-widget-react'
 setApiBaseUrl('https://app.andypartner.com/api')
 
 export function SupportWidget() {
-	return <AndyChat embedId='your-agent-id' />
+	return <AndyChat agentId='your-agent-id' />
 }
 ```
 
-`embedId` is the non-secret Andy Agent ID. The Widget fetches its effective configuration from
-`GET /api/chatbot/:embedId` and sends visitor messages to `POST /api/messages`. The browser sends
-the embedding page's `Origin`; Andy enforces the Agent's exact allowed-origin configuration.
+`AndyChat` renders one `<andy-chat>` element and hands it its props. `agentId` is the non-secret Andy Agent
+ID: the Widget fetches its configuration from `GET /api/chatbot/:agentId` and streams replies from
+`POST /api/chat/stream`. The browser sends the embedding page's `Origin`; Andy enforces the Agent's allowed
+origins. Server rendering draws an empty host `<div>`; the element mounts on the client.
 
-The launcher starts closed. If the Agent ID is invalid or configuration cannot be loaded, the
-Widget renders no launcher and does not affect the host page. Message failures remain inside the
-Widget as a short, language-aware retry message.
+The Launcher starts closed. If the Agent ID is invalid or its configuration cannot be loaded, nothing shows
+and the host page is unaffected.
 
 ## Props
 
 | Prop | Type | Purpose |
 | --- | --- | --- |
-| `embedId` | `string` | Required Agent ID outside preview mode |
-| `tooltip` | `string` | Optional launcher tooltip |
-| `name` | `string` | Override the configured Agent name |
-| `headline` | `string` | Override the configured headline |
-| `description` | `string` | Override the configured description |
-| `welcomeMessage` | `string` | Override the configured first message |
-| `bubbleLabel` | `string` | Override the configured pill label |
-| `lang` | `'en' \| 'es'` | Language for the Widget's own chrome (placeholder, starter-question title, error and handoff text). Overrides the Agent's `defaultLang`, so a Spanish Agent on an English page still renders English chrome |
-| `predefinedQuestions` | `{ order: number, question: string }[]` | Override the configured starter questions |
-| `theme` | `'light' \| 'dark' \| 'auto'` | Override the configured theme |
-| `orientation` | `'left' \| 'right'` | Override the configured position |
-| `brandColor` | `string` | Override the configured six-digit hex color |
-| `bubbleStyle` | `'icon' \| 'pill'` | Override the configured launcher style |
-| `useBrandColor` | `boolean` | Override configured brand-color use |
-| `logoUrl` | `string` | Override the configured logo |
-| `previewMode` | `boolean` | Render local prop-based preview configuration |
-| `initialOpen` | `boolean` | Opt into an initially open Widget; defaults to `false` |
-
-The server configuration controls **Powered by Andy** visibility. Consumers cannot suppress it
-with a prop. FAQ entries render only when the API supplies both a question and an answer; the
-current question-only response safely exposes no incomplete FAQ. Visitor-information and lead
-capture are disabled in this release because there is no durable public submission boundary.
-
-This release intentionally has no Widget analytics or event callback API. Use Andy's existing
-conversation analytics rather than observing the Shadow DOM.
+| `agentId` | `string` | The Sales Agent ID, shown to anonymous Visitors |
+| `support` | `SupportOptions` | Support Mode for signed-in Requesters (see [Authenticated Support](#authenticated-support)) |
+| `lang` | `'en' \| 'es'` | The Widget's language, over the page's `<html lang>`, the browser's language and the Agent's `defaultLang` |
+| `initialOpen` | `boolean` | Start with the panel open; defaults to `false` |
+| `orientation` | `'left' \| 'right'` | The Launcher's side |
+| `nudge` | `{ id: string, message: string, draft?: string, delayMs?: number } \| null` | A bubble above the closed Launcher, in Sales and Support Mode (see [Nudge](#nudge)) |
+| `name` | `string` | Override the Agent's name |
+| `welcomeMessage` | `string` | Override the Greeting |
+| `predefinedQuestions` | `{ order: number, question: string }[]` | Override the Starters |
+| `theme` | `'light' \| 'dark' \| 'auto'` | Override the theme |
+| `brandColor` | `string` | Override the accent (`#RRGGBB`) |
+| `useBrandColor` | `boolean` | `false` uses the neutral accent |
+| `bubbleStyle` | `'icon' \| 'pill'` | Override the Launcher style |
+| `bubbleLabel` | `string` | Override the pill Launcher's label |
+| `logoUrl` | `string` | Override the avatar, also shown on the Launcher |
+| `previewMode` | `boolean` | Draw the override props over the defaults with no configuration fetched (a Widget Preview); messages still reach `agentId` |
+| `embedId` | `string` | Deprecated alias of `agentId`; logs one notice |
+| `mode` | `'support'` | Deprecated: `support` without `agentId`; logs one notice |
+| `tooltip` | `string` | Deprecated and ignored: the 3.x Launcher has no tooltip |
+| `headline` | `string` | Deprecated and ignored: the panel shows only the name and the Greeting, with no status line |
+| `description` | `string` | Deprecated and ignored: the panel shows no intro description |
+
+The overrides replace the Agent's own values in the Widget's language, in Sales Mode only; an empty or invalid
+value leaves the Agent's. The server configuration controls **Powered by Andy**; no prop suppresses it.
+
+## Nudge
+
+`nudge` asks the user something from a bubble above the closed Launcher, for example feedback on a new page:
+
+```tsx
+<AndyChat
+	support={support}
+	nudge={{ id: 'visualizaciones-feedback-1', message: '¿Hay algo que mejorarías de esta visualización?', draft: 'Mejoraría ' }}
+/>
+```
+
+- It shows `delayMs` after the Launcher appears (default 1,500 ms), only while the panel is closed, on the Launcher's side.
+- Clicking it opens the panel with `draft` in an empty composer; nothing is sent until the user sends it.
+- It shows on every page that passes it. Once its × is clicked, or the bubble opens the panel, it stays hidden for the rest of the browser session (`sessionStorage`, per `id`). A new session (a new tab or a reopened browser) shows it again, and so does a new `id`.
+- `null`, or a different `id`, updates it in place without remounting the Widget. The same `id` with new text only changes the text.
 
 ## Authenticated Support
 
-Support requires a configured host installation and a server-provisioned Support Agent. Use the accepted core/React package pair; this source addition is unpublished until the coordinated release is approved.
+Support requires a configured host installation and a server-provisioned Support Agent.
+
+One Widget serves both: its Widget Mode comes from identity. A Visitor gets Sales Mode with `agentId`; a signed-in Requester whose `getRequesterPass` returns a pass gets Support Mode. Without `agentId` (a Support-only host) nothing shows until a Requester is verified.
 
 ```tsx
 <AndyChat
-  mode='support'
+  agentId='your-sales-agent-id'
   lang='es'
   support={{
     installationId: hostInstallationId,
-    contextKey: `${signedInUserId}:${selectedCompanyId}`,
+    contextKey: signedInUserId ? `${signedInUserId}:${selectedCompanyId}` : 'anonymous',
     getRequesterPass: async () => {
-      const response = await fetch('/api/andy/requester-pass', { cache: 'no-store' })
+      if (!signedInUserId) return null // known signed out: Sales shows without a round trip
+      const response = await fetch('/api/andy/requester-pass', { method: 'POST', cache: 'no-store' })
+      if (response.status === 401) return null // signed out
       if (!response.ok) throw new Error('Support authentication unavailable')
       return (await response.json()).pass
     }
@@ -85,32 +105,32 @@ Support requires a configured host installation and a server-provisioned Support
 />
 ```
 
-That host endpoint signs on the server from the authenticated user/company; never put a signing key in the browser. Change `contextKey` whenever identity/company changes, and unmount on sign-out. The SDK aborts and clears old private state. The pass remains in memory and is sent only in `X-Andy-Requester`. Expired/unknown-key refusals renew once; other failures stop inside the panel. `apiBaseUrl` may explicitly select the reviewed Andy API origin; normal production defaults to Andy.
-
-Provider branding and links, greeting/questions and reply promise come from Andy. When the host `lang` differs from the Agent default language, Support uses a localized default greeting and omits the Agent’s untranslated suggested questions. Existing conversation messages keep their original language. Custom hooks can pass `lang` in their Support options. There is no `embedId`, visitor identity form or Sales action in this mode. Sending the team form consents to attach the frozen conversation; its retry preserves the request key and receipt. Mis solicitudes stays inside the panel and displays the Requester's public human thread. The panel fills phones. Vanilla Support is frozen.
-
-For a custom React presentation, `useAndyChat({ mode: 'support', support })` returns `{ mode, state, controller }`. The controller exposes `send`, `escalate`, `submit`, `showRequests`, `inspect`, `back` and `newConversation`; it has the same consent, abort and retry semantics as the mounted panel. Do not use Sales presentation helpers with this result. Ticket replies and explicit reopens use the private human Requester operations, never the AI route.
+That host endpoint signs on the server from the authenticated user/company; never put a signing key in the browser. The installation ID is public and is never a credential: without a pass there is no Support Mode. Identity comes only from the pass, never from name or email props.
 
-The panel captures its displayed `lang` on the first consented open as the ticket's Reply Email preference. A retry keeps that original choice even if the host changes language. Custom presentations call `controller.submit(subject, body, 'es' | 'en')` with their displayed language; omission defaults to Spanish. This copy preference never enters the signed pass or provider configuration.
+- Change `contextKey` on sign-in, sign-out and every user, workspace or organization switch. Each change starts a fresh panel; reopening the panel is not an identity change.
+- Return `null` from `getRequesterPass` while nobody is signed in. At mount a rejection also counts as signed out; during a session it shows Retry or the expired session, which keeps a half-written request.
+- Signing in tears down Sales and forgets the tab's Visitor session, so the anonymous transcript is never shown to the Requester or attached to a request, and does not come back after signing out.
+- Signing out, a new `contextKey`, a renewed pass that names another account, or `getRequesterPass` returning `null` destroys all Support state: chat, drafts, requests and unread count. When the tab becomes visible again the Widget asks for a pass once more, so a sign-out or account switch in another tab reaches it.
+- Sales requests never carry `X-Andy-Requester`, and Support requests never carry a Sales session.
 
-## Advanced exports
+`mode='support'` is a deprecated alias for `support` without `agentId`, and logs one notice.
 
-The package also exports `useAndyChat`, individual presentation components, its public TypeScript
-types, design tokens, `getApiBaseUrl`, and `setApiBaseUrl`. `Andy` remains a compatibility alias
-for `AndyChat`; new integrations should use `AndyChat`.
+The pass remains in memory and is sent only in `X-Andy-Requester`. Expired/unknown-key refusals renew once; other failures stop inside the panel. `apiBaseUrl` may explicitly select the reviewed Andy API origin; normal production defaults to Andy.
 
-## Supported integration path
+Provider branding and links, greeting/questions and reply promise come from Andy. When the host `lang` differs from the Agent default language, Support uses a localized default greeting and omits the Agent’s untranslated suggested questions. Existing conversation messages keep their original language. There is no `embedId`, visitor identity form or Sales action in this mode. The panel is the 3.x `<andy-chat>` shell in Support Mode: Chat and Mis solicitudes tabs with an unread count, the team form as a sheet over the chat, the receipt as a card in the thread, and each request's public human thread with Reply, Reabrir and Es otro problema. Sending the team form consents to attach the frozen conversation; its retry preserves the request key and receipt. When Andy's AI allowance is spent, the chat says so and offers Talk to the team. It follows the system light or dark theme and fills phones. `orientation` picks the Launcher's side; `tooltip` is ignored (the 3.x Launcher has none). Plain HTML hosts get the same Widget through the browser bundle's `window.AndyChat.configure` (see `andy-widget-vanilla`).
 
-Use the React package directly. Do not use an iframe, a floating `@latest` dependency, or Andy's
-legacy hosted `/widget.js` redirect for new integrations.
+The panel captures its displayed `lang` on the first consented open as the ticket's Reply Email preference. A retry keeps that original choice even if the host changes language. This copy preference never enters the signed pass or provider configuration.
 
-## License
+To handle a Reply Email link, pass the host URL's ticket parameter as `support.ticketId` after normal host sign-in. The widget opens that request only after Andy authorizes the current Requester/company. On another company or user, keep changing `contextKey`; on sign-out, unmount. Never supply an old pass as URL data.
 
-MIT
+The human thread follows replies and status changes without a page reload. Private polling runs every three seconds while subscribed and pauses in hidden documents. The launcher and My requests show unread replies. Opening a visible thread marks only its displayed public entries seen; closing it preserves unread replies. Resolved requests offer Reopen with a message for the same problem, or This is another problem for a fresh consented request. Reply and reopen retries retain their original body and request key.
 
+## Exports
 
-To handle a Reply Email link, pass the host URL's ticket parameter as `support.ticketId` after normal host sign-in. The widget opens that request only after Andy authorizes the current Requester/company. On another company or user, keep changing `contextKey`; on sign-out, unmount. Never supply an old pass as URL data.
+`AndyChat` (also the default export, and `Andy` as a compatibility alias), its prop types
+(`AndyChatProps`, `SalesAndyChatProps`, `SupportAndyChatProps`, `PredefinedQuestion`), and `getApiBaseUrl`
+and `setApiBaseUrl`. For the element itself, its config normalizer and string table, use `andy-widget-core`.
 
-The human thread follows replies and status changes without a page reload. Private polling runs every three seconds while subscribed and pauses in hidden documents. The launcher and My requests show unread replies. Opening a visible thread marks only its displayed public entries seen; closing it preserves unread replies. Resolved requests offer Reopen with a message for the same problem, or This is another problem for a fresh consented request. Reply and reopen retries retain their original body and request key.
+## License
 
-Custom presentations also use `controller.reply(body, reopen?)`, `newProblem()` and `refresh()`. Call `setVisible(false)` when a displayed thread is closed or hidden, and `setVisible(true)` when it is being read. Subscription disposal stops automatic refresh. The controller's `unreadCount`, Ticket sequence marks and public entries carry the same behavior as the mounted panel.
+MIT