@chanl/widget-sdk 0.2.0-canary.0

package/README.md

@@ -0,0 +1,257 @@
+# @chanl/widget-sdk
+
+Embeddable chat + voice widget SDK for [Chanl AI](https://chanl.ai) agents. Powers the official Chanl chat widget and any custom integration.
+
+- **Embed script** — drop-in `<script>` tag, no build step required
+- **Headless client** — `createChanlClient()` for custom UIs
+- **React hooks** — `useChat` for React apps via the `/react` subpath
+- **Public-key auth** — designed for client-side embedding (no secrets in browser code)
+
+## Three ways to use it
+
+### 1. Embed script (zero setup)
+
+The fastest way to add a chat widget to any HTML page. Drop in two `<script>` tags and a Chanl agent appears in the bottom-right corner with a launcher button, iframe chat UI, and proactive messages.
+
+```html
+<script src="https://chat.channel.tel/widget/v1.js"></script>
+<script>
+  ChanlChat.init({
+    agentId: 'ag_xxx',
+    apiKey:  'pub_xxx',
+    theme:   'dark',
+  });
+</script>
+```
+
+The script is hosted at `chat.channel.tel/widget/v1.js`. It creates a launcher button + iframe and handles all the wiring. End users see only the widget — never the API key or backend URL.
+
+See [`docs/embed-script.md`](./docs/embed-script.md) for the full config and method reference.
+
+### 2. Headless client
+
+If you want to build your own chat UI, use the unified client directly. No iframe, no launcher — just the transport.
+
+```typescript
+import { createChanlClient } from '@chanl/widget-sdk';
+
+const client = createChanlClient({
+  agentId: 'ag_xxx',
+  apiKey:  'pub_xxx',
+});
+
+const session = await client.chat.createSession('ag_xxx');
+
+await client.chat.streamMessage(
+  session.sessionId,
+  'Hello, how can you help me?',
+  (chunk) => process.stdout.write(chunk),  // text deltas
+  (part)  => console.log('Tool:', part),   // tool calls + results
+);
+
+await client.chat.endSession(session.sessionId);
+```
+
+### 3. React hooks
+
+For React apps, the `/react` subpath ships three hooks. Pick the one that matches what you need:
+
+- **`useChat`** — text chat only. Zero browser audio deps. Safe for SSR / Node.
+- **`useVoice`** — voice call only. Pulls in `Worker` + `AudioContext` + audio codec deps; browser only.
+- **`useChanl`** — both, in one call. Convenience wrapper around the other two.
+
+**Why three hooks instead of one?** Voice transport depends on browser-only globals (`Worker`, `MediaStream`, `extendable-media-recorder`) that add ~100 KB of bundle weight and break SSR. Splitting by mode means text-only consumers get perfect tree-shaking and work anywhere; voice consumers opt in explicitly.
+
+```tsx
+// Text only — no voice deps in the bundle
+import { useChat } from '@chanl/widget-sdk/react';
+
+function ChatWidget({ agentId, apiKey }: { agentId: string; apiKey: string }) {
+  const { messages, isTyping, send, agentConfig } = useChat({ agentId, apiKey });
+
+  return (
+    <div>
+      {messages.map((m) => (
+        <div key={m.id}>{m.role}: {m.content}</div>
+      ))}
+      {isTyping && <div>Agent is typing...</div>}
+      <button onClick={() => send('Hello')}>Send</button>
+    </div>
+  );
+}
+```
+
+```tsx
+// Voice only — browser required
+import { useVoice } from '@chanl/widget-sdk/react';
+
+function VoicePanel({ agentId, apiKey }: { agentId: string; apiKey: string }) {
+  const {
+    voiceState,        // 'idle' | 'connecting' | 'active' | 'closed'
+    startVoice,
+    stopVoice,
+    toggleMute,
+    isMuted,
+    isAgentSpeaking,   // live speaking indicator
+    duration,          // seconds
+    error,
+  } = useVoice({ agentId, apiKey });
+
+  if (voiceState === 'idle') {
+    return <button onClick={() => startVoice()}>Start call</button>;
+  }
+
+  return (
+    <div>
+      <div>{isAgentSpeaking ? 'Agent is talking' : 'Listening...'}</div>
+      <div>{Math.floor(duration)}s</div>
+      <button onClick={toggleMute}>{isMuted ? 'Unmute' : 'Mute'}</button>
+      <button onClick={() => stopVoice()}>End call</button>
+      {error && <div>Error: {error.message}</div>}
+    </div>
+  );
+}
+```
+
+```tsx
+// Both modes — mode-switching UI
+import { useChanl } from '@chanl/widget-sdk/react';
+
+function ChatAndVoice({ agentId, apiKey }: { agentId: string; apiKey: string }) {
+  const {
+    // Text
+    messages, isTyping, send,
+    // Voice
+    voiceState, startVoice, stopVoice, toggleMute, isMuted, isAgentSpeaking, duration,
+    // Shared
+    agentConfig, error,
+  } = useChanl({ agentId, apiKey });
+
+  // Your UI — switch between text box and voice panel based on voiceState
+  return (
+    <div>
+      {voiceState === 'idle' ? (
+        <TextChat messages={messages} isTyping={isTyping} onSend={send} />
+      ) : (
+        <VoicePanel
+          state={voiceState}
+          isAgentSpeaking={isAgentSpeaking}
+          isMuted={isMuted}
+          duration={duration}
+          onToggleMute={toggleMute}
+          onStop={stopVoice}
+        />
+      )}
+      <button onClick={() => startVoice()}>Switch to voice</button>
+    </div>
+  );
+}
+```
+
+#### Identified users (Intercom-style)
+
+`useChat` and `useChanl` both accept `user` + `userHash` for passing verified end-user identity into the conversation. The backend verifies the HMAC, upserts a Customer by `externalId`, and exposes attributes as `{{customer:<key>}}` prompt variables.
+
+```tsx
+const { messages, send } = useChat({
+  agentId,
+  apiKey,
+  // Identified user — agent knows who they're talking to
+  user: {
+    externalId: 'user_42',
+    email: 'jane@example.com',
+    name: 'Jane Doe',
+    // Any additional attributes flow through as prompt variables
+  },
+  // HMAC-SHA256 of `user.externalId` using the workspace identity secret.
+  // Compute server-side; never ship the identity secret to the browser.
+  userHash: hashFromYourServer,
+  // Extra variables merged into prompt substitution
+  variables: { plan: 'pro', seat: 'admin' },
+  // Free-form metadata (pageUrl, source, etc.)
+  metadata: { pageUrl: window.location.pathname, source: 'dashboard' },
+});
+```
+
+**Why `userHash`?** Without verification, anyone who inspects your site could pass `externalId: 'admin_42'` and impersonate a user. The HMAC proves your server blessed this identity. Compute it server-side with the workspace identity secret from the Chanl dashboard; the SDK just forwards it.
+
+**Re-identification.** When `user.externalId` changes (e.g., user logs in / switches accounts), the SDK automatically ends the stale session so the next `send()` creates a fresh one with the new identity. No manual reset needed.
+
+## Install
+
+```bash
+npm install @chanl/widget-sdk
+```
+
+## Auth
+
+Two key types are supported:
+
+| Key prefix | Where to use | Notes |
+|------------|--------------|-------|
+| `pub_xxx`  | Browser code, embed script | Public key, no secret. Validated by an origin allowlist on the server. |
+| `ak_xxx.secret` | Server code | Has a secret. Never embed in client code. |
+
+The SDK auto-detects the prefix and uses the right header. Get keys from the Chanl dashboard under **API Keys**.
+
+## Config
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `agentId` | string | required | Chanl agent ID (`ag_xxx`) |
+| `apiKey`  | string | required | Public key (`pub_xxx`) for browser, API key (`ak_xxx.secret`) for server |
+| `baseUrl` | string | auto | Override the Chanl platform API URL. Auto-resolves to localhost during development and the production API otherwise. |
+
+For the embed script's full config (theme, position, color, proactive messages, agent overrides, etc.) see [`docs/embed-script.md`](./docs/embed-script.md).
+
+## Voice
+
+Voice transport (WebSocket + WebRTC + audio recording) is bundled in this package and gated behind explicit opt-in so text-only consumers don't ship the audio codec deps.
+
+Three access patterns, in order of abstraction:
+
+### High level: `useVoice` / `useChanl` React hooks
+
+Best for React apps. See the [React hooks section](#3-react-hooks) above.
+
+### Mid level: `createChanlClient().voice`
+
+The unified client exposes voice as a lazy getter, so importing the client doesn't trigger audio deps until you actually touch `.voice`.
+
+```typescript
+import { createChanlClient } from '@chanl/widget-sdk';
+
+const client = createChanlClient({ agentId: 'ag_xxx', apiKey: 'pub_xxx' });
+
+// First `.voice` access imports the VoiceClient module (browser only).
+const voice = client.voice;
+voice.on('transcript', (t) => console.log(t.text));
+await voice.start('ag_xxx');
+```
+
+### Low level: direct `VoiceClient` import
+
+For advanced consumers who want explicit control over instantiation.
+
+```typescript
+import { VoiceClient } from '@chanl/widget-sdk/voice';
+
+// Browser only — this import pulls in Worker + audio APIs.
+const voice = new VoiceClient('pub_xxx', { baseUrl: 'https://platform.channel.tel' });
+voice.on('transcript', (t) => console.log(t.text));
+await voice.start('ag_xxx');
+```
+
+### Built-in voice mode in the embed script
+
+The drop-in `<script src="chat.channel.tel/widget/v1.js">` loader does not currently expose voice mode in its default iframe UI — the `ChanlChat` global is text-only. If you want voice in a drop-in widget, render your own UI using `useVoice` / `useChanl` in a React app and mount it wherever you want. The `apps/chat-host` repo has a working `/test-voice` playground route that does exactly this.
+
+## Links
+
+- **Documentation**: <https://docs.chanl.ai>
+- **Live demo**: <https://chat.channel.tel>
+- **Issues**: <https://github.com/chanl-ai/chanl-sdk/issues>
+
+## License
+
+MIT © Chanl AI

package/dist/auth.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Auth helpers — pub_/ak_ key detection.
+ *
+ * - pub_xxx → public key, used in client-side embeds (browser-safe)
+ * - ak_xxx  → API key with secret, server-side only
+ *
+ * Both work with the platform API but use different headers.
+ */
+export type ApiKey = string;
+export interface AuthHeaders {
+    /** Headers to send with HTTP requests */
+    headers: Record<string, string>;
+    /** Query params to append (some endpoints require key in URL) */
+    queryParams: string;
+}
+/**
+ * Build auth headers for an API request.
+ * Auto-detects pub_ vs ak_ prefix.
+ */
+export declare function buildAuthHeaders(apiKey: ApiKey): AuthHeaders;
+/**
+ * Returns true if the key looks like a public key.
+ * Use this to gate client-side vs server-side flows.
+ */
+export declare function isPublicKey(apiKey: ApiKey): boolean;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,MAAM,MAAM,GAAG,MAAM,CAAC;AAE5B,MAAM,WAAW,WAAW;IAC1B,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,iEAAiE;IACjE,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,CAY5D;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEnD"}

package/dist/auth.js

@@ -0,0 +1,36 @@
+"use strict";
+/**
+ * Auth helpers — pub_/ak_ key detection.
+ *
+ * - pub_xxx → public key, used in client-side embeds (browser-safe)
+ * - ak_xxx  → API key with secret, server-side only
+ *
+ * Both work with the platform API but use different headers.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildAuthHeaders = buildAuthHeaders;
+exports.isPublicKey = isPublicKey;
+/**
+ * Build auth headers for an API request.
+ * Auto-detects pub_ vs ak_ prefix.
+ */
+function buildAuthHeaders(apiKey) {
+    const headers = { 'Content-Type': 'application/json' };
+    let queryParams = '';
+    if (apiKey.startsWith('pub_')) {
+        headers['x-public-key'] = apiKey;
+        queryParams = `publicKey=${encodeURIComponent(apiKey)}`;
+    }
+    else {
+        headers['x-api-key'] = apiKey;
+    }
+    return { headers, queryParams };
+}
+/**
+ * Returns true if the key looks like a public key.
+ * Use this to gate client-side vs server-side flows.
+ */
+function isPublicKey(apiKey) {
+    return apiKey.startsWith('pub_');
+}
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;AAeH,4CAYC;AAMD,kCAEC;AAxBD;;;GAGG;AACH,SAAgB,gBAAgB,CAAC,MAAc;IAC7C,MAAM,OAAO,GAA2B,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC;IAC/E,IAAI,WAAW,GAAG,EAAE,CAAC;IAErB,IAAI,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;QAC9B,OAAO,CAAC,cAAc,CAAC,GAAG,MAAM,CAAC;QACjC,WAAW,GAAG,aAAa,kBAAkB,CAAC,MAAM,CAAC,EAAE,CAAC;IAC1D,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,WAAW,CAAC,GAAG,MAAM,CAAC;IAChC,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC;AAClC,CAAC;AAED;;;GAGG;AACH,SAAgB,WAAW,CAAC,MAAc;IACxC,OAAO,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;AACnC,CAAC"}

package/dist/chat/chat-client.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Chanl Chat Client — Standalone, no npm dependencies.
+ * Handles session creation, streaming messages, and session lifecycle.
+ * Streaming protocol parser ported from platform-sdk/modules/chat.ts.
+ *
+ * Auth: public key via query param + x-public-key header.
+ */
+import type { ChatClientConfig, ChatSession, ResumedChatSession, ChatMessageResponse, CreateSessionInput, MessagePart } from '../types';
+export declare function createChatClient(config: ChatClientConfig): {
+    createSession(agentId: string, input?: CreateSessionInput): Promise<ChatSession>;
+    /**
+     * Resume an existing chat session via a previously-issued sessionToken.
+     *
+     * Returns the rehydrated session + message history + a *refreshed*
+     * sessionToken (rolling-window TTL). Caller MUST replace its stored
+     * token with the new one.
+     *
+     * Throws on any 4xx so the caller can fall back to createSession + post
+     * a `session-token-cleared` message to the parent loader.
+     */
+    resumeSession(interactionId: string, sessionToken: string): Promise<ResumedChatSession>;
+    streamMessage(sessionId: string, message: string, onChunk: (text: string) => void, onPart?: (part: MessagePart) => void): Promise<ChatMessageResponse>;
+    sendMessage(sessionId: string, message: string): Promise<ChatMessageResponse>;
+    endSession(sessionId: string): Promise<void>;
+    /**
+     * Identify a visitor mid-session — Intercom-style.
+     *
+     * Use case: the widget opened anonymously (no `user` payload at
+     * createSession), the visitor exchanged a few messages, and now the
+     * host app has authenticated them. The host calls this method with
+     * the user's identity + HMAC. The platform verifies, runs
+     * Lead → User conversion against its Customer record, and updates the
+     * interaction's customerId in place. The agent's NEXT reply on this
+     * same session picks up the new identity via the per-turn
+     * <customer> context block — no session recreation needed,
+     * conversation history preserved.
+     *
+     * Idempotent: re-calling with the same identity is a no-op. Reassigning
+     * to a different externalId reassigns the customer (account switch).
+     *
+     * Mirrors Intercom's window.Intercom('update', { user_id, user_hash }).
+     *
+     * @example
+     * await client.identify(sessionId, {
+     *   user: { externalId: 'host-uid', email: 'dean@…', name: 'Dean' },
+     *   userHash: '<HMAC-SHA256(externalId, workspaceIdentitySecret), minted on host server>',
+     * });
+     */
+    identify(sessionId: string, input: {
+        user: {
+            externalId: string;
+            email?: string;
+            name?: string;
+            avatarUrl?: string;
+            attributes?: Record<string, unknown>;
+        };
+        userHash?: string;
+    }): Promise<{
+        sessionId: string;
+        customerId: string;
+        created: boolean;
+    }>;
+    /**
+     * Fetch the message history for an existing session. Used by the chat-host
+     * iframe to restore a conversation thread on page reload — the session id
+     * is persisted in localStorage on the iframe origin and replayed here.
+     *
+     * Returns `null` if the session is unknown / expired / inaccessible — the
+     * caller should fall back to starting a fresh session in that case.
+     */
+    getMessages(sessionId: string): Promise<{
+        sessionId: string;
+        messages: Array<{
+            role: string;
+            content: string;
+            timestamp?: string | number;
+        }>;
+        toolCalls: unknown[];
+    } | null>;
+};
+//# sourceMappingURL=chat-client.d.ts.map

package/dist/chat/chat-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-client.d.ts","sourceRoot":"","sources":["../../src/chat/chat-client.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAChB,WAAW,EACX,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,WAAW,EACZ,MAAM,UAAU,CAAC;AAelB,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,gBAAgB;2BAc1C,MAAM,UACP,kBAAkB,GACzB,OAAO,CAAC,WAAW,CAAC;IA2BvB;;;;;;;;;OASG;iCAEc,MAAM,gBACP,MAAM,GACnB,OAAO,CAAC,kBAAkB,CAAC;6BA2BjB,MAAM,WACR,MAAM,WACN,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,WACtB,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,GACnC,OAAO,CAAC,mBAAmB,CAAC;2BAmBF,MAAM,WAAW,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;0BAiBvD,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOlD;;;;;;;;;;;;;;;;;;;;;;;OAuBG;wBAEU,MAAM,SACV;QACL,IAAI,EAAE;YAAE,UAAU,EAAE,MAAM,CAAC;YAAC,KAAK,CAAC,EAAE,MAAM,CAAC;YAAC,IAAI,CAAC,EAAE,MAAM,CAAC;YAAC,SAAS,CAAC,EAAE,MAAM,CAAC;YAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;SAAE,CAAC;QACtH,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,GACA,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC;IAkBvE;;;;;;;OAOG;2BAC0B,MAAM,GAAG,OAAO,CAAC;QAC5C,SAAS,EAAE,MAAM,CAAC;QAClB,QAAQ,EAAE,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAC;YAAC,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;SAAE,CAAC,CAAC;QAChF,SAAS,EAAE,OAAO,EAAE,CAAC;KACtB,GAAG,IAAI,CAAC;EAeZ"}

package/dist/chat/chat-client.js

@@ -0,0 +1,192 @@
+"use strict";
+/**
+ * Chanl Chat Client — Standalone, no npm dependencies.
+ * Handles session creation, streaming messages, and session lifecycle.
+ * Streaming protocol parser ported from platform-sdk/modules/chat.ts.
+ *
+ * Auth: public key via query param + x-public-key header.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createChatClient = createChatClient;
+const stream_parser_1 = require("./stream-parser");
+const auth_1 = require("../auth");
+// ── Helpers ──
+function unwrap(data) {
+    // Handle { success, data: { data: ... } } and { data: ... } formats
+    if (data?.data?.data)
+        return data.data.data;
+    if (data?.data)
+        return data.data;
+    return data;
+}
+// ── Chat Client ──
+function createChatClient(config) {
+    const { apiKey, baseUrl, user: configUser, userHash: configUserHash, anonymousId: configAnonymousId, } = config;
+    const base = baseUrl.replace(/\/$/, '');
+    const auth = (0, auth_1.buildAuthHeaders)(apiKey);
+    const qSep = (extra) => (auth.queryParams ? `${extra}&${auth.queryParams}` : extra);
+    return {
+        async createSession(agentId, input) {
+            // Merge config-level identity with per-call input.
+            // Per-call user/userHash override config-level (e.g. identify() after mount).
+            const body = {
+                ...(input || {}),
+                user: input?.user ?? configUser,
+                userHash: input?.userHash ?? configUserHash,
+                anonymousId: input?.anonymousId ?? configAnonymousId,
+            };
+            const res = await fetch(`${base}/api/v1/interactions/chat?${qSep(`agentId=${encodeURIComponent(agentId)}`)}`, { method: 'POST', headers: auth.headers, body: JSON.stringify(body) });
+            if (!res.ok)
+                throw new Error(`Create session failed (${res.status})`);
+            const raw = unwrap(await res.json());
+            return {
+                interactionId: raw.interactionId,
+                sessionId: raw.interactionId || raw.sessionId,
+                agentId: raw.agentId,
+                agentName: raw.agentName,
+                model: raw.model,
+                createdAt: raw.createdAt,
+                sessionToken: raw.sessionToken,
+            };
+        },
+        /**
+         * Resume an existing chat session via a previously-issued sessionToken.
+         *
+         * Returns the rehydrated session + message history + a *refreshed*
+         * sessionToken (rolling-window TTL). Caller MUST replace its stored
+         * token with the new one.
+         *
+         * Throws on any 4xx so the caller can fall back to createSession + post
+         * a `session-token-cleared` message to the parent loader.
+         */
+        async resumeSession(interactionId, sessionToken) {
+            const url = `${base}/api/v1/interactions/${encodeURIComponent(interactionId)}/resume?${qSep(`sessionToken=${encodeURIComponent(sessionToken)}`)}`;
+            const res = await fetch(url, { method: 'GET', headers: auth.headers });
+            if (!res.ok) {
+                // 403 (bad sig / wrong workspace / identity transition) | 404
+                // (interaction missing or ended) | 410 (token expired). Caller
+                // treats any of these as "create fresh session" + clear stored
+                // token.
+                const detail = await res.text().catch(() => '');
+                throw new Error(`Resume failed (${res.status}): ${detail.slice(0, 200)}`);
+            }
+            const raw = unwrap(await res.json());
+            return {
+                interactionId: raw.interactionId,
+                sessionId: raw.sessionId || raw.interactionId,
+                agentId: raw.agentId,
+                agentName: raw.agentName,
+                status: raw.status,
+                createdAt: raw.createdAt || new Date().toISOString(),
+                messages: raw.messages || [],
+                sessionToken: raw.sessionToken,
+            };
+        },
+        async streamMessage(sessionId, message, onChunk, onPart) {
+            const start = Date.now();
+            const res = await fetch(`${base}/api/v1/interactions/${sessionId}/message?${qSep('stream=true')}`, { method: 'POST', headers: auth.headers, body: JSON.stringify({ message }) });
+            if (!res.ok)
+                throw new Error(`Stream failed (${res.status}): ${await res.text().catch(() => '')}`);
+            if (!res.body)
+                throw new Error('No response body');
+            const { text, parts, toolCalls } = await (0, stream_parser_1.parseStream)(res.body, onChunk, onPart);
+            return {
+                sessionId,
+                message: text,
+                parts: parts.length > 0 ? parts : undefined,
+                toolCalls: toolCalls.length > 0 ? toolCalls : undefined,
+                latencyMs: Date.now() - start,
+            };
+        },
+        async sendMessage(sessionId, message) {
+            const url = auth.queryParams
+                ? `${base}/api/v1/interactions/${sessionId}/message?${auth.queryParams}`
+                : `${base}/api/v1/interactions/${sessionId}/message`;
+            const res = await fetch(url, {
+                method: 'POST', headers: auth.headers, body: JSON.stringify({ message }),
+            });
+            if (!res.ok)
+                throw new Error(`Send failed (${res.status})`);
+            const raw = unwrap(await res.json());
+            return {
+                sessionId,
+                message: raw.message,
+                toolCalls: raw.toolCalls,
+                latencyMs: raw.latencyMs,
+            };
+        },
+        async endSession(sessionId) {
+            const url = auth.queryParams
+                ? `${base}/api/v1/interactions/${sessionId}/end?${auth.queryParams}`
+                : `${base}/api/v1/interactions/${sessionId}/end`;
+            await fetch(url, { method: 'POST', headers: auth.headers, body: '{}' }).catch(() => { });
+        },
+        /**
+         * Identify a visitor mid-session — Intercom-style.
+         *
+         * Use case: the widget opened anonymously (no `user` payload at
+         * createSession), the visitor exchanged a few messages, and now the
+         * host app has authenticated them. The host calls this method with
+         * the user's identity + HMAC. The platform verifies, runs
+         * Lead → User conversion against its Customer record, and updates the
+         * interaction's customerId in place. The agent's NEXT reply on this
+         * same session picks up the new identity via the per-turn
+         * <customer> context block — no session recreation needed,
+         * conversation history preserved.
+         *
+         * Idempotent: re-calling with the same identity is a no-op. Reassigning
+         * to a different externalId reassigns the customer (account switch).
+         *
+         * Mirrors Intercom's window.Intercom('update', { user_id, user_hash }).
+         *
+         * @example
+         * await client.identify(sessionId, {
+         *   user: { externalId: 'host-uid', email: 'dean@…', name: 'Dean' },
+         *   userHash: '<HMAC-SHA256(externalId, workspaceIdentitySecret), minted on host server>',
+         * });
+         */
+        async identify(sessionId, input) {
+            const url = auth.queryParams
+                ? `${base}/api/v1/interactions/${sessionId}/identify?${auth.queryParams}`
+                : `${base}/api/v1/interactions/${sessionId}/identify`;
+            const res = await fetch(url, {
+                method: 'POST',
+                headers: auth.headers,
+                body: JSON.stringify({ user: input.user, userHash: input.userHash }),
+            });
+            if (!res.ok)
+                throw new Error(`Identify failed (${res.status})`);
+            const raw = unwrap(await res.json());
+            return {
+                sessionId: raw.sessionId,
+                customerId: raw.customerId,
+                created: !!raw.created,
+            };
+        },
+        /**
+         * Fetch the message history for an existing session. Used by the chat-host
+         * iframe to restore a conversation thread on page reload — the session id
+         * is persisted in localStorage on the iframe origin and replayed here.
+         *
+         * Returns `null` if the session is unknown / expired / inaccessible — the
+         * caller should fall back to starting a fresh session in that case.
+         */
+        async getMessages(sessionId) {
+            const url = auth.queryParams
+                ? `${base}/api/v1/interactions/${sessionId}/messages?${auth.queryParams}`
+                : `${base}/api/v1/interactions/${sessionId}/messages`;
+            const res = await fetch(url, { method: 'GET', headers: auth.headers });
+            if (!res.ok)
+                return null;
+            const raw = unwrap(await res.json());
+            if (!raw || !Array.isArray(raw.messages))
+                return null;
+            return {
+                sessionId: raw.sessionId ?? sessionId,
+                messages: raw.messages,
+                toolCalls: Array.isArray(raw.toolCalls) ? raw.toolCalls : [],
+            };
+        },
+    };
+}
+//# sourceMappingURL=chat-client.js.map

