@giveitsmaller/sdk 0.2.2 → 0.4.0

package/dist/client.js

@@ -1,38 +1,205 @@
 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 { GislApiError, GislError, GislTimeoutError, GislValidationError } from './errors.js';
+import { AudioWatermarkDecodeRequestToJSON, AudioWatermarkDecodeResponseFromJSON, ExternalImportCreatedResponseFromJSON, ExternalImportRequestToJSON, LoginUser200ResponseDataFromJSON, CreditsBalanceResponseFromJSON, CreditsUsageResponseFromJSON, UploadResponseFromJSON, UploadProbeResponseFromJSON, MultipartInitiateResponseFromJSON, MultipartInitiateRequestMetadataHintToJSON, MultipartCompleteResponseFromJSON, MultipartCompleteRequestToJSON, WorkflowCancelResponseFromJSON, WorkflowCreateResponseFromJSON, WorkflowResumeResponseFromJSON, WorkflowStatusResponseFromJSON, WorkflowDownloadResponseFromJSON, MetadataResponseFromJSON, OperationsSchemaResponseFromJSON, RetryResponseFromJSON, WorkflowStatus, AuthErrorResponseFromJSON, AuthErrorType, BalanceExhaustedResponseFromJSON, BalanceExhaustedResponseRequiredActionEnum, FeatureNotAvailableResponseFromJSON, FeatureTierRestrictedResponseFromJSON, TierRestrictionKind, TierRestrictionResponseFromJSON, UserTier, WorkflowExpiredResponseFromJSON, UploadThresholdsSingleShotMaxBytesEnum, UploadThresholdsMultipartChunkSizeEnum, UploadThresholdsMultipartConcurrencyDefaultEnum, } from '@giveitsmaller/contracts/openapi';
+import { GislAbortError, GislApiError, GislAuthError, GislBalanceExhaustedError, GislError, GislFeatureNotAvailableError, GislFeatureTierRestrictedError, GislTierRestrictedError, GislTimeoutError, GislValidationError, GislWorkflowExpiredError, } from './errors.js';
 import { parseSseStream } from './sse.js';
 const DEFAULT_TIMEOUT_MS = 30_000;
-const DEFAULT_MULTIPART_THRESHOLD = 10 * 1024 * 1024; // 10 MB
-const DEFAULT_MULTIPART_CONCURRENCY = 4;
+// SDK-internal aliases derived from the contract-pinned UploadThresholds enums
+// (compression_contracts/openapi schema `UploadThresholds`, ticket u0ar7Yye).
+// `satisfies number` keeps the literal type so the drift guards below pin the
+// expected value at compile time. Bumping any of these requires a contracts
+// release that regenerates the corresponding *Enum, plus updating the literal
+// in the matching `_AssertTrue<>` line.
+const SINGLE_SHOT_MAX_BYTES = UploadThresholdsSingleShotMaxBytesEnum.NUMBER_10000000;
+const MULTIPART_CHUNK_SIZE = UploadThresholdsMultipartChunkSizeEnum.NUMBER_5242880;
+export const MULTIPART_CONCURRENCY_DEFAULT = UploadThresholdsMultipartConcurrencyDefaultEnum.NUMBER_4;
+const DEFAULT_MULTIPART_MAX_ATTEMPTS = 3;
+const DEFAULT_MULTIPART_RETRY_BASE_MS = 500;
 // Fixed per contract (compression_contracts/openapi/api.yaml:134). The server
 // uses the first chunk for MIME detection + throughput measurement and stores
 // it as S3 multipart part 1. Must NOT be derived from multipartThreshold —
 // that is the "use multipart above this size" routing threshold, a separate
 // concept. Conflating them caused the /api/uploads/multipart/initiate 413.
+// TODO(58nBQLWQ): replace with UploadThresholdsMultipartFirstChunkSizeEnum
+// once contracts ticket promotes this to a typed const (v2.3.1 follow-up).
 export const DEFAULT_MULTIPART_FIRST_CHUNK_SIZE = 8 * 1024 * 1024; // 8 MB
 const DEFAULT_POLL_INTERVAL_MS = 2_000;
 const DEFAULT_POLL_TIMEOUT_MS = 300_000; // 5 min
+// Statuses that waitForWorkflow() returns immediately on. Per ticket I24,
+// `cancelled` and `expired` are terminal (a workflow cannot leave either
+// state). `paused_insufficient_credits` is a soft-pause: not terminal, but
+// polling blindly is the wrong behaviour because the workflow only resumes
+// on caller action (top-up + resume). The SDK returns immediately so the
+// caller can inspect `pausedDetail` and drive the resume flow.
 const TERMINAL_STATUSES = new Set([
     WorkflowStatus.completed,
     WorkflowStatus.failed,
     WorkflowStatus.partially_failed,
+    WorkflowStatus.cancelled,
+    WorkflowStatus.expired,
+    WorkflowStatus.paused_insufficient_credits,
 ]);
