@origonai/web-sdk 0.1.1 → 0.1.3

package/docs/backend-integration.md

@@ -82,7 +82,7 @@ Document a min-supported-browser policy with the product team.
 |---|---|---|
 | Bidi QUIC stream | `wt.createBidirectionalStream()` (client-opened) | ControlMessages — Connect, NegotiateMedia, Hold, Mute, SendDtmf, Resume + their `*Ok` + server-push |
 | QUIC datagrams | `wt.datagrams` (readable + writable streams) | Audio frames (one frame per datagram), uplink + downlink |
-| QUIC uni stream (server→client) | `wt.incomingUnidirectionalStreams` | DTMF events when the peer pressed a digit |
+| QUIC uni stream (server→client) | `wt.incomingUnidirectionalStreams` | Drained as unsupported protocol input; no public receive lane |
 | QUIC graceful close | `wt.close({ closeCode, reason })` | Hangup |
 
 Everything in [`client-integration.md`](client-integration.md) §4–§12 applies
@@ -154,8 +154,8 @@ After `ConnectOk` the bidi multiplexes:
 - Your verbs out (`Hold`, `Mute`, `SendDtmf`, `Resume`, `NegotiateMedia`).
 - Server `*Ok` responses (correlate by `request_id`).
 - Server-push events (`PeerAttached`, `PeerDetached`, `EndpointHeld`,
-  `EndpointMuted`, `PeerStateChanged`, `DtmfReceived`, `EndpointHangup`,
-  `MoqError`) — these carry `request_id = 0`.
+  `EndpointMuted`, `PeerStateChanged`, `EndpointHangup`, `MoqError`) — these
+  carry `request_id = 0`.
 
 A single read loop on `ctrl.readable.getReader()` is sufficient. Dispatch
 by `msg_type`.
@@ -232,30 +232,18 @@ manual PLC). Server never retransmits.
 
 ---
 
-## 6. DTMF inbound (unidirectional sub-stream)
+## 6. DTMF flow input
 
-DTMF *from a peer* arrives on a fresh server-initiated uni stream, one
-per digit:
+`SessionManager.sendDtmf(sessionId, digit)` sends exactly one symbol from
+`0-9*#A-D` as `SendDtmf` on the bidi control stream. It resolves only after
+the matching `SendDtmfOk`, which acknowledges Media publication to the active
+CX flow. Request-scoped Media errors reject only the matching call.
 
-```js
-const uniReader = wt.incomingUnidirectionalStreams.getReader()
-while (true) {
-  const { value: stream, done } = await uniReader.read()
-  if (done) break
-  // stream is a ReadableStream<Uint8Array>
-  handleDtmfUniStream(stream)        // decodes SubgroupHeader + DtmfEvent + EndOfGroup
-}
-```
-
-The framing on this stream is documented in
-[`docs/wire-protocol.md`](wire-protocol.md) §"Stream paths (non-audio)".
-The payload is a single `DtmfEvent { digit, duration_ms }` protobuf
-message.
-
-DTMF *to the server* (you pressing a digit) is the `SendDtmf` verb on
-the bidi control stream — not a uni stream. The browser cannot open
-WT uni sub-streams at all in some specs/browsers, so we never required
-it for the outbound direction.
+The request belongs to the WebTransport on which it was sent. A close rejects
+it; reconnect/Resume never queues or replays it, and a stale ACK is ignored.
+The SDK does not receive peer-generated DTMF, expose a DTMF callback, synthesize
+a tone, or imply PSTN/carrier delivery. Incoming uni streams are drained only
+to keep the transport healthy.
 
 ---
 
@@ -268,13 +256,12 @@ Same shape as native. See [`client-integration.md`](client-integration.md)
 |---|---|---|
 | `Hold { held: bool }` | Client → Server | `session.hold` |
 | `Mute { scope: Uplink \| Downlink \| Both \| None }` | Client → Server | `session.mute_self` |
-| `SendDtmf { digit, duration_ms }` | Client → Server | `dtmf_send` |
+| `SendDtmf { request_id, digit }` | Client → Server | `dtmf_send` |
 | `Resume { call_token, last_event_seq }` | Client → Server | (token only) |
 | `NegotiateMedia { offers, frame_size_ms }` | Client → Server | (token only; additive) |
 
-The corresponding `*Ok` responses carry the echoed `request_id`. Server
-pushes the matching state-change event (`EndpointHeld`, `EndpointMuted`,
-`PeerStateChanged`, `DtmfReceived`) for other peers' UI consistency.
+The corresponding `*Ok` responses carry the echoed `request_id`. DTMF has no
+peer receive event; `SendDtmfOk` acknowledges Media publication only.
 
 ---
 
