@liqhtworks/sophon-sdk 0.1.2 → 0.1.4

package/.github/workflows/open-generated-pr.yml

@@ -0,0 +1,63 @@
+name: Open Generated SDK PR
+
+# The sophon-api Sync SDK Update PRs workflow pushes generated branches into
+# this repo. This workflow uses the repo-local GITHUB_TOKEN to open or update
+# the PR, so the cross-repo token only needs contents:write.
+
+on:
+  push:
+    branches:
+      - "generated/sophon-api-*"
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  open:
+    name: Open or update PR
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Open or update generated SDK PR
+        env:
+          GH_TOKEN: ${{ github.token }}
+          BRANCH: ${{ github.ref_name }}
+        shell: bash
+        run: |
+          set -euo pipefail
+
+          title="$(git log -1 --format=%s)"
+          body="$(git log -1 --format=%B | sed '1d')"
+          if [ -z "${body}" ]; then
+            body="Generated SDK update from sophon-api."
+          fi
+
+          existing="$(
+            gh api --method GET "repos/${GITHUB_REPOSITORY}/pulls" \
+              -f state=open \
+              -f head="${GITHUB_REPOSITORY_OWNER}:${BRANCH}" \
+              -f base=main \
+              --jq '.[0].number // empty'
+          )"
+
+          body_file="$(mktemp)"
+          printf '%s\n' "${body}" > "${body_file}"
+
+          if [ -n "${existing}" ]; then
+            gh pr edit "${existing}" \
+              --repo "${GITHUB_REPOSITORY}" \
+              --title "${title}" \
+              --body-file "${body_file}"
+            echo "Updated PR #${existing}"
+          else
+            gh pr create \
+              --repo "${GITHUB_REPOSITORY}" \
+              --base main \
+              --head "${BRANCH}" \
+              --title "${title}" \
+              --body-file "${body_file}"
+          fi

package/.github/workflows/publish.yml

@@ -1,13 +1,15 @@
-name: Publish to npm
+name: TypeScript SDK CI
 
-# Fires when the sophon-api "Publish SDKs" workflow pushes a v<version> tag
-# into this repo. The tag commit already contains the fully-generated SDK;
-# this workflow installs, builds, and publishes to npm.
+# PRs and main pushes validate the generated package natively in the SDK repo.
+# v<version> tags additionally publish the already-generated SDK to npm.
 
 on:
   push:
+    branches:
+      - main
     tags:
       - "v*"
+  pull_request:
   workflow_dispatch:
     inputs:
       tag:
@@ -19,8 +21,33 @@ permissions:
   id-token: write
 
 jobs:
+  validate:
+    name: install + build + pack
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout package
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.inputs.tag || github.ref }}
+          fetch-depth: 1
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Install + build
+        run: |
+          if [ -f package-lock.json ]; then npm ci; else npm install; fi
+          npm run build
+
+      - name: Validate npm package contents
+        run: npm pack --dry-run
+
   publish:
     name: npm publish
+    needs: validate
+    if: startsWith(github.ref, 'refs/tags/v') || (github.event_name == 'workflow_dispatch' && github.event.inputs.tag != '')
     runs-on: ubuntu-latest
     steps:
       - name: Checkout tag
@@ -43,15 +70,11 @@ jobs:
       - name: Verify tag matches package.json
         shell: bash
         env:
-          # `GITHUB_REF_NAME` is the *dispatched* ref (often `main`), not the
-          # checked-out tag. Prefer the explicit workflow_dispatch input,
-          # then fall back to GITHUB_REF_NAME for the tag-push trigger.
           INPUT_TAG: ${{ github.event.inputs.tag }}
         run: |
-          tag="${INPUT_TAG#v}"
-          if [ -z "${tag}" ]; then
-            tag="${GITHUB_REF_NAME#v}"
-          fi
+          tag="${INPUT_TAG:-${GITHUB_REF_NAME}}"
+          tag="${tag#refs/tags/}"
+          tag="${tag#v}"
           pkg="$(node -p "require('./package.json').version")"
           if [ "${tag}" != "${pkg}" ]; then
             echo "::error::tag v${tag} does not match package.json version ${pkg}" >&2
@@ -60,7 +83,7 @@ jobs:
 
       - name: Install + build
         run: |
-          npm ci || npm install
+          if [ -f package-lock.json ]; then npm ci; else npm install; fi
           npm run build
 
       - name: Publish

package/README.md

@@ -1,164 +1,82 @@
-# @liqhtworks/sophon-sdk@0.1.0
+# @liqhtworks/sophon-sdk
 
-A TypeScript SDK client for the api.liqhtworks.xyz API.
+Official TypeScript SDK for the SOPHON Encoding API.
 
