@uploadfilm/sdk 0.1.0 → 0.2.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 (75) hide show
  1. package/README.md +26 -6
  2. package/dist/copy/types.d.ts +29 -2
  3. package/dist/index.js +1 -1
  4. package/dist/index.mjs +1 -1
  5. package/dist/player.js +1 -1
  6. package/dist/player.mjs +1 -1
  7. package/dist/server/media/client.d.ts +34 -1
  8. package/dist/server/media/protocol.d.ts +242 -4
  9. package/dist/server/r2/client.d.ts +18 -4
  10. package/dist/server/storage/chunked.d.ts +6 -2
  11. package/dist/server/storage/s3.d.ts +51 -0
  12. package/dist/server/testing/fake-r2.d.ts +22 -2
  13. package/dist/server/transfer/handler.d.ts +50 -0
  14. package/dist/server/transfer/protocol.d.ts +53 -4
  15. package/dist/server-media.js +1 -1
  16. package/dist/server-media.mjs +1 -1
  17. package/dist/server-testing.js +1 -1
  18. package/dist/server-testing.mjs +1 -1
  19. package/dist/server.js +1 -1
  20. package/dist/server.mjs +1 -1
  21. package/dist/transfer/client.d.ts +13 -2
  22. package/dist/transfer/engine.d.ts +22 -2
  23. package/dist/transfer/growing/bytes.d.ts +17 -0
  24. package/dist/transfer/growing/index.d.ts +12 -0
  25. package/dist/transfer/growing/parts.d.ts +157 -0
  26. package/dist/transfer/growing/retry.d.ts +38 -0
  27. package/dist/transfer/growing/store.d.ts +66 -0
  28. package/dist/transfer/growing/upload.d.ts +126 -0
  29. package/dist/transfer/index.d.ts +1 -0
  30. package/dist/transfer/protocol.d.ts +5 -0
  31. package/dist/transfer/storage.d.ts +28 -3
  32. package/dist/workers/cli.mjs +115 -0
  33. package/dist/workers/media/config.mjs +53 -0
  34. package/dist/workers/media/container/Dockerfile +19 -0
  35. package/dist/workers/media/container/FFMPEG.md +129 -0
  36. package/dist/workers/media/container/runner.mjs +2690 -0
  37. package/dist/workers/media/index.mjs +1011 -0
  38. package/dist/workers/media/init/config.ts +52 -0
  39. package/dist/workers/media/init/worker.ts +8 -0
  40. package/dist/workers/media/init/wrangler.toml +44 -0
  41. package/dist/workers/media/runner.mjs +2656 -0
  42. package/dist/workers/media/types/build/entry/config.d.mts +6 -0
  43. package/dist/workers/media/types/build/entry/index.d.mts +43 -0
  44. package/dist/workers/media/types/build/entry/program.d.mts +13 -0
  45. package/dist/workers/media/types/build/entry/runner.d.mts +12 -0
  46. package/dist/workers/media/types/build/entry/settings.d.mts +40 -0
  47. package/dist/workers/media/types/src/config.d.mts +135 -0
  48. package/dist/workers/media/types/src/jobs.d.mts +73 -0
  49. package/dist/workers/media/types/src/runner/container.d.mts +32 -0
  50. package/dist/workers/media/types/src/runner/ffmpeg.d.mts +227 -0
  51. package/dist/workers/media/types/src/runner/job.d.mts +107 -0
  52. package/dist/workers/media/types/src/runner/node.d.mts +71 -0
  53. package/dist/workers/media/types/src/runner/plugins.d.mts +45 -0
  54. package/dist/workers/media/types/src/serve.d.mts +107 -0
  55. package/dist/workers/media/types/src/steps/audio.d.mts +33 -0
  56. package/dist/workers/media/types/src/steps/edit.d.mts +62 -0
  57. package/dist/workers/media/types/src/steps/frameCheck.d.mts +44 -0
  58. package/dist/workers/media/types/src/steps/gate.d.mts +18 -0
  59. package/dist/workers/media/types/src/steps/paths.d.mts +1 -0
  60. package/dist/workers/media/types/src/steps/prep.d.mts +60 -0
  61. package/dist/workers/media/types/src/steps/render.d.mts +40 -0
  62. package/dist/workers/media/types/src/steps/runner.d.mts +30 -0
  63. package/dist/workers/media/types/src/steps/transcribe.d.mts +89 -0
  64. package/dist/workers/media/types/src/storyboard/index.d.mts +61 -0
  65. package/dist/workers/media/types/src/transcoder.d.mts +30 -0
  66. package/dist/workers/media/types/src/worker.d.mts +30 -0
  67. package/dist/workers/zip/index.mjs +589 -0
  68. package/dist/workers/zip/init/config.ts +22 -0
  69. package/dist/workers/zip/init/worker.ts +5 -0
  70. package/dist/workers/zip/init/wrangler.toml +25 -0
  71. package/dist/workers/zip/types/build/entry/index.d.mts +5 -0
  72. package/dist/workers/zip/types/src/config.d.mts +35 -0
  73. package/dist/workers/zip/types/src/serve.d.mts +86 -0
  74. package/dist/workers/zip/types/src/worker.d.mts +12 -0
  75. package/package.json +51 -3
