@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 +15 -3
- package/dist/index.d.mts +124 -40
- package/dist/index.d.ts +124 -40
- package/dist/index.js +157 -659
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +141 -644
- package/dist/index.mjs.map +1 -1
- package/package.json +4 -4
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
|
|
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: {
|
|
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
|
|
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" | "
|
|
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.
|
|
320
|
-
*
|
|
321
|
-
*
|
|
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
|
-
*
|
|
411
|
-
* {@link
|
|
412
|
-
*
|
|
413
|
-
*
|
|
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.
|
|
420
|
-
*
|
|
421
|
-
*
|
|
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
|
-
/**
|
|
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
|
-
*
|
|
435
|
-
*
|
|
436
|
-
*
|
|
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
|
-
/**
|
|
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
|
|
453
|
-
*
|
|
454
|
-
*
|
|
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
|
-
* -
|
|
459
|
-
* `CLIP_NOT_READY
|
|
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
|
|
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
|
-
|
|
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
|
-
*
|
|
1038
|
-
*
|
|
1039
|
-
*
|
|
1040
|
-
*
|
|
1041
|
-
*
|
|
1042
|
-
*
|
|
1043
|
-
*
|
|
1044
|
-
*
|
|
1045
|
-
*
|
|
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,
|
|
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" | "
|
|
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.
|
|
320
|
-
*
|
|
321
|
-
*
|
|
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
|
-
*
|
|
411
|
-
* {@link
|
|
412
|
-
*
|
|
413
|
-
*
|
|
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.
|
|
420
|
-
*
|
|
421
|
-
*
|
|
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
|
-
/**
|
|
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
|
-
*
|
|
435
|
-
*
|
|
436
|
-
*
|
|
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
|
-
/**
|
|
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
|
|
453
|
-
*
|
|
454
|
-
*
|
|
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
|
-
* -
|
|
459
|
-
* `CLIP_NOT_READY
|
|
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
|
|
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
|
-
|
|
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
|
-
*
|
|
1038
|
-
*
|
|
1039
|
-
*
|
|
1040
|
-
*
|
|
1041
|
-
*
|
|
1042
|
-
*
|
|
1043
|
-
*
|
|
1044
|
-
*
|
|
1045
|
-
*
|
|
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,
|
|
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 };
|