@smooai/chat-widget 0.11.0 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smooai/chat-widget",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Embeddable AI chat as a framework-light web component — the Aurora Glass design, streaming replies, grounded sources, and per-brand theming. Speaks the smooth-operator WebSocket protocol.",
   "license": "MIT",
   "author": "SmooAI",
@@ -58,7 +58,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@smooai/smooth-operator": "^1.8.0",
+    "@smooai/smooth-operator": "^1.21.1",
     "libphonenumber-js": "^1.13.7",
     "zustand": "^5.0.14"
   },

package/src/conversation.ts

@@ -93,6 +93,9 @@ export type ConnectionStatus = 'idle' | 'connecting' | 'ready' | 'error' | 'clos
  *   Resume with {@link ConversationController.verifyOtp}.
  * - `confirm` — the agent wants to run a state-mutating tool and needs approval.
  *   Resume with {@link ConversationController.confirmTool}.
+ * - `interaction` — the agent raised a Rich Interaction (structured card, e.g.
+ *   identity intake). Resume with {@link ConversationController.submitInteraction}
+ *   or {@link ConversationController.declineInteraction}.
  */
 export type Interrupt =
     | {
@@ -106,7 +109,28 @@ export type Interrupt =
           error?: string;
           attemptsRemaining?: number;
       }
