@giveitsmaller/sdk 0.12.1 → 0.13.0

package/README.md

@@ -12,34 +12,42 @@ Node.js 18+ required.
 
 ## Quickstart
 
+The SDK is **file-first**: you start from a file (`.file(path)` for one,
+`.files([paths])` for many) and call operations *on* it — upload, workflow
+creation, and waiting all happen for you.
+
 ```ts
-import { GislClient, uploadSource, OperationType } from '@giveitsmaller/sdk';
-
-const client = new GislClient({
-  baseUrl: 'https://api.giveitsmaller.com',
-  apiKey: 'REPLACE_ME_API_KEY',
-});
-
-const upload = await client.uploadFile('./photo.jpg');
-
-const workflow = await client.createWorkflow({
-  jobs: [
-    {
-      id: 'compressed',
-      source: uploadSource(upload.fileId),
-      operations: [
-        { type: OperationType.compress, options: { mode: 'lossy', quality: 80 } },
-      ],
-    },
-  ],
-});
-
-await client.waitForWorkflow(workflow.workflowId);
-
-const dls = await client.getWorkflowDownloads(workflow.workflowId);
-console.log('Compressed:', dls.downloads[0].files[0].downloadUrl);
+import { gisl, OptimizeFor } from '@giveitsmaller/sdk';
+
+// baseUrl defaults to https://api.giveitsmaller.com; the key can also come
+// from GISL_API_KEY or ~/.gisl/credentials.
+const client = await gisl.create({ apiKey: 'sk_...' });
+
+// One file:
+const result = await client
+  .file('./photo.jpg')
+  .compress(OptimizeFor.Balanced)
+  .run({ maxWait: '5m' });
+
+console.log(result.url); // pre-signed download URL
+
+// Many files (fan-out) — the same chain:
+const many = await client
+  .files(['./a.jpg', './b.png'])
+  .compress(OptimizeFor.Balanced)
+  .run();
+
+for (const artifact of many.artifacts) console.log(artifact.url);
 ```
 
