@observertc/observer-js 1.3.0-rc.2 → 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: JsonlFileSink }` | the client's JSONL sample file was created (only when `createClientJsonlSink` returns a path); 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).
-    createClientJsonlSink?: (p: { clientId: string; observedCall: ObservedCall }) => string | 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;
   };
@@ -1929,6 +1932,9 @@ that are still open, since the observer does not close mediasoup routers.
 | Method | Does |
 |--------|------|
 | `create(SinkClass, settings)` | constructs `new SinkClass(settings)` and registers it under `settings.id` (generated when omitted); `undefined` if the id is taken |
+| `add(sink): boolean` | registers a sink constructed elsewhere under its own `id`; `false` if the id is taken (the sink stays yours to end). Prefer `create` for sinks that open a resource on construction: it checks the id first |
+| `createFromDestination(id, destination)` | registers the sink a `SinkDestination` describes under `id`: `{ jsonlPath }` creates a `JsonlFileSink` (the id is checked first), `{ sink }` adds your sink (its `id` must be `id`). `undefined` if refused; a refused `sink` is ended |
+| `owns(id): boolean` | whether `id` was added to this registry itself, not to a descendant |
 | `get<T>(id)` | the sink, if any (own or a descendant's) |
 | `write(id, record): boolean` | writes to the sink; `false` if there is none, or on backpressure |
 | `clear()` | ends every sink of the registry and its descendants |
@@ -1944,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
@@ -1974,21 +1980,38 @@ 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 removes — ends — that sink when it closes. For the
-common case, a JSONL file per client, return a path from `createClientJsonlSink`:
+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:
+
+| `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({
-  // return undefined for no file
-  createClientJsonlSink: ({ observedCall, clientId }) => `./stats/${observedCall.callId}__${clientId}.jsonl`,
+  saveClientSamples: {
+    jsonlPath: ({ observedCall, clientId }) => `./stats/${observedCall.callId}__${clientId}.jsonl`,
+  },
 });
 
 observer.on('client-sink-created', ({ observedClient, sink }) => {
-  sink.once('close', () => uploadFile(sink.path));   // flushed & fd closed → ready
+  if (sink instanceof JsonlFileSink) sink.once('close', () => uploadFile(sink.path));   // flushed & fd closed → ready
 });
 ```
 
-For any other destination, create your own sink under the client id when the client is created:
+**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:
 
 ```ts
 class HttpSink extends EventEmitter implements ClientSampleSink {
@@ -2017,9 +2040,14 @@ class HttpSink extends EventEmitter implements ClientSampleSink {
   }
 }
 
