@giveitsmaller/sdk 0.1.0

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@giveitsmaller/sdk",
+  "version": "0.1.0",
+  "description": "Node.js SDK for the GISL (Give It Smaller) file compression and processing API",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "types": "./src/index.ts",
+  "files": [
+    "src/"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@giveitsmaller/contracts": "file:../../generated/typescript"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "typescript": "^5.7",
+    "vitest": "^3.1"
+  },
+  "scripts": {
+    "check": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/client.ts

@@ -0,0 +1,401 @@
+import { readFileSync, statSync } from 'node:fs';
+import { basename } from 'node:path';
+
+import {
+  UploadResponseFromJSON,
+  MultipartInitiateResponseFromJSON,
+  WorkflowCreateResponseFromJSON,
+  WorkflowStatusResponseFromJSON,
+  WorkflowDownloadResponseFromJSON,
+  MetadataResponseFromJSON,
+  OperationsSchemaResponseFromJSON,
+  RetryResponseFromJSON,
+  WorkflowStatus,
+} from '@giveitsmaller/contracts/openapi';
+
+import type {
+  UploadResponse,
+  MultipartInitiateResponse,
+  WorkflowCreateResponse,
+  WorkflowStatusResponse,
+  WorkflowDownloadResponse,
+  MetadataResponse,
+  OperationsSchemaResponse,
+  RetryResponse,
+} from '@giveitsmaller/contracts/openapi';
+
+import { GislApiError, GislError, GislTimeoutError, GislValidationError } from './errors.js';
+import { parseSseStream } from './sse.js';
+import type {
+  GislClientConfig,
+  GislSseEvent,
+  UploadOptions,
+  WaitOptions,
+  WorkflowCreatePayload,
+} from './types.js';
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_MULTIPART_THRESHOLD = 10 * 1024 * 1024; // 10 MB
+const DEFAULT_MULTIPART_CONCURRENCY = 4;
+const DEFAULT_POLL_INTERVAL_MS = 2_000;
+const DEFAULT_POLL_TIMEOUT_MS = 300_000; // 5 min
+
+const TERMINAL_STATUSES: ReadonlySet<string> = new Set([
+  WorkflowStatus.completed,
+  WorkflowStatus.failed,
+  WorkflowStatus.partially_failed,
+]);
+
+export class GislClient {
+  private readonly baseUrl: string;
+  private readonly headers: Record<string, string>;
+  private readonly timeoutMs: number;
+  private readonly multipartThreshold: number;
+  private readonly multipartConcurrency: number;
+
+  constructor(config: GislClientConfig) {
+    this.baseUrl = config.baseUrl.replace(/\/+$/, '');
+    this.timeoutMs = config.timeout ?? DEFAULT_TIMEOUT_MS;
+    this.multipartThreshold = config.multipartThreshold ?? DEFAULT_MULTIPART_THRESHOLD;
+    this.multipartConcurrency = config.multipartConcurrency ?? DEFAULT_MULTIPART_CONCURRENCY;
+
+    this.headers = { ...config.headers };
+    if (config.apiKey) {
+      this.headers['Authorization'] = `Bearer ${config.apiKey}`;
+    }
+  }
+
+  // -----------------------------------------------------------------------
+  // Internal HTTP
+  // -----------------------------------------------------------------------
+
+  private async request<T>(
+    method: string,
+    path: string,
+    opts: {
+      body?: BodyInit | Record<string, unknown>;
+      json?: boolean;
+      deserialize?: (raw: unknown) => T;
+      rawResponse?: boolean;
+    } = {},
+  ): Promise<T> {
+    const url = `${this.baseUrl}${path}`;
+    const headers: Record<string, string> = { ...this.headers };
+    let body: BodyInit | undefined;
+
+    if (opts.json !== false && opts.body && !(opts.body instanceof FormData)) {
+      headers['Content-Type'] = 'application/json';
+      body = JSON.stringify(opts.body);
+    } else {
+      body = opts.body as BodyInit | undefined;
+    }
+
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+
+    let response: Response;
+    try {
+      response = await fetch(url, {
+        method,
+        headers,
+        body,
+        signal: controller.signal,
+      });
+    } catch (err: unknown) {
+      if (err instanceof DOMException && err.name === 'AbortError') {
+        throw new GislTimeoutError(`Request to ${method} ${path} timed out after ${this.timeoutMs}ms`);
+      }
+      throw err;
+    } finally {
+      clearTimeout(timer);
+    }
+
+    if (opts.rawResponse) {
+      return response as unknown as T;
+    }
+
+    return this.handleResponse(response, path, opts.deserialize);
+  }
+
+  private async handleResponse<T>(
+    response: Response,
+    path: string,
+    deserialize?: (raw: unknown) => T,
+  ): Promise<T> {
+    const contentType = response.headers.get('content-type') ?? '';
+    if (!contentType.includes('application/json')) {
+      if (!response.ok) {
+        throw new GislApiError(response.status, `Non-JSON error from ${path}`);
+      }
+      return undefined as unknown as T;
+    }
+
+    const json = await response.json();
+
+    // Schema endpoint returns raw JSON (no envelope)
+    if (path === '/api/operations/schema') {
+      if (!response.ok) {
+        throw new GislApiError(response.status, json.error ?? 'Unknown error');
+      }
+      return deserialize ? deserialize(json) : (json as T);
+    }
+
+    // Standard envelope: { success, data } or { success, error, details }
+    if (!response.ok || json.success === false) {
+      if (json.details && Array.isArray(json.details)) {
+        throw new GislValidationError(response.status, json.error ?? 'Validation error', json.details);
+      }
+      throw new GislApiError(response.status, json.error ?? 'Unknown error');
+    }
+
+    const data = json.data ?? json;
+    return deserialize ? deserialize(data) : (data as T);
+  }
+
+  // -----------------------------------------------------------------------
+  // Upload
+  // -----------------------------------------------------------------------
+
+  /**
+   * Upload a file. Automatically uses multipart upload for files exceeding
+   * the configured threshold (default 10 MB).
+   *
+   * @param file  File path (string) or a Blob/File instance.
+   * @param options  Upload options including progress callback.
+   */
+  async uploadFile(
+    file: string | Blob,
+    options?: UploadOptions,
+  ): Promise<UploadResponse> {
+    let blob: Blob;
+    let fileName: string;
+    let fileSize: number;
+
+    if (typeof file === 'string') {
+      const stat = statSync(file);
+      fileSize = stat.size;
+      fileName = basename(file);
+      const content = readFileSync(file);
+      blob = new Blob([content]);
+    } else {
+      blob = file;
+      fileName = (file as File).name ?? 'upload';
+      fileSize = file.size;
+    }
+
+    if (fileSize > this.multipartThreshold) {
+      return this.multipartUpload(blob, fileName, fileSize, options);
+    }
+
+    return this.singleUpload(blob, fileName);
+  }
+
+  private async singleUpload(blob: Blob, fileName: string): Promise<UploadResponse> {
+    const form = new FormData();
+    form.append('file', blob, fileName);
+
+    return this.request('POST', '/api/uploads', {
+      body: form,
+      json: false,
+      deserialize: UploadResponseFromJSON,
+    });
+  }
+
+  private async multipartUpload(
+    blob: Blob,
+    fileName: string,
+    totalSize: number,
+    options?: UploadOptions,
+  ): Promise<UploadResponse> {
+    // Step 1: Initiate with first chunk
+    const firstChunkSize = Math.min(totalSize, this.multipartThreshold);
+    const firstChunk = blob.slice(0, firstChunkSize);
+
+    const initiateForm = new FormData();
+    initiateForm.append('chunk', firstChunk, fileName);
+    initiateForm.append('original_name', fileName);
+    initiateForm.append('total_size_bytes', totalSize.toString());
+
+    const initResponse = await this.request<MultipartInitiateResponse>(
+      'POST',
+      '/api/uploads/multipart/initiate',
+      {
+        body: initiateForm,
+        json: false,
+        deserialize: MultipartInitiateResponseFromJSON,
+      },
+    );
+
+    let uploadedBytes = firstChunkSize;
+    options?.onProgress?.(uploadedBytes, totalSize);
+
+    // Step 2: Upload remaining chunks to S3 presigned URLs
+    const etags: Array<{ part_number: number; etag: string }> = [];
+    const presignedUrls = initResponse.presignedUrls;
+    const chunkSize = initResponse.recommendedChunkSize;
+
+    const uploadChunk = async (index: number): Promise<void> => {
+      const part = presignedUrls[index];
+      const start = firstChunkSize + index * chunkSize;
+      const end = Math.min(start + chunkSize, totalSize);
+      const chunk = blob.slice(start, end);
+
+      const s3Response = await fetch(part.url, {
+        method: 'PUT',
+        body: chunk,
+        headers: { 'Content-Length': (end - start).toString() },
+      });
+
+      if (!s3Response.ok) {
+        throw new GislError(`S3 chunk upload failed for part ${part.partNumber}: ${s3Response.status}`);
+      }
+
+      const etag = s3Response.headers.get('etag');
+      if (!etag) {
+        throw new GislError(`S3 response missing ETag for part ${part.partNumber}`);
+      }
+
+      etags.push({ part_number: part.partNumber, etag });
+      uploadedBytes += end - start;
+      options?.onProgress?.(uploadedBytes, totalSize);
+    };
+
+    // Upload with concurrency limit
+    const queue = [...presignedUrls.keys()];
+    const workers = Array.from(
+      { length: Math.min(this.multipartConcurrency, queue.length) },
+      async () => {
+        while (queue.length > 0) {
+          const index = queue.shift()!;
+          await uploadChunk(index);
+        }
+      },
+    );
+    await Promise.all(workers);
+
+    // Step 3: Complete multipart upload
+    etags.sort((a, b) => a.part_number - b.part_number);
+
+    return this.request<UploadResponse>('POST', '/api/uploads/multipart/complete', {
+      body: {
+        file_id: initResponse.fileId,
+        parts: etags,
+      },
+      deserialize: UploadResponseFromJSON,
+    });
+  }
+
+  // -----------------------------------------------------------------------
+  // Workflows
+  // -----------------------------------------------------------------------
+
+  /**
+   * Create a new workflow.
+   */
+  async createWorkflow(payload: WorkflowCreatePayload): Promise<WorkflowCreateResponse> {
+    return this.request('POST', '/api/workflows', {
+      body: payload as unknown as Record<string, unknown>,
+      deserialize: WorkflowCreateResponseFromJSON,
+    });
+  }
+
+  /**
+   * Get current workflow status.
+   */
+  async getWorkflowStatus(workflowId: string): Promise<WorkflowStatusResponse> {
+    return this.request('GET', `/api/workflows/${encodeURIComponent(workflowId)}/status`, {
+      deserialize: WorkflowStatusResponseFromJSON,
+    });
+  }
+
+  /**
+   * Poll until the workflow reaches a terminal status.
+   */
+  async waitForWorkflow(
+    workflowId: string,
+    options?: WaitOptions,
+  ): Promise<WorkflowStatusResponse> {
+    const intervalMs = options?.intervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const timeoutMs = options?.timeoutMs ?? DEFAULT_POLL_TIMEOUT_MS;
+    const deadline = Date.now() + timeoutMs;
+
+    while (true) {
+      const status = await this.getWorkflowStatus(workflowId);
+      options?.onPoll?.(status.status);
+
+      if (TERMINAL_STATUSES.has(status.status)) {
+        return status;
+      }
+
+      if (Date.now() + intervalMs > deadline) {
+        throw new GislTimeoutError(
+          `Workflow ${workflowId} did not complete within ${timeoutMs}ms`,
+        );
+      }
+
+      await new Promise((resolve) => setTimeout(resolve, intervalMs));
+    }
+  }
+
+  /**
+   * Get download URLs for a completed workflow.
+   */
+  async getWorkflowDownloads(workflowId: string): Promise<WorkflowDownloadResponse> {
+    return this.request('GET', `/api/workflows/${encodeURIComponent(workflowId)}/download`, {
+      deserialize: WorkflowDownloadResponseFromJSON,
+    });
+  }
+
+  /**
+   * Stream SSE events for a workflow. Returns an async iterable.
+   */
+  async streamEvents(workflowId: string): Promise<AsyncGenerator<GislSseEvent>> {
+    const response = await this.request<Response>(
+      'GET',
+      `/api/workflows/${encodeURIComponent(workflowId)}/events`,
+      { rawResponse: true },
+    );
+
+    if (!response.ok) {
+      await this.handleResponse(response, `/api/workflows/${workflowId}/events`);
+    }
+
+    return parseSseStream(response);
+  }
+
+  // -----------------------------------------------------------------------
+  // File metadata
+  // -----------------------------------------------------------------------
+
+  /**
+   * Get metadata for an uploaded file.
+   */
+  async getMetadata(fileId: string): Promise<MetadataResponse> {
+    return this.request('GET', `/api/uploads/${encodeURIComponent(fileId)}/metadata`, {
+      deserialize: MetadataResponseFromJSON,
+    });
+  }
+
+  // -----------------------------------------------------------------------
+  // Operations
+  // -----------------------------------------------------------------------
+
+  /**
+   * Get the operations schema (available types, options, constraints).
+   * This endpoint returns raw JSON (no envelope) and is CDN-cacheable.
+   */
+  async getSchema(): Promise<OperationsSchemaResponse> {
+    return this.request('GET', '/api/operations/schema', {
+      deserialize: OperationsSchemaResponseFromJSON,
+    });
+  }
+
+  /**
+   * Retry a failed operation.
+   */
+  async retryOperation(operationId: string): Promise<RetryResponse> {
+    return this.request('POST', `/api/operations/${encodeURIComponent(operationId)}/retry`, {
+      deserialize: RetryResponseFromJSON,
+    });
+  }
+}

package/src/errors.ts

@@ -0,0 +1,39 @@
+export class GislError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'GislError';
+  }
+}
+
+export class GislApiError extends GislError {
+  readonly statusCode: number;
+  readonly errorMessage: string;
+
+  constructor(statusCode: number, errorMessage: string) {
+    super(`API error ${statusCode}: ${errorMessage}`);
+    this.name = 'GislApiError';
+    this.statusCode = statusCode;
+    this.errorMessage = errorMessage;
+  }
+}
+
+export class GislValidationError extends GislApiError {
+  readonly details: Array<{ field: string; message: string }>;
+
+  constructor(
+    statusCode: number,
+    errorMessage: string,
+    details: Array<{ field: string; message: string }>,
+  ) {
+    super(statusCode, errorMessage);
+    this.name = 'GislValidationError';
+    this.details = details;
+  }
+}
+
+export class GislTimeoutError extends GislError {
+  constructor(message: string) {
+    super(message);
+    this.name = 'GislTimeoutError';
+  }
+}

