@observertc/observer-js 1.3.0-rc.3 → 1.3.0-rc.4

package/README.md

@@ -404,7 +404,7 @@ See [Mediasoup router observation](#mediasoup-router-observation) for the full d
 | Event | Extra | Fires when |
 |-------|-------|-----------|
 | `client-added` | — | a client is created |
-| `client-sink-created` | `{ sink: Sink<ClientSample> }` | the client's sample sink was created by `createClientSink`; fires right after `client-added` |
+| `client-sink-created` | `{ sink: Sink<ClientSample> }` | the client's sample sink was created through `saveClientSamples`; fires right after `client-added` |
 | `client-updated` | `{ sample: ClientSample, elapsedTimeInMs: number, context?: AcceptContext }` | the client processed a sample |
 | `client-closed` | — | the client closed |
 | `client-joined` | — | first `CLIENT_JOINED` event seen |
@@ -480,7 +480,10 @@ type ObserverConfig<AppData = 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>;
     // a JSONL file per client: return its path, or undefined for none (see Sinks).
-    createClientSink?: (p: { id: string; clientId: string; observedCall: ObservedCall }) => SinkDestination<ClientSample> | undefined;
+    // where each client's samples are saved: exactly one of jsonlPath / sink, each a per-client callback (see Sinks).
+    saveClientSamples?:
+      | { jsonlPath: (p: { id: string; clientId: string; observedCall: ObservedCall }) => string | undefined }
+      | { sink: (p: { id: string; clientId: string; observedCall: ObservedCall }) => Sink<ClientSample> | undefined };
     // remote-track-resolver factory — produces a call's RemoteTrackResolver (see Remote track resolution).
     createRemoteTrackResolver?: (observedCall: ObservedCall) => RemoteTrackResolver | undefined;
   };
@@ -1947,7 +1950,7 @@ and never crashes the process.
 import type { Sink, SinkSettings } from '@observertc/observer-js';
 
 interface Sink<T = unknown> {          // typically: class X extends EventEmitter implements Sink<T>
-  readonly id: string;
+  readonly id: string;                 // unique per observer
   write(record: T): boolean;           // `false` once ended (nothing written), or on backpressure
   end(): void;                         // idempotent; MUST emit `ended` synchronously, then flush and emit `close`
   on / once / off(event, listener);    // the events below
@@ -1977,18 +1980,20 @@ its id — refuse writes after it, and emit `close` / `error` for its destinatio
 ### Client samples
 
 A client writes every accepted sample to the sink registered under its **client id** in its call's
-registry (`observedClient.sink` returns it), and ends that sink when it closes. `createClientSink`
-decides it, per client, by returning a **`SinkDestination`** — exactly one of `jsonlPath` and `sink`:
+registry (`observedClient.sink` returns it), and ends that sink when it closes. The
+**`saveClientSamples`** config option decides it — exactly one of two per-client callbacks, the same
+`jsonlPath` / `sink` pair as `createExtensionStats` takes:
 
-| Returns | Sink |
-|---------|------|
-| `{ jsonlPath }` | a JSONL file at that path: a `JsonlFileSink` created by the library under the client id |
-| `{ sink }` | your `Sink<ClientSample>`; its `id` must be `params.id`, the client id |
-| `undefined` | none |
+| `saveClientSamples` | Called per client with `{ id, observedCall, clientId }`, returns | Sink |
+|---------------------|------------------------------------------------------------------|------|
+| `{ jsonlPath }` | the path of the client's file, or `undefined` | a `JsonlFileSink` at that path, created by the library under the client id |
+| `{ sink }` | your `Sink<ClientSample>`, or `undefined` | that sink; its `id` must be `id` |
 
 ```ts
 const observer = new Observer({
-  createClientSink: ({ observedCall, clientId }) => ({ jsonlPath: `./stats/${observedCall.callId}__${clientId}.jsonl` }),
+  saveClientSamples: {
+    jsonlPath: ({ observedCall, clientId }) => `./stats/${observedCall.callId}__${clientId}.jsonl`,
+  },
 });
 
 observer.on('client-sink-created', ({ observedClient, sink }) => {
@@ -1996,10 +2001,15 @@ observer.on('client-sink-created', ({ observedClient, sink }) => {
 });
 ```
 
-`createClientSink` is called only when the client id is free as a sink id, so a clash opens no file.
-A returned sink with a different id is ended and not used. Giving both `jsonlPath` and `sink` is a
-compile error (and refused at runtime). For a JSONL file with a custom serializer, return
-`{ sink: new JsonlFileSink({ id, path, serializeSample }) }`.
+**A client's sample sink id is its client id.** The `id` the callbacks receive is that id, and
+with `jsonlPath` the library uses it for you. Sink ids are unique per observer, so **client ids
+must be unique across the observer's open calls** — client monitors generate uuids, so this
+normally holds. A client whose id is already a sink id gets no sink, and a warning is logged.
+
+The callback is called only when the id is free, so a clash opens no file; `undefined` gives that
+client no sink. A returned sink with a different id is ended and not used. Giving both `jsonlPath`
+and `sink` is a compile error (and refused at runtime). For a JSONL file with a custom serializer,
+use `sink: ({ id }) => new JsonlFileSink({ id, path, serializeSample })`.
 
 Any other destination works the same way — return your own implementation:
 
@@ -2031,7 +2041,9 @@ class HttpSink extends EventEmitter implements ClientSampleSink {
 }
 
 new Observer({
-  createClientSink: ({ id, clientId }) => ({ sink: new HttpSink({ id, url: `https://stats.example.com/${clientId}` }) }),
+  saveClientSamples: {
+    sink: ({ id, clientId }) => new HttpSink({ id, url: `https://stats.example.com/${clientId}` }),   // id: the client id
+  },
 });
 
 // Or later, on `client-added`, if the client has no sink yet:

package/dist/index.d.mts

@@ -59,6 +59,12 @@ type SinkDestination<T = unknown> = {
     sink: Sink<T>;
     jsonlPath?: never;
 };
+/** What the `saveClientSamples` callbacks receive: `id` is the client's sample sink id, the client id. */
+type ClientSinkParams<Call = unknown> = {
+    id: string;
+    observedCall: Call;
+    clientId: string;
+};
 
 /** A sink class `SinkRegistry.create` can construct: its constructor takes one settings object (with `id`). */
 type SinkConstructor = new (settings: any) => Sink<any>;
@@ -4004,7 +4010,7 @@ declare class ObservedClient<AppData extends Record<string, unknown> = Record<st
     /** The distinct `publicAddress`es currently known by this client's open peer connections. */
     /**
      * The sink this client's samples are written to: whatever is registered under its client id in
-     * `call.sinks` (the one `createClientSink` returned, or a sink the application added), if any.
+     * `call.sinks` (the one created through `saveClientSamples`, or a sink the application added), if any.
      */
     get sink(): Sink<ClientSample> | undefined;
     get publicAddresses(): string[];
@@ -5883,8 +5889,8 @@ declare class ObservedCall<AppData extends Record<string, unknown> = Record<stri
     private _onClientUpdate;
     private _clientJoined;
     private _clientLeft;
-    /** Emit an Observer-bus event scoped to this call. */
     private _createClientSink;
+    /** Emit an Observer-bus event scoped to this call. */
     private _notify;
 }
 