+function isValidationDetails(value) {
+    return (Array.isArray(value) &&
+        value.length > 0 &&
+        value.every((el) => typeof el === 'object' &&
+            el !== null &&
+            typeof el.message === 'string'));
+}
+// An abort may surface as DOMException (browser + modern Node), a plain Error
+// subclass with name='AbortError', or (rarely) a plain object with that name
+// on less conformant runtimes. Match any non-null thing exposing the name.
+function isAbortError(err) {
+    return (err !== null &&
+        typeof err === 'object' &&
+        err.name === 'AbortError');
+}
+// Retryable S3 PUT response statuses: 429 throttling, 503 slow-down, and any
+// other 5xx (502/504 are common transients behind CloudFront/S3). 4xx other
+// than 429 (403 signed-URL expiry, 400 SignatureDoesNotMatch, etc.) are
+// configuration / authority issues — retrying just delays the real failure.
+function isRetryableStatus(status) {
+    return status === 429 || (status >= 500 && status <= 599);
+}
+// fetch surfaces network failures (DNS, TLS, TCP reset, mid-body disconnect)
+// as TypeError. Abort surfaces as a DOMException with name='AbortError', not
+// a TypeError, so a plain instanceof check is sufficient — abort is filtered
+// before reaching here by the dedicated isAbortError guard in the catch.
+function isRetryableNetworkError(err) {
+    return err instanceof TypeError;
+}
+// Full-jitter exponential backoff: delay = random(0, base * 2^attemptIndex).
+// AWS SDK guidance for shared-throttling sources like S3 — keeps competing
+// clients from synchronising their retries.
+function fullJitterDelay(baseMs, attemptIndex) {
+    if (baseMs <= 0)
+        return 0;
+    const ceiling = baseMs * Math.pow(2, attemptIndex);
+    return Math.floor(Math.random() * ceiling);
+}
+// Cancel a Response body so undici (Node 18+ fetch) releases the underlying
+// connection promptly instead of waiting for GC. We swallow any error: the
+// retry loop is about to re-PUT the chunk; failing the cleanup must not
+// shadow the real failure that triggered the retry.
+async function drainResponseBody(response) {
+    try {
+        await response.body?.cancel();
+    }
+    catch {
+        /* ignore */
+    }
+}
+// Reject NaN/Infinity and floor at 1 attempt. A misconfigured 0/negative
+// still attempts the PUT once (so callers see the underlying error rather
+// than a silent zero-PUT no-op).
+function sanitiseAttempts(value, fallback) {
+    if (value === undefined || !Number.isFinite(value))
+        return fallback;
+    return Math.max(1, Math.floor(value));
+}
+// Reject NaN/Infinity and clamp at 0. `0` is permitted so callers can opt out
+// of backoff entirely (e.g. for fast-path tests); `Infinity` would otherwise
+// stall the retry loop indefinitely on the very first backoff.
+function sanitiseBaseMs(value, fallback) {
+    if (value === undefined || !Number.isFinite(value))
+        return fallback;
+    return Math.max(0, Math.floor(value));
+}
+// Reject NaN/Infinity and snap to fallback for any value below 1. Diverges
+// from sanitiseAttempts (which floors at 1) because zero workers here is
+// not a "fail-fast once" semantic — `Math.min(0, queue.length) = 0` at the
+// worker fan-out site below produces zero S3 PUTs, so /multipart/complete
+// is then called with an incomplete `parts` array (silent corruption).
+// Garbage input almost certainly meant "use the default", not "send no parts".
+function sanitiseConcurrency(value, fallback) {
+    if (value === undefined || !Number.isFinite(value))
+        return fallback;
+    const floored = Math.floor(value);
+    return floored < 1 ? fallback : floored;
+}
+// Cancellable sleep. Resolves after `ms` ms, rejects with GislAbortError if
+// the caller's signal aborts, or resolves early (without throwing) if the
+// internal `wakeSignal` fires — that path lets a sibling worker's terminal
+// failure short-circuit a peer's backoff sleep without producing a spurious
+// abort error in the peer's own throw stack.
+function sleepWithEitherSignal(ms, abortSignal, wakeSignal) {
+    if (abortSignal?.aborted) {
+        return Promise.reject(new GislAbortError('Multipart upload aborted'));
+    }
+    if (wakeSignal.aborted || ms <= 0)
+        return Promise.resolve();
+    return new Promise((resolve, reject) => {
+        const cleanup = () => {
+            abortSignal?.removeEventListener('abort', onAbort);
+            wakeSignal.removeEventListener('abort', onWake);
+        };
+        const onAbort = () => {
+            clearTimeout(timer);
+            cleanup();
+            reject(new GislAbortError('Multipart upload aborted'));
+        };
+        const onWake = () => {
+            clearTimeout(timer);
+            cleanup();
+            resolve();
+        };
+        const timer = setTimeout(() => {
+            cleanup();
+            resolve();
+        }, ms);
+        abortSignal?.addEventListener('abort', onAbort, { once: true });
+        wakeSignal.addEventListener('abort', onWake, { once: true });
+    });
+}
+// Wire an optional external AbortSignal onto an internal per-request controller
+// so either source trips the composed fetch. The `onExternalAbort` callback
+// fires the moment the external signal aborts — callers use it to capture the
+// temporal order of user-vs-timeout causes, so the tiebreak in request() does
+// not rely on `signal.aborted` read at catch time (which flips true regardless
+// of which cause actually fired first).
+//
+// Returns a teardown that removes the listener — must be called in a finally
+// so long-lived user AbortControllers do not accumulate listeners across many
+// uploads. Node 18+ compatible (no AbortSignal.any).
+function bindAbortSignal(external, internal, onExternalAbort) {
+    if (!external)
+        return () => { };
+    if (external.aborted) {
+        onExternalAbort?.();
+        internal.abort();
+        return () => { };
+    }
+    const onAbort = () => {
+        onExternalAbort?.();
+        internal.abort();
+    };
+    external.addEventListener('abort', onAbort, { once: true });
+    return () => external.removeEventListener('abort', onAbort);
+}
 export class GislClient {
     baseUrl;
     headers;
     timeoutMs;
     multipartThreshold;
     multipartConcurrency;
+    multipartMaxAttempts;
+    multipartRetryBaseMs;
+    useSessionCookie;
     constructor(config) {
         this.baseUrl = config.baseUrl.replace(/\/+$/, '');
         this.timeoutMs = config.timeout ?? DEFAULT_TIMEOUT_MS;
+        this.useSessionCookie = config.useSessionCookie ?? false;
         // Floor the threshold at the first-chunk size: the multipart initiate
         // must always carry an 8MB chunk, so routing a sub-8MB file into the
         // multipart path would violate the contract.
-        this.multipartThreshold = Math.max(config.multipartThreshold ?? DEFAULT_MULTIPART_THRESHOLD, DEFAULT_MULTIPART_FIRST_CHUNK_SIZE);
-        this.multipartConcurrency = config.multipartConcurrency ?? DEFAULT_MULTIPART_CONCURRENCY;
+        this.multipartThreshold = Math.max(config.multipartThreshold ?? SINGLE_SHOT_MAX_BYTES, DEFAULT_MULTIPART_FIRST_CHUNK_SIZE);
+        this.multipartConcurrency = sanitiseConcurrency(config.multipartConcurrency, MULTIPART_CONCURRENCY_DEFAULT);
+        // Sanitise: reject NaN/Infinity (the former would cause `attempt < NaN`
+        // to be perpetually false, skipping every PUT; the latter would retry
+        // unboundedly). Floor at 1 so a misconfigured 0/negative still attempts
+        // once.
+        this.multipartMaxAttempts = sanitiseAttempts(config.multipartMaxAttempts, DEFAULT_MULTIPART_MAX_ATTEMPTS);
+        this.multipartRetryBaseMs = sanitiseBaseMs(config.multipartRetryBaseMs, DEFAULT_MULTIPART_RETRY_BASE_MS);
         this.headers = { ...config.headers };
         if (config.apiKey) {
             this.headers['Authorization'] = `Bearer ${config.apiKey}`;
@@ -42,8 +209,12 @@ export class GislClient {
     // Internal HTTP
     // -----------------------------------------------------------------------
     async request(method, path, opts = {}) {
+        // Fast-fail on a pre-aborted user signal before building the request.
+        if (opts.signal?.aborted) {
+            throw new GislAbortError(`Request to ${method} ${path} aborted`);
+        }
         const url = `${this.baseUrl}${path}`;
-        const headers = { ...this.headers };
+        const headers = { ...this.headers, ...opts.headers };
         let body;
         if (opts.json !== false && opts.body && !(opts.body instanceof FormData)) {
             headers['Content-Type'] = 'application/json';
@@ -53,7 +224,22 @@ export class GislClient {
             body = opts.body;
         }
         const controller = new AbortController();
-        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        // Record the first cause that tripped the composed controller. Checking
+        // `opts.signal.aborted` alone at catch time is not sound: if the timer
+        // fires first and the user signal aborts microseconds later (before
+        // `catch` runs), that flag is also true — but the true cause was the
+        // timeout. Capturing which side fired first gives a deterministic
+        // classification regardless of scheduling.
+        let firstCause = null;
+        const timer = setTimeout(() => {
+            if (firstCause === null)
+                firstCause = 'timeout';
+            controller.abort();
+        }, this.timeoutMs);
+        const unbind = bindAbortSignal(opts.signal, controller, () => {
+            if (firstCause === null)
+                firstCause = 'user';
+        });
         let response;
         try {
             response = await fetch(url, {
@@ -61,48 +247,143 @@ export class GislClient {
                 headers,
                 body,
                 signal: controller.signal,
+                // `credentials: 'include'` on every request when the consumer opts
+                // into cookie-based auth (Symfony session via /api/auth/login).
+                // No-op in Node (fetch ignores the field there); mandatory for
+                // cross-origin browser SPAs to send the session cookie.
+                ...(this.useSessionCookie ? { credentials: 'include' } : {}),
             });
         }
         catch (err) {
-            if (err instanceof DOMException && err.name === 'AbortError') {
+            if (isAbortError(err)) {
+                if (firstCause === 'user') {
+                    throw new GislAbortError(`Request to ${method} ${path} aborted`);
+                }
                 throw new GislTimeoutError(`Request to ${method} ${path} timed out after ${this.timeoutMs}ms`);
             }
             throw err;
         }
         finally {
             clearTimeout(timer);
+            unbind();
         }
         if (opts.rawResponse) {
             return response;
         }
+        // 204 No Content — contracted success status for endpoints that return
+        // no body (e.g. POST /api/contact). Short-circuit before handleResponse
+        // so an empty body never trips the JSON parser.
+        if (response.status === 204) {
+            return undefined;
+        }
         return this.handleResponse(response, path, opts.deserialize);
     }
     async handleResponse(response, path, deserialize) {
-        const contentType = response.headers.get('content-type') ?? '';
-        if (!contentType.includes('application/json')) {
+        const contentType = (response.headers.get('content-type') ?? '').toLowerCase();
+        const isJsonContent = contentType.includes('application/json') || contentType.includes('+json');
+        if (!isJsonContent) {
             if (!response.ok) {
-                throw new GislApiError(response.status, `Non-JSON error from ${path}`);
+                throw new GislApiError(response.status, 'Non-JSON response', path);
             }
             return undefined;
         }
-        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;
+        // Wire-side fields are snake_case (raw response.json() — never run through
+        // FromJSON helpers here). The structured-error subclasses receive a typed
+        // payload built via the per-envelope FromJSON helper, which handles the
+        // snake_case -> camelCase conversion for nested fields.
+        let json;
+        try {
+            json = await response.json();
+        }
+        catch {
+            throw new GislApiError(response.status, 'Invalid JSON response', path);
         }
         // 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);
+            // Localisation triple per ticket I26 — surfaced on every typed error so
+            // consumers can drive client-side i18n catalogs without unwrapping the
+            // typed payload. Field names are wire snake_case here; the typed payload
+            // (built via FromJSON below) carries camelCase copies.
+            const i18n = {
+                messageKey: json.message_key,
+                locale: json.locale,
+                messageParams: json.message_params,
+            };
+            // Validation-details branch first — preserve existing shape so callers
+            // matching on `instanceof GislValidationError` keep working.
+            if (isValidationDetails(json.details)) {
+                throw new GislValidationError(response.status, json.error ?? 'Validation error', json.details, path, i18n);
+            }
+            // Dispatch by (status, error_type) onto the structured envelope shapes
+            // emitted by the v2 contracts. Each branch builds the typed payload via
+            // the generated FromJSON helper so consumers reading e.g.
+            // `error.payload.errorType` see camelCase fields rather than the raw
+            // wire snake_case.
+            //
+            // Defense-in-depth: if a malformed wire envelope causes the FromJSON
+            // helper to throw or coerce a required field to a sentinel value
+            // (e.g. `expired_at` missing -> `new Date(undefined)` => Invalid Date),
+            // fall through to the base `GislApiError` rather than handing the
+            // caller silently-corrupted typed metadata.
+            const errorType = json.error_type;
+            const status = response.status;
+            const errorMessage = json.error ?? 'Unknown error';
+            // Build the typed payload via FromJSON, then validate that all
+            // required typed fields are well-formed. FromJSON does not throw on
+            // missing required fields — for example `workflow_expired` without
+            // `expired_at` produces `new Date(undefined)` => Invalid Date with
+            // `getTime() === NaN`. Without an explicit validity check the error
+            // would surface a silently-corrupted typed payload instead of falling
+            // through to the generic base class.
+            const tryThrowStructured = (construct, ErrorClass, validate) => {
+                let payload;
+                try {
+                    payload = construct(json);
+                }
+                catch {
+                    return undefined;
+                }
+                if (validate && !validate(payload)) {
+                    return undefined;
+                }
+                throw new ErrorClass(status, errorMessage, payload, path, i18n);
+            };
+            const isValidDate = (d) => d instanceof Date && !Number.isNaN(d.getTime());
+            if (status === 401 || status === 403) {
+                if (errorType && this.isAuthErrorType(errorType)) {
+                    tryThrowStructured(AuthErrorResponseFromJSON, GislAuthError, (p) => typeof p.errorType === 'string');
+                }
+            }
+            const isInEnum = (value, members) => typeof value === 'string' && Object.values(members).includes(value);
+            const isFeatureViolation = (v) => typeof v === 'object' && v !== null
+                && typeof v.feature === 'string';
+            if (status === 402 && errorType === 'balance_exhausted') {
+                tryThrowStructured(BalanceExhaustedResponseFromJSON, GislBalanceExhaustedError, (p) => isInEnum(p.requiredAction, BalanceExhaustedResponseRequiredActionEnum));
+            }
+            if (status === 403 && errorType === 'tier_restriction') {
+                tryThrowStructured(TierRestrictionResponseFromJSON, GislTierRestrictedError, (p) => isInEnum(p.restrictionKind, TierRestrictionKind)
+                    && isInEnum(p.currentTier, UserTier));
+            }
+            if (status === 403 && errorType === 'feature_tier_restricted') {
+                tryThrowStructured(FeatureTierRestrictedResponseFromJSON, GislFeatureTierRestrictedError, (p) => Array.isArray(p.violations) && p.violations.every(isFeatureViolation));
+            }
+            if (status === 422 && errorType === 'feature_not_available') {
+                tryThrowStructured(FeatureNotAvailableResponseFromJSON, GislFeatureNotAvailableError, (p) => Array.isArray(p.violations) && p.violations.every(isFeatureViolation));
+            }
+            if (status === 422 && errorType === 'workflow_expired') {
+                tryThrowStructured(WorkflowExpiredResponseFromJSON, GislWorkflowExpiredError, (p) => isValidDate(p.expiredAt));
             }
-            throw new GislApiError(response.status, json.error ?? 'Unknown error');
+            throw new GislApiError(status, errorMessage, path, json.details, { ...i18n, payload: json });
         }
         const data = json.data ?? json;
         return deserialize ? deserialize(data) : data;
     }
+    // Membership check for the AuthErrorType discriminator. Reads the generated
+    // enum object directly so a future contract addition lands here without a
+    // hand-edit. The bundle cost is one tiny `as const` literal map (8 entries).
+    isAuthErrorType(value) {
+        return Object.values(AuthErrorType).includes(value);
+    }
     // -----------------------------------------------------------------------
     // Upload
     // -----------------------------------------------------------------------
@@ -114,6 +395,11 @@ export class GislClient {
      * @param options  Upload options including progress callback.
      */
     async uploadFile(file, options) {
+        // Pre-abort check: bail before statSync/readFileSync buffers the whole
+        // file into memory when the caller has already cancelled.
+        if (options?.signal?.aborted) {
+            throw new GislAbortError('Upload aborted before start');
+        }
         let blob;
         let fileName;
         let fileSize;
@@ -132,17 +418,29 @@ export class GislClient {
         if (fileSize > this.multipartThreshold) {
             return this.multipartUpload(blob, fileName, fileSize, options);
         }
-        return this.singleUpload(blob, fileName);
+        return this.singleUpload(blob, fileName, options);
     }
-    async singleUpload(blob, fileName) {
+    async singleUpload(blob, fileName, options) {
         const form = new FormData();
         form.append('file', blob, fileName);
         return this.request('POST', '/api/uploads', {
             body: form,
             json: false,
             deserialize: UploadResponseFromJSON,
+            signal: options?.signal,
         });
     }
+    /**
+     * Direct-to-S3 multipart upload for files above the threshold.
+     *
+     * The /multipart/complete response (MultipartCompleteResponse) only carries
+     * { upload_id, status }. The server's upload_id is the same UUID callers
+     * pass as file_id to POST /api/workflows — so fileId is synthesised from
+     * upload_id and a full UploadResponse is returned to keep the public
+     * uploadFile() API uniform across single and multipart paths. The mimeType
+     * comes from the initiate response's first-chunk detection; for authoritative
+     * post-upload metadata callers should use getMetadata(fileId).
+     */
     async multipartUpload(blob, fileName, totalSize, options) {
         // Step 1: Initiate with first chunk
         const firstChunkSize = Math.min(totalSize, DEFAULT_MULTIPART_FIRST_CHUNK_SIZE);
@@ -151,10 +449,23 @@ export class GislClient {
         initiateForm.append('file', firstChunk, fileName);
         initiateForm.append('filename', fileName);
         initiateForm.append('total_size', totalSize.toString());
+        if (options?.metadataHint !== undefined) {
+            // Wire format: a single FormData field carrying the JSON-stringified
+            // hint object. Single-shot uploads do not accept this field — see
+            // singleUpload() which silently ignores `options.metadataHint`.
+            // Route through the generated ToJSON helper so the wire form is the
+            // contract-pinned snake_case shape (`duration_seconds`, `width`,
+            // `height`). Stringify-ing the camelCase TS object directly would
+            // emit `durationSeconds` and the server would silently drop it,
+            // defeating the hint's primary use (long-form pre-classification when
+            // the first-chunk probe lacks container metadata).
+            initiateForm.append('metadata_hint', JSON.stringify(MultipartInitiateRequestMetadataHintToJSON(options.metadataHint)));
+        }
         const initResponse = await this.request('POST', '/api/uploads/multipart/initiate', {
             body: initiateForm,
             json: false,
             deserialize: MultipartInitiateResponseFromJSON,
+            signal: options?.signal,
         });
         let uploadedBytes = firstChunkSize;
         options?.onProgress?.(uploadedBytes, totalSize);
@@ -162,45 +473,179 @@ export class GislClient {
         const etags = [];
         const presignedUrls = initResponse.presignedUrls;
         const chunkSize = initResponse.recommendedChunkSize;
+        // Internal abort signal that workers use to short-circuit each others'
+        // backoff sleeps. When any worker hits a terminal failure it aborts this
+        // controller, which races the caller's signal inside sleepWithSignal so
+        // sleeping siblings stop waiting for their timer to expire.
+        const failureController = new AbortController();
+        // Single PUT attempt. Returns a structured outcome instead of throwing
+        // for retryable/non-retryable distinctions, so the caller can decide
+        // whether to loop without conflating user-callback errors with
+        // network-layer retries (codex review).
+        const attemptPut = async (part, chunk, contentLength) => {
+            let s3Response;
+            try {
+                s3Response = await fetch(part.url, {
+                    method: 'PUT',
+                    body: chunk,
+                    headers: { 'Content-Length': contentLength.toString() },
+                    signal: options?.signal,
+                });
+            }
+            catch (err) {
+                if (isAbortError(err) && options?.signal?.aborted) {
+                    return {
+                        kind: 'fatal',
+                        err: new GislAbortError(`S3 part ${part.partNumber} upload aborted`),
+                    };
+                }
+                if (isRetryableNetworkError(err)) {
+                    return { kind: 'retryable', lastErr: err };
+                }
+                return { kind: 'fatal', err };
+            }
+            if (s3Response.ok) {
+                const etag = s3Response.headers.get('etag');
+                if (!etag) {
+                    // Drain the body even though we're failing fast — keeps the
+                    // connection released eagerly.
+                    await drainResponseBody(s3Response);
+                    return {
+                        kind: 'fatal',
+                        err: new GislError(`S3 response missing ETag for part ${part.partNumber}`),
+                    };
+                }
+                return { kind: 'ok', etag };
+            }
+            // Non-OK: drain the body in BOTH branches before deciding. Undici
+            // holds the connection open until the body is consumed regardless of
+            // whether we retry.
+            await drainResponseBody(s3Response);
+            if (!isRetryableStatus(s3Response.status)) {
+                return {
+                    kind: 'fatal',
+                    err: new GislError(`S3 chunk upload failed for part ${part.partNumber}: ${s3Response.status}`),
+                };
+            }
+            return {
+                kind: 'retryable',
+                lastErr: new GislError(`S3 chunk upload failed for part ${part.partNumber}: ${s3Response.status}`),
+            };
+        };
         const uploadChunk = async (index) => {
             const part = presignedUrls[index];
             const start = firstChunkSize + index * chunkSize;
             const end = Math.min(start + chunkSize, totalSize);
+            // Blob.slice() returns a new Blob view; the underlying bytes are
+            // immutable so the same `chunk` may be re-sent across retry attempts.
+            // S3 multipart parts are idempotent by partNumber — a re-PUT overwrites,
+            // there is no duplicate-data risk.
             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}`);
+            const contentLength = end - start;
+            let lastErr = null;
+            for (let attempt = 0; attempt < this.multipartMaxAttempts; attempt++) {
+                if (options?.signal?.aborted) {
+                    throw new GislAbortError(`S3 part ${part.partNumber} upload aborted`);
+                }
+                if (failureController.signal.aborted) {
+                    // Sibling worker hit a terminal failure: bail before dispatching a
+                    // wasted PUT. The thrown error is swallowed by the outer worker
+                    // loop — Promise.all has already settled with the first failure.
+                    throw new GislError(`S3 part ${part.partNumber} upload abandoned after sibling worker failure`);
+                }
+                const outcome = await attemptPut(part, chunk, contentLength);
+                if (outcome.kind === 'ok') {
+                    // Apply progress side effects OUTSIDE the retry-scoped path so a
+                    // user-callback throw does not trigger a duplicate PUT (codex
+                    // review: retrying after a successful PUT would double-record the
+                    // ETag and re-upload an already accepted part).
+                    etags.push({ partNumber: part.partNumber, etag: outcome.etag });
+                    uploadedBytes += contentLength;
+                    options?.onProgress?.(uploadedBytes, totalSize);
+                    return;
+                }
+                if (outcome.kind === 'fatal') {
+                    throw outcome.err;
+                }
+                lastErr = outcome.lastErr;
+                if (attempt + 1 >= this.multipartMaxAttempts)
+                    break;
+                const delay = fullJitterDelay(this.multipartRetryBaseMs, attempt);
+                // Race the caller's signal AND the sibling-failure signal so a
+                // worker that fails terminally wakes its sleeping peers instead of
+                // forcing them to wait out their backoff timer.
+                await sleepWithEitherSignal(delay, options?.signal, failureController.signal);
             }
-            etags.push({ part_number: part.partNumber, etag });
-            uploadedBytes += end - start;
-            options?.onProgress?.(uploadedBytes, totalSize);
+            throw new GislError(`S3 chunk upload failed for part ${part.partNumber} after ${this.multipartMaxAttempts} attempts: ` +
+                (lastErr instanceof Error ? lastErr.message : String(lastErr)));
         };
-        // Upload with concurrency limit
+        // Upload with concurrency limit. Workers check the signal before pulling
+        // the next queue item so a mid-upload abort drains fast without
+        // dispatching new chunks. Chunks already in-flight are cancelled via the
+        // composed signal passed to fetch above; sleeping siblings are woken via
+        // the failureController set below.
         const queue = [...presignedUrls.keys()];
         const workers = Array.from({ length: Math.min(this.multipartConcurrency, queue.length) }, async () => {
-            while (queue.length > 0) {
+            while (queue.length > 0 && !failureController.signal.aborted) {
+                if (options?.signal?.aborted) {
+                    throw new GislAbortError('Multipart upload aborted');
+                }
                 const index = queue.shift();
-                await uploadChunk(index);
+                try {
+                    await uploadChunk(index);
+                }
+                catch (err) {
+                    // Wake any sibling currently in a backoff sleep, and prevent
+                    // siblings from picking up further queue items.
+                    failureController.abort();
+                    throw err;
+                }
             }
         });
         await Promise.all(workers);
-        // Step 3: Complete multipart upload
-        etags.sort((a, b) => a.part_number - b.part_number);
-        return this.request('POST', '/api/uploads/multipart/complete', {
-            body: {
-                file_id: initResponse.fileId,
-                parts: etags,
-            },
-            deserialize: UploadResponseFromJSON,
+        // Step 3: Complete multipart upload.
+        // Build a typed MultipartCompleteRequest and serialise via the generated
+        // ToJSON helper — tsc now catches any field-name drift between the SDK
+        // and the OpenAPI spec (see contract-drift-fields.test.ts describe 'c').
+        etags.sort((a, b) => a.partNumber - b.partNumber);
+        const completeRequest = {
+            uploadId: initResponse.uploadId,
+            parts: etags,
+        };
+        // MultipartCompleteRequestToJSON's declared return type is the camelCase
+        // `MultipartCompleteRequest` interface, but at runtime it returns the
+        // snake_case wire object — an openapi-generator v7 quirk. The drift gate
+        // for field names lives at `completeRequest: MultipartCompleteRequest`
+        // above; the local wire type + runtime sanity check below guard against
+        // the remaining hypothetical: a future generator version emitting a
+        // different shape without the declared type catching it.
+        const wireCompleteBody = MultipartCompleteRequestToJSON(completeRequest);
+        if (typeof wireCompleteBody?.upload_id !== 'string' ||
+            !Array.isArray(wireCompleteBody?.parts)) {
+            throw new GislError('MultipartCompleteRequestToJSON returned an unexpected shape — generator output may have changed.');
+        }
+        const completeResp = await this.request('POST', '/api/uploads/multipart/complete', {
+            body: wireCompleteBody,
+            deserialize: MultipartCompleteResponseFromJSON,
+            signal: options?.signal,
         });
+        // Defensive: the status enum currently has only 'completed', but guard
+        // against future expansion so an unexpected terminal state doesn't pass
+        // as a successful upload.
+        if (completeResp.status !== 'completed') {
+            throw new GislError(`Multipart upload completed with unexpected status: ${completeResp.status}`);
+        }
+        return {
+            fileId: completeResp.uploadId,
+            originalName: fileName,
+            mimeType: initResponse.mimeType,
+            sizeBytes: blob.size,
+            // Preserved from the initiate response: v2 contract makes
+            // `constraintsApplied` a REQUIRED field on UploadResponse, and the
+            // multipart/complete endpoint does not re-emit it. The first-chunk probe
+            // result on the initiate envelope is the authoritative source.
+            constraintsApplied: initResponse.constraintsApplied,
+        };
     }
     // -----------------------------------------------------------------------
     // Workflows
@@ -241,6 +686,49 @@ export class GislClient {
             await new Promise((resolve) => setTimeout(resolve, intervalMs));
         }
     }
+    /**
+     * Cancel a workflow. Idempotent — cancelling an already-cancelled
+     * workflow returns 200 with the same shape (and the original
+     * `cancelledAt`). Cancelling a `completed` / `failed` /
+     * `partially_failed` / `expired` workflow returns 409.
+     *
+     * The response's `billingEffect` field tells the caller what
+     * happened to outstanding reservations:
+     * - `unspent_reservation_released` — workflow was active or paused
+     *   and the unspent portion of the reservation has been refunded.
+     *   The refund appears as a separate `CreditTransaction` with
+     *   `type: refund`.
+     * - `none` — no refund (all reserved credits were already consumed
+     *   by completed jobs, or this is an idempotent re-cancel).
+     *
+     * In-flight operations may continue running briefly after the
+     * cancel response while their Lambda processes terminate; the
+     * response is the binding "no further reservations will be made"
+     * signal.
+     */
+    async cancelWorkflow(workflowId) {
+        return this.request('POST', `/api/workflows/${encodeURIComponent(workflowId)}/cancel`, {
+            deserialize: WorkflowCancelResponseFromJSON,
+        });
+    }
+    /**
+     * Resume a workflow that is in `paused_insufficient_credits`.
+     *
+     * Resume succeeds only when `availableCredits` covers the next
+     * reservation. If the balance is still insufficient, throws
+     * `GislBalanceExhaustedError` (402, same envelope as the workflow-
+     * create 402 path) and the workflow stays paused. If the workflow
+     * is past its `expiresAt` (default 7-day TTL from `pausedAt`),
+     * throws `GislWorkflowExpiredError` (422) and the workflow has
+     * transitioned to `expired` — callers cannot un-expire a workflow.
+     * Resuming a workflow that is not in `paused_insufficient_credits`
+     * is a 409 (no-op).
+     */
+    async resumeWorkflow(workflowId) {
+        return this.request('POST', `/api/workflows/${encodeURIComponent(workflowId)}/resume`, {
+            deserialize: WorkflowResumeResponseFromJSON,
+        });
+    }
     /**
      * Get download URLs for a completed workflow.
      */
@@ -253,9 +741,10 @@ export class GislClient {
      * Stream SSE events for a workflow. Returns an async iterable.
      */
     async streamEvents(workflowId) {
-        const response = await this.request('GET', `/api/workflows/${encodeURIComponent(workflowId)}/events`, { rawResponse: true });
+        const eventsPath = `/api/workflows/${encodeURIComponent(workflowId)}/events`;
+        const response = await this.request('GET', eventsPath, { rawResponse: true });
         if (!response.ok) {
-            await this.handleResponse(response, `/api/workflows/${workflowId}/events`);
+            await this.handleResponse(response, eventsPath);
         }
         return parseSseStream(response);
     }
@@ -275,12 +764,58 @@ export class GislClient {
     // -----------------------------------------------------------------------
     /**
      * Get the operations schema (available types, options, constraints).
-     * This endpoint returns raw JSON (no envelope) and is CDN-cacheable.
+     *
+     * Returns raw JSON (no envelope). The response is **per-tier private**
+     * (cache key includes the caller's `user_tier`); CDN-style public
+     * caching is not used. Pass `ifNoneMatch` / `ifModifiedSince` from a
+     * previous response to revalidate — a 304 surfaces as
+     * `{ notModified: true, etag, lastModified }` so callers can keep
+     * using their cached copy.
      */
-    async getSchema() {
-        return this.request('GET', '/api/operations/schema', {
-            deserialize: OperationsSchemaResponseFromJSON,
+    async getSchema(options = {}) {
+        const params = new URLSearchParams();
+        if (options.mimeType !== undefined)
+            params.set('mime_type', options.mimeType);
+        if (options.operation !== undefined)
+            params.set('operation', options.operation);
+        const query = params.toString();
+        // The contract-drift test (tests/unit/contract-drift.test.ts) scans this
+        // file for path literals via a regex that picks up both single-quoted
+        // strings AND backtick templates. Embedding the querystring in a single
+        // template would normalise to a path-with-querystring that no contract
+        // path matches. Compose with concatenation so only the bare path appears
+        // as a literal.
+        const path = '/api/operations/schema' + (query ? '?' + query : '');
+        const headers = {};
+        if (options.ifNoneMatch !== undefined)
+            headers['If-None-Match'] = options.ifNoneMatch;
+        if (options.ifModifiedSince !== undefined)
+            headers['If-Modified-Since'] = options.ifModifiedSince;
+        const response = await this.request('GET', path, {
+            rawResponse: true,
+            signal: options.signal,
+            ...(Object.keys(headers).length > 0 ? { headers } : {}),
         });
+        const etag = response.headers.get('etag') ?? undefined;
+        const lastModified = response.headers.get('last-modified') ?? undefined;
+        if (response.status === 304) {
+            return { notModified: true, etag, lastModified };
+        }
+        if (!response.ok) {
+            let errorMessage = 'Unknown error';
+            try {
+                const errJson = (await response.json());
+                if (errJson.error)
+                    errorMessage = errJson.error;
+            }
+            catch {
+                // Non-JSON body — keep generic message.
+            }
+            throw new GislApiError(response.status, errorMessage, path);
+        }
+        const raw = await response.json();
+        const data = OperationsSchemaResponseFromJSON(raw);
+        return { notModified: false, data, etag, lastModified };
     }
     /**
      * Retry a failed operation.
@@ -290,4 +825,213 @@ export class GislClient {
             deserialize: RetryResponseFromJSON,
         });
     }
+    // -----------------------------------------------------------------------
+    // Contact
+    // -----------------------------------------------------------------------
+    /**
+     * Submit a contact-form message. The endpoint returns 204 No Content on
+     * success, so this method resolves to `void`.
+     *
+     * Validation errors (e.g. missing `email`, non-empty honeypot `website`)
+     * surface as `GislValidationError` from the standard error envelope.
+     */
+    async submitContact(payload) {
+        await this.request('POST', '/api/contact', {
+            body: payload,
+        });
+    }
+    // -----------------------------------------------------------------------
+    // Credits / billing
+    // -----------------------------------------------------------------------
+    /**
+     * Get a snapshot of the caller's current credit position. The canonical
+     * billing-state surface — `BalanceExhaustedResponse` (402) on workflow
+     * creation includes pre-error counters for context, but UIs should drive
+     * spend-now affordances and tier-upgrade prompts off this endpoint, not
+     * off the error envelope.
+     */
+    async getCreditsBalance() {
+        return this.request('GET', '/api/v2/credits/balance', {
+            deserialize: CreditsBalanceResponseFromJSON,
+        });
+    }
+    // -----------------------------------------------------------------------
+    // Auth
+    // -----------------------------------------------------------------------
+    /**
+     * Authenticate with email/password. On success the server issues a
+     * session cookie via `Set-Cookie`; subsequent requests authenticate
+     * via that cookie when the client is configured with
+     * `useSessionCookie: true`.
+     *
+     * Failure modes per ticket FX6mbTJD:
+     * - **401** `invalid_credentials` (collapsed with unverified
+     *   accounts for anti-enumeration) → `GislAuthError`.
+     * - **403** account-state failures (`account_locked`,
+     *   `account_disabled`, `account_deleted`,
+     *   `account_deletion_expired`) → `GislAuthError`.
+     * - **429** infrastructure rate-limit → `GislApiError` with
+     *   the `Retry-After` header echoed on the response.
+     *
+     * Node session persistence (cookie-jar across processes) is out of
+     * scope — this method only touches the request side.
+     */
+    async login(credentials) {
+        return this.request('POST', '/api/auth/login', {
+            body: credentials,
+            deserialize: LoginUser200ResponseDataFromJSON,
+        });
+    }
+    /**
+     * Invalidate the current session.
+     *
+     * Idempotent: calling logout without an active session returns 401,
+     * but the SDK collapses both 200 and 401 into a single "logged out"
+     * outcome — `logout()` resolves to `void` in either case so caller
+     * cleanup code does not need to special-case the not-currently-
+     * authenticated path. Other errors (e.g. 500, network failures)
+     * still throw.
+     */
+    async logout() {
+        try {
+            await this.request('POST', '/api/auth/logout', {});
+        }
+        catch (err) {
+            // Treat 401 as success (already logged out — idempotent per
+            // contract). Logout 401 is a bare ErrorEnvelope with no
+            // `error_type`, so it surfaces as the base GislApiError rather
+            // than the typed GislAuthError — match on the status code to
+            // capture both shapes.
+            if (err instanceof GislApiError && err.statusCode === 401) {
+                return;
+            }
+            throw err;
+        }
+    }
+    // -----------------------------------------------------------------------
+    // External imports
+    // -----------------------------------------------------------------------
+    /**
+     * Register a one-shot bearer URL (S3 presigned, GCS signed, Azure
+     * SAS, Dropbox shared link, public HTTPS) and receive an opaque
+     * `externalSourceId` handle. Subsequent workflows reference the
+     * handle via `WorkflowSource` of `type: external_import` —
+     * compose with the [`externalImportSource()`](./types.ts) factory.
+     *
+     * Per ADR-0005 §"SSRF posture": the server validates 8 rules at
+     * registration time AND again at fetch time. HTTPS-only;
+     * private/loopback/cloud-metadata IPs are rejected (403). The
+     * original URL + password are encrypted at rest and never
+     * returned in any response.
+     *
+     * Currently `availability: planned` — the runtime endpoint returns
+     * 422 `feature_not_available` (or 404, per the cross-repo rollout)
+     * until the external-import infrastructure ships. The method
+     * exists today so consumers can write the integration ahead of
+     * time.
+     */
+    async createExternalImport(payload) {
+        return this.request('POST', '/api/external-imports', {
+            body: ExternalImportRequestToJSON(payload),
+            deserialize: ExternalImportCreatedResponseFromJSON,
+        });
+    }
+    // -----------------------------------------------------------------------
+    // Audio watermark
+    // -----------------------------------------------------------------------
+    /**
+     * Decode a previously-embedded steganographic audio watermark
+     * (per ticket I20). Pairs with the `audio_watermark` operation —
+     * the operation embeds; this endpoint decodes.
+     *
+     * **Enterprise tier only.** Free / pro callers receive
+     * `GislFeatureTierRestrictedError` (403).
+     *
+     * **Own watermarks only.** The decoder will refuse to extract from
+     * media the caller did not mark themselves — mismatches return 404
+     * (rather than leaking that *some* watermark was detected).
+     *
+     * Currently `availability: planned` — calls return
+     * `GislFeatureNotAvailableError` (422) until the cross-repo Lambda
+     * support ships. Decode requests are rate-limited independently
+     * from workflow-create.
+     */
+    async decodeAudioWatermark(payload) {
+        // The generated request type is camelCase; convert to snake_case wire
+        // shape before sending. Mirrors the multipart complete pattern.
+        return this.request('POST', '/api/audio-watermark/decode', {
+            body: AudioWatermarkDecodeRequestToJSON(payload),
+            deserialize: AudioWatermarkDecodeResponseFromJSON,
+        });
+    }
+    // -----------------------------------------------------------------------
+    // Upload probe / preflight
+    // -----------------------------------------------------------------------
+    /**
+     * Probe an uploaded file for workflow-readiness — detects corruption,
+     * unsupported codecs, and pre-assigns the processing class the server
+     * would route the file to. Designed for the long-form merge edge case
+     * where a single bad input would fail the whole workflow.
+     *
+     * Currently `availability: planned` — calls return
+     * `GislFeatureNotAvailableError` (422) until the cross-repo Lambda
+     * support ships. Idempotent: probing the same `fileId` twice returns
+     * the cached result.
+     */
+    async probeUpload(fileId) {
+        return this.request('POST', `/api/uploads/${encodeURIComponent(fileId)}/probe`, {
+            deserialize: UploadProbeResponseFromJSON,
+        });
+    }
+    /**
+     * Probe N uploaded files in parallel and partition the results by
+     * outcome. Returns `{ ok, rejected, errors }` so the caller can
+     * cleanly drop bad clips before submitting a long-form merge
+     * workflow. Probe-call failures (including the
+     * `feature_not_available` 422 returned while the endpoint is
+     * `availability: planned`) land in `errors` rather than throwing,
+     * so a partially-successful batch still yields useful aggregation.
+     */
+    async preflightClips(fileIds) {
+        const settled = await Promise.allSettled(fileIds.map((fileId) => this.probeUpload(fileId)));
+        const ok = [];
+        const rejected = [];
+        const errors = [];
+        for (let i = 0; i < settled.length; i++) {
+            const result = settled[i];
+            const fileId = fileIds[i];
+            if (result.status === 'fulfilled') {
+                if (result.value.probeStatus === 'ok') {
+                    ok.push(result.value);
+                }
+                else {
+                    rejected.push(result.value);
+                }
+            }
+            else {
+                errors.push({ fileId, error: result.reason });
+            }
+        }
+        return { ok, rejected, errors };
+    }
+    /**
+     * Get a paginated page of credit transaction history for the caller.
+     * Server defaults: `limit=20`, `offset=0`. Most-recent-first.
+     */
+    async getCreditsUsage(options = {}) {
+        const params = new URLSearchParams();
+        if (options.limit !== undefined)
+            params.set('limit', String(options.limit));
+        if (options.offset !== undefined)
+            params.set('offset', String(options.offset));
+        const query = params.toString();
+        // String concatenation (not template) so the contract-drift path scanner
+        // picks up the literal path. See getSchema for the same pattern.
+        const path = query.length > 0
+            ? '/api/v2/credits/usage' + '?' + query
+            : '/api/v2/credits/usage';
+        return this.request('GET', path, {
+            deserialize: CreditsUsageResponseFromJSON,
+        });
+    }
 }