@agentforge-io/chat-sdk 0.1.0

package/dist/entities.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Pure entity types — no behavior, no transport, no DOM. Anything that holds
+ * data about a chat session lives here so the rest of the SDK can stay tiny
+ * and easy to reason about.
+ */
+export type ChatRole = 'user' | 'assistant' | 'system';
+export interface ChatMessage {
+    /** Stable client-side id so view layers can key off it. */
+    id: string;
+    role: ChatRole;
+    /** Plain text. The widget renders this as `white-space: pre-wrap`; if you
+     *  want markdown rendering, do it in your own View layer. */
+    content: string;
+    createdAt: Date;
+    /** True while the assistant is still streaming this message. The UI uses
+     *  this to render a caret/cursor next to a half-written reply. */
+    isStreaming?: boolean;
+}
+export interface ChatAgentSummary {
+    slug: string;
+    name: string;
+    description?: string;
+}
+/**
+ * Visual theme returned alongside the agent. Pure data — the SDK doesn't
+ * apply it; it just surfaces it so any View layer (widget renderer, React
+ * adapter, custom UI) can read the same source.
+ */
+export interface ChatTheme {
+    primaryColor?: string;
+    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+    title?: string;
+    greeting?: string;
+    avatarUrl?: string;
+}
+/**
+ * Discriminated union of everything `ChatSession` can emit. Subscribe via
+ * `session.onEvent(cb)` — the SDK is intentionally not tied to any specific
+ * event emitter library so it stays bundle-light.
+ */
+export type ChatEvent = {
+    type: 'agent_loaded';
+    agent: ChatAgentSummary;
+    theme?: ChatTheme;
+} | {
+    type: 'state';
+    state: ChatSessionState;
+} | {
+    type: 'message_added';
+    message: ChatMessage;
+} | {
+    type: 'message_updated';
+    message: ChatMessage;
+} | {
+    type: 'message_removed';
+    messageId: string;
+} | {
+    type: 'error';
+    message: string;
+    code?: string;
+} | {
+    type: 'destroyed';
+};
+export type ChatSessionStatus = 'idle' | 'loading' | 'ready' | 'sending' | 'streaming' | 'ended' | 'error';
+export interface ChatSessionState {
+    status: ChatSessionStatus;
+    agent?: ChatAgentSummary;
+    theme?: ChatTheme;
+    conversationId?: string;
+    messages: ChatMessage[];
+    lastError?: string;
+}
+export interface ChatSessionOptions {
+    /** Public chat token (`aft_*`) issued from the admin UI. */
+    token: string;
+    /**
+     * Base URL of the AgentForge API, including scheme. Trailing slash is
+     * stripped. Defaults to the origin the SDK was loaded from when running
+     * inside a browser bundle of the widget; required everywhere else.
+     */
+    apiBaseUrl?: string;
+    /** Stable id for this end-user's browser. Persist it (localStorage etc.)
+     *  so usage rolls up across visits. If omitted, the SDK generates one and
+     *  surfaces it via `session.browserSessionId` — caller can then store it. */
+    browserSessionId?: string;
+    /** When true, use SSE streaming endpoints (default). Set false to fall
+     *  back to plain POSTs returning the final reply in one shot. */
+    stream?: boolean;
+    /**
+     * Existing conversation id to resume. When set, `start()` fetches the
+     * transcript and replays it as `message_added` events before going to
+     * `ready`. If the id no longer exists or doesn't belong to this browser
+     * session, the SDK silently falls back to a fresh conversation.
+     */
+    resumeConversationId?: string;
+}

package/dist/entities.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * Pure entity types — no behavior, no transport, no DOM. Anything that holds
+ * data about a chat session lives here so the rest of the SDK can stay tiny
+ * and easy to reason about.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @agentforge-io/chat-sdk — headless chat session SDK.
+ *
+ * Public surface (intentionally tiny):
+ *   - `ChatSession`  → the only class consumers create.
+ *   - `HttpTransport` → exported for advanced cases (custom error handling,
+ *     server-side rendering) but most apps never touch it directly.
+ *   - All entity types so View layers can render strongly-typed state.
+ */
+export { ChatSession } from './session';
+export { HttpTransport } from './transport';
+export type { StreamEvent, ServerStreamChunk, TransportError, } from './transport';
+export type { ChatAgentSummary, ChatEvent, ChatMessage, ChatRole, ChatSessionOptions, ChatSessionState, ChatSessionStatus, ChatTheme, } from './entities';

package/dist/index.js

@@ -0,0 +1,16 @@
+"use strict";
+/**
+ * @agentforge-io/chat-sdk — headless chat session SDK.
+ *
+ * Public surface (intentionally tiny):
+ *   - `ChatSession`  → the only class consumers create.
+ *   - `HttpTransport` → exported for advanced cases (custom error handling,
+ *     server-side rendering) but most apps never touch it directly.
+ *   - All entity types so View layers can render strongly-typed state.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpTransport = exports.ChatSession = void 0;
+var session_1 = require("./session");
+Object.defineProperty(exports, "ChatSession", { enumerable: true, get: function () { return session_1.ChatSession; } });
+var transport_1 = require("./transport");
+Object.defineProperty(exports, "HttpTransport", { enumerable: true, get: function () { return transport_1.HttpTransport; } });

package/dist/react.d.ts

@@ -0,0 +1,46 @@
+/**
+ * React adapter for `@agentforge-io/chat-sdk`.
+ *
+ * Why this exists: the standalone `widget.js` (served by AgentForge) is a
+ * vanilla-JS bootstrap that injects a floating chat bubble. Customers who
+ * already render their site in React want the same widget without a
+ * separate <script> tag fighting their bundler — so we ship a React
+ * component that wraps `ChatSession` and renders the same look-and-feel
+ * with the framework already in the page.
+ *
+ * Public surface is one component: `<ChatWidget />`. Pass it a public
+ * chat token (`aft_*`) and an `apiBaseUrl`; everything else is optional.
+ *
+ * React is a `peerDependency` — we don't bundle it. Consumers always have
+ * their own copy, and pulling our own would risk the dreaded "two Reacts"
+ * runtime error.
+ */
+import { type CSSProperties } from 'react';
+import type { ChatTheme } from './entities';
+export interface ChatWidgetProps {
+    /** Public chat token (`aft_*`) issued from the admin UI. */
+    token: string;
+    /** AgentForge API origin. Defaults to `window.location.origin` in the
+     *  browser — set this when your site and the API live on different hosts. */
+    apiBaseUrl?: string;
+    /** Render inline (fills the parent) instead of as a floating bubble. */
+    inline?: boolean;
+    /** Override the launcher position when not inline. */
+    position?: NonNullable<ChatTheme['position']>;
+    /** Persistent id for this end-user's browser. Pass the same value across
+     *  visits to let server-side usage aggregate. */
+    browserSessionId?: string;
+    /** Existing conversation id to resume. */
+    resumeConversationId?: string;
+    /** Disable SSE streaming and use plain POSTs. */
+    stream?: boolean;
+    /** Extra class on the root container. */
+    className?: string;
+    /** Inline style on the root container. */
+    style?: CSSProperties;
+}
+/**
+ * Drop-in chat widget. Owns its own `ChatSession` and re-renders on every
+ * SDK event. Consumers don't need to read `session.getState()` themselves.
+ */
+export declare function ChatWidget(props: ChatWidgetProps): JSX.Element;