@@ -6445,6 +6451,14 @@ type ClientAppDataFactory = (params: {
     observedCall: ObservedCall;
     acceptCtx?: AcceptContext;
 }) => Record<string, unknown>;
+/** `ObserverConfig.saveClientSamples`: exactly one of the two per-client callbacks. */
+type SaveClientSamplesConfig = {
+    jsonlPath: (params: ClientSinkParams<ObservedCall>) => string | undefined;
+    sink?: never;
+} | {
+    sink: (params: ClientSinkParams<ObservedCall>) => Sink<ClientSample> | undefined;
+    jsonlPath?: never;
+};
 type ObserverConfig<AppData extends Record<string, unknown> = Record<string, unknown>> = {
     /**
      * Application-owned data for the observer itself. Never read or modified by the library.
@@ -6598,22 +6612,15 @@ type ObserverConfig<AppData extends Record<string, unknown> = Record<string, unk
     /** Same as `createCallAppData`, for clients. Receives the (already-created) parent call. */
     createClientAppData?: ClientAppDataFactory;
     /**
-     * The sink a newly-created client writes its samples to: `{ jsonlPath }` (a `JsonlFileSink` is
-     * created at that path under the client id), `{ sink }` (a `Sink` whose `id` is `params.id`, the
-     * client id), or `undefined` for none. The sink is added to `observedCall.sinks` and is ended
-     * when the client closes; `client-sink-created` announces it.
-     *
-     * ```ts
-     * createClientSink: ({ observedCall, clientId }) => ({ jsonlPath: `./stats/${observedCall.callId}__${clientId}.jsonl` }),
-     * ```
+     * Where each client's samples are saved: exactly one of `jsonlPath` (return the path of the
+     * client's JSONL file) and `sink` (return a sink whose `id` is `params.id`), each called per
+     * client; `undefined` gives that client no sink. See the README's *Sinks* section.
      *
-     * Called only when the client id is free as a sink id, so a clash opens no file.
+     * A client's sample sink id is its client id (`params.id`). Sink ids are unique per observer, so
+     * client ids must be unique across the observer's open calls; a client whose id is already a sink
+     * id gets no sink, and a warning is logged.
      */
-    createClientSink?: (params: {
-        id: string;
-        observedCall: ObservedCall;
-        clientId: string;
-    }) => SinkDestination<ClientSample> | undefined;
+    saveClientSamples?: SaveClientSamplesConfig;
     /**
      * Optional factory invoked when a call is created, producing the call's `RemoteTrackResolver`
      * (or `undefined` for none). Use the built-ins
@@ -7183,7 +7190,7 @@ declare function setObserverLogger(logger: ObserverLogger): void;
 /** The lifecycle events a client sample sink may emit. Same as {@link SinkEvents}. */
 type ClientSampleSinkEvents = SinkEvents;
 /**
- * A per-client destination for accepted samples. Return one from `ObserverConfig.createClientSink`
+ * A per-client destination for accepted samples. Return one from `ObserverConfig.saveClientSamples.sink`
  * (with the `id` it receives), or create one under the client id with
  * `observedCall.sinks.create(MySink, { id: clientId, ... })`.
  *
@@ -7253,4 +7260,4 @@ declare function createInMemorySink(samples?: ClientSample[]): InMemorySink;
 declare function createDefaultMediasoupRemoteTrackResolverFactory(): RemoteTrackResolverFactory;
 declare function createP2pRemoteTrackResolverFactory(): RemoteTrackResolverFactory;
 
-export { type AcceptContext, type AcceptMiddleware, type AcceptMiddlewarePayload, type ActiveClientIssue, type ActiveIssueTracker, ActiveIssuesRegistry, AudioEchoDetector, type AudioEchoDetectorConfig, AudioEchoTypes, type AudioInputDevice, type AvailableCallScopeDetectorsConfigs, type AvailableDetectorsConfigs, type AvailableObserverScopeDetectorsConfigs, type AvailableValidatorConfigs, CODEC_MISMATCH_ISSUE, type CalculatedScore, type CallAppDataFactory, CallConcurrentIssueDetector, type CallConcurrentIssueDetectorConfig, type CallConcurrentIssueGroup, CallConcurrentIssueTypes, type CallHealth, CallHealthAggregator, type CallIssue, type CallIssueSpread, type CallScopedEventName, type CallSummary, type CallSummaryClients, CallSummaryCollector, type CallSummaryConfig, type CallSummaryEnricher, type CallSummaryEnrichers, type CallSummaryScores, type CallSummarySection, type CallSummaryTruncation, type CallSummaryTurnServers, type CertificateStats, type ClientAppDataFactory, type ClientEvent, ClientEventTypes, type ClientHealth, type ClientHealthThresholds, type ClientIssue, type ClientLocation, type ClientLocationResolver, type ClientMetaData, ClientMetaTypes, type ClientPopulation, type ClientPopulationAxis, ClientPopulationIssueDetector, type ClientPopulationIssueDetectorConfig, ClientPopulationIssueTypes, type ClientSample, type ClientSampleSink, type ClientSampleSinkEvents, type CodecConsistencyReportPayload, CodecConsistencyValidator, type CodecConsistencyValidatorConfig, type CodecEvidence, type CodecStats, type CorroboratedPublisherFault, type CreateExtensionStatsSettings, type DataChannelStats, type Detector, Detectors, type ExtensionStat, ExtensionStatsRegistry, GEOHASH_CELL_SIZES, type IceCandidatePairStats, type IceCandidateStats, type IceTransportStats, InMemorySink, type InboundRtpStats, type InboundTrackSample, type Issue, type IssueBase, type IssueConclusion, IssueFanOutDetector, type IssueFanOutDetectorConfig, IssueFanOutTypes, type IssueFaultDomain, JsonlFileSink, type JsonlFileSinkOptions, LOWEST_COMMON_DENOMINATOR_ISSUE, type Logger, type MannKendallResult, type MediaKind, type MediaPlayoutStats, type MediaSourceStats, type MediasoupConsumerSample, type MediasoupConsumerSampleEvent, type MediasoupDataConsumerSample, type MediasoupDataProducerSample, type MediasoupDirectTransportSample, type MediasoupDirectTransportSampleEventMap, type MediasoupPipeTransportSample, type MediasoupPipeTransportSampleEventMap, type MediasoupPlainTransportSample, type MediasoupPlainTransportSampleEventMap, type MediasoupProducerSample, type MediasoupProducerSampleEvent, type MediasoupRouterSample, type MediasoupSampleEnricher, type MediasoupTransportSample, type MediasoupWebRtcTransportSample, type MediasoupWebRtcTransportSampleEventMap, type Middleware, MiddlewareProcessor, ObservedCall, type ObservedCallScope, type ObservedCallSettings, ObservedCertificate, ObservedClient, ObservedClientIssueRegistry, type ObservedClientScope, type ObservedClientSettings, ObservedCodec, ObservedDataChannel, ObservedIceCandidate, ObservedIceCandidatePair, ObservedIceTransport, ObservedInboundRtp, ObservedInboundTrack, ObservedMediaPlayout, ObservedMediaSource, ObservedMediasoupRouter, type ObservedMediasoupRouterEvents, type ObservedMediasoupRouterScope, type ObservedMediasoupRouterSettings, ObservedOutboundRtp, ObservedOutboundTrack, ObservedPeerConnection, type ObservedPeerConnectionScope, ObservedPeerConnectionTransport, ObservedRemoteInboundRtp, ObservedRemoteOutboundRtp, ObservedTURN, type ObservedTURNEventMap, ObservedTurnServer, Observer, ObserverConcurrentIssueDetector, type ObserverConcurrentIssueDetectorConfig, type ObserverConcurrentIssueGroup, ObserverConcurrentIssueTypes, type ObserverEventBase, type ObserverEvents, type ObserverIssue, type ObserverIssueSpread, type ObserverLogger, type OutboundRtpStats, type OutboundTrackSample, type PageHinkleyResult, type PeerConnectionSample, type PeerConnectionTransportStats, type PsnrSum, PublisherFaultCorroborationDetector, type PublisherFaultCorroborationDetectorConfig, PublisherFaultTypes, type QualityLimitationDurations, RESOLVED_ISSUE_SUFFIX, RTT_HISTOGRAM_BUCKET_WIDTH_IN_MS, RTT_HISTOGRAM_NUMBER_OF_BUCKETS, type RemoteInboundRtpStats, type RemoteOutboundRtpStats, type RemoteTrackLinkEvidence, RemoteTrackResolver, type RemoteTrackResolverFactory, type RemoteTrackResolverReportPayload, RemoteTrackResolverValidator, type RemoteTrackResolverValidatorConfig, type RemoteTrackResolvers, type ResolvedActiveClientIssue, type RttSummary, type RunningValidator, SCORE_HISTOGRAM_BUCKET_WIDTH, SCORE_HISTOGRAM_NUMBER_OF_BUCKETS, type SampleRejectedReason, type ScoreCalculator, type ScoreSummary, SfuCongestionDetector, type SfuCongestionDetectorBucket, type SfuCongestionDetectorConfig, type SfuCongestionDetectorEvaluation, type SfuCongestionDetectorReport, type SimulcastReceiverEvidence, type SimulcastReceiverReportPayload, SimulcastReceiverValidator, type SimulcastReceiverValidatorConfig, type Sink, type SinkConstructor, type SinkCreateSettings, type SinkDestination, type SinkEvents, SinkRegistry, type SinkSettings, SlidingWindow, type SlidingWindowEntry, type StatsSummary, TrackDeliveryMismatchDetector, type TrackDeliveryMismatchDetectorConfig, TrackDeliveryMismatchTypes, TrendTester, type TrendTesterConfig, type TurnServerHealth, TurnServerHealthDetector, type TurnServerHealthDetectorConfig, TurnServerHealthTypes, TurnServerOutageDetector, type TurnServerOutageDetectorConfig, TurnServerOutageTypes, UNRESOLVED_TRACK_LINKS_ISSUE, UnconsumedTrackDetector, type UnconsumedTrackDetectorConfig, UnconsumedTrackTypes, type ValidationReport, type Validator, type ValidatorName, baseIssueType, concludeCallIssue, concludeObserverIssue, correlation, counterDelta, createCallSummary, createDefaultMediasoupRemoteTrackResolverFactory, createInMemorySink, createJsonlFileSink, createLogger, createP2pRemoteTrackResolverFactory, defaultCallSummaryConfig, defaultClientHealthThresholds, geohash, isClientIssueResolutionEntry, isPublicIpAddress, issuePayloadAsString, mannKendall, mannKendallVerdict, median, medianAbsoluteDeviation, pageHinkley, percentile, percentileOfHistogram, percentileOfSorted, robustZScore, schemaVersion, setObserverLogger, summarize };
+export { type AcceptContext, type AcceptMiddleware, type AcceptMiddlewarePayload, type ActiveClientIssue, type ActiveIssueTracker, ActiveIssuesRegistry, AudioEchoDetector, type AudioEchoDetectorConfig, AudioEchoTypes, type AudioInputDevice, type AvailableCallScopeDetectorsConfigs, type AvailableDetectorsConfigs, type AvailableObserverScopeDetectorsConfigs, type AvailableValidatorConfigs, CODEC_MISMATCH_ISSUE, type CalculatedScore, type CallAppDataFactory, CallConcurrentIssueDetector, type CallConcurrentIssueDetectorConfig, type CallConcurrentIssueGroup, CallConcurrentIssueTypes, type CallHealth, CallHealthAggregator, type CallIssue, type CallIssueSpread, type CallScopedEventName, type CallSummary, type CallSummaryClients, CallSummaryCollector, type CallSummaryConfig, type CallSummaryEnricher, type CallSummaryEnrichers, type CallSummaryScores, type CallSummarySection, type CallSummaryTruncation, type CallSummaryTurnServers, type CertificateStats, type ClientAppDataFactory, type ClientEvent, ClientEventTypes, type ClientHealth, type ClientHealthThresholds, type ClientIssue, type ClientLocation, type ClientLocationResolver, type ClientMetaData, ClientMetaTypes, type ClientPopulation, type ClientPopulationAxis, ClientPopulationIssueDetector, type ClientPopulationIssueDetectorConfig, ClientPopulationIssueTypes, type ClientSample, type ClientSampleSink, type ClientSampleSinkEvents, type ClientSinkParams, type CodecConsistencyReportPayload, CodecConsistencyValidator, type CodecConsistencyValidatorConfig, type CodecEvidence, type CodecStats, type CorroboratedPublisherFault, type CreateExtensionStatsSettings, type DataChannelStats, type Detector, Detectors, type ExtensionStat, ExtensionStatsRegistry, GEOHASH_CELL_SIZES, type IceCandidatePairStats, type IceCandidateStats, type IceTransportStats, InMemorySink, type InboundRtpStats, type InboundTrackSample, type Issue, type IssueBase, type IssueConclusion, IssueFanOutDetector, type IssueFanOutDetectorConfig, IssueFanOutTypes, type IssueFaultDomain, JsonlFileSink, type JsonlFileSinkOptions, LOWEST_COMMON_DENOMINATOR_ISSUE, type Logger, type MannKendallResult, type MediaKind, type MediaPlayoutStats, type MediaSourceStats, type MediasoupConsumerSample, type MediasoupConsumerSampleEvent, type MediasoupDataConsumerSample, type MediasoupDataProducerSample, type MediasoupDirectTransportSample, type MediasoupDirectTransportSampleEventMap, type MediasoupPipeTransportSample, type MediasoupPipeTransportSampleEventMap, type MediasoupPlainTransportSample, type MediasoupPlainTransportSampleEventMap, type MediasoupProducerSample, type MediasoupProducerSampleEvent, type MediasoupRouterSample, type MediasoupSampleEnricher, type MediasoupTransportSample, type MediasoupWebRtcTransportSample, type MediasoupWebRtcTransportSampleEventMap, type Middleware, MiddlewareProcessor, ObservedCall, type ObservedCallScope, type ObservedCallSettings, ObservedCertificate, ObservedClient, ObservedClientIssueRegistry, type ObservedClientScope, type ObservedClientSettings, ObservedCodec, ObservedDataChannel, ObservedIceCandidate, ObservedIceCandidatePair, ObservedIceTransport, ObservedInboundRtp, ObservedInboundTrack, ObservedMediaPlayout, ObservedMediaSource, ObservedMediasoupRouter, type ObservedMediasoupRouterEvents, type ObservedMediasoupRouterScope, type ObservedMediasoupRouterSettings, ObservedOutboundRtp, ObservedOutboundTrack, ObservedPeerConnection, type ObservedPeerConnectionScope, ObservedPeerConnectionTransport, ObservedRemoteInboundRtp, ObservedRemoteOutboundRtp, ObservedTURN, type ObservedTURNEventMap, ObservedTurnServer, Observer, ObserverConcurrentIssueDetector, type ObserverConcurrentIssueDetectorConfig, type ObserverConcurrentIssueGroup, ObserverConcurrentIssueTypes, type ObserverEventBase, type ObserverEvents, type ObserverIssue, type ObserverIssueSpread, type ObserverLogger, type OutboundRtpStats, type OutboundTrackSample, type PageHinkleyResult, type PeerConnectionSample, type PeerConnectionTransportStats, type PsnrSum, PublisherFaultCorroborationDetector, type PublisherFaultCorroborationDetectorConfig, PublisherFaultTypes, type QualityLimitationDurations, RESOLVED_ISSUE_SUFFIX, RTT_HISTOGRAM_BUCKET_WIDTH_IN_MS, RTT_HISTOGRAM_NUMBER_OF_BUCKETS, type RemoteInboundRtpStats, type RemoteOutboundRtpStats, type RemoteTrackLinkEvidence, RemoteTrackResolver, type RemoteTrackResolverFactory, type RemoteTrackResolverReportPayload, RemoteTrackResolverValidator, type RemoteTrackResolverValidatorConfig, type RemoteTrackResolvers, type ResolvedActiveClientIssue, type RttSummary, type RunningValidator, SCORE_HISTOGRAM_BUCKET_WIDTH, SCORE_HISTOGRAM_NUMBER_OF_BUCKETS, type SampleRejectedReason, type SaveClientSamplesConfig, type ScoreCalculator, type ScoreSummary, SfuCongestionDetector, type SfuCongestionDetectorBucket, type SfuCongestionDetectorConfig, type SfuCongestionDetectorEvaluation, type SfuCongestionDetectorReport, type SimulcastReceiverEvidence, type SimulcastReceiverReportPayload, SimulcastReceiverValidator, type SimulcastReceiverValidatorConfig, type Sink, type SinkConstructor, type SinkCreateSettings, type SinkDestination, type SinkEvents, SinkRegistry, type SinkSettings, SlidingWindow, type SlidingWindowEntry, type StatsSummary, TrackDeliveryMismatchDetector, type TrackDeliveryMismatchDetectorConfig, TrackDeliveryMismatchTypes, TrendTester, type TrendTesterConfig, type TurnServerHealth, TurnServerHealthDetector, type TurnServerHealthDetectorConfig, TurnServerHealthTypes, TurnServerOutageDetector, type TurnServerOutageDetectorConfig, TurnServerOutageTypes, UNRESOLVED_TRACK_LINKS_ISSUE, UnconsumedTrackDetector, type UnconsumedTrackDetectorConfig, UnconsumedTrackTypes, type ValidationReport, type Validator, type ValidatorName, baseIssueType, concludeCallIssue, concludeObserverIssue, correlation, counterDelta, createCallSummary, createDefaultMediasoupRemoteTrackResolverFactory, createInMemorySink, createJsonlFileSink, createLogger, createP2pRemoteTrackResolverFactory, defaultCallSummaryConfig, defaultClientHealthThresholds, geohash, isClientIssueResolutionEntry, isPublicIpAddress, issuePayloadAsString, mannKendall, mannKendallVerdict, median, medianAbsoluteDeviation, pageHinkley, percentile, percentileOfHistogram, percentileOfSorted, robustZScore, schemaVersion, setObserverLogger, summarize };

package/dist/index.d.ts

@@ -59,6 +59,12 @@ type SinkDestination<T = unknown> = {
     sink: Sink<T>;
     jsonlPath?: never;
 };
+/** What the `saveClientSamples` callbacks receive: `id` is the client's sample sink id, the client id. */
+type ClientSinkParams<Call = unknown> = {
+    id: string;
+    observedCall: Call;
+    clientId: string;
+};
 
 /** A sink class `SinkRegistry.create` can construct: its constructor takes one settings object (with `id`). */
 type SinkConstructor = new (settings: any) => Sink<any>;
@@ -4004,7 +4010,7 @@ declare class ObservedClient<AppData extends Record<string, unknown> = Record<st
     /** The distinct `publicAddress`es currently known by this client's open peer connections. */
     /**
      * The sink this client's samples are written to: whatever is registered under its client id in
-     * `call.sinks` (the one `createClientSink` returned, or a sink the application added), if any.
+     * `call.sinks` (the one created through `saveClientSamples`, or a sink the application added), if any.
      */
     get sink(): Sink<ClientSample> | undefined;
     get publicAddresses(): string[];
@@ -5883,8 +5889,8 @@ declare class ObservedCall<AppData extends Record<string, unknown> = Record<stri
     private _onClientUpdate;
     private _clientJoined;
     private _clientLeft;
-    /** Emit an Observer-bus event scoped to this call. */
     private _createClientSink;
+    /** Emit an Observer-bus event scoped to this call. */
     private _notify;
 }
 
