@liqhtworks/sophon-sdk 0.1.4 → 0.1.5

package/.github/CODEOWNERS

@@ -0,0 +1,6 @@
+# This repository is generated from Liqhtworks/sophon-api at every
+# release. Source-side changes (helpers, OpenAPI spec, generator
+# config) belong in that repo, not here. Filing issues / PRs against
+# this repo is fine — Liqhtworks engineers triage them and route the
+# fix upstream as needed.
+*       @Liqhtworks/engineering

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,34 @@
+---
+name: Bug report
+about: Something the SDK does that contradicts the docs or its types.
+title: "[bug] "
+labels: bug
+---
+
+## What happened
+
+<!-- What you tried to do, what the SDK did instead. -->
+
+## Reproducer
+
+```ts
+// Minimum code that reproduces. Strip secrets.
+import { Configuration, JobsApi } from "@liqhtworks/sophon-sdk";
+// …
+```
+
+## Environment
+
+- `@liqhtworks/sophon-sdk` version: `0.1.x`
+- Node / Bun / Deno version: `…`
+- OS: `…`
+- Running in: server-side / browser / edge runtime
+
+## Expected vs. actual
+
+- Expected: `…`
+- Actual: `…` (paste error message + stack trace inside a fenced block)
+
+## Anything else
+
+<!-- Logs, X-Request-Id headers from the response, network captures, etc. -->

package/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: SOPHON API documentation
+    url: https://registry.scalar.com/@liqhtworks/apis/sophon-encoding-api/latest
+    about: Reference for every endpoint the SDK wraps.
+  - name: API + spec issues (sophon-api)
+    url: https://github.com/Liqhtworks/sophon-api/issues
+    about: For server-side bugs or OpenAPI questions, file there. SDK bugs stay here.

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: A capability you want from the SDK that isn't shipped.
+title: "[feature] "
+labels: enhancement
+---
+
+## What would you like the SDK to do
+
+<!-- Describe the customer-facing behavior, not the implementation. -->
+
+## What you tried instead
+
+<!-- Working around it today, or which competitor / hand-rolled tool you'd
+otherwise reach for. -->
+
+## Is this an SDK-level fit, or upstream?
+
+- [ ] SDK-level (helper, type, ergonomic)
+- [ ] Spec / API-level (would also need a sophon-api change)