package/dist/chat/chat-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-client.js","sourceRoot":"","sources":["../../src/chat/chat-client.ts"],"names":[],"mappings":"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"}

package/dist/chat/stream-parser.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Stream protocol parser for chat responses.
+ * Ported from platform-sdk/modules/chat.ts.
+ *
+ * Protocol:
+ *   0:"text delta"                                   - text chunk
+ *   9:{"toolCallId":"x","toolName":"y","args":{}}    - tool call started
+ *   a:{"toolCallId":"x","result":{...}}              - tool result
+ *   e:{"finishReason":"stop"}                        - stream finished
+ *
+ * Falls back to raw text mode if first chunk doesn't match protocol prefix.
+ */
+import type { MessagePart } from '../types';
+export interface ParseStreamResult {
+    text: string;
+    parts: MessagePart[];
+    toolCalls: unknown[];
+}
+export declare function parseStream(body: ReadableStream<Uint8Array>, onChunk: (text: string) => void, onPart?: (part: MessagePart) => void): Promise<ParseStreamResult>;
+//# sourceMappingURL=stream-parser.d.ts.map

package/dist/chat/stream-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-parser.d.ts","sourceRoot":"","sources":["../../src/chat/stream-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAkB,MAAM,UAAU,CAAC;AAE5D,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,SAAS,EAAE,OAAO,EAAE,CAAC;CACtB;AAED,wBAAsB,WAAW,CAC/B,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,EAChC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,EAC/B,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,GACnC,OAAO,CAAC,iBAAiB,CAAC,CA6G5B"}