@observertc/observer-js 1.0.0-beta.5 → 1.0.0-beta.7

package/dist/index.d.ts

@@ -1340,6 +1340,25 @@ type CalculatedScore = {
 
 type MediaKind = 'audio' | 'video';
 
+declare class ObservedMediaPlayout implements MediaPlayoutStats {
+    timestamp: number;
+    id: string;
+    kind: MediaKind;
+    private readonly _peerConnection;
+    private _visited;
+    appData?: Record<string, unknown>;
+    synthesizedSamplesDuration?: number | undefined;
+    synthesizedSamplesEvents?: number | undefined;
+    totalSamplesDuration?: number | undefined;
+    totalPlayoutDelay?: number | undefined;
+    totalSamplesCount?: number | undefined;
+    attachments?: Record<string, unknown> | undefined;
+    constructor(timestamp: number, id: string, kind: MediaKind, _peerConnection: ObservedPeerConnection);
+    get visited(): boolean;
+    getPeerConnection(): ObservedPeerConnection;
+    update(stats: MediaPlayoutStats): void;
+}
+
 declare class ObservedMediaSource implements MediaSourceStats {
     timestamp: number;
     id: string;
@@ -1579,91 +1598,6 @@ declare class ObservedOutboundRtp implements OutboundRtpStats {
     update(stats: OutboundRtpStats): void;
 }
 
-type InboundAudioTrackReport = {
-    trackId: string;
-    fractionLostDistribution: {
-        lt001: number;
-        lt005: number;
-        lt010: number;
-        lt020: number;
-        lt050: number;
-        gtOrEq050: number;
-        count: number;
-        sum: number;
-    };
-};
-type InboundVideoTrackReport = {
-    trackId: string;
-    fractionLostDistribution: {
-        lt001: number;
-        lt005: number;
-        lt010: number;
-        lt020: number;
-        lt050: number;
-        gtOrEq050: number;
-        count: number;
-        sum: number;
-    };
-};
-type OutboundAudioTrackReport = {
-    trackId: string;
-};
-type OutboundVideoTrackReport = {
-    trackId: string;
-};
-type InboundTrackReport = ({
-    kind: 'audio';
-} & InboundAudioTrackReport) | ({
-    kind: 'video';
-} & InboundVideoTrackReport);
-type OutboundTrackReport = ({
-    kind: 'audio';
-} & OutboundAudioTrackReport) | ({
-    kind: 'video';
-} & OutboundVideoTrackReport);
-type TrackReport = ({
-    direction: 'inbound';
-} & InboundTrackReport) | ({
-    direction: 'outbound';
-} & OutboundTrackReport);
-type ClientReport = {
-    callId: string;
-    clientId: string;
-    totalDataChannelBytesReceived: number;
-    totalDataChannelBytesSent: number;
-    totalDataChannelMessagesReceived: number;
-    totalDataChannelMessagesSent: number;
-    totalInboundRtpPacketsReceived: number;
-    totalInboundRtpPacketsLost: number;
-    totalInboundRtpBytesReceived: number;
-    totalOutboundRtpPacketsSent: number;
-    totalOutboundRtpBytesSent: number;
-    totalAudioBytesReceived: number;
-    totalVideoBytesReceived: number;
-    totalAudioBytesSent: number;
-    totalVideoBytesSent: number;
-    totalNumberOfIssues: number;
-    issues: Record<string, number>;
-    rttDistribution: {
-        lt50ms: number;
-        lt150ms: number;
-        lt300ms: number;
-        gtOrEq300ms: number;
-        count: number;
-        sum: number;
-    };
-    scoreDistribution: {
-        '0': number;
-        '1': number;
-        '2': number;
-        '3': number;
-        '4': number;
-        '5': number;
-        count: number;
-        sum: number;
-    };
-};
-
 declare class ObservedOutboundTrack implements OutboundTrackSample {
     timestamp: number;
     readonly id: string;
@@ -1673,7 +1607,7 @@ declare class ObservedOutboundTrack implements OutboundTrackSample {
     private readonly _mediaSource?;
     private _visited;
     appData?: Record<string, unknown>;
-    readonly report: OutboundTrackReport;
+    readonly remoteInboundTracks: Set<ObservedInboundTrack>;
     readonly calculatedScore: CalculatedScore;
     addedAt?: number | undefined;
     removedAt?: number | undefined;
@@ -1685,29 +1619,9 @@ declare class ObservedOutboundTrack implements OutboundTrackSample {
     getPeerConnection(): ObservedPeerConnection;
     getOutboundRtps(): ObservedOutboundRtp[] | undefined;
     getMediaSource(): ObservedMediaSource | undefined;
-    getRemoteInboundTracks(): ObservedInboundTrack[] | undefined;
     update(stats: OutboundTrackSample): void;
 }
 
-declare class ObservedMediaPlayout implements MediaPlayoutStats {
-    timestamp: number;
-    id: string;
-    kind: MediaKind;
-    private readonly _peerConnection;
-    private _visited;
-    appData?: Record<string, unknown>;
-    synthesizedSamplesDuration?: number | undefined;
-    synthesizedSamplesEvents?: number | undefined;
-    totalSamplesDuration?: number | undefined;
-    totalPlayoutDelay?: number | undefined;
-    totalSamplesCount?: number | undefined;
-    attachments?: Record<string, unknown> | undefined;
-    constructor(timestamp: number, id: string, kind: MediaKind, _peerConnection: ObservedPeerConnection);
-    get visited(): boolean;
-    getPeerConnection(): ObservedPeerConnection;
-    update(stats: MediaPlayoutStats): void;
-}
-
 declare class ObservedInboundTrack implements InboundTrackSample {
     timestamp: number;
     readonly id: string;
@@ -1717,7 +1631,7 @@ declare class ObservedInboundTrack implements InboundTrackSample {
     private readonly _mediaPlayout?;
     readonly calculatedScore: CalculatedScore;
     appData?: Record<string, unknown>;
-    report: InboundTrackReport;
+    remoteOutboundTrack?: ObservedOutboundTrack | undefined;
     private _visited;
     addedAt?: number | undefined;
     removedAt?: number | undefined;
@@ -1729,7 +1643,6 @@ declare class ObservedInboundTrack implements InboundTrackSample {
     getPeerConnection(): ObservedPeerConnection;
     getInboundRtp(): ObservedInboundRtp | undefined;
     getMediaPlayout(): ObservedMediaPlayout | undefined;
-    getRemoteOutboundTrack(): ObservedOutboundTrack | undefined;
     update(stats: InboundTrackSample): void;
 }
 
@@ -2237,9 +2150,6 @@ type ObserverEvents = {
     'client-event': [ObservedClientScope & {
         event: ClientEvent;
     }];
-    'client-track-report': [ObservedClientScope & {
-        report: TrackReport;
-    }];
     'peer-connection-added': [ObservedPeerConnectionScope];
     'peer-connection-updated': [ObservedPeerConnectionScope];
     'peer-connection-closed': [ObservedPeerConnectionScope];
@@ -2479,7 +2389,6 @@ declare class ObservedClient<AppData extends Record<string, unknown> = Record<st
     deltaNumberOfIssues: number;
     totalScoreSum: number;
     numberOfScoreMeasurements: number;
-    readonly report: ClientReport;
     readonly mediaDevices: MediaDeviceInfo[];
     issues: ClientIssue[];
     private _injections;
@@ -2508,9 +2417,49 @@ interface ScoreCalculator {
     update(): void;
 }
 
-interface RemoteTrackResolver {
+type RemoteTrackResolverFactory = (observedCall: ObservedCall) => RemoteTrackResolver;
+/**
+ * Strategy functions that map a track to its publish/subscribe identity. Two tracks are linked
+ * when a subscribed (inbound) track's **publisher id** equals a published (outbound) track's
+ * **publisher id** — one publisher → many subscribers. The **subscriber id** is optional and is
+ * only used to look an inbound track up via `getInboundTrackBySubscriberId`.
+ *
+ * The "publisher id" is whatever a strategy uses as the link key: mediasoup passes its producerId,
+ * a p2p strategy the SSRC, a generic strategy a shared attachment value.
+ */
+type RemoteTrackResolvers = {
+    /** The publisher id a subscribed (inbound) track receives. Required — this is the link key. */
+    resolveInboundTrackPublisherId: (inboundTrack: ObservedInboundTrack) => string | undefined;
+    /** The publisher id a published (outbound) track represents. Required — this is the link key. */
+    resolveOutboundTrackPublisherId: (outboundTrack: ObservedOutboundTrack) => string | undefined;
+    /** Optional: the inbound track's own subscription id (enables `getInboundTrackBySubscriberId`). */
+    resolveInboundTrackSubscriberId?: (inboundTrack: ObservedInboundTrack) => string | undefined;
+};
+/**
+ * Generic, strategy-driven base resolver. It subscribes to the Observer bus (filtered to one call),
+ * links subscribed↔published tracks by publisher id, and maintains the links directly on the tracks
+ * (`inboundTrack.remoteOutboundTrack`, `outboundTrack.remoteInboundTracks`).
+ *
+ * Concrete strategies (mediasoup, p2p-by-SSRC, generic attachment) are just different
+ * {@link RemoteTrackResolvers} passed to this class. Ids are re-resolved on demand rather than
+ * cached, so the only state kept is the two lookup indexes that back the public getters.
+ */
+declare class RemoteTrackResolver {
+    readonly observedCall: ObservedCall;
+    private readonly resolvers;
+    private readonly _publisherIdToOutboundTrack;
+    private readonly _subscriberIdToInboundTrack;
+    constructor(observedCall: ObservedCall, resolvers: RemoteTrackResolvers);
+    /** The published (outbound) track for a publisher id, if any. */
+    getOutboundTrackByPublisherId(publisherId: string): ObservedOutboundTrack | undefined;
+    /** The subscribed (inbound) track for a subscriber id, if the strategy resolves subscriber ids. */
+    getInboundTrackBySubscriberId(subscriberId: string): ObservedInboundTrack | undefined;
     resolveRemoteOutboundTrack(inboundTrack: ObservedInboundTrack): ObservedOutboundTrack | undefined;
     resolveRemoteInboundTracks(outboundTrack: ObservedOutboundTrack): ObservedInboundTrack[] | undefined;
+    private _addInboundTrack;
+    private _removeInboundTrack;
+    private _addOutboundTrack;
+    private _removeOutboundTrack;
 }
 
 interface Updater {
@@ -2536,16 +2485,11 @@ declare class Detectors {
 }
 
 type ObservedCallUpdateConfig = {
-    updatePolicy: 'update-on-interval';
-    updateIntervalInMs: number;
-} | {
     updatePolicy?: 'update-on-any-client-updated' | 'update-when-all-client-updated';
-    updateIntervalInMs?: number;
 };
 type ObservedCallSettings<AppData extends Record<string, unknown> = Record<string, unknown>> = ObservedCallUpdateConfig & {
     callId: string;
     appData?: AppData;
-    remoteTrackResolvePolicy?: 'p2p' | 'mediasoup-sfu' | 'none';
     closeCallIfEmptyForMs?: number;
 };
 type ObservedCallEvents = {
@@ -2606,6 +2550,22 @@ declare class ObservedCall<AppData extends Record<string, unknown> = Record<stri
     private _notify;
 }
 
+type Middleware<T> = (input: T, next: (nextInput: T) => void) => void;
+interface Processor<T> {
+    finalCallback?: Callback<T>;
+    process(value: T): void;
+    addMiddleware(...middlewares: Middleware<T>[]): Processor<T>;
+    removeMiddleware(...middlewares: Middleware<T>[]): Processor<T>;
+}
+type Callback<T> = (input: T) => void;
+declare class MiddlewareProcessor<T> implements Processor<T> {
+    private stack;
+    finalCallback?: Callback<T>;
+    addMiddleware(...middlewares: Middleware<T>[]): Processor<T>;
+    removeMiddleware(...middlewares: Middleware<T>[]): Processor<T>;
+    process(value: T): void;
+}
+
 type SampleRejectedReason = 'observer-closed' | 'missing-callId' | 'missing-clientId';
 
 /**
@@ -2614,12 +2574,20 @@ type SampleRejectedReason = 'observer-closed' | 'missing-callId' | 'missing-clie
  * merged into the `appData` of entities created during the accept pass.
  */
 type AcceptContext = Record<string, unknown>;
+/** The payload threaded through `accept()` middlewares: the sample and its optional context. */
+type AcceptMiddlewarePayload = {
+    sample: ClientSample;
+    context?: AcceptContext;
+};
+/**
+ * A global middleware run on every sample passed to `observer.accept()`, in registration order,
+ * **before** the sample is dispatched to any call/client. It may inspect or mutate the sample
+ * (e.g. set/normalize `callId`/`clientId`, enrich, redact) or the context, then call
+ * `next(payload)` to continue the chain. Not calling `next` **drops** the sample.
+ */
+type AcceptMiddleware = Middleware<AcceptMiddlewarePayload>;
 type ObserverUpdateConfig = {
-    updatePolicy: 'update-on-interval';
-    updateIntervalInMs: number;
-} | {
     updatePolicy?: 'update-on-any-call-updated' | 'update-when-all-call-updated';
-    updateIntervalInMs?: number;
 };
 /** Produces the initial `appData` for a call created without an explicit `appData`. */
 type CallAppDataFactory = (params: {
@@ -2633,7 +2601,6 @@ type ClientAppDataFactory = (params: {
 }) => Record<string, unknown>;
 type ObserverConfig<AppData extends Record<string, unknown> = Record<string, unknown>> = ObserverUpdateConfig & {
     defaultCallUpdatePolicy?: ObservedCallSettings['updatePolicy'];
-    defaultCallUpdateIntervalInMs?: number;
     appData?: AppData;
     closeClientIfIdleForMs?: number;
     closeCallIfEmptyForMs?: number;
@@ -2651,6 +2618,13 @@ type ObserverConfig<AppData extends Record<string, unknown> = Record<string, unk
      * can be derived from `callId` / `clientId`.
      */
     createClientSink?: ClientSampleSinkFactory;
+    /**
+     * Optional factory invoked when a call is created, producing the call's `RemoteTrackResolver`
+     * (or `undefined` for none). Use the built-ins
+     * (`createDefaultMediasoupRemoteTrackResolverFactory()` / `createP2pRemoteTrackResolverFactory()`)
+     * or build a `RemoteTrackResolver` with custom publisher/subscriber id resolvers.
+     */
+    createTrackResolver?: RemoteTrackResolverFactory;
 };
 declare interface Observer {
     on<U extends keyof ObserverEvents>(event: U, listener: (...args: ObserverEvents[U]) => void): this;
@@ -2674,7 +2648,8 @@ declare class Observer<AppData extends Record<string, unknown> = Record<string,
     numberOfOutboundRtpStreams: number;
     numberOfDataChannels: number;
     numberOfPeerConnections: number;
-    private _timer?;
+    /** Global, pre-dispatch middleware chain run on every accepted sample. */
+    readonly acceptMiddlewares: MiddlewareProcessor<AcceptMiddlewarePayload>;
     constructor(config?: ObserverConfig<AppData>);
     get numberOfCalls(): number;
     get appData(): AppData | undefined;
@@ -2790,6 +2765,7 @@ declare class InMemorySink extends ClientSampleSink {
 }
 declare function createInMemorySink(samples?: ClientSample[]): InMemorySink;
 
-type Middleware<T> = (input: T, next: (nextInput: T) => void) => void;
+declare function createDefaultMediasoupRemoteTrackResolverFactory(): RemoteTrackResolverFactory;
+declare function createP2pRemoteTrackResolverFactory(): RemoteTrackResolverFactory;
 
-export { type AcceptContext, type CallAppDataFactory, type ClientAppDataFactory, type ClientEvent, ClientEventTypes, type ClientIssue, type ClientMetaData, ClientMetaTypes, type ClientReport, type ClientSample, ClientSampleSink, type ClientSampleSinkEvents, type ClientSampleSinkFactory, type Detector, Detectors, InMemorySink, JsonlFileSink, type JsonlFileSinkFactoryOptions, type JsonlFileSinkOptions, type Logger, type Middleware, ObservedCall, type ObservedCallScope, ObservedCertificate, ObservedClient, type ObservedClientScope, ObservedCodec, ObservedDataChannel, ObservedIceCandidate, ObservedIceCandidatePair, ObservedIceTransport, ObservedInboundRtp, ObservedInboundTrack, ObservedMediaPlayout, ObservedMediaSource, ObservedOutboundRtp, ObservedOutboundTrack, ObservedPeerConnection, type ObservedPeerConnectionScope, ObservedPeerConnectionTransport, ObservedRemoteInboundRtp, ObservedRemoteOutboundRtp, Observer, type ObserverEventBase, type ObserverEvents, type ObserverLogger, type SampleRejectedReason, type ScoreCalculator, type TrackReport, createInMemorySink, createJsonlFileSink, createJsonlFileSinkFactory, createLogger, setObserverLogger };
+export { type AcceptContext, type AcceptMiddleware, type AcceptMiddlewarePayload, type CallAppDataFactory, type ClientAppDataFactory, type ClientEvent, ClientEventTypes, type ClientIssue, type ClientMetaData, ClientMetaTypes, type ClientSample, ClientSampleSink, type ClientSampleSinkEvents, type ClientSampleSinkFactory, type Detector, Detectors, InMemorySink, JsonlFileSink, type JsonlFileSinkFactoryOptions, type JsonlFileSinkOptions, type Logger, type Middleware, ObservedCall, type ObservedCallScope, ObservedCertificate, ObservedClient, type ObservedClientScope, ObservedCodec, ObservedDataChannel, ObservedIceCandidate, ObservedIceCandidatePair, ObservedIceTransport, ObservedInboundRtp, ObservedInboundTrack, ObservedMediaPlayout, ObservedMediaSource, ObservedOutboundRtp, ObservedOutboundTrack, ObservedPeerConnection, type ObservedPeerConnectionScope, ObservedPeerConnectionTransport, ObservedRemoteInboundRtp, ObservedRemoteOutboundRtp, Observer, type ObserverEventBase, type ObserverEvents, type ObserverLogger, RemoteTrackResolver, type RemoteTrackResolverFactory, type RemoteTrackResolvers, type SampleRejectedReason, type ScoreCalculator, createDefaultMediasoupRemoteTrackResolverFactory, createInMemorySink, createJsonlFileSink, createJsonlFileSinkFactory, createLogger, createP2pRemoteTrackResolverFactory, setObserverLogger };