package/dist/react.js

@@ -0,0 +1,374 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChatWidget = ChatWidget;
+const jsx_runtime_1 = require("react/jsx-runtime");
+/**
+ * React adapter for `@agentforge-io/chat-sdk`.
+ *
+ * Why this exists: the standalone `widget.js` (served by AgentForge) is a
+ * vanilla-JS bootstrap that injects a floating chat bubble. Customers who
+ * already render their site in React want the same widget without a
+ * separate <script> tag fighting their bundler — so we ship a React
+ * component that wraps `ChatSession` and renders the same look-and-feel
+ * with the framework already in the page.
+ *
+ * Public surface is one component: `<ChatWidget />`. Pass it a public
+ * chat token (`aft_*`) and an `apiBaseUrl`; everything else is optional.
+ *
+ * React is a `peerDependency` — we don't bundle it. Consumers always have
+ * their own copy, and pulling our own would risk the dreaded "two Reacts"
+ * runtime error.
+ */
+const react_1 = require("react");
+const session_1 = require("./session");
+// ─── Markdown rendering ─────────────────────────────────────────────────
+// Same minimal renderer the standalone widget.js ships — paragraphs,
+// headings, lists, blockquotes, fenced code, inline code, links, bold,
+// italic. Input is HTML-escaped first so the resulting markup is safe to
+// drop into dangerouslySetInnerHTML.
+function escapeHtml(s) {
+    return s.replace(/[&<>"']/g, (c) => c === '&'
+        ? '&amp;'
+        : c === '<'
+            ? '&lt;'
+            : c === '>'
+                ? '&gt;'
+                : c === '"'
+                    ? '&quot;'
+                    : '&#39;');
+}
+function renderInline(s) {
+    const codes = [];
+    s = s.replace(/`([^`\n]+)`/g, (_m, body) => {
+        codes.push(`<code>${escapeHtml(body)}</code>`);
+        return `\x00CODE${codes.length - 1}\x00`;
+    });
+    s = escapeHtml(s);
+    s = s.replace(/\[([^\]]+)\]\((https?:\/\/[^\s)]+|mailto:[^\s)]+)\)/g, (_m, text, href) => `<a href="${href}" target="_blank" rel="noopener noreferrer">${text}</a>`);
+    s = s.replace(/\*\*([^*\n]+)\*\*/g, '<strong>$1</strong>');
+    s = s.replace(/(^|[^*])\*([^*\n]+)\*/g, '$1<em>$2</em>');
+    s = s.replace(/\x00CODE(\d+)\x00/g, (_m, i) => codes[+i]);
+    return s;
+}
+function renderMarkdown(src) {
+    if (!src)
+        return '';
+    const lines = String(src).replace(/\r\n/g, '\n').split('\n');
+    const out = [];
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        const fence = line.match(/^```(\w*)\s*$/);
+        if (fence) {
+            const buf = [];
+            i++;
+            while (i < lines.length && !/^```\s*$/.test(lines[i])) {
+                buf.push(lines[i]);
+                i++;
+            }
+            i++;
+            out.push(`<pre><code>${escapeHtml(buf.join('\n'))}</code></pre>`);
+            continue;
+        }
+        if (/^\s*(---+|\*\*\*+|___+)\s*$/.test(line)) {
+            out.push('<hr>');
+            i++;
+            continue;
+        }
+        const h = line.match(/^(#{1,3})\s+(.*)$/);
+        if (h) {
+            const level = h[1].length;
+            out.push(`<h${level}>${renderInline(h[2])}</h${level}>`);
+            i++;
+            continue;
+        }
+        if (/^\s*[-*]\s+/.test(line)) {
+            const items = [];
+            while (i < lines.length && /^\s*[-*]\s+/.test(lines[i])) {
+                items.push(`<li>${renderInline(lines[i].replace(/^\s*[-*]\s+/, ''))}</li>`);
+                i++;
+            }
+            out.push(`<ul>${items.join('')}</ul>`);
+            continue;
+        }
+        if (/^\s*\d+\.\s+/.test(line)) {
+            const items = [];
+            while (i < lines.length && /^\s*\d+\.\s+/.test(lines[i])) {
+                items.push(`<li>${renderInline(lines[i].replace(/^\s*\d+\.\s+/, ''))}</li>`);
+                i++;
+            }
+            out.push(`<ol>${items.join('')}</ol>`);
+            continue;
+        }
+        if (/^\s*>\s?/.test(line)) {
+            const qbuf = [];
+            while (i < lines.length && /^\s*>\s?/.test(lines[i])) {
+                qbuf.push(lines[i].replace(/^\s*>\s?/, ''));
+                i++;
+            }
+            out.push(`<blockquote>${renderInline(qbuf.join(' '))}</blockquote>`);
+            continue;
+        }
+        if (/^\s*$/.test(line)) {
+            i++;
+            continue;
+        }
+        const pbuf = [];
+        while (i < lines.length &&
+            !/^\s*$/.test(lines[i]) &&
+            !/^```/.test(lines[i]) &&
+            !/^(#{1,3})\s+/.test(lines[i]) &&
+            !/^\s*[-*]\s+/.test(lines[i]) &&
+            !/^\s*\d+\.\s+/.test(lines[i]) &&
+            !/^\s*>\s?/.test(lines[i]) &&
+            !/^\s*(---+|\*\*\*+|___+)\s*$/.test(lines[i])) {
+            pbuf.push(lines[i]);
+            i++;
+        }
+        out.push(`<p>${renderInline(pbuf.join('\n')).replace(/\n/g, '<br>')}</p>`);
+    }
+    return out.join('');
+}
+/**
+ * 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, } = props;
+    const [session, setSession] = (0, react_1.useState)(null);
+    const [status, setStatus] = (0, react_1.useState)('idle');
+    const [agent, setAgent] = (0, react_1.useState)();
+    const [theme, setTheme] = (0, react_1.useState)();
+    const [messages, setMessages] = (0, react_1.useState)([]);
+    const [lastError, setLastError] = (0, react_1.useState)(null);
+    const [open, setOpen] = (0, react_1.useState)(inline);
+    const [draft, setDraft] = (0, react_1.useState)('');
+    const messagesRef = (0, react_1.useRef)(null);
+    const styleId = (0, react_1.useId)();
+    // ── Session lifecycle. Recreate when token / apiBaseUrl changes. ──────
+    (0, react_1.useEffect)(() => {
+        let cancelled = false;
+        const s = new session_1.ChatSession({
+            token,
+            apiBaseUrl,
+            browserSessionId,
+            resumeConversationId,
+            stream,
+        });
+        setSession(s);
+        setMessages([]);
+        setStatus('idle');
+        setLastError(null);
+        const unsubscribe = s.onEvent((evt) => {
+            if (cancelled)
+                return;
+            if (evt.type === 'agent_loaded') {
+                setAgent(evt.agent);
+                setTheme(evt.theme);
+                return;
+            }
+            if (evt.type === 'state') {
+                setStatus(evt.state.status);
+                setLastError(evt.state.lastError ?? null);
+                // Replace the message list wholesale — the SDK is the source of
+                // truth, and message_added/_updated already covered single mutations.
+                setMessages(evt.state.messages.map((m) => ({ ...m })));
+                return;
+            }
+            if (evt.type === 'error') {
+                setLastError(evt.message);
+                return;
+            }
+        });
+        void s.start();
+        return () => {
+            cancelled = true;
+            unsubscribe();
+            s.destroy();
+        };
+    }, [token, apiBaseUrl, browserSessionId, resumeConversationId, stream]);
+    // Auto-scroll on new tokens.
+    (0, react_1.useEffect)(() => {
+        const el = messagesRef.current;
+        if (!el)
+            return;
+        el.scrollTop = el.scrollHeight;
+    }, [messages]);
+    // Inject the widget stylesheet exactly once per page. We key the <style>
+    // tag by a fixed id so multiple widget mounts share it.
+    (0, react_1.useEffect)(() => {
+        if (typeof document === 'undefined')
+            return;
+        const id = 'af-chat-widget-style';
+        if (document.getElementById(id))
+            return;
+        const el = document.createElement('style');
+        el.id = id;
+        el.textContent = WIDGET_CSS;
+        document.head.appendChild(el);
+    }, []);
+    const handleSend = (0, react_1.useCallback)(() => {
+        if (!session)
+            return;
+        const text = draft.trim();
+        if (!text)
+            return;
+        setDraft('');
+        void session.send(text);
+    }, [session, draft]);
+    const onKeyDown = (0, react_1.useCallback)((e) => {
+        if (e.key === 'Enter' && !e.shiftKey) {
+            e.preventDefault();
+            handleSend();
+        }
+    }, [handleSend]);
+    const sendDisabled = !session ||
+        status === 'idle' ||
+        status === 'loading' ||
+        status === 'sending' ||
+        status === 'streaming' ||
+        status === 'ended' ||
+        !draft.trim();
+    const resolvedPosition = position ?? theme?.position ?? 'bottom-right';
+    const rootClass = [
+        'af-widget-root',
+        `af-pos-${resolvedPosition}`,
+        inline ? 'af-inline' : '',
+        className ?? '',
+    ]
+        .filter(Boolean)
+        .join(' ');
+    const rootStyle = {
+        ...style,
+        // Surface the theme primary color so the bubble + accents follow it.
+        ...(theme?.primaryColor
+            ? { ['--af-primary']: theme.primaryColor }
+            : {}),
+    };
+    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 }, 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 }) {
+    const cls = `af-msg af-msg-${message.role}${message.role === 'assistant' && message.isStreaming
+        ? message.content
+            ? ' af-msg-streaming'
+            : ' af-msg-typing'
+        : ''}`;
+    // Typing state (no content yet): render the three-dot indicator, no markdown.
+    if (message.role === 'assistant' && message.isStreaming && !message.content) {
+        return ((0, jsx_runtime_1.jsx)("div", { className: cls, children: (0, jsx_runtime_1.jsxs)("span", { className: "af-typing-dots", "aria-label": "Assistant is typing", children: [(0, jsx_runtime_1.jsx)("span", {}), " ", (0, jsx_runtime_1.jsx)("span", {}), " ", (0, jsx_runtime_1.jsx)("span", {})] }) }));
+    }
+    if (message.role === 'assistant') {
+        return ((0, jsx_runtime_1.jsx)("div", { className: cls, 
+            // Output is sanitized by escapeHtml + a fixed tag whitelist in
+            // renderMarkdown — safe to inject as HTML.
+            dangerouslySetInnerHTML: { __html: renderMarkdown(message.content) } }));
+    }
+    // User & system messages stay as plain text — they're typed verbatim.
+    return (0, jsx_runtime_1.jsx)("div", { className: cls, children: message.content });
+}
+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" }) }));
+}
+function CloseIcon() {
+    return ((0, jsx_runtime_1.jsxs)("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", "aria-hidden": true, children: [(0, jsx_runtime_1.jsx)("line", { x1: "18", y1: "6", x2: "6", y2: "18" }), (0, jsx_runtime_1.jsx)("line", { x1: "6", y1: "6", x2: "18", y2: "18" })] }));
+}
+function SendIcon() {
+    return ((0, jsx_runtime_1.jsxs)("svg", { viewBox: "0 0 24 24", fill: "none", stroke: "currentColor", strokeWidth: "2", strokeLinecap: "round", strokeLinejoin: "round", "aria-hidden": true, children: [(0, jsx_runtime_1.jsx)("line", { x1: "22", y1: "2", x2: "11", y2: "13" }), (0, jsx_runtime_1.jsx)("polygon", { points: "22 2 15 22 11 13 2 9 22 2" })] }));
+}
+// Stylesheet kept verbatim from the standalone widget.js so the React
+// component is visually indistinguishable from the script-injected one.
+const WIDGET_CSS = `
+.af-widget-root {
+  --af-primary: #7c5cff;
+  --af-primary-soft: rgba(124, 92, 255, 0.35);
+  --af-bg: #ffffff;
+  --af-fg: #0f172a;
+  --af-muted: #64748b;
+  --af-border: #e2e8f0;
+  --af-bubble-bg: #f8fafc;
+  position: fixed; z-index: 2147483646;
+  font-family: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+}
+.af-widget-root.af-pos-bottom-right { bottom: 24px; right: 24px; }
+.af-widget-root.af-pos-bottom-left  { bottom: 24px; left: 24px; }
+.af-widget-root.af-pos-top-right    { top: 24px; right: 24px; }
+.af-widget-root.af-pos-top-left     { top: 24px; left: 24px; }
+.af-widget-root *, .af-widget-root *::before, .af-widget-root *::after { box-sizing: border-box; }
+.af-widget-root.af-inline { position: relative; top: auto; bottom: auto; left: auto; right: auto; }
+.af-toggle { width: 56px; height: 56px; border-radius: 50%; border: none; cursor: pointer;
+  background: var(--af-primary); color: white;
+  box-shadow: 0 10px 30px var(--af-primary-soft); display: grid; place-items: center; transition: transform .15s ease; }
+.af-toggle:hover { transform: scale(1.05); }
+.af-toggle svg { width: 24px; height: 24px; stroke: currentColor; fill: none; stroke-width: 2; }
+.af-panel { position: absolute; width: 360px; max-width: calc(100vw - 32px);
+  height: 540px; max-height: calc(100vh - 96px); background: var(--af-bg); color: var(--af-fg); border-radius: 16px;
+  box-shadow: 0 20px 50px rgba(15, 23, 42, 0.25); display: none; flex-direction: column; overflow: hidden; }
+.af-widget-root.af-pos-bottom-right .af-panel,
+.af-widget-root.af-pos-bottom-left  .af-panel { bottom: 72px; }
+.af-widget-root.af-pos-top-right    .af-panel,
+.af-widget-root.af-pos-top-left     .af-panel { top: 72px; }
+.af-widget-root.af-pos-bottom-right .af-panel,
+.af-widget-root.af-pos-top-right    .af-panel { right: 0; }
+.af-widget-root.af-pos-bottom-left  .af-panel,
+.af-widget-root.af-pos-top-left     .af-panel { left: 0; }
+.af-widget-root.af-inline .af-panel { position: relative; top: auto; bottom: auto; left: auto; right: auto; width: 100%; height: 540px; box-shadow: 0 1px 3px rgba(15,23,42,0.08); display: flex; }
+.af-panel.af-open { display: flex; }
+.af-header { padding: 14px 16px; background: var(--af-fg); color: white; display: flex; align-items: center; gap: 10px; }
+.af-header-info { flex: 1; min-width: 0; }
+.af-header-avatar { width: 28px; height: 28px; border-radius: 50%; object-fit: cover; background: rgba(255,255,255,0.1); }
+.af-header-title { font-weight: 600; font-size: 14px; }
+.af-header-subtitle { font-size: 11px; opacity: 0.7; margin-top: 2px; }
+.af-close { background: transparent; border: none; color: white; cursor: pointer; padding: 4px; line-height: 0; }
+.af-close svg { width: 18px; height: 18px; }
+.af-messages { flex: 1; overflow-y: auto; padding: 16px; background: var(--af-bubble-bg); display: flex; flex-direction: column; gap: 10px; scroll-behavior: smooth; }
+.af-msg { max-width: 80%; padding: 10px 12px; border-radius: 14px; font-size: 14px; line-height: 1.5; word-wrap: break-word; overflow-wrap: anywhere;
+  animation: af-msg-in 220ms cubic-bezier(0.2, 0.8, 0.2, 1); }
+.af-msg-user { align-self: flex-end; background: var(--af-primary); color: white; border-bottom-right-radius: 4px; white-space: pre-wrap; }
+.af-msg-assistant { align-self: flex-start; background: var(--af-bg); color: var(--af-fg); border: 1px solid var(--af-border); border-bottom-left-radius: 4px; }
+.af-msg-assistant p { margin: 0; }
+.af-msg-assistant p + p { margin-top: 8px; }
+.af-msg-assistant ul, .af-msg-assistant ol { margin: 6px 0; padding-left: 20px; }
+.af-msg-assistant li { margin: 2px 0; }
+.af-msg-assistant h1, .af-msg-assistant h2, .af-msg-assistant h3 { margin: 8px 0 4px; font-weight: 600; line-height: 1.3; }
+.af-msg-assistant h1 { font-size: 16px; }
+.af-msg-assistant h2 { font-size: 15px; }
+.af-msg-assistant h3 { font-size: 14px; }
+.af-msg-assistant a { color: var(--af-primary); text-decoration: underline; word-break: break-all; }
+.af-msg-assistant code { background: rgba(15,23,42,0.06); padding: 1px 5px; border-radius: 4px; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 12.5px; }
+.af-msg-assistant pre { margin: 6px 0; padding: 10px 12px; background: #0f172a; color: #f1f5f9; border-radius: 8px; overflow-x: auto; font-size: 12.5px; line-height: 1.45; }
+.af-msg-assistant pre code { background: transparent; padding: 0; color: inherit; font-size: inherit; }
+.af-msg-assistant blockquote { margin: 4px 0; padding-left: 10px; border-left: 3px solid var(--af-border); color: var(--af-muted); }
+.af-msg-assistant hr { border: none; border-top: 1px solid var(--af-border); margin: 8px 0; }
+.af-msg-assistant strong { font-weight: 600; }
+.af-msg-assistant em { font-style: italic; }
+.af-msg-assistant.af-msg-streaming::after { content: '▍'; display: inline-block; margin-left: 2px; animation: af-blink 1s infinite; color: #94a3b8; font-weight: 300; }
+.af-msg-system { align-self: center; font-size: 12px; color: var(--af-muted); background: transparent; border: none; padding: 4px 8px; }
+.af-msg-assistant.af-msg-typing { padding: 14px 14px; min-width: 56px; }
+.af-msg-assistant.af-msg-typing::after { content: none; }
+.af-typing-dots { display: inline-flex; gap: 4px; align-items: center; }
+.af-typing-dots span { width: 7px; height: 7px; border-radius: 50%; background: var(--af-muted); display: inline-block; animation: af-bounce 1.2s infinite ease-in-out; }
+.af-typing-dots span:nth-child(2) { animation-delay: 0.15s; }
+.af-typing-dots span:nth-child(3) { animation-delay: 0.3s; }
+@keyframes af-bounce {
+  0%, 60%, 100% { transform: translateY(0); opacity: 0.4; }
+  30% { transform: translateY(-4px); opacity: 1; }
+}
+@keyframes af-blink { 0%, 80%, 100% { opacity: 0.3; } 40% { opacity: 1; } }
+@keyframes af-msg-in {
+  from { opacity: 0; transform: translateY(6px); }
+  to { opacity: 1; transform: translateY(0); }
+}
+.af-input-row { padding: 12px; border-top: 1px solid var(--af-border); background: var(--af-bg); display: flex; gap: 8px; align-items: flex-end; }
+.af-input { flex: 1; border: 1px solid var(--af-border); border-radius: 10px; padding: 10px 12px; font-size: 14px; font-family: inherit; outline: none; resize: none; min-height: 40px; max-height: 120px; color: var(--af-fg); background: var(--af-bg); transition: border-color .15s ease, box-shadow .15s ease; }
+.af-input:focus { border-color: var(--af-primary); box-shadow: 0 0 0 3px var(--af-primary-soft); }
+.af-input:disabled { background: var(--af-bubble-bg); cursor: not-allowed; }
+.af-send { background: var(--af-primary); color: white; border: none; border-radius: 10px; padding: 0 14px; min-height: 40px; cursor: pointer; font-weight: 500; font-size: 14px; display: inline-flex; align-items: center; justify-content: center; transition: opacity .15s ease, transform .1s ease; }
+.af-send:hover:not(:disabled) { transform: translateY(-1px); }
+.af-send:active:not(:disabled) { transform: translateY(0); }
+.af-send:disabled { opacity: 0.5; cursor: not-allowed; }
+.af-send svg { width: 16px; height: 16px; }
+.af-error { padding: 10px 16px; font-size: 12px; color: #b91c1c; background: #fef2f2; border-top: 1px solid #fee2e2; }
+.af-footer { padding: 6px 12px; font-size: 10px; color: var(--af-muted); text-align: center; background: var(--af-bubble-bg); border-top: 1px solid var(--af-border); }
+`;

package/dist/session.d.ts

@@ -0,0 +1,57 @@
+import { type ChatEvent, type ChatSessionOptions, type ChatSessionState } from './entities';
+type Listener = (event: ChatEvent) => void;
+/**
+ * Headless chat session. Owns all conversation state and the network calls
+ * that mutate it; emits events for any View to consume. Use this directly
+ * from React/Vue/Svelte/vanilla — it has no DOM dependency.
+ *
+ * Lifecycle:
+ *   const session = new ChatSession({ token, apiBaseUrl });
+ *   const unsubscribe = session.onEvent(handler);
+ *   await session.start();
+ *   await session.send('Hello');
+ *   session.destroy();
+ *
+ * Errors mid-stream don't kill the session — `state.status` flips to 'error'
+ * and the consumer can call `send()` again. Hard errors (bad token, 403)
+ * leave `lastError` set and `status='error'` so the UI can surface them.
+ */
+export declare class ChatSession {
+    readonly browserSessionId: string;
+    private readonly transport;
+    private readonly stream;
+    private readonly resumeId?;
+    private listeners;
+    private state;
+    private started;
+    constructor(opts: ChatSessionOptions);
+    /** Returns an unsubscribe function. Listeners are called synchronously. */
+    onEvent(listener: Listener): () => void;
+    getState(): ChatSessionState;
+    start(): Promise<void>;
+    /**
+     * Mark the active conversation as ended on the server and lock the
+     * session locally. After this, sends throw — the consumer should drop
+     * the persisted conversationId and start a fresh ChatSession to
+     * continue chatting.
+     */
+    end(): Promise<void>;
+    /** Tear down. Future sends throw. Useful for SPA unmount. */
+    destroy(): void;
+    /**
+     * Send a user message. Opens the conversation on first call. Returns the
+     * final assistant content for callers that want to await it; the same
+     * content is also emitted via `message_added` / `message_updated`.
+     */
+    send(text: string): Promise<string>;
+    private runStream;
+    private runNonStream;
+    private appendMessage;
+    private updateMessage;
+    private removeMessage;
+    private setStatus;
+    private emitStateChange;
+    private handleError;
+    private emit;
+}
+export {};