@@ -446,7 +433,7 @@ async function startCall({ url, jwt, certHash /* optional */ }) {
   startBidiReadLoop(reader, dispatchEvent)              // server-push + verb Oks
   startDatagramSender(wt, audioAlias, serverEpochUnix)  // mic → Opus → datagram
   startDatagramReceiver(wt)                              // datagrams → decoders
-  startUniReceiver(wt)                                   // DTMF uni streams
+  startUniStreamDrain(wt)                                // unsupported server uni input
 
   // 5. Wait for session end
   wt.closed.then(info => onClosed(info), err => onError(err))

package/docs/contract.md

@@ -34,25 +34,47 @@ 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.
-
-## 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.
+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.
+
+## Internal voice DTMF wire codec
+
+- The browser codec encodes `SEND_DTMF=0x58` as
+  `requestId (QUIC varint) | digit (exactly one ASCII byte)` and decodes
+  `SEND_DTMF_OK=0x59` as the echoed request id only. The accepted alphabet is
+  exactly `0-9*#A-D`; empty, multi-byte, lowercase, non-ASCII, and trailing
+  bytes fail closed.
+- Request-scoped Media refusals remain the existing `MoqError` path:
+  `CapabilityMissing`, `IllegalState`, or `ResourceExhausted`. An ACK means
+  input acceptance for the owning CX flow, not peer delivery, tone playback,
+  or carrier forwarding.
+- `src/voice/wire/testdata/send_dtmf_golden.txt` is a byte-identical copy of
+  Media's producer-owned canonical fixture at
+  `core/media/modules/moq-endpoint/testdata/send_dtmf_golden.txt`.
+- `VoiceSession.sendDtmf(digit)` and
+  `SessionManager.sendDtmf(sessionId, digit)` expose the send-only API. Calls
+  reject during Resume, pending requests reject on transport close, and no
+  request is replayed on a replacement transport. There is no peer-receive
+  callback or tone playback. Media error-code changes and canonical fixture
+  changes therefore require a web-sdk consumer review.
+
+## 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.

package/docs/voice.md

@@ -5,7 +5,7 @@
 | Layer        | Tech                                                                 |
 |--------------|----------------------------------------------------------------------|
 | Transport    | WebTransport (`https://<media-server>/web`), one bidi control sub-stream + datagrams |
-| Control      | B2BUA verbs (Connect/ConnectOk/Mute/Resume/PeerAttached/…), `msg_type (vi) \| payload_len (vi) \| payload` |
+| Control      | B2BUA verbs (Connect/ConnectOk/Mute/Resume/SendDtmf/PeerAttached/…), `msg_type (vi) \| payload_len (vi) \| payload` |
 | Audio        | Opus 48 kHz mono, 20 ms frames (50 per wall-second), `ObjectDatagram` per frame |
 | Group / object IDs | `group_id = floor(Date.now()/1000) - server_epoch_unix`, `object_id ∈ [0..49]`, `end_of_group` on object 49 |
 | Reconnect    | Tier-3 `Resume { call_token, last_event_seq }` only — browsers expose no QUIC migration / 0-RTT |
@@ -13,6 +13,10 @@
 
 See [`backend-integration.md`](backend-integration.md) (canonical spec) for the full wire definitions.
 
+The internal `SendDtmf` codec carries one `0-9*#A-D` symbol and awaits its
+request-correlated ACK. It does not yet expose a public send method, receive
+callback, tone generator, duration control, or carrier-forwarding behavior.
+
 ## Required browser features (the SDK-wide floor)
 
 | Feature                | Needed by                                        |
@@ -128,6 +132,7 @@ const { sessionId } = await client.joinSession({
 })
 
 await client.setMute(sessionId, 'uplink')   // 'uplink' | 'downlink' | 'both' | 'none'
+await client.sendDtmf(sessionId, '#')       // exactly one of 0-9, *, #, A-D
 
 // For a provisioned receive-only join, enter and leave microphone capture
 // without exposing an unmuted permission/acquisition window.
@@ -147,6 +152,12 @@ await client.endSession(sessionId)
 
 ## Reconnect behaviour
 
+DTMF requests are transport-bound. Calls made during reconnect reject locally;
+an unacknowledged digit is rejected when its transport closes and is never
+replayed on the replacement transport. `SendDtmfOk` means CX-flow publication
+was accepted, not carrier delivery. There is no inbound DTMF callback or SDK
+tone playback.
+
 When `wt.closed` fires unexpectedly (no `EndpointHangup` or terminal `MoqError` arrived first), the SDK runs:
 
 ```

package/package.json

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