@paramms/chat-widget 1.0.40 → 1.0.42

package/README.md

@@ -8,7 +8,9 @@ Real-time embeddable chat widget for the Relay platform. Drop into any website w
 npm install @paramms/chat-widget
 ```
 
-## Quick start — CDN (no npm, no build)
+## Quick start — CDN, ESM `mount()` (no npm, no build, manual container)
+
+This is the ESM path — you control the mount point yourself. For a floating bubble on any site with zero JavaScript (or a config object), see [Script tag](#script-tag-any-website--plain-html-wordpress-shopify-phprailsdjangolaravel-or-literally-anything) below instead — it's usually simpler unless you specifically need to place the widget inline in your own container (`data-relay-*`/`Relay('boot', ...)` don't support choosing a container element; this ESM form does, via `el`).
 
 ```html
 <div id="chat"></div>
@@ -111,9 +113,157 @@ Prefer a floating bubble that opens the same app in a panel? `<ChatAppLauncher
 
 > **Multi-tenancy note:** conversations are created and keyed under the tenant the server resolves *from* `profileId` — guests can't spoof it. For **reading your own inbox**, `ChatApp`/`ChatAppLauncher` (and `useRelayChatList`/`mountChatList`/`GET /conversations/mine`) also accept a **`tenantId`** directly: it lists every conversation the user has with that business across all of its chatrooms, and is equally safe because the list is always self-scoped to the caller's own identity. `scope="tenant"` / `tenantId` never crosses into another business's data.
 
+## Script tag (any website — plain HTML, WordPress, Shopify, PHP/Rails/Django/Laravel, or literally anything)
+
+This is the path for every site that isn't React: one `<script>` tag, no build step, no framework. It works two ways — pick based on how much JavaScript you're willing to write:
+
+- **Zero-JavaScript** — `data-relay-*` attributes right on the `<script>` tag. This is the one that matters most for a plain-HTML site, a WordPress block, or a no-code builder, because it's the *only* option when there's no JavaScript on the page at all — a server template just fills in attribute values.
+- **Full config** — a JS object (`window.relaySettings = {...}` or `Relay('boot', {...})`, same shape either way). Needed the moment you want something an HTML attribute can't hold: a nested object, an array, a function, or changing the widget's identity *after* the page has loaded (e.g. once a visitor logs in).
+
+Both configure the exact same widget with the exact same field names as the React components above — `profileId`, `userName`/`userEmail`/`userAvatar`, `contextTitle`/`contextSubtitle`/`contextStatus` (or `listingTitle`/`listingMeta`/`listingPrice`/`listingStatus` for a marketplace-style card), `accent`, `launcher`, `position`, `launcherMessage`. If you already know the React props, you already know these.
+
+### Zero-JavaScript — `data-relay-*` attributes
+
+```html
+<script
+  async
+  src="https://relay.paramms.com/embed.js"
+  data-relay-app="YOUR_PROFILE_ID"
+  data-relay-user="user_123"
+  data-relay-user-name="Jane Doe"
+  data-relay-user-email="jane@example.com"
+  data-relay-accent="#4F63F5"
+  data-relay-position="bottom-right"
+></script>
+```
+
+Drop that before `</body>` and you have a working floating bubble — no other JavaScript needed anywhere on the page. Every attribute is optional except `data-relay-app`.
+
+| Attribute | Matches field | Notes |
+|---|---|---|
+| `data-relay-app` | `profileId` | **Required.** `data-relay-profile-id` works identically — same thing, matches the React prop name |
+| `data-relay-user` | `userId` | Unauthenticated stable id. Omit for an anonymous guest |
+| `data-relay-token` | `token` | Signed ES256 JWT — the production identity tier |
+| `data-relay-user-name` | `userName` | Shown to agents |
+| `data-relay-user-email` | `userEmail` | Shown to agents; also powers the offline email fallback |
+| `data-relay-user-avatar` | `userAvatar` | Shown to agents |
+| `data-relay-listing` | `listingId` | Sugar for `subjectId: "listing_<id>"` |
+| `data-relay-context-title` / `-subtitle` / `-status` | `contextTitle` / `contextSubtitle` / `contextStatus` | Context card (general — an order, ticket, booking) |
+| `data-relay-listing-title` / `-meta` / `-price` / `-status` | `listingTitle` / `listingMeta` / `listingPrice` / `listingStatus` | Marketplace card (a specific item — price + status badge). Use these OR the `context-*` set, both build the same card |
+| `data-relay-accent` | `accent` | Brand colour hex |
+| `data-relay-url` | `url` | Only needed for self-hosted Relay |
+| `data-relay-position` | `position` | `bottom-right` \| `bottom-left` |
+| `data-relay-launcher` | `launcher` | Set to `"false"` for an inline (non-floating) widget |
+| `data-relay-launcher-message` / `data-relay-launcher-subtitle` | `launcherMessage` | Two flat attributes combine into the teaser card — see note below |
+| `data-relay-target` | `el` | CSS selector for an existing element to mount into. Ignored in launcher mode |
+| `data-relay-height` | `height` | Inline container height. Ignored in launcher mode |
+| `data-relay-inbox` | `inbox` | `"true"` adds a back-chevron → full conversation list. Requires `data-relay-launcher="false"` — see the note below the table |
+| `data-relay-inbox-start` | `inboxStart` | `"true"` opens **directly on the conversation list** instead of a single thread — for a dedicated "Messages" page. Implies `inbox`. Requires `data-relay-launcher="false"` |
+| `data-relay-inbox-scope` | `inboxScope` | `tenant` (default) \| `profile` |
+| `data-relay-tenant-id` | `tenantId` | Your business id. Lists threads across **all** your chatrooms without naming one — use instead of `data-relay-app` on an inbox page |
+
+**What's NOT available as an attribute:** `user`/`subject` as nested objects, `quickReplies`, `i18n`, and `refreshToken` — an HTML attribute can only hold a string, so these need the JS-object form below. (`launcherMessage`'s two attributes are a workaround for exactly this: the React prop takes one `{ title, subtitle }` object, which an attribute can't express, so it's split into two flat attributes that get recombined.)
+
+**`inbox` requires `data-relay-launcher="false"`** — same limit React has (a launcher+inbox combination needs a different component there, `ChatAppLauncher`); with the default floating launcher, `data-relay-inbox` is silently ignored.
+
+**A whole "Messages" page, zero JavaScript.** `data-relay-inbox` alone only puts the list *behind* a back-chevron — the widget still lands on one thread, which is right for a product page and wrong for a page whose entire job is the inbox. `data-relay-inbox-start` makes the list the landing view, and `data-relay-tenant-id` spans every chatroom you run:
+
+```html
+<div id="relay-inbox" style="height:600px"></div>
+
+<script
+  async
+  src="https://relay.paramms.com/embed.js"
+  data-relay-tenant-id="acme"
+  data-relay-inbox-start="true"
+  data-relay-launcher="false"
+  data-relay-target="#relay-inbox"
+  data-relay-user="user_123"
+></script>
+```
+
+Tapping a row opens that conversation against **its own** chatroom; its back-chevron returns to the list. There's no ✕ in this mode — the list is the root view, so there'd be nothing behind it to close to. ✎ compose opens against your default chatroom (the server reports which). This is the script-tag equivalent of React's `<ChatApp tenantId={...} />`.
+
+### Full config — JS object
+
+Same field names, all in one place, same object whether it's set on page load or reacts to something happening later:
+
+```html
+<script async src="https://relay.paramms.com/embed.js"></script>
+<script>
+  window.relaySettings = {
+    profileId:        'YOUR_PROFILE_ID',   // required — your chatroom id
+    url:               undefined,          // optional — only for self-hosted Relay
+    apiUrl:            undefined,          // optional — only if REST lives on a different origin than the socket
+
+    token:             undefined,          // optional — signed ES256 JWT, production identity (wins over userId)
+    userId:            'user_123',         // optional — unauthenticated stable id; omit both → anonymous guest
+    refreshToken:      () => fetchNewToken(),  // optional — called when a signed token expires
+
+    userName:          'Jane Doe',              // optional — shown to agents, not identity
+    userEmail:         'jane@example.com',      // optional — also powers the offline email fallback
+    userAvatar:        'https://…/jane.png',    // optional
+    // or, if it's easier to build one object: user: { name, email, avatar }
+
+    subjectId:         undefined,          // optional — pins a dedicated thread; usually just use listingId below
+    listingId:         '4821',             // optional — sugar for subjectId: "listing_4821"
+    contextTitle:       'Order #4821',              // optional — context card title (general use)
+    contextSubtitle:    'Placed Mar 3 · $129.00',   // optional — context card subtitle
+    contextStatus:       'Shipped',                  // optional — status badge
+    // or, for a marketplace-style card: listingTitle / listingMeta / listingPrice / listingStatus
+    // or build the card yourself:        subject: { title, subtitle, tags, status }
+
+    accent:            '#4F63F5',           // optional — brand colour
+    launcher:           true,               // optional — floating bubble vs inline; default true
+    position:          'bottom-right',      // optional — 'bottom-right' | 'bottom-left'
+    launcherMessage:   { title: 'Questions? Chat with us', subtitle: 'Start a conversation' },  // optional — a bare string also works (title only)
+
+    quickReplies:      ['Track my order', 'Return an item'],   // optional — reply chips above the input
+    i18n:              { send: 'Enviar' },                      // optional — UI string overrides
+    translateLang:      undefined,          // optional — auto-translate incoming messages (ISO code)
+
+    // Inline placement (ignored in launcher mode — a floating bubble is a
+    // fixed popup mount() owns, not something placed at a point in the page):
+    el:                 '#chat',            // optional — CSS selector or element; omit → an auto-created host
+    height:             '600px',            // optional — inline container height
+    inbox:              false,              // optional — back-chevron → full conversation list (inline only, see below)
+    inboxScope:        'tenant',            // optional — 'tenant' (default, all your chatrooms) | 'profile' (this one only)
+  }
+</script>
+```
+
+`Relay('boot', {...})` (below) takes this exact same object — use whichever form fits how the page is built.
+
+**`inbox` matches React exactly, including its one limit:** it only works with `launcher: false`. A floating launcher bubble is a fixed-size popup the widget owns; React itself needs a *different* component (`ChatAppLauncher`) for a launcher-with-inbox experience, and the script-tag path draws the same line. With `inbox: true` and `launcher: false`, the widget's header shows a back-chevron; tapping it swaps to the full conversation list (reusing the same list engine the dashboard's own inbox runs on); tapping a row opens that conversation; a ✕ in the list view returns to this widget's original thread.
+
+### Commands — the same object, applied later
+
+For identity that arrives after the page loads (a visitor logs in), or SPA-style navigation between pages without a full reload, call `Relay(...)` directly instead of (or in addition to) setting `window.relaySettings`. Same field names as above — `Relay('boot'/'identify'/'update', {...})` all take a `RelaySettings` object, just at a different moment:
+
+```html
+<script async src="https://relay.paramms.com/embed.js"></script>
+<script>
+  Relay('boot', { profileId: 'YOUR_PROFILE_ID' })      // mount immediately, anonymous
+
+  // later, once the visitor logs in:
+  Relay('identify', { userId: currentUser.id, userName: currentUser.name })   // merges their guest history in
+
+  // on navigation to a different listing/order page:
+  Relay('update', { listingId: newListing.id, listingTitle: newListing.title })
+
+  // on logout:
+  Relay('shutdown')                                     // removes the widget + local session
+</script>
+```
+
+`Relay(...)` is queue-safe — calls made before `embed.js` finishes loading are never lost. `identify`/`update` merge onto whatever's currently running (a fresh `boot` replaces it entirely).
+
+**Network requirement:** if the host page sets a Content-Security-Policy, it must allow the relay connection — `connect-src https://api.paramms.com wss://api.paramms.com;` (both are separate origins to the browser; include both), or your self-hosted equivalent.
+
 ### Old section below (kept for reference)
 
 ```tsx
+
 'use client'
 import { ChatWidget } from '@paramms/chat-widget/react'
 
@@ -214,16 +364,7 @@ arrives automatically over the socket. Pass `launcherMessage` only to override
 the dashboard value for one embed (it also renders instantly, before the
 socket connects).
 
-Script-tag embeds use data attributes:
-
-```html
-<script
-  src="https://relay.paramms.com/embed.js"
-  data-relay-app="YOUR_PROFILE_ID"
-  data-relay-launcher-message="Questions? Chat with us"
-  data-relay-launcher-subtitle="Start a conversation"
-></script>
-```
+Script-tag embeds use `data-relay-launcher-message` / `data-relay-launcher-subtitle` (or the `launcherMessage: {title,subtitle}` object in JS-object form) — see the [Script tag](#script-tag-any-website--plain-html-wordpress-shopify-phprailsdjangolaravel-or-literally-anything) section above for the full reference.
 
 ## Internationalisation
 
@@ -234,12 +375,18 @@ Script-tag embeds use data attributes:
   i18n={{
     placeholder: 'Écrivez un message…',
     send:        'Envoyer',
-    offline:     'Nous sommes hors ligne pour l\'instant',
+    offline:     'Nous sommes absents pour le moment',   // the away notice
     poweredBy:   '',   // empty string hides the footer
   }}
 />
 ```
 
