@origonai/web-sdk 0.1.0 → 0.1.2

package/README.md

@@ -2,7 +2,7 @@
 
 Origon Web SDK — chat and voice session client for browsers.
 
-> **Status**: v0.5.0 (unpublished). Chat (orpc over WebTransport) and
+> **Status**: v0.6.0 (unpublished). Chat (orpc over WebTransport) and
 > voice (WebTransport + WASM Opus) are both implemented — see
 > [Status](#status). **WebTransport is required for both channels**;
 > browsers without it (Safari, Firefox today) are unsupported.
@@ -25,6 +25,7 @@ const client = getSessionManager()
 client.initialize({
   endpoint: 'https://your-backend.example.com',
   token: '<bearer>',     // optional; omit for anonymous users
+  // attachmentBaseUrl: '/cx/core/chat/attachment', // authenticated agent lane
   userId: '<your-id>',   // optional; auto-generated UUID v7 if not provided
   bundleId: 'com.example.app',
 })
@@ -34,13 +35,13 @@ await client.authenticate()
 client.setCallbacks({
   onMessageAdded: (sessionId, channel, msg) => render(msg),
   onMessageUpdated: (sessionId, channel, { id, message }) => update(id, message),
-  onTyping: (sessionId, channel, isTyping) => setTyping(isTyping),
+  onTyping: (sessionId, channel, update) => setTyping(update),
   onDisconnected: (sessionId, channel, { reason }) => console.log('closed:', reason),
 })
 
 const { sessionId } = await client.startSession({ channel: 'chat' })
 
-await client.sendMessage(sessionId, { text: 'Hello!' })
+await client.sendMessage(sessionId, { text: 'Hello!' }) // participant server defaults audience to all
 
 client.notifyTyping(sessionId)   // call on each keystroke; SDK debounces
 
@@ -57,7 +58,7 @@ await client.endSession(sessionId)
 
 ### Sessions
 - `startSession({ channel, sessionId?, data? })` — originate a chat or voice session (issues `POST /session/start`)
-- `joinSession({ channel, sessionId, url, token, voice? })` — attach to a session provisioned out of band, skipping `POST /session/start`; `voice.receiveOnly` starts playout with no microphone and awaits server uplink mute before connecting (see [Joining a provisioned session](#joining-a-provisioned-session))
+- `joinSession({ channel, sessionId, url, token, chat?, voice? })` — attach to a session provisioned out of band, skipping `POST /session/start`; `chat.recovery` opts into caller-authorized server-replay recovery, while `voice.receiveOnly` starts playout with no microphone and awaits server uplink mute before connecting (see [Joining a provisioned session](#joining-a-provisioned-session))
 - `endSession(sessionId)` — close a session
 - `endAllSessions()` — close every active session
 - `migrateSessionId(oldId, newId)` — re-key a live session whose id the control plane reassigned mid-call, without a media re-dial
@@ -67,18 +68,25 @@ await client.endSession(sessionId)
 - `getSession(sessionId)` — GET `/session/{id}` (transcript + control)
 
 ### Chat
-- `sendMessage(sessionId, payload)` — post a message; SDK fires `onMessageAdded` immediately with `status: 'sending'`, then `onMessageUpdated` with `'delivered'` or `'failed'` after the server acks
-- `notifyTyping(sessionId)` — call on each keystroke; SDK debounces (3s window) and emits typing on/off automatically
+- `sendMessage(sessionId, payload)` — post a message with optional `metadata: {audience}`; ordinary participant sends omit it and the server resolves the audience to `all`. The SDK fires `onMessageAdded` immediately with `status: 'sending'`, then `onMessageUpdated` with `'delivered'` or `'failed'` after the server acks
+- `notifyTyping(sessionId, metadata?)` — call on each keystroke; ordinary participant typing omits metadata, and the SDK debounces (3s window) and emits typing on/off automatically
 - `stopTyping(sessionId)` — flush typing-off immediately
 
 ### Attachments
-Attachments are **widget-scoped, not session-scoped** — both verbs address the
-`endpoint` given to `initialize()` and need no live session, so a file can be the
-first thing a visitor sends.
+Attachments are not session-scoped. With no `attachmentBaseUrl`, both verbs use
+the widget `endpoint` lane and suppress the top-level token, so a file can be the
+first thing a visitor sends. Authenticated consumers set a same-origin top-level
+`attachmentBaseUrl` (absolute or root-relative) together with the existing
+top-level token; upload and delete then send it as a bearer. Missing token,
+malformed, credential-bearing, query/hash,
+or cross-origin bases are rejected during `initialize()`, before any network.
 
 - `uploadAttachment(file, { uploadId, onProgress? })` — streamed upload with progress
 - `deleteAttachment(idOrUploadId)` — dual-purpose: cancels in-flight uploads if `idOrUploadId` matches a pending `uploadId`; otherwise DELETEs the stored attachment
 
+An uploaded `Attachment.url` is optional until the canonical message echo
+returns the server URL. `localUrl` remains the client-only preview.
+
 ## Callbacks
 
 `active` is directory liveness, not stored status. The SDK requires the field
@@ -93,7 +101,8 @@ consumer can host multiple sessions.
   // Chat
   onMessageAdded?: (sessionId, channel, message)
   onMessageUpdated?: (sessionId, channel, { id, message })
-  onTyping?: (sessionId, channel, isTyping)
+  onTyping?: (sessionId, channel, { participantId, role, userId, userName,
+                                   state, metadata: { audience } })
   onSessionUpdated?: (sessionId, channel)
 
   // Lifecycle (both channels — chat terminals land on onDisconnected too)
@@ -121,6 +130,14 @@ consumer can host multiple sessions.
 The outbound `payload.role` is a local-only hint for the provisional
 `onMessageAdded` row; it's stripped before POST.
 
+Message metadata is optional at both levels:
+`metadata?: { audience?: 'internal' | 'all' }`. Missing/null containers remain
+absent, while an explicitly present empty object remains `{}`; unknown
+non-empty audiences are protocol failures. A
+monitor client must always send an explicit known audience even though the
+shared SDK type is optional. Typing callbacks retain required audience plus
+participant identity; watchdogs are isolated by `participantId`.
+
 ## Errors
 
 REST-path errors are `ClientError` with a structured shape:
@@ -191,6 +208,26 @@ client.setCallbacks({ onConnected, onPeerAttached, onDisconnected })
 // `offer` = { sessionId, url, token }, delivered by your control channel.
 await client.joinSession({ channel: 'voice', ...offer })
 
+// Recoverable provisioned chat: the host re-runs its authenticated monitor
+// start request. The retry array is explicit and finite; every successful
+// refresh must return the same session id. CX Attach supplies full replay.
+await client.joinSession({
+  channel: 'chat',
+  ...monitorOffer,
+  chat: {
+    recovery: {
+      replay: 'server',
+      delaysMs: [0, 500, 1_000],
+      reauthorize: async ({ sessionId, attempt, generation, cause }) => {
+        const result = await refreshMonitor({ sessionId, attempt, generation, cause })
+        // Return `{sessionId,url,token}` or an authoritative terminal verdict:
+        // `{terminal:'ended'|'revoked'|'removed'|'capacity'}`.
+        return result
+      },
+    },
+  },
+})
+
 // Listen-only provisioned leg: starts the worklet + receive transport, never
 // asks for microphone permission, and fires onConnected only after MuteOk.
 await client.joinSession({
@@ -227,6 +264,17 @@ or unmute fails, the SDK returns to uplink-muted state and releases the local
 microphone. A late permission result cannot revive capture after Listen or
 disconnect wins.
 
+`chat.recovery` likewise changes only provisioned chat joins. Transport errors,
+clean FIN, `stream_overflow`, and an expired Attach credential serialize through
+the caller's `reauthorize` callback. Each response is fenced by a monotonic
+generation and must name the original session; changed-session credentials fail
+closed. Attach provides the authoritative ordered replay and the SDK dedupes it
+against already surfaced message ids, so this mode never calls visitor
+`POST /session/start` or `GET /session/:id`. `ended`, `revoked`, `removed`,
+`capacity`, and retry exhaustion are terminal. Close sends Leave only for a
+currently live Attach; a server-ended session only clears retained typing/UI
+state locally. Omitting `chat.recovery` preserves ordinary visitor recovery.
+
 ## Status
 
 - ✅ **Phase 1 — Chat** — orpc over WebTransport (protobuf wire),

package/dist/index.d.ts

@@ -2,7 +2,8 @@ export declare interface Attachment {
     id: string;
     name: string;
     contentType: string;
-    url: string;
+    /** Server URL; absent on a provisional upload until the canonical echo. */
+    url?: string;
     /**
      * Client-only preview source (`blob:`, `file://`) the UI can render
      * immediately. Stripped from outgoing wire bodies, preserved across
@@ -38,6 +39,9 @@ export declare interface AudioWorkletStats {
 
 export declare type Channel = 'chat' | 'voice';
 
+/** Closed audience vocabulary; the field holding it may be absent. */
+export declare type ChatAudience = 'internal' | 'all';
+
 export declare class ClientError extends Error {
     readonly kind: ClientErrorKind;
     readonly status?: number;
@@ -90,6 +94,12 @@ export declare interface Credentials {
     token?: string;
     userId?: string;
     attributes?: Record<string, unknown>;
+    /**
+     * Optional same-origin attachment route base for authenticated consumers
+     * (for example `/cx/core/chat/attachment`). When absent, uploads retain the
+     * widget endpoint and suppress any top-level token.
+     */
+    attachmentBaseUrl?: string;
     /**
      * Optional absolute base URL the voice assets are fetched from
      * (`<base>/audio/audio-processor.js` and
@@ -157,6 +167,8 @@ export declare interface JoinSessionOptions {
     token: string;
     /** Voice-only join behavior. Omit to retain the normal microphone join. */
     voice?: VoiceJoinOptions;
+    /** Chat-only recovery for a session provisioned by another control plane. */
+    chat?: ProvisionedChatJoinOptions;
 }
 
 export declare interface Message {
@@ -177,6 +189,7 @@ export declare interface Message {
     errorText?: string;
     status: MessageStatus;
     state: MessageState;
+    metadata?: MessageMetadata;
     /**
      * Lifecycle action for a `role:'system'` message — `'queued' | 'joined' |
      * 'ended'` (kept an open `string`: the server may add more; a distinct
@@ -230,6 +243,10 @@ export declare interface MessageCard {
     buttons: MessageButton[];
 }
 
+export declare interface MessageMetadata {
+    audience?: ChatAudience;
+}
+
 export declare type MessageRole = 'ai' | 'external' | 'user' | 'system';
 
 export declare type MessageState = 'streaming' | 'completed';
@@ -249,6 +266,52 @@ export declare class OrpcError extends Error {
     constructor(code: number, reason: string);
 }
 
+/** Additive options for an out-of-band provisioned chat join. */
+export declare interface ProvisionedChatJoinOptions {
+    recovery?: ProvisionedChatRecoveryOptions;
+}
+
+/** Why a provisioned chat needs fresh credentials. */
+export declare type ProvisionedChatRecoveryCause = 'transportError' | 'cleanFin' | 'streamOverflow' | 'unauthenticated';
+
+/** Explicit, finite provisioned-chat recovery policy. */
+export declare interface ProvisionedChatRecoveryOptions {
+    /**
+     * Re-run the caller's authenticated provision/start request. The SDK never
+     * substitutes visitor `/session/start` or history calls on this path.
+     */
+    reauthorize: (request: ProvisionedChatRecoveryRequest) => Promise<ProvisionedChatRecoveryResult>;
+    /** CX Attach supplies the authoritative full replay; no client history read. */
+    replay: 'server';
+    /**
+     * Delay before each attempt, in milliseconds. Must contain 1–8 finite,
+     * non-negative values; the array length is the hard attempt bound.
+     */
+    delaysMs: readonly number[];
+}
+
+/** Context passed to the caller-owned monitor start/reauthorization request. */
+export declare interface ProvisionedChatRecoveryRequest {
+    sessionId: string;
+    /** One-based position in the caller's explicit retry schedule. */
+    attempt: number;
+    /** Monotonic fence for discarding a refresh that resolves after close. */
+    generation: number;
+    cause: ProvisionedChatRecoveryCause;
+}
+
+/**
+ * A fresh same-session credential triple, or an authoritative terminal
+ * control-plane verdict. Thrown refresher errors are transient and consume the
+ * current retry slot.
+ */
+export declare type ProvisionedChatRecoveryResult = StartSessionResponse | {
+    terminal: ProvisionedChatTerminalReason;
+};
+
+/** Terminal control-plane verdicts that must never enter the retry ladder. */
+export declare type ProvisionedChatTerminalReason = 'ended' | 'revoked' | 'removed' | 'capacity';
+
 /**
  * Optional callbacks the SDK fires through `SessionManager.setCallbacks`.
  * All callbacks receive `sessionId` and `channel` as their first two args
@@ -262,8 +325,8 @@ export declare interface SdkCallbacks {
         id: string;
         message: Message;
     }) => void;
-    /** Inbound typing indicator from the peer (debounced by SDK watchdog). */
-    onTyping?: (sessionId: string, channel: Channel, isTyping: boolean) => void;
+    /** Participant-aware inbound typing update (debounced by a per-participant watchdog). */
+    onTyping?: (sessionId: string, channel: Channel, update: TypingUpdate) => void;
     /** Session id changed (e.g. server promoted a temp id, or reattach assigned a new one). */
     onSessionUpdated?: (sessionId: string, channel: Channel) => void;
     onConnected?: (sessionId: string, channel: Channel) => void;
@@ -295,6 +358,8 @@ export declare interface SendMessagePayload {
     text?: string;
     html?: string;
     attachments?: Attachment[];
+    /** Optional for participant callers; monitor callers must supply an audience. */
+    metadata?: MessageMetadata;
     /**
      * Local-only hint for the provisional `onMessageAdded` role. Defaults to
      * `'external'` when absent; staff dashboards set `'user'`. Stripped before
@@ -333,6 +398,8 @@ export declare class SessionManager {
     private sessionHttp;
     private attributes;
     private assetBaseUrl;
+    private attachmentBaseUrl;
+    private attachmentBearer;
     private readonly dispatcher;
     private readonly sessions;
     private readonly pendingUploads;
@@ -387,7 +454,7 @@ export declare class SessionManager {
      */
     migrateSessionId(oldId: string, newId: string): void;
     sendMessage(sessionId: string, payload: SendMessagePayload): Promise<Message>;
-    notifyTyping(sessionId: string): void;
+    notifyTyping(sessionId: string, metadata?: TypingMetadata): void;
     stopTyping(sessionId: string): void;
     setMute(sessionId: string, scope: MuteScope): Promise<void>;
     /** Enable microphone coaching on a receive-only voice join. */
@@ -402,18 +469,17 @@ export declare class SessionManager {
      */
     subscribeAudioStats(sessionId: string, cb: (stats: AudioWorkletStats) => void): () => void;
     /**
-     * Upload an attachment. WIDGET-scoped and session-less: the URL is built
-     * from the `endpoint` given to `initialize()`, so an attachment can be the
-     * first thing a visitor sends — no session is opened, and none is required.
+     * Upload an attachment. It remains session-less: widget callers use the
+     * tokenless endpoint lane, while an explicit same-origin attachmentBaseUrl
+     * selects the authenticated agent lane and uses the top-level token.
      * Needs `authenticate()` only for the local policy precheck (absent config
      * defers the whole decision to the server).
      */
     uploadAttachment(file: File, options: UploadOptions): Promise<Attachment>;
     /**
      * Dual purpose: cancel an in-flight upload (when `idOrUploadId` matches a
-     * pending `uploadId`) OR DELETE a stored attachment by id. Widget-scoped and
-     * session-less on both arms, so a visitor can remove a file they attached
-     * before sending anything.
+     * pending `uploadId`) OR DELETE a stored attachment by id. The route/auth
+     * lane matches upload: explicit base is authenticated; widget is tokenless.
      */
     deleteAttachment(idOrUploadId: string): Promise<void>;
     private requireChatSession;
@@ -446,6 +512,20 @@ export declare interface StartSessionResponse {
     token: string;
 }
 
+export declare interface TypingMetadata {
+    audience: ChatAudience;
+}
+
+/** Participant-aware typing update; one participant never clears another. */
+export declare interface TypingUpdate {
+    participantId: string;
+    role: string;
+    userId: string;
+    userName: string;
+    state: 'on' | 'off';
+    metadata: TypingMetadata;
+}
+
 export declare interface UploadOptions {
     /** Caller-issued id used to cancel the upload via `delete_attachment`. */
     uploadId: string;