-    | { kind: 'confirm'; toolId?: string; actionDescription?: string };
+    | { kind: 'confirm'; toolId?: string; actionDescription?: string }
+    | {
+          kind: 'interaction';
+          /** Server-generated interaction instance id (echoed on submit). */
+          interactionId: string;
+          /** The Rich Interaction kind (e.g. `identity_intake`) — selects the card. */
+          interactionKind: string;
+          /** Kind-specific render spec (identity_intake: `{ fields: [...] }`). */
+          spec: Record<string, unknown>;
+          /** Why the agent raised it (card header copy). */
+          reason?: string;
+          /** Per-field server-side validation errors (from `interaction_invalid`). */
+          errors?: { field: string; message: string }[];
+      };
+
+/**
+ * The Rich-Interaction render capabilities this widget declares at session
+ * create (`supports`). Must stay aligned with the card registry in
+ * `element.ts` (`INTERACTION_CARDS`) — registering a card IS declaring its
+ * capability; a test asserts the two match.
+ */
+export const SUPPORTED_INTERACTION_CAPABILITIES: readonly string[] = ['identity_form'];
 
 export interface UserInfo {
     name?: string;
@@ -232,6 +256,9 @@ export class ConversationController {
     /** requestId of the in-flight turn — used to resume OTP / tool confirmations. */
     private activeRequestId: string | null = null;
     private interrupt: Interrupt | null = null;
+    /** Values from the last interaction submit, merged into the persisted
+     *  identity (identity_intake only) once the server acks them. */
+    private pendingInteractionValues: { kind: string; values: Record<string, unknown> } | null = null;
     private identityRestore: IdentityRestore = { phase: 'idle' };
     /**
      * True once the resume probe (persisted-pointer get_session OR the
@@ -337,6 +364,41 @@ export class ConversationController {
         this.setInterrupt(null);
     }
 
+    /**
+     * Submit a Rich Interaction card to resume the parked turn. The server
+     * routes to the kind's validator: invalid values come back as an
+     * `interaction_invalid` event (the card re-renders with per-field errors —
+     * the turn stays parked); a valid submit is acked and the turn resumes.
+     * No-op if not awaiting an interaction.
+     */
+    submitInteraction(values: Record<string, unknown>): void {
+        if (!this.client || !this.sessionId || !this.activeRequestId || this.interrupt?.kind !== 'interaction') return;
+        // Stash the values so the ack (immediate_response) can merge accepted
+        // identity values into the persisted store.
+        this.pendingInteractionValues = { kind: this.interrupt.interactionKind, values };
+        this.client.submitInteraction({
+            sessionId: this.sessionId,
+            requestId: this.activeRequestId,
+            interactionId: this.interrupt.interactionId,
+            kind: this.interrupt.interactionKind,
+            values,
+        });
+    }
+
+    /** Decline the pending Rich Interaction; the agent continues without it. */
+    declineInteraction(): void {
+        if (!this.client || !this.sessionId || !this.activeRequestId || this.interrupt?.kind !== 'interaction') return;
+        this.client.submitInteraction({
+            sessionId: this.sessionId,
+            requestId: this.activeRequestId,
+            interactionId: this.interrupt.interactionId,
+            kind: this.interrupt.interactionKind,
+            declined: true,
+        });
+        this.pendingInteractionValues = null;
+        this.setInterrupt(null);
+    }
+
     private nextId(prefix: string): string {
         this.seq += 1;
         return `${prefix}-${this.seq}-${Date.now().toString(36)}`;
@@ -543,6 +605,10 @@ export class ConversationController {
             userName: state.identity.name,
             userEmail: state.identity.email,
             browserFingerprint: this.fingerprint(),
+            // Declare the Rich-Interaction cards this widget can render (derived
+            // from the card registry), so the server emits `interaction_required`
+            // for those kinds instead of the conversational fallback.
+            supports: [...SUPPORTED_INTERACTION_CAPABILITIES],
             ...(metadata ? { metadata } : {}),
         });
         this.sessionId = session.sessionId;
@@ -700,7 +766,51 @@ export class ConversationController {
             case 'write_confirmation_required':
                 this.setInterrupt({ kind: 'confirm', toolId: str(inner.toolId), actionDescription: str(inner.actionDescription) });
                 break;
-            default:
+            case 'interaction_required': {
+                const interactionId = str(inner.interactionId);
+                const kind = str(inner.kind);
+                const spec = inner.spec && typeof inner.spec === 'object' ? (inner.spec as Record<string, unknown>) : {};
+                if (!interactionId || !kind) break; // not renderable — ignore
+                this.pendingInteractionValues = null;
+                this.setInterrupt({
+                    kind: 'interaction',
+                    interactionId,
+                    interactionKind: kind,
+                    spec,
+                    reason: str(inner.reason),
+                });
+                break;
+            }
+            case 'interaction_invalid':
+                if (this.interrupt?.kind === 'interaction' && this.interrupt.interactionId === str(inner.interactionId)) {
+                    const errors: { field: string; message: string }[] = [];
+                    if (Array.isArray(inner.errors)) {
+                        for (const e of inner.errors) {
+                            if (!e || typeof e !== 'object') continue;
+                            const o = e as Record<string, unknown>;
+                            const field = str(o.field);
+                            if (field) errors.push({ field, message: str(o.message) ?? 'Invalid value' });
+                        }
+                    }
+                    this.pendingInteractionValues = null;
+                    this.setInterrupt({ ...this.interrupt, errors });
+                }
+                break;
+            case 'immediate_response':
+                // Mid-turn immediate_response while an interaction card is showing
+                // is the submit/decline ack: the park resolved — clear the card
+                // and, for accepted identity values, persist them.
+                if (this.interrupt?.kind === 'interaction') {
+                    const pending = this.pendingInteractionValues;
+                    if (pending && pending.kind === 'identity_intake') {
+                        const v = pending.values as { name?: string; email?: string; phone?: string };
+                        this.store.getState().mergeIdentity({ name: v.name, email: v.email, phone: v.phone });
+                    }
+                    this.pendingInteractionValues = null;
+                    this.setInterrupt(null);
+                }
+                break;
+                        default:
                 break;
         }
     }

package/src/element.ts

@@ -17,7 +17,7 @@
 import { AsYouType, isValidPhoneNumber, parsePhoneNumber } from 'libphonenumber-js/min';
 import type { ChatWidgetConfig, ChatWidgetMode, ChatWidgetTheme } from './config.js';
 import { needsUserInfo, resolveConfig } from './config.js';
-import { type ChatMessage, type Citation, type ConnectionStatus, ConversationController, type IdentityRestore, type Interrupt } from './conversation.js';
+import { type ChatMessage, type Citation, type ConnectionStatus, ConversationController, type IdentityRestore, type Interrupt, SUPPORTED_INTERACTION_CAPABILITIES } from './conversation.js';
 import { SMOOTH_ICON_SVG } from './logo.js';
 import { cleanCitationSnippet, escapeHtml, renderMarkdown, safeHttpUrl } from './markdown.js';
 import { buildStyles } from './styles.js';
@@ -71,10 +71,166 @@ const ICON = {
     chev: `<svg width="11" height="11" viewBox="0 0 24 24" fill="none"><path d="m9 6 6 6-6 6" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"/></svg>`,
     /** OTP interrupt — a padlock. */
     lock: `<svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg"><rect x="5" y="10.5" width="14" height="9.5" rx="2.2" stroke="currentColor" stroke-width="1.7"/><path d="M8 10.5V8a4 4 0 0 1 8 0v2.5" stroke="currentColor" stroke-width="1.7"/></svg>`,
+    /** Identity-intake interrupt — a person. */
+    user: `<svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg"><circle cx="12" cy="8.2" r="3.4" stroke="currentColor" stroke-width="1.7"/><path d="M5.5 19.5c.8-3.1 3.4-4.8 6.5-4.8s5.7 1.7 6.5 4.8" stroke="currentColor" stroke-width="1.7" stroke-linecap="round"/></svg>`,
     /** Tool-confirmation interrupt — a shield. */
     shield: `<svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M12 3 5 6v5c0 4.4 3 7.2 7 8.5 4-1.3 7-4.1 7-8.5V6l-7-3Z" stroke="currentColor" stroke-width="1.7" stroke-linejoin="round"/><path d="m9 11.5 2 2 4-4" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round"/></svg>`,
 } as const;
 
+/**
+ * The Rich Interactions **card registry**: interaction kind → overlay card.
+ * `interaction_required { kind }` looks its card up here; registering a card IS
+ * declaring the widget's render capability for that kind (see
+ * `SUPPORTED_INTERACTION_CAPABILITIES` in conversation.ts — a test keeps the
+ * two aligned). Adding a kind = one card builder + one entry.
+ *
+ * The existing OTP and tool-approval overlays are prior instances of this same
+ * shape and should retrofit onto this registry later (their wire events predate
+ * the pattern).
+ */
+export interface InteractionCardContext {
+    /** Submit kind-shaped values (resumes the parked turn; server validates). */
+    submit: (values: Record<string, unknown>) => void;
+    /** Decline the interaction (the agent continues without it). */
+    decline: () => void;
+    /** Persisted visitor identity, for pre-filling known fields. */
+    prefill: { name?: string; email?: string; phone?: string };
+    /** Wire live phone formatting + validity hint onto a form's phone input. */
+    wirePhoneField: (form: HTMLFormElement) => void;
+}
+
+export interface InteractionCard {
+    /** The render capability this card provides (goes into `supports`). */
+    capability: string;
+    /** Card header title. */
+    title: string;
+    /** Static, trusted header icon SVG. */
+    icon: string;
+    /** Build the card body for an `interaction` interrupt. */
+    build: (it: Extract<Interrupt, { kind: 'interaction' }>, ctx: InteractionCardContext) => HTMLElement;
+}
+
+/**
+ * The identity_intake card: the fields the agent requested (pre-chat form field
+ * pattern — same classes, same phone formatting), per-field server errors, a
+ * submit and a decline affordance. Server-supplied text (reason, labels, error
+ * messages) is set via `textContent` — never innerHTML.
+ */
+function buildIdentityIntakeCard(it: Extract<Interrupt, { kind: 'interaction' }>, ctx: InteractionCardContext): HTMLElement {
+    const form = document.createElement('form');
+    form.className = 'int-form';
+    form.noValidate = true;
+
+    if (it.reason) {
+        const desc = document.createElement('div');
+        desc.className = 'int-desc';
+        desc.textContent = it.reason;
+        form.appendChild(desc);
+    }
+
+    const DEFAULTS: Record<string, { label: string; type: string; autocomplete: string }> = {
+        name: { label: 'Name', type: 'text', autocomplete: 'name' },
+        email: { label: 'Email', type: 'email', autocomplete: 'email' },
+        phone: { label: 'Phone', type: 'tel', autocomplete: 'tel' },
+    };
+
+    // Parse the kind's spec defensively: `{ fields: [{ key, required, label? }] }`.
+    const rawFields = Array.isArray(it.spec.fields) ? it.spec.fields : [];
+    const fields: { key: 'name' | 'email' | 'phone'; required: boolean; label?: string }[] = [];
+    for (const f of rawFields) {
+        if (!f || typeof f !== 'object') continue;
+        const o = f as Record<string, unknown>;
+        const key = typeof o.key === 'string' ? o.key : '';
+        if (key !== 'name' && key !== 'email' && key !== 'phone') continue;
+        fields.push({ key, required: o.required === true, label: typeof o.label === 'string' ? o.label : undefined });
+    }
+    if (fields.length === 0) fields.push({ key: 'email', required: true });
+
+    for (const f of fields) {
+        const d = DEFAULTS[f.key]!;
+        const label = document.createElement('label');
+        label.className = 'pc-field';
+        const caption = document.createElement('span');
+        caption.textContent = f.label ?? d.label;
+        const input = document.createElement('input');
+        input.name = f.key;
+        input.type = d.type;
+        input.setAttribute('autocomplete', d.autocomplete);
+        input.required = f.required;
+        const prefill = ctx.prefill[f.key];
+        if (prefill) input.value = prefill;
+        label.append(caption, input);
+        if (f.key === 'phone') {
+            const hint = document.createElement('span');
+            hint.className = 'pc-hint';
+            hint.setAttribute('aria-live', 'polite');
+            label.appendChild(hint);
+        }
+        // Per-field server-side validation error (interaction_invalid).
+        const serverError = it.errors?.find((e) => e.field === f.key);
+        if (serverError) {
+            label.classList.add('invalid');
+            const err = document.createElement('span');
+            err.className = 'int-error';
+            err.textContent = serverError.message;
+            label.appendChild(err);
+        }
+        form.appendChild(label);
+    }
+
+    const row = document.createElement('div');
+    row.className = 'int-row';
+    const decline = document.createElement('button');
+    decline.className = 'int-btn';
+    decline.type = 'button';
+    decline.textContent = 'No thanks';
+    decline.addEventListener('click', () => ctx.decline());
+    const share = document.createElement('button');
+    share.className = 'int-btn primary';
+    share.type = 'submit';
+    share.textContent = 'Share details';
+    row.append(decline, share);
+    form.appendChild(row);
+
+    form.addEventListener('submit', (ev) => {
+        ev.preventDefault();
+        if (!form.reportValidity()) return;
+        const data = new FormData(form);
+        const val = (k: string) => ((data.get(k) as string | null)?.trim() || undefined);
+
+        // Phone: mirror the pre-chat rules — block a required-but-invalid number,
+        // prefer canonical E.164 when it parses (the server re-validates anyway).
+        const rawPhone = val('phone');
+        const phoneInput = form.querySelector('input[name="phone"]') as HTMLInputElement | null;
+        if (rawPhone && phoneInput && !isValidPhoneNumber(rawPhone, PHONE_DEFAULT_REGION)) {
+            const field = phoneInput.closest('.pc-field');
+            field?.classList.add('invalid');
+            const hint = field?.querySelector('.pc-hint');
+            if (hint) hint.textContent = 'Enter a valid phone number';
+            if (phoneInput.hasAttribute('required')) {
+                phoneInput.focus();
+                return;
+            }
+        }
+        const phone = rawPhone ? (phoneToE164(rawPhone) ?? rawPhone) : undefined;
+        ctx.submit({ name: val('name'), email: val('email'), phone });
+    });
+    // Same live phone formatting + validity hint as the pre-chat form.
+    ctx.wirePhoneField(form);
+    queueMicrotask(() => (form.querySelector('input') as HTMLInputElement | null)?.focus());
+    return form;
+}
+
+/** Kind → card. See the registry doc above. */
+export const INTERACTION_CARDS: Record<string, InteractionCard> = {
+    identity_intake: {
+        capability: 'identity_form',
+        title: 'Share your details',
+        icon: ICON.user,
+        build: buildIdentityIntakeCard,
+    },
+};
+
 // `safeHttpUrl` / `escapeHtml` live in `./markdown.js` (the markdown renderer
 // needs them too); re-exported here for back-compat with existing importers.
 export { escapeHtml, safeHttpUrl } from './markdown.js';
@@ -480,21 +636,38 @@ export class SmoothAgentChatElement extends HTMLElement {
         head.className = 'int-head';
         const ico = document.createElement('span');
         ico.className = 'int-ico';
-        ico.innerHTML = it.kind === 'otp' ? ICON.lock : ICON.shield; // static, trusted
+        const card_meta = it.kind === 'interaction' ? INTERACTION_CARDS[it.interactionKind] : undefined;
+        if (it.kind === 'interaction' && !card_meta) {
+            // A kind we have no card for (shouldn't happen — we only declare
+            // capabilities for registered cards). Decline so the turn never hangs.
+            this.controller?.declineInteraction();
+            el.classList.add('hidden');
+            return;
+        }
+        ico.innerHTML = it.kind === 'otp' ? ICON.lock : it.kind === 'interaction' ? (card_meta?.icon ?? ICON.user) : ICON.shield; // static, trusted
         const title = document.createElement('span');
         title.className = 'int-title';
-        title.textContent = it.kind === 'otp' ? 'Verification required' : 'Confirm this action';
+        title.textContent = it.kind === 'otp' ? 'Verification required' : it.kind === 'interaction' ? (card_meta?.title ?? 'One more thing') : 'Confirm this action';
         head.append(ico, title);
         card.appendChild(head);
 
-        if (it.actionDescription) {
+        if (it.kind !== 'interaction' && it.actionDescription) {
             const desc = document.createElement('div');
             desc.className = 'int-desc';
             desc.textContent = it.actionDescription;
             card.appendChild(desc);
         }
 
-        if (it.kind === 'otp') {
+        if (it.kind === 'interaction') {
+            card.appendChild(
+                card_meta!.build(it, {
+                    submit: (values) => this.controller?.submitInteraction(values),
+                    decline: () => this.controller?.declineInteraction(),
+                    prefill: this.controller?.getStore().getState().identity ?? {},
+                    wirePhoneField: (form) => this.wirePhoneField(form),
+                }),
+            );
+        } else if (it.kind === 'otp') {
             if (it.sent?.maskedDestination) {
                 const sent = document.createElement('div');
                 sent.className = 'int-sent';

package/src/styles.ts

@@ -643,6 +643,9 @@ ${
     border-color: color-mix(in srgb, var(--sac-primary) 60%, transparent);
     box-shadow: 0 0 0 4px color-mix(in srgb, var(--sac-primary) 14%, transparent);
 }
+.int-form { display: flex; flex-direction: column; gap: 10px; margin-top: 10px; }
+.int-form .pc-field input { width: 100%; box-sizing: border-box; }
+.int-form .int-error { margin-top: 2px; }
 .int-btn {
     border: 1px solid color-mix(in srgb, var(--sac-border) 80%, transparent);
     background: var(--sac-surface-2);
@@ -662,8 +665,14 @@ ${
     color: var(--sac-primary-text);
     box-shadow: 0 6px 14px -6px color-mix(in srgb, var(--sac-primary) 65%, transparent);
 }
-.int-row .int-btn { flex: 1; }
-.int-row .int-input + .int-btn { flex: 0 0 auto; }
+.int-row .int-form { display: flex; flex-direction: column; gap: 10px; margin-top: 10px; }
+.int-form .pc-field input { width: 100%; box-sizing: border-box; }
+.int-form .int-error { margin-top: 2px; }
+.int-btn { flex: 1; }
+.int-row .int-input + .int-form { display: flex; flex-direction: column; gap: 10px; margin-top: 10px; }
+.int-form .pc-field input { width: 100%; box-sizing: border-box; }
+.int-form .int-error { margin-top: 2px; }
+.int-btn { flex: 0 0 auto; }
 .int-error { margin-top: 8px; font-size: 12px; color: #f87171; }
 .int-card { position: relative; }
 .int-close {