package/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+All notable changes to `@liqhtworks/sophon-sdk` are recorded here. The
+package follows [SemVer](https://semver.org/) — see `README.md` for the
+versioning policy applied during the v0.x pre-1.0 phase.
+
+## [0.1.4] — 2026-05-08
+
+- `JobSource.upload(uploadId)` constructor — typed alternative to the
+  fragile `{ type: "upload", upload_id: "..." }` literal.
+- Generated exports tightened so all helpers and discriminated-union
+  constructors are reachable at the top level.
+- Build-test coverage extended over the new surface.
+
+## [0.1.3] — 2026-05-08
+
+- `UploadsApiLike` helper interface narrowed to only the fields the
+  helpers actually read. The previous declaration typed `expires_at`
+  as `string`, but the generated `UploadsApi` returns `Date`, so the
+  helper compiled in isolation but not against the real client. Fixed.
+
+## [0.1.2] — 2026-04-23
+
+- Per-route idempotency keys in `uploadFile`. Earlier releases reused
+  one key for both `createUpload` and `completeUpload`; SOPHON scopes
+  idempotency keys per route and rejected the second call with HTTP 409.
+  Now derives `${idem}/create` and `${idem}/complete` from the caller's
+  seed so retries still reach the server's idempotent path.
+- Build-test fixtures regenerate as real ffprobe-able media via ffmpeg.
+
+## [0.1.0] — 2026-04-23
+
+Initial public release.
+
+- Generated transport (`Configuration`, `JobsApi`, `UploadsApi`,
+  `WebhooksApi`, `DownloadsApi`, `HealthApi`) from the SOPHON OpenAPI
+  spec.
+- Hand-written helpers spliced on top of the generated client:
+  - `uploadFile` — chunked, concurrent, resumable upload with progress
+    reporting and bounded retry.
+  - `waitForJob` — typed terminal-state polling with backoff and
+    timeout.
+  - `verifyWebhookSignature` — constant-time HMAC-SHA256 verification
+    with a default replay window. Uses Web Crypto so it runs on Node
+    18+ and modern browsers.
+- Provenance signed via npm sigstore on every publish.
+
+[0.1.4]: https://github.com/Liqhtworks/sophon-sdk-typescript/releases/tag/v0.1.4
+[0.1.3]: https://github.com/Liqhtworks/sophon-sdk-typescript/releases/tag/v0.1.3
+[0.1.2]: https://github.com/Liqhtworks/sophon-sdk-typescript/releases/tag/v0.1.2
+[0.1.0]: https://github.com/Liqhtworks/sophon-sdk-typescript/releases/tag/v0.1.0

package/README.md

@@ -14,42 +14,110 @@ npm install @liqhtworks/sophon-sdk
 Requires Node 18+ or a runtime with `fetch`, `Blob`, `AbortController`, and Web
 Crypto.
 
+## Get an API key
+
+1. Sign in at <https://liqhtworks.xyz/account/general>.
+2. In **API keys**, create a key for your server-side integration.
+3. Copy the `xt_live_...` token when it is shown. It is only shown once.
+4. Store it as an environment variable:
+
+```bash
+export SOPHON_API_KEY=xt_live_...
+export SOPHON_BASE_URL=https://api.liqhtworks.xyz
+```
+
+Keep API keys on the server. Do not ship them in browser bundles, mobile apps,
+public repos, logs, or analytics events.
+
 ## Quick Start
 
+This is the smallest complete server-side flow: upload a local video, create an
+encode job, wait for completion, and download the MP4 output.
+
 ```ts
 import {
   Configuration,
+  JobProfile,
+  JobSource,
+  JobStatus,
+  JobsApi,
   UploadsApi,
   uploadFile,
+  waitForJob,
 } from "@liqhtworks/sophon-sdk";
 import { Blob } from "node:buffer";
-import { readFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { readFile, writeFile } from "node:fs/promises";
+import { basename } from "node:path";
+
+const inputPath = process.argv[2] ?? "./source.mov";
+const apiKey = process.env.SOPHON_API_KEY;
+if (!apiKey) throw new Error("SOPHON_API_KEY is required");
 
+const basePath = process.env.SOPHON_BASE_URL ?? "https://api.liqhtworks.xyz";
 const config = new Configuration({
-  basePath: process.env.SOPHON_BASE_URL ?? "https://api.liqhtworks.xyz",
-  accessToken: process.env.SOPHON_API_KEY,
+  basePath,
+  accessToken: apiKey,
 });
 
 const uploads = new UploadsApi(config);
+const jobs = new JobsApi(config);
 
-const bytes = await readFile("./source.mov");
-const source = new Blob([bytes], { type: "video/quicktime" });
+const bytes = await readFile(inputPath);
+const mimeType = inputPath.endsWith(".mov") ? "video/quicktime" : "video/mp4";
+const source = new Blob([bytes], { type: mimeType });
 
 const upload = await uploadFile({
   api: uploads,
   source,
-  fileName: "source.mov",
-  mimeType: "video/quicktime",
+  fileName: basename(inputPath),
+  mimeType,
   concurrency: 4,
   onProgress: (p) => console.log(`${p.partsDone}/${p.partsTotal} parts`),
 });
 
-console.log(upload.uploadId);
+const job = await jobs.createJob({
+  idempotencyKey: randomUUID(),
+  createJobRequest: {
+    source: JobSource.upload(upload.uploadId),
+    profile: JobProfile.SOPHON_ESPRESSO,
+  },
+});
+
+const final = await waitForJob({
+  api: jobs,
+  jobId: job.id,
+  timeoutMs: 30 * 60 * 1000,
+});
+if (final.status !== JobStatus.COMPLETED) {
+  throw new Error(`job ended in ${final.status}`);
+}
+
+const redirect = await fetch(`${basePath}/v1/jobs/${final.id}/output`, {
+  headers: { authorization: `Bearer ${apiKey}` },
+  redirect: "manual",
+});
+const location = redirect.headers.get("location");
+if (!location) throw new Error("missing output redirect");
+
+const download = await fetch(new URL(location, basePath));
+await writeFile("sophon-output.mp4", Buffer.from(await download.arrayBuffer()));
+
+console.log(`wrote sophon-output.mp4 from ${final.id}`);
 ```
 
-For a standalone file-path upload recipe, see
+For a runnable copy of this flow, see
+[`examples/encode-file.mjs`](./examples/encode-file.mjs).
+
+For upload-only integration work, see
 [`examples/upload-node-path.mjs`](./examples/upload-node-path.mjs).
 
+### Profile choice
+
+Use `sophon-auto` for production unless you need deterministic encoder
+settings. The quickstart uses `sophon-espresso` because it is the fastest
+smoke-test profile and always produces a new encoded output.
+
 ## Webhooks
 
 Use `verifyWebhookSignature` with the raw request body before JSON parsing.
@@ -77,6 +145,22 @@ npm install
 npm run build
 ```
 
+## Versioning
+
+`@liqhtworks/sophon-sdk` follows [SemVer](https://semver.org/), with one
+pre-1.0 caveat: while we are at `v0.x`, **minor bumps may include
+breaking changes**. Pin a tilde range until 1.0:
+
+```bash
+npm install @liqhtworks/sophon-sdk@~0.1
+```
+
+Patch releases (`0.1.x`) are always backward-compatible — they ship bug
+fixes, helper-layer improvements, and additive types. Once we cut
+`v1.0.0`, regular SemVer applies and breaking changes only land on
+major bumps. See [`CHANGELOG.md`](./CHANGELOG.md) for the per-release
+log.
+
 ## License
 
 Proprietary. See [`LICENSE`](./LICENSE).

package/examples/encode-file.mjs

@@ -0,0 +1,70 @@
+import {
+  Configuration,
+  JobProfile,
+  JobSource,
+  JobStatus,
+  JobsApi,
+  UploadsApi,
+  uploadFile,
+  waitForJob,
+} from "@liqhtworks/sophon-sdk";
+import { Blob } from "node:buffer";
+import { randomUUID } from "node:crypto";
+import { readFile, writeFile } from "node:fs/promises";
+import { basename } from "node:path";
+
+const inputPath = process.argv[2];
+if (!inputPath) {
+  throw new Error("usage: node examples/encode-file.mjs /path/to/video.mov");
+}
+
+const apiKey = process.env.SOPHON_API_KEY;
+if (!apiKey) throw new Error("SOPHON_API_KEY is required");
+
+const basePath = process.env.SOPHON_BASE_URL ?? "https://api.liqhtworks.xyz";
+const config = new Configuration({ basePath, accessToken: apiKey });
+const uploads = new UploadsApi(config);
+const jobs = new JobsApi(config);
+
+const bytes = await readFile(inputPath);
+const mimeType = inputPath.endsWith(".mov") ? "video/quicktime" : "video/mp4";
+const upload = await uploadFile({
+  api: uploads,
+  source: new Blob([bytes], { type: mimeType }),
+  fileName: basename(inputPath),
+  mimeType,
+  concurrency: 4,
+  onProgress: (p) => console.log(`upload ${p.partsDone}/${p.partsTotal}`),
+});
+
+const job = await jobs.createJob({
+  idempotencyKey: randomUUID(),
+  createJobRequest: {
+    source: JobSource.upload(upload.uploadId),
+    profile: JobProfile.SOPHON_ESPRESSO,
+  },
+});
+console.log(`created ${job.id}`);
+
+const final = await waitForJob({
+  api: jobs,
+  jobId: job.id,
+  timeoutMs: 30 * 60 * 1000,
+  onProgress: (j) => console.log(`job ${j.id}: ${j.status}`),
+});
+if (final.status !== JobStatus.COMPLETED) {
+  throw new Error(`job ended in ${final.status}`);
+}
+
+const redirect = await fetch(`${basePath}/v1/jobs/${final.id}/output`, {
+  headers: { authorization: `Bearer ${apiKey}` },
+  redirect: "manual",
+});
+const location = redirect.headers.get("location");
+if (!location) throw new Error("missing output redirect");
+
+const download = await fetch(new URL(location, basePath));
+if (!download.ok) throw new Error(`download failed: ${download.status}`);
+
+await writeFile("sophon-output.mp4", Buffer.from(await download.arrayBuffer()));
+console.log("wrote sophon-output.mp4");

package/examples/upload-node-path.mjs

@@ -0,0 +1,32 @@
+import {
+  Configuration,
+  UploadsApi,
+  uploadFile,
+} from "@liqhtworks/sophon-sdk";
+import { Blob } from "node:buffer";
+import { basename } from "node:path";
+import { readFile } from "node:fs/promises";
+
+const path = process.argv[2];
+if (!path) {
+  throw new Error("usage: node examples/upload-node-path.mjs /path/to/video.mov");
+}
+
+const config = new Configuration({
+  basePath: process.env.SOPHON_BASE_URL ?? "https://api.liqhtworks.xyz",
+  accessToken: process.env.SOPHON_API_KEY,
+});
+
+const bytes = await readFile(path);
+const source = new Blob([bytes], { type: "video/quicktime" });
+const uploads = new UploadsApi(config);
+
+const upload = await uploadFile({
+  api: uploads,
+  source,
+  fileName: basename(path),
+  mimeType: "video/quicktime",
+  concurrency: 4,
+});
+
+console.log(upload.uploadId);

package/examples/webhook-server/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "sophon-webhook-server-example",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "node src/server.mjs",
+    "check": "node --check src/server.mjs"
+  },
+  "dependencies": {
+    "@liqhtworks/sophon-sdk": "latest",
+    "express": "^4.19.2"
+  }
+}

package/examples/webhook-server/src/server.mjs

@@ -0,0 +1,51 @@
+import express from "express";
+import {
+  WebhookSignatureError,
+  verifyWebhookSignature,
+} from "@liqhtworks/sophon-sdk";
+
+const secret = process.env.SOPHON_WEBHOOK_SECRET;
+if (!secret) {
+  throw new Error("SOPHON_WEBHOOK_SECRET is required");
+}
+
+const app = express();
+
+app.post(
+  "/webhooks/sophon",
+  express.raw({ type: "application/json", limit: "2mb" }),
+  async (req, res) => {
+    if (!Buffer.isBuffer(req.body)) {
+      res.status(400).send("raw body required");
+      return;
+    }
+
+    try {
+      await verifyWebhookSignature({
+        rawBody: req.body,
+        signatureHeader: req.get("X-Turbo-Signature-256"),
+        timestampHeader: req.get("X-Turbo-Timestamp"),
+        secret,
+      });
+    } catch (err) {
+      if (err instanceof WebhookSignatureError) {
+        console.warn("rejected SOPHON webhook", { reason: err.reason });
+      }
+      res.status(401).send("invalid signature");
+      return;
+    }
+
+    const event = JSON.parse(req.body.toString("utf8"));
+    console.log("accepted SOPHON webhook", {
+      type: event.type,
+      id: event.id,
+    });
+
+    res.sendStatus(204);
+  },
+);
+
+const port = Number(process.env.PORT ?? 3000);
+app.listen(port, () => {
+  console.log(`listening on :${port}`);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liqhtworks/sophon-sdk",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "OpenAPI client for @liqhtworks/sophon-sdk",
   "author": "OpenAPI-Generator",
   "repository": {