package/src/index.ts

@@ -0,0 +1,86 @@
+// SDK classes and functions
+export { GislClient } from './client.js';
+export { verifyWebhook } from './webhook.js';
+export { parseSseStream } from './sse.js';
+
+// SDK types and factories
+export type {
+  GislClientConfig,
+  GislSseEvent,
+  UploadOptions,
+  WaitOptions,
+  WorkflowCreatePayload,
+  OperationDef,
+  FileJobPayload,
+  SourceJobPayload,
+  InputsJobPayload,
+  JobDefinitionPayload,
+} from './types.js';
+export { fileJob, sourceJob, inputsJob } from './types.js';
+
+// Errors
+export {
+  GislError,
+  GislApiError,
+  GislValidationError,
+  GislTimeoutError,
+} from './errors.js';
+
+// Re-export key contract types so users only need @giveitsmaller/sdk
+export type {
+  UploadResponse,
+  WorkflowCreateResponse,
+  WorkflowStatusResponse,
+  WorkflowDownloadResponse,
+  MetadataResponse,
+  OperationsSchemaResponse,
+  RetryResponse,
+  JobDownload,
+  OperationDownload,
+  WebhookPayload,
+  JobResponse,
+  OperationResponse,
+  OperationResult,
+  ExportConfig,
+} from '@giveitsmaller/contracts/openapi';
+
+export {
+  WorkflowStatus,
+  OperationType,
+  SseEventType,
+  CallbackEventType,
+  OperationStatus,
+  JobStatus,
+} from '@giveitsmaller/contracts/openapi';
+
+export type {
+  SseOperationProgressData,
+  SseOperationCompletedData,
+  SseOperationFailedData,
+  SseJobCompletedData,
+  SseJobFailedData,
+  SseWorkflowTerminalData,
+} from '@giveitsmaller/contracts/openapi';
+
+// Re-export all operation option types
+export type {
+  CompressImageOptions,
+  CompressVideoOptions,
+  CompressAudioOptions,
+  CompressDocumentPdfOptions,
+  CompressDocumentOfficeOptions,
+  CompressDocumentOdfOptions,
+  CompressDocumentEpubOptions,
+  ThumbnailImageOptions,
+  ThumbnailVideoOptions,
+  ThumbnailDocumentOptions,
+  ConvertImageOptions,
+  ConvertVideoOptions,
+  ConvertAudioOptions,
+  ConvertDocumentPdfOptions,
+  MergeImageOptions,
+  MergeVideoOptions,
+  MergeAudioOptions,
+  MergeDocumentOptions,
+  ArchiveOptions,
+} from '@giveitsmaller/contracts/operations';