-## Usage
+This repository is generated from `Liqhtworks/sophon-api`. The curated
+`README.md` and `examples/` directory are preserved across SDK regeneration.
 
-First, install the SDK from npm.
+## Install
 
 ```bash
-npm install @liqhtworks/sophon-sdk --save
+npm install @liqhtworks/sophon-sdk
 ```
 
-Next, try it out.
+Requires Node 18+ or a runtime with `fetch`, `Blob`, `AbortController`, and Web
+Crypto.
 
+## Quick Start
 
 ```ts
 import {
   Configuration,
-  DownloadsApi,
-} from '@liqhtworks/sophon-sdk';
-import type { DownloadRequest } from '@liqhtworks/sophon-sdk';
-
-async function example() {
-  console.log("🚀 Testing @liqhtworks/sophon-sdk SDK...");
-  const api = new DownloadsApi();
-
-  const body = {
-    // string | HMAC-signed download token encoding the object key and expiry.
-    token: token_example,
-  } satisfies DownloadRequest;
-
-  try {
-    const data = await api.download(body);
-    console.log(data);
-  } catch (error) {
-    console.error(error);
-  }
-}
-
-// Run the test
-example().catch(console.error);
+  UploadsApi,
+  uploadFile,
+} from "@liqhtworks/sophon-sdk";
+import { Blob } from "node:buffer";
+import { readFile } from "node:fs/promises";
+
+const config = new Configuration({
+  basePath: process.env.SOPHON_BASE_URL ?? "https://api.liqhtworks.xyz",
+  accessToken: process.env.SOPHON_API_KEY,
+});
+
+const uploads = new UploadsApi(config);
+
+const bytes = await readFile("./source.mov");
+const source = new Blob([bytes], { type: "video/quicktime" });
+
+const upload = await uploadFile({
+  api: uploads,
+  source,
+  fileName: "source.mov",
+  mimeType: "video/quicktime",
+  concurrency: 4,
+  onProgress: (p) => console.log(`${p.partsDone}/${p.partsTotal} parts`),
+});
+
+console.log(upload.uploadId);
 ```
 
+For a standalone file-path upload recipe, see
+[`examples/upload-node-path.mjs`](./examples/upload-node-path.mjs).
 
