@liqhtworks/sophon-sdk 0.1.0

package/src/helpers/webhooks.ts

@@ -0,0 +1,134 @@
+// Webhook signature verification for inbound terminal-job deliveries.
+//
+// SOPHON signs each delivery with HMAC-SHA256 over `"{timestamp}.{raw_body}"`
+// using the per-webhook secret. The hex digest is sent as
+// `X-Turbo-Signature-256: sha256=<hex>`.
+//
+// Isomorphic: uses the Web Crypto API (`crypto.subtle`), available globally in
+// Node 18+ and modern browsers. No Node-specific imports.
+//
+// Consumers call `verifyWebhookSignature` with the RAW request body (string or
+// Uint8Array — NOT a parsed JSON object), the signature header, the timestamp
+// header, and the webhook secret. The helper does a constant-time comparison
+// and enforces a replay window by default.
+
+export interface VerifyWebhookSignatureParams {
+  /** Raw HTTP body exactly as received, before any JSON parsing. */
+  rawBody: string | Uint8Array;
+  /** Value of `X-Turbo-Signature-256`, e.g. `"sha256=abc..."`. */
+  signatureHeader: string | null | undefined;
+  /** Value of `X-Turbo-Timestamp`. */
+  timestampHeader: string | null | undefined;
+  /** Webhook secret returned by `POST /v1/webhooks`. */
+  secret: string;
+  /** Maximum acceptable clock skew in ms. Default 5 min. Set 0 to disable. */
+  replayWindowMs?: number;
+  /** Override "now" for deterministic tests. */
+  now?: () => number;
+}
+
+export class WebhookSignatureError extends Error {
+  readonly reason:
+    | "missing_signature"
+    | "missing_timestamp"
+    | "invalid_timestamp"
+    | "replay_window_exceeded"
+    | "bad_prefix"
+    | "bad_signature_encoding"
+    | "signature_mismatch";
+  constructor(reason: WebhookSignatureError["reason"], message?: string) {
+    super(message ?? reason);
+    this.name = "WebhookSignatureError";
+    this.reason = reason;
+  }
+}
+
+/**
+ * Throws `WebhookSignatureError` if the delivery is not authentic. Returns
+ * a resolved promise on success.
+ */
+export async function verifyWebhookSignature(
+  params: VerifyWebhookSignatureParams,
+): Promise<void> {
+  const {
+    rawBody,
+    signatureHeader,
+    timestampHeader,
+    secret,
+    replayWindowMs = 5 * 60 * 1000,
+    now = Date.now,
+  } = params;
+
+  if (!signatureHeader) throw new WebhookSignatureError("missing_signature");
+  if (!timestampHeader) throw new WebhookSignatureError("missing_timestamp");
+
+  const deliveredTs = Date.parse(timestampHeader);
+  if (Number.isNaN(deliveredTs)) {
+    throw new WebhookSignatureError("invalid_timestamp");
+  }
+
+  if (replayWindowMs > 0) {
+    const drift = Math.abs(now() - deliveredTs);
+    if (drift > replayWindowMs) {
+      throw new WebhookSignatureError("replay_window_exceeded");
+    }
+  }
+
+  if (!signatureHeader.startsWith("sha256=")) {
+    throw new WebhookSignatureError("bad_prefix");
+  }
+  const deliveredHex = signatureHeader.slice("sha256=".length).trim();
+  const delivered = hexToBytes(deliveredHex);
+  if (!delivered) {
+    throw new WebhookSignatureError("bad_signature_encoding");
+  }
+
+  const bodyBytes =
+    typeof rawBody === "string" ? new TextEncoder().encode(rawBody) : rawBody;
+  const payload = concatBytes(
+    new TextEncoder().encode(`${timestampHeader}.`),
+    bodyBytes,
+  );
+
+  const key = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  const expected = new Uint8Array(
+    // TS 5.7+ tightened BufferSource to require ArrayBufferView<ArrayBuffer>;
+    // our concatenated Uint8Array is backed by an ArrayBuffer at runtime.
+    await crypto.subtle.sign("HMAC", key, payload as BufferSource),
+  );
+
+  if (!constantTimeEqual(delivered, expected)) {
+    throw new WebhookSignatureError("signature_mismatch");
+  }
+}
+
+function hexToBytes(hex: string): Uint8Array | null {
+  if (hex.length % 2 !== 0 || !/^[0-9a-fA-F]*$/.test(hex)) return null;
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < out.length; i++) {
+    out[i] = parseInt(hex.substr(i * 2, 2), 16);
+  }
+  return out;
+}
+
+function concatBytes(a: Uint8Array, b: Uint8Array): Uint8Array {
+  const out = new Uint8Array(a.length + b.length);
+  out.set(a, 0);
+  out.set(b, a.length);
+  return out;
+}
+
+function constantTimeEqual(a: Uint8Array, b: Uint8Array): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) {
+    diff |= (a[i] ?? 0) ^ (b[i] ?? 0);
+  }
+  return diff === 0;
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+/* tslint:disable */
+/* eslint-disable */
+export * from './runtime';
+export * from './apis/index';
+export * from './models/index';
+
+export * from './helpers/index';

