@agentforge-io/chat-sdk 2.0.19 → 2.0.21

package/dist/entities.d.ts

@@ -19,25 +19,39 @@ export type ChatRole = 'user' | 'assistant' | 'system';
  * Future kinds extend this union without breaking back-compat: the
  * View checks `kind` and falls back to plain text when it's unknown.
  */
+export interface ChatApprovalCopy {
+    title: string;
+    body: string;
+    approveLabel: string;
+    approveBusyLabel: string;
+    denyLabel: string;
+    denyBusyLabel: string;
+    approvedPill: string;
+    deniedPill: string;
+    readOnlyHint: string;
+    blockedTitle: string;
+    blockedBody: string;
+    expiresPrefix: string;
+}
 export type ChatMessageMetadata = {
     kind: 'awaiting_approval';
     approvalId: string;
     toolName: string;
     expiresAt: string;
-    /** Friendly connector display name surfaced by the server when
-     *  available (e.g. `'Granola'`). Lets the View render a
-     *  natural-language card without the host having to map slugs
-     *  to product names. */
     connectorName?: string;
-    /** First line of the tool's description from the connector
-     *  definition. Used as a one-line "what will happen" hint. */
     toolDescription?: string;
+    /** Server-authored microcopy for the approval bubble. Generated
+     *  on every pause by an AI copywriter on the backend so language
+     *  and tone match the live conversation. View layers render it
+     *  verbatim; when missing, fall back to a minimal meta render. */
+    copy?: ChatApprovalCopy;
 } | {
     kind: 'tool_blocked';
     toolName: string;
     reason?: string;
     connectorName?: string;
     toolDescription?: string;
+    copy?: ChatApprovalCopy;
 } | {
     kind: string;
     [k: string]: unknown;

package/dist/react.d.ts

@@ -18,57 +18,45 @@
 import { type CSSProperties } from 'react';
 import type { ChatTheme } from './entities';
 /**
- * Optional callback invoked when the visitor clicks the Approve/Deny
- * button on a tool-approval bubble. When omitted, the bubble renders
- * as a read-only "waiting" hint — the visitor can't decide from inside
- * the widget. When wired, the widget calls this with `{approvalId,
- * action}` and the host implementation typically POSTs to
- * `/public/chat/approvals/:id/{approve|deny}` with the visitor's
- * `browserSessionId` for ownership verification.
- *
- * Throwing or rejecting from the handler keeps the bubble in its
- * pending state and surfaces the error inline so the visitor can
- * retry.
+ * Optional observer fired after the SDK resolves a tool-approval bubble.
+ * The SDK owns the network call (it already has `apiBaseUrl` and the
+ * `browserSessionId`); the host only gets notified for analytics or
+ * audit logging. The hook is fire-and-forget — throwing from it does
+ * not roll back the decision the server already committed.
  */
-export type ApprovalActionHandler = (args: {
+export type ApprovalDecisionObserver = (args: {
     approvalId: string;
     action: 'approve' | 'deny';
-}) => Promise<void>;
+    ok: boolean;
+    error?: string;
+}) => void;
 /**
  * Localizable copy for the approval / blocked bubbles. Pass via the
  * `approvalCopy` prop on `<ChatWidget>` to drop the defaults (Spanish,
- * conversational) and tailor every line to your audience.
+ * Server-authored approval microcopy. The bubble renders whatever the
+ * server places in `metadata.copy` — title, body, button labels, etc.
+ * That copy is generated by the AgentForge backend on every pause via a
+ * dedicated Haiku call, so its language and tone always match the
+ * conversation the user is having. There is no client-side dictionary
+ * to keep in sync.
  *
- * Functions receive whatever context the server enriched the chunk
- * with — typically a friendly connector name like `'Granola'`. When
- * the server didn't supply it, the function is called with `undefined`
- * and the implementation should pick a sensible generic line. The
- * widget itself never references the raw tool slug in copy.
+ * The shape mirrors `ApprovalCopyBundle` in `@agentforge-io/core`.
  */
 export interface ApprovalCopy {
     title: string;
-    body: (ctx: {
-        connectorName?: string;
-        toolDescription?: string;
-    }) => string;
+    body: string;
     approveLabel: string;
     approveBusyLabel: string;
     denyLabel: string;
     denyBusyLabel: string;
     approvedPill: string;
     deniedPill: string;
-    /** Shown when the host didn't wire `onApprovalAction` — the visitor
-     *  can't decide from inside the widget so we tell them where to go. */
     readOnlyHint: string;
-    /** Used by the `expires in …` countdown. Receives minutes/seconds
-     *  and returns the formatted string. */
-    expiresIn: (mins: number, secs: number) => string;
-    /** Block bubble title + body. */
     blockedTitle: string;
-    blockedBody: (ctx: {
-        connectorName?: string;
-        reason?: string;
-    }) => string;
+    blockedBody: string;
+    /** Prefix shown before the countdown, e.g. "Expires in". The seconds
+     *  are appended client-side because they tick locally. */
+    expiresPrefix: string;
 }
 export interface ChatWidgetProps {
     /** Public chat token (`aft_*`) issued from the admin UI. */
@@ -92,17 +80,19 @@ export interface ChatWidgetProps {
     /** Inline style on the root container. */
     style?: CSSProperties;
     /**
-     * Handler for tool-approval bubble actions. See `ApprovalActionHandler`
-     * for the contract. Omit to render approval messages as read-only
-     * hints.
+     * Optional observer called after the SDK resolves an approval bubble.
+     * The SDK handles the network call internally — pass this only if you
+     * want to record the decision for analytics. See
+     * `ApprovalDecisionObserver`.
      */
-    onApprovalAction?: ApprovalActionHandler;
+    onApprovalDecision?: ApprovalDecisionObserver;
     /**
-     * Override any subset of the approval-card copy. Keys you don't
-     * provide fall back to the Spanish defaults in `DEFAULT_APPROVAL_COPY`.
-     * Use this for translations or to match your product's voice.
+     * When `false` (the default), the Approve/Deny buttons render on
+     * `awaiting_approval` bubbles. Set to `true` to render bubbles as
+     * read-only — useful for transcripts/embeds where the visitor cannot
+     * legitimately decide.
      */
-    approvalCopy?: Partial<ApprovalCopy>;
+    readOnlyApprovals?: boolean;
 }
 /**
  * Drop-in chat widget. Owns its own `ChatSession` and re-renders on every

package/dist/react.js

@@ -154,37 +154,34 @@ function renderMarkdown(src) {
     return out.join('');
 }
 /**
- * Defaults are Spanish + conversational. The host overrides individual
- * keys via the `approvalCopy` prop; unset keys keep these values.
+ * Minimal fallback used when the server didn't supply `metadata.copy`
+ * (older backend, copywriter timeout, missing API key, etc.). Intentionally
+ * terse and meta-only — the goal is to avoid lying about language. The
+ * server is the source of truth for natural copy.
  */
-const DEFAULT_APPROVAL_COPY = {
-    title: 'Necesito tu permiso',
-    body: ({ connectorName }) => connectorName
-        ? `¿Me das permiso para usar ${connectorName}?`
-        : '¿Me das permiso para continuar?',
-    approveLabel: 'Permitir',
-    approveBusyLabel: 'Permitiendo…',
-    denyLabel: 'No, gracias',
-    denyBusyLabel: 'Cancelando…',
-    approvedPill: 'Listo, continuando…',
-    deniedPill: 'Cancelado',
-    readOnlyHint: 'Pídele al administrador del workspace que lo apruebe.',
-    expiresIn: (m, s) => m >= 60
-        ? `Expira en ${Math.floor(m / 60)}h ${m % 60}m`
-        : `Expira en ${m}m ${s.toString().padStart(2, '0')}s`,
-    blockedTitle: 'No disponible',
-    blockedBody: ({ connectorName, reason }) => reason ??
-        (connectorName
-            ? `No puedo usar ${connectorName} en esta cuenta.`
-            : 'No puedo usar esa herramienta en esta cuenta.'),
-};
+function fallbackCopy(ctx) {
+    const target = ctx.connectorName ?? ctx.toolName ?? '';
+    return {
+        title: target || 'Permission required',
+        body: target ? `${target} →  ✓ / ✗` : 'Permission required',
+        approveLabel: '✓',
+        approveBusyLabel: '…',
+        denyLabel: '✗',
+        denyBusyLabel: '…',
+        approvedPill: '✓',
+        deniedPill: '✗',
+        readOnlyHint: '',
+        blockedTitle: target || 'Blocked',
+        blockedBody: ctx.reason ?? (target ? `${target} blocked` : 'Blocked'),
+        expiresPrefix: '⏱',
+    };
+}
 /**
  * Drop-in chat widget. Owns its own `ChatSession` and re-renders on every
  * SDK event. Consumers don't need to read `session.getState()` themselves.
  */
 function ChatWidget(props) {
-    const { token, apiBaseUrl, inline = false, position, browserSessionId, resumeConversationId, stream, className, style, onApprovalAction, approvalCopy, } = props;
-    const copy = { ...DEFAULT_APPROVAL_COPY, ...(approvalCopy ?? {}) };
+    const { token, apiBaseUrl, inline = false, position, browserSessionId, resumeConversationId, stream, className, style, onApprovalDecision, readOnlyApprovals = false, } = props;
     const [session, setSession] = (0, react_1.useState)(null);
     const [status, setStatus] = (0, react_1.useState)('idle');
     const [agent, setAgent] = (0, react_1.useState)();
@@ -304,7 +301,7 @@ function ChatWidget(props) {
     };
     return ((0, jsx_runtime_1.jsxs)("div", { className: rootClass, style: rootStyle, "data-style-id": styleId, children: [!inline && ((0, jsx_runtime_1.jsx)("button", { type: "button", className: "af-toggle", "aria-label": open ? 'Close chat' : 'Open chat', "aria-expanded": open, onClick: () => setOpen((v) => !v), children: open ? (0, jsx_runtime_1.jsx)(CloseIcon, {}) : (0, jsx_runtime_1.jsx)(ChatIcon, {}) })), (0, jsx_runtime_1.jsxs)("div", { className: `af-panel ${open ? 'af-open' : ''}`, children: [(0, jsx_runtime_1.jsxs)("div", { className: "af-header", children: [theme?.avatarUrl ? (
                             // eslint-disable-next-line @next/next/no-img-element
-                            (0, jsx_runtime_1.jsx)("img", { className: "af-header-avatar", src: theme.avatarUrl, alt: "" })) : null, (0, jsx_runtime_1.jsxs)("div", { className: "af-header-info", children: [(0, jsx_runtime_1.jsx)("div", { className: "af-header-title", children: theme?.title ?? agent?.name ?? 'Chat' }), (0, jsx_runtime_1.jsx)("div", { className: "af-header-subtitle", children: status === 'loading' ? 'Loading…' : agent?.description ?? '' })] }), !inline && ((0, jsx_runtime_1.jsx)("button", { type: "button", className: "af-close", onClick: () => setOpen(false), "aria-label": "Close chat", children: (0, jsx_runtime_1.jsx)(CloseIcon, {}) }))] }), (0, jsx_runtime_1.jsx)("div", { className: "af-messages", ref: messagesRef, children: messages.map((m) => ((0, jsx_runtime_1.jsx)(MessageBubble, { message: m, copy: copy, onApprovalAction: onApprovalAction, onContinue: () => {
+                            (0, jsx_runtime_1.jsx)("img", { className: "af-header-avatar", src: theme.avatarUrl, alt: "" })) : null, (0, jsx_runtime_1.jsxs)("div", { className: "af-header-info", children: [(0, jsx_runtime_1.jsx)("div", { className: "af-header-title", children: theme?.title ?? agent?.name ?? 'Chat' }), (0, jsx_runtime_1.jsx)("div", { className: "af-header-subtitle", children: status === 'loading' ? 'Loading…' : agent?.description ?? '' })] }), !inline && ((0, jsx_runtime_1.jsx)("button", { type: "button", className: "af-close", onClick: () => setOpen(false), "aria-label": "Close chat", children: (0, jsx_runtime_1.jsx)(CloseIcon, {}) }))] }), (0, jsx_runtime_1.jsx)("div", { className: "af-messages", ref: messagesRef, children: messages.map((m) => ((0, jsx_runtime_1.jsx)(MessageBubble, { message: m, session: session, readOnly: readOnlyApprovals, onDecision: onApprovalDecision, onContinue: () => {
                                 // After a successful Approve, kick the next turn so the
                                 // gate's fast-path consumes the approval and the tool
                                 // actually runs. `silent: true` keeps the literal
@@ -318,13 +315,13 @@ function ChatWidget(props) {
                                 }, 250);
                             } }, m.id))) }), lastError && status === 'error' && ((0, jsx_runtime_1.jsx)("div", { className: "af-error", children: lastError })), (0, jsx_runtime_1.jsxs)("div", { className: "af-input-row", children: [(0, jsx_runtime_1.jsx)("textarea", { className: "af-input", value: draft, onChange: (e) => setDraft(e.target.value), onKeyDown: onKeyDown, placeholder: "Type a message\u2026", rows: 1, disabled: status === 'ended' || status === 'loading' || status === 'idle' }), (0, jsx_runtime_1.jsx)("button", { type: "button", className: "af-send", onClick: handleSend, disabled: sendDisabled, "aria-label": "Send message", children: (0, jsx_runtime_1.jsx)(SendIcon, {}) })] }), (0, jsx_runtime_1.jsx)("div", { className: "af-footer", children: "Powered by AgentForge" })] })] }));
 }
-function MessageBubble({ message, copy, onApprovalAction, onContinue, }) {
+function MessageBubble({ message, session, readOnly, onDecision, onContinue, }) {
     const kind = message.metadata?.kind;
     if (kind === 'awaiting_approval') {
-        return ((0, jsx_runtime_1.jsx)(ApprovalBubble, { message: message, copy: copy, onAction: onApprovalAction, onContinue: onContinue }));
+        return ((0, jsx_runtime_1.jsx)(ApprovalBubble, { message: message, session: session, readOnly: readOnly, onDecision: onDecision, onContinue: onContinue }));
     }
     if (kind === 'tool_blocked') {
-        return (0, jsx_runtime_1.jsx)(BlockedBubble, { message: message, copy: copy });
+        return (0, jsx_runtime_1.jsx)(BlockedBubble, { message: message });
     }
     const cls = `af-msg af-msg-${message.role}${message.role === 'assistant' && message.isStreaming
         ? message.content
@@ -351,54 +348,60 @@ function MessageBubble({ message, copy, onApprovalAction, onContinue, }) {
  * so the chat auto-sends "continue" and the gate's fast-path consumes
  * the row on the next turn.
  */
-function ApprovalBubble({ message, copy, onAction, onContinue, }) {
+function ApprovalBubble({ message, session, readOnly, onDecision, onContinue, }) {
     const meta = message.metadata;
     const [busy, setBusy] = (0, react_1.useState)(null);
     const [decided, setDecided] = (0, react_1.useState)(null);
     const [err, setErr] = (0, react_1.useState)(null);
-    const remaining = useExpiresIn(meta?.expiresAt, copy.expiresIn);
+    const copy = meta?.copy ?? fallbackCopy({
+        connectorName: meta?.connectorName,
+        toolName: meta?.toolName,
+    });
+    const remaining = useExpiresIn(meta?.expiresAt, copy.expiresPrefix);
     if (!meta)
         return null;
     const act = async (action) => {
-        if (!onAction)
+        if (!session)
             return;
         setBusy(action);
         setErr(null);
         try {
-            await onAction({ approvalId: meta.approvalId, action });
+            await session.resolveApproval(meta.approvalId, action);
             setDecided(action === 'approve' ? 'approved' : 'denied');
+            onDecision?.({ approvalId: meta.approvalId, action, ok: true });
             if (action === 'approve')
                 onContinue();
         }
         catch (e) {
-            setErr(e instanceof Error ? e.message : String(e));
+            const message = e instanceof Error ? e.message : String(e);
+            setErr(message);
+            onDecision?.({ approvalId: meta.approvalId, action, ok: false, error: message });
         }
         finally {
             setBusy(null);
         }
     };
-    return ((0, jsx_runtime_1.jsxs)("div", { className: "af-msg af-msg-approval", children: [(0, jsx_runtime_1.jsx)("div", { className: "af-approval-title", children: copy.title }), (0, jsx_runtime_1.jsx)("div", { className: "af-approval-body", children: copy.body({
-                    connectorName: meta.connectorName,
-                    toolDescription: meta.toolDescription,
-                }) }), remaining && !decided && ((0, jsx_runtime_1.jsx)("div", { className: "af-approval-meta", children: remaining })), decided && ((0, jsx_runtime_1.jsx)("div", { className: `af-approval-pill af-approval-pill-${decided}`, children: decided === 'approved' ? copy.approvedPill : copy.deniedPill })), !decided && onAction && ((0, jsx_runtime_1.jsxs)("div", { className: "af-approval-actions", children: [(0, jsx_runtime_1.jsx)("button", { type: "button", className: "af-approval-btn af-approval-approve", disabled: busy !== null, onClick: () => act('approve'), children: busy === 'approve' ? copy.approveBusyLabel : copy.approveLabel }), (0, jsx_runtime_1.jsx)("button", { type: "button", className: "af-approval-btn af-approval-deny", disabled: busy !== null, onClick: () => act('deny'), children: busy === 'deny' ? copy.denyBusyLabel : copy.denyLabel })] })), !decided && !onAction && ((0, jsx_runtime_1.jsx)("div", { className: "af-approval-hint", children: copy.readOnlyHint })), err && (0, jsx_runtime_1.jsx)("div", { className: "af-approval-error", children: err })] }));
+    return ((0, jsx_runtime_1.jsxs)("div", { className: "af-msg af-msg-approval", children: [(0, jsx_runtime_1.jsx)("div", { className: "af-approval-title", children: copy.title }), (0, jsx_runtime_1.jsx)("div", { className: "af-approval-body", children: copy.body }), remaining && !decided && ((0, jsx_runtime_1.jsx)("div", { className: "af-approval-meta", children: remaining })), decided && ((0, jsx_runtime_1.jsx)("div", { className: `af-approval-pill af-approval-pill-${decided}`, children: decided === 'approved' ? copy.approvedPill : copy.deniedPill })), !decided && !readOnly && session && ((0, jsx_runtime_1.jsxs)("div", { className: "af-approval-actions", children: [(0, jsx_runtime_1.jsx)("button", { type: "button", className: "af-approval-btn af-approval-approve", disabled: busy !== null, onClick: () => act('approve'), children: busy === 'approve' ? copy.approveBusyLabel : copy.approveLabel }), (0, jsx_runtime_1.jsx)("button", { type: "button", className: "af-approval-btn af-approval-deny", disabled: busy !== null, onClick: () => act('deny'), children: busy === 'deny' ? copy.denyBusyLabel : copy.denyLabel })] })), !decided && readOnly && ((0, jsx_runtime_1.jsx)("div", { className: "af-approval-hint", children: copy.readOnlyHint })), err && (0, jsx_runtime_1.jsx)("div", { className: "af-approval-error", children: err })] }));
 }
 /**
  * Terminal "tool blocked" bubble. No action — just informs the visitor
  * that the tool the agent tried isn't available.
  */
-function BlockedBubble({ message, copy, }) {
+function BlockedBubble({ message, }) {
     const meta = message.metadata;
     if (!meta)
         return null;
-    return ((0, jsx_runtime_1.jsxs)("div", { className: "af-msg af-msg-blocked", children: [(0, jsx_runtime_1.jsx)("div", { className: "af-blocked-title", children: copy.blockedTitle }), (0, jsx_runtime_1.jsx)("div", { className: "af-blocked-body", children: copy.blockedBody({
-                    connectorName: meta.connectorName,
-                    reason: meta.reason,
-                }) })] }));
+    const copy = meta.copy ?? fallbackCopy({
+        connectorName: meta.connectorName,
+        toolName: meta.toolName,
+        reason: meta.reason,
+    });
+    return ((0, jsx_runtime_1.jsxs)("div", { className: "af-msg af-msg-blocked", children: [(0, jsx_runtime_1.jsx)("div", { className: "af-blocked-title", children: copy.blockedTitle }), (0, jsx_runtime_1.jsx)("div", { className: "af-blocked-body", children: copy.blockedBody })] }));
 }
 /** Live "expires in" countdown. Returns null after the deadline.
- *  The format function is host-supplied so the label stays localisable —
- *  the hook itself doesn't hard-code any user-facing string. */
-function useExpiresIn(iso, format) {
+ *  The prefix label is server-authored so the language matches the
+ *  rest of the bubble; the hook just appends the localised digits. */
+function useExpiresIn(iso, prefix) {
     const [, force] = (0, react_1.useState)(0);
     (0, react_1.useEffect)(() => {
         if (!iso)
@@ -414,7 +417,10 @@ function useExpiresIn(iso, format) {
     const totalSeconds = Math.floor(ms / 1000);
     const m = Math.floor(totalSeconds / 60);
     const s = totalSeconds % 60;
-    return format(m, s);
+    const tail = m >= 60
+        ? `${Math.floor(m / 60)}h ${m % 60}m`
+        : `${m}m ${s.toString().padStart(2, '0')}s`;
+    return `${prefix} ${tail}`.trim();
 }
 function ChatIcon() {
     return ((0, jsx_runtime_1.jsx)("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", "aria-hidden": true, children: (0, jsx_runtime_1.jsx)("path", { d: "M21 11.5a8.38 8.38 0 0 1-.9 3.8 8.5 8.5 0 0 1-7.6 4.7 8.38 8.38 0 0 1-3.8-.9L3 21l1.9-5.7a8.38 8.38 0 0 1-.9-3.8 8.5 8.5 0 0 1 4.7-7.6 8.38 8.38 0 0 1 3.8-.9h.5a8.48 8.48 0 0 1 8 8v.5z" }) }));

package/dist/session.d.ts

@@ -36,6 +36,13 @@ export declare class ChatSession {
      * continue chatting.
      */
     end(): Promise<void>;
+    /**
+     * Resolve a pending tool-approval bubble. The SDK owns the transport
+     * call so hosts don't have to know the approval endpoint or assemble
+     * the `browserSessionId` payload. Errors propagate so the calling View
+     * layer can keep the bubble in pending state and show the message.
+     */
+    resolveApproval(approvalId: string, action: 'approve' | 'deny'): Promise<void>;
     /** Tear down. Future sends throw. Useful for SPA unmount. */
     destroy(): void;
     /**

package/dist/session.js

@@ -129,6 +129,15 @@ class ChatSession {
             this.handleError(err);
         }
     }
+    /**
+     * Resolve a pending tool-approval bubble. The SDK owns the transport
+     * call so hosts don't have to know the approval endpoint or assemble
+     * the `browserSessionId` payload. Errors propagate so the calling View
+     * layer can keep the bubble in pending state and show the message.
+     */
+    async resolveApproval(approvalId, action) {
+        await this.transport.resolveApproval(approvalId, action, this.browserSessionId);
+    }
     /** Tear down. Future sends throw. Useful for SPA unmount. */
     destroy() {
         this.listeners.clear();
@@ -214,12 +223,12 @@ class ChatSession {
                             expiresAt: c.expiresAt,
                             connectorName: c.connectorName,
                             toolDescription: c.toolDescription,
+                            copy: c.copy,
                         };
-                        assistant.content =
-                            full ||
-                                (c.connectorName
-                                    ? `Necesito tu permiso para usar ${c.connectorName}.`
-                                    : `Necesito tu permiso para continuar.`);
+                        // Plain-text fallback for legacy clients that don't render
+                        // metadata.kind. Capable widgets ignore `content` and read
+                        // `metadata.copy` directly.
+                        assistant.content = full || c.copy?.body || (c.connectorName ?? '');
                         this.updateMessage(assistant);
                         continue;
                     }
@@ -231,13 +240,10 @@ class ChatSession {
                             reason: c.reason,
                             connectorName: c.connectorName,
                             toolDescription: c.toolDescription,
+                            copy: c.copy,
                         };
                         assistant.content =
-                            full ||
-                                c.reason ||
-                                (c.connectorName
-                                    ? `No puedo usar ${c.connectorName} en esta cuenta.`
-                                    : `No puedo usar esa herramienta en esta cuenta.`);
+                            full || c.copy?.blockedBody || c.reason || (c.connectorName ?? '');
                         this.updateMessage(assistant);
                         continue;
                     }

package/dist/transport.d.ts

@@ -83,6 +83,15 @@ export declare class HttpTransport {
             metadata?: Record<string, unknown>;
         }>;
     } | null>;
+    /**
+     * Resolve a pending tool-approval bubble. The server verifies the row
+     * is owned by `browser:<browserSessionId>` before mutating it, so the
+     * SDK forwards the same browser session it uses for messaging. The
+     * route lives under `/public/chat/approvals/*` — siblings of this
+     * transport's `/public/chat/:token/*` routes — and does not need the
+     * widget token (the approvalId is the capability).
+     */
+    resolveApproval(approvalId: string, action: 'approve' | 'deny', browserSessionId: string): Promise<void>;
     endConversation(conversationId: string, browserSessionId: string): Promise<void>;
     /** Parse the server's SSE response body into typed events. */
     private readSse;

package/dist/transport.js

@@ -111,6 +111,26 @@ class HttpTransport {
             })),
         };
     }
+    /**
+     * Resolve a pending tool-approval bubble. The server verifies the row
+     * is owned by `browser:<browserSessionId>` before mutating it, so the
+     * SDK forwards the same browser session it uses for messaging. The
+     * route lives under `/public/chat/approvals/*` — siblings of this
+     * transport's `/public/chat/:token/*` routes — and does not need the
+     * widget token (the approvalId is the capability).
+     */
+    async resolveApproval(approvalId, action, browserSessionId) {
+        const base = this.apiBaseUrl.replace(/\/$/, '');
+        const res = await fetch(`${base}/public/chat/approvals/${encodeURIComponent(approvalId)}/${action}`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ browserSessionId }),
+        });
+        if (!res.ok && res.status !== 204) {
+            const data = await safeJson(res);
+            throw makeTransportError(data?.message ?? `HTTP ${res.status}`, res.status, data?.error);
+        }
+    }
     async endConversation(conversationId, browserSessionId) {
         const res = await fetch(this.url(`/conversations/${encodeURIComponent(conversationId)}/end`), {
             method: 'POST',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentforge-io/chat-sdk",
-  "version": "2.0.19",
+  "version": "2.0.21",
   "description": "Framework-free chat session SDK for AgentForge public chat tokens. Headless — no DOM. Drop into any frontend (React, Vue, Svelte, vanilla) and listen for events.",
   "license": "MIT",
   "main": "dist/index.js",