@uploadfilm/sdk 0.0.0-stage → 0.1.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.
Files changed (218) hide show
  1. package/LICENSE +4 -0
  2. package/README.md +509 -2
  3. package/dist/ai/embed.d.ts +58 -0
  4. package/dist/ai/fake.d.ts +41 -0
  5. package/dist/ai/http.d.ts +17 -0
  6. package/dist/ai/index.d.ts +27 -0
  7. package/dist/ai/languages.d.ts +2 -0
  8. package/dist/ai/ollama.d.ts +23 -0
  9. package/dist/ai/openaiCompatible.d.ts +54 -0
  10. package/dist/ai/passages.d.ts +28 -0
  11. package/dist/ai/transcribe.d.ts +84 -0
  12. package/dist/ai/types.d.ts +141 -0
  13. package/dist/ai/usage.d.ts +66 -0
  14. package/dist/ai/whisperJson.d.ts +15 -0
  15. package/dist/ai/workersAi.d.ts +56 -0
  16. package/dist/ai.js +1 -0
  17. package/dist/ai.mjs +1 -0
  18. package/dist/cards/files.d.ts +91 -0
  19. package/dist/cards/index.d.ts +15 -0
  20. package/dist/cards/layouts.d.ts +121 -0
  21. package/dist/cards/probe.d.ts +69 -0
  22. package/dist/cards/proxies.d.ts +70 -0
  23. package/dist/cards/select.d.ts +68 -0
  24. package/dist/cards/volumes.d.ts +170 -0
  25. package/dist/cards/xml.d.ts +80 -0
  26. package/dist/cards.js +1 -0
  27. package/dist/cards.mjs +1 -0
  28. package/dist/copy/checksums.d.ts +66 -0
  29. package/dist/copy/engine.d.ts +24 -0
  30. package/dist/copy/errors.d.ts +109 -0
  31. package/dist/copy/index.d.ts +15 -0
  32. package/dist/copy/steps.d.ts +28 -0
  33. package/dist/copy/sweep.d.ts +24 -0
  34. package/dist/copy/types.d.ts +336 -0
  35. package/dist/embed/player.js +2 -0
  36. package/dist/host/adapters.d.ts +107 -0
  37. package/dist/host/detect.d.ts +68 -0
  38. package/dist/host/encoders.d.ts +34 -0
  39. package/dist/host/environment.d.ts +53 -0
  40. package/dist/host/index.d.ts +20 -0
  41. package/dist/host/linux.d.ts +94 -0
  42. package/dist/host/mac.d.ts +47 -0
  43. package/dist/host/network.d.ts +54 -0
  44. package/dist/host/node.d.ts +13 -0
  45. package/dist/host/policy.d.ts +101 -0
  46. package/dist/host/tuner.d.ts +48 -0
  47. package/dist/host/types.d.ts +118 -0
  48. package/dist/host-node.js +1 -0
  49. package/dist/host-node.mjs +1 -0
  50. package/dist/host.js +1 -0
  51. package/dist/host.mjs +1 -0
  52. package/dist/images/index.d.ts +11 -0
  53. package/dist/images/settings.d.ts +43 -0
  54. package/dist/images/types.d.ts +83 -0
  55. package/dist/images/url.d.ts +65 -0
  56. package/dist/index.d.ts +16 -0
  57. package/dist/index.js +1 -0
  58. package/dist/index.mjs +1 -0
  59. package/dist/player/adapters/hlsjs.d.ts +28 -0
  60. package/dist/player/bandwidthMemory.d.ts +28 -0
  61. package/dist/player/captions/index.d.ts +55 -0
  62. package/dist/player/embed/code.d.ts +195 -0
  63. package/dist/player/embed/constants.d.ts +4 -0
  64. package/dist/player/embed/controller.d.ts +62 -0
  65. package/dist/player/embed/element.d.ts +32 -0
  66. package/dist/player/embed/frame.d.ts +65 -0
  67. package/dist/player/embed/global.d.ts +14 -0
  68. package/dist/player/embed/index.d.ts +15 -0
  69. package/dist/player/embed/loader.d.ts +1 -0
  70. package/dist/player/embed/oembed.d.ts +74 -0
  71. package/dist/player/embed/protocol.d.ts +64 -0
  72. package/dist/player/engine.d.ts +215 -0
  73. package/dist/player/index.d.ts +18 -0
  74. package/dist/player/start.d.ts +62 -0
  75. package/dist/player/store.d.ts +10 -0
  76. package/dist/player/storyboard/index.d.ts +161 -0
  77. package/dist/player/stream.d.ts +206 -0
  78. package/dist/player/tracks.d.ts +41 -0
  79. package/dist/player.js +1 -0
  80. package/dist/player.mjs +1 -0
  81. package/dist/proxies/args.d.ts +19 -0
  82. package/dist/proxies/budget.d.ts +57 -0
  83. package/dist/proxies/camera.d.ts +104 -0
  84. package/dist/proxies/formats.d.ts +36 -0
  85. package/dist/proxies/index.d.ts +18 -0
  86. package/dist/proxies/jobs.d.ts +98 -0
  87. package/dist/proxies/node.d.ts +32 -0
  88. package/dist/proxies/plan.d.ts +89 -0
  89. package/dist/proxies/probe.d.ts +39 -0
  90. package/dist/proxies/render.d.ts +104 -0
  91. package/dist/proxies/safety.d.ts +45 -0
  92. package/dist/proxies/types.d.ts +83 -0
  93. package/dist/proxies/upload.d.ts +14 -0
  94. package/dist/react/BigPlay.d.ts +26 -0
  95. package/dist/react/Player.d.ts +58 -0
  96. package/dist/react/embed/index.d.ts +45 -0
  97. package/dist/react/examples/CustomControls.d.ts +8 -0
  98. package/dist/react/images/Image.d.ts +16 -0
  99. package/dist/react/images/index.d.ts +4 -0
  100. package/dist/react/images/useImage.d.ts +47 -0
  101. package/dist/react/index.d.ts +17 -0
  102. package/dist/react/storyboard/index.d.ts +58 -0
  103. package/dist/react/theme.d.ts +37 -0
  104. package/dist/react/useAdapterErrors.d.ts +8 -0
  105. package/dist/react/usePlaybackStart.d.ts +18 -0
  106. package/dist/react/usePlayer.d.ts +28 -0
  107. package/dist/react/useReducedMotion.d.ts +2 -0
  108. package/dist/react/useTimedTrack.d.ts +22 -0
  109. package/dist/react.js +1 -0
  110. package/dist/react.mjs +1 -0
  111. package/dist/server/auth/apiKeys.d.ts +30 -0
  112. package/dist/server/auth/cache.d.ts +21 -0
  113. package/dist/server/auth/deviceTokens.d.ts +38 -0
  114. package/dist/server/auth/envelope.d.ts +15 -0
  115. package/dist/server/auth/grants.d.ts +76 -0
  116. package/dist/server/auth/index.d.ts +19 -0
  117. package/dist/server/auth/jwt.d.ts +65 -0
  118. package/dist/server/auth/keyring.d.ts +31 -0
  119. package/dist/server/auth/kv.d.ts +12 -0
  120. package/dist/server/auth/repository.d.ts +45 -0
  121. package/dist/server/auth/revocations.d.ts +21 -0
  122. package/dist/server/auth/scope.d.ts +4 -0
  123. package/dist/server/auth/serviceAuth.d.ts +24 -0
  124. package/dist/server/auth/signedUrls.d.ts +28 -0
  125. package/dist/server/embed/index.d.ts +36 -0
  126. package/dist/server/embed/lifecycle.d.ts +53 -0
  127. package/dist/server/embed/playerScript.d.ts +4 -0
  128. package/dist/server/images/index.d.ts +15 -0
  129. package/dist/server/images/job.d.ts +80 -0
  130. package/dist/server/images/layout.d.ts +24 -0
  131. package/dist/server/images/params.d.ts +90 -0
  132. package/dist/server/images/route.d.ts +101 -0
  133. package/dist/server/images/sign.d.ts +55 -0
  134. package/dist/server/index.d.ts +42 -0
  135. package/dist/server/media/client.d.ts +66 -0
  136. package/dist/server/media/frameCheck.d.ts +62 -0
  137. package/dist/server/media/index.d.ts +10 -0
  138. package/dist/server/media/protocol.d.ts +318 -0
  139. package/dist/server/media/storyboard.d.ts +144 -0
  140. package/dist/server/media/transcript.d.ts +143 -0
  141. package/dist/server/pipeline/index.d.ts +12 -0
  142. package/dist/server/pipeline/match.d.ts +10 -0
  143. package/dist/server/pipeline/pipeline.d.ts +182 -0
  144. package/dist/server/pipeline/queues.d.ts +108 -0
  145. package/dist/server/pipeline/sources.d.ts +54 -0
  146. package/dist/server/r2/client.d.ts +150 -0
  147. package/dist/server/r2/crc32.d.ts +24 -0
  148. package/dist/server/r2/encoding.d.ts +35 -0
  149. package/dist/server/r2/errors.d.ts +9 -0
  150. package/dist/server/r2/integrity.d.ts +25 -0
  151. package/dist/server/r2/parts.d.ts +46 -0
  152. package/dist/server/r2/sign.d.ts +47 -0
  153. package/dist/server/redis/index.d.ts +39 -0
  154. package/dist/server/state/memory.d.ts +18 -0
  155. package/dist/server/state/r2.d.ts +73 -0
  156. package/dist/server/state/types.d.ts +57 -0
  157. package/dist/server/storage/chunked.d.ts +21 -0
  158. package/dist/server/storage/index.d.ts +12 -0
  159. package/dist/server/storage/r2.d.ts +96 -0
  160. package/dist/server/storage/s3.d.ts +93 -0
  161. package/dist/server/testing/fake-r2.d.ts +390 -0
  162. package/dist/server/testing/index.d.ts +10 -0
  163. package/dist/server/testing/kv-contract.d.ts +14 -0
  164. package/dist/server/transfer/handler.d.ts +167 -0
  165. package/dist/server/transfer/keys.d.ts +45 -0
  166. package/dist/server/transfer/protocol.d.ts +141 -0
  167. package/dist/server/zip/client.d.ts +32 -0
  168. package/dist/server/zip/generations.d.ts +83 -0
  169. package/dist/server/zip/index.d.ts +12 -0
  170. package/dist/server/zip/planner.d.ts +94 -0
  171. package/dist/server/zip/sign.d.ts +22 -0
  172. package/dist/server-media.js +1 -0
  173. package/dist/server-media.mjs +1 -0
  174. package/dist/server-redis.js +1 -0
  175. package/dist/server-redis.mjs +1 -0
  176. package/dist/server-testing.js +1 -0
  177. package/dist/server-testing.mjs +1 -0
  178. package/dist/server.js +1 -0
  179. package/dist/server.mjs +1 -0
  180. package/dist/storage/browserFile.d.ts +19 -0
  181. package/dist/storage/index.d.ts +12 -0
  182. package/dist/storage/local.d.ts +9 -0
  183. package/dist/storage/presigned.d.ts +22 -0
  184. package/dist/sync/ffmpeg.d.ts +44 -0
  185. package/dist/sync/index.d.ts +17 -0
  186. package/dist/sync/match.d.ts +28 -0
  187. package/dist/sync/probe.d.ts +30 -0
  188. package/dist/sync/timecode.d.ts +50 -0
  189. package/dist/sync/transcript.d.ts +35 -0
  190. package/dist/sync/types.d.ts +172 -0
  191. package/dist/sync/waveform.d.ts +89 -0
  192. package/dist/sync.js +1 -0
  193. package/dist/sync.mjs +1 -0
  194. package/dist/transfer/claims.d.ts +41 -0
  195. package/dist/transfer/client.d.ts +256 -0
  196. package/dist/transfer/download.d.ts +192 -0
  197. package/dist/transfer/engine.d.ts +382 -0
  198. package/dist/transfer/errors.d.ts +50 -0
  199. package/dist/transfer/index.d.ts +39 -0
  200. package/dist/transfer/integrity.d.ts +93 -0
  201. package/dist/transfer/limits.d.ts +34 -0
  202. package/dist/transfer/node.d.ts +63 -0
  203. package/dist/transfer/pool.d.ts +83 -0
  204. package/dist/transfer/protocol.d.ts +167 -0
  205. package/dist/transfer/signer.d.ts +29 -0
  206. package/dist/transfer/storage.d.ts +110 -0
  207. package/dist/transfer/timing.d.ts +132 -0
  208. package/dist/transfer/transports/electronNet.d.ts +62 -0
  209. package/dist/transfer/transports/fetch.d.ts +15 -0
  210. package/dist/transfer/transports/retryAfter.d.ts +12 -0
  211. package/dist/transfer/transports/undici.d.ts +72 -0
  212. package/dist/transfer/tuner.d.ts +56 -0
  213. package/dist/zip/index.d.ts +13 -0
  214. package/dist/zip/layout.d.ts +129 -0
  215. package/dist/zip/names.d.ts +34 -0
  216. package/dist/zip/plan.d.ts +115 -0
  217. package/dist/zip/sw.d.ts +7 -0
  218. package/package.json +265 -4
