@origonai/web-sdk 0.1.0 → 0.1.2

package/docs/contract.md

@@ -34,9 +34,69 @@ reciprocal cross-repository contract ledger.
 
 ## Release gate
 
-Run typecheck, unit tests, and the production build, then rebuild the linked
-`workspace/web/chat` consumer before publication. Publishing to npm remains an
-owner action and is never part of an implementation spin.
+Run typecheck, unit tests, and the production build, then rebuild both linked
+`workspace/web/chat` and `workspace/web/cx` consumers. Inspect the packed
+declarations and artifact bytes before publication. Publishing to npm remains
+an owner action and is never part of an implementation spin.
+
+## Live-chat monitoring and optional message metadata
+
+- Version 0.1.2 exposes optional `Message.metadata` and optional
+  `MessageMetadata.audience`. ORPC messages plus REST directory/history rows
+  normalize missing/null containers to `undefined`, while a present object with
+  a missing/null/empty audience remains `{}`. Lowercase `internal|all` is
+  preserved and every other non-empty value fails without trimming. Received
+  `TypingEvent.metadata` remains required and known.
+- Ordinary participant message and typing calls omit request metadata. CX
+  resolves participant-purpose omission to `all`; monitor-purpose omission is
+  invalid. Monitor consumers therefore validate and send an explicit
+  `internal|all` audience for every message and typing operation.
+- CX remains the authorization and projection boundary. Optional parsing never
+  authorizes an internal row for an external consumer, and newly authored CX
+  storage/events/replay/history/directory values remain explicit.
+- `onTyping` receives exactly `{participantId, role, userId, userName, state,
+  metadata}`. Inbound watchdogs are participant-keyed; one participant's off
+  or message cannot clear an unrelated participant.
+
+## Authenticated attachment lane
+
+- `Credentials.attachmentBaseUrl` is the only lane selector. It accepts an
+  HTTP(S) absolute or root-relative base only when its resolved origin exactly
+  matches `Credentials.endpoint`; credentials, query, fragment, raw/encoded/
+  backslash traversal, malformed encodings, and cross-origin inputs fail during
+  `initialize()` before network.
+- Selecting this authenticated lane requires the otherwise-optional top-level
+  token; omission fails during `initialize()`.
+- When the explicit base is present, XHR upload and fetch delete send the
+  existing top-level token as `Authorization: Bearer …`. When it is absent, the
+  widget endpoint lane suppresses the token even if one was supplied for other
+  APIs. Error surfaces redact the bearer.
+- Upload progress, cancellation-by-upload-id, and delete behavior are shared by
+  both lanes. An upload response may omit `Attachment.url`; the canonical chat
+  message echo is the first required server-URL carrier.
+
+## Provisioned chat recovery
+
+- `joinSession({channel:'chat', ..., chat:{recovery}})` is the only provisioned
+  recovery opt-in. `recovery` requires `replay:'server'`, an explicit 1–8 entry
+  finite non-negative `delaysMs` schedule, and caller-owned `reauthorize`.
+- Recoverable transport error, clean FIN, `stream_overflow`, and an
+  unauthenticated Attach serialize through that callback. Every invocation
+  carries the original `sessionId`, one-based attempt, monotonic generation,
+  and cause. A successful result must be a fresh `{sessionId,url,token}` for
+  that exact same session; a changed id, empty credential, or late generation
+  fails closed and is never attached.
+- `reauthorize` owns the authenticated monitor start request. The SDK never
+  calls visitor `POST /session/start` or `GET /session/:id` in provisioned
+  recovery. Attach is the authoritative full server replay; existing message
+  ids dedupe replay/live overlap while preserving stream order.
+- A callback may return `{terminal:'ended'|'revoked'|'removed'|'capacity'}`.
+  These, terminal Attach refusals, and exhausted schedules stop recovery.
+  Participant/audience typing watchdogs clear independently at each transport
+  boundary and terminal. Leave is sent only for a live Attach; after an in-band
+  `sessionEnded`, local close emits no Leave.
+- Omitting `chat.recovery` preserves ordinary visitor behavior exactly,
+  including overflow history reconciliation and same-id visitor re-mint.
 
 ## Provisioned receive-only voice join
 

package/docs/new-chat-protocol.md

@@ -12,8 +12,8 @@ arms that descriptor carries.
 | Direction | RPC (`chat.v1.Session/…`) | Payload |
 |-----------|-------------------------------|---------|
 | attach    | `Attach` (server-streaming)   | initial `AttachResponse {participantId, role}`, then one `ChatEvent` per frame |
-| send      | `Message` (unary)             | `MessageRequest {clientMessageId, text?, html?, attachments, value?, galleryLabel?}` → the canonical `Message` echo |
-| typing    | `Typing` (unary)              | `TypingRequest {state: "on"\|"off"}` |
+| send      | `Message` (unary)             | `MessageRequest {clientMessageId, text?, html?, attachments, value?, galleryLabel?, metadata:{audience}}` → the canonical `Message` echo |
+| typing    | `Typing` (unary)              | `TypingRequest {state: "on"\|"off", metadata:{audience}}` |
 | leave     | `Leave` (unary)               | empty; immediate server-side finalize |
 
 `ChatEvent` is a oneof: `message`, `typing`, `participant_joined`,
@@ -22,6 +22,21 @@ arms that descriptor carries.
 it does not know — is consumed and dropped. That tolerance is the
 forward-compat contract.
 
+The live-monitoring metadata is a deliberate hardcut: every `Message`,
+`MessageRequest`, `TypingRequest`, and `TypingEvent` carries audience
+`internal|all`. Missing/unknown audience fails closed. Ordinary visitor sends
+inject `all`; monitor callers can select `internal`. The public typing callback
+is the participant-aware `{participantId, role, userId, userName, state,
+metadata}` object, and watchdog state is keyed by participant.
+
+Provisioned monitor recovery is an SDK control seam, not a new wire arm. With
+`joinSession(... chat.recovery)`, transport error/FIN/overflow triggers a
+caller-owned reauthorization request followed by a fresh Attach. Attach replays
+the authoritative full transcript; the client never substitutes visitor
+history/start APIs. Existing message ids dedupe replay/live overlap, while the
+stream retains canonical sequence order. Ordinary visitor overflow recovery is
+unchanged.
+
 ## The extension rule: proto arms first
 
 **A chat feature does not exist until it has a proto arm.** The path for
@@ -80,7 +95,7 @@ default). Mapping vs. the legacy chat-sdk:
 `sendMessage`'s wire carrier is `MessageRequest`:
 `clientMessageId` (SDK-minted idempotency key), `text`, `html`,
 `attachments` (ids/names only — URLs are server-assigned on the echo),
-`value`, `galleryLabel`. The public payload surface also accepts the local
+`value`, `galleryLabel`, and required `metadata`. The public payload surface also accepts the local
 typed `buttonReply {value,label?}` adapter and maps it to those two top-level
 wire fields; the nested adapter never rides ORPC. Two other local-only fields
 are stripped before send: `role` (the provisional-row hint) and
@@ -89,3 +104,6 @@ SSE-era fields with no wire carrier (`type`/`results`/`meta`/`context`/
 `createSystem`/`mode`) were deleted with 0.5.0 (owner decision,
 2026-08-07) — a new outbound field starts with a proto arm, per the
 extension rule above.
+
+Accordingly, the public `Attachment.url` is optional on provisional/upload
+responses and becomes authoritative only on the canonical message echo.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@origonai/web-sdk",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Origon Web SDK - chat and voice session client",
   "type": "module",
   "packageManager": "pnpm@11.5.1",