@observertc/observer-js 1.0.0-beta.17 → 1.0.0-beta.18

package/README.md

@@ -262,7 +262,10 @@ deliberately distinct:
 
 - **`appData`** — application-assigned extra info that identifies/decorates an entity, fixed at
   creation (via `settings.appData` or the `createCallAppData` / `createClientAppData` factories),
-  or assigned by the app on the `*-added` events. The library never changes it.
+  or assigned by the app on the `*-added` events. The library never changes it. The factories
+  **receive the context of the `accept()` that triggered the creation**, so a fact carried on the
+  context can be baked into `appData` at birth — but it is copied by the factory, deliberately, not
+  written across by the library.
 - **`context`** — passed per `accept()`, may differ on every call, and is carried straight
   through to the `*-updated` events that the `accept()` triggers, then discarded.
 
@@ -470,8 +473,8 @@ type ObserverConfig<AppData = Record<string, unknown>> = {
     callSummary?: Partial<CallSummaryConfig> | null;
     // appData factories — run when an entity is created without explicit appData
     // (incl. lazily by accept()). appData is application-owned; accept `context` never touches it.
-    createCallAppData?: (p: { callId: string; observer: Observer }) => Record<string, unknown>;
-    createClientAppData?: (p: { clientId: string; observedCall: ObservedCall }) => Record<string, unknown>;
+    createCallAppData?: (p: { callId: string; observer: Observer; acceptCtx?: AcceptContext }) => Record<string, unknown>;
+    createClientAppData?: (p: { clientId: string; observedCall: ObservedCall; acceptCtx?: AcceptContext }) => Record<string, unknown>;
     // sink factory — produces a per-client sink that receives every accepted sample (see Sinks).
     createClientSink?: (p: { clientId: string; observedCall: ObservedCall }) => ClientSampleSink | undefined;
     // remote-track-resolver factory — produces a call's RemoteTrackResolver (see Remote track resolution).
@@ -480,26 +483,36 @@ type ObserverConfig<AppData = Record<string, unknown>> = {
 ```
 
 **appData factories.** Instead of pre-creating a call/client (or assigning on `call-added` /
-`client-added`) just to enrich its `appData`, register a factory once. It runs in the entity's
-constructor whenever it's created without an explicit `settings.appData` — including the lazy
-creation inside `accept()`. The `client` factory receives the already-created parent
-`observedCall`, so it can derive fields from it. `appData` is application-owned and is never
-modified by the `accept()` context.
+`client-added`) just to enrich its `appData`, register a factory once. It runs whenever the entity
+is created without an explicit `settings.appData` — including the lazy creation inside `accept()`.
+The `client` factory receives the already-created parent `observedCall`, so it can derive fields
+from it.
+
+Both also receive **`acceptCtx`**: the [`AcceptContext`](#context-the-acceptcontext) of the
+`accept()` that caused the creation, or `undefined` when you created the entity yourself. This is
+what lets an [accept middleware](#accept-middlewares-global-pre-dispatch-hook) resolve something
+once — a tenant, a trace id — and have it land in `appData` at birth, instead of every factory
+re-deriving it from the sample.
 
 ```ts
 const observer = new Observer({
-  createCallAppData:   ({ callId })                 => ({ callId, startedAt: Date.now(), region: 'eu' }),
-  createClientAppData: ({ clientId, observedCall }) => ({ clientId, region: observedCall.appData.region }),
+  createCallAppData:   ({ callId, acceptCtx })      => ({ callId, startedAt: Date.now(), tenant: acceptCtx?.tenant }),
+  createClientAppData: ({ clientId, observedCall }) => ({ clientId, tenant: observedCall.appData.tenant }),
 });
+
+observer.accept(sample, { tenant: 'acme' });
 ```
 
+`appData` stays application-owned: the context is *offered* to the factory, never written across by
+the library, and it is still not stored on any entity.
+
 Key members:
 
 - `accept(sample: ClientSample, context?: AcceptContext): void`
 - `addAcceptMiddleware(...mw: AcceptMiddleware[]): this` / `removeAcceptMiddleware(...mw): this` — global pre-dispatch sample hooks (see [Accept middlewares](#accept-middlewares-global-pre-dispatch-hook))
 - `getObservedCall<T>(callId): ObservedCall<T> | undefined`
-- `createObservedCall<T>(settings): ObservedCall<T> | undefined`
-- `getOrCreateObservedCall<T>(settings): ObservedCall<T> | undefined`
+- `createObservedCall<T>(settings, acceptCtx?): ObservedCall<T> | undefined`
+- `getOrCreateObservedCall<T>(settings, acceptCtx?): ObservedCall<T> | undefined`
 - `addIssue(issue: Omit<ObserverIssue, 'scope'>): void` — raise an **observer-level** finding → emits `observer-issue`. `scope` is stamped for you
 - `update(): void` — force an aggregation/`observer-updated` tick
 - `addObserverDetector(name, config?): this` — build a cross-call detector onto `observer.detectors`
@@ -544,7 +557,7 @@ Key members:
 
 - `readonly callId: string`, `appData: AppData`
 - `readonly observedClients: Map<string, ObservedClient>`, `get numberOfClients()`
-- `getObservedClient<T>(clientId)`, `createObservedClient<T>(settings)`, `getOrCreateObservedClient<T>(settings)` (all `… | undefined`)
+- `getObservedClient<T>(clientId)`, `createObservedClient<T>(settings, acceptCtx?)`, `getOrCreateObservedClient<T>(settings, acceptCtx?)` (all `… | undefined`)
 - `addIssue(issue: Omit<CallIssue, 'scope'>): void` — raise a **call-level** finding → emits `call-issue`. `scope` is stamped for you
 - `addDetector(name, config?): this` — build a call-scoped detector onto this call only
 - `removeDetector(name): number` — remove it from this call, `close()`ing it. For one specific

package/dist/index.d.mts

@@ -4952,8 +4952,8 @@ declare class ObservedCall<AppData extends Record<string, unknown> = Record<stri
     addIssue(issue: Omit<CallIssue, 'scope'>): void;
     close(): void;
     getObservedClient<ClientAppData extends Record<string, unknown> = Record<string, unknown>>(clientId: string): ObservedClient<ClientAppData> | undefined;
-    createObservedClient<ClientAppData extends Record<string, unknown> = Record<string, unknown>>(settings: ObservedClientSettings<ClientAppData>): ObservedClient<ClientAppData> | undefined;
-    getOrCreateObservedClient<ClientAppData extends Record<string, unknown> = Record<string, unknown>>(settings: ObservedClientSettings<ClientAppData>): ObservedClient<ClientAppData> | undefined;
+    createObservedClient<ClientAppData extends Record<string, unknown> = Record<string, unknown>>(settings: ObservedClientSettings<ClientAppData>, acceptCtx?: AcceptContext): ObservedClient<ClientAppData> | undefined;
+    getOrCreateObservedClient<ClientAppData extends Record<string, unknown> = Record<string, unknown>>(settings: ObservedClientSettings<ClientAppData>, acceptCtx?: AcceptContext): ObservedClient<ClientAppData> | undefined;
     update(context?: AcceptContext): void;
     private _onClientUpdate;
     private _clientJoined;
@@ -5430,11 +5430,13 @@ type AcceptMiddleware = Middleware<AcceptMiddlewarePayload>;
 type CallAppDataFactory = (params: {
     callId: string;
     observer: Observer;
+    acceptCtx?: AcceptContext;
 }) => Record<string, unknown>;
 /** Produces the initial `appData` for a client created without an explicit `appData`. */
 type ClientAppDataFactory = (params: {
     clientId: string;
     observedCall: ObservedCall;
+    acceptCtx?: AcceptContext;
 }) => Record<string, unknown>;
 type ObserverConfig<AppData extends Record<string, unknown> = Record<string, unknown>> = {
     appData?: AppData;
@@ -5661,8 +5663,13 @@ declare class Observer<AppData extends Record<string, unknown> = Record<string,
      */
     cancelValidator(target: keyof AvailableValidatorConfigs | RunningValidator, reason?: string): number;
     getObservedCall<T extends Record<string, unknown> = Record<string, unknown>>(callId: string): ObservedCall<T> | undefined;
-    createObservedCall<T extends Record<string, unknown> = Record<string, unknown>>(settings: ObservedCallSettings<T>): ObservedCall<T> | undefined;
-    getOrCreateObservedCall<T extends Record<string, unknown> = Record<string, unknown>>(settings: ObservedCallSettings<T>): ObservedCall<T> | undefined;
+    /**
+     * @param acceptCtx the `accept()` context, when this call is being created to receive a sample.
+     * Passed on to `ObserverConfig.createCallAppData`, so the factory can read whatever the caller (or
+     * an accept middleware) put there — a tenant, a region, a trace id.
+     */
+    createObservedCall<T extends Record<string, unknown> = Record<string, unknown>>(settings: ObservedCallSettings<T>, acceptCtx?: AcceptContext): ObservedCall<T> | undefined;
+    getOrCreateObservedCall<T extends Record<string, unknown> = Record<string, unknown>>(settings: ObservedCallSettings<T>, acceptCtx?: AcceptContext): ObservedCall<T> | undefined;
     createObservedMediasoupRouter<T extends Record<string, unknown> = Record<string, unknown>>(settings: ObservedMediasoupRouterSettings<T> & {
         matchPeerConnectionByWebRtcTransportId?: boolean;
     }): ObservedMediasoupRouter<Record<string, unknown>> | undefined;

package/dist/index.d.ts

@@ -4952,8 +4952,8 @@ declare class ObservedCall<AppData extends Record<string, unknown> = Record<stri
     addIssue(issue: Omit<CallIssue, 'scope'>): void;
     close(): void;
     getObservedClient<ClientAppData extends Record<string, unknown> = Record<string, unknown>>(clientId: string): ObservedClient<ClientAppData> | undefined;
-    createObservedClient<ClientAppData extends Record<string, unknown> = Record<string, unknown>>(settings: ObservedClientSettings<ClientAppData>): ObservedClient<ClientAppData> | undefined;
-    getOrCreateObservedClient<ClientAppData extends Record<string, unknown> = Record<string, unknown>>(settings: ObservedClientSettings<ClientAppData>): ObservedClient<ClientAppData> | undefined;
+    createObservedClient<ClientAppData extends Record<string, unknown> = Record<string, unknown>>(settings: ObservedClientSettings<ClientAppData>, acceptCtx?: AcceptContext): ObservedClient<ClientAppData> | undefined;
+    getOrCreateObservedClient<ClientAppData extends Record<string, unknown> = Record<string, unknown>>(settings: ObservedClientSettings<ClientAppData>, acceptCtx?: AcceptContext): ObservedClient<ClientAppData> | undefined;
     update(context?: AcceptContext): void;
     private _onClientUpdate;
     private _clientJoined;
@@ -5430,11 +5430,13 @@ type AcceptMiddleware = Middleware<AcceptMiddlewarePayload>;
 type CallAppDataFactory = (params: {
     callId: string;
     observer: Observer;
+    acceptCtx?: AcceptContext;
 }) => Record<string, unknown>;
 /** Produces the initial `appData` for a client created without an explicit `appData`. */
 type ClientAppDataFactory = (params: {
     clientId: string;
     observedCall: ObservedCall;
+    acceptCtx?: AcceptContext;
 }) => Record<string, unknown>;
 type ObserverConfig<AppData extends Record<string, unknown> = Record<string, unknown>> = {
     appData?: AppData;
@@ -5661,8 +5663,13 @@ declare class Observer<AppData extends Record<string, unknown> = Record<string,
      */
     cancelValidator(target: keyof AvailableValidatorConfigs | RunningValidator, reason?: string): number;
     getObservedCall<T extends Record<string, unknown> = Record<string, unknown>>(callId: string): ObservedCall<T> | undefined;
-    createObservedCall<T extends Record<string, unknown> = Record<string, unknown>>(settings: ObservedCallSettings<T>): ObservedCall<T> | undefined;
-    getOrCreateObservedCall<T extends Record<string, unknown> = Record<string, unknown>>(settings: ObservedCallSettings<T>): ObservedCall<T> | undefined;
+    /**
+     * @param acceptCtx the `accept()` context, when this call is being created to receive a sample.
+     * Passed on to `ObserverConfig.createCallAppData`, so the factory can read whatever the caller (or
+     * an accept middleware) put there — a tenant, a region, a trace id.
+     */
+    createObservedCall<T extends Record<string, unknown> = Record<string, unknown>>(settings: ObservedCallSettings<T>, acceptCtx?: AcceptContext): ObservedCall<T> | undefined;
+    getOrCreateObservedCall<T extends Record<string, unknown> = Record<string, unknown>>(settings: ObservedCallSettings<T>, acceptCtx?: AcceptContext): ObservedCall<T> | undefined;
     createObservedMediasoupRouter<T extends Record<string, unknown> = Record<string, unknown>>(settings: ObservedMediasoupRouterSettings<T> & {
         matchPeerConnectionByWebRtcTransportId?: boolean;
     }): ObservedMediasoupRouter<Record<string, unknown>> | undefined;

package/dist/index.js

@@ -4475,7 +4475,7 @@ var ObservedCall = class extends import_events3.EventEmitter {
     if (this.closed || !this.observedClients.has(clientId)) return;
     return this.observedClients.get(clientId);
   }
-  createObservedClient(settings) {
+  createObservedClient(settings, acceptCtx) {
     if (this.closed) {
       logger4.warn("Attempted to create a client (clientId: %s) on a closed call %s", settings.clientId, this.callId);
       return void 0;
@@ -4484,15 +4484,18 @@ var ObservedCall = class extends import_events3.EventEmitter {
       logger4.warn("Client with id %s already exists in call %s; returning the existing instance", settings.clientId, this.callId);
       return this.observedClients.get(settings.clientId);
     }
-    if (!settings.closeClientIfIdleForMs) {
-      settings.closeClientIfIdleForMs = this.observer.config.closeClientIfIdleForMs;
-    }
-    if (settings.appData === void 0) {
-      settings.appData = this.observer.config.createClientAppData?.({ clientId: settings.clientId, observedCall: this });
-    }
+    const clientSettings = {
+      ...settings,
+      closeClientIfIdleForMs: settings.closeClientIfIdleForMs || this.observer.config.closeClientIfIdleForMs,
+      appData: settings.appData ?? this.observer.config.createClientAppData?.({
+        clientId: settings.clientId,
+        observedCall: this,
+        acceptCtx
+      })
+    };
     const observedClientIssueRegistry = new ObservedClientIssueRegistry(this.activeIssuesRegistry);
     const result = new ObservedClient(
-      settings,
+      clientSettings,
       this,
       observedClientIssueRegistry
     );
@@ -4539,8 +4542,8 @@ var ObservedCall = class extends import_events3.EventEmitter {
     }
     return result;
   }
-  getOrCreateObservedClient(settings) {
-    return this.getObservedClient(settings.clientId) ?? this.createObservedClient(settings);
+  getOrCreateObservedClient(settings, acceptCtx) {
+    return this.getObservedClient(settings.clientId) ?? this.createObservedClient(settings, acceptCtx);
   }
   update(context) {
     if (this.closed) return;
@@ -6788,7 +6791,12 @@ var Observer = class extends import_events6.EventEmitter {
     if (this.closed || !this.observedCalls.has(callId)) return;
     return this.observedCalls.get(callId);
   }
-  createObservedCall(settings) {
+  /**
+   * @param acceptCtx the `accept()` context, when this call is being created to receive a sample.
+   * Passed on to `ObserverConfig.createCallAppData`, so the factory can read whatever the caller (or
+   * an accept middleware) put there — a tenant, a region, a trace id.
+   */
+  createObservedCall(settings, acceptCtx) {
     if (this.closed) {
       logger9.warn("Attempted to create a call (callId: %s) on a closed observer", settings.callId);
       return void 0;
@@ -6800,7 +6808,7 @@ var Observer = class extends import_events6.EventEmitter {
     const callSettings = {
       ...settings,
       closeCallIfEmptyForMs: settings.closeCallIfEmptyForMs ?? this.config.closeCallIfEmptyForMs,
-      appData: settings.appData ?? this.config.createCallAppData?.({ callId: settings.callId, observer: this })
+      appData: settings.appData ?? this.config.createCallAppData?.({ callId: settings.callId, observer: this, acceptCtx })
     };
     const callActiveIssuesRegistry = new ActiveIssuesRegistry(this.activeIssuesRegistry);
     const observedCall = new ObservedCall(
@@ -6827,8 +6835,8 @@ var Observer = class extends import_events6.EventEmitter {
     this._notify("call-added", { ...this.eventScope, observedCall });
     return observedCall;
   }
-  getOrCreateObservedCall(settings) {
-    return this.getObservedCall(settings.callId) ?? this.createObservedCall(settings);
+  getOrCreateObservedCall(settings, acceptCtx) {
+    return this.getObservedCall(settings.callId) ?? this.createObservedCall(settings, acceptCtx);
   }
   createObservedMediasoupRouter(settings) {
     if (this.closed) {
@@ -6895,21 +6903,9 @@ var Observer = class extends import_events6.EventEmitter {
       this._notify("sample-rejected", { ...this.eventScope, reason: "missing-clientId", sample });
       return;
     }
-    let call = this.getObservedCall(sample.callId);
-    if (!call) {
-      call = this.createObservedCall({
-        callId: sample.callId,
-        appData: this.config.createCallAppData?.({ callId: sample.callId, observer: this })
-      });
-    }
+    const call = this.getOrCreateObservedCall({ callId: sample.callId }, context);
     if (!call) return;
-    let client = call.getObservedClient(sample.clientId);
-    if (!client) {
-      client = call.createObservedClient({
-        clientId: sample.clientId,
-        appData: this.config.createClientAppData?.({ clientId: sample.clientId, observedCall: call })
-      });
-    }
+    const client = call.getOrCreateObservedClient({ clientId: sample.clientId }, context);
     if (!client) return;
     client.accept(sample, context);
   }