package/src/models/CompleteUploadResponse.ts

@@ -0,0 +1,102 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * SOPHON Encoding API
+ * REST API for submitting, monitoring, and retrieving SOPHON encoding jobs.  Authentication is via Bearer API key or session cookie. All POST endpoints require an Idempotency-Key header. List endpoints use opaque cursor-based pagination. 
+ *
+ * The version of the OpenAPI document: 1.0.0
+ * 
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+
+import { mapValues } from '../runtime';
+/**
+ * 
+ * @export
+ * @interface CompleteUploadResponse
+ */
+export interface CompleteUploadResponse {
+    /**
+     * 
+     * @type {string}
+     * @memberof CompleteUploadResponse
+     */
+    id: string;
+    /**
+     * 
+     * @type {CompleteUploadResponseStatusEnum}
+     * @memberof CompleteUploadResponse
+     */
+    status: CompleteUploadResponseStatusEnum;
+    /**
+     * SHA-256 hex digest of the assembled file.
+     * @type {string}
+     * @memberof CompleteUploadResponse
+     */
+    sha256: string;
+    /**
+     * 
+     * @type {number}
+     * @memberof CompleteUploadResponse
+     */
+    bytes: number;
+}
+
+/**
+* @export
+* @enum {string}
+*/
+export enum CompleteUploadResponseStatusEnum {
+    COMPLETED = 'completed'
+}
+
+
+/**
+ * Check if a given object implements the CompleteUploadResponse interface.
+ */
+export function instanceOfCompleteUploadResponse(value: object): value is CompleteUploadResponse {
+    if (!('id' in value) || value['id'] === undefined) return false;
+    if (!('status' in value) || value['status'] === undefined) return false;
+    if (!('sha256' in value) || value['sha256'] === undefined) return false;
+    if (!('bytes' in value) || value['bytes'] === undefined) return false;
+    return true;
+}
+
+export function CompleteUploadResponseFromJSON(json: any): CompleteUploadResponse {
+    return CompleteUploadResponseFromJSONTyped(json, false);
+}
+
+export function CompleteUploadResponseFromJSONTyped(json: any, ignoreDiscriminator: boolean): CompleteUploadResponse {
+    if (json == null) {
+        return json;
+    }
+    return {
+        
+        'id': json['id'],
+        'status': json['status'],
+        'sha256': json['sha256'],
+        'bytes': json['bytes'],
+    };
+}
+
+export function CompleteUploadResponseToJSON(json: any): CompleteUploadResponse {
+    return CompleteUploadResponseToJSONTyped(json, false);
+}
+
+export function CompleteUploadResponseToJSONTyped(value?: CompleteUploadResponse | null, ignoreDiscriminator: boolean = false): any {
+    if (value == null) {
+        return value;
+    }
+
+    return {
+        
+        'id': value['id'],
+        'status': value['status'],
+        'sha256': value['sha256'],
+        'bytes': value['bytes'],
+    };
+}
+

package/src/models/CreateJobOutputOptions.ts

