andy-widget-react 2.2.0 → 2.3.0

package/README.md

@@ -8,7 +8,7 @@ The official React Widget for Andy. Its canonical source is
 Pin an exact reviewed release:
 
 ```bash
-bun add andy-widget-react@2.0.5
+bun add andy-widget-react@2.2.1
 ```
 
 React and React DOM 18 or 19 are required peer dependencies.
@@ -65,6 +65,34 @@ capture are disabled in this release because there is no durable public submissi
 This release intentionally has no Widget analytics or event callback API. Use Andy's existing
 conversation analytics rather than observing the Shadow DOM.
 
+## 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.
+
+```tsx
+<AndyChat
+  mode='support'
+  lang='es'
+  support={{
+    installationId: hostInstallationId,
+    contextKey: `${signedInUserId}:${selectedCompanyId}`,
+    getRequesterPass: async () => {
+      const response = await fetch('/api/andy/requester-pass', { cache: 'no-store' })
+      if (!response.ok) throw new Error('Support authentication unavailable')
+      return (await response.json()).pass
+    }
+  }}
+/>
+```
+
+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. 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.
+
+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.
+
 ## Advanced exports
 
 The package also exports `useAndyChat`, individual presentation components, its public TypeScript
@@ -79,3 +107,10 @@ legacy hosted `/widget.js` redirect for new integrations.
 ## License
 
 MIT
+
+
+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.
+
+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.
+
+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.