@observertc/observer-js 1.0.0-beta.10 → 1.0.0-beta.11

package/llms-full.txt

@@ -1,7 +1,7 @@
 # observer-js (@observertc/observer-js) — full documentation
 
 > Single-file export of the project's documentation for one-shot LLM ingestion.
-> Concatenates: README.md, docs/logging.md, CHANGELOG.md. Generated from source —
+> Concatenates: README.md, docs/logging.md, CHANGELOG.md. Generated by scripts/build-llms-full.mjs —
 > the canonical, always-current copies live in the repository; see llms.txt for the link index.
 
 ---
@@ -75,9 +75,10 @@ and emits a single, unified stream of typed events the application can react to.
 11. [Remote track resolution (mediasoup / SFU)](#remote-track-resolution-mediasoup--sfu)
 12. [Mediasoup router observation](#mediasoup-router-observation)
 13. [Sinks (per-client sample persistence)](#sinks-per-client-sample-persistence)
-14. [Logging](#logging)
-15. [Error-handling philosophy](#error-handling-philosophy)
-16. [Development & extension guide](#development--extension-guide)
+14. [Injecting data into a client](#injecting-data-into-a-client)
+15. [Logging](#logging)
+16. [Error-handling philosophy](#error-handling-philosophy)
+17. [Development & extension guide](#development--extension-guide)
 
 ---
 
@@ -381,7 +382,7 @@ additional field(s) on top of that scope.
 | Event | Extra | Fires when |
 |-------|-------|-----------|
 | `mediasoup-router-added` | — | `observer.createObservedMediasoupRouter(...)` registered a router |
-| `mediasoup-router-matched-with-peer-connection` | `{ observedCall, observedClient, observedPeerConnection }` | a newly added peer connection's id matched one of the router's WebRTC transport ids. |
+| `mediasoup-router-matched-with-peer-connection` | `{ observedCall, observedClient, observedPeerConnection }` | a newly added peer connection's id matched one of the router's WebRTC transport ids. **Opt-in** via `matchPeerConnectionByWebRtcTransportId: true`. |
 | `mediasoup-router-removed` | — | the underlying mediasoup router closed (its `router.observer` `close` fired) |
 
 See [Mediasoup router observation](#mediasoup-router-observation) for the full design and examples.
@@ -551,7 +552,7 @@ Key members:
 - `readonly sink?: ClientSampleSink` — the per-client sink (see [Sinks](#sinks-per-client-sample-persistence)), if `createClientSink` is configured; listen on it for `close`/`error`
 - **Injection API** (queue app data to be merged into the next sample processing):
   `injectEvent(ClientEvent)`, `injectIssue(ClientIssue)`, `injectMetaData(ClientMetaData)`,
-  `injectExtensionStat(ExtensionStat)`, `injectAttachment(key, value)`
+  `injectExtensionStat(ExtensionStat)`, `injectAttachment(attachments: Record<string, unknown>)`
 - **Direct add API** (process immediately): `addIssue(ClientIssue)`, `addMetadata(ClientMetaData)`,
   `addExtensionStats(ExtensionStat)`
 - Metrics (current/derived): `currentAvgRttInMs?`, `currentMinRttInMs?`, `currentMaxRttInMs?`,
@@ -844,11 +845,13 @@ ancestry, so you get the router **and** the matched `observedPeerConnection`, `o
 `observedCall` in one place. Stamp the `routerId` into the peer connection's / client's `appData`,
 build your own index, attach the server sample to the call in your database — whatever fits.
 
-How it works: as peer connections are observed (`peer-connection-added`), the observer checks whether
-the peer connection's id is one of the router's WebRTC transport ids. On a hit it emits — **once per
-matching peer connection** (de-duplicated by peer-connection id) — and keeps watching, so a router
-that serves many participants emits one match per participant's transport. The internal listener is
-removed automatically when the router closes or the observer closes.
+This matching is **opt-in**: pass `matchPeerConnectionByWebRtcTransportId: true` to
+`createObservedMediasoupRouter`. When enabled, as peer connections are observed
+(`peer-connection-added`) the observer checks whether the peer connection's id is one of the router's
+WebRTC transport ids; on a hit it emits — once per matching peer connection — and keeps watching, so a
+router serving many participants emits one match per participant's transport. When the flag is omitted
+or `false`, no matching is performed and the event never fires. The internal listener is removed
+automatically when the router closes or the observer closes.
 
 When the underlying mediasoup router closes, its `close` propagates to `ObservedMediasoupRouter`,
 which emits **`mediasoup-router-removed`**. That is your cue to do whatever cleanup or persistence
@@ -862,10 +865,11 @@ you want with the now-final `sample` — again, the observer itself keeps nothin
 | `routerId` | `string` | yes | your id for the router (the sample also carries `router.id`) |
 | `appData` | `Record<string, unknown>` | no | application-owned bag on the `ObservedMediasoupRouter` |
 | `attachments` | `Record<string, unknown>` | no | free-form data copied onto `sample.attachments` |
+| `matchPeerConnectionByWebRtcTransportId` | `boolean` | no | opt in to peer-connection matching: emit `mediasoup-router-matched-with-peer-connection` for each peer connection whose id matches one of the router's WebRTC transport ids. Omitted / `false` → no matching, the event never fires |
 
-Peer-connection matching is automatic — there is nothing to opt into. Returns the
-`ObservedMediasoupRouter`, or `undefined` if the observer is closed (a router with the same id
-returns the existing instance — both warn).
+Peer-connection matching is **off by default**; enable it with
+`matchPeerConnectionByWebRtcTransportId: true`. Returns the `ObservedMediasoupRouter`, or `undefined`
+if the observer is closed (a router with the same id returns the existing instance — both warn).
 
 Useful members on the returned object: `.sample` (the `MediasoupRouterSample`), `.appData`,
 `.attachments` (getter over `sample.attachments`), `.webrtcTransportIds: Set<string>`, `.id`,
@@ -882,9 +886,13 @@ const observer = new Observer();
 // 1) Feed client samples as usual so the observer knows about calls, clients & peer connections.
 //    (e.g. transport-layer: observer.accept(clientSample, context))
 
-// 2) Observe the SFU side. The observer auto-matches peer connections to this router's transports.
+// 2) Observe the SFU side, opting in to peer-connection matching for this router's transports.
 const router = /* your mediasoup router */ undefined as any;
-const observedRouter = observer.createObservedMediasoupRouter({ router, routerId: router.id });
+const observedRouter = observer.createObservedMediasoupRouter({
+  router,
+  routerId: router.id,
+  matchPeerConnectionByWebRtcTransportId: true,
+});
 
 // 3) Every peer connection whose id matches one of the router's WebRTC transport ids fires this —
 //    WE decide what to do with each pairing. The payload carries the full ancestry.
@@ -1043,6 +1051,60 @@ const observer = new Observer({ createClientSink });
 the bus with full ancestry. `ClientSampleSinkFactory` is
 `(p: { clientId: string; observedCall: ObservedCall }) => ClientSampleSink | undefined`.
 
+---
+
+## Injecting data into a client
+
+Sometimes the application holds data that belongs on a client's record but isn't part of the
+client-reported `ClientSample` — a room id or display name, an application-level event
+(*"recording started"*), a server-detected issue, an extension stat, or a device/meta item.
+`ObservedClient` exposes **injection** methods that merge such data into the client's sample stream,
+so it updates the live model **and** is persisted to the client's
+[sink](#sinks-per-client-sample-persistence) exactly like sampled data.
+
+| Method | Adds to the sample's | Surfaces as |
+|--------|----------------------|-------------|
+| `injectAttachment(attachments)` | `attachments` (merged via `Object.assign`) | `observedClient.attachments` |
+| `injectEvent(event: ClientEvent)` | `clientEvents` | `client-event` (plus any state the event drives) |
+| `injectIssue(issue: ClientIssue)` | `clientIssues` | `client-issue` |
+| `injectMetaData(meta: ClientMetaData)` | `clientMetaItems` | `client-metadata` |
+| `injectExtensionStat(stat: ExtensionStat)` | `extensionStats` | `client-extension-stats` |
+
+### When the injected data lands
+
+Injection is timing-aware so nothing is dropped, regardless of *when* you call it:
+
+- **During a sample's processing** — e.g. from inside a `client-updated` / `client-event` handler,
+  which run within `accept()` — the data is applied to the **current** sample immediately: reflected
+  in entity state and written to the sink as part of that sample.
+- **Between samples** — the data is buffered and merged into the **next** `accept()`'s sample.
+- **On `close()` with pending injections and no further sample** — the buffer is flushed as a final
+  synthetic sample (applied to state and written to the sink) before the sink is ended, so a
+  last-moment injection is never lost.
+
+In every case the injected data both updates the live `ObservedClient` and reaches the per-client
+sink — the sink always receives the final, **injection-merged** sample (the sink write happens at the
+end of `accept()`, after the merge).
+
+### Example
+
+```ts
+// Enrich at creation from your app's knowledge of the participant. Injecting in `client-added`
+// (which runs just before the first accept) lands on the first sample.
+observer.on('client-added', ({ observedClient }) => {
+  observedClient.injectAttachment({ roomId: lookupRoomId(observedClient.clientId) });
+});
+
+// Application-level signals at any time:
+const client = observer.getObservedCall(callId)?.getObservedClient(clientId);
+client?.injectEvent({ type: 'RECORDING_STARTED', timestamp: Date.now() });
+client?.injectIssue({ type: 'app-kicked-participant', timestamp: Date.now() });
+```
+
+`attachments` are latest-wins (like sampled `attachments`): injecting a key overwrites its previous
+value. `appData` is unaffected — injections flow into the sample/telemetry, not the app-owned
+`appData` bag (see [Ingestion](#ingestion-accept-context--lifecycle)).
+
 ## Logging
 
 `observer-js` logs through a single, swappable sink. Out of the box it writes `debug` and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@observertc/observer-js",
-  "version": "1.0.0-beta.10",
+  "version": "1.0.0-beta.11",
   "description": "Server-side Node.js library for processing ObserveRTC Samples",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -32,7 +32,8 @@
     "build": "tsup",
     "typecheck": "tsc --noEmit",
     "test": "jest --config jest.config.js",
-    "test:coverage": "jest --config jest.config.js --coverage"
+    "test:coverage": "jest --config jest.config.js --coverage",
+    "docs:llms-full": "node scripts/build-llms-full.mjs"
   },
   "keywords": [
     "webrtc",