+`offline` is the fallback text for the **away notice** shown above the composer
+outside the chatroom's office hours. It never blocks anything: guests can always
+send, the message is delivered like any other, and an agent replies when they're
+back. The chatroom's own "offline message" (dashboard → *Widget message &
+availability*) takes precedence over this string.
+
 RTL is detected automatically for Arabic, Hebrew, Persian and Urdu browsers.
 
 ## All options
@@ -262,6 +409,8 @@ RTL is detected automatically for Arabic, Hebrew, Persian and Urdu browsers.
 | `i18n` | `I18nStrings` | English | UI string overrides |
 | `inbox` | `boolean` | `false` | Add a ‹ back in the chatroom header that opens the full `ChatApp` conversation list (inline widgets only) |
 | `inboxScope` | `'tenant' \| 'profile'` | `'tenant'` | With `inbox`: list threads across all chatrooms (`tenant`) or just this one (`profile`) |
+| `inboxStart` | `boolean` | `false` | Land ON the conversation list instead of a single thread (a dedicated "Messages" page). Implies `inbox`; requires `launcher: false`. Script-tag/embed only — in React use `<ChatApp/>` directly |
+| `tenantId` | `string` | — | Script-tag/embed only. Your business id: lists threads across ALL your chatrooms with no chatroom named. Only meaningful with `inboxStart` — a single thread still needs a `profileId` |
 
 ## Development
 