@@ -0,0 +1,101 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * SOPHON Encoding API
+ * REST API for submitting, monitoring, and retrieving SOPHON encoding jobs.  Authentication is via Bearer API key or session cookie. All POST endpoints require an Idempotency-Key header. List endpoints use opaque cursor-based pagination. 
+ *
+ * The version of the OpenAPI document: 1.0.0
+ * 
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+
+import { mapValues } from '../runtime';
+import type { OutputContainer } from './OutputContainer';
+import {
+    OutputContainerFromJSON,
+    OutputContainerFromJSONTyped,
+    OutputContainerToJSON,
+    OutputContainerToJSONTyped,
+} from './OutputContainer';
+
+/**
+ * Optional output shaping knobs for a new job.
+ * @export
+ * @interface CreateJobOutputOptions
+ */
+export interface CreateJobOutputOptions {
+    /**
+     * 
+     * @type {OutputContainer}
+     * @memberof CreateJobOutputOptions
+     */
+    container?: OutputContainer;
+    /**
+     * When true, audio is included in the output. MKV preserves
+     * source audio streams unchanged. MP4 preserves broadly compatible
+     * source audio codecs when possible, and may normalize
+     * incompatible codecs to AAC for playback compatibility.
+     * When false, the output is video only.
+     * 
+     * @type {boolean}
+     * @memberof CreateJobOutputOptions
+     */
+    audio?: boolean;
+    /**
+     * Target output height in pixels. When set, output is scaled down
+     * (aspect ratio preserved, width derived from source, both dims
+     * rounded to even). If absent or larger than source height, output
+     * uses source dimensions. Billing tier is determined by the actual
+     * encoded output, not by this requested value.
+     * 
+     * @type {number}
+     * @memberof CreateJobOutputOptions
+     */
+    target_height?: number;
+}
+
+
+
+/**
+ * Check if a given object implements the CreateJobOutputOptions interface.
+ */
+export function instanceOfCreateJobOutputOptions(value: object): value is CreateJobOutputOptions {
+    return true;
+}
+
+export function CreateJobOutputOptionsFromJSON(json: any): CreateJobOutputOptions {
+    return CreateJobOutputOptionsFromJSONTyped(json, false);
+}
+
+export function CreateJobOutputOptionsFromJSONTyped(json: any, ignoreDiscriminator: boolean): CreateJobOutputOptions {
+    if (json == null) {
+        return json;
+    }
+    return {
+        
+        'container': json['container'] == null ? undefined : OutputContainerFromJSON(json['container']),
+        'audio': json['audio'] == null ? undefined : json['audio'],
+        'target_height': json['target_height'] == null ? undefined : json['target_height'],
+    };
+}
+
+export function CreateJobOutputOptionsToJSON(json: any): CreateJobOutputOptions {
+    return CreateJobOutputOptionsToJSONTyped(json, false);
+}
+
+export function CreateJobOutputOptionsToJSONTyped(value?: CreateJobOutputOptions | null, ignoreDiscriminator: boolean = false): any {
+    if (value == null) {
+        return value;
+    }
+
+    return {
+        
+        'container': OutputContainerToJSON(value['container']),
+        'audio': value['audio'],
+        'target_height': value['target_height'],
+    };
+}
+

package/src/models/CreateJobRequest.ts