package/src/sse.ts

@@ -0,0 +1,105 @@
+import type { GislSseEvent } from './types.js';
+
+/**
+ * Parse an SSE stream from a fetch Response into an AsyncIterable of typed events.
+ *
+ * Handles:
+ * - Chunk boundary buffering (events split across chunks)
+ * - Multi-line `data:` fields (concatenated with newlines)
+ * - Comment lines (`:` prefix) used as keep-alives
+ * - `retry:` field (ignored, SDK manages its own reconnection)
+ */
+export async function* parseSseStream(
+  response: Response,
+): AsyncGenerator<GislSseEvent> {
+  const body = response.body;
+  if (!body) {
+    return;
+  }
+
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = '';
+  let eventType = '';
+  let dataLines: string[] = [];
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+
+      buffer += decoder.decode(value, { stream: true });
+
+      // SSE spec allows \n, \r\n, and \r as line endings
+      const lines = buffer.replace(/\r\n?/g, '\n').split('\n');
+      // Keep the last (potentially incomplete) line in the buffer
+      buffer = lines.pop() ?? '';
+
+      for (const line of lines) {
+        if (line === '') {
+          // Empty line = end of event
+          if (dataLines.length > 0) {
+            const rawData = dataLines.join('\n');
+            let parsed: unknown;
+            try {
+              parsed = JSON.parse(rawData);
+            } catch {
+              parsed = rawData;
+            }
+            yield {
+              event: eventType || 'message',
+              data: parsed,
+            } as GislSseEvent;
+          }
+          eventType = '';
+          dataLines = [];
+          continue;
+        }
+
+        if (line.startsWith(':')) {
+          // Comment line (keep-alive), skip
+          continue;
+        }
+
+        const colonIndex = line.indexOf(':');
+        if (colonIndex === -1) {
+          continue;
+        }
+
+        const field = line.slice(0, colonIndex);
+        // Strip single leading space after colon per SSE spec
+        const valueStart = line[colonIndex + 1] === ' ' ? colonIndex + 2 : colonIndex + 1;
+        const fieldValue = line.slice(valueStart);
+
+        switch (field) {
+          case 'event':
+            eventType = fieldValue;
+            break;
+          case 'data':
+            dataLines.push(fieldValue);
+            break;
+          case 'retry':
+            // Ignored — SDK manages its own polling/reconnection
+            break;
+        }
+      }
+    }
+
+    // Flush any remaining buffered event
+    if (dataLines.length > 0) {
+      const rawData = dataLines.join('\n');
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(rawData);
+      } catch {
+        parsed = rawData;
+      }
+      yield {
+        event: eventType || 'message',
+        data: parsed,
+      } as GislSseEvent;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}