package/README.md CHANGED
@@ -39,7 +39,7 @@ npm install @uploadfilm/sdk
39
39
 
40
40
  ## 🧭 Entry points
41
41
 
42
- Every entry point is a subpath of this one package, ESM + CJS with types, `sideEffects: false`.
42
+ Every entry point is a subpath of this one package, ESM + CJS with types (the Workers: ESM only), `sideEffects: false`.
43
43
 
44
44
  | Import | What you get | Runs in |
45
45
  |---|---|---|
@@ -54,9 +54,12 @@ Every entry point is a subpath of this one package, ESM + CJS with types, `sideE
54
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
55
  | `@uploadfilm/sdk/cards` | Camera cards: mounted volumes, camera folder layouts read into clips (spanned clips, proxies, sidecars, LUTs), the upload plan | Node |
56
56
  | `@uploadfilm/sdk/sync` | Dual-system audio sync: which recorder file belongs to which clip, and at what offset | Node (runs FFmpeg) |
57
+ | `@uploadfilm/sdk/workers/media` · `/config` · `/runner` | Your media Worker: `createMediaWorker(config)`, the `Transcoder` Durable Object, `ContainerProxy`; `/config` (types and defaults, safe in Node); `/runner` (self-hosted runner, the container program for a custom image). The container files: `/workers/media/container/Dockerfile`, `runner.mjs`. ESM only | Cloudflare Workers (`/runner`: Node 22.3+) |
58
+ | `@uploadfilm/sdk/workers/zip` | Your zip download Worker: `createZipWorker(config)`, `createZipHandler`. ESM only | Cloudflare Workers |
57
59
 
58
60
  **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
61
+ `@upstash/redis`, `inngest`, `@cloudflare/workers-types`, `@cloudflare/containers` (the media Worker only). The SDK
62
+ never imports them itself where it can avoid it: you
60
63
  pass `undici`, `hls.js` or Electron's `net` in.
61
64
 
62
65
  ## 🚀 Quick start: uploads (Node or Electron)
@@ -342,8 +345,25 @@ From your own code: `new EmbedController(iframe)`, `defineEmbedElement()` for `<
342
345
  ## ⚙️ The media pipeline on Cloudflare Workers
343
346
 
344
347
  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.
348
+ your own bucket. The Worker ships **in this package** at `@uploadfilm/sdk/workers/media` (same version as the job client
349
+ your site imports, so they never drift):
350
+
351
+ ```bash
352
+ npm install @uploadfilm/sdk @cloudflare/containers@^0.3.7 @cloudflare/workers-types wrangler # the peers only the Worker needs
353
+ npx @uploadfilm/sdk init media-worker workers/media # worker.ts, config.ts, wrangler.toml (never overwrites)
354
+ cd workers/media && npx wrangler secret put MEDIA_SECRET && npx wrangler deploy # set a Cloudflare budget alert first
355
+ ```
356
+
357
+ ```ts
358
+ // workers/media/worker.ts
359
+ import { createMediaWorker } from "@uploadfilm/sdk/workers/media";
360
+ import { config } from "./config";
361
+ export default createMediaWorker(config);
362
+ export { Transcoder, ContainerProxy } from "@uploadfilm/sdk/workers/media";
363
+ ```
364
+
365
+ The container image is built from the installed package (`dist/workers/media/container/Dockerfile`: a pinned base image
366
+ and FFmpeg 7.1.5, no product settings baked in). Your site uses the job client and the protocol below.
347
367
 