@@ -0,0 +1,123 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * SOPHON Encoding API
+ * REST API for submitting, monitoring, and retrieving SOPHON encoding jobs.  Authentication is via Bearer API key or session cookie. All POST endpoints require an Idempotency-Key header. List endpoints use opaque cursor-based pagination. 
+ *
+ * The version of the OpenAPI document: 1.0.0
+ * 
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+
+import { mapValues } from '../runtime';
+import type { CreateJobOutputOptions } from './CreateJobOutputOptions';
+import {
+    CreateJobOutputOptionsFromJSON,
+    CreateJobOutputOptionsFromJSONTyped,
+    CreateJobOutputOptionsToJSON,
+    CreateJobOutputOptionsToJSONTyped,
+} from './CreateJobOutputOptions';
+import type { JobProfile } from './JobProfile';
+import {
+    JobProfileFromJSON,
+    JobProfileFromJSONTyped,
+    JobProfileToJSON,
+    JobProfileToJSONTyped,
+} from './JobProfile';
+import type { UploadJobSource } from './UploadJobSource';
+import {
+    UploadJobSourceFromJSON,
+    UploadJobSourceFromJSONTyped,
+    UploadJobSourceToJSON,
+    UploadJobSourceToJSONTyped,
+} from './UploadJobSource';
+
+/**
+ * 
+ * @export
+ * @interface CreateJobRequest
+ */
+export interface CreateJobRequest {
+    /**
+     * 
+     * @type {UploadJobSource}
+     * @memberof CreateJobRequest
+     */
+    source: UploadJobSource;
+    /**
+     * 
+     * @type {JobProfile}
+     * @memberof CreateJobRequest
+     */
+    profile: JobProfile;
+    /**
+     * 
+     * @type {CreateJobOutputOptions}
+     * @memberof CreateJobRequest
+     */
+    output?: CreateJobOutputOptions;
+    /**
+     * IDs of registered webhook endpoints to notify on job state changes.
+     * @type {Array<string>}
+     * @memberof CreateJobRequest
+     */
+    webhook_ids?: Array<string>;
+    /**
+     * Arbitrary key-value metadata attached to the job. Max 16 KiB serialized.
+     * @type {{ [key: string]: any; }}
+     * @memberof CreateJobRequest
+     */
+    metadata?: { [key: string]: any; };
+}
+
+
+
+/**
+ * Check if a given object implements the CreateJobRequest interface.
+ */
+export function instanceOfCreateJobRequest(value: object): value is CreateJobRequest {
+    if (!('source' in value) || value['source'] === undefined) return false;
+    if (!('profile' in value) || value['profile'] === undefined) return false;
+    return true;
+}
+
+export function CreateJobRequestFromJSON(json: any): CreateJobRequest {
+    return CreateJobRequestFromJSONTyped(json, false);
+}
+
+export function CreateJobRequestFromJSONTyped(json: any, ignoreDiscriminator: boolean): CreateJobRequest {
+    if (json == null) {
+        return json;
+    }
+    return {
+        
+        'source': UploadJobSourceFromJSON(json['source']),
+        'profile': JobProfileFromJSON(json['profile']),
+        'output': json['output'] == null ? undefined : CreateJobOutputOptionsFromJSON(json['output']),
+        'webhook_ids': json['webhook_ids'] == null ? undefined : json['webhook_ids'],
+        'metadata': json['metadata'] == null ? undefined : json['metadata'],
+    };
+}
+
+export function CreateJobRequestToJSON(json: any): CreateJobRequest {
+    return CreateJobRequestToJSONTyped(json, false);
+}
+
+export function CreateJobRequestToJSONTyped(value?: CreateJobRequest | null, ignoreDiscriminator: boolean = false): any {
+    if (value == null) {
+        return value;
+    }
+
+    return {
+        
+        'source': UploadJobSourceToJSON(value['source']),
+        'profile': JobProfileToJSON(value['profile']),
+        'output': CreateJobOutputOptionsToJSON(value['output']),
+        'webhook_ids': value['webhook_ids'],
+        'metadata': value['metadata'],
+    };
+}
+

package/src/models/CreateUploadRequest.ts