+> **Operation-first / low-level also ships.** A lower-level
+> `client.compress(path, { ... }).run()` form (and `thumbnail` / `convert`) is
+> available, and the raw wire client — `client.createWorkflow({ jobs: [...] })`
+> with `uploadSource` / `OperationType` for hand-built job DAGs — is the advanced
+> escape hatch. File-first is the recommended direction the
+> [examples](https://github.com/AntonioCS/giveitsmaller-sdks/tree/main/docs/typescript/examples)
+> build on.
+
 > **Reusing an upload id across clients?** An upload created by an
 > authenticated caller is owned by that caller. If you persist a `fileId` and
 > later reference it (via `fileInput.uploadId(id)`) from a client configured

package/dist/client.d.ts

@@ -1,5 +1,5 @@
 import type { AudioWatermarkDecodeRequest, AudioWatermarkDecodeResponse, ExternalImportCreatedResponse, ExternalImportRequest, LoginUserRequest, LoginUser200ResponseData, ContactRequest, CreditsBalanceResponse, CreditsUsageResponse, UploadResponse, UploadProbeResponse, WorkflowCancelResponse, WorkflowCreateResponse, WorkflowResumeResponse, WorkflowStatusResponse, WorkflowListResponse, WorkflowSummary, WorkflowDownloadResponse, MetadataResponse, RetryResponse } from '@giveitsmaller/contracts/openapi';
-import type { CreditsUsageOptions, ListWorkflowsOptions, GetSchemaOptions, GetSchemaResult, GislClientConfig, GislSseEvent, PreflightClipsResult, UploadOptions, WaitOptions, WorkflowCreatePayload, _Sdk3HandCodedKeepaliveResult, _Sdk3HandCodedMultipartStatusResult, _Sdk3HandCodedPresignPartsResult } from './types.js';
+import type { CreditsUsageOptions, ListWorkflowsOptions, GetSchemaOptions, GetSchemaResult, GislClientConfig, GislSseEvent, PreflightClipsResult, ProbeWaitOptions, ProbeWaitResult, UploadOptions, WaitOptions, WorkflowCreatePayload, _Sdk3HandCodedKeepaliveResult, _Sdk3HandCodedMultipartStatusResult, _Sdk3HandCodedPresignPartsResult } from './types.js';
 export declare const MULTIPART_CONCURRENCY_DEFAULT: 4;
 export declare const DEFAULT_MULTIPART_FIRST_CHUNK_SIZE: number;
 export interface ValidationDetail {
@@ -306,15 +306,52 @@ export declare class GislClient {
     /**
      * 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.
+     * would route the file to. For video uploads the probe also lands the
+     * codec + duration the server needs to admit the parallel split, so
+     * calling this (or {@link waitForProbe}) before workflow-create is the
+     * structural unlock for the fast video path on the multipart flow.
      *
-     * Currently `availability: planned` — calls return
-     * `GislFeatureNotAvailableError` (422) until the cross-repo Lambda
-     * support ships. Idempotent: probing the same `fileId` twice returns
-     * the cached result.
+     * Endpoint availability is `stable`. The probe runs asynchronously after
+     * upload: until the result has landed, this returns `422`
+     * `feature_not_available` (surfaced as {@link GislFeatureNotAvailableError})
+     * — i.e. that 422 means "probe not landed yet", NOT "not implemented". Once
+     * landed it returns a `200` with any `probeStatus`. Idempotent: probing the
+     * same `fileId` twice returns the cached result. See {@link waitForProbe}
+     * for a bounded poll that turns this into a single ready/gave-up answer.
+     */
+    probeUpload(fileId: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<UploadProbeResponse>;
+    /**
+     * Bounded poll of {@link probeUpload} until the probe lands — the helper
+     * frontends call between upload-complete and workflow-create so the server
+     * sees the video's codec + duration and admits the ~3× parallel split.
+     *
+     * Loop (per the API wire contract):
+     * - `422 feature_not_available` → probe not landed yet → keep polling
+     *   (exponential full-jitter backoff, honouring a `Retry-After` header when
+     *   present, clamped to the remaining budget).
+     * - any `200` → STOP. Resolves `{ landed: true, probe }` regardless of
+     *   `probeStatus` (ok / corrupt / unsupported_codec / missing_metadata) —
+     *   the server + fan-out gate decide split-vs-single from the landed
+     *   metadata; the SDK does not interpret it.
+     * - `5xx` (prober crash) → retry a couple of times, then give up.
+     * - timeout → give up.
+     *
+     * **Never bounces:** on give-up (timeout / repeated 5xx / transport) it
+     * resolves `{ landed: false, reason }` rather than throwing, so the caller
+     * proceeds to create the workflow anyway (the server's size heuristic routes
+     * it; worst case = today's single-task behaviour). Genuine failures —
+     * `404 upload_not_found`, auth errors, or caller abort — DO propagate (they
+     * are not "probe not ready"), so a real problem is never silently swallowed.
+     *
+     * `timeoutMs` bounds the OVERALL poll, checked between attempts; each
+     * in-flight probe request is bounded by the client's own per-request timeout
+     * (a hung request surfaces as a transient and the next deadline check gives
+     * up). So a single slow probe may run up to one client-request-timeout before
+     * the wait returns.
      */
-    probeUpload(fileId: string): Promise<UploadProbeResponse>;
+    waitForProbe(fileId: string, options?: ProbeWaitOptions): Promise<ProbeWaitResult>;
     /**
      * Probe N uploaded files in parallel and partition the results by
      * outcome. Returns `{ ok, rejected, errors }` so the caller can

package/dist/client.js

@@ -112,6 +112,51 @@ function isRetryableStatus(status) {
 function isRetryableNetworkError(err) {
     return err instanceof TypeError;
 }
+// Parse an HTTP `Retry-After` header into milliseconds. Accepts the two RFC
+// 9110 forms: delta-seconds (e.g. "5") or an HTTP-date. Returns `undefined`
+// for an absent / unparseable / negative value (caller falls back to its own
+// backoff). A past HTTP-date clamps to 0.
+function parseRetryAfterMs(headerValue) {
+    if (headerValue === undefined)
+        return undefined;
+    const trimmed = headerValue.trim();
+    if (trimmed === '')
+        return undefined;
+    let ms;
+    if (/^\d+$/.test(trimmed)) {
+        ms = Number(trimmed) * 1000;
+    }
+    else {
+        const when = Date.parse(trimmed);
+        if (Number.isNaN(when))
+            return undefined;
+        ms = when - Date.now();
+    }
+    // A non-positive Retry-After (e.g. "0" or a past HTTP-date) must NOT short-
+    // circuit the backoff to zero — treat it as absent so the caller falls back
+    // to jitter and the loop can't busy-poll until timeout.
+    return ms > 0 ? ms : undefined;
+}
+// Cancellable sleep for poll loops. Resolves after `ms`, or rejects with
+// `GislAbortError` if `signal` aborts. Resolves immediately for ms <= 0.
+function cancellableSleep(ms, signal) {
+    if (signal?.aborted)
+        return Promise.reject(new GislAbortError('waitForProbe aborted'));
+    if (ms <= 0)
+        return Promise.resolve();
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+            reject(new GislAbortError('waitForProbe aborted'));
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
 // 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.
@@ -1979,19 +2024,118 @@ export class GislClient {
     /**
      * 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.
+     * would route the file to. For video uploads the probe also lands the
+     * codec + duration the server needs to admit the parallel split, so
+     * calling this (or {@link waitForProbe}) before workflow-create is the
+     * structural unlock for the fast video path on the multipart flow.
      *
-     * Currently `availability: planned` — calls return
-     * `GislFeatureNotAvailableError` (422) until the cross-repo Lambda
-     * support ships. Idempotent: probing the same `fileId` twice returns
-     * the cached result.
+     * Endpoint availability is `stable`. The probe runs asynchronously after
+     * upload: until the result has landed, this returns `422`
+     * `feature_not_available` (surfaced as {@link GislFeatureNotAvailableError})
+     * — i.e. that 422 means "probe not landed yet", NOT "not implemented". Once
+     * landed it returns a `200` with any `probeStatus`. Idempotent: probing the
+     * same `fileId` twice returns the cached result. See {@link waitForProbe}
+     * for a bounded poll that turns this into a single ready/gave-up answer.
      */
-    async probeUpload(fileId) {
+    async probeUpload(fileId, options = {}) {
         return this.request('POST', `/api/uploads/${encodeURIComponent(fileId)}/probe`, {
             deserialize: UploadProbeResponseFromJSON,
+            signal: options.signal,
         });
     }
+    /**
+     * Bounded poll of {@link probeUpload} until the probe lands — the helper
+     * frontends call between upload-complete and workflow-create so the server
+     * sees the video's codec + duration and admits the ~3× parallel split.
+     *
+     * Loop (per the API wire contract):
+     * - `422 feature_not_available` → probe not landed yet → keep polling
+     *   (exponential full-jitter backoff, honouring a `Retry-After` header when
+     *   present, clamped to the remaining budget).
+     * - any `200` → STOP. Resolves `{ landed: true, probe }` regardless of
+     *   `probeStatus` (ok / corrupt / unsupported_codec / missing_metadata) —
+     *   the server + fan-out gate decide split-vs-single from the landed
+     *   metadata; the SDK does not interpret it.
+     * - `5xx` (prober crash) → retry a couple of times, then give up.
+     * - timeout → give up.
+     *
+     * **Never bounces:** on give-up (timeout / repeated 5xx / transport) it
+     * resolves `{ landed: false, reason }` rather than throwing, so the caller
+     * proceeds to create the workflow anyway (the server's size heuristic routes
+     * it; worst case = today's single-task behaviour). Genuine failures —
+     * `404 upload_not_found`, auth errors, or caller abort — DO propagate (they
+     * are not "probe not ready"), so a real problem is never silently swallowed.
+     *
+     * `timeoutMs` bounds the OVERALL poll, checked between attempts; each
+     * in-flight probe request is bounded by the client's own per-request timeout
+     * (a hung request surfaces as a transient and the next deadline check gives
+     * up). So a single slow probe may run up to one client-request-timeout before
+     * the wait returns.
+     */
+    async waitForProbe(fileId, options = {}) {
+        const timeoutMs = sanitiseBaseMs(options.timeoutMs, 30_000);
+        const signal = options.signal;
+        const start = Date.now();
+        const deadline = start + timeoutMs;
+        const BASE_BACKOFF_MS = 250;
+        const MAX_PROBER_RETRIES = 2;
+        let attempt = 0;
+        // Counts transient probe-call failures (5xx + transport + per-request
+        // timeout) — repeated transients give up so the caller creates anyway
+        // (never-bounce).
+        let transientFailures = 0;
+        for (;;) {
+            if (signal?.aborted)
+                throw new GislAbortError('waitForProbe aborted');
+            const remainingBeforeAttempt = deadline - Date.now();
+            if (remainingBeforeAttempt <= 0)
+                return { landed: false, reason: 'timeout' };
+            attempt += 1;
+            options.onPoll?.({ attempt, elapsedMs: Date.now() - start });
+            let retryAfterMs;
+            try {
+                const probe = await this.probeUpload(fileId, { signal });
+                return { landed: true, probe };
+            }
+            catch (err) {
+                // A CALLER abort always propagates (it is not "probe not ready").
+                if (signal?.aborted) {
+                    throw err instanceof GislAbortError ? err : new GislAbortError('waitForProbe aborted');
+                }
+                if (err instanceof GislFeatureNotAvailableError) {
+                    // Not landed yet — keep polling.
+                    retryAfterMs = parseRetryAfterMs(err.responseHeaders?.['retry-after']);
+                }
+                else if ((err instanceof GislApiError && err.statusCode >= 500) ||
+                    err instanceof GislTimeoutError ||
+                    isRetryableNetworkError(err)) {
+                    // Transient probe-call failure — a 5xx, the client's own per-request
+                    // timeout, or a transport error. Retry a couple of times, then give
+                    // up (never-bounce: the caller creates anyway).
+                    transientFailures += 1;
+                    if (transientFailures > MAX_PROBER_RETRIES) {
+                        return { landed: false, reason: 'prober_error' };
+                    }
+                    retryAfterMs =
+                        err instanceof GislApiError
+                            ? parseRetryAfterMs(err.responseHeaders?.['retry-after'])
+                            : undefined;
+                }
+                else {
+                    // 404 upload_not_found, auth, validation, or any other typed/unexpected
+                    // error is a real failure, not "probe not ready" — propagate.
+                    throw err;
+                }
+            }
+            const remaining = deadline - Date.now();
+            if (remaining <= 0)
+                return { landed: false, reason: 'timeout' };
+            const backoff = retryAfterMs ?? fullJitterDelay(BASE_BACKOFF_MS, attempt - 1);
+            await cancellableSleep(Math.min(backoff, remaining), signal);
+            if (Date.now() >= deadline)
+                return { landed: false, reason: 'timeout' };
+        }
+    }
     /**
      * Probe N uploaded files in parallel and partition the results by
      * outcome. Returns `{ ok, rejected, errors }` so the caller can

package/dist/ergonomic/preset_resolver.d.ts

@@ -68,6 +68,7 @@ export interface ResolveCompressOptionsOutput {
  * @internal — exported for unit tests.
  */
 export declare function _parseTargetSize(value: unknown): number;
+export declare const KNOWN_WIRE_FIELDS: Readonly<Record<PresetMedia, ReadonlySet<string>>>;
 /**
  * Resolve the wire payload + introspection projection for a compress
  * operation call. Throws {@link GislConfigError} before any network

package/dist/ergonomic/preset_resolver.js

@@ -300,7 +300,10 @@ function mergeLayer(acc, layer, source) {
 // ---------------------------------------------------------------------------
 // Validations on the merged wire payload
 // ---------------------------------------------------------------------------
-const KNOWN_WIRE_FIELDS = Object.freeze({
+// Exported so the wire-key conformance guard (tests/unit/wire-key-conformance.test.ts)
+// can pin this hand-maintained allowlist to the generated contract metadata: every
+// field the resolver may emit MUST be a real contract option key for `compress`.
+export const KNOWN_WIRE_FIELDS = Object.freeze({
     image: new Set(['mode', 'quality', 'metadata', 'icc_profile', 'progressive', 'output_format']),
     audio: new Set(['bitrate', 'channels', 'sample_rate', 'normalize', 'trim_start', 'trim_end']),
     video: new Set(['codec', 'encoding_mode', 'crf', 'target_size_bytes', 'preset', 'width', 'height', 'fit', 'fps', 'faststart', 'audio_codec', 'audio_bitrate', 'trim_start', 'trim_end']),

package/dist/file-first.d.ts

@@ -466,7 +466,7 @@ export declare class FilesRecipe {
      * lowering builds an internal Recipe that throws the same `GislConfigError`.
      */
     compress(optimize?: OptimizeFor, options?: Record<string, unknown>): FilesRecipe;
-    /** Change every input's format. `format` lowers verbatim to the `format` option. */
+    /** Change every input's format. `format` lowers to the contract `output_format` wire key (via {@link Recipe.convert}), NOT `format`. */
     convert(format: string, options?: Record<string, unknown>): FilesRecipe;
     /** Generate a preview of every input. Omitted dimensions are dropped from the wire options. */
     thumbnail(options?: {

package/dist/file-first.js

@@ -785,7 +785,7 @@ export class FilesRecipe {
     compress(optimize, options = {}) {
         return this.withStep(this.baseRecipe().compress(optimize, options));
     }
-    /** Change every input's format. `format` lowers verbatim to the `format` option. */
+    /** Change every input's format. `format` lowers to the contract `output_format` wire key (via {@link Recipe.convert}), NOT `format`. */
     convert(format, options = {}) {
         return this.withStep(this.baseRecipe().convert(format, options));
     }

package/dist/index.core.d.ts

@@ -1,6 +1,6 @@
 export { GislClient, DEFAULT_MULTIPART_FIRST_CHUNK_SIZE } from './client.js';
 export { parseSseStream } from './sse.js';
-export type { CreditsUsageOptions, ListWorkflowsOptions, GetSchemaOptions, GetSchemaResult, PreflightClipError, PreflightClipsResult, GislClientConfig, GislSseEvent, UploadOptions, WaitOptions, WorkflowCreatePayload, OperationDef, WorkflowSourcePayload, MultiInputSourcePayload, UploadSourcePayload, JobOutputSourcePayload, ExternalImportSourcePayload, ConnectionSourcePayload, JobInputV2Payload, JobDefinitionPayload, ExternalDestinationPayload, DeliveryPayload, DeliveryModePayload, DeliveryBundleFormatPayload, DeliverySelectionPayload, DeliverySelectionTypePayload, DeliveryOutputRefPayload, WorkflowProcessingPayload, ProcessingClassHintPayload, MultipartCheckpointState, _Sdk3HandCodedUploadedPart, _Sdk3HandCodedMultipartStatusResult, _Sdk3HandCodedPresignedPart, _Sdk3HandCodedPresignPartsResult, _Sdk3HandCodedKeepaliveResult, } from './types.js';
+export type { CreditsUsageOptions, ListWorkflowsOptions, GetSchemaOptions, GetSchemaResult, PreflightClipError, PreflightClipsResult, ProbeWaitOptions, ProbeWaitResult, GislClientConfig, GislSseEvent, UploadOptions, WaitOptions, WorkflowCreatePayload, OperationDef, WorkflowSourcePayload, MultiInputSourcePayload, UploadSourcePayload, JobOutputSourcePayload, ExternalImportSourcePayload, ConnectionSourcePayload, JobInputV2Payload, JobDefinitionPayload, ExternalDestinationPayload, DeliveryPayload, DeliveryModePayload, DeliveryBundleFormatPayload, DeliverySelectionPayload, DeliverySelectionTypePayload, DeliveryOutputRefPayload, WorkflowProcessingPayload, ProcessingClassHintPayload, MultipartCheckpointState, _Sdk3HandCodedUploadedPart, _Sdk3HandCodedMultipartStatusResult, _Sdk3HandCodedPresignedPart, _Sdk3HandCodedPresignPartsResult, _Sdk3HandCodedKeepaliveResult, } from './types.js';
 export { uploadSource, jobOutputSource, externalImportSource, connectionSource, } from './types.js';
 export type { GislConfigErrorMetadata } from './errors.js';
 export { GislError, GislApiError, GislValidationError, GislBalanceExhaustedError, GislTierRestrictedError, GislFeatureTierRestrictedError, GislFeatureNotAvailableError, GislWorkflowExpiredError, GislProbePendingError, GislAuthError, GislUploadCapExceededError, GislMultipartPartError, GislMultipartPartCountError, GislMultipartSessionNotFoundError, GislMultipartSessionOwnershipError, GislMultipartSessionAuthRequiredError, GislTimeoutError, GislAbortError, GislNetworkError, GislConfigError, GislMissingCredentialsError, GislFeatureRequiresAuthError, GislUndeclaredAssetError, GislUnusedAssetError, GislPerInputOptionsNotSupportedError, GislChainCardinalityMismatchError, GislBundleAlreadyArchivedError, GislNoSuchKeyError, GislSinkError, GislResultNotReadyError, } from './errors.js';

package/dist/types.d.ts

@@ -287,6 +287,43 @@ export interface WaitOptions {
     /** Called after each poll with current status */
     onPoll?: (status: string) => void;
 }
+export interface ProbeWaitOptions {
+    /**
+     * Overall wall-clock bound for the poll loop in ms (default: 30000). On
+     * elapse the loop gives up and resolves `{ landed: false, reason: 'timeout' }`
+     * — it never throws for a slow probe (the caller then creates anyway).
+     */
+    timeoutMs?: number;
+    /** Abort the wait early; aborting rejects the promise with `GislAbortError`. */
+    signal?: AbortSignal;
+    /**
+     * Fires once per poll attempt — drive an "analysing video…" UI in the gap
+     * between upload-complete and workflow-create. `attempt` is 1-based;
+     * `elapsedMs` is wall-clock since the wait started.
+     */
+    onPoll?: (info: {
+        attempt: number;
+        elapsedMs: number;
+    }) => void;
+}
+export interface ProbeWaitResult {
+    /**
+     * True iff the probe landed — i.e. `POST /api/uploads/{id}/probe` returned
+     * 200 (ANY `probeStatus`: ok / corrupt / unsupported_codec / missing_metadata).
+     * The caller proceeds to create the workflow either way; a landed probe lets
+     * the server admit the parallel video split.
+     */
+    landed: boolean;
+    /** The landed probe response — present iff `landed`. */
+    probe?: UploadProbeResponse;
+    /**
+     * Why the wait gave up WITHOUT a landed probe — present iff `!landed`.
+     * `timeout` = the bound elapsed; `prober_error` = repeated 5xx from the
+     * prober. In both cases the caller should create anyway (never-bounce); the
+     * server's size heuristic routes the job (single-task worst case).
+     */
+    reason?: 'timeout' | 'prober_error';
+}
 export type GislSseEvent = {
     event: typeof SseEventType.operation_progress;
     data: SseOperationProgressData;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@giveitsmaller/sdk",
-  "version": "0.12.1",
+  "version": "0.13.0",
   "description": "Node.js SDK for the GISL (Give It Smaller) file compression and processing API",
   "license": "MIT",
   "type": "module",
@@ -31,7 +31,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@giveitsmaller/contracts": "^0.17.0"
+    "@giveitsmaller/contracts": "^0.18.0"
   },
   "devDependencies": {
     "@types/node": "^22",