package/src/types.ts

@@ -0,0 +1,151 @@
+import type {
+  OperationType,
+  CallbackEventType,
+  SseEventType,
+  SseOperationProgressData,
+  SseOperationCompletedData,
+  SseOperationFailedData,
+  SseJobCompletedData,
+  SseJobFailedData,
+  SseWorkflowTerminalData,
+} from '@giveitsmaller/contracts/openapi';
+
+// ---------------------------------------------------------------------------
+// Client configuration
+// ---------------------------------------------------------------------------
+
+export interface GislClientConfig {
+  baseUrl: string;
+  apiKey?: string;
+  headers?: Record<string, string>;
+  timeout?: number;
+  /** Threshold in bytes above which multipart upload is used (default: 10MB) */
+  multipartThreshold?: number;
+  /** Max concurrent chunk uploads for multipart (default: 4) */
+  multipartConcurrency?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Job definition (typed replacement for generated `any`)
+// ---------------------------------------------------------------------------
+
+export interface OperationDef {
+  type: OperationType;
+  options?: Record<string, unknown>;
+}
+
+/** Job sourced from an uploaded file */
+export interface FileJobPayload {
+  ref: string;
+  file_id: string;
+  operations: OperationDef[];
+}
+
+/** Job sourced from a single upstream job's output */
+export interface SourceJobPayload {
+  ref: string;
+  source: { ref: string; operation?: string };
+  operations: OperationDef[];
+}
+
+/** Job sourced from multiple upstream jobs (merge/archive) */
+export interface InputsJobPayload {
+  ref: string;
+  inputs: Array<{
+    ref: string;
+    operation?: string;
+    per_input_options?: Record<string, unknown>;
+  }>;
+  operations: OperationDef[];
+}
+
+export type JobDefinitionPayload =
+  | FileJobPayload
+  | SourceJobPayload
+  | InputsJobPayload;
+
+// ---------------------------------------------------------------------------
+// Job factory functions
+// ---------------------------------------------------------------------------
+
+export function fileJob(
+  ref: string,
+  fileId: string,
+  operations: OperationDef[],
+): FileJobPayload {
+  return { ref, file_id: fileId, operations };
+}
+
+export function sourceJob(
+  ref: string,
+  source: { ref: string; operation?: string },
+  operations: OperationDef[],
+): SourceJobPayload {
+  return { ref, source, operations };
+}
+
+export function inputsJob(
+  ref: string,
+  inputs: Array<{
+    ref: string;
+    operation?: string;
+    per_input_options?: Record<string, unknown>;
+  }>,
+  operations: OperationDef[],
+): InputsJobPayload {
+  return { ref, inputs, operations };
+}
+
+// ---------------------------------------------------------------------------
+// Workflow creation request (SDK-level, wire-format ready)
+// ---------------------------------------------------------------------------
+
+export interface WorkflowCreatePayload {
+  jobs: JobDefinitionPayload[];
+  workflow_edges?: Array<{ from: string; to: string }>;
+  callback_url?: string;
+  callback_events?: CallbackEventType[];
+  export?: {
+    service: 's3';
+    bucket: string;
+    key_prefix?: string;
+    role_arn: string;
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Polling options
+// ---------------------------------------------------------------------------
+
+export interface WaitOptions {
+  /** Poll interval in milliseconds (default: 2000) */
+  intervalMs?: number;
+  /** Maximum wait time in milliseconds (default: 300000 = 5 min) */
+  timeoutMs?: number;
+  /** Called after each poll with current status */
+  onPoll?: (status: string) => void;
+}
+
+// ---------------------------------------------------------------------------
+// SSE event types (SDK-level typed discriminated union)
+// ---------------------------------------------------------------------------
+
+export type GislSseEvent =
+  | { event: typeof SseEventType.operation_progress; data: SseOperationProgressData }
+  | { event: typeof SseEventType.operation_completed; data: SseOperationCompletedData }
+  | { event: typeof SseEventType.operation_failed; data: SseOperationFailedData }
+  | { event: typeof SseEventType.job_completed; data: SseJobCompletedData }
+  | { event: typeof SseEventType.job_failed; data: SseJobFailedData }
+  | { event: typeof SseEventType.workflow_completed; data: SseWorkflowTerminalData }
+  | { event: typeof SseEventType.workflow_failed; data: SseWorkflowTerminalData }
+  | { event: typeof SseEventType.workflow_partially_failed; data: SseWorkflowTerminalData }
+  | { event: string; data: unknown };
+
+// ---------------------------------------------------------------------------
+// Upload options
+// ---------------------------------------------------------------------------
+
+export interface UploadOptions {
+  /** Called with bytes uploaded so far (only for multipart) */
+  onProgress?: (uploadedBytes: number, totalBytes: number) => void;
+}

package/src/webhook.ts

@@ -0,0 +1,48 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { GislError } from './errors.js';
+
+const SIGNATURE_PREFIX = 'sha256=';
+
+/**
+ * Verify a GISL webhook signature.
+ *
+ * @param secret   The `webhook_secret` from the workflow creation response.
+ * @param signature The value of the `X-GIS-Signature` header.
+ * @param body     The raw request body as a string or Buffer.
+ * @returns `true` if valid.
+ * @throws {GislError} if the signature is missing, malformed, or invalid.
+ */
+export function verifyWebhook(
+  secret: string,
+  signature: string,
+  body: string | Buffer,
+): boolean {
+  if (!signature.startsWith(SIGNATURE_PREFIX)) {
+    throw new GislError(
+      `Invalid signature format: expected "${SIGNATURE_PREFIX}<hex>"`,
+    );
+  }
+
+  const receivedHex = signature.slice(SIGNATURE_PREFIX.length);
+
+  if (!/^[0-9a-f]{64}$/i.test(receivedHex)) {
+    throw new GislError('Webhook signature verification failed');
+  }
+
+  const expectedHex = createHmac('sha256', secret)
+    .update(body)
+    .digest('hex');
+
+  const receivedBuf = Buffer.from(receivedHex, 'hex');
+  const expectedBuf = Buffer.from(expectedHex, 'hex');
+
+  if (receivedBuf.length !== expectedBuf.length) {
+    throw new GislError('Webhook signature verification failed');
+  }
+
+  if (!timingSafeEqual(receivedBuf, expectedBuf)) {
+    throw new GislError('Webhook signature verification failed');
+  }
+
+  return true;
+}