@reactor-team/js-sdk 2.12.0 → 2.12.2

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/README.md CHANGED
@@ -17,7 +17,7 @@ pnpm create reactor-app my-app
17
17
  cd my-app && pnpm install && pnpm dev
18
18
  ```
19
19
 
20
- Or wire it up by hand. Exchange your API key for a short-lived JWT on the server, then mount `<ReactorProvider>` in the client:
20
+ Or wire it up by hand. Exchange your API key on the server for a short-lived JWT **scoped to your model**, then mount `<ReactorProvider>` in the client. The `authorization_details` block is what downscopes the token: it can create a bounded number of sessions for that one model and act only on the sessions it created — a leaked token exposes nothing else on the account:
21
21
 
22
22
  ```ts
23
23
  // app/api/token/route.ts
@@ -26,7 +26,19 @@ import { NextResponse } from "next/server";
26
26
  export async function POST() {
27
27
  const r = await fetch("https://api.reactor.inc/tokens", {
28
28
  method: "POST",
29
- headers: { "Reactor-API-Key": process.env.REACTOR_API_KEY! },
29
+ headers: {
30
+ "Reactor-API-Key": process.env.REACTOR_API_KEY!,
31
+ "Content-Type": "application/json",
32
+ },
33
+ body: JSON.stringify({
34
+ authorization_details: [
35
+ {
36
+ type: "session",
37
+ resources: { models: { match: ["your-org/your-model-name"] } },
38
+ constraints: { max_sessions: 10 },
39
+ },
40
+ ],
41
+ }),
30
42
  });
31
43
  const { jwt } = await r.json();
32
44
  return NextResponse.json({ jwt });
@@ -219,7 +231,7 @@ For models with a published typed SDK, prefer [`@reactor-models/<name>`](https:/
219
231
  | Surface | Where it lives |
220
232
  | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
221
233
  | `Reactor` | [Reactor class](https://docs.reactor.inc/api-reference/reactor-class) |
222
- | `<ReactorProvider>`, `<ReactorView>`, `<WebcamStream>`, `<ReactorController>` | [React components](https://docs.reactor.inc/api-reference/react-components) |
234
+ | `<ReactorProvider>`, `<ReactorView>`, `<WebcamStream>` | [React components](https://docs.reactor.inc/api-reference/react-components) |
223
235
  | `useReactor`, `useReactorMessage`, `useStats` | [React hooks](https://docs.reactor.inc/api-reference/react-hooks) |
224
236
  | `<ClipPlayer>`, `<ClipDownloadButton>`, `useClipDownload`, `RecordingClient`, `RecordingError`, `fetchPlaylist`, `parsePlaylist` | [Recordings](https://docs.reactor.inc/concepts/recordings) |
225
237
 
package/dist/index.d.mts CHANGED
@@ -85,6 +85,52 @@ type TrackCapability = z.infer<typeof TrackCapabilitySchema>;
85
85
  type CommandCapability = z.infer<typeof CommandCapabilitySchema>;
86
86
  type SessionResponse = z.infer<typeof SessionResponseSchema>;
87
87
  type Capabilities = z.infer<typeof CapabilitiesSchema>;
88
+ /** One OpenAPI operation (the `post` of an event/webhook path item). */
89
+ interface ModelSchemaOperation {
90
+ operationId?: string;
91
+ summary?: string;
92
+ description?: string;
93
+ requestBody?: {
94
+ required?: boolean;
95
+ content?: Record<string, {
96
+ schema?: Record<string, unknown>;
97
+ }>;
98
+ };
99
+ responses?: Record<string, unknown>;
100
+ [key: string]: unknown;
101
+ }
102
+ /** An OpenAPI path item; the runtime only populates `post`. */
103
+ interface ModelSchemaPathItem {
104
+ post?: ModelSchemaOperation;
105
+ [key: string]: unknown;
106
+ }
107
+ /**
108
+ * The model's OpenAPI 3.1 schema, returned by the runtime in response to a
109
+ * `requestSchema` runtime-channel command. This is a pass-through of the
110
+ * runtime's document, not a shape the SDK reshapes: client-triggerable
111
+ * events live under `paths` as `POST /events/<name>` operations, outbound
112
+ * model messages under `webhooks`, and media tracks under `x-reactor.tracks`.
113
+ * Read the parts you need.
114
+ */
115
+ interface ModelSchema {
116
+ openapi: string;
117
+ info: {
118
+ title: string;
119
+ version: string;
120
+ description?: string;
121
+ };
122
+ paths?: Record<string, ModelSchemaPathItem>;
123
+ webhooks?: Record<string, ModelSchemaPathItem>;
124
+ "x-reactor"?: {
125
+ tracks?: Array<{
126
+ name: string;
127
+ kind: string;
128
+ direction: string;
129
+ }>;
130
+ };
131
+ components?: Record<string, unknown>;
132
+ [key: string]: unknown;
133
+ }
88
134
 
89
135
  /**
90
136
  * Reference to an uploaded file, returned by {@link Reactor.uploadFile}.
@@ -126,6 +172,10 @@ declare class AbortError extends Error {
126
172
  }
127
173
  /** Matches both our custom AbortError and the native DOMException thrown by fetch(). */
128
174
  declare function isAbortError(error: unknown): boolean;
175
+ declare class SessionLostError extends Error {
176
+ constructor(message: string);
177
+ }
178
+ declare function isSessionLostError(error: unknown): boolean;
129
179
  interface ReactorState$1 {
130
180
  status: ReactorStatus;
131
181
  lastError?: ReactorError;
@@ -205,7 +255,7 @@ interface ConnectionStats {
205
255
  connectionTimings?: ConnectionTimings;
206
256
  timestamp: number;
207
257
  }
208
- type ReactorEvent = "statusChanged" | "sessionIdChanged" | "message" | "runtimeMessage" | "trackReceived" | "error" | "sessionExpirationChanged" | "capabilitiesReceived" | "statsUpdate";
258
+ type ReactorEvent = "statusChanged" | "sessionIdChanged" | "message" | "runtimeMessage" | "trackReceived" | "error" | "sessionExpirationChanged" | "schemaReceived" | "statsUpdate";
209
259
  /**
210
260
  * Severity tier of a content moderation event delivered as the inner
211
261
  * payload of a `runtimeMessage` with `type === "moderation"`.
@@ -316,9 +366,10 @@ type ClipKind = "snap" | "recording";
316
366
  * - `predictedReadyAtMs` is a **Unix epoch in milliseconds** — the
317
367
  * runtime's estimate of when the boundary chunk will be servable
318
368
  * by `/clips`. Compare against `Date.now()` to drive a "ready in
319
- * Ns" indicator. The SDK uses this as the polling deadline: past
320
- * `predictedReadyAtMs + slackMs` and still 202, the SDK fails with
321
- * `CLIP_NOT_READY` on the assumption the runtime crashed.
369
+ * Ns" indicator. It is only an estimate: the SDK polls `/clips`
370
+ * until the manifest is actually ready and does not give up when
371
+ * this epoch passes (see {@link fetchPlaylist} for the polling and
372
+ * cancellation model).
322
373
  * - `playlistUrl` is short-lived in production (the embedded chunk
323
374
  * URLs are presigned for a few minutes). Re-issuing the request
324
375
  * produces a fresh URL with fresh presigning.
@@ -407,21 +458,29 @@ interface ParsedPlaylist {
407
458
  segmentUrls: string[];
408
459
  }
409
460
  /**
410
- * Default grace period after `predictedReadyAtMs` before
411
- * {@link fetchPlaylist} gives up. Applied from
412
- * `max(predictedReadyAtMs, pollStart)` so late clicks still get the
413
- * full window.
461
+ * Suggested grace period for callers that opt into a *bounded* wait by
462
+ * passing it as {@link FetchPlaylistOptions.slackMs}. It is **not** a
463
+ * default: {@link fetchPlaylist} polls indefinitely unless a bound is
464
+ * supplied. Provided so callers who do want the old ~15 s ceiling can
465
+ * ask for it by name rather than hard-coding a magic number.
414
466
  */
415
467
  declare const DEFAULT_PLAYLIST_POLL_SLACK_MS = 15000;
416
468
  interface FetchPlaylistOptions {
417
469
  /**
418
470
  * Unix epoch (ms) when the runtime predicts the boundary chunk will
419
- * be servable. Pass `clip.predictedReadyAtMs` here. When set, polling
420
- * continues until `predictedReadyAtMs + slackMs`; once past, a
421
- * stuck `202` produces `CLIP_NOT_READY` (assume runtime crashed).
471
+ * be servable. Pass `clip.predictedReadyAtMs` here. On its own it
472
+ * does *not* stop polling — it only anchors the optional `slackMs`
473
+ * deadline. Use it to drive a "ready in Ns" indicator.
422
474
  */
423
475
  predictedReadyAtMs?: number;
424
- /** Grace period after `predictedReadyAtMs`. Default {@link DEFAULT_PLAYLIST_POLL_SLACK_MS}. */
476
+ /**
477
+ * Opt-in grace period that turns polling into a *bounded* wait. When
478
+ * set to a finite value, a stuck `202` produces `CLIP_NOT_READY` once
479
+ * `max(predictedReadyAtMs, pollStart) + slackMs` passes. Omit (the
480
+ * default) to poll indefinitely until the manifest is ready or the
481
+ * caller aborts via `signal`. See {@link DEFAULT_PLAYLIST_POLL_SLACK_MS}
482
+ * for a sensible value if you want the old ~15 s ceiling.
483
+ */
425
484
  slackMs?: number;
426
485
  /**
427
486
  * Hard cap on the per-poll wait. The server's `Retry-After` header is
@@ -431,12 +490,18 @@ interface FetchPlaylistOptions {
431
490
  /** Floor on the per-poll wait so we don't hot-loop on cheap networks. Default 200 ms. */
432
491
  minRetryDelayMs?: number;
433
492
  /**
434
- * Fallback retry count used when `predictedReadyAtMs` is omitted
435
- * (e.g. someone calls `fetchPlaylist` directly with a saved URL,
436
- * outside of a fresh `Clip`). Default 5.
493
+ * Opt-in cap on the number of `202` responses tolerated before
494
+ * `CLIP_NOT_READY`. Omit (the default) to poll indefinitely; set it
495
+ * for a simple attempt-count ceiling when you don't have a
496
+ * `predictedReadyAtMs` to anchor a `slackMs` deadline.
437
497
  */
438
498
  maxRetries?: number;
439
- /** Aborts in-flight fetches and the inter-poll sleep. */
499
+ /**
500
+ * Aborts in-flight fetches and the inter-poll sleep. Because polling
501
+ * is unbounded by default, this is the primary way a caller ends a
502
+ * wait that is taking too long (a timeout, a user "cancel", a React
503
+ * unmount).
504
+ */
440
505
  signal?: AbortSignal;
441
506
  /**
442
507
  * Coordinator JWT. When set, attached as `Authorization: Bearer
@@ -449,14 +514,19 @@ interface FetchPlaylistOptions {
449
514
  * Fetch the playlist URL, polling on `202 Accepted` (which the manifest
450
515
  * endpoint returns while the boundary chunk is still uploading).
451
516
  *
452
- * Polling deadline is driven by `predictedReadyAtMs + slackMs` when a
453
- * `Clip` was just minted by the runtime; without that field the
454
- * function falls back to `maxRetries` attempts. Either way:
517
+ * Polling is **unbounded by default** — it keeps retrying on `202`
518
+ * until the manifest is ready or the caller aborts via `signal`. This
519
+ * matches the reality that a clip's boundary chunk can take arbitrarily
520
+ * long to land (a paused model closes no chunks; a long recording's
521
+ * final chunk is large). Callers own the give-up policy: pass `signal`
522
+ * to cancel, or opt into a ceiling with `slackMs` / `maxRetries`.
523
+ *
455
524
  * - `200` → returns the manifest body.
456
525
  * - `410` / `404` → throws `CLIP_GONE`.
457
526
  * - `5xx`/other → throws `PLAYLIST_FETCH_FAILED` (no retry).
458
- * - Past the deadline / retries with stuck `202` → throws
459
- * `CLIP_NOT_READY` (the runtime probably crashed mid-chunk).
527
+ * - `202` past an opt-in `slackMs` deadline or `maxRetries` cap →
528
+ * throws `CLIP_NOT_READY`.
529
+ * - aborted `signal` → rejects with the fetch/`sleep` `AbortError`.
460
530
  */
461
531
  declare function fetchPlaylist(playlistUrl: string, options?: FetchPlaylistOptions): Promise<string>;
462
532
  /**
@@ -672,9 +742,10 @@ declare class Reactor {
672
742
  * down its own transport but leaves the session alive.
673
743
  */
674
744
  private createdSession;
745
+ private retryingSessionLoss;
675
746
  private connectStartTime?;
676
747
  private connectionTimings?;
677
- private capabilities?;
748
+ private schema?;
678
749
  private tracks;
679
750
  private presetTracks?;
680
751
  private autoResumeTracks;
@@ -782,9 +853,16 @@ declare class Reactor {
782
853
  getStatus(): ReactorStatus;
783
854
  getState(): ReactorState$1;
784
855
  getLastError(): ReactorError | undefined;
785
- getCapabilities(): Capabilities | undefined;
856
+ /**
857
+ * The model's OpenAPI schema (events, outbound messages, tracks),
858
+ * received over the runtime channel shortly after the session becomes
859
+ * ready. `undefined` until the `schemaReceived` event has fired.
860
+ */
861
+ getSchema(): ModelSchema | undefined;
786
862
  getSessionInfo(): SessionResponse | undefined;
787
863
  getStats(): ConnectionStats | undefined;
864
+ /** Timing breakdown from the most recent connect() handshake. */
865
+ getConnectionTimings(): ConnectionTimings | undefined;
788
866
  private setSessionId;
789
867
  private setStatus;
790
868
  private setSessionExpiration;
@@ -826,6 +904,19 @@ interface ReactorActions {
826
904
  disconnect(recoverable?: boolean): Promise<void>;
827
905
  publish(name: string, track: MediaStreamTrack): Promise<void>;
828
906
  unpublish(name: string): Promise<void>;
907
+ /**
908
+ * Ask the runtime to stop processing a recvonly track. Top-level
909
+ * alias for `internal.reactor.pauseTrack(…)` — lifted onto the store
910
+ * so consumers don't have to reach through `internal.reactor`. See
911
+ * {@link Reactor.pauseTrack}.
912
+ */
913
+ pauseTrack(name: string): void;
914
+ /**
915
+ * Ask the runtime to resume a previously paused recvonly track.
916
+ * Top-level alias for `internal.reactor.resumeTrack(…)`. See
917
+ * {@link Reactor.resumeTrack}.
918
+ */
919
+ resumeTrack(name: string): void;
829
920
  reconnect(options?: ConnectOptions): Promise<void>;
830
921
  uploadFile(file: File | Blob, options?: {
831
922
  name?: string;
@@ -921,12 +1012,6 @@ interface ReactorViewProps {
921
1012
  }
922
1013
  declare function ReactorView({ track, audioTrack, width, height, className, style, videoObjectFit, muted, }: ReactorViewProps): react_jsx_runtime.JSX.Element;
923
1014
 
924
- interface ReactorControllerProps {
925
- className?: string;
926
- style?: React.CSSProperties;
927
- }
928
- declare function ReactorController({ className, style, }: ReactorControllerProps): react_jsx_runtime.JSX.Element;
929
-
930
1015
  interface WebcamStreamProps {
931
1016
  /**
932
1017
  * The name of the sendonly **video** track to publish the webcam to.
@@ -1034,16 +1119,15 @@ interface ClipPlayerProps {
1034
1119
  */
1035
1120
  getJwt?: () => string | Promise<string>;
1036
1121
  /**
1037
- * Override the grace period beyond ``clip.predictedReadyAtMs``
1038
- * before the SDK gives up polling the ``/clips`` manifest endpoint
1039
- * with ``CLIP_NOT_READY``. Defaults to
1040
- * {@link DEFAULT_PLAYLIST_POLL_SLACK_MS} (15 s) — enough for snap
1041
- * clips, but long-running session recordings may legitimately need
1042
- * a minute or more for the final boundary chunk to finish encoding
1043
- * + uploading, in which case pass a larger value (e.g. ``120_000``
1044
- * for two-minute grace). Forwarded directly to
1045
- * {@link fetchPlaylist}'s ``slackMs`` option — see that helper for
1046
- * the polling semantics.
1122
+ * Opt into a *bounded* wait: give up polling the ``/clips`` manifest
1123
+ * endpoint with ``CLIP_NOT_READY`` once
1124
+ * ``max(clip.predictedReadyAtMs, pollStart) + slackMs`` passes. By
1125
+ * default this is **unset** — the player polls indefinitely until the
1126
+ * clip is ready, and stops only when it unmounts or ``clip`` changes
1127
+ * (both abort the in-flight poll). Set a value when you want a hard
1128
+ * ceiling (e.g. ``120_000`` for a two-minute cap). Forwarded
1129
+ * directly to {@link fetchPlaylist}'s ``slackMs`` option — see that
1130
+ * helper for the polling semantics.
1047
1131
  */
1048
1132
  slackMs?: number;
1049
1133
  /** Play automatically once the manifest is attached. Default ``true``. */
@@ -1266,4 +1350,4 @@ declare function useReactorInternalMessage(handler: (message: any) => void): voi
1266
1350
  */
1267
1351
  declare function useStats(): ConnectionStats | undefined;
1268
1352
 
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 };
1353
+ 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 ModelSchema, type ModelSchemaOperation, type ModelSchemaPathItem, type ModerationAction, type ModerationEvent, type Options, type ParseClipOptions, Reactor, type ReactorConnectOptions, type ReactorError, type ReactorEvent, ReactorProvider, type ReactorState$1 as ReactorState, type ReactorStatus, type ReactorStore, ReactorView, type ReactorViewProps, RecordingClient, type RecordingClientHost, RecordingError, RuntimeRecordingMessageType, SessionLostError, type SessionResponse, type TrackCapability, type UseClipDownloadOptions, type UseClipDownloadResult, WebcamStream, type WebcamStreamProps, clipFromPayload, createPlayableManifestUrl, downloadClipAsFile, fetchPlaylist, isAbortError, isSessionLostError, normalizeJwtSource, parsePlaylist, rewriteUrlHost, useClipDownload, useReactor, useReactorInternalMessage, useReactorMessage, useReactorStore, useStats };
package/dist/index.d.ts CHANGED
@@ -85,6 +85,52 @@ type TrackCapability = z.infer<typeof TrackCapabilitySchema>;
85
85
  type CommandCapability = z.infer<typeof CommandCapabilitySchema>;
86
86
  type SessionResponse = z.infer<typeof SessionResponseSchema>;
87
87
  type Capabilities = z.infer<typeof CapabilitiesSchema>;
88
+ /** One OpenAPI operation (the `post` of an event/webhook path item). */
89
+ interface ModelSchemaOperation {
90
+ operationId?: string;
91
+ summary?: string;
92
+ description?: string;
93
+ requestBody?: {
94
+ required?: boolean;
95
+ content?: Record<string, {
96
+ schema?: Record<string, unknown>;
97
+ }>;
98
+ };
99
+ responses?: Record<string, unknown>;
100
+ [key: string]: unknown;
101
+ }
102
+ /** An OpenAPI path item; the runtime only populates `post`. */
103
+ interface ModelSchemaPathItem {
104
+ post?: ModelSchemaOperation;
105
+ [key: string]: unknown;
106
+ }
107
+ /**
108
+ * The model's OpenAPI 3.1 schema, returned by the runtime in response to a
109
+ * `requestSchema` runtime-channel command. This is a pass-through of the
110
+ * runtime's document, not a shape the SDK reshapes: client-triggerable
111
+ * events live under `paths` as `POST /events/<name>` operations, outbound
112
+ * model messages under `webhooks`, and media tracks under `x-reactor.tracks`.
113
+ * Read the parts you need.
114
+ */
115
+ interface ModelSchema {
116
+ openapi: string;
117
+ info: {
118
+ title: string;
119
+ version: string;
120
+ description?: string;
121
+ };
122
+ paths?: Record<string, ModelSchemaPathItem>;
123
+ webhooks?: Record<string, ModelSchemaPathItem>;
124
+ "x-reactor"?: {
125
+ tracks?: Array<{
126
+ name: string;
127
+ kind: string;
128
+ direction: string;
129
+ }>;
130
+ };
131
+ components?: Record<string, unknown>;
132
+ [key: string]: unknown;
133
+ }
88
134
 
89
135
  /**
90
136
  * Reference to an uploaded file, returned by {@link Reactor.uploadFile}.
@@ -126,6 +172,10 @@ declare class AbortError extends Error {
126
172
  }
127
173
  /** Matches both our custom AbortError and the native DOMException thrown by fetch(). */
128
174
  declare function isAbortError(error: unknown): boolean;
175
+ declare class SessionLostError extends Error {
176
+ constructor(message: string);
177
+ }
178
+ declare function isSessionLostError(error: unknown): boolean;
129
179
  interface ReactorState$1 {
130
180
  status: ReactorStatus;
131
181
  lastError?: ReactorError;
@@ -205,7 +255,7 @@ interface ConnectionStats {
205
255
  connectionTimings?: ConnectionTimings;
206
256
  timestamp: number;
207
257
  }
208
- type ReactorEvent = "statusChanged" | "sessionIdChanged" | "message" | "runtimeMessage" | "trackReceived" | "error" | "sessionExpirationChanged" | "capabilitiesReceived" | "statsUpdate";
258
+ type ReactorEvent = "statusChanged" | "sessionIdChanged" | "message" | "runtimeMessage" | "trackReceived" | "error" | "sessionExpirationChanged" | "schemaReceived" | "statsUpdate";
209
259
  /**
210
260
  * Severity tier of a content moderation event delivered as the inner
211
261
  * payload of a `runtimeMessage` with `type === "moderation"`.
@@ -316,9 +366,10 @@ type ClipKind = "snap" | "recording";
316
366
  * - `predictedReadyAtMs` is a **Unix epoch in milliseconds** — the
317
367
  * runtime's estimate of when the boundary chunk will be servable
318
368
  * by `/clips`. Compare against `Date.now()` to drive a "ready in
319
- * Ns" indicator. The SDK uses this as the polling deadline: past
320
- * `predictedReadyAtMs + slackMs` and still 202, the SDK fails with
321
- * `CLIP_NOT_READY` on the assumption the runtime crashed.
369
+ * Ns" indicator. It is only an estimate: the SDK polls `/clips`
370
+ * until the manifest is actually ready and does not give up when
371
+ * this epoch passes (see {@link fetchPlaylist} for the polling and
372
+ * cancellation model).
322
373
  * - `playlistUrl` is short-lived in production (the embedded chunk
323
374
  * URLs are presigned for a few minutes). Re-issuing the request
324
375
  * produces a fresh URL with fresh presigning.
@@ -407,21 +458,29 @@ interface ParsedPlaylist {
407
458
  segmentUrls: string[];
408
459
  }
409
460
  /**
410
- * Default grace period after `predictedReadyAtMs` before
411
- * {@link fetchPlaylist} gives up. Applied from
412
- * `max(predictedReadyAtMs, pollStart)` so late clicks still get the
413
- * full window.
461
+ * Suggested grace period for callers that opt into a *bounded* wait by
462
+ * passing it as {@link FetchPlaylistOptions.slackMs}. It is **not** a
463
+ * default: {@link fetchPlaylist} polls indefinitely unless a bound is
464
+ * supplied. Provided so callers who do want the old ~15 s ceiling can
465
+ * ask for it by name rather than hard-coding a magic number.
414
466
  */
415
467
  declare const DEFAULT_PLAYLIST_POLL_SLACK_MS = 15000;
416
468
  interface FetchPlaylistOptions {
417
469
  /**
418
470
  * Unix epoch (ms) when the runtime predicts the boundary chunk will
419
- * be servable. Pass `clip.predictedReadyAtMs` here. When set, polling
420
- * continues until `predictedReadyAtMs + slackMs`; once past, a
421
- * stuck `202` produces `CLIP_NOT_READY` (assume runtime crashed).
471
+ * be servable. Pass `clip.predictedReadyAtMs` here. On its own it
472
+ * does *not* stop polling — it only anchors the optional `slackMs`
473
+ * deadline. Use it to drive a "ready in Ns" indicator.
422
474
  */
423
475
  predictedReadyAtMs?: number;
424
- /** Grace period after `predictedReadyAtMs`. Default {@link DEFAULT_PLAYLIST_POLL_SLACK_MS}. */
476
+ /**
477
+ * Opt-in grace period that turns polling into a *bounded* wait. When
478
+ * set to a finite value, a stuck `202` produces `CLIP_NOT_READY` once
479
+ * `max(predictedReadyAtMs, pollStart) + slackMs` passes. Omit (the
480
+ * default) to poll indefinitely until the manifest is ready or the
481
+ * caller aborts via `signal`. See {@link DEFAULT_PLAYLIST_POLL_SLACK_MS}
482
+ * for a sensible value if you want the old ~15 s ceiling.
483
+ */
425
484
  slackMs?: number;
426
485
  /**
427
486
  * Hard cap on the per-poll wait. The server's `Retry-After` header is
@@ -431,12 +490,18 @@ interface FetchPlaylistOptions {
431
490
  /** Floor on the per-poll wait so we don't hot-loop on cheap networks. Default 200 ms. */
432
491
  minRetryDelayMs?: number;
433
492
  /**
434
- * Fallback retry count used when `predictedReadyAtMs` is omitted
435
- * (e.g. someone calls `fetchPlaylist` directly with a saved URL,
436
- * outside of a fresh `Clip`). Default 5.
493
+ * Opt-in cap on the number of `202` responses tolerated before
494
+ * `CLIP_NOT_READY`. Omit (the default) to poll indefinitely; set it
495
+ * for a simple attempt-count ceiling when you don't have a
496
+ * `predictedReadyAtMs` to anchor a `slackMs` deadline.
437
497
  */
438
498
  maxRetries?: number;
439
- /** Aborts in-flight fetches and the inter-poll sleep. */
499
+ /**
500
+ * Aborts in-flight fetches and the inter-poll sleep. Because polling
501
+ * is unbounded by default, this is the primary way a caller ends a
502
+ * wait that is taking too long (a timeout, a user "cancel", a React
503
+ * unmount).
504
+ */
440
505
  signal?: AbortSignal;
441
506
  /**
442
507
  * Coordinator JWT. When set, attached as `Authorization: Bearer
@@ -449,14 +514,19 @@ interface FetchPlaylistOptions {
449
514
  * Fetch the playlist URL, polling on `202 Accepted` (which the manifest
450
515
  * endpoint returns while the boundary chunk is still uploading).
451
516
  *
452
- * Polling deadline is driven by `predictedReadyAtMs + slackMs` when a
453
- * `Clip` was just minted by the runtime; without that field the
454
- * function falls back to `maxRetries` attempts. Either way:
517
+ * Polling is **unbounded by default** — it keeps retrying on `202`
518
+ * until the manifest is ready or the caller aborts via `signal`. This
519
+ * matches the reality that a clip's boundary chunk can take arbitrarily
520
+ * long to land (a paused model closes no chunks; a long recording's
521
+ * final chunk is large). Callers own the give-up policy: pass `signal`
522
+ * to cancel, or opt into a ceiling with `slackMs` / `maxRetries`.
523
+ *
455
524
  * - `200` → returns the manifest body.
456
525
  * - `410` / `404` → throws `CLIP_GONE`.
457
526
  * - `5xx`/other → throws `PLAYLIST_FETCH_FAILED` (no retry).
458
- * - Past the deadline / retries with stuck `202` → throws
459
- * `CLIP_NOT_READY` (the runtime probably crashed mid-chunk).
527
+ * - `202` past an opt-in `slackMs` deadline or `maxRetries` cap →
528
+ * throws `CLIP_NOT_READY`.
529
+ * - aborted `signal` → rejects with the fetch/`sleep` `AbortError`.
460
530
  */
461
531
  declare function fetchPlaylist(playlistUrl: string, options?: FetchPlaylistOptions): Promise<string>;
462
532
  /**
@@ -672,9 +742,10 @@ declare class Reactor {
672
742
  * down its own transport but leaves the session alive.
673
743
  */
674
744
  private createdSession;
745
+ private retryingSessionLoss;
675
746
  private connectStartTime?;
676
747
  private connectionTimings?;
677
- private capabilities?;
748
+ private schema?;
678
749
  private tracks;
679
750
  private presetTracks?;
680
751
  private autoResumeTracks;
@@ -782,9 +853,16 @@ declare class Reactor {
782
853
  getStatus(): ReactorStatus;
783
854
  getState(): ReactorState$1;
784
855
  getLastError(): ReactorError | undefined;
785
- getCapabilities(): Capabilities | undefined;
856
+ /**
857
+ * The model's OpenAPI schema (events, outbound messages, tracks),
858
+ * received over the runtime channel shortly after the session becomes
859
+ * ready. `undefined` until the `schemaReceived` event has fired.
860
+ */
861
+ getSchema(): ModelSchema | undefined;
786
862
  getSessionInfo(): SessionResponse | undefined;
787
863
  getStats(): ConnectionStats | undefined;
864
+ /** Timing breakdown from the most recent connect() handshake. */
865
+ getConnectionTimings(): ConnectionTimings | undefined;
788
866
  private setSessionId;
789
867
  private setStatus;
790
868
  private setSessionExpiration;
@@ -826,6 +904,19 @@ interface ReactorActions {
826
904
  disconnect(recoverable?: boolean): Promise<void>;
827
905
  publish(name: string, track: MediaStreamTrack): Promise<void>;
828
906
  unpublish(name: string): Promise<void>;
907
+ /**
908
+ * Ask the runtime to stop processing a recvonly track. Top-level
909
+ * alias for `internal.reactor.pauseTrack(…)` — lifted onto the store
910
+ * so consumers don't have to reach through `internal.reactor`. See
911
+ * {@link Reactor.pauseTrack}.
912
+ */
913
+ pauseTrack(name: string): void;
914
+ /**
915
+ * Ask the runtime to resume a previously paused recvonly track.
916
+ * Top-level alias for `internal.reactor.resumeTrack(…)`. See
917
+ * {@link Reactor.resumeTrack}.
918
+ */
919
+ resumeTrack(name: string): void;
829
920
  reconnect(options?: ConnectOptions): Promise<void>;
830
921
  uploadFile(file: File | Blob, options?: {
831
922
  name?: string;
@@ -921,12 +1012,6 @@ interface ReactorViewProps {
921
1012
  }
922
1013
  declare function ReactorView({ track, audioTrack, width, height, className, style, videoObjectFit, muted, }: ReactorViewProps): react_jsx_runtime.JSX.Element;
923
1014
 
924
- interface ReactorControllerProps {
925
- className?: string;
926
- style?: React.CSSProperties;
927
- }
928
- declare function ReactorController({ className, style, }: ReactorControllerProps): react_jsx_runtime.JSX.Element;
929
-
930
1015
  interface WebcamStreamProps {
931
1016
  /**
932
1017
  * The name of the sendonly **video** track to publish the webcam to.
@@ -1034,16 +1119,15 @@ interface ClipPlayerProps {
1034
1119
  */
1035
1120
  getJwt?: () => string | Promise<string>;
1036
1121
  /**
1037
- * Override the grace period beyond ``clip.predictedReadyAtMs``
1038
- * before the SDK gives up polling the ``/clips`` manifest endpoint
1039
- * with ``CLIP_NOT_READY``. Defaults to
1040
- * {@link DEFAULT_PLAYLIST_POLL_SLACK_MS} (15 s) — enough for snap
1041
- * clips, but long-running session recordings may legitimately need
1042
- * a minute or more for the final boundary chunk to finish encoding
1043
- * + uploading, in which case pass a larger value (e.g. ``120_000``
1044
- * for two-minute grace). Forwarded directly to
1045
- * {@link fetchPlaylist}'s ``slackMs`` option — see that helper for
1046
- * the polling semantics.
1122
+ * Opt into a *bounded* wait: give up polling the ``/clips`` manifest
1123
+ * endpoint with ``CLIP_NOT_READY`` once
1124
+ * ``max(clip.predictedReadyAtMs, pollStart) + slackMs`` passes. By
1125
+ * default this is **unset** — the player polls indefinitely until the
1126
+ * clip is ready, and stops only when it unmounts or ``clip`` changes
1127
+ * (both abort the in-flight poll). Set a value when you want a hard
1128
+ * ceiling (e.g. ``120_000`` for a two-minute cap). Forwarded
1129
+ * directly to {@link fetchPlaylist}'s ``slackMs`` option — see that
1130
+ * helper for the polling semantics.
1047
1131
  */
1048
1132
  slackMs?: number;
1049
1133
  /** Play automatically once the manifest is attached. Default ``true``. */
@@ -1266,4 +1350,4 @@ declare function useReactorInternalMessage(handler: (message: any) => void): voi
1266
1350
  */
1267
1351
  declare function useStats(): ConnectionStats | undefined;
1268
1352
 
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 };
1353
+ 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 ModelSchema, type ModelSchemaOperation, type ModelSchemaPathItem, type ModerationAction, type ModerationEvent, type Options, type ParseClipOptions, Reactor, type ReactorConnectOptions, type ReactorError, type ReactorEvent, ReactorProvider, type ReactorState$1 as ReactorState, type ReactorStatus, type ReactorStore, ReactorView, type ReactorViewProps, RecordingClient, type RecordingClientHost, RecordingError, RuntimeRecordingMessageType, SessionLostError, type SessionResponse, type TrackCapability, type UseClipDownloadOptions, type UseClipDownloadResult, WebcamStream, type WebcamStreamProps, clipFromPayload, createPlayableManifestUrl, downloadClipAsFile, fetchPlaylist, isAbortError, isSessionLostError, normalizeJwtSource, parsePlaylist, rewriteUrlHost, useClipDownload, useReactor, useReactorInternalMessage, useReactorMessage, useReactorStore, useStats };