348
368
  ```
349
369
  your site ──signed job (HMAC)──▶ media Worker ──▶ Durable Object (one per job) ──▶ FFmpeg Container: ONE decode
@@ -417,8 +437,8 @@ export async function streamUrl(prefix: string) {
417
437
  RAW source fails with code `unsupported`, so store it and flag it "no preview".
418
438
 
419
439
  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.
440
+ verification, driven by `createPipeline`; a ZIP Worker (`@uploadfilm/sdk/workers/zip`,
441
+ `npx @uploadfilm/sdk init zip-worker`) streams folder downloads of any size straight from R2.
422
442
 
423
443
  ## 🧪 Testing your integration
424
444
 
@@ -112,7 +112,10 @@ export interface WriteOptions {
112
112
  size?: number;
113
113
  /** User metadata to store with the object (lowercase keys). */
114
114
  meta: Record<string, string>;
115
- /** publish(): the CRC-32 (hex) the staged object must still have. */
115
+ /**
116
+ * The CRC-32 (hex) the object must have. publish(): the staged object must still have it. put(): a destination
117
+ * that can check it (s3: sent as the trailer's checksum) refuses other bytes, so nothing else is stored.
118
+ */
116
119
  crc32?: string;
117
120
  }
118
121
  export interface UploadInfo {
@@ -227,10 +230,28 @@ export interface CopyOptions {
227
230
  * e.g. the last part stored but its answer lost): complete that upload as the old version's copy instead of
228
231
  * abandoning it (default false). Where the source keeps no old versions (R2), it may be the only copy of those
229
232
  * bytes. Proven like any copy: against the old version's known checksum. Needs a destination that lists parts.
233
+ * true: never over another version's copy that is already the current object, and in a resumed upload only parts
234
+ * this run sent or checked. "keepAll", for a destination that keeps every version (a versioned bucket): completed
235
+ * over another version's copy too (that one becomes non-current), and a resumed upload's other parts count when
236
+ * they have the right size and a CRC (the completed object must carry this version's source-etag). The backup
237
+ * Worker's rule.
230
238
  */
231
- salvage?: boolean;
239
+ salvage?: boolean | "keepAll";
232
240
  /** Part size (bytes). Default: the source's own part size when known, else the destination's preference. */
233
241
  partSize?: number;
242
+ /**
243
+ * How the copy is written: "auto" (default) is one PUT when the object fits one part, else a multipart upload;
244
+ * "always" is a multipart upload whatever the size (an empty object is one empty part); "never" is one PUT, and an
245
+ * object over the destination's largest PUT fails with TooLarge. A product whose existing copies were made one way
246
+ * keeps making them that way (the backup Worker: originals always multipart, manifest revisions one PUT), so the
247
+ * stored ETags stay the same.
248
+ */
249
+ multipart?: "auto" | "always" | "never";
250
+ /**
251
+ * Write the `verify` label (`verify=unverified|etag|read`) when no expected CRC-32 is known (default true). false: no
252
+ * label (the backup Worker's manifest revisions carry none). `expected-crc32` is written either way when known.
253
+ */
254
+ verifyMeta?: boolean;
234
255
  /** Most parts a copy may be cut into (e.g. ≤ 900 when every part is an Inngest step). */
235
256
  maxParts?: number;
236
257
  /** A source body that sends no byte for this long is a failed read, retried (default 120 s). */
@@ -265,6 +286,12 @@ export interface CopyOptions {
265
286
  * lifecycle rule (a writer key without abort permission; the backup worker never aborts).
266
287
  */
267
288
  abandon?: "abort" | "leave";
289
+ /**
290
+ * An existing copy of this version that holds other bytes than its known checksum: "recopy" (default) copies again
291
+ * once, labelled `attempt=recopy`, and a mismatch then fails; "copy" copies again as an ordinary first copy (it may
292
+ * resume an unfinished upload), then recopies once if that mismatches too: the backup Worker's rule.
293
+ */
294
+ existingMismatch?: "recopy" | "copy";
268
295
  /** Recopy even though an earlier recopy of this version mismatched the expected CRC (send by hand once fixed). */
269
296
  force?: boolean;
270
297
  hasher?: CopyHasher;