package/dist/session.js

@@ -0,0 +1,336 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChatSession = void 0;
+const transport_1 = require("./transport");
+/**
+ * Headless chat session. Owns all conversation state and the network calls
+ * that mutate it; emits events for any View to consume. Use this directly
+ * from React/Vue/Svelte/vanilla — it has no DOM dependency.
+ *
+ * Lifecycle:
+ *   const session = new ChatSession({ token, apiBaseUrl });
+ *   const unsubscribe = session.onEvent(handler);
+ *   await session.start();
+ *   await session.send('Hello');
+ *   session.destroy();
+ *
+ * Errors mid-stream don't kill the session — `state.status` flips to 'error'
+ * and the consumer can call `send()` again. Hard errors (bad token, 403)
+ * leave `lastError` set and `status='error'` so the UI can surface them.
+ */
+class ChatSession {
+    constructor(opts) {
+        this.listeners = new Set();
+        this.state = {
+            status: 'idle',
+            messages: [],
+        };
+        this.started = false;
+        if (!opts.token)
+            throw new Error('ChatSession: token is required');
+        const apiBaseUrl = opts.apiBaseUrl ?? defaultApiBase();
+        if (!apiBaseUrl) {
+            throw new Error('ChatSession: apiBaseUrl is required outside the browser');
+        }
+        this.transport = new transport_1.HttpTransport(apiBaseUrl, opts.token);
+        this.stream = opts.stream ?? true;
+        this.browserSessionId = opts.browserSessionId ?? generateBrowserSessionId();
+        this.resumeId = opts.resumeConversationId;
+    }
+    // ─── Subscriptions ──────────────────────────────────────────────────────
+    /** Returns an unsubscribe function. Listeners are called synchronously. */
+    onEvent(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    getState() {
+        // Defensive copy — consumers shouldn't be able to mutate internal state.
+        return {
+            ...this.state,
+            messages: this.state.messages.map((m) => ({ ...m })),
+        };
+    }
+    // ─── Lifecycle ──────────────────────────────────────────────────────────
+    async start() {
+        if (this.started)
+            return;
+        this.started = true;
+        this.setStatus('loading');
+        try {
+            const { agent, theme } = await this.transport.getAgent();
+            this.state.agent = agent;
+            this.state.theme = theme;
+            this.emit({ type: 'agent_loaded', agent, theme });
+            // Try to resume a previous conversation if the caller handed us an id.
+            // Failure is non-fatal — the server may have GC'd the conv, the
+            // browser session may have rotated, or the row could belong to a
+            // different agent. In any of those cases we silently fall through to
+            // "fresh start" so the widget never gets stuck.
+            let resumed = false;
+            if (this.resumeId) {
+                try {
+                    const history = await this.transport.getConversation(this.resumeId, this.browserSessionId);
+                    if (history) {
+                        this.state.conversationId = history.id;
+                        for (const m of history.messages) {
+                            // Replay each persisted message as if it had been streamed in
+                            // — view layers already render `message_added` events.
+                            this.appendMessage({
+                                id: m.id,
+                                role: m.role,
+                                content: m.content,
+                                createdAt: new Date(m.createdAt),
+                            });
+                        }
+                        if (history.status === 'completed') {
+                            this.setStatus('ended');
+                            resumed = true;
+                            return;
+                        }
+                        resumed = true;
+                    }
+                }
+                catch {
+                    // Treat all errors as "couldn't resume, start fresh".
+                }
+            }
+            // Only show the canned greeting when we DIDN'T resume — otherwise
+            // it would appear at the top of an existing chat every page reload.
+            if (!resumed && theme?.greeting) {
+                this.appendMessage({
+                    id: makeMessageId('s'),
+                    role: 'system',
+                    content: theme.greeting,
+                    createdAt: new Date(),
+                });
+            }
+            this.setStatus('ready');
+        }
+        catch (err) {
+            this.handleError(err);
+        }
+    }
+    /**
+     * Mark the active conversation as ended on the server and lock the
+     * session locally. After this, sends throw — the consumer should drop
+     * the persisted conversationId and start a fresh ChatSession to
+     * continue chatting.
+     */
+    async end() {
+        const convId = this.state.conversationId;
+        if (!convId)
+            return;
+        try {
+            await this.transport.endConversation(convId, this.browserSessionId);
+            this.setStatus('ended');
+        }
+        catch (err) {
+            this.handleError(err);
+        }
+    }
+    /** Tear down. Future sends throw. Useful for SPA unmount. */
+    destroy() {
+        this.listeners.clear();
+        this.emit({ type: 'destroyed' });
+        // Drop everything — a destroyed session shouldn't be reused.
+        this.state = { status: 'idle', messages: [] };
+        this.started = false;
+    }
+    // ─── User actions ───────────────────────────────────────────────────────
+    /**
+     * Send a user message. Opens the conversation on first call. Returns the
+     * final assistant content for callers that want to await it; the same
+     * content is also emitted via `message_added` / `message_updated`.
+     */
+    async send(text) {
+        const trimmed = text.trim();
+        if (!trimmed)
+            return '';
+        if (this.state.status === 'ended') {
+            throw new Error('Conversation has ended. Start a fresh chat to continue.');
+        }
+        if (!this.started)
+            await this.start();
+        this.appendMessage({
+            id: makeMessageId('u'),
+            role: 'user',
+            content: trimmed,
+            createdAt: new Date(),
+        });
+        const assistant = {
+            id: makeMessageId('a'),
+            role: 'assistant',
+            content: '',
+            createdAt: new Date(),
+            isStreaming: true,
+        };
+        this.appendMessage(assistant);
+        if (this.stream) {
+            return this.runStream(trimmed, assistant);
+        }
+        return this.runNonStream(trimmed, assistant);
+    }
+    // ─── Internals ──────────────────────────────────────────────────────────
+    async runStream(text, assistant) {
+        this.setStatus('sending');
+        try {
+            const generator = this.state.conversationId
+                ? this.transport.streamSendMessage(this.state.conversationId, text, this.browserSessionId)
+                : this.transport.streamCreateConversation(text, this.browserSessionId);
+            let full = '';
+            let sawAnyChunk = false;
+            for await (const evt of generator) {
+                if (evt.kind === 'conversation') {
+                    this.state.conversationId = evt.id;
+                    continue;
+                }
+                if (evt.kind === 'chunk') {
+                    sawAnyChunk = true;
+                    const delta = extractDelta(evt.chunk);
+                    if (!delta)
+                        continue;
+                    if (this.state.status !== 'streaming')
+                        this.setStatus('streaming');
+                    full += delta;
+                    assistant.content = full;
+                    this.updateMessage(assistant);
+                    continue;
+                }
+                if (evt.kind === 'error') {
+                    throw new Error(evt.message);
+                }
+                if (evt.kind === 'done') {
+                    break;
+                }
+            }
+            // Stream closed with no usable content — surface as an error rather
+            // than leaving an empty assistant bubble. Most often this means the
+            // backend swallowed an exception inside streamMessage (e.g. the
+            // history query failed or the runner rejected the model).
+            if (!full) {
+                throw new Error(sawAnyChunk
+                    ? 'The model returned an empty response.'
+                    : 'No response received from the server.');
+            }
+            assistant.isStreaming = false;
+            this.updateMessage(assistant);
+            this.setStatus('ready');
+            return full;
+        }
+        catch (err) {
+            // Drop the half-built assistant message — leaving an empty bubble
+            // around is worse than no bubble at all.
+            if (!assistant.content) {
+                this.removeMessage(assistant.id);
+            }
+            else {
+                assistant.isStreaming = false;
+                this.updateMessage(assistant);
+            }
+            this.handleError(err);
+            return assistant.content;
+        }
+    }
+    async runNonStream(text, assistant) {
+        this.setStatus('sending');
+        try {
+            let content;
+            if (this.state.conversationId) {
+                const res = await this.transport.sendMessage(this.state.conversationId, text, this.browserSessionId);
+                content = res.content;
+            }
+            else {
+                const res = await this.transport.createConversation(text, this.browserSessionId);
+                this.state.conversationId = res.conversationId;
+                content = res.content;
+            }
+            assistant.content = content;
+            assistant.isStreaming = false;
+            this.updateMessage(assistant);
+            this.setStatus('ready');
+            return content;
+        }
+        catch (err) {
+            if (!assistant.content) {
+                this.removeMessage(assistant.id);
+            }
+            else {
+                assistant.isStreaming = false;
+                this.updateMessage(assistant);
+            }
+            this.handleError(err);
+            return '';
+        }
+    }
+    appendMessage(message) {
+        this.state.messages = [...this.state.messages, message];
+        this.emit({ type: 'message_added', message });
+        this.emitStateChange();
+    }
+    updateMessage(message) {
+        this.state.messages = this.state.messages.map((m) => m.id === message.id ? message : m);
+        this.emit({ type: 'message_updated', message });
+        this.emitStateChange();
+    }
+    removeMessage(messageId) {
+        this.state.messages = this.state.messages.filter((m) => m.id !== messageId);
+        this.emit({ type: 'message_removed', messageId });
+        this.emitStateChange();
+    }
+    setStatus(status) {
+        if (this.state.status === status)
+            return;
+        this.state.status = status;
+        this.emitStateChange();
+    }
+    emitStateChange() {
+        this.emit({ type: 'state', state: this.getState() });
+    }
+    handleError(err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const code = err && typeof err === 'object' && 'code' in err
+            ? String(err.code)
+            : undefined;
+        this.state.lastError = message;
+        this.state.status = 'error';
+        this.emit({ type: 'error', message, code });
+        this.emitStateChange();
+    }
+    emit(event) {
+        for (const listener of this.listeners) {
+            try {
+                listener(event);
+            }
+            catch {
+                // A bad subscriber shouldn't take the whole session down.
+            }
+        }
+    }
+}
+exports.ChatSession = ChatSession;
+/** Extract the text delta out of a server stream chunk. */
+function extractDelta(chunk) {
+    if (typeof chunk.delta === 'string')
+        return chunk.delta;
+    if (typeof chunk.text === 'string')
+        return chunk.text;
+    return '';
+}
+function makeMessageId(prefix) {
+    return `${prefix}_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+function generateBrowserSessionId() {
+    // Web crypto in browser/node 19+; fallback for ancient environments.
+    const c = globalThis.crypto;
+    if (c?.randomUUID)
+        return c.randomUUID();
+    return `${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}
+function defaultApiBase() {
+    if (typeof window === 'undefined')
+        return undefined;
+    // When the SDK is bundled into the AgentForge-served widget, it loads from
+    // the API origin — so the same origin is the natural default. Consumers in
+    // their own app will pass `apiBaseUrl` explicitly.
+    return window.location.origin;
+}

package/dist/transport.d.ts

@@ -0,0 +1,85 @@
+import type { ChatAgentSummary, ChatTheme } from './entities';
+/**
+ * Raw chunk shape produced by AgentForge's streaming endpoint. Mirrors
+ * @agentforge-io/core StreamChunk loosely — we only consume the fields that
+ * actually move state on the client.
+ */
+export interface ServerStreamChunk {
+    type: string;
+    delta?: string;
+    text?: string;
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+        totalTokens?: number;
+    };
+    [key: string]: unknown;
+}
+export type StreamEvent = {
+    kind: 'conversation';
+    id: string;
+} | {
+    kind: 'chunk';
+    chunk: ServerStreamChunk;
+} | {
+    kind: 'done';
+} | {
+    kind: 'error';
+    message: string;
+};
+export interface TransportError extends Error {
+    status: number;
+    code?: string;
+}
+/**
+ * Thin HTTP layer over the public chat endpoints. Knows nothing about state —
+ * it just hits the wire and yields whatever the server sends. The session
+ * layer above turns these events into entities + UI state.
+ */
+export declare class HttpTransport {
+    private readonly apiBaseUrl;
+    private readonly token;
+    constructor(apiBaseUrl: string, token: string);
+    private url;
+    getAgent(): Promise<{
+        agent: ChatAgentSummary;
+        theme?: ChatTheme;
+    }>;
+    /**
+     * Open a conversation and stream the first reply. Yields a `conversation`
+     * event first (with the new id), then assistant chunks, then `done`. Maps
+     * server-side `event: error` frames to a thrown `TransportError`.
+     */
+    streamCreateConversation(content: string, browserSessionId: string): AsyncGenerator<StreamEvent>;
+    streamSendMessage(conversationId: string, content: string, browserSessionId: string): AsyncGenerator<StreamEvent>;
+    /**
+     * Non-streaming fallbacks. Useful when the consumer disabled `stream`
+     * (e.g. running in environments without `ReadableStream`) or as a manual
+     * retry path after a streaming error.
+     */
+    createConversation(content: string, browserSessionId: string): Promise<{
+        conversationId: string;
+        content: string;
+    }>;
+    sendMessage(conversationId: string, content: string, browserSessionId: string): Promise<{
+        content: string;
+    }>;
+    /**
+     * Fetch a previously-opened conversation's transcript. Returns null when
+     * the conversation has been deleted, never existed, or belongs to another
+     * browser session — the SDK treats that as "start fresh".
+     */
+    getConversation(conversationId: string, browserSessionId: string): Promise<{
+        id: string;
+        status: string;
+        messages: Array<{
+            id: string;
+            role: 'user' | 'assistant' | 'system';
+            content: string;
+            createdAt: string;
+        }>;
+    } | null>;
+    endConversation(conversationId: string, browserSessionId: string): Promise<void>;
+    /** Parse the server's SSE response body into typed events. */
+    private readSse;
+}

package/dist/transport.js

@@ -0,0 +1,235 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpTransport = void 0;
+function makeTransportError(message, status, code) {
+    const err = new Error(message);
+    err.status = status;
+    err.code = code;
+    return err;
+}
+/**
+ * Thin HTTP layer over the public chat endpoints. Knows nothing about state —
+ * it just hits the wire and yields whatever the server sends. The session
+ * layer above turns these events into entities + UI state.
+ */
+class HttpTransport {
+    constructor(apiBaseUrl, token) {
+        this.apiBaseUrl = apiBaseUrl;
+        this.token = token;
+    }
+    url(path) {
+        const base = this.apiBaseUrl.replace(/\/+$/, '');
+        return `${base}/public/chat/${encodeURIComponent(this.token)}${path}`;
+    }
+    async getAgent() {
+        const res = await fetch(this.url('/agent'), { method: 'GET' });
+        const data = await safeJson(res);
+        if (!res.ok) {
+            throw makeTransportError((data && data.message) ?? `HTTP ${res.status}`, res.status, data?.error);
+        }
+        return {
+            agent: data.agent,
+            theme: data.theme ?? undefined,
+        };
+    }
+    /**
+     * Open a conversation and stream the first reply. Yields a `conversation`
+     * event first (with the new id), then assistant chunks, then `done`. Maps
+     * server-side `event: error` frames to a thrown `TransportError`.
+     */
+    async *streamCreateConversation(content, browserSessionId) {
+        const res = await fetch(this.url('/conversations/stream'), {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ content, browserSessionId }),
+        });
+        yield* this.readSse(res);
+    }
+    async *streamSendMessage(conversationId, content, browserSessionId) {
+        const res = await fetch(this.url(`/conversations/${encodeURIComponent(conversationId)}/messages/stream`), {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ content, browserSessionId }),
+        });
+        yield* this.readSse(res);
+    }
+    /**
+     * Non-streaming fallbacks. Useful when the consumer disabled `stream`
+     * (e.g. running in environments without `ReadableStream`) or as a manual
+     * retry path after a streaming error.
+     */
+    async createConversation(content, browserSessionId) {
+        const res = await fetch(this.url('/conversations'), {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ initialMessage: content, browserSessionId }),
+        });
+        const data = await safeJson(res);
+        if (!res.ok) {
+            throw makeTransportError(data?.message ?? `HTTP ${res.status}`, res.status, data?.error);
+        }
+        return {
+            conversationId: data.conversation.id,
+            content: extractAssistantText(data.firstResponse),
+        };
+    }
+    async sendMessage(conversationId, content, browserSessionId) {
+        const res = await fetch(this.url(`/conversations/${encodeURIComponent(conversationId)}/messages`), {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ content, browserSessionId }),
+        });
+        const data = await safeJson(res);
+        if (!res.ok) {
+            throw makeTransportError(data?.message ?? `HTTP ${res.status}`, res.status, data?.error);
+        }
+        return { content: extractAssistantText(data) };
+    }
+    /**
+     * Fetch a previously-opened conversation's transcript. Returns null when
+     * the conversation has been deleted, never existed, or belongs to another
+     * browser session — the SDK treats that as "start fresh".
+     */
+    async getConversation(conversationId, browserSessionId) {
+        const qs = new URLSearchParams({ browserSessionId });
+        const res = await fetch(this.url(`/conversations/${encodeURIComponent(conversationId)}?${qs}`), { method: 'GET' });
+        if (res.status === 404)
+            return null;
+        const data = await safeJson(res);
+        if (!res.ok) {
+            throw makeTransportError(data?.message ?? `HTTP ${res.status}`, res.status, data?.error);
+        }
+        return {
+            id: data.conversationId,
+            status: data.status,
+            messages: (data.messages ?? []).map((m) => ({
+                id: m.id,
+                role: m.role,
+                content: m.content,
+                createdAt: m.createdAt,
+            })),
+        };
+    }
+    async endConversation(conversationId, browserSessionId) {
+        const res = await fetch(this.url(`/conversations/${encodeURIComponent(conversationId)}/end`), {
+            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);
+        }
+    }
+    /** Parse the server's SSE response body into typed events. */
+    async *readSse(res) {
+        if (!res.ok) {
+            const data = await safeJson(res);
+            throw makeTransportError(data?.message ?? `HTTP ${res.status}`, res.status, data?.error);
+        }
+        if (!res.body) {
+            throw makeTransportError('Streaming not supported in this environment', 500);
+        }
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        try {
+            while (true) {
+                const { value, done } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                // SSE messages are separated by a blank line. Pull complete messages
+                // off the buffer; leave anything trailing for the next chunk.
+                let sepIdx;
+                while ((sepIdx = buffer.indexOf('\n\n')) !== -1) {
+                    const raw = buffer.slice(0, sepIdx);
+                    buffer = buffer.slice(sepIdx + 2);
+                    const evt = parseSseMessage(raw);
+                    if (!evt)
+                        continue;
+                    if (evt.event === 'conversation') {
+                        yield { kind: 'conversation', id: evt.data.id };
+                    }
+                    else if (evt.event === 'error') {
+                        yield { kind: 'error', message: evt.data?.message ?? 'stream error' };
+                    }
+                    else if (evt.event === 'done') {
+                        yield { kind: 'done' };
+                    }
+                    else {
+                        yield { kind: 'chunk', chunk: evt.data };
+                    }
+                }
+            }
+        }
+        finally {
+            try {
+                reader.releaseLock();
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+}
+exports.HttpTransport = HttpTransport;
+/**
+ * Parse one SSE frame (lines separated by `\n` inside the frame, frames
+ * separated by `\n\n`). Tolerates the `id:` line we emit and ignores
+ * comment lines. Returns null on unparseable / empty frames.
+ */
+function parseSseMessage(raw) {
+    if (!raw.trim())
+        return null;
+    let event = 'message';
+    const dataLines = [];
+    for (const line of raw.split('\n')) {
+        if (line.startsWith(':'))
+            continue; // SSE comment
+        const colon = line.indexOf(':');
+        if (colon === -1)
+            continue;
+        const field = line.slice(0, colon);
+        const value = line.slice(colon + 1).trimStart();
+        if (field === 'event')
+            event = value;
+        else if (field === 'data')
+            dataLines.push(value);
+        // `id` and `retry` are valid SSE fields but we don't use them client-side.
+    }
+    if (dataLines.length === 0)
+        return null;
+    const dataStr = dataLines.join('\n');
+    try {
+        return { event, data: JSON.parse(dataStr) };
+    }
+    catch {
+        // Server should never emit non-JSON, but if it does, surface as a string.
+        return { event, data: dataStr };
+    }
+}
+async function safeJson(res) {
+    try {
+        return await res.json();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Anthropic-style responses sometimes return content as a string and
+ * sometimes as an array of content blocks. Normalize to a single string.
+ */
+function extractAssistantText(response) {
+    if (!response)
+        return '';
+    if (typeof response.content === 'string')
+        return response.content;
+    if (Array.isArray(response.content)) {
+        return response.content
+            .map((c) => (typeof c === 'string' ? c : c?.text ?? ''))
+            .join('');
+    }
+    return '';
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@agentforge-io/chat-sdk",
+  "version": "0.1.0",
+  "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",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "default": "./dist/react.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "build:watch": "tsc -p tsconfig.build.json --watch",
+    "clean": "rm -rf dist *.tgz"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/react": "^18.3.28",
+    "react": "^18.3.1",
+    "typescript": "^5.0.0"
+  }
+}