-## Documentation
-
-### API Endpoints
-
-All URIs are relative to *https://api.liqhtworks.xyz*
-
-| Class | Method | HTTP request | Description
-| ----- | ------ | ------------ | -------------
-*DownloadsApi* | [**download**](docs/DownloadsApi.md#download) | **GET** /v1/downloads/{token} | Download an output file via signed token
-*HealthApi* | [**healthz**](docs/HealthApi.md#healthz) | **GET** /healthz | Liveness probe
-*HealthApi* | [**readyz**](docs/HealthApi.md#readyz) | **GET** /readyz | Readiness probe
-*JobsApi* | [**cancelJob**](docs/JobsApi.md#canceljob) | **DELETE** /v1/jobs/{id} | Cancel a job
-*JobsApi* | [**createJob**](docs/JobsApi.md#createjoboperation) | **POST** /v1/jobs | Submit an encoding job
-*JobsApi* | [**getJob**](docs/JobsApi.md#getjob) | **GET** /v1/jobs/{id} | Get a single job by ID
-*JobsApi* | [**getJobOutput**](docs/JobsApi.md#getjoboutput) | **GET** /v1/jobs/{id}/output | Get the encoded output file
-*JobsApi* | [**listJobs**](docs/JobsApi.md#listjobs) | **GET** /v1/jobs | List jobs with cursor pagination
-*UploadsApi* | [**cancelUpload**](docs/UploadsApi.md#cancelupload) | **DELETE** /v1/uploads/{id} | Cancel an upload session
-*UploadsApi* | [**completeUpload**](docs/UploadsApi.md#completeupload) | **POST** /v1/uploads/{id}/complete | Finalize a chunked upload
-*UploadsApi* | [**createUpload**](docs/UploadsApi.md#createuploadoperation) | **POST** /v1/uploads | Initialize a chunked upload session
-*UploadsApi* | [**getUpload**](docs/UploadsApi.md#getupload) | **GET** /v1/uploads/{id} | Get upload session status
-*UploadsApi* | [**uploadPart**](docs/UploadsApi.md#uploadpart) | **PUT** /v1/uploads/{id}/parts/{part_number} | Upload a single chunk
-*WebhooksApi* | [**createWebhook**](docs/WebhooksApi.md#createwebhookoperation) | **POST** /v1/webhooks | Register a webhook endpoint
-*WebhooksApi* | [**deleteWebhook**](docs/WebhooksApi.md#deletewebhook) | **DELETE** /v1/webhooks/{id} | Soft-delete a webhook endpoint
-*WebhooksApi* | [**listWebhooks**](docs/WebhooksApi.md#listwebhooks) | **GET** /v1/webhooks | List active webhook endpoints
-
-
-### Models
-
-- [CompleteUploadResponse](docs/CompleteUploadResponse.md)
-- [CreateJobOutputOptions](docs/CreateJobOutputOptions.md)
-- [CreateJobRequest](docs/CreateJobRequest.md)
-- [CreateUploadRequest](docs/CreateUploadRequest.md)
-- [CreateUploadResponse](docs/CreateUploadResponse.md)
-- [CreateWebhookRequest](docs/CreateWebhookRequest.md)
-- [ErrorBody](docs/ErrorBody.md)
-- [ErrorEnvelope](docs/ErrorEnvelope.md)
-- [JobOutputInfo](docs/JobOutputInfo.md)
-- [JobProfile](docs/JobProfile.md)
-- [JobProgress](docs/JobProgress.md)
-- [JobResponse](docs/JobResponse.md)
-- [JobSourceInfo](docs/JobSourceInfo.md)
-- [JobSourceType](docs/JobSourceType.md)
-- [JobStatus](docs/JobStatus.md)
-- [ListJobsResponse](docs/ListJobsResponse.md)
-- [OutputContainer](docs/OutputContainer.md)
-- [ReadyResponse](docs/ReadyResponse.md)
-- [UploadJobSource](docs/UploadJobSource.md)
-- [UploadPartResponse](docs/UploadPartResponse.md)
-- [UploadStatusResponse](docs/UploadStatusResponse.md)
-- [WebhookDeliveryPayload](docs/WebhookDeliveryPayload.md)
-- [WebhookListItem](docs/WebhookListItem.md)
-- [WebhookListResponse](docs/WebhookListResponse.md)
-- [WebhookResponse](docs/WebhookResponse.md)
-
-### Authorization
-
-
-Authentication schemes defined for the API:
-<a id="bearerApiKey"></a>
-#### bearerApiKey
-
-
-- **Type**: HTTP Bearer Token authentication
-<a id="sessionCookie"></a>
-#### sessionCookie
-
-
-- **Type**: API key
-- **API key parameter name**: `sophon_api_session`
-- **Location**: 
-
-## About
-
-This TypeScript SDK client supports the [Fetch API](https://fetch.spec.whatwg.org/)
-and is automatically generated by the
-[OpenAPI Generator](https://openapi-generator.tech) project:
-
-- API version: `1.0.0`
-- Package version: `0.1.0`
-- Generator version: `7.21.0`
-- Build package: `org.openapitools.codegen.languages.TypeScriptFetchClientCodegen`
-
-The generated npm module supports the following:
-
-- Environments
-  * Node.js
-  * Webpack
-  * Browserify
-- Language levels
-  * ES5 - you must have a Promises/A+ library installed
-  * ES6
-- Module systems
-  * CommonJS
-  * ES6 module system
-
-For more information, please visit [https://liqhtworks.xyz](https://liqhtworks.xyz)
+## Webhooks
 
-## Development
+Use `verifyWebhookSignature` with the raw request body before JSON parsing.
 
-### Building
+See [`examples/webhook-server`](./examples/webhook-server) for an Express
+handler that preserves the raw body, verifies `X-Turbo-Signature-256`, and only
+then parses JSON.
 
-To build the TypeScript source code, you need to have Node.js and npm installed.
-After cloning the repository, navigate to the project directory and run:
+## Helpers
 
-```bash
-npm install
-npm run build
-```
+| Helper | Purpose |
+|---|---|
+| `uploadFile` | Chunked upload orchestration with bounded concurrency, retries, resume, and progress callbacks. |
+| `waitForJob` | Poll until terminal status with timeout and typed errors. |
+| `verifyWebhookSignature` | Constant-time HMAC verification plus replay-window enforcement. |
 
-### Publishing
+## API Docs
 
-Once you've built the package, you can publish it to npm:
+Generated endpoint/model docs live under [`docs/`](./docs).
+
+## Development
 
 ```bash
-npm publish
+npm install
+npm run build
 ```
 
 ## License
 
-[Proprietary]()
+Proprietary. See [`LICENSE`](./LICENSE).

package/dist/esm/helpers/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./uploads";
 export * from "./jobs";
+export * from "./sources";
 export * from "./webhooks";

package/dist/esm/helpers/index.js

@@ -1,3 +1,4 @@
 export * from "./uploads";
 export * from "./jobs";
+export * from "./sources";
 export * from "./webhooks";

package/dist/esm/helpers/sources.d.ts

@@ -0,0 +1,8 @@
+export interface UploadJobSourceLike {
+    type: any;
+    upload_id: string;
+}
+export declare function uploadJobSource(uploadId: string): UploadJobSourceLike;
+export declare const JobSource: Readonly<{
+    upload: typeof uploadJobSource;
+}>;

package/dist/esm/helpers/sources.js

@@ -0,0 +1,6 @@
+export function uploadJobSource(uploadId) {
+    return { type: "upload", upload_id: uploadId };
+}
+export const JobSource = Object.freeze({
+    upload: uploadJobSource,
+});

package/dist/esm/helpers/uploads.d.ts

@@ -10,7 +10,6 @@ export interface UploadsApiLike {
         id: string;
         chunk_size: number;
         total_chunks: number;
-        expires_at: string;
     }>;
     uploadPart(params: {
         id: string;
@@ -25,7 +24,6 @@ export interface UploadsApiLike {
         idempotencyKey: string;
     }): Promise<{
         id: string;
-        status: string;
         sha256: string;
         bytes: number;
     }>;
@@ -33,7 +31,6 @@ export interface UploadsApiLike {
         id: string;
     }): Promise<{
         id: string;
-        status: string;
         total_chunks: number;
         received_chunks: number[];
     }>;

package/dist/helpers/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./uploads";
 export * from "./jobs";
+export * from "./sources";
 export * from "./webhooks";

package/dist/helpers/index.js

@@ -16,4 +16,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./uploads"), exports);
 __exportStar(require("./jobs"), exports);
+__exportStar(require("./sources"), exports);
 __exportStar(require("./webhooks"), exports);

package/dist/helpers/sources.d.ts

@@ -0,0 +1,8 @@
+export interface UploadJobSourceLike {
+    type: any;
+    upload_id: string;
+}
+export declare function uploadJobSource(uploadId: string): UploadJobSourceLike;
+export declare const JobSource: Readonly<{
+    upload: typeof uploadJobSource;
+}>;

package/dist/helpers/sources.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JobSource = void 0;
+exports.uploadJobSource = uploadJobSource;
+function uploadJobSource(uploadId) {
+    return { type: "upload", upload_id: uploadId };
+}
+exports.JobSource = Object.freeze({
+    upload: uploadJobSource,
+});

package/dist/helpers/uploads.d.ts

@@ -10,7 +10,6 @@ export interface UploadsApiLike {
         id: string;
         chunk_size: number;
         total_chunks: number;
-        expires_at: string;
     }>;
     uploadPart(params: {
         id: string;
@@ -25,7 +24,6 @@ export interface UploadsApiLike {
         idempotencyKey: string;
     }): Promise<{
         id: string;
-        status: string;
         sha256: string;
         bytes: number;
     }>;
@@ -33,7 +31,6 @@ export interface UploadsApiLike {
         id: string;
     }): Promise<{
         id: string;
-        status: string;
         total_chunks: number;
         received_chunks: number[];
     }>;

package/package.json

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

package/src/helpers/index.ts

@@ -1,3 +1,4 @@
 export * from "./uploads";
 export * from "./jobs";
+export * from "./sources";
 export * from "./webhooks";

package/src/helpers/sources.ts

@@ -0,0 +1,14 @@
+export interface UploadJobSourceLike {
+  // `any` keeps the helper assignable to the generated string enum type while
+  // still centralizing the only valid runtime discriminator value.
+  type: any;
+  upload_id: string;
+}
+
+export function uploadJobSource(uploadId: string): UploadJobSourceLike {
+  return { type: "upload", upload_id: uploadId };
+}
+
+export const JobSource = Object.freeze({
+  upload: uploadJobSource,
+});

package/src/helpers/uploads.ts

@@ -4,11 +4,15 @@
 // separate calls; this wrapper handles chunk slicing, bounded concurrency,
 // per-part retry, resume against existing sessions, and progress reporting.
 
+// Narrow structural type — only the fields the helper actually reads.
+// Keeping it tight lets the generated UploadsApi (which carries Date /
+// nullable / extra metadata fields) satisfy this interface without
+// explicit casts at the call site.
 export interface UploadsApiLike {
   createUpload(params: {
     createUploadRequest: { file_name: string; file_size: number; mime_type: string };
     idempotencyKey: string;
-  }): Promise<{ id: string; chunk_size: number; total_chunks: number; expires_at: string }>;
+  }): Promise<{ id: string; chunk_size: number; total_chunks: number }>;
 
   uploadPart(params: {
     id: string;
@@ -19,11 +23,10 @@ export interface UploadsApiLike {
   completeUpload(params: {
     id: string;
     idempotencyKey: string;
-  }): Promise<{ id: string; status: string; sha256: string; bytes: number }>;
+  }): Promise<{ id: string; sha256: string; bytes: number }>;
 
   getUpload(params: { id: string }): Promise<{
     id: string;
-    status: string;
     total_chunks: number;
     received_chunks: number[];
   }>;