package/LICENSE ADDED
@@ -0,0 +1,4 @@
1
+ Copyright (c) 2026 UploadFilm. All rights reserved.
2
+
3
+ This software is proprietary and confidential. It is not open source. No licence to use, copy, modify, merge,
4
+ publish, distribute, sublicense or sell copies of it is granted except by a separate written agreement with UploadFilm.
package/README.md CHANGED
@@ -1,3 +1,510 @@
1
- # Temporary Holding Version
1
+ # 🎞️ @uploadfilm/sdk
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ **One engine for moving camera footage into your own storage, processing it on your own Cloudflare account, and
4
+ playing it back in your own app.** Resumable, verified uploads to your R2 bucket; a headless video player with embeds;
5
+ React hooks over it; and the server side: presigning, an auth kit, media jobs, verified copies to S3.
6
+
7
+ It's a **library, not a service**: no central API, no hosted keys, no shared logging, no billing. You run your own
8
+ bucket, routes, auth and media Worker, and import only the entry points you need. UploadFilm runs on it in production.
9
+
10
+ ```bash
11
+ npm install @uploadfilm/sdk
12
+ ```
13
+
14
+ - [✨ Features](#-features)
15
+ - [🧭 Entry points](#-entry-points)
16
+ - [🚀 Quick start: uploads](#-quick-start-uploads-node-or-electron)
17
+ - [🔐 Quick start: the server route](#-quick-start-the-server-route)
18
+ - [🎬 The player](#-the-player)
19
+ - [⚙️ The media pipeline on Cloudflare Workers](#️-the-media-pipeline-on-cloudflare-workers)
20
+ - [🧪 Testing your integration](#-testing-your-integration)
21
+ - [🛡️ Guarantees](#️-guarantees)
22
+ - [🚧 Not built yet](#-not-built-yet)
23
+
24
+ ## ✨ Features
25
+
26
+ | | |
27
+ |---|---|
28
+ | ✅ **Bytes verified** | An upload resolves `verified` only after storage confirmed a checksum of the bytes read from your file: Content-MD5 for a single PUT, every part's MD5 ETag plus the composite ETag for a multipart, or SHA-256 receipts in `integrity: "sha256"` mode. |
29
+ | 🚫 **Never a false "done"** | Storage that stored something without a checksum to compare gives `failed` / `Unverified`, never success. The media Worker writes its completion file last and refuses a ladder shorter than the source. |
30
+ | 🔁 **Resumable** | The multipart record is saved after every part. After a crash, `upload()` with the same id proves the saved parts against `ListParts` and a re-read of the file before sending anything new. |
31
+ | 🎥 **Originals first** | Upload lanes keep ⌈2/3⌉ of the connections for originals while they have work; proxies borrow the rest and hand it back. |
32
+ | 🔑 **No storage credentials on clients** | Clients get per-part presigned URLs from your server, signed with [aws4fetch](https://github.com/mhart/aws4fetch). No AWS S3 SDK anywhere. |
33
+ | ⬇️ **Verified downloads** | Parallel ranged downloads pinned to one version (`If-Match`), checked against the uploader's ETag or SHA-256, resumable, never overwriting. |
34
+ | ▶️ **A player that keeps playing** | HLS or MP4, recovery with fresh URLs, fallback from the same spot, offline wait, stall and frozen-playhead detection (WebKit), bandwidth memory. Headless: a store your UI renders from. |
35
+ | 🪟 **Embeds** | `<uploadfilm-player>`, an iframe postMessage control API, snippets, oEmbed, and a tiny `<script>` build your server serves from its own domain. |
36
+ | 🔐 **Auth kit** | JWTs with `kid` rotation, device tokens, API keys (hashed, prefix + last4), signed URLs, AES-GCM sealed grants and envelopes, revocation lists. All WebCrypto, every compare constant-time, every verifier fails closed. |
37
+ | ⚙️ **Media pipeline** | Signed jobs to your own media Worker: HLS ladder 360/720/1080, poster, storyboard hover previews, fast-start MP4, audio and transcript, from **one decode** per job. |
38
+ | 🧩 **Yours to own** | No hardcoded hosts, buckets or tables. State goes through adapters you pass in (memory, Redis, R2, your database); records reach you as events and hooks. |
39
+
40
+ ## 🧭 Entry points
41
+
42
+ Every entry point is a subpath of this one package, ESM + CJS with types, `sideEffects: false`.
43
+
44
+ | Import | What you get | Runs in |
45
+ |---|---|---|
46
+ | `@uploadfilm/sdk` | The client transfer engine: `createTransferEngine` (resumable verified uploads, lanes, claims, dedupe), `downloadObject`, transports (`createUndiciTransport`, `createFetchTransport`, `createElectronNetTransport`), `createHttpSigner`, `createEngineCore`, part math and integrity helpers, streaming-ZIP layout, image URL helpers, `copy()` with client-side modules | Node 20.16+ or 22.3+, Electron main |
47
+ | `@uploadfilm/sdk/player` | Headless player (`createPlayer`), its store, timed tracks (markers, chapters, captions), WebVTT captions, storyboard hover previews, embeds (options, snippets, oEmbed, `<uploadfilm-player>`, the postMessage control API) | Browsers |
48
+ | `@uploadfilm/sdk/react` | Hooks first: `usePlayer`, `usePlayerState`, `useTimedTrack`, `useCaptions`, `useTimelinePreview`, `useEmbedController`, `useImage`. Optional components: `<Player>` (a Video.js 10 skin over the engine), `<TimelinePreview>`, `<EmbedFrame>`, `<Image>` | React ≥ 18 |
49
+ | `@uploadfilm/sdk/server` | R2 presign, multipart and integrity (`createR2Client`), the key-layout guard (`createKeyGuard`), the sign route handler (`createSignHandler` with authorize / quota / dedupe hooks), the auth kit, state stores (`createMemoryStore`, `createR2Store`), `servePlayerScript()`, `copy()` with `r2()` / `s3()`, the upload-completed pipeline (`createPipeline` + Inngest / Cloudflare Queues / in-memory), the ZIP planner, the media job client | Node 20.16+ or 22.3+, Cloudflare Workers |
50
+ | `@uploadfilm/sdk/server/media` | Only the media Worker's protocol and job client (`mediaJobClient`, `refuseStale`, `ladderSettings`, `stepSettings`, `sourceHash`) | Node, Workers |
51
+ | `@uploadfilm/sdk/server/redis` | `createRedisStore(client)`: a `KeyValueStore` with atomic `incr` / `compareAndSet` over **your** `ioredis` or `@upstash/redis` client | Node, Workers |
52
+ | `@uploadfilm/sdk/server/testing` | `createFakeR2()`: a fake R2 that checks SigV4, serves presigned URLs and injects faults; `keyValueStoreContract` for your own state adapter | Node (tests) |
53
+ | `@uploadfilm/sdk/ai` | Pluggable speech-to-text and embeddings: Workers AI, any OpenAI-compatible server, Ollama, fakes | Node, Workers |
54
+ | `@uploadfilm/sdk/host` · `/host/node` | Host profile (CPU, memory, disk, power, thermal, network, hardware encoders) and how hard to drive it; `bindEngine` tunes uploads live | `/host` anywhere, `/host/node` Node |
55
+ | `@uploadfilm/sdk/cards` | Camera cards: mounted volumes, camera folder layouts read into clips (spanned clips, proxies, sidecars, LUTs), the upload plan | Node |
56
+ | `@uploadfilm/sdk/sync` | Dual-system audio sync: which recorder file belongs to which clip, and at what offset | Node (runs FFmpeg) |
57
+
58
+ **Optional peer dependencies**, only for what you use: `react`, `@videojs/react`, `hls.js`, `undici`, `ioredis`,
59
+ `@upstash/redis`, `inngest`, `@cloudflare/workers-types`. The SDK never imports them itself where it can avoid it: you
60
+ pass `undici`, `hls.js` or Electron's `net` in.
61
+
62
+ ## 🚀 Quick start: uploads (Node or Electron)
63
+
64
+ ```ts
65
+ import * as undici from "undici";
66
+ import { createHttpSigner, createTiming, createTransferEngine, createUndiciTransport, fileStore } from "@uploadfilm/sdk";
67
+
68
+ const timing = createTiming();
69
+ const engine = createTransferEngine({
70
+ // Batches the engine's ops into POST {ops} → {results} against your sign route (next section).
71
+ signer: createHttpSigner({
72
+ url: (scope) => `https://app.example.com/api/projects/${scope}/sign`,
73
+ headers: async () => ({ authorization: `Bearer ${await getSessionToken()}` }),
74
+ }),
75
+ transport: createUndiciTransport(undici, timing, {
76
+ allowedOrigins: ["https://ACCOUNT_ID.r2.cloudflarestorage.com"], // nothing else is ever PUT to
77
+ }),
78
+ timing,
79
+ store: fileStore("./.upload-state"), // survives a crash: upload() again with the same id resumes
80
+ lanes: [
81
+ { name: "original", minShare: 2 / 3 }, // originals keep ⌈2/3⌉ of the connections
82
+ { name: "proxy", yieldable: true }, // proxies borrow the rest
83
+ ],
84
+ });
85
+ engine.start();
86
+
87
+ const upload = engine.upload({
88
+ scope: "project-42",
89
+ key: "p/project-42/orig/A001_C003.mov",
90
+ path: "/Volumes/CARD/A001_C003.mov",
91
+ lane: "original",
92
+ immutable: true, // written once: a different object at this key is a conflict, never overwritten
93
+ });
94
+ upload.on("progress", (sent, size) => console.log(`${((100 * sent) / size).toFixed(1)}%`));
95
+ upload.on("state", (s) => console.log("state:", s)); // queued | waiting | sending | verified | failed
96
+
97
+ const result = await upload.done;
98
+ if (result.state === "verified") console.log("stored and verified", result.etag);
99
+ else console.error(result.code, result.error, result.retryable ? "(try again later)" : "");
100
+ engine.stop();
101
+ ```
102
+
103
+ **Electron main process:** the same engine over Chromium's network stack. The SDK never imports Electron; you pass
104
+ `net` in: `transport: createElectronNetTransport(net, timing)`.
105
+
106
+ Useful extras: `engine.pause()` / `engine.resume()`, `engine.stats()`, `connections: { min, max }`, `inflightBytes`,
107
+ `shareUploads: true`, `claims` (two processes never send the same key twice), `dedupe: true`, `integrity: "sha256"`,
108
+ and `source: ByteSource` (`bufferSource`, `fileSource`) for something that isn't a path.
109
+
110
+ **A verified download** (ranged, parallel, pinned to one version):
111
+
112
+ ```ts
113
+ import { createTiming, downloadObject } from "@uploadfilm/sdk";
114
+
115
+ const result = await downloadObject({
116
+ url: () => signedGetUrl("p/project-42/orig/A001_C003.mov"), // re-signed after a 403
117
+ dest: "/Users/me/Downloads/A001_C003.mov", // bytes go to .part first; never overwrites
118
+ size: 734_003_200,
119
+ etag: "9b2cf535f27731c974343645a3985328-44", // the uploader's verified ETag
120
+ timing: createTiming(),
121
+ onProgress: (done, size) => console.log(done, size),
122
+ });
123
+ console.log(result.state); // "verified" | "unverified" (with a reason)
124
+ ```
125
+
126
+ Pass `state: { load, save, remove }` to resume a download after a restart.
127
+
128
+ > 🌐 The transfer engine reads files with `node:fs`, so it runs in Node and Electron, not in a browser (yet). The
129
+ > player, embeds and image helpers do run in browsers.
130
+
131
+ ## 🔐 Quick start: the server route
132
+
133
+ The server side of uploads is one route. Here as a Next.js route handler (on a Worker it's the same
134
+ `(req) => Response`), with the auth kit verifying a short-lived token your app issued:
135
+
136
+ ```ts
137
+ // app/api/projects/[id]/sign/route.ts
138
+ import { createKeyGuard, createR2Client, createSignHandler, keyring, verifyToken } from "@uploadfilm/sdk/server";
139
+
140
+ const r2 = createR2Client({
141
+ endpoint: process.env.R2_ENDPOINT!, // https://<account>.r2.cloudflarestorage.com
142
+ bucket: process.env.R2_BUCKET!, // "bucket" or "bucket/prefix"
143
+ accessKeyId: process.env.R2_ACCESS_KEY_ID!,
144
+ secretAccessKey: process.env.R2_SECRET_ACCESS_KEY!,
145
+ fetch: (url, init) => fetch(url, { ...init, cache: "no-store" }), // Next.js: never cache storage calls
146
+ });
147
+ const keys = keyring({ current: { kid: "2026-11", secret: process.env.TOKEN_SECRET! } });
148
+
149
+ type Kind = "original" | "proxy";
150
+ // The only keys this route signs: p/<projectId>/orig/<name> and p/<projectId>/proxy/<name>.
151
+ const classify = createKeyGuard<Kind>([
152
+ (s) => (s[0] === "orig" && s.length === 2 ? "original" : null),
153
+ (s) => (s[0] === "proxy" && s.length === 2 ? "proxy" : null),
154
+ ]);
155
+
156
+ const handler = createSignHandler<Kind, { userId: string; projectId: string }>({
157
+ r2,
158
+ classify: (key, ctx) => classify(`p/${ctx.projectId}/`, key),
159
+ immutable: (kind) => kind === "original",
160
+ hooks: {
161
+ // Quota that can't be raced: charge before a write is signed, bind it to the multipart, check it at complete.
162
+ reserve: async (ctx, w) => ((await reserveBytes(ctx.userId, w.key, w.size, w.uploadId)) ? "ok" : "quota"),
163
+ bindUpload: (_ctx, key, uploadId) => bindReservation(key, uploadId),
164
+ reservation: (ctx, key, uploadId) => reservedBytes(ctx.userId, key, uploadId),
165
+ },
166
+ });
167
+
168
+ export async function POST(req: Request, { params }: { params: Promise<{ id: string }> }) {
169
+ const { id } = await params;
170
+ const auth = await verifyToken(keys, req.headers.get("authorization")?.replace(/^Bearer /, ""), {
171
+ aud: "uploads",
172
+ scope: `project:${id}:write`,
173
+ });
174
+ if (!auth.ok) return Response.json({ error: "unauthorized" }, { status: 401 });
175
+ const answer = await handler.handle(await req.json(), { userId: auth.claims.sub, projectId: id });
176
+ return Response.json(answer.body, { status: answer.status });
177
+ }
178
+ ```
179
+
180
+ Issuing that token, with key rotation:
181
+
182
+ ```ts
183
+ import { issueToken, keyring } from "@uploadfilm/sdk/server";
184
+
185
+ const keys = keyring({
186
+ current: { kid: "2026-11", secret: process.env.TOKEN_SECRET! },
187
+ previous: [{ kid: "2026-10", secret: process.env.TOKEN_SECRET_PREVIOUS! }], // old tokens still verify
188
+ });
189
+ export const uploadToken = (userId: string, projectId: string) =>
190
+ issueToken(keys, { sub: userId, aud: "uploads", scope: [`project:${projectId}:write`], ttl: "15m" });
191
+ ```
192
+
193
+ The hooks are where your policy lives: `guard`, `grant`, `reserve` / `bindUpload` / `confirm` / `release` /
194
+ `reservation`, `dedupe`, `onError`, and custom `ops`. More of the auth kit:
195
+
196
+ ```ts
197
+ import { createMemoryStore, generateApiKey, grantSealer, keyring, revocationList, signUrl, verifySignedUrl } from "@uploadfilm/sdk/server";
198
+ import { createRedisStore } from "@uploadfilm/sdk/server/redis";
199
+
200
+ const keys = keyring({ current: { kid: "k1", secret: process.env.TOKEN_SECRET! } });
201
+
202
+ const { raw, hash, prefix, last4 } = await generateApiKey({ prefix: "cm_live_" }); // show raw once, store hash
203
+ const url = await signUrl(keys, "https://app.example.com/files/123", { ttl: "10m" });
204
+ const check = await verifySignedUrl(keys, url); // { ok: true, exp, kid } | { ok: false, reason }
205
+
206
+ const kv = redisClient ? createRedisStore(redisClient) : createMemoryStore(); // ioredis or @upstash/redis
207
+ await revocationList(kv).revoke("token-jti", Math.floor(Date.now() / 1000) + 3600);
208
+
209
+ // Sealed grants (AES-GCM): read access to one folder until `exp`; what viewers of the media Worker carry.
210
+ const grants = grantSealer({ salt: "myproduct-stream", isValid: (g) => /^media\/[0-9a-f]{32}\/$/.test(g.prefix) });
211
+ ```
212
+
213
+ > With `@upstash/redis`, create the client with `automaticDeserialization: false` (values come back as stored).
214
+
215
+ ## 🎬 The player
216
+
217
+ The player is **headless**: an engine that owns the hard part (staying playing) and a store your UI renders from. The
218
+ React components are thin renders of public hooks, so you can replace any of them.
219
+
220
+ **React, default skin** (Video.js 10's skin over the SDK's engine; `react`, `@videojs/react` and `hls.js` are yours):
221
+
222
+ ```tsx
223
+ import "@videojs/react/video/skin.css";
224
+ import { Video, VideoPlayer, VideoSkin } from "@videojs/react/video";
225
+ import { HlsJsVideo } from "@videojs/react/media/hlsjs-video";
226
+ import { Player, type VideoJsComponents } from "@uploadfilm/sdk/react";
227
+
228
+ const VIDEOJS: VideoJsComponents = { Video, VideoPlayer, VideoSkin, HlsJsVideo };
229
+
230
+ export function Watch({ hls, mp4, poster }: { hls: string | null; mp4: string; poster?: string }) {
231
+ return (
232
+ <div style={{ position: "relative", aspectRatio: "16 / 9" }}>
233
+ <Player
234
+ sources={{ hls, mp4 }}
235
+ components={VIDEOJS}
236
+ poster={poster}
237
+ title="Day 3, scene 12"
238
+ theme={{ accentColor: "#ffb800", accentTextColor: "#000", borderRadius: "12px" }}
239
+ storyboard="https://media.example.com/h/GRANT/storyboard/storyboard.vtt"
240
+ bigPlay
241
+ onReady={() => console.log("playing with a buffer")}
242
+ onFailed={() => console.log("out of tries")}
243
+ />
244
+ </div>
245
+ );
246
+ }
247
+ ```
248
+
249
+ Without `components`, `<Player>` renders a plain `<video controls>` loaded by the engine. The package ships no CSS.
250
+
251
+ **Vanilla:**
252
+
253
+ ```ts
254
+ import Hls from "hls.js";
255
+ import { captionsTrack, createPlayer, hlsJsLoader } from "@uploadfilm/sdk/player";
256
+
257
+ const player = createPlayer({
258
+ sources: { hls: "https://media.example.com/h/GRANT/master.m3u8", mp4: "https://cdn.example.com/clip.mp4" },
259
+ stream: hlsJsLoader(Hls), // the SDK never imports hls.js itself
260
+ refreshSource: async ({ mode, attempt }) => freshSignedUrl(mode, attempt), // a new URL for a recovery
261
+ tracks: [captionsTrack("https://media.example.com/h/GRANT/transcript.vtt", { language: "en", label: "English" })],
262
+ });
263
+ player.attach(document.querySelector("video")!);
264
+ player.on("fallback", ({ from }) => console.log(`${from} gave up; the MP4 plays from the same spot`));
265
+ player.subscribe((s) => (document.title = `${s.status} · ${Math.round(s.currentTime)}s`));
266
+ await player.play(); // "sound" | "muted" | "failed" | "aborted"
267
+ ```
268
+
269
+ What it does for you:
270
+
271
+ - 📡 **HLS or MP4.** The stream where the browser can (MediaSource, ManagedMediaSource or native HLS), the MP4 otherwise.
272
+ - 🩹 **Recovery.** A stream failing before it played becomes the MP4 from the same spot; later failures load a fresh URL
273
+ and carry on, in the same paused/playing state, with backoff.
274
+ - 📴 **Offline.** It waits for the network instead of spending tries.
275
+ - 🧊 **Stalls.** A stalled MP4 or a frozen HLS playhead (WebKit: no error, no stall event) is reloaded.
276
+ - ✋ **The viewer's pause wins**, through fallbacks and recoveries.
277
+
278
+ Events: `ready`, `stall`, `error`, `recover`, `fallback`, `cantplay`, `failed`, `offline` / `online`, `cuechange`,
279
+ `sourcechange`, plus the element's own. In React, `usePlayer({ …, onReady, onStall, onFailed, onEvent })` and
280
+ `usePlayerState(player, selector)`.
281
+
282
+ **Tracks, captions and hover previews.** Markers, chapters and captions are `TimedTrack`s
283
+ (`player.setTracks([...])`, `loadCaptions`, `captionsFromVtt`, `cuePosition`, `nextCue`). Storyboard previews come from
284
+ the media Worker's `storyboard.vtt`: `createTimelinePreviews(url)` + `spriteStyle(preview, 160)`, or in React
285
+ `useTimelinePreview(url, hoverTime, { width: 160 })` and `<TimelinePreview>`.
286
+
287
+ **Your own controls**, no Video.js:
288
+
289
+ ```tsx
290
+ import Hls from "hls.js";
291
+ import { hlsJsLoader } from "@uploadfilm/sdk/player";
292
+ import { usePlayer, usePlayerState } from "@uploadfilm/sdk/react";
293
+
294
+ const stream = hlsJsLoader(Hls);
295
+
296
+ export function MiniPlayer({ hls, mp4 }: { hls: string; mp4: string }) {
297
+ const { player, videoRef } = usePlayer({ sources: { hls, mp4 }, stream, autoplay: false });
298
+ const { paused, currentTime, duration } = usePlayerState(player, (s) => ({
299
+ paused: s.paused,
300
+ currentTime: s.currentTime,
301
+ duration: s.duration,
302
+ }));
303
+ return (
304
+ <div>
305
+ <video ref={videoRef} playsInline style={{ width: "100%" }} />
306
+ <button onClick={() => (paused ? void player.play() : player.pause())}>{paused ? "▶️" : "⏸️"}</button>
307
+ <span>{Math.round(currentTime)} / {Math.round(duration)} s</span>
308
+ </div>
309
+ );
310
+ }
311
+ ```
312
+
313
+ ### 🪟 Embeds
314
+
315
+ Serve the embed script from your own domain:
316
+
317
+ ```ts
318
+ // app/embeds/v1/player.js/route.ts
319
+ import { servePlayerScript } from "@uploadfilm/sdk/server";
320
+
321
+ const serve = servePlayerScript(); // 200 with an ETag, then cheap 304s
322
+ export const GET = serve;
323
+ export const HEAD = serve;
324
+ ```
325
+
326
+ Your customers' pages then do:
327
+
328
+ ```html
329
+ <iframe id="reel" src="https://app.example.com/e/EMBED_ID" allow="autoplay; fullscreen; picture-in-picture"></iframe>
330
+ <script src="https://app.example.com/embeds/v1/player.js"></script>
331
+ <script>
332
+ const player = new UploadFilm.Player(document.getElementById("reel"));
333
+ player.on("ready", () => player.seek(12.5).play());
334
+ </script>
335
+ ```
336
+
337
+ From your own code: `new EmbedController(iframe)`, `defineEmbedElement()` for `<uploadfilm-player src="…">`,
338
+ `iframeSnippet(…)` for the copy-paste snippet, `parseOEmbedRequest` + `buildOEmbed`, and on the frame side
339
+ `serveEmbedControl(player, { embedId })`. Your product's name on the global (`MyApp.Player`):
340
+ `servePlayerScript({ script: renameEmbedGlobal(PLAYER_SCRIPT, "MyApp") })`; the tag too: `defineEmbedElement("myapp-player")`.
341
+
342
+ ## ⚙️ The media pipeline on Cloudflare Workers
343
+
344
+ You run your own media Worker (Worker + Durable Object + FFmpeg Container) on your own Cloudflare account, against
345
+ your own bucket. It ships as its own package, `@uploadfilm/media-worker` (with `npx @uploadfilm/media-worker init` to
346
+ scaffold it). This package gives your site the job client and the protocol.
347
+
348
+ ```
349
+ your site ──signed job (HMAC)──▶ media Worker ──▶ Durable Object (one per job) ──▶ FFmpeg Container: ONE decode
350
+ ▲ │
351
+ └────────── signed report ◀── destroy() the container once the result is in ◀───────┘ outputs ──▶ your R2
352
+ viewers ──▶ /h/<sealed grant>/master.m3u8 (served by the Worker)
353
+ ```
354
+
355
+ | Step | Outputs |
356
+ |---|---|
357
+ | `ladder` | HLS fMP4, 360 / 720 / 1080; `master.m3u8` is written last: it is the "done" file |
358
+ | `poster` | the poster frame |
359
+ | `storyboard` | WebP sprite sheets + `storyboard.vtt` for hover previews |
360
+ | `faststart` | `faststart.mp4`, index first (a remux, no decode) |
361
+ | `audio` / `transcript` | audio chunks with silences found; `transcript.json` + `transcript.vtt` (Workers AI Whisper or any `@uploadfilm/sdk/ai` Transcriber) |
362
+
363
+ From your site:
364
+
365
+ ```ts
366
+ import { grantSealer, jobVersion, mediaJobClient, refuseStale, sourceHash, stepSettings, type Step } from "@uploadfilm/sdk/server";
367
+
368
+ const VERSION = "360-720-1080/2"; // the same as the Worker's config: stamped on every output
369
+ const SETTINGS = stepSettings("steps-sb/1", { storyboard: {} });
370
+ const STEPS: Step[] = ["ladder", "poster", "storyboard"];
371
+ const STAMP = jobVersion(VERSION, STEPS, SETTINGS);
372
+
373
+ const media = mediaJobClient({
374
+ url: process.env.MEDIA_URL!,
375
+ secret: () => process.env.MEDIA_SECRET!,
376
+ jobDomain: "media-job-1",
377
+ doneDomain: "media-done-1",
378
+ signatureHeader: "x-media-sig",
379
+ issuedAt: true, // a captured request can't be replayed later
380
+ });
381
+
382
+ export async function requestMedia(src: string, etag: string, bytes: number, attempt: number) {
383
+ const prefix = `media/${(await sourceHash(src, etag, VERSION)).slice(0, 32)}/`;
384
+ await media.request({ id: prefix.split("/")[1], attempt, src, etag, bytes, prefix, done: "https://app.example.com/api/media/done", steps: STEPS });
385
+ return prefix;
386
+ }
387
+
388
+ // POST /api/media/done: the Worker's signed report.
389
+ export async function POST(req: Request) {
390
+ const checked = await media.readReport(await req.text(), req.headers.get("x-media-sig") ?? "");
391
+ if (!checked.ok) return new Response(checked.body, { status: checked.status });
392
+ const r = checked.report;
393
+ if (r.state === "done" && refuseStale({ state: "done", ladder: r.ladder as string | undefined }, STAMP))
394
+ return new Response("stale image", { status: 409 });
395
+ // Update your record only where id, attempt AND prefix still match: a late report of an older attempt changes nothing.
396
+ await markReadyIfCurrent({ id: String(r.id), attempt: Number(r.attempt), prefix: String(r.prefix), ok: r.state === "done" });
397
+ return new Response("ok");
398
+ }
399
+
400
+ // A viewer's URL: a sealed grant to the outputs' folder, valid 6 hours.
401
+ const grants = grantSealer({ salt: "myproduct-stream", isValid: (g) => /^media\/[0-9a-f]{32}\/$/.test(g.prefix) });
402
+ export async function streamUrl(prefix: string) {
403
+ const token = await grants.sealGrant(process.env.MEDIA_SECRET!, { prefix, exp: Math.floor(Date.now() / 1000) + 6 * 3600 });
404
+ return `${process.env.MEDIA_URL}/h/${token}/master.m3u8`;
405
+ }
406
+ ```
407
+
408
+ - 🔏 **Signed both ways**, with different HMAC domains; with `issuedAt` a request outside ±15 min is refused.
409
+ - 📁 **A job writes only where its source's outputs belong**; reads are pinned to the source ETag; callbacks are
410
+ allowlisted (https only).
411
+ - 🏷️ **The settings version is the idempotency key**: the same id + version is the same job, joined while it runs and
412
+ answered from its result once done. Outputs stamped by an older image are refused.
413
+ - 💸 **Containers never idle**: the Durable Object calls `destroy()` as soon as the result is collected, and the
414
+ container exits on SIGTERM. An idle-container bug once cost about $77 in a week. **Set a budget alert on your
415
+ Cloudflare account before the first deploy.**
416
+ - 🎞️ The container runs a pinned FFmpeg 7.1.5. Proprietary RAW never goes in the core image: without a decoder plugin a
417
+ RAW source fails with code `unsupported`, so store it and flag it "no preview".
418
+
419
+ Also server-side: `copy()` with `r2()` / `s3()` replicates objects to S3 (backup, archive, Object Lock) with byte
420
+ verification, driven by `createPipeline`; a ZIP Worker (`@uploadfilm/zip-worker`) streams folder downloads of any size
421
+ straight from R2.
422
+
423
+ ## 🧪 Testing your integration
424
+
425
+ `@uploadfilm/sdk/server/testing` gives you a fake R2 that checks SigV4 like the real one, serves presigned URLs and
426
+ injects faults. Wire your real sign handler to it and run the real engine end to end:
427
+
428
+ ```ts
429
+ import { mkdtempSync, writeFileSync } from "node:fs";
430
+ import { tmpdir } from "node:os";
431
+ import { join } from "node:path";
432
+ import { createFetchTransport, createHttpSigner, createTiming, createTransferEngine } from "@uploadfilm/sdk";
433
+ import { createKeyGuard, createR2Client, createSignHandler } from "@uploadfilm/sdk/server";
434
+ import { createFakeR2 } from "@uploadfilm/sdk/server/testing";
435
+
436
+ const fake = await createFakeR2(); // a random local port
437
+ const guard = createKeyGuard((s) => (s[0] === "orig" ? "original" : null));
438
+ const handler = createSignHandler({
439
+ r2: createR2Client(fake.config),
440
+ classify: (key, ctx: { project: string }) => guard(`p/${ctx.project}/`, key),
441
+ immutable: () => true,
442
+ });
443
+ const timing = createTiming({ scale: 0.01 }); // timeouts and backoffs 100× shorter
444
+ const engine = createTransferEngine({
445
+ signer: createHttpSigner({
446
+ url: "http://test/sign",
447
+ fetch: async (_url, init) => {
448
+ const answer = await handler.handle(JSON.parse(String(init?.body)), { project: "p1" });
449
+ return Response.json(answer.body, { status: answer.status });
450
+ },
451
+ }),
452
+ transport: createFetchTransport(timing),
453
+ timing,
454
+ scope: "p1",
455
+ });
456
+ engine.start();
457
+
458
+ // Storage stores a corrupted part: the engine must resend it, never say "verified" on bad bytes.
459
+ fake.fault({ target: "partPut", action: "storeCorrupted", times: 1 });
460
+
461
+ const file = join(mkdtempSync(join(tmpdir(), "sdk-")), "clip.mov");
462
+ writeFileSync(file, Buffer.alloc(40 * 1024 * 1024, 7));
463
+ const r = await engine.upload({ key: "p/p1/orig/clip.mov", path: file, immutable: true }).done;
464
+ console.assert(r.state === "verified");
465
+ console.assert(fake.object("p/p1/orig/clip.mov")!.body.equals(Buffer.alloc(40 * 1024 * 1024, 7))); // the bytes
466
+ engine.stop();
467
+ await fake.close();
468
+ ```
469
+
470
+ Faults: `drop`, `reset`, `dropResponse`, `holdResponse`, `delay`, `status`, `stall`, `noSuchUpload`, `expire`,
471
+ `corruptInTransit`, `storeCorrupted`, `wrongEtag` (aim them with `times`, `after`, `match`), and `fake.outage(true)` for
472
+ a pulled cable. ✅ **Make every test check the stored bytes, not just the result.** Writing your own `KeyValueStore`?
473
+ Run `keyValueStoreContract` against it.
474
+
475
+ ## 🛡️ Guarantees
476
+
477
+ - 🔒 **Security.** Tokens, signed URLs, routes and embeds are attacked by a red team (forge, steal, replay, escalate,
478
+ cross-access, inject); every hole closed has a regression test. Verifiers fail closed, secret compares are
479
+ constant-time, every token kind is domain-separated, revocation stores that can't answer mean "revoked", and the key
480
+ guard refuses traversal, encoding tricks, invisible and bidi characters. Signed URLs never appear in results or errors.
481
+ - 🧱 **Reliability.** Fault-injecting fake servers, property-based tests, kill-and-resume and soak runs, with every
482
+ test upload's bytes checked against the stored object: zero tolerance for silent corruption or a false "done".
483
+ - 🎥 **Formats.** Cameras, phones, codecs and containers probe, process and play correctly, or are rejected or flagged
484
+ gracefully (HDR tone-mapped, interlaced deinterlaced, VFR, edit lists, RAW flagged "no preview" without a plugin).
485
+
486
+ ## ❓ Good to know
487
+
488
+ - **Node:** `^20.16.0 || >=22.3.0` (the SDK uses `zlib.crc32` and `process.getBuiltinModule`).
489
+ - **Why not the AWS S3 SDK?** Write credentials on a laptop would bypass immutability and quota, so clients only get
490
+ per-part presigned URLs. Lighter too.
491
+ - **Workers' ~100 MiB request cap:** `s3()` and `r2()` over the S3 API cap requests at 96 MiB inside a Worker by
492
+ themselves. Client uploads go straight to R2 with presigned URLs and never pass through a Worker.
493
+ - **Next.js caches storage calls:** pass `fetch: (url, init) => fetch(url, { ...init, cache: "no-store" })` to
494
+ `createR2Client`.
495
+ - **Keep your own uploader?** Fine: take the transports, signing or player alone. Everything is an independent import.
496
+
497
+ ## 🚧 Not built yet
498
+
499
+ | Not yet | Today |
500
+ |---|---|
501
+ | A browser build of the transfer engine (File source, wasm hasher) | Node and Electron only |
502
+ | Growing-source uploads (a file still being recorded) | upload once the file is closed |
503
+ | An async `ResumeStore` | `fileStore`, `memoryStore` (synchronous) |
504
+ | SHA-256 receipts through `createSignHandler` | it fails closed (`Unverified`); sign `x-amz-checksum-sha256` in a route of your own |
505
+ | Job bookkeeping helpers (claims, attempts, backoff for media jobs) | your own |
506
+ | RAW plugins for R3D, ARRIRAW, Canon Cinema RAW Light | BRAW only |
507
+
508
+ ## License
509
+
510
+ Proprietary (`UNLICENSED`): see `LICENSE` in the package. Use requires a written agreement with UploadFilm.
@@ -0,0 +1,58 @@
1
+ /**
2
+ * Vectors for a transcript's passages (or a video's frames), delivered batch by batch to the product's `onEmbeddings`
3
+ * hook. The SDK NEVER stores them: the product writes them to its own pgvector table or Vectorize index (keyed by its
4
+ * asset id + passage index), and decides what to do when its write fails.
5
+ *
6
+ * Never throws: the outcome says what was delivered, so an embedding that can't be made never fails a video job.
7
+ */
8
+ import { type Passage, type PassageOptions } from "./passages";
9
+ import type { Transcript } from "../server/media/transcript";
10
+ import type { AiUsage, Embedder, ImageInput } from "./types";
11
+ export interface EmbeddingBatch<T> {
12
+ /** What was embedded (passages, or frames' times), in order. */
13
+ items: T[];
14
+ /** One vector per item. */
15
+ vectors: number[][];
16
+ adapter: string;
17
+ model: string;
18
+ dimensions: number;
19
+ usage: AiUsage;
20
+ /** Which batch (0-based) of how many. */
21
+ batch: number;
22
+ batches: number;
23
+ }
24
+ export type EmbedOutcome = {
25
+ state: "done";
26
+ items: number;
27
+ batches: number;
28
+ dimensions: number;
29
+ usage: AiUsage[];
30
+ } | {
31
+ state: "error";
32
+ reason: string;
33
+ permanent: boolean;
34
+ /** Batches already handed to onEmbeddings. */ delivered: number;
35
+ usage: AiUsage[];
36
+ };
37
+ export interface EmbedRunOptions<T> {
38
+ embedder: Embedder;
39
+ /** Gets each batch's vectors. A throw (the product's store failed) stops the run: state "error". */
40
+ onEmbeddings(batch: EmbeddingBatch<T>): void | Promise<void>;
41
+ /** Items per call (default and maximum: the embedder's maxBatch). */
42
+ batchSize?: number;
43
+ signal?: AbortSignal;
44
+ onUsage?: (u: AiUsage) => void;
45
+ }
46
+ /** A transcript → passages → vectors, handed over batch by batch. */
47
+ export declare function embedTranscript(o: EmbedRunOptions<Passage> & {
48
+ transcript: Pick<Transcript, "segments">;
49
+ passages: PassageOptions;
50
+ }): Promise<EmbedOutcome>;
51
+ /** Passages (from transcriptPassages, or the product's own) → vectors. */
52
+ export declare function embedPassages(o: EmbedRunOptions<Passage> & {
53
+ passages: Passage[];
54
+ }): Promise<EmbedOutcome>;
55
+ /** Frames (storyboard tiles, keyframes) → vectors; each frame's `t` comes back with its vector. */
56
+ export declare function embedFrames(o: EmbedRunOptions<ImageInput> & {
57
+ frames: ImageInput[];
58
+ }): Promise<EmbedOutcome>;
@@ -0,0 +1,41 @@
1
+ /**
2
+ * Fakes for tests: a transcriber answering from a script (recorded answers, errors, delays) and a deterministic
3
+ * embedder (the same text always gives the same unit vector). Both report usage like a real adapter.
4
+ */
5
+ import { type AudioInput, type EmbedInput, type Embedder, type TranscribeOptions, type Transcriber, type Transcription } from "./types";
6
+ export type FakeAnswer = Omit<Transcription, "usage" | "text"> & {
7
+ text?: string;
8
+ };
9
+ export interface FakeTranscriberOptions {
10
+ /**
11
+ * The answer to call n (0-based): a Transcription-like value, an Error to throw, or a function of the audio. Past the
12
+ * end of a list, the last entry repeats.
13
+ */
14
+ answers: (FakeAnswer | Error)[] | ((audio: AudioInput, n: number, o: TranscribeOptions) => FakeAnswer | Error | Promise<FakeAnswer | Error>);
15
+ model?: string;
16
+ maxBytes?: number;
17
+ /** Simulated latency (ms) reported in usage. */
18
+ latencyMs?: number;
19
+ /** Simulated price per audio minute. */
20
+ perAudioMinuteUsd?: number;
21
+ }
22
+ export declare function fakeTranscriber(o: FakeTranscriberOptions): Transcriber & {
23
+ calls: {
24
+ audio: AudioInput;
25
+ options: TranscribeOptions;
26
+ }[];
27
+ };
28
+ /** A deterministic unit vector for a string (tests: equal texts → equal vectors; different texts → different). */
29
+ export declare function fakeVector(s: string, dims: number): number[];
30
+ export interface FakeEmbedderOptions {
31
+ dimensions?: number;
32
+ model?: string;
33
+ maxBatch?: number;
34
+ images?: boolean;
35
+ /** Throw this on call n (0-based). */
36
+ failOn?: (n: number) => Error | undefined;
37
+ latencyMs?: number;
38
+ }
39
+ export declare function fakeEmbedder(o?: FakeEmbedderOptions): Embedder & {
40
+ calls: EmbedInput[];
41
+ };
@@ -0,0 +1,17 @@
1
+ export type FetchLike = (url: string, init: RequestInit) => Promise<Response>;
2
+ /** A key, or a function giving one (rotated secrets, a vault): asked for on every call, never kept. */
3
+ export type Credential = string | (() => string | Promise<string>);
4
+ export declare const credential: (c: Credential | undefined) => Promise<string | undefined>;
5
+ /** Biggest answer read (bytes): an endpoint answering garbage can't fill memory. */
6
+ export declare const MAX_ANSWER_BYTES: number;
7
+ /** POST and read a JSON answer. Network errors, timeouts, 408/429/5xx: not permanent; other 4xx and bad JSON: permanent/not. */
8
+ export declare function requestJson(adapter: string, f: FetchLike, url: string, init: RequestInit, o: {
9
+ timeoutMs: number;
10
+ signal?: AbortSignal;
11
+ }): Promise<{
12
+ json: unknown;
13
+ headers: Headers;
14
+ }>;
15
+ /** Bytes → base64 in slices (no Buffer in workerd without nodejs_compat; one spread of a whole chunk overflows the stack). */
16
+ export declare function toBase64(b: Uint8Array): string;
17
+ export declare const trimSlash: (u: string) => string;