-observer.on('client-added', ({ observedCall, observedClient }) => {
-  observedCall.sinks.create(HttpSink, { id: observedClient.clientId, url: `https://stats.example.com/${observedClient.clientId}` });
+new Observer({
+  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:
+// observedCall.sinks.create(HttpSink, { id: observedClient.clientId, url })
 ```
 
 Client ids double as sink ids, so they must be unique across the observer's open calls (client
@@ -2037,8 +2065,11 @@ the call) or `observedMediasoupRouter` (a pipe transport's `getStats()`): the la
 optionally a sink that receives every data. The API is the same on all three; a call is shown.
 
 ```ts
-// Register the id; with `createSink` (what `sinks.create` takes), a sink is created under the same id.
-call.createExtensionStats({ id: `${call.callId}:sfu`, createSink: [ JsonlFileSink<SfuStats>, { path: './stats/sfu.jsonl' } ] });
+// Register the id, with a JSONL file that receives every data accepted for it.
+call.createExtensionStats({ id: `${call.callId}:sfu`, jsonlPath: './stats/sfu.jsonl' });
+
+// Or with a sink of your own; its id must be the extension stats id.
+call.createExtensionStats({ id: `${call.callId}:metrics`, sink: new HttpSink({ id: `${call.callId}:metrics`, url }) });
 
 // Your own polling: keep the last data, and write it to the sink with the same id, if any.
 call.acceptExtensionStats(`${call.callId}:sfu`, await collectSfuStats(call.callId));
@@ -2049,7 +2080,7 @@ call.extensionStats.values;                               // Map<id, last data>
 
 | Method | Behaviour |
 |--------|-----------|
-| `createExtensionStats({ id, createSink? })` | Registers `id`. With `createSink` — what `sinks.create` takes, `[SinkClass, settings]` — it also creates a sink under `id` (an `id` in the sink settings is ignored), ending and replacing a sink the owner already holds under `id`. Returns the created sink, or `undefined`: without `createSink`, on a closed owner, when `id` is already in `extensionStats.values` (created or accepted before), or when another object of the observer holds a sink with this id |
+| `createExtensionStats({ id, jsonlPath? \| sink? })` | Registers `id`, optionally with a sink — at most one of: `jsonlPath`, the path of a JSONL file, for which a `JsonlFileSink` is created under `id`; or `sink`, a `Sink` of your own, whose `id` must be `id`. Either ends and replaces a sink the owner itself already holds under `id`. Returns the sink, or `undefined`: with neither, on a closed owner, when `id` is already in `extensionStats.values` (created or accepted before), with a `sink` whose id differs, or when another object of the observer holds a sink with this id. Giving both is a compile error (refused at runtime). A refused `sink` is ended; for `jsonlPath`, the id is checked before the file is opened |
 | `acceptExtensionStats(id, data)` | Keeps `data` as the last data of `id` and writes it to the owner's sink with the same id, if there is one (a sink that throws is logged). `id` does not have to be created first. Dropped once the owner is closed |
 | `getExtensionStats<T>(id)` | The last data accepted for `id`, or `undefined` |
 | `extensionStats` | The owner's `ExtensionStatsRegistry`: `values` (`Map<id, last data>`), `closed`, `close()`, and `create` / `accept` / `get`, which the three methods above delegate to |
@@ -2057,12 +2088,12 @@ call.extensionStats.values;                               // Map<id, last data>
 **Extension stats ids share the sink id namespace, so they must be unique per observer**: the sink
 of extension stats `x` is the sink with id `x`. Consequently:
 
-- With `createSink`, a sink the owner already holds under the id is ended and replaced. If another
-  object of the observer holds it, no sink is created and the data is only kept.
-- Without `createSink`, a sink you create later under the id (`sinks.create(SinkClass, { id, ... })`)
-  receives the data accepted from then on.
-- An id accepted before it was created can no longer be created with `createSink`; give it a sink
-  with `sinks.create` instead.
+- With `jsonlPath` or `sink`, a sink the owner itself already holds under the id is ended and replaced. A sink another object holds under it is never touched: no sink is created and the data
+  is only kept.
+- With neither, a sink you add later under the id (`sinks.create(SinkClass, { id, ... })` or
+  `sinks.add(sink)`) receives the data accepted from then on.
+- An id accepted before it was created can no longer be created with a sink; give it one with
+  `sinks.create` / `sinks.add` instead.
 
 **Lifecycle.** When the owner (the call, the router or the observer) closes, it closes its
 `extensionStats`: data accepted afterwards is dropped, `createExtensionStats` returns `undefined`,

package/dist/index.d.mts

@@ -48,6 +48,23 @@ interface Sink<T = unknown> {
     once(event: keyof SinkEvents, listener: (...args: any[]) => void): this;
     off(event: keyof SinkEvents, listener: (...args: any[]) => void): this;
 }
+/**
+ * Where records go, exactly one of: `jsonlPath`, the path of a JSONL file (a `JsonlFileSink` is
+ * created there), or `sink`, a sink of your own. Giving both is a compile error.
+ */
+type SinkDestination<T = unknown> = {
+    jsonlPath: string;
+    sink?: never;
+} | {
+    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>;
@@ -70,6 +87,7 @@ type SinkCreateSettings<C extends SinkConstructor> = Omit<ConstructorParameters<
 declare class SinkRegistry {
     readonly parent?: SinkRegistry | undefined;
     private readonly _sinks;
+    private readonly _ownIds;
     constructor(parent?: SinkRegistry | undefined);
     /** Number of open sinks in this registry and its descendants. */
     get size(): number;
@@ -82,21 +100,41 @@ declare class SinkRegistry {
      * `undefined` is returned and a warning logged.
      */
     create<C extends SinkConstructor>(SinkClass: C, settings: SinkCreateSettings<C>): InstanceType<C> | undefined;
+    /**
+     * Register a sink constructed elsewhere, under its own `id`. Returns `false`, registering nothing,
+     * when the id is already in use in the observer (the sink is then the caller's to end). Prefer
+     * `create` when the sink opens a resource on construction: it checks the id first.
+     */
+    add(sink: Sink<any>): boolean;
+    /**
+     * Register the sink a `SinkDestination` describes, under `id`: for `jsonlPath`, a `JsonlFileSink`
+     * is created (the id is checked before the file is opened); a `sink` is added, and its `id` must
+     * be `id`. Returns `undefined` when the id is taken, the ids differ, or both are given (possible
+     * from JavaScript); a given `sink` that is not registered is ended.
+     */
+    createFromDestination<T>(id: string, destination: SinkDestination<T>): Sink<T> | undefined;
+    /** Whether the sink `id` was added to this registry itself, rather than to a descendant. */
+    owns(id: string): boolean;
     /** Write `record` to the sink `id`. `false` when there is no such sink, or on backpressure. */
     write(id: string, record: unknown): boolean;
     /** End every sink of this registry and of its descendants. */
     clear(): void;
     /** This registry and its ancestors, up to the root. */
+    private _register;
     private _lineage;
 }
 
-/** The settings of `createExtensionStats` on an observer, a call or a mediasoup router. */
-type CreateExtensionStatsSettings<C extends SinkConstructor> = {
+/**
+ * The settings of `createExtensionStats` on an observer, a call or a mediasoup router: the `id`,
+ * and at most one of `jsonlPath` and `sink` (a `SinkDestination`).
+ */
+type CreateExtensionStatsSettings<T = unknown> = {
     /** Unique per observer: it is also the id of the sink that receives the stats. */
     id: string;
-    /** What `sinks.create` takes; the sink is created under `id` (an `id` in its settings is ignored). */
-    createSink?: [SinkClass: C, settings: Omit<SinkCreateSettings<C>, 'id'>];
-};
+} & (SinkDestination<T> | {
+    jsonlPath?: never;
+    sink?: never;
+});
 /**
  * The extension stats of one object — `observer.extensionStats`, `observedCall.extensionStats`,
  * `observedMediasoupRouter.extensionStats`: the last data per id (`values`), written to the
@@ -118,7 +156,7 @@ declare class ExtensionStatsRegistry {
      * owner's `sinks.clear()`. Called by the owner when it closes.
      */
     close(): void;
-    create<C extends SinkConstructor>(settings: CreateExtensionStatsSettings<C>): InstanceType<C> | undefined;
+    create<T = unknown>(settings: CreateExtensionStatsSettings<T>): Sink<T> | undefined;
     accept(id: string, data: unknown): void;
     get<T>(id: string): T | undefined;
 }
@@ -3147,39 +3185,6 @@ declare function isClientIssueResolutionEntry(issue: ClientIssue): boolean;
 /** Strip the `-resolved` suffix, so both entries of a lifecycle share one logical type. */
 declare function baseIssueType(type: string): string;
 
-type JsonlFileSinkOptions<T = ClientSample> = Partial<SinkSettings> & {
-    /** Absolute or relative file path to append JSONL lines to. */
-    path: string;
-    /** Optional custom serializer; defaults to `JSON.stringify`. */
-    serializeSample?: (record: T) => string;
-};
-/**
- * A sink that serializes each record to a JSON line and appends it to a file. Defaults to client
- * samples, but takes any record type: `sinks.create(JsonlFileSink<PipeTransportStats[]>, { id, path })`. It wraps an
- * `fs.WriteStream` and re-emits its lifecycle events, so `close` fires once the file is flushed
- * and its descriptor is closed (file ready) and `error` surfaces file errors.
- */
-declare interface JsonlFileSink {
-    on<E extends keyof SinkEvents>(event: E, listener: (...args: SinkEvents[E]) => void): this;
-    once<E extends keyof SinkEvents>(event: E, listener: (...args: SinkEvents[E]) => void): this;
-    off<E extends keyof SinkEvents>(event: E, listener: (...args: SinkEvents[E]) => void): this;
-    emit<E extends keyof SinkEvents>(event: E, ...args: SinkEvents[E]): boolean;
-}
-declare class JsonlFileSink<T = ClientSample> extends EventEmitter implements Sink<T> {
-    readonly id: string;
-    /** The file this sink writes to. Read it (e.g. in a `close` handler) to upload/move the file. */
-    readonly path: string;
-    private readonly _stream;
-    private readonly _serializeSample;
-    private _ended;
-    constructor(options: JsonlFileSinkOptions<T>);
-    get ended(): boolean;
-    write(record: T): boolean;
-    end(): void;
-}
-/** Build a JSONL file sink for a single path. */
-declare function createJsonlFileSink<T = ClientSample>(options: JsonlFileSinkOptions<T>): JsonlFileSink<T>;
-
 /** mediasoup `TransportTuple` (the selected local/remote address pair of a transport). */
 type TransportTuple = {
     localAddress: string;
@@ -3467,7 +3472,7 @@ declare class ObservedMediasoupRouter<AppData extends Record<string, unknown> =
      */
     snapshot(): MediasoupRouterSample;
     close(): void;
-    createExtensionStats<C extends SinkConstructor>(settings: CreateExtensionStatsSettings<C>): InstanceType<C> | undefined;
+    createExtensionStats<T = unknown>(settings: CreateExtensionStatsSettings<T>): Sink<T> | undefined;
     acceptExtensionStats(id: string, data: unknown): void;
     getExtensionStats<T>(id: string): T | undefined;
     addTransport: (transport: types.Transport) => void;
@@ -3565,7 +3570,7 @@ type ObserverEvents = {
     }];
     'client-added': [ObservedClientScope];
     'client-sink-created': [ObservedClientScope & {
-        sink: JsonlFileSink;
+        sink: Sink<ClientSample>;
     }];
     'client-updated': [ObservedClientScope & {
         sample: ClientSample;
@@ -4005,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 `createClientJsonlSink` file, 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[];
@@ -5874,7 +5879,7 @@ declare class ObservedCall<AppData extends Record<string, unknown> = Record<stri
      */
     addIssue(issue: Omit<CallIssue, 'scope'>): void;
     close(): void;
-    createExtensionStats<C extends SinkConstructor>(settings: CreateExtensionStatsSettings<C>): InstanceType<C> | undefined;
+    createExtensionStats<T = unknown>(settings: CreateExtensionStatsSettings<T>): Sink<T> | undefined;
     acceptExtensionStats(id: string, data: unknown): void;
     getExtensionStats<T>(id: string): T | undefined;
     getObservedClient<ClientAppData extends Record<string, unknown> = Record<string, unknown>>(clientId: string): ObservedClient<ClientAppData> | undefined;
@@ -5884,6 +5889,7 @@ declare class ObservedCall<AppData extends Record<string, unknown> = Record<stri
     private _onClientUpdate;
     private _clientJoined;
     private _clientLeft;
+    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,38 +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;
     /**
-     * Write every sample a client accepts to a JSONL file: return the file path for a newly-created
-     * client, or `undefined` for no file. The directory must exist. The `JsonlFileSink` is added to
-     * `observedCall.sinks` under the client id and is ended when the client closes; `client-sink-created`
-     * announces it, so a `close` handler can upload or move the file once it is flushed.
-     *
-     * For any other destination, add your own sink under the client id instead, e.g. on
-     * `client-added`: `observedCall.sinks.create(MySink, { id: observedClient.clientId, ... })`.
-     *
-     * Replaces `createClientSink` (removed in 1.3.0), and with it `createJsonlFileSinkFactory`.
-     * To migrate:
+     * 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.
      *
-     * ```ts
-     * // before (1.2): JSONL files
-     * new Observer({ createClientSink: createJsonlFileSinkFactory({ directory: './stats' }) });
-     * // after: return the path; `${callId}__${clientId}.jsonl` was the factory's default file name
-     * new Observer({
-     *   createClientJsonlSink: ({ observedCall, clientId }) => path.join('./stats', `${observedCall.callId}__${clientId}.jsonl`),
-     * });
-     *
-     * // before (1.2): any other sink
-     * new Observer({ createClientSink: ({ clientId, observedCall }) => new HttpSink(url(observedCall, clientId)) });
-     * // after: create it under the client id when the client is added (HttpSink implements
-     * // `ClientSampleSink`, takes `SinkSettings & { ... }` and emits `ended` from `end()`)
-     * observer.on('client-added', ({ observedCall, observedClient }) => {
-     *   observedCall.sinks.create(HttpSink, { id: observedClient.clientId, url: url(observedCall, observedClient.clientId) });
-     * });
-     * ```
+     * 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.
      */
-    createClientJsonlSink?: (params: {
-        observedCall: ObservedCall;
-        clientId: string;
-    }) => string | undefined;
+    saveClientSamples?: SaveClientSamplesConfig;
     /**
      * Optional factory invoked when a call is created, producing the call's `RemoteTrackResolver`
      * (or `undefined` for none). Use the built-ins
@@ -6800,7 +6791,7 @@ declare class Observer<AppData extends Record<string, unknown> = Record<string,
         matchPeerConnectionByWebRtcTransportId?: boolean;
     }): ObservedMediasoupRouter<Record<string, unknown>> | undefined;
     close(): void;
-    createExtensionStats<C extends SinkConstructor>(settings: CreateExtensionStatsSettings<C>): InstanceType<C> | undefined;
+    createExtensionStats<T = unknown>(settings: CreateExtensionStatsSettings<T>): Sink<T> | undefined;
     acceptExtensionStats(id: string, data: unknown): void;
     getExtensionStats<T>(id: string): T | undefined;
     accept(sample: ClientSample, context?: AcceptContext): void;
@@ -7199,9 +7190,9 @@ 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. Create one under the client id with
- * `observedCall.sinks.create(MySink, { id: clientId, ... })`, or let
- * `ObserverConfig.createClientJsonlSink` create a `JsonlFileSink` there.
+ * 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, ... })`.
  *
  * The library calls `write(sample)` synchronously per accepted sample (not awaited) and `end()`s
  * the sink when the client closes; the registry attaches an `error` listener so a failing sink
@@ -7210,6 +7201,39 @@ type ClientSampleSinkEvents = SinkEvents;
  */
 type ClientSampleSink = Sink<ClientSample>;
 
+type JsonlFileSinkOptions<T = ClientSample> = Partial<SinkSettings> & {
+    /** Absolute or relative file path to append JSONL lines to. */
+    path: string;
+    /** Optional custom serializer; defaults to `JSON.stringify`. */
+    serializeSample?: (record: T) => string;
+};
+/**
+ * A sink that serializes each record to a JSON line and appends it to a file. Defaults to client
+ * samples, but takes any record type: `sinks.create(JsonlFileSink<PipeTransportStats[]>, { id, path })`. It wraps an
+ * `fs.WriteStream` and re-emits its lifecycle events, so `close` fires once the file is flushed
+ * and its descriptor is closed (file ready) and `error` surfaces file errors.
+ */
+declare interface JsonlFileSink {
+    on<E extends keyof SinkEvents>(event: E, listener: (...args: SinkEvents[E]) => void): this;
+    once<E extends keyof SinkEvents>(event: E, listener: (...args: SinkEvents[E]) => void): this;
+    off<E extends keyof SinkEvents>(event: E, listener: (...args: SinkEvents[E]) => void): this;
+    emit<E extends keyof SinkEvents>(event: E, ...args: SinkEvents[E]): boolean;
+}
+declare class JsonlFileSink<T = ClientSample> extends EventEmitter implements Sink<T> {
+    readonly id: string;
+    /** The file this sink writes to. Read it (e.g. in a `close` handler) to upload/move the file. */
+    readonly path: string;
+    private readonly _stream;
+    private readonly _serializeSample;
+    private _ended;
+    constructor(options: JsonlFileSinkOptions<T>);
+    get ended(): boolean;
+    write(record: T): boolean;
+    end(): void;
+}
+/** Build a JSONL file sink for a single path. */
+declare function createJsonlFileSink<T = ClientSample>(options: JsonlFileSinkOptions<T>): JsonlFileSink<T>;
+
 declare interface InMemorySink {
     on<E extends keyof SinkEvents>(event: E, listener: (...args: SinkEvents[E]) => void): this;
     once<E extends keyof SinkEvents>(event: E, listener: (...args: SinkEvents[E]) => void): this;
@@ -7236,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 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 };