@verygoodffmpeg/sdk 0.1.0 → 1.0.0

package/README.md

@@ -0,0 +1,136 @@
+# @verygoodffmpeg/sdk
+
+TypeScript SDK for the Very Good FFmpeg API — run FFmpeg jobs in the cloud.
+
+[![npm](https://img.shields.io/npm/v/@verygoodffmpeg/sdk)](https://www.npmjs.com/package/@verygoodffmpeg/sdk)
+
+[Homepage](https://verygoodffmpeg.com) · [API Docs](https://verygoodffmpeg.com/docs)
+
+## Usage
+
+```
+npm install @verygoodffmpeg/sdk
+```
+
+```ts
+import VGF from "@verygoodffmpeg/sdk";
+
+const client = new VGF(process.env.VGF_API_KEY);
+
+// Create a job and wait for it to complete
+const job = await client.run(
+  {
+    input_files: {
+      "input.mp4": "https://example.com/input.mp4",
+    },
+    output_files: ["output.mp4"],
+    ffmpeg_commands: ["-i input.mp4 -vf scale=1280:720 output.mp4"],
+  },
+  { wait: true },
+);
+
+// Fetch the job again by ID
+const fetched = await client.jobs.get(job.id);
+console.log(fetched.status); // "succeeded"
+console.log(fetched.output_files); // { "output.mp4": "https://..." }
+```
+
+## Reference
+
+### Create a job — `client.run(params, options?)`
+
+Submits an FFmpeg job. Pass `{ wait: true }` to block until the job reaches a terminal state.
+
+```ts
+const job = await client.run(
+  {
+    input_files: { "input.mp4": "https://example.com/input.mp4" },
+    output_files: ["output.mp4"],
+    ffmpeg_commands: ["-i input.mp4 -c:v libx264 output.mp4"],
+    webhook_url: "https://example.com/webhook", // optional
+    machine: "nvidia", // optional: "cpu" | "nvidia"
+  },
+  { wait: true }, // optional
+);
+```
+
+### Get a job — `client.jobs.get(id)`
+
+Fetches a single job by ID.
+
+```ts
+const job = await client.jobs.get("job_abc123");
+console.log(job.status); // "queued" | "running" | "succeeded" | "failed" | "cancelled"
+```
+
+### List jobs — `client.jobs.list(params?)`
+
+Returns a paginated list of jobs.
+
+```ts
+const { data, pagingParams } = await client.jobs.list({ limit: 20, offset: 0 });
+console.log(data); // Job[]
+console.log(pagingParams); // { limit, offset, total, hasMore }
+```
+
+### Cancel a job — `client.jobs.cancel(id)`
+
+Cancels a queued or running job.
+
+```ts
+const job = await client.jobs.cancel("job_abc123");
+console.log(job.status); // "cancelled"
+```
+
+### Upload a file — `client.files.upload(data, contentType?)`
+
+Uploads a file to temporary storage and returns a URL you can use as an `input_files` value.
+
+```ts
+import { readFileSync } from "fs";
+
+const url = await client.files.upload(readFileSync("input.mp4"), "video/mp4");
+
+const job = await client.run({
+  input_files: { "input.mp4": url },
+  output_files: ["output.mp4"],
+  ffmpeg_commands: ["-i input.mp4 -vf scale=1280:720 output.mp4"],
+});
+```
+
+### Prepare upload — `client.files.prepareUpload()`
+
+Returns a presigned `upload_url` and `download_url` directly, useful when you need to stream a large file yourself rather than buffering it in memory.
+
+```ts
+import { createReadStream, statSync } from "fs";
+
+const { upload_url, download_url } = await client.files.prepareUpload();
+
+await fetch(upload_url, {
+  method: "PUT",
+  headers: {
+    "Content-Type": "video/mp4",
+    "Content-Length": String(statSync("large.mp4").size),
+  },
+  body: createReadStream("large.mp4"),
+  duplex: "half",
+});
+
+const job = await client.run({
+  input_files: { "input.mp4": download_url },
+  output_files: ["output.mp4"],
+  ffmpeg_commands: ["-i input.mp4 -vf scale=1280:720 output.mp4"],
+});
+```
+
+## Complete examples
+
+See the [`examples/`](./examples) folder for minimal runnable examples:
+
+- [`examples/node-cjs`](./examples/node-cjs) — Node.js CommonJS
+- [`examples/ts-esm`](./examples/ts-esm) — TypeScript ESM
+
+## Support
+
+Open an issue at [github.com/verygoodffmpeg/Very-Good-FFmpeg-Typescript-SDK](https://github.com/verygoodffmpeg/Very-Good-FFmpeg-Typescript-SDK) or email [please_help@verygoodffmpeg.com](mailto:please_help@verygoodffmpeg.com).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@verygoodffmpeg/sdk",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "description": "TypeScript SDK for the Very Good FFmpeg API",
   "type": "module",
   "main": "./dist/index.cjs",