@@ -0,0 +1,84 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * SOPHON Encoding API
+ * REST API for submitting, monitoring, and retrieving SOPHON encoding jobs.  Authentication is via Bearer API key or session cookie. All POST endpoints require an Idempotency-Key header. List endpoints use opaque cursor-based pagination. 
+ *
+ * The version of the OpenAPI document: 1.0.0
+ * 
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+
+import { mapValues } from '../runtime';
+/**
+ * 
+ * @export
+ * @interface CreateUploadRequest
+ */
+export interface CreateUploadRequest {
+    /**
+     * 
+     * @type {string}
+     * @memberof CreateUploadRequest
+     */
+    file_name: string;
+    /**
+     * Total file size in bytes.
+     * @type {number}
+     * @memberof CreateUploadRequest
+     */
+    file_size: number;
+    /**
+     * 
+     * @type {string}
+     * @memberof CreateUploadRequest
+     */
+    mime_type: string;
+}
+
+/**
+ * Check if a given object implements the CreateUploadRequest interface.
+ */
+export function instanceOfCreateUploadRequest(value: object): value is CreateUploadRequest {
+    if (!('file_name' in value) || value['file_name'] === undefined) return false;
+    if (!('file_size' in value) || value['file_size'] === undefined) return false;
+    if (!('mime_type' in value) || value['mime_type'] === undefined) return false;
+    return true;
+}
+
+export function CreateUploadRequestFromJSON(json: any): CreateUploadRequest {
+    return CreateUploadRequestFromJSONTyped(json, false);
+}
+
+export function CreateUploadRequestFromJSONTyped(json: any, ignoreDiscriminator: boolean): CreateUploadRequest {
+    if (json == null) {
+        return json;
+    }
+    return {
+        
+        'file_name': json['file_name'],
+        'file_size': json['file_size'],
+        'mime_type': json['mime_type'],
+    };
+}
+
+export function CreateUploadRequestToJSON(json: any): CreateUploadRequest {
+    return CreateUploadRequestToJSONTyped(json, false);
+}
+
+export function CreateUploadRequestToJSONTyped(value?: CreateUploadRequest | null, ignoreDiscriminator: boolean = false): any {
+    if (value == null) {
+        return value;
+    }
+
+    return {
+        
+        'file_name': value['file_name'],
+        'file_size': value['file_size'],
+        'mime_type': value['mime_type'],
+    };
+}
+

package/src/models/CreateUploadResponse.ts

@@ -0,0 +1,95 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * SOPHON Encoding API
+ * REST API for submitting, monitoring, and retrieving SOPHON encoding jobs.  Authentication is via Bearer API key or session cookie. All POST endpoints require an Idempotency-Key header. List endpoints use opaque cursor-based pagination. 
+ *
+ * The version of the OpenAPI document: 1.0.0
+ * 
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+
+import { mapValues } from '../runtime';
+/**
+ * 
+ * @export
+ * @interface CreateUploadResponse
+ */
+export interface CreateUploadResponse {
+    /**
+     * 
+     * @type {string}
+     * @memberof CreateUploadResponse
+     */
+    id: string;
+    /**
+     * Size of each chunk in bytes. Tiered by file size:
+     * <64 MB = whole file, <=1 GB = 8 MB, <=10 GB = 16 MB, >10 GB = 32 MB.
+     * 
+     * @type {number}
+     * @memberof CreateUploadResponse
+     */
+    chunk_size: number;
+    /**
+     * 
+     * @type {number}
+     * @memberof CreateUploadResponse
+     */
+    total_chunks: number;
+    /**
+     * Upload session expiry (24 hours from creation).
+     * @type {Date}
+     * @memberof CreateUploadResponse
+     */
+    expires_at: Date;
+}
+
+/**
+ * Check if a given object implements the CreateUploadResponse interface.
+ */
+export function instanceOfCreateUploadResponse(value: object): value is CreateUploadResponse {
+    if (!('id' in value) || value['id'] === undefined) return false;
+    if (!('chunk_size' in value) || value['chunk_size'] === undefined) return false;
+    if (!('total_chunks' in value) || value['total_chunks'] === undefined) return false;
+    if (!('expires_at' in value) || value['expires_at'] === undefined) return false;
+    return true;
+}
+
+export function CreateUploadResponseFromJSON(json: any): CreateUploadResponse {
+    return CreateUploadResponseFromJSONTyped(json, false);
+}
+
+export function CreateUploadResponseFromJSONTyped(json: any, ignoreDiscriminator: boolean): CreateUploadResponse {
+    if (json == null) {
+        return json;
+    }
+    return {
+        
+        'id': json['id'],
+        'chunk_size': json['chunk_size'],
+        'total_chunks': json['total_chunks'],
+        'expires_at': (new Date(json['expires_at'])),
+    };
+}
+
+export function CreateUploadResponseToJSON(json: any): CreateUploadResponse {
+    return CreateUploadResponseToJSONTyped(json, false);
+}
+
+export function CreateUploadResponseToJSONTyped(value?: CreateUploadResponse | null, ignoreDiscriminator: boolean = false): any {
+    if (value == null) {
+        return value;
+    }
+
+    return {
+        
+        'id': value['id'],
+        'chunk_size': value['chunk_size'],
+        'total_chunks': value['total_chunks'],
+        'expires_at': value['expires_at'].toISOString(),
+    };
+}
+