package/dist/connection.d.ts

@@ -43,11 +43,24 @@ export declare class ConnectionManager {
      *  The outbox is bounded so a prolonged outage can't grow memory without limit
      *  — oldest queued frames are dropped past the cap. */
     send(frame: ClientFrame): void;
+    /** How many frames are waiting to go out. Useful for a host that wants to
+     *  show "message pending" state, and for asserting the outbox stays bounded. */
+    pendingCount(): number;
     close(): void;
     private handle;
     private refreshing;
     private fatal;
+    /** Release queued frames. When called from 'opened' we know the canonical
+     *  conversation id the server just resolved us to, and queued `send` frames
+     *  are retargeted to it. A manager only ever opens ONE conversation (its
+     *  `opts.open`), so every queued send belongs to that thread by
+     *  construction — but the id it was queued with can be STALE (queued against
+     *  the previous session's conversation before a reconnect). Retargeting is a
+     *  no-op in the normal case and rescues the message in the stale one. */
     private flush;
+    /** Bounded enqueue — the cap lives here so EVERY path that queues respects
+     *  it (a failed `raw` used to push straight onto the array, bypassing it). */
+    private queue;
     private raw;
     private onClosed;
 }

package/dist/embed.d.ts

@@ -1,9 +1,19 @@
-/** Everything an embedder can pass. All optional except `appId`. Names are
- *  intentionally plain — no knowledge of the widget internals required. */
+import { type MountOptions, type UserInfo } from './index.js';
+/** Everything an embedder can pass. All optional except `profileId`. Field
+ *  names DELIBERATELY mirror the React props (`ChatWidgetProps` /
+ *  `MarketplaceChatProps` in react.tsx) so the same mental model — and often
+ *  the same field names — carries over whether you're using React or a plain
+ *  script tag. Where a name changed over time the old one still works (see
+ *  the `@deprecated` notes) — this is a published package embedded on live
+ *  customer sites (WordPress plugin, Shopify theme block), so nothing here is
+ *  ever removed, only added to. */
 export interface RelaySettings {
-    /** The chatroom id (from your Relay dashboard). Required. `profileId` is an alias. */
-    appId?: string;
+    /** The chatroom id (from your Relay dashboard). Required. Matches the React
+     *  `profileId` prop name. `appId` is the original alias — still works. */
     profileId?: string;
+    /** @deprecated alias for `profileId` — kept working, `profileId` is now the
+     *  documented name (matches React). */
+    appId?: string;
     /** Relay server URL. Defaults to the hosted relay; set for self-hosted. */
     url?: string;
     apiUrl?: string;
@@ -12,27 +22,139 @@ export interface RelaySettings {
      *  both for an anonymous visitor. See EMBED.md. */
     token?: string;
     userId?: string;
-    /** Display info shown to agents (not identity). */
+    /** Called when a signed `token` is rejected (expired): return a fresh token
+     *  from your backend to renew the session without a reload. Matches the
+     *  React `refreshToken` prop. Only usable from `window.relaySettings` /
+     *  `Relay('boot', ...)` (a function can't be expressed as an HTML
+     *  attribute) — not available via `data-relay-*`. */
+    refreshToken?: () => Promise<string | null>;
+    /** Display info shown to agents (not identity) — matches the React
+     *  `userName` / `userEmail` / `userAvatar` props. */
+    userName?: string;
+    userEmail?: string;
+    userAvatar?: string;
+    /** @deprecated flat aliases for `userName` / `userEmail` / `userAvatar` —
+     *  kept working (the shipped Shopify integration used these names nested
+     *  under `user`, see `user` below, which is the fix for that; these bare
+     *  top-level fields predate that and still work standalone). */
     name?: string;
     email?: string;
     avatar?: string;
-    /** Subject the chat is about (e.g. a marketplace listing). `listingId` is sugar
-     *  for `subjectId: "listing_<id>"`. */
+    /** Same info as `userName`/`userEmail`/`userAvatar`, as one nested object —
+     *  matches `MountOptions.user` / React's internal shape exactly, and is
+     *  what a server-rendered snippet (e.g. Shopify Liquid, WordPress PHP) will
+     *  most naturally emit: `user: { name: "...", email: "..." }`. Takes
+     *  precedence over the flat fields if both are somehow given. */
+    user?: UserInfo;
+    /** Subject the chat is about (e.g. a marketplace listing). `listingId` is
+     *  sugar for `subjectId: "listing_<id>"`. */
     subjectId?: string;
     listingId?: string;
+    /** Context-card fields — matches React's `ChatWidget` `contextTitle` /
+     *  `contextSubtitle` / `contextStatus` props (a general "here's what this
+     *  conversation is about" card: an order, ticket, booking, etc). */
+    contextTitle?: string;
+    contextSubtitle?: string;
+    contextStatus?: string;
+    /** Marketplace-card fields — matches React's `MarketplaceChat`
+     *  `listingTitle` / `listingMeta` / `listingPrice` / `listingStatus` props
+     *  (a specific-item card: price + status badge, e.g. "2019 Camry — $12,500
+     *  — Available"). Use these OR `contextTitle`/etc — both build the same
+     *  card, pick whichever vocabulary matches your use case. */
+    listingTitle?: string;
+    listingMeta?: string;
+    listingPrice?: number;
+    listingStatus?: string;
+    /** @deprecated original flat names for the context/marketplace card —
+     *  kept working. `contextTitle`/`listingTitle` are now the documented
+     *  names (matching the two React components). */
     subjectTitle?: string;
     subjectMeta?: string;
     subjectPrice?: number;
     subjectStatus?: string;
+    /** The context/marketplace card as one nested object, if you'd rather build
+     *  it yourself than use the flat fields above — matches
+     *  `MountOptions.subject` exactly. Takes precedence over every flat field
+     *  above if given. */
+    subject?: {
+        title?: string;
+        subtitle?: string;
+        tags?: string[];
+        status?: string;
+        ownerLabel?: string;
+    };
+    /** Pre-set reply chips shown above the input — matches the React
+     *  `quickReplies` prop. `window.relaySettings` / `Relay('boot', ...)` only
+     *  (an array can't be expressed as a single `data-relay-*` attribute). */
+    quickReplies?: string[];
+    /** i18n string overrides — matches the React `i18n` prop. Same restriction
+     *  as `quickReplies`: object, so JS-object form only. */
+    i18n?: MountOptions['i18n'];
     /** Appearance. `launcher` defaults to true (a floating bubble). */
     accent?: string;
     launcher?: boolean;
     position?: 'bottom-right' | 'bottom-left';
-    /** Launcher teaser ("optional message" above the bubble). Title, or
-     *  title + subtitle. Omit to use the chatroom's manifest value. */
-    launcherMessage?: string;
+    /** Launcher teaser ("optional message" above the bubble). Matches the React
+     *  `launcherMessage` prop exactly: a bare string (title only), or
+     *  `{ title, subtitle }`. `launcherSubtitle` below is a SEPARATE flat
+     *  field kept only so `data-relay-launcher-message` /
+     *  `data-relay-launcher-subtitle` (two HTML attributes — an attribute
+     *  can't hold a nested object) can still combine into the same shape; in
+     *  JS-object form just pass the object directly, same as React. Omit to
+     *  use the chatroom's manifest value. */
+    launcherMessage?: string | {
+        title: string;
+        subtitle?: string;
+    };
+    /** @deprecated HTML-attribute-only companion to a string `launcherMessage`
+     *  — see the note above. Prefer `launcherMessage: { title, subtitle }` in
+     *  JS-object form. */
     launcherSubtitle?: string;
     translateLang?: string;
+    /** Mount INLINE into an existing element instead of the auto-created,
+     *  body-appended host that the default floating launcher uses. A CSS
+     *  selector string (works from `data-relay-target` too) or an element
+     *  reference (JS-object form only). Ignored when `launcher` is true — same
+     *  restriction as `height`/`inbox` below: a floating launcher panel is a
+     *  fixed-size popup `mount()` owns, not something you place in the page. */
+    el?: string | HTMLElement;
+    /** Inline container height — matches the React `height` prop. Only applies
+     *  when `launcher` is false/omitted. */
+    height?: string;
+    /** Adds a back-chevron to the widget that swaps it for the full
+     *  conversation list — matches the React `ChatWidget`/`MarketplaceChat`
+     *  `inbox` prop, INCLUDING its one limitation: not supported in launcher
+     *  mode. (React itself requires a different component, `ChatAppLauncher`,
+     *  for a launcher+inbox combination — same scope boundary here.) Tapping a
+     *  row opens that conversation; its own back-chevron returns to the list; a
+     *  ✕ in the list view returns to this widget's original single-thread
+     *  view. Requires `launcher: false`. */
+    inbox?: boolean;
+    /** Open DIRECTLY on the conversation list instead of a single thread —
+     *  what you want for a dedicated "Messages" page. `inbox: true` alone only
+     *  adds a back-chevron to a single thread, so the list is reachable but
+     *  never the landing view; that is the right default for a widget bolted
+     *  onto a product page, and the wrong one for a page whose whole job is the
+     *  inbox. Implies `inbox`. Requires `launcher: false` (same restriction as
+     *  `inbox`), and `profileId` OR `tenantId`.
+     *
+     *  With `inboxStart`, tapping a row opens that conversation and its own
+     *  back-chevron returns to the list. There is no ✕ — the list IS the root
+     *  view here, so there is nothing behind it to close back to. */
+    inboxStart?: boolean;
+    /** Inbox scope when `inbox` is set: `'tenant'` (default) lists the user's
+     *  threads across ALL your chatrooms; `'profile'` limits it to this one. */
+    inboxScope?: 'tenant' | 'profile';
+    /** Your business id — lists the visitor's threads across ALL your chatrooms
+     *  without naming one, and lets "new conversation" open against your default
+     *  chatroom (the server reports it). This is the vanilla equivalent of
+     *  React's `<ChatApp tenantId=… />`, which has always accepted a tenant with
+     *  no profile; the script tag previously could not express that at all and
+     *  hard-required a `profileId`.
+     *
+     *  Only meaningful with `inboxStart` — a single-thread widget still needs a
+     *  `profileId`, because a lone thread has to belong to a specific chatroom. */
+    tenantId?: string;
 }
 export type RelayCommand = 'boot' | 'update' | 'identify' | 'shutdown';
 /** The public command dispatcher exposed as `window.Relay`. */