@origonai/web-sdk 0.1.0 → 0.1.1

package/docs/contract.md

@@ -38,6 +38,65 @@ 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.
 
+## Live-chat monitoring LCM-2 hardcut candidate
+
+- The unpublished candidate is generated from workspace wave base
+  `a7a731d62cc938f8221d3749cbf7b05474f0f9b4` plus the coordinated dirty
+  LCM-2 proto/golden inputs by
+  `web/kit/scripts/ship-orpc.sh`; `src/orpc-gen/PROVENANCE` pins the candidate
+  proto and both golden-fixture hashes. It remains unpublished and is consumed
+  only through the exact local links recorded in the workspace artifact ledger;
+  monitoring endpoint/lifecycle activation remains LCM-3.
+- `Message.metadata` and `TypingEvent.metadata` are required server outputs,
+  with audience exactly `internal|all`; missing or unknown output metadata fails
+  closed. Current ordinary calls inject `all`. CX additionally accepts an
+  omitted `MessageRequest.metadata` or `TypingRequest.metadata` only from an
+  authenticated participant-purpose legacy client and normalizes it to `all`;
+  monitor-purpose omission remains invalid.
+- `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
 
 The active in-workspace consumer is `workspace/web/cx` Insights Live. Its

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.1",
   "description": "Origon Web SDK - chat and voice session client",
   "type": "module",
   "packageManager": "pnpm@11.5.1",