@@ -6445,6 +6451,14 @@ type ClientAppDataFactory = (params: {
     observedCall: ObservedCall;
     acceptCtx?: AcceptContext;
 }) => Record<string, unknown>;
+/** `ObserverConfig.saveClientSamples`: exactly one of the two per-client callbacks. */
+type SaveClientSamplesConfig = {
+    jsonlPath: (params: ClientSinkParams<ObservedCall>) => string | undefined;
+    sink?: never;
+} | {
+    sink: (params: ClientSinkParams<ObservedCall>) => Sink<ClientSample> | undefined;
+    jsonlPath?: never;
+};
 type ObserverConfig<AppData extends Record<string, unknown> = Record<string, unknown>> = {
     /**
      * Application-owned data for the observer itself. Never read or modified by the library.
@@ -6598,22 +6612,15 @@ type ObserverConfig<AppData extends Record<string, unknown> = Record<string, unk
     /** Same as `createCallAppData`, for clients. Receives the (already-created) parent call. */
     createClientAppData?: ClientAppDataFactory;
     /**
-     * The sink a newly-created client writes its samples to: `{ jsonlPath }` (a `JsonlFileSink` is
-     * created at that path under the client id), `{ sink }` (a `Sink` whose `id` is `params.id`, the
-     * client id), or `undefined` for none. The sink is added to `observedCall.sinks` and is ended
-     * when the client closes; `client-sink-created` announces it.
-     *
-     * ```ts
-     * createClientSink: ({ observedCall, clientId }) => ({ jsonlPath: `./stats/${observedCall.callId}__${clientId}.jsonl` }),
-     * ```
+     * Where each client's samples are saved: exactly one of `jsonlPath` (return the path of the
+     * client's JSONL file) and `sink` (return a sink whose `id` is `params.id`), each called per
+     * client; `undefined` gives that client no sink. See the README's *Sinks* section.
      *
-     * Called only when the client id is free as a sink id, so a clash opens no file.
+     * A client's sample sink id is its client id (`params.id`). Sink ids are unique per observer, so
+     * client ids must be unique across the observer's open calls; a client whose id is already a sink
+     * id gets no sink, and a warning is logged.
      */
-    createClientSink?: (params: {
-        id: string;
-        observedCall: ObservedCall;
-        clientId: string;
-    }) => SinkDestination<ClientSample> | undefined;
+    saveClientSamples?: SaveClientSamplesConfig;
     /**
      * Optional factory invoked when a call is created, producing the call's `RemoteTrackResolver`
      * (or `undefined` for none). Use the built-ins
@@ -7183,7 +7190,7 @@ declare function setObserverLogger(logger: ObserverLogger): void;
 /** The lifecycle events a client sample sink may emit. Same as {@link SinkEvents}. */
 type ClientSampleSinkEvents = SinkEvents;
 /**
- * A per-client destination for accepted samples. Return one from `ObserverConfig.createClientSink`
+ * A per-client destination for accepted samples. Return one from `ObserverConfig.saveClientSamples.sink`
  * (with the `id` it receives), or create one under the client id with
  * `observedCall.sinks.create(MySink, { id: clientId, ... })`.
  *
@@ -7253,4 +7260,4 @@ declare function createInMemorySink(samples?: ClientSample[]): InMemorySink;
 declare function createDefaultMediasoupRemoteTrackResolverFactory(): RemoteTrackResolverFactory;
 declare function createP2pRemoteTrackResolverFactory(): RemoteTrackResolverFactory;
 
-export { type AcceptContext, type AcceptMiddleware, type AcceptMiddlewarePayload, type ActiveClientIssue, type ActiveIssueTracker, ActiveIssuesRegistry, AudioEchoDetector, type AudioEchoDetectorConfig, AudioEchoTypes, type AudioInputDevice, type AvailableCallScopeDetectorsConfigs, type AvailableDetectorsConfigs, type AvailableObserverScopeDetectorsConfigs, type AvailableValidatorConfigs, CODEC_MISMATCH_ISSUE, type CalculatedScore, type CallAppDataFactory, CallConcurrentIssueDetector, type CallConcurrentIssueDetectorConfig, type CallConcurrentIssueGroup, CallConcurrentIssueTypes, type CallHealth, CallHealthAggregator, type CallIssue, type CallIssueSpread, type CallScopedEventName, type CallSummary, type CallSummaryClients, CallSummaryCollector, type CallSummaryConfig, type CallSummaryEnricher, type CallSummaryEnrichers, type CallSummaryScores, type CallSummarySection, type CallSummaryTruncation, type CallSummaryTurnServers, type CertificateStats, type ClientAppDataFactory, type ClientEvent, ClientEventTypes, type ClientHealth, type ClientHealthThresholds, type ClientIssue, type ClientLocation, type ClientLocationResolver, type ClientMetaData, ClientMetaTypes, type ClientPopulation, type ClientPopulationAxis, ClientPopulationIssueDetector, type ClientPopulationIssueDetectorConfig, ClientPopulationIssueTypes, type ClientSample, type ClientSampleSink, type ClientSampleSinkEvents, type CodecConsistencyReportPayload, CodecConsistencyValidator, type CodecConsistencyValidatorConfig, type CodecEvidence, type CodecStats, type CorroboratedPublisherFault, type CreateExtensionStatsSettings, type DataChannelStats, type Detector, Detectors, type ExtensionStat, ExtensionStatsRegistry, GEOHASH_CELL_SIZES, type IceCandidatePairStats, type IceCandidateStats, type IceTransportStats, InMemorySink, type InboundRtpStats, type InboundTrackSample, type Issue, type IssueBase, type IssueConclusion, IssueFanOutDetector, type IssueFanOutDetectorConfig, IssueFanOutTypes, type IssueFaultDomain, JsonlFileSink, type JsonlFileSinkOptions, LOWEST_COMMON_DENOMINATOR_ISSUE, type Logger, type MannKendallResult, type MediaKind, type MediaPlayoutStats, type MediaSourceStats, type MediasoupConsumerSample, type MediasoupConsumerSampleEvent, type MediasoupDataConsumerSample, type MediasoupDataProducerSample, type MediasoupDirectTransportSample, type MediasoupDirectTransportSampleEventMap, type MediasoupPipeTransportSample, type MediasoupPipeTransportSampleEventMap, type MediasoupPlainTransportSample, type MediasoupPlainTransportSampleEventMap, type MediasoupProducerSample, type MediasoupProducerSampleEvent, type MediasoupRouterSample, type MediasoupSampleEnricher, type MediasoupTransportSample, type MediasoupWebRtcTransportSample, type MediasoupWebRtcTransportSampleEventMap, type Middleware, MiddlewareProcessor, ObservedCall, type ObservedCallScope, type ObservedCallSettings, ObservedCertificate, ObservedClient, ObservedClientIssueRegistry, type ObservedClientScope, type ObservedClientSettings, ObservedCodec, ObservedDataChannel, ObservedIceCandidate, ObservedIceCandidatePair, ObservedIceTransport, ObservedInboundRtp, ObservedInboundTrack, ObservedMediaPlayout, ObservedMediaSource, ObservedMediasoupRouter, type ObservedMediasoupRouterEvents, type ObservedMediasoupRouterScope, type ObservedMediasoupRouterSettings, ObservedOutboundRtp, ObservedOutboundTrack, ObservedPeerConnection, type ObservedPeerConnectionScope, ObservedPeerConnectionTransport, ObservedRemoteInboundRtp, ObservedRemoteOutboundRtp, ObservedTURN, type ObservedTURNEventMap, ObservedTurnServer, Observer, ObserverConcurrentIssueDetector, type ObserverConcurrentIssueDetectorConfig, type ObserverConcurrentIssueGroup, ObserverConcurrentIssueTypes, type ObserverEventBase, type ObserverEvents, type ObserverIssue, type ObserverIssueSpread, type ObserverLogger, type OutboundRtpStats, type OutboundTrackSample, type PageHinkleyResult, type PeerConnectionSample, type PeerConnectionTransportStats, type PsnrSum, PublisherFaultCorroborationDetector, type PublisherFaultCorroborationDetectorConfig, PublisherFaultTypes, type QualityLimitationDurations, RESOLVED_ISSUE_SUFFIX, RTT_HISTOGRAM_BUCKET_WIDTH_IN_MS, RTT_HISTOGRAM_NUMBER_OF_BUCKETS, type RemoteInboundRtpStats, type RemoteOutboundRtpStats, type RemoteTrackLinkEvidence, RemoteTrackResolver, type RemoteTrackResolverFactory, type RemoteTrackResolverReportPayload, RemoteTrackResolverValidator, type RemoteTrackResolverValidatorConfig, type RemoteTrackResolvers, type ResolvedActiveClientIssue, type RttSummary, type RunningValidator, SCORE_HISTOGRAM_BUCKET_WIDTH, SCORE_HISTOGRAM_NUMBER_OF_BUCKETS, type SampleRejectedReason, type ScoreCalculator, type ScoreSummary, SfuCongestionDetector, type SfuCongestionDetectorBucket, type SfuCongestionDetectorConfig, type SfuCongestionDetectorEvaluation, type SfuCongestionDetectorReport, type SimulcastReceiverEvidence, type SimulcastReceiverReportPayload, SimulcastReceiverValidator, type SimulcastReceiverValidatorConfig, type Sink, type SinkConstructor, type SinkCreateSettings, type SinkDestination, type SinkEvents, SinkRegistry, type SinkSettings, SlidingWindow, type SlidingWindowEntry, type StatsSummary, TrackDeliveryMismatchDetector, type TrackDeliveryMismatchDetectorConfig, TrackDeliveryMismatchTypes, TrendTester, type TrendTesterConfig, type TurnServerHealth, TurnServerHealthDetector, type TurnServerHealthDetectorConfig, TurnServerHealthTypes, TurnServerOutageDetector, type TurnServerOutageDetectorConfig, TurnServerOutageTypes, UNRESOLVED_TRACK_LINKS_ISSUE, UnconsumedTrackDetector, type UnconsumedTrackDetectorConfig, UnconsumedTrackTypes, type ValidationReport, type Validator, type ValidatorName, baseIssueType, concludeCallIssue, concludeObserverIssue, correlation, counterDelta, createCallSummary, createDefaultMediasoupRemoteTrackResolverFactory, createInMemorySink, createJsonlFileSink, createLogger, createP2pRemoteTrackResolverFactory, defaultCallSummaryConfig, defaultClientHealthThresholds, geohash, isClientIssueResolutionEntry, isPublicIpAddress, issuePayloadAsString, mannKendall, mannKendallVerdict, median, medianAbsoluteDeviation, pageHinkley, percentile, percentileOfHistogram, percentileOfSorted, robustZScore, schemaVersion, setObserverLogger, summarize };
+export { type AcceptContext, type AcceptMiddleware, type AcceptMiddlewarePayload, type ActiveClientIssue, type ActiveIssueTracker, ActiveIssuesRegistry, AudioEchoDetector, type AudioEchoDetectorConfig, AudioEchoTypes, type AudioInputDevice, type AvailableCallScopeDetectorsConfigs, type AvailableDetectorsConfigs, type AvailableObserverScopeDetectorsConfigs, type AvailableValidatorConfigs, CODEC_MISMATCH_ISSUE, type CalculatedScore, type CallAppDataFactory, CallConcurrentIssueDetector, type CallConcurrentIssueDetectorConfig, type CallConcurrentIssueGroup, CallConcurrentIssueTypes, type CallHealth, CallHealthAggregator, type CallIssue, type CallIssueSpread, type CallScopedEventName, type CallSummary, type CallSummaryClients, CallSummaryCollector, type CallSummaryConfig, type CallSummaryEnricher, type CallSummaryEnrichers, type CallSummaryScores, type CallSummarySection, type CallSummaryTruncation, type CallSummaryTurnServers, type CertificateStats, type ClientAppDataFactory, type ClientEvent, ClientEventTypes, type ClientHealth, type ClientHealthThresholds, type ClientIssue, type ClientLocation, type ClientLocationResolver, type ClientMetaData, ClientMetaTypes, type ClientPopulation, type ClientPopulationAxis, ClientPopulationIssueDetector, type ClientPopulationIssueDetectorConfig, ClientPopulationIssueTypes, type ClientSample, type ClientSampleSink, type ClientSampleSinkEvents, type ClientSinkParams, type CodecConsistencyReportPayload, CodecConsistencyValidator, type CodecConsistencyValidatorConfig, type CodecEvidence, type CodecStats, type CorroboratedPublisherFault, type CreateExtensionStatsSettings, type DataChannelStats, type Detector, Detectors, type ExtensionStat, ExtensionStatsRegistry, GEOHASH_CELL_SIZES, type IceCandidatePairStats, type IceCandidateStats, type IceTransportStats, InMemorySink, type InboundRtpStats, type InboundTrackSample, type Issue, type IssueBase, type IssueConclusion, IssueFanOutDetector, type IssueFanOutDetectorConfig, IssueFanOutTypes, type IssueFaultDomain, JsonlFileSink, type JsonlFileSinkOptions, LOWEST_COMMON_DENOMINATOR_ISSUE, type Logger, type MannKendallResult, type MediaKind, type MediaPlayoutStats, type MediaSourceStats, type MediasoupConsumerSample, type MediasoupConsumerSampleEvent, type MediasoupDataConsumerSample, type MediasoupDataProducerSample, type MediasoupDirectTransportSample, type MediasoupDirectTransportSampleEventMap, type MediasoupPipeTransportSample, type MediasoupPipeTransportSampleEventMap, type MediasoupPlainTransportSample, type MediasoupPlainTransportSampleEventMap, type MediasoupProducerSample, type MediasoupProducerSampleEvent, type MediasoupRouterSample, type MediasoupSampleEnricher, type MediasoupTransportSample, type MediasoupWebRtcTransportSample, type MediasoupWebRtcTransportSampleEventMap, type Middleware, MiddlewareProcessor, ObservedCall, type ObservedCallScope, type ObservedCallSettings, ObservedCertificate, ObservedClient, ObservedClientIssueRegistry, type ObservedClientScope, type ObservedClientSettings, ObservedCodec, ObservedDataChannel, ObservedIceCandidate, ObservedIceCandidatePair, ObservedIceTransport, ObservedInboundRtp, ObservedInboundTrack, ObservedMediaPlayout, ObservedMediaSource, ObservedMediasoupRouter, type ObservedMediasoupRouterEvents, type ObservedMediasoupRouterScope, type ObservedMediasoupRouterSettings, ObservedOutboundRtp, ObservedOutboundTrack, ObservedPeerConnection, type ObservedPeerConnectionScope, ObservedPeerConnectionTransport, ObservedRemoteInboundRtp, ObservedRemoteOutboundRtp, ObservedTURN, type ObservedTURNEventMap, ObservedTurnServer, Observer, ObserverConcurrentIssueDetector, type ObserverConcurrentIssueDetectorConfig, type ObserverConcurrentIssueGroup, ObserverConcurrentIssueTypes, type ObserverEventBase, type ObserverEvents, type ObserverIssue, type ObserverIssueSpread, type ObserverLogger, type OutboundRtpStats, type OutboundTrackSample, type PageHinkleyResult, type PeerConnectionSample, type PeerConnectionTransportStats, type PsnrSum, PublisherFaultCorroborationDetector, type PublisherFaultCorroborationDetectorConfig, PublisherFaultTypes, type QualityLimitationDurations, RESOLVED_ISSUE_SUFFIX, RTT_HISTOGRAM_BUCKET_WIDTH_IN_MS, RTT_HISTOGRAM_NUMBER_OF_BUCKETS, type RemoteInboundRtpStats, type RemoteOutboundRtpStats, type RemoteTrackLinkEvidence, RemoteTrackResolver, type RemoteTrackResolverFactory, type RemoteTrackResolverReportPayload, RemoteTrackResolverValidator, type RemoteTrackResolverValidatorConfig, type RemoteTrackResolvers, type ResolvedActiveClientIssue, type RttSummary, type RunningValidator, SCORE_HISTOGRAM_BUCKET_WIDTH, SCORE_HISTOGRAM_NUMBER_OF_BUCKETS, type SampleRejectedReason, type SaveClientSamplesConfig, type ScoreCalculator, type ScoreSummary, SfuCongestionDetector, type SfuCongestionDetectorBucket, type SfuCongestionDetectorConfig, type SfuCongestionDetectorEvaluation, type SfuCongestionDetectorReport, type SimulcastReceiverEvidence, type SimulcastReceiverReportPayload, SimulcastReceiverValidator, type SimulcastReceiverValidatorConfig, type Sink, type SinkConstructor, type SinkCreateSettings, type SinkDestination, type SinkEvents, SinkRegistry, type SinkSettings, SlidingWindow, type SlidingWindowEntry, type StatsSummary, TrackDeliveryMismatchDetector, type TrackDeliveryMismatchDetectorConfig, TrackDeliveryMismatchTypes, TrendTester, type TrendTesterConfig, type TurnServerHealth, TurnServerHealthDetector, type TurnServerHealthDetectorConfig, TurnServerHealthTypes, TurnServerOutageDetector, type TurnServerOutageDetectorConfig, TurnServerOutageTypes, UNRESOLVED_TRACK_LINKS_ISSUE, UnconsumedTrackDetector, type UnconsumedTrackDetectorConfig, UnconsumedTrackTypes, type ValidationReport, type Validator, type ValidatorName, baseIssueType, concludeCallIssue, concludeObserverIssue, correlation, counterDelta, createCallSummary, createDefaultMediasoupRemoteTrackResolverFactory, createInMemorySink, createJsonlFileSink, createLogger, createP2pRemoteTrackResolverFactory, defaultCallSummaryConfig, defaultClientHealthThresholds, geohash, isClientIssueResolutionEntry, isPublicIpAddress, issuePayloadAsString, mannKendall, mannKendallVerdict, median, medianAbsoluteDeviation, pageHinkley, percentile, percentileOfHistogram, percentileOfSorted, robustZScore, schemaVersion, setObserverLogger, summarize };

package/dist/index.js

@@ -312,11 +312,11 @@ var SinkRegistry = class {
   }
   /** End every sink of this registry and of its descendants. */
   clear() {
-    for (const sink of [...this._sinks.values()]) {
+    for (const [id, sink] of [...this._sinks.entries()]) {
       try {
         sink.end();
       } catch (err) {
-        logger.warn("Sink %s failed to end: %o", sink.id, err);
+        logger.warn("Sink %s failed to end: %o", id, err);
       }
     }
   }
@@ -3258,7 +3258,7 @@ var ObservedClient = class extends import_node_events3.EventEmitter {
   /** The distinct `publicAddress`es currently known by this client's open peer connections. */
   /**
    * The sink this client's samples are written to: whatever is registered under its client id in
-   * `call.sinks` (the one `createClientSink` returned, or a sink the application added), if any.
+   * `call.sinks` (the one created through `saveClientSamples`, or a sink the application added), if any.
    */
   get sink() {
     return this.call.sinks.get(this.clientId);
@@ -5411,17 +5411,26 @@ var ObservedCall = class extends import_node_events4.EventEmitter {
     if (!client.leftAt) return;
     this.endedAt = Math.max(this.endedAt ?? client.leftAt, client.leftAt);
   }
-  /** Emit an Observer-bus event scoped to this call. */
   _createClientSink(clientId) {
-    const createClientSink = this.observer.config.createClientSink;
-    if (!createClientSink) return void 0;
+    const config = this.observer.config.saveClientSamples;
+    if (!config || !config.jsonlPath && !config.sink) return void 0;
+    if (config.jsonlPath && config.sink) {
+      logger6.warn("saveClientSamples: give either jsonlPath or sink, not both; no client samples are saved");
+      return void 0;
+    }
     if (this.observer.sinks.get(clientId)) {
       logger6.warn("No sample sink for client %s in call %s: sink id %s is already in use", clientId, this.callId, clientId);
       return void 0;
     }
-    const destination = createClientSink({ id: clientId, observedCall: this, clientId });
-    return destination ? this.sinks.createFromDestination(clientId, destination) : void 0;
+    const params = { id: clientId, observedCall: this, clientId };
+    if (config.jsonlPath) {
+      const jsonlPath = config.jsonlPath(params);
+      return jsonlPath === void 0 ? void 0 : this.sinks.createFromDestination(clientId, { jsonlPath });
+    }
+    const sink = config.sink?.(params);
+    return sink ? this.sinks.createFromDestination(clientId, { sink }) : void 0;
   }
+  /** Emit an Observer-bus event scoped to this call. */
   _notify(type, ...args) {
     this.observer.emit(type, ...args);
   }