@liqhtworks/sophon-sdk 0.1.0

package/src/apis/WebhooksApi.ts

@@ -0,0 +1,298 @@
+/* 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 * as runtime from '../runtime';
+import type {
+  CreateWebhookRequest,
+  ErrorEnvelope,
+  WebhookListResponse,
+  WebhookResponse,
+} from '../models/index';
+import {
+    CreateWebhookRequestFromJSON,
+    CreateWebhookRequestToJSON,
+    ErrorEnvelopeFromJSON,
+    ErrorEnvelopeToJSON,
+    WebhookListResponseFromJSON,
+    WebhookListResponseToJSON,
+    WebhookResponseFromJSON,
+    WebhookResponseToJSON,
+} from '../models/index';
+
+export interface CreateWebhookOperationRequest {
+    idempotencyKey: string;
+    createWebhookRequest: CreateWebhookRequest;
+}
+
+export interface DeleteWebhookRequest {
+    id: string;
+}
+
+/**
+ * WebhooksApi - interface
+ * 
+ * @export
+ * @interface WebhooksApiInterface
+ */
+export interface WebhooksApiInterface {
+    /**
+     * Creates request options for createWebhook without sending the request
+     * @param {string} idempotencyKey Client-generated UUID or string for exactly-once semantics. Required on all POST endpoints. Replaying the same key with the same request body returns the original response without side effects. 
+     * @param {CreateWebhookRequest} createWebhookRequest 
+     * @throws {RequiredError}
+     * @memberof WebhooksApiInterface
+     */
+    createWebhookRequestOpts(requestParameters: CreateWebhookOperationRequest): Promise<runtime.RequestOpts>;
+
+    /**
+     * Registers an HTTPS endpoint for terminal job events and returns the HMAC signing secret once at creation time. 
+     * @summary Register a webhook endpoint
+     * @param {string} idempotencyKey Client-generated UUID or string for exactly-once semantics. Required on all POST endpoints. Replaying the same key with the same request body returns the original response without side effects. 
+     * @param {CreateWebhookRequest} createWebhookRequest 
+     * @param {*} [options] Override http request option.
+     * @throws {RequiredError}
+     * @memberof WebhooksApiInterface
+     */
+    createWebhookRaw(requestParameters: CreateWebhookOperationRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<WebhookResponse>>;
+
+    /**
+     * Registers an HTTPS endpoint for terminal job events and returns the HMAC signing secret once at creation time. 
+     * Register a webhook endpoint
+     */
+    createWebhook(requestParameters: CreateWebhookOperationRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<WebhookResponse>;
+
+    /**
+     * Creates request options for deleteWebhook without sending the request
+     * @param {string} id 
+     * @throws {RequiredError}
+     * @memberof WebhooksApiInterface
+     */
+    deleteWebhookRequestOpts(requestParameters: DeleteWebhookRequest): Promise<runtime.RequestOpts>;
+
+    /**
+     * Sets the webhook to inactive. It will no longer receive deliveries.
+     * @summary Soft-delete a webhook endpoint
+     * @param {string} id 
+     * @param {*} [options] Override http request option.
+     * @throws {RequiredError}
+     * @memberof WebhooksApiInterface
+     */
+    deleteWebhookRaw(requestParameters: DeleteWebhookRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<void>>;
+
+    /**
+     * Sets the webhook to inactive. It will no longer receive deliveries.
+     * Soft-delete a webhook endpoint
+     */
+    deleteWebhook(requestParameters: DeleteWebhookRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<void>;
+
+    /**
+     * Creates request options for listWebhooks without sending the request
+     * @throws {RequiredError}
+     * @memberof WebhooksApiInterface
+     */
+    listWebhooksRequestOpts(): Promise<runtime.RequestOpts>;
+
+    /**
+     * Lists active webhook endpoints for the authenticated organization. 
+     * @summary List active webhook endpoints
+     * @param {*} [options] Override http request option.
+     * @throws {RequiredError}
+     * @memberof WebhooksApiInterface
+     */
+    listWebhooksRaw(initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<WebhookListResponse>>;
+
+    /**
+     * Lists active webhook endpoints for the authenticated organization. 
+     * List active webhook endpoints
+     */
+    listWebhooks(initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<WebhookListResponse>;
+
+}
+
+/**
+ * 
+ */
+export class WebhooksApi extends runtime.BaseAPI implements WebhooksApiInterface {
+
+    /**
+     * Creates request options for createWebhook without sending the request
+     */
+    async createWebhookRequestOpts(requestParameters: CreateWebhookOperationRequest): Promise<runtime.RequestOpts> {
+        if (requestParameters['idempotencyKey'] == null) {
+            throw new runtime.RequiredError(
+                'idempotencyKey',
+                'Required parameter "idempotencyKey" was null or undefined when calling createWebhook().'
+            );
+        }
+
+        if (requestParameters['createWebhookRequest'] == null) {
+            throw new runtime.RequiredError(
+                'createWebhookRequest',
+                'Required parameter "createWebhookRequest" was null or undefined when calling createWebhook().'
+            );
+        }
+
+        const queryParameters: any = {};
+
+        const headerParameters: runtime.HTTPHeaders = {};
+
+        headerParameters['Content-Type'] = 'application/json';
+
+        if (requestParameters['idempotencyKey'] != null) {
+            headerParameters['Idempotency-Key'] = String(requestParameters['idempotencyKey']);
+        }
+
+        if (this.configuration && this.configuration.accessToken) {
+            const token = this.configuration.accessToken;
+            const tokenString = await token("bearerApiKey", []);
+
+            if (tokenString) {
+                headerParameters["Authorization"] = `Bearer ${tokenString}`;
+            }
+        }
+
+        let urlPath = `/v1/webhooks`;
+
+        return {
+            path: urlPath,
+            method: 'POST',
+            headers: headerParameters,
+            query: queryParameters,
+            body: CreateWebhookRequestToJSON(requestParameters['createWebhookRequest']),
+        };
+    }
+
+    /**
+     * Registers an HTTPS endpoint for terminal job events and returns the HMAC signing secret once at creation time. 
+     * Register a webhook endpoint
+     */
+    async createWebhookRaw(requestParameters: CreateWebhookOperationRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<WebhookResponse>> {
+        const requestOptions = await this.createWebhookRequestOpts(requestParameters);
+        const response = await this.request(requestOptions, initOverrides);
+
+        return new runtime.JSONApiResponse(response, (jsonValue) => WebhookResponseFromJSON(jsonValue));
+    }
+
+    /**
+     * Registers an HTTPS endpoint for terminal job events and returns the HMAC signing secret once at creation time. 
+     * Register a webhook endpoint
+     */
+    async createWebhook(requestParameters: CreateWebhookOperationRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<WebhookResponse> {
+        const response = await this.createWebhookRaw(requestParameters, initOverrides);
+        return await response.value();
+    }
+
+    /**
+     * Creates request options for deleteWebhook without sending the request
+     */
+    async deleteWebhookRequestOpts(requestParameters: DeleteWebhookRequest): Promise<runtime.RequestOpts> {
+        if (requestParameters['id'] == null) {
+            throw new runtime.RequiredError(
+                'id',
+                'Required parameter "id" was null or undefined when calling deleteWebhook().'
+            );
+        }
+
+        const queryParameters: any = {};
+
+        const headerParameters: runtime.HTTPHeaders = {};
+
+        if (this.configuration && this.configuration.accessToken) {
+            const token = this.configuration.accessToken;
+            const tokenString = await token("bearerApiKey", []);
+
+            if (tokenString) {
+                headerParameters["Authorization"] = `Bearer ${tokenString}`;
+            }
+        }
+
+        let urlPath = `/v1/webhooks/{id}`;
+        urlPath = urlPath.replace(`{${"id"}}`, encodeURIComponent(String(requestParameters['id'])));
+
+        return {
+            path: urlPath,
+            method: 'DELETE',
+            headers: headerParameters,
+            query: queryParameters,
+        };
+    }
+
+    /**
+     * Sets the webhook to inactive. It will no longer receive deliveries.
+     * Soft-delete a webhook endpoint
+     */
+    async deleteWebhookRaw(requestParameters: DeleteWebhookRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<void>> {
+        const requestOptions = await this.deleteWebhookRequestOpts(requestParameters);
+        const response = await this.request(requestOptions, initOverrides);
+
+        return new runtime.VoidApiResponse(response);
+    }
+
+    /**
+     * Sets the webhook to inactive. It will no longer receive deliveries.
+     * Soft-delete a webhook endpoint
+     */
+    async deleteWebhook(requestParameters: DeleteWebhookRequest, initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<void> {
+        await this.deleteWebhookRaw(requestParameters, initOverrides);
+    }
+
+    /**
+     * Creates request options for listWebhooks without sending the request
+     */
+    async listWebhooksRequestOpts(): Promise<runtime.RequestOpts> {
+        const queryParameters: any = {};
+
+        const headerParameters: runtime.HTTPHeaders = {};
+
+        if (this.configuration && this.configuration.accessToken) {
+            const token = this.configuration.accessToken;
+            const tokenString = await token("bearerApiKey", []);
+
+            if (tokenString) {
+                headerParameters["Authorization"] = `Bearer ${tokenString}`;
+            }
+        }
+
+        let urlPath = `/v1/webhooks`;
+
+        return {
+            path: urlPath,
+            method: 'GET',
+            headers: headerParameters,
+            query: queryParameters,
+        };
+    }
+
+    /**
+     * Lists active webhook endpoints for the authenticated organization. 
+     * List active webhook endpoints
+     */
+    async listWebhooksRaw(initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<runtime.ApiResponse<WebhookListResponse>> {
+        const requestOptions = await this.listWebhooksRequestOpts();
+        const response = await this.request(requestOptions, initOverrides);
+
+        return new runtime.JSONApiResponse(response, (jsonValue) => WebhookListResponseFromJSON(jsonValue));
+    }
+
+    /**
+     * Lists active webhook endpoints for the authenticated organization. 
+     * List active webhook endpoints
+     */
+    async listWebhooks(initOverrides?: RequestInit | runtime.InitOverrideFunction): Promise<WebhookListResponse> {
+        const response = await this.listWebhooksRaw(initOverrides);
+        return await response.value();
+    }
+
+}

package/src/apis/index.ts

@@ -0,0 +1,7 @@
+/* tslint:disable */
+/* eslint-disable */
+export * from './DownloadsApi';
+export * from './HealthApi';
+export * from './JobsApi';
+export * from './UploadsApi';
+export * from './WebhooksApi';

package/src/helpers/index.ts

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

package/src/helpers/jobs.ts

@@ -0,0 +1,112 @@
+// Polling helper that resolves when a job hits a terminal state.
+
+export type JobTerminalStatus = "completed" | "failed" | "canceled";
+export type JobStatusLike = JobTerminalStatus | "queued" | "probing" | "encoding" | "muxing" | "uploading_output";
+
+export interface JobLike {
+  id: string;
+  status: JobStatusLike;
+  error?: string | null;
+}
+
+export interface JobsApiLike {
+  getJob(params: { id: string }): Promise<JobLike>;
+}
+
+export interface WaitForJobParams<T extends JobLike = JobLike> {
+  api: { getJob: (p: { id: string }) => Promise<T> };
+  jobId: string;
+  /** Resolve only on these statuses. Default: the three terminal ones. */
+  until?: readonly JobStatusLike[];
+  /** Initial poll interval (ms). Default 1000. */
+  pollMinMs?: number;
+  /** Cap on poll interval (ms). Default 15000. */
+  pollMaxMs?: number;
+  /** Exponential backoff multiplier per poll. Default 1.5. */
+  pollBackoff?: number;
+  /** Abort and throw after this many ms. Default 3600000 (1h). */
+  timeoutMs?: number;
+  /** Called on every poll with the freshly fetched job. */
+  onProgress?: (job: T) => void;
+  signal?: AbortSignal;
+}
+
+export class JobTerminalError<T extends JobLike = JobLike> extends Error {
+  readonly job: T;
+  constructor(job: T) {
+    super(job.error ?? `job ${job.id} ended in status ${job.status}`);
+    this.name = "JobTerminalError";
+    this.job = job;
+  }
+}
+
+export class JobTimeoutError extends Error {
+  readonly jobId: string;
+  constructor(jobId: string, waitedMs: number) {
+    super(`job ${jobId} did not finish within ${waitedMs}ms`);
+    this.name = "JobTimeoutError";
+    this.jobId = jobId;
+  }
+}
+
+const DEFAULT_TERMINAL: readonly JobTerminalStatus[] = ["completed", "failed", "canceled"];
+
+/**
+ * Polls `getJob` until the job hits a terminal status (or the requested
+ * `until` list), then returns the final job. Throws `JobTerminalError` on
+ * `failed` / `canceled` unless those are explicitly requested in `until`.
+ * Throws `JobTimeoutError` if the timeout elapses.
+ */
+export async function waitForJob<T extends JobLike = JobLike>(
+  params: WaitForJobParams<T>,
+): Promise<T> {
+  const {
+    api,
+    jobId,
+    until = DEFAULT_TERMINAL,
+    pollMinMs = 1000,
+    pollMaxMs = 15000,
+    pollBackoff = 1.5,
+    timeoutMs = 60 * 60 * 1000,
+    onProgress,
+    signal,
+  } = params;
+
+  const start = Date.now();
+  let interval = pollMinMs;
+
+  while (true) {
+    if (signal?.aborted) throw new DOMException("Aborted", "AbortError");
+    if (Date.now() - start > timeoutMs) throw new JobTimeoutError(jobId, Date.now() - start);
+
+    const job = await api.getJob({ id: jobId });
+    onProgress?.(job);
+
+    if (until.some((s) => s === job.status)) {
+      // The caller opted into this status; only synthesize a JobTerminalError
+      // when they are waiting for the default-terminal set and we landed on a
+      // failed/canceled status.
+      if (until === DEFAULT_TERMINAL && (job.status === "failed" || job.status === "canceled")) {
+        throw new JobTerminalError(job);
+      }
+      return job;
+    }
+
+    await sleep(interval, signal);
+    interval = Math.min(Math.ceil(interval * pollBackoff), pollMaxMs);
+  }
+}
+
+function sleep(ms: number, signal: AbortSignal | undefined): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const t = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(t);
+      reject(new DOMException("Aborted", "AbortError"));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}

package/src/helpers/uploads.ts

@@ -0,0 +1,243 @@
+// Upload orchestration on top of the generated UploadsApi.
+//
+// The generated SDK exposes createUpload / uploadPart / completeUpload as
+// separate calls; this wrapper handles chunk slicing, bounded concurrency,
+// per-part retry, resume against existing sessions, and progress reporting.
+
+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 }>;
+
+  uploadPart(params: {
+    id: string;
+    partNumber: number;
+    body: Blob;
+  }): Promise<{ part_number: number; received: boolean }>;
+
+  completeUpload(params: {
+    id: string;
+    idempotencyKey: string;
+  }): Promise<{ id: string; status: string; sha256: string; bytes: number }>;
+
+  getUpload(params: { id: string }): Promise<{
+    id: string;
+    status: string;
+    total_chunks: number;
+    received_chunks: number[];
+  }>;
+}
+
+export interface UploadProgress {
+  bytesUploaded: number;
+  bytesTotal: number;
+  partsDone: number;
+  partsTotal: number;
+}
+
+export interface UploadFileParams {
+  api: UploadsApiLike;
+  source: Blob;
+  fileName: string;
+  mimeType: string;
+  /** Resume a prior session instead of creating a new one. */
+  uploadId?: string;
+  /** Parallel in-flight chunks. Default 4. */
+  concurrency?: number;
+  /** Retries per chunk before aborting. Default 3. */
+  retries?: number;
+  /** Base backoff in ms; doubles each attempt. Default 500. */
+  retryBaseMs?: number;
+  /** Idempotency key reused for createUpload + completeUpload. Auto-generated if omitted. */
+  idempotencyKey?: string;
+  onProgress?: (p: UploadProgress) => void;
+  /** Abort the whole upload. Chunks in flight will still settle. */
+  signal?: AbortSignal;
+}
+
+export interface UploadFileResult {
+  uploadId: string;
+  sha256: string;
+  bytes: number;
+}
+
+export async function uploadFile(params: UploadFileParams): Promise<UploadFileResult> {
+  const {
+    api,
+    source,
+    fileName,
+    mimeType,
+    uploadId: resumeId,
+    concurrency = 4,
+    retries = 3,
+    retryBaseMs = 500,
+    idempotencyKey = randomIdempotencyKey(),
+    onProgress,
+    signal,
+  } = params;
+
+  if (concurrency < 1) throw new RangeError("concurrency must be >= 1");
+  if (retries < 0) throw new RangeError("retries must be >= 0");
+
+  let uploadId: string;
+  let chunkSize: number;
+  let totalChunks: number;
+  let alreadyReceived = new Set<number>();
+
+  if (resumeId) {
+    const status = await api.getUpload({ id: resumeId });
+    uploadId = status.id;
+    totalChunks = status.total_chunks;
+    alreadyReceived = new Set(status.received_chunks);
+    // Derive chunk size from file size / totalChunks. Last chunk may be smaller;
+    // we only need the head size to slice, so use ceil.
+    chunkSize = Math.ceil(source.size / totalChunks);
+  } else {
+    const session = await api.createUpload({
+      createUploadRequest: {
+        file_name: fileName,
+        file_size: source.size,
+        mime_type: mimeType,
+      },
+      idempotencyKey,
+    });
+    uploadId = session.id;
+    chunkSize = session.chunk_size;
+    totalChunks = session.total_chunks;
+  }
+
+  const progress: UploadProgress = {
+    bytesUploaded: 0,
+    bytesTotal: source.size,
+    partsDone: 0,
+    partsTotal: totalChunks,
+  };
+
+  // Seed progress from any resumed parts so callers see accurate counts.
+  for (const part of alreadyReceived) {
+    progress.partsDone += 1;
+    progress.bytesUploaded += partBytes(source.size, chunkSize, totalChunks, part);
+  }
+  onProgress?.({ ...progress });
+
+  const pending: number[] = [];
+  for (let i = 0; i < totalChunks; i++) {
+    if (!alreadyReceived.has(i)) pending.push(i);
+  }
+
+  let nextIdx = 0;
+  const workers: Promise<void>[] = [];
+
+  for (let w = 0; w < Math.min(concurrency, pending.length); w++) {
+    workers.push(
+      (async () => {
+        while (true) {
+          if (signal?.aborted) throw new DOMException("Aborted", "AbortError");
+          const idx = nextIdx++;
+          if (idx >= pending.length) return;
+
+          const partNumber = pending[idx]!;
+          const start = partNumber * chunkSize;
+          const end = Math.min(start + chunkSize, source.size);
+          const chunk = source.slice(start, end, "application/octet-stream");
+
+          await withRetry(
+            () => api.uploadPart({ id: uploadId, partNumber, body: chunk }),
+            retries,
+            retryBaseMs,
+            signal,
+          );
+
+          progress.partsDone += 1;
+          progress.bytesUploaded += chunk.size;
+          onProgress?.({ ...progress });
+        }
+      })(),
+    );
+  }
+
+  await Promise.all(workers);
+
+  const done = await api.completeUpload({ id: uploadId, idempotencyKey });
+
+  return { uploadId: done.id, sha256: done.sha256, bytes: done.bytes };
+}
+
+function partBytes(total: number, chunkSize: number, totalChunks: number, part: number): number {
+  if (part < totalChunks - 1) return chunkSize;
+  return total - chunkSize * (totalChunks - 1);
+}
+
+async function withRetry<T>(
+  fn: () => Promise<T>,
+  retries: number,
+  baseMs: number,
+  signal: AbortSignal | undefined,
+): Promise<T> {
+  let attempt = 0;
+  // One initial try + `retries` follow-ups.
+  while (true) {
+    try {
+      return await fn();
+    } catch (err) {
+      if (signal?.aborted) throw err;
+      if (attempt >= retries || !isRetryable(err)) throw err;
+      const delay = baseMs * 2 ** attempt + Math.floor(Math.random() * baseMs);
+      await sleep(delay, signal);
+      attempt += 1;
+    }
+  }
+}
+
+function isRetryable(err: unknown): boolean {
+  if (err instanceof TypeError) return true; // network-level fetch errors
+  const maybeResponse = (err as { response?: { status?: number } }).response;
+  const status = maybeResponse?.status;
+  if (typeof status !== "number") return false;
+  return status === 408 || status === 429 || (status >= 500 && status < 600);
+}
+
+function sleep(ms: number, signal: AbortSignal | undefined): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const t = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(t);
+      reject(new DOMException("Aborted", "AbortError"));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+function randomIdempotencyKey(): string {
+  // Single capture of the global `crypto` object so the TS narrowing from
+  // one `in` check doesn't bleed into the next branch.
+  const c =
+    typeof crypto !== "undefined"
+      ? (crypto as unknown as {
+          randomUUID?: () => string;
+          getRandomValues?: (arr: Uint8Array) => Uint8Array;
+        })
+      : undefined;
+
+  if (c?.randomUUID) return c.randomUUID();
+
+  // Fallback for very old runtimes without crypto.randomUUID. Web Crypto's
+  // getRandomValues has been in Node since 15 and all evergreen browsers, so
+  // this almost never runs — but we avoid Math.random so idempotency keys
+  // stay uncorrelated across callers even on ancient targets.
+  if (c?.getRandomValues) {
+    const bytes = new Uint8Array(16);
+    c.getRandomValues(bytes);
+    let hex = "";
+    for (const b of bytes) hex += b.toString(16).padStart(2, "0");
+    return `idem_${hex}`;
+  }
+
+  throw new Error(
+    "crypto API unavailable; pass an explicit idempotencyKey to uploadFile",
+  );
+}