@reactor-team/js-sdk 2.11.1 → 2.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.mts CHANGED
@@ -136,6 +136,35 @@ interface ReactorState$1 {
136
136
  interface ConnectOptions {
137
137
  /** Maximum number of SDP polling attempts before giving up. Default: 6. */
138
138
  maxAttempts?: number;
139
+ /**
140
+ * When true (default), sends `resume_track` for every recvonly track
141
+ * immediately after the connection is established, causing the backend to
142
+ * begin streaming those tracks — this preserves the pre-multi-connection
143
+ * behaviour where output tracks flow automatically on connect. Set to false
144
+ * to keep recvonly tracks paused on connect and resume them individually via
145
+ * `resumeTrack()` (e.g. multi-connection apps that only subscribe to a
146
+ * subset of peers).
147
+ */
148
+ autoResumeTracks?: boolean;
149
+ /**
150
+ * Attach to a session that already exists (e.g. one created by a backend)
151
+ * instead of creating a new one. When set, `connect()` skips `POST /sessions`
152
+ * and brings up the transport directly against this id. The JWT passed to
153
+ * `connect()` must be valid for the account that owns the session.
154
+ */
155
+ sessionId?: string;
156
+ /**
157
+ * Use a specific WebRTC connection id instead of minting one. When omitted
158
+ * (default), the transport registers a fresh connection (`POST .../connections`)
159
+ * and the server mints the id. When set, the transport skips registration and
160
+ * sends its SDP offer directly to that connection — so the id must already have
161
+ * been registered under this session (e.g. a backend called `POST .../connections`
162
+ * and handed the id to this client) and must still be open.
163
+ *
164
+ * `connect()` rejects if the id is invalid (out of the server's accepted range)
165
+ * or if no open connection with that id exists for the session.
166
+ */
167
+ connectionId?: number;
139
168
  }
140
169
  /**
141
170
  * Transport-agnostic timing breakdown of the connect() handshake, recorded
@@ -177,6 +206,50 @@ interface ConnectionStats {
177
206
  timestamp: number;
178
207
  }
179
208
  type ReactorEvent = "statusChanged" | "sessionIdChanged" | "message" | "runtimeMessage" | "trackReceived" | "error" | "sessionExpirationChanged" | "capabilitiesReceived" | "statsUpdate";
209
+ /**
210
+ * Severity tier of a content moderation event delivered as the inner
211
+ * payload of a `runtimeMessage` with `type === "moderation"`.
212
+ *
213
+ * - `"warn"`: the input scored above the warn threshold but below the
214
+ * terminate threshold. The session continues; this is informational
215
+ * only.
216
+ * - `"terminate"`: the input crossed the terminate threshold. The
217
+ * session will be ended shortly after this message is dispatched.
218
+ */
219
+ type ModerationAction = "warn" | "terminate";
220
+ /**
221
+ * Inner payload of a `runtimeMessage` with `type === "moderation"`.
222
+ *
223
+ * Surfaces a content-moderation outcome to the client app. Fires on
224
+ * any moderatable input (free-text fields, file uploads) that the
225
+ * configured moderation policy flags. Apps receive it by subscribing
226
+ * to the existing `runtimeMessage` event and filtering on `type`:
227
+ *
228
+ * reactor.on("runtimeMessage", (m) => {
229
+ * if (m?.type === "moderation") {
230
+ * const payload = m.data as ModerationEvent;
231
+ * // ...render banner, log, etc.
232
+ * }
233
+ * });
234
+ */
235
+ interface ModerationEvent {
236
+ /** Severity tier — `"warn"` continues the session, `"terminate"` ends it. */
237
+ action: ModerationAction;
238
+ /**
239
+ * Modality of the flagged input. `"text"` for string fields,
240
+ * `"image"` for `UploadedFile` payloads with an image MIME type.
241
+ */
242
+ input_kind: "text" | "image";
243
+ /**
244
+ * Name of the inbound command/event whose payload was flagged
245
+ * (e.g. `"set_prompt"`, `"set_image"`, `"fileUploaded"`).
246
+ */
247
+ command: string;
248
+ /** Category labels that flagged (e.g. `["sexual"]`, `["violence/graphic"]`). */
249
+ categories: string[];
250
+ /** Short human-readable summary suitable for UI rendering. */
251
+ message: string;
252
+ }
180
253
 
181
254
  /**
182
255
  * Lazy resolver for the Coordinator bearer token. The SDK calls this
@@ -590,11 +663,21 @@ declare class Reactor {
590
663
  private sessionExpiration?;
591
664
  private local;
592
665
  private sessionId?;
666
+ /**
667
+ * True only when the active session was created by THIS connect flow
668
+ * (via `createSession()`). False when the session was adopted via
669
+ * `connect({ sessionId })`. We must never DELETE a session we did not
670
+ * create — another client (or the backend that created it) owns its
671
+ * lifecycle, so on disconnect/teardown/error an adopting client tears
672
+ * down its own transport but leaves the session alive.
673
+ */
674
+ private createdSession;
593
675
  private connectStartTime?;
594
676
  private connectionTimings?;
595
677
  private capabilities?;
596
678
  private tracks;
597
679
  private presetTracks?;
680
+ private autoResumeTracks;
598
681
  private sessionResponse?;
599
682
  private jwtResolver?;
600
683
  /** Per-Reactor recording client. See {@link RecordingClient}. */
@@ -666,6 +749,8 @@ declare class Reactor {
666
749
  */
667
750
  publishTrack(name: string, track: MediaStreamTrack): Promise<void>;
668
751
  unpublishTrack(name: string): Promise<void>;
752
+ pauseTrack(name: string): void;
753
+ resumeTrack(name: string): void;
669
754
  /**
670
755
  * Reconnects to an existing session with a fresh transport.
671
756
  */
@@ -676,6 +761,12 @@ declare class Reactor {
676
761
  * be a static string or a {@link JwtSource} resolver; pass a
677
762
  * resolver when the token is short-lived so each Coordinator HTTP
678
763
  * hop sees a fresh value.
764
+ *
765
+ * Pass `options.sessionId` to attach to a session that already exists
766
+ * (e.g. one created by a backend) instead of creating a new one — session
767
+ * creation is skipped and the transport is brought up against that id. The
768
+ * `jwtToken` must be valid for the account that owns the session. Works in
769
+ * local mode too (it looks the session up by id rather than starting one).
679
770
  */
680
771
  connect(jwtToken?: JwtSource, options?: ConnectOptions): Promise<void>;
681
772
  /**
@@ -716,9 +807,21 @@ interface ReactorState {
716
807
  sessionExpiration?: number;
717
808
  /** Token source for Coordinator HTTP calls — see {@link JwtSource}. */
718
809
  jwtToken?: JwtSource;
810
+ /**
811
+ * Default connect options set by the provider. Applied as base values
812
+ * whenever `connect()` is called without explicit options, so that
813
+ * provider-level settings like `autoResumeTracks` are honoured for
814
+ * both autoConnect and manual connect calls.
815
+ */
816
+ connectOptions?: ConnectOptions;
719
817
  }
720
818
  interface ReactorActions {
721
819
  sendCommand(command: string, data: any, scope?: MessageScope): Promise<void>;
820
+ /**
821
+ * Connect the underlying {@link Reactor}. `options` is forwarded verbatim —
822
+ * pass `options.sessionId` to attach to an existing session instead of
823
+ * creating one (see {@link ConnectOptions}).
824
+ */
722
825
  connect(jwtToken?: JwtSource, options?: ConnectOptions): Promise<void>;
723
826
  disconnect(recoverable?: boolean): Promise<void>;
724
827
  publish(name: string, track: MediaStreamTrack): Promise<void>;
@@ -758,6 +861,8 @@ type ReactorStore = ReactorState & ReactorActions & {
758
861
  interface ReactorInitializationProps extends Options {
759
862
  /** Token source for the underlying {@link Reactor} — see {@link JwtSource}. */
760
863
  jwtToken?: JwtSource;
864
+ /** Default connect options applied when `connect()` is called without explicit options. */
865
+ connectOptions?: ConnectOptions;
761
866
  }
762
867
 
763
868
  /**
@@ -1161,4 +1266,4 @@ declare function useReactorInternalMessage(handler: (message: any) => void): voi
1161
1266
  */
1162
1267
  declare function useStats(): ConnectionStats | undefined;
1163
1268
 
1164
- export { AbortError, type Capabilities, type Clip, ClipDownloadButton, type ClipDownloadButtonProps, type ClipDownloadState, type ClipFailedPayload, type ClipKind, ClipPlayer, type ClipPlayerProps, type ClipReadyPayload, type CommandCapability, ConflictError, type ConnectOptions, type ConnectionStats, type ConnectionTimings, DEFAULT_BASE_URL, DEFAULT_CLIP_REQUEST_TIMEOUT_MS, DEFAULT_PLAYLIST_POLL_SLACK_MS, type DownloadClipOptions, type FetchPlaylistOptions, FileRef, type JwtResolver, type JwtSource, type MessageScope, type Options, type ParseClipOptions, Reactor, type ReactorConnectOptions, ReactorController, type ReactorControllerProps, type ReactorError, type ReactorEvent, ReactorProvider, type ReactorState$1 as ReactorState, type ReactorStatus, type ReactorStore, ReactorView, type ReactorViewProps, RecordingClient, type RecordingClientHost, RecordingError, RuntimeRecordingMessageType, type SessionResponse, type TrackCapability, type UseClipDownloadOptions, type UseClipDownloadResult, WebcamStream, type WebcamStreamProps, clipFromPayload, createPlayableManifestUrl, downloadClipAsFile, fetchPlaylist, isAbortError, normalizeJwtSource, parsePlaylist, rewriteUrlHost, useClipDownload, useReactor, useReactorInternalMessage, useReactorMessage, useReactorStore, useStats };
1269
+ export { AbortError, type Capabilities, type Clip, ClipDownloadButton, type ClipDownloadButtonProps, type ClipDownloadState, type ClipFailedPayload, type ClipKind, ClipPlayer, type ClipPlayerProps, type ClipReadyPayload, type CommandCapability, ConflictError, type ConnectOptions, type ConnectionStats, type ConnectionTimings, DEFAULT_BASE_URL, DEFAULT_CLIP_REQUEST_TIMEOUT_MS, DEFAULT_PLAYLIST_POLL_SLACK_MS, type DownloadClipOptions, type FetchPlaylistOptions, FileRef, type JwtResolver, type JwtSource, type MessageScope, type ModerationAction, type ModerationEvent, type Options, type ParseClipOptions, Reactor, type ReactorConnectOptions, ReactorController, type ReactorControllerProps, type ReactorError, type ReactorEvent, ReactorProvider, type ReactorState$1 as ReactorState, type ReactorStatus, type ReactorStore, ReactorView, type ReactorViewProps, RecordingClient, type RecordingClientHost, RecordingError, RuntimeRecordingMessageType, type SessionResponse, type TrackCapability, type UseClipDownloadOptions, type UseClipDownloadResult, WebcamStream, type WebcamStreamProps, clipFromPayload, createPlayableManifestUrl, downloadClipAsFile, fetchPlaylist, isAbortError, normalizeJwtSource, parsePlaylist, rewriteUrlHost, useClipDownload, useReactor, useReactorInternalMessage, useReactorMessage, useReactorStore, useStats };
package/dist/index.d.ts CHANGED
@@ -136,6 +136,35 @@ interface ReactorState$1 {
136
136
  interface ConnectOptions {
137
137
  /** Maximum number of SDP polling attempts before giving up. Default: 6. */
138
138
  maxAttempts?: number;
139
+ /**
140
+ * When true (default), sends `resume_track` for every recvonly track
141
+ * immediately after the connection is established, causing the backend to
142
+ * begin streaming those tracks — this preserves the pre-multi-connection
143
+ * behaviour where output tracks flow automatically on connect. Set to false
144
+ * to keep recvonly tracks paused on connect and resume them individually via
145
+ * `resumeTrack()` (e.g. multi-connection apps that only subscribe to a
146
+ * subset of peers).
147
+ */
148
+ autoResumeTracks?: boolean;
149
+ /**
150
+ * Attach to a session that already exists (e.g. one created by a backend)
151
+ * instead of creating a new one. When set, `connect()` skips `POST /sessions`
152
+ * and brings up the transport directly against this id. The JWT passed to
153
+ * `connect()` must be valid for the account that owns the session.
154
+ */
155
+ sessionId?: string;
156
+ /**
157
+ * Use a specific WebRTC connection id instead of minting one. When omitted
158
+ * (default), the transport registers a fresh connection (`POST .../connections`)
159
+ * and the server mints the id. When set, the transport skips registration and
160
+ * sends its SDP offer directly to that connection — so the id must already have
161
+ * been registered under this session (e.g. a backend called `POST .../connections`
162
+ * and handed the id to this client) and must still be open.
163
+ *
164
+ * `connect()` rejects if the id is invalid (out of the server's accepted range)
165
+ * or if no open connection with that id exists for the session.
166
+ */
167
+ connectionId?: number;
139
168
  }
140
169
  /**
141
170
  * Transport-agnostic timing breakdown of the connect() handshake, recorded
@@ -177,6 +206,50 @@ interface ConnectionStats {
177
206
  timestamp: number;
178
207
  }
179
208
  type ReactorEvent = "statusChanged" | "sessionIdChanged" | "message" | "runtimeMessage" | "trackReceived" | "error" | "sessionExpirationChanged" | "capabilitiesReceived" | "statsUpdate";
209
+ /**
210
+ * Severity tier of a content moderation event delivered as the inner
211
+ * payload of a `runtimeMessage` with `type === "moderation"`.
212
+ *
213
+ * - `"warn"`: the input scored above the warn threshold but below the
214
+ * terminate threshold. The session continues; this is informational
215
+ * only.
216
+ * - `"terminate"`: the input crossed the terminate threshold. The
217
+ * session will be ended shortly after this message is dispatched.
218
+ */
219
+ type ModerationAction = "warn" | "terminate";
220
+ /**
221
+ * Inner payload of a `runtimeMessage` with `type === "moderation"`.
222
+ *
223
+ * Surfaces a content-moderation outcome to the client app. Fires on
224
+ * any moderatable input (free-text fields, file uploads) that the
225
+ * configured moderation policy flags. Apps receive it by subscribing
226
+ * to the existing `runtimeMessage` event and filtering on `type`:
227
+ *
228
+ * reactor.on("runtimeMessage", (m) => {
229
+ * if (m?.type === "moderation") {
230
+ * const payload = m.data as ModerationEvent;
231
+ * // ...render banner, log, etc.
232
+ * }
233
+ * });
234
+ */
235
+ interface ModerationEvent {
236
+ /** Severity tier — `"warn"` continues the session, `"terminate"` ends it. */
237
+ action: ModerationAction;
238
+ /**
239
+ * Modality of the flagged input. `"text"` for string fields,
240
+ * `"image"` for `UploadedFile` payloads with an image MIME type.
241
+ */
242
+ input_kind: "text" | "image";
243
+ /**
244
+ * Name of the inbound command/event whose payload was flagged
245
+ * (e.g. `"set_prompt"`, `"set_image"`, `"fileUploaded"`).
246
+ */
247
+ command: string;
248
+ /** Category labels that flagged (e.g. `["sexual"]`, `["violence/graphic"]`). */
249
+ categories: string[];
250
+ /** Short human-readable summary suitable for UI rendering. */
251
+ message: string;
252
+ }
180
253
 
181
254
  /**
182
255
  * Lazy resolver for the Coordinator bearer token. The SDK calls this
@@ -590,11 +663,21 @@ declare class Reactor {
590
663
  private sessionExpiration?;
591
664
  private local;
592
665
  private sessionId?;
666
+ /**
667
+ * True only when the active session was created by THIS connect flow
668
+ * (via `createSession()`). False when the session was adopted via
669
+ * `connect({ sessionId })`. We must never DELETE a session we did not
670
+ * create — another client (or the backend that created it) owns its
671
+ * lifecycle, so on disconnect/teardown/error an adopting client tears
672
+ * down its own transport but leaves the session alive.
673
+ */
674
+ private createdSession;
593
675
  private connectStartTime?;
594
676
  private connectionTimings?;
595
677
  private capabilities?;
596
678
  private tracks;
597
679
  private presetTracks?;
680
+ private autoResumeTracks;
598
681
  private sessionResponse?;
599
682
  private jwtResolver?;
600
683
  /** Per-Reactor recording client. See {@link RecordingClient}. */
@@ -666,6 +749,8 @@ declare class Reactor {
666
749
  */
667
750
  publishTrack(name: string, track: MediaStreamTrack): Promise<void>;
668
751
  unpublishTrack(name: string): Promise<void>;
752
+ pauseTrack(name: string): void;
753
+ resumeTrack(name: string): void;
669
754
  /**
670
755
  * Reconnects to an existing session with a fresh transport.
671
756
  */
@@ -676,6 +761,12 @@ declare class Reactor {
676
761
  * be a static string or a {@link JwtSource} resolver; pass a
677
762
  * resolver when the token is short-lived so each Coordinator HTTP
678
763
  * hop sees a fresh value.
764
+ *
765
+ * Pass `options.sessionId` to attach to a session that already exists
766
+ * (e.g. one created by a backend) instead of creating a new one — session
767
+ * creation is skipped and the transport is brought up against that id. The
768
+ * `jwtToken` must be valid for the account that owns the session. Works in
769
+ * local mode too (it looks the session up by id rather than starting one).
679
770
  */
680
771
  connect(jwtToken?: JwtSource, options?: ConnectOptions): Promise<void>;
681
772
  /**
@@ -716,9 +807,21 @@ interface ReactorState {
716
807
  sessionExpiration?: number;
717
808
  /** Token source for Coordinator HTTP calls — see {@link JwtSource}. */
718
809
  jwtToken?: JwtSource;
810
+ /**
811
+ * Default connect options set by the provider. Applied as base values
812
+ * whenever `connect()` is called without explicit options, so that
813
+ * provider-level settings like `autoResumeTracks` are honoured for
814
+ * both autoConnect and manual connect calls.
815
+ */
816
+ connectOptions?: ConnectOptions;
719
817
  }
720
818
  interface ReactorActions {
721
819
  sendCommand(command: string, data: any, scope?: MessageScope): Promise<void>;
820
+ /**
821
+ * Connect the underlying {@link Reactor}. `options` is forwarded verbatim —
822
+ * pass `options.sessionId` to attach to an existing session instead of
823
+ * creating one (see {@link ConnectOptions}).
824
+ */
722
825
  connect(jwtToken?: JwtSource, options?: ConnectOptions): Promise<void>;
723
826
  disconnect(recoverable?: boolean): Promise<void>;
724
827
  publish(name: string, track: MediaStreamTrack): Promise<void>;
@@ -758,6 +861,8 @@ type ReactorStore = ReactorState & ReactorActions & {
758
861
  interface ReactorInitializationProps extends Options {
759
862
  /** Token source for the underlying {@link Reactor} — see {@link JwtSource}. */
760
863
  jwtToken?: JwtSource;
864
+ /** Default connect options applied when `connect()` is called without explicit options. */
865
+ connectOptions?: ConnectOptions;
761
866
  }
762
867
 
763
868
  /**
@@ -1161,4 +1266,4 @@ declare function useReactorInternalMessage(handler: (message: any) => void): voi
1161
1266
  */
1162
1267
  declare function useStats(): ConnectionStats | undefined;
1163
1268
 
1164
- export { AbortError, type Capabilities, type Clip, ClipDownloadButton, type ClipDownloadButtonProps, type ClipDownloadState, type ClipFailedPayload, type ClipKind, ClipPlayer, type ClipPlayerProps, type ClipReadyPayload, type CommandCapability, ConflictError, type ConnectOptions, type ConnectionStats, type ConnectionTimings, DEFAULT_BASE_URL, DEFAULT_CLIP_REQUEST_TIMEOUT_MS, DEFAULT_PLAYLIST_POLL_SLACK_MS, type DownloadClipOptions, type FetchPlaylistOptions, FileRef, type JwtResolver, type JwtSource, type MessageScope, type Options, type ParseClipOptions, Reactor, type ReactorConnectOptions, ReactorController, type ReactorControllerProps, type ReactorError, type ReactorEvent, ReactorProvider, type ReactorState$1 as ReactorState, type ReactorStatus, type ReactorStore, ReactorView, type ReactorViewProps, RecordingClient, type RecordingClientHost, RecordingError, RuntimeRecordingMessageType, type SessionResponse, type TrackCapability, type UseClipDownloadOptions, type UseClipDownloadResult, WebcamStream, type WebcamStreamProps, clipFromPayload, createPlayableManifestUrl, downloadClipAsFile, fetchPlaylist, isAbortError, normalizeJwtSource, parsePlaylist, rewriteUrlHost, useClipDownload, useReactor, useReactorInternalMessage, useReactorMessage, useReactorStore, useStats };
1269
+ export { AbortError, type Capabilities, type Clip, ClipDownloadButton, type ClipDownloadButtonProps, type ClipDownloadState, type ClipFailedPayload, type ClipKind, ClipPlayer, type ClipPlayerProps, type ClipReadyPayload, type CommandCapability, ConflictError, type ConnectOptions, type ConnectionStats, type ConnectionTimings, DEFAULT_BASE_URL, DEFAULT_CLIP_REQUEST_TIMEOUT_MS, DEFAULT_PLAYLIST_POLL_SLACK_MS, type DownloadClipOptions, type FetchPlaylistOptions, FileRef, type JwtResolver, type JwtSource, type MessageScope, type ModerationAction, type ModerationEvent, type Options, type ParseClipOptions, Reactor, type ReactorConnectOptions, ReactorController, type ReactorControllerProps, type ReactorError, type ReactorEvent, ReactorProvider, type ReactorState$1 as ReactorState, type ReactorStatus, type ReactorStore, ReactorView, type ReactorViewProps, RecordingClient, type RecordingClientHost, RecordingError, RuntimeRecordingMessageType, type SessionResponse, type TrackCapability, type UseClipDownloadOptions, type UseClipDownloadResult, WebcamStream, type WebcamStreamProps, clipFromPayload, createPlayableManifestUrl, downloadClipAsFile, fetchPlaylist, isAbortError, normalizeJwtSource, parsePlaylist, rewriteUrlHost, useClipDownload, useReactor, useReactorInternalMessage, useReactorMessage, useReactorStore, useStats };