@agentforge-io/chat-sdk 2.0.20 → 2.0.21

package/dist/react.d.ts

@@ -18,22 +18,18 @@
 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,
@@ -84,11 +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`.
+     */
+    onApprovalDecision?: ApprovalDecisionObserver;
+    /**
+     * 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.
      */
-    onApprovalAction?: ApprovalActionHandler;
+    readOnlyApprovals?: boolean;
 }
 /**
  * Drop-in chat widget. Owns its own `ChatSession` and re-renders on every

package/dist/react.js

@@ -181,7 +181,7 @@ function fallbackCopy(ctx) {
  * 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, } = props;
+    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)();
@@ -301,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, 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
@@ -315,10 +315,10 @@ 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, 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, 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 });
@@ -348,7 +348,7 @@ function MessageBubble({ message, onApprovalAction, onContinue, }) {
  * so the chat auto-sends "continue" and the gate's fast-path consumes
  * the row on the next turn.
  */
-function ApprovalBubble({ message, 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);
@@ -361,24 +361,27 @@ function ApprovalBubble({ message, onAction, onContinue, }) {
     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 }), 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

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();

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.20",
+  "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",