@giveitsmaller/sdk 0.12.1 → 0.14.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/builder.d.ts

@@ -253,10 +253,26 @@ export interface RunOptions {
     readonly useSSE?: boolean;
     /** Override the poll interval used by the fallback (ms). */
     readonly pollIntervalMs?: number;
+    /**
+     * Best-effort probe-before-create for a VIDEO upload that went multipart:
+     * after upload, before createWorkflow, wait for the server's probe to land
+     * so it admits the parallel video split. Default `true`; set `false` to
+     * skip the wait entirely. Never-bounce — a give-up just proceeds to create.
+     */
+    readonly probeBeforeCreate?: boolean;
+    /** Overall timeout (ms) for the probe-before-create wait. */
+    readonly probeTimeoutMs?: number;
 }
 export interface SubmitOptions {
     /** Webhook URL — wired to `WorkflowCreateRequest.callback_url`. */
     readonly webhook: string;
+    /**
+     * Best-effort probe-before-create for a VIDEO upload that went multipart.
+     * Default `true`; set `false` to skip the wait. See {@link RunOptions}.
+     */
+    readonly probeBeforeCreate?: boolean;
+    /** Overall timeout (ms) for the probe-before-create wait. */
+    readonly probeTimeoutMs?: number;
 }
 /**
  * Captures the (op-type, input, options) tuple for one ergonomic-layer
@@ -405,6 +421,17 @@ export declare function _projectResult(status: WorkflowStatusResponse, jobDownlo
 }[], appliedOptions: Record<string, unknown>, resolvedOptionsOverride?: ResolvedOptions): Result;
 /** @internal — exported for reuse by `merge.ts` (T3) and future builders. */
 export declare function _checkAborted(signal: AbortSignal | undefined): void;
+/**
+ * Cap a best-effort probe-before-create timeout to the remaining `maxWait`
+ * budget so the probe wait can never push createWorkflow past the caller's
+ * deadline. Under a deadline an UNSET `probeTimeoutMs` becomes the remaining
+ * budget (never the 30s waitForProbe default); a set value is clamped to the
+ * remaining budget. With no deadline (the `submit()` fire-and-forget path),
+ * `probeTimeoutMs` passes through unchanged.
+ *
+ * @internal — exported for reuse by `file-first.ts` + `merge.ts`.
+ */
+export declare function _cappedProbeTimeoutMs(probeTimeoutMs: number | undefined, deadline: number | undefined): number | undefined;
 /**
  * Parse a `maxWait` argument: number = milliseconds; string with suffix
  * `ms` / `s` / `m` / `h`. Throws if the string is malformed.

package/dist/builder.js

@@ -275,6 +275,24 @@ export class OperationBuilder {
         if (Date.now() >= deadline) {
             throw new GislTimeoutError(`Upload completed but maxWait elapsed before workflow could be created`);
         }
+        // Best-effort probe-before-create for a multipart video upload (never-bounce).
+        // Capped to the remaining maxWait budget so a slow probe cannot push
+        // createWorkflow past the caller's deadline.
+        await this.client.maybeWaitForVideoProbe(uploadResp.fileId, {
+            enabled: options.probeBeforeCreate ?? true,
+            isVideo: _detectCompressMedia(this.input) === 'video',
+            sizeBytes: uploadResp.sizeBytes,
+            timeoutMs: _cappedProbeTimeoutMs(options.probeTimeoutMs, deadline),
+            signal,
+        });
+        // A cancel arriving during the FINAL successful probe request must not still
+        // create the workflow (maybeWaitForVideoProbe returns landed without a final
+        // abort re-check), so check here BEFORE createWorkflow.
+        _checkAborted(signal);
+        // RE-CHECK the deadline AFTER the probe wait (it consumes time).
+        if (Date.now() >= deadline) {
+            throw new GislTimeoutError('Probe wait completed but maxWait elapsed before workflow could be created');
+        }
         // 2. Build + create the workflow.
         const job = {
             id: 'op',
@@ -320,6 +338,13 @@ export class OperationBuilder {
         // call before the upload — same fail-early contract as run().
         const resolved = this._resolve();
         const uploadResp = await this.client.uploadFile(this.input);
+        // Best-effort probe-before-create for a multipart video upload (never-bounce).
+        await this.client.maybeWaitForVideoProbe(uploadResp.fileId, {
+            enabled: options.probeBeforeCreate ?? true,
+            isVideo: _detectCompressMedia(this.input) === 'video',
+            sizeBytes: uploadResp.sizeBytes,
+            timeoutMs: options.probeTimeoutMs,
+        });
         const job = {
             id: 'op',
             source: uploadSource(uploadResp.fileId),
@@ -759,6 +784,23 @@ export function _checkAborted(signal) {
         throw new DOMException('Aborted', 'AbortError');
     }
 }
+/**
+ * Cap a best-effort probe-before-create timeout to the remaining `maxWait`
+ * budget so the probe wait can never push createWorkflow past the caller's
+ * deadline. Under a deadline an UNSET `probeTimeoutMs` becomes the remaining
+ * budget (never the 30s waitForProbe default); a set value is clamped to the
+ * remaining budget. With no deadline (the `submit()` fire-and-forget path),
+ * `probeTimeoutMs` passes through unchanged.
+ *
+ * @internal — exported for reuse by `file-first.ts` + `merge.ts`.
+ */
+export function _cappedProbeTimeoutMs(probeTimeoutMs, deadline) {
+    if (deadline === undefined) {
+        return probeTimeoutMs;
+    }
+    const remaining = Math.max(0, deadline - Date.now());
+    return probeTimeoutMs !== undefined ? Math.min(probeTimeoutMs, remaining) : remaining;
+}
 async function sleep(ms, signal) {
     return await new Promise((resolve, reject) => {
         const t = setTimeout(() => {

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,67 @@ 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): Promise<UploadProbeResponse>;
+    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.
+     */
+    waitForProbe(fileId: string, options?: ProbeWaitOptions): Promise<ProbeWaitResult>;
+    /**
+     * Best-effort probe-before-create for a VIDEO upload that went multipart.
+     * No-op unless enabled AND isVideo AND the upload exceeded the multipart
+     * threshold (i.e. it was a multipart upload — small single-shot videos skip
+     * the wait). Delegates to {@link waitForProbe} (never-bounce): a give-up just
+     * returns; genuine failures / caller abort propagate. The caller passes
+     * `isVideo` so the low-level client never imports ergonomic media detection.
+     */
+    maybeWaitForVideoProbe(fileId: string, opts: {
+        enabled: boolean;
+        isVideo: boolean;
+        sizeBytes?: number;
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<void>;
     /**
      * 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,133 @@ 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' };
+        }
+    }
+    /**
+     * Best-effort probe-before-create for a VIDEO upload that went multipart.
+     * No-op unless enabled AND isVideo AND the upload exceeded the multipart
+     * threshold (i.e. it was a multipart upload — small single-shot videos skip
+     * the wait). Delegates to {@link waitForProbe} (never-bounce): a give-up just
+     * returns; genuine failures / caller abort propagate. The caller passes
+     * `isVideo` so the low-level client never imports ergonomic media detection.
+     */
+    async maybeWaitForVideoProbe(fileId, opts) {
+        if (!opts.enabled || !opts.isVideo)
+            return;
+        if (opts.sizeBytes === undefined || opts.sizeBytes <= this.multipartThreshold)
+            return;
+        await this.waitForProbe(fileId, { timeoutMs: opts.timeoutMs, signal: opts.signal });
+    }
     /**
      * 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

@@ -396,6 +396,8 @@ export declare class Recipe {
         onProgress?: (event: ProgressEvent) => void;
         signal?: AbortSignal;
         pollIntervalMs?: number;
+        probeBeforeCreate?: boolean;
+        probeTimeoutMs?: number;
     }): Promise<RunResult>;
     /**
      * Fire-and-forget the recipe: upload the input (when required), create the
@@ -409,8 +411,14 @@ export declare class Recipe {
      * sent. Mirrors the PHP `Recipe.submit()`.
      *
      * @param webhook Absolute callback URL the server POSTs lifecycle events to.
+     * @param options Opt-out (`probeBeforeCreate: false`) / tune (`probeTimeoutMs`)
+     *   the best-effort video probe-before-create. Kept as a 2nd optional param so
+     *   the existing positional `webhook` arg stays backward compatible.
      */
-    submit(webhook?: string): Promise<Handle>;
+    submit(webhook?: string, options?: {
+        probeBeforeCreate?: boolean;
+        probeTimeoutMs?: number;
+    }): Promise<Handle>;
     /**
      * Resolve the upload id (verbatim for a pre-uploaded id; uploading a path /
      * blob otherwise, emitting `{phase:'upload'}` progress), check the post-upload
@@ -466,7 +474,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?: {
@@ -530,6 +538,8 @@ export declare class FilesRecipe {
         onProgress?: (event: ProgressEvent) => void;
         signal?: AbortSignal;
         pollIntervalMs?: number;
+        probeBeforeCreate?: boolean;
+        probeTimeoutMs?: number;
     }): Promise<RunResult>;
     /**
      * Fire-and-forget the fan-out: upload every input, create ONE multi-job
@@ -546,8 +556,13 @@ export declare class FilesRecipe {
      * Mirrors the single-file {@link Recipe.submit}.
      *
      * @param webhook Absolute callback URL the server POSTs lifecycle events to.
+     * @param options Opt-out / tune the best-effort video probe-before-create
+     *   (2nd optional param so the positional `webhook` arg stays compatible).
      */
-    submit(webhook?: string): Promise<Handle>;
+    submit(webhook?: string, options?: {
+        probeBeforeCreate?: boolean;
+        probeTimeoutMs?: number;
+    }): Promise<Handle>;
     /**
      * Upload every input (verbatim for a pre-uploaded id; uploading a path /
      * blob otherwise, emitting `{phase:'upload'}` progress) then create ONE
@@ -633,13 +648,22 @@ export declare class MergedRecipe {
         onProgress?: (event: ProgressEvent) => void;
         signal?: AbortSignal;
         pollIntervalMs?: number;
+        probeBeforeCreate?: boolean;
+        probeTimeoutMs?: number;
     }): Promise<RunResult>;
     /**
      * Fire-and-forget: upload + create the merge workflow (wiring `webhook` into
      * `callback_url` when given), return a client-bound {@link Handle}. Does NOT
      * wait for terminal status. Mirrors {@link Recipe.submit}.
+     *
+     * @param webhook Absolute callback URL the server POSTs lifecycle events to.
+     * @param options Opt-out / tune the best-effort video probe-before-create
+     *   (2nd optional param so the positional `webhook` arg stays compatible).
      */
-    submit(webhook?: string): Promise<Handle>;
+    submit(webhook?: string, options?: {
+        probeBeforeCreate?: boolean;
+        probeTimeoutMs?: number;
+    }): Promise<Handle>;
     /**
      * Upload every input (verbatim for a pre-uploaded id; uploading a path / blob
      * otherwise, emitting `{phase:'upload'}` progress) then create ONE merge
@@ -723,13 +747,22 @@ export declare class ArchivedRecipe {
         onProgress?: (event: ProgressEvent) => void;
         signal?: AbortSignal;
         pollIntervalMs?: number;
+        probeBeforeCreate?: boolean;
+        probeTimeoutMs?: number;
     }): Promise<RunResult>;
     /**
      * Fire-and-forget: upload + create the archive workflow (wiring `webhook` into
      * `callback_url` when given), return a client-bound {@link Handle}. Mirrors
      * {@link MergedRecipe.submit}.
+     *
+     * @param webhook Absolute callback URL the server POSTs lifecycle events to.
+     * @param options Opt-out / tune the best-effort video probe-before-create
+     *   (2nd optional param so the positional `webhook` arg stays compatible).
      */
-    submit(webhook?: string): Promise<Handle>;
+    submit(webhook?: string, options?: {
+        probeBeforeCreate?: boolean;
+        probeTimeoutMs?: number;
+    }): Promise<Handle>;
     private _uploadAllAndCreate;
     /**
      * Reject an invalid bundle BEFORE any upload fires — the archive schema allows

package/dist/file-first.js

@@ -10,7 +10,7 @@
  * Mirrors `packages/php/src/FileFirst/*`.
  */
 import { GislConfigError, GislNetworkError, GislNoSuchKeyError, GislSinkError, GislTimeoutError, SseEndedWithoutTerminal } from './errors.js';
-import { _detectCompressMedia, _detectAudioLossless, _consumeSseToTerminal, _pollToTerminal, _parseMaxWait, _checkAborted, } from './builder.js';
+import { _detectCompressMedia, _detectAudioLossless, _consumeSseToTerminal, _pollToTerminal, _parseMaxWait, _checkAborted, _cappedProbeTimeoutMs, } from './builder.js';
 import { LazyHttpDownloader } from './lazy-downloader.js';
 import { resolveCompressOptions, } from './ergonomic/preset_resolver.js';
 import { OptimizeFor } from './generated/sdk_spec/enums.js';
@@ -529,7 +529,7 @@ export class Recipe {
         const deadline = Date.now() + _parseMaxWait(options.maxWait ?? 300_000);
         // 1+2. Upload (when required) + create the workflow. Shared with submit()
         // (which passes a webhook → callback_url). run() passes no webhook.
-        const created = await this._uploadAndCreate(undefined, deadline, onProgress, signal);
+        const created = await this._uploadAndCreate(undefined, deadline, onProgress, signal, options.probeBeforeCreate, options.probeTimeoutMs);
         // 3. Wait to terminal status — SSE first, poll on a genuine SSE error.
         // Caller-aborted + deadline-elapsed errors MUST propagate (not transient).
         let finalStatus;
@@ -587,8 +587,11 @@ export class Recipe {
      * sent. Mirrors the PHP `Recipe.submit()`.
      *
      * @param webhook Absolute callback URL the server POSTs lifecycle events to.
+     * @param options Opt-out (`probeBeforeCreate: false`) / tune (`probeTimeoutMs`)
+     *   the best-effort video probe-before-create. Kept as a 2nd optional param so
+     *   the existing positional `webhook` arg stays backward compatible.
      */
-    async submit(webhook) {
+    async submit(webhook, options) {
         if (this.client === undefined) {
             throw new GislConfigError('Recipe.submit() requires a client; build the recipe via gisl().file(...) rather than constructing Recipe directly.', { reason: 'no_client' });
         }
@@ -597,7 +600,7 @@ export class Recipe {
         // own request timeout, not an arbitrary submit-side cap. Pass `undefined`
         // so the post-upload deadline check is skipped: a 300s cap here would throw
         // on a slow-but-successful big upload before createWorkflow (codex).
-        const created = await this._uploadAndCreate(webhook, undefined);
+        const created = await this._uploadAndCreate(webhook, undefined, undefined, undefined, options?.probeBeforeCreate, options?.probeTimeoutMs);
         return new Handle(created.workflowId, created.webhookSecret != null ? created.webhookSecret : undefined, this.client, this.recipeKey ?? null);
     }
     /**
@@ -610,10 +613,13 @@ export class Recipe {
      * The post-upload deadline check carries a prior codex fix (9a117f04eb59): a
      * slow upload must not proceed to createWorkflow past the deadline.
      */
-    async _uploadAndCreate(webhook, deadline, onProgress, signal) {
+    async _uploadAndCreate(webhook, deadline, onProgress, signal, probeBeforeCreate, probeTimeoutMs) {
         // 1. Resolve the upload id. A pre-uploaded id skips the upload entirely;
         // a path / blob is uploaded now, emitting {phase:'upload'} progress.
         let fileId;
+        // A pre-uploaded id carries no local mime/size, so the video probe-gate is
+        // skipped for it (no `up` to read sizeBytes from).
+        let uploadSizeBytes;
         if (this.input.kind === 'uploadId') {
             fileId = this.input.fileId;
         }
@@ -630,6 +636,7 @@ export class Recipe {
                     : {}),
             });
             fileId = up.fileId;
+            uploadSizeBytes = up.sizeBytes;
         }
         _checkAborted(signal);
         // run() passes a whole-run deadline (the codex 9a117f04eb59 fix: a slow
@@ -638,6 +645,35 @@ export class Recipe {
         if (deadline !== undefined && Date.now() >= deadline) {
             throw new GislTimeoutError('Upload completed but maxWait elapsed before workflow could be created');
         }
+        // Best-effort probe-before-create: for a VIDEO upload that went multipart,
+        // let the server see the codec + duration before createWorkflow so it
+        // admits the ~3× parallel split. Never-bounce — a give-up just proceeds.
+        // The probe wait is CAPPED to the remaining maxWait budget so a slow probe
+        // cannot push createWorkflow past the caller's deadline (an unset
+        // probeTimeoutMs under a deadline becomes the remaining budget, never the
+        // 30s default).
+        // Skip a pre-uploaded (`uploadId`) input entirely — no local mime/size to
+        // gate on (mirrors the multi-input seams, which omit uploadId inputs from
+        // their probe targets).
+        if (this.input.kind !== 'uploadId') {
+            await this.client.maybeWaitForVideoProbe(fileId, {
+                enabled: probeBeforeCreate ?? true,
+                isVideo: this.compressMediaHint() === 'video',
+                sizeBytes: uploadSizeBytes,
+                timeoutMs: _cappedProbeTimeoutMs(probeTimeoutMs, deadline),
+                signal,
+            });
+        }
+        // A cancel arriving during the FINAL successful probe request must not still
+        // create the workflow (maybeWaitForVideoProbe returns landed without a final
+        // abort re-check), so check here BEFORE createWorkflow.
+        _checkAborted(signal);
+        // RE-CHECK the deadline AFTER the probe wait: the wait itself consumes time,
+        // so a workflow must not be created past maxWait even when the wait was
+        // capped (mirrors the post-upload check above).
+        if (deadline !== undefined && Date.now() >= deadline) {
+            throw new GislTimeoutError('Probe wait completed but maxWait elapsed before workflow could be created');
+        }
         // 2. Create the workflow from the lowered payload (callback_url built into
         // the payload at construction when a webhook is given).
         const payload = this.toWorkflowPayload(fileId, webhook);
@@ -785,7 +821,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));
     }
@@ -884,7 +920,7 @@ export class FilesRecipe {
         const deadline = Date.now() + _parseMaxWait(options.maxWait ?? 300_000);
         // 1+2. Upload EVERY input + create ONE multi-job workflow. Shared with
         // submit() (which passes a webhook → callback_url and no deadline).
-        const created = await this._uploadAllAndCreate(undefined, deadline, onProgress, signal);
+        const created = await this._uploadAllAndCreate(undefined, deadline, onProgress, signal, options.probeBeforeCreate, options.probeTimeoutMs);
         // 3. Wait to terminal status — SSE first, poll on a genuine SSE error.
         // `partially_failed` is a normal terminal state here (the helper treats it
         // as terminal); only caller-aborted / deadline / API errors propagate.
@@ -941,12 +977,14 @@ export class FilesRecipe {
      * Mirrors the single-file {@link Recipe.submit}.
      *
      * @param webhook Absolute callback URL the server POSTs lifecycle events to.
+     * @param options Opt-out / tune the best-effort video probe-before-create
+     *   (2nd optional param so the positional `webhook` arg stays compatible).
      */
-    async submit(webhook) {
+    async submit(webhook, options) {
         if (this.client === undefined) {
             throw new GislConfigError('FilesRecipe.submit() requires a client; build the fan-out via gisl().files(...) rather than constructing FilesRecipe directly.', { reason: 'no_client' });
         }
-        const created = await this._uploadAllAndCreate(webhook, undefined);
+        const created = await this._uploadAllAndCreate(webhook, undefined, undefined, undefined, options?.probeBeforeCreate, options?.probeTimeoutMs);
         return new Handle(created.workflowId, created.webhookSecret != null ? created.webhookSecret : undefined, this.client, null);
     }
     /**
@@ -961,8 +999,11 @@ export class FilesRecipe {
      * createWorkflow past maxWait); `submit()` passes `undefined`, so the
      * deadline checks are skipped.
      */
-    async _uploadAllAndCreate(webhook, deadline, onProgress, signal) {
+    async _uploadAllAndCreate(webhook, deadline, onProgress, signal, probeBeforeCreate, probeTimeoutMs) {
         const fileIds = [];
+        // Track each freshly-uploaded input's probe-gate inputs (a pre-uploaded id
+        // carries no local mime/size, so it is excluded — never probed).
+        const probeTargets = [];
         for (const input of this.inputs) {
             // Fail fast between uploads — a deadline that elapses mid-batch should
             // not force every remaining input to upload before throwing.
@@ -986,12 +1027,39 @@ export class FilesRecipe {
                         : {}),
                 });
                 fileIds.push(up.fileId);
+                probeTargets.push({
+                    fileId: up.fileId,
+                    isVideo: _detectCompressMedia(source) === 'video',
+                    sizeBytes: up.sizeBytes,
+                });
             }
         }
         _checkAborted(signal);
         if (deadline !== undefined && Date.now() >= deadline) {
             throw new GislTimeoutError('Uploads completed but maxWait elapsed before workflow could be created');
         }
+        // Best-effort probe-before-create for the multipart-video inputs. Run the
+        // waits CONCURRENTLY (Promise.all): each is bounded by the SAME capped
+        // timeout, so the aggregate wall-clock stays ~timeout rather than N×timeout.
+        // The cap is the remaining maxWait budget so the waits cannot push
+        // createWorkflow past the caller's deadline. Never-bounce, so a give-up
+        // just proceeds.
+        const cappedProbeTimeoutMs = _cappedProbeTimeoutMs(probeTimeoutMs, deadline);
+        await Promise.all(probeTargets.map((t) => this.client.maybeWaitForVideoProbe(t.fileId, {
+            enabled: probeBeforeCreate ?? true,
+            isVideo: t.isVideo,
+            sizeBytes: t.sizeBytes,
+            timeoutMs: cappedProbeTimeoutMs,
+            signal,
+        })));
+        // A cancel arriving during a FINAL successful probe request must not still
+        // create the workflow (the probe waits return landed without a final abort
+        // re-check), so check here BEFORE createWorkflow.
+        _checkAborted(signal);
+        // RE-CHECK the deadline AFTER the probe waits (they consume time).
+        if (deadline !== undefined && Date.now() >= deadline) {
+            throw new GislTimeoutError('Probe wait completed but maxWait elapsed before workflow could be created');
+        }
         const created = await this.client.createWorkflow(this.toWorkflowPayload(fileIds, webhook));
         _checkAborted(signal);
         return created;
@@ -1129,7 +1197,7 @@ export class MergedRecipe {
             throw new GislConfigError('MergedRecipe.run() requires a client; build the merge via gisl().files(...).merge(...) rather than constructing MergedRecipe directly.', { reason: 'no_client' });
         }
         const deadline = Date.now() + _parseMaxWait(options.maxWait ?? 300_000);
-        const created = await this._uploadAllAndCreate(undefined, deadline, onProgress, signal);
+        const created = await this._uploadAllAndCreate(undefined, deadline, onProgress, signal, options.probeBeforeCreate, options.probeTimeoutMs);
         let finalStatus;
         try {
             finalStatus = await _consumeSseToTerminal(this.client, {
@@ -1170,12 +1238,16 @@ export class MergedRecipe {
      * Fire-and-forget: upload + create the merge workflow (wiring `webhook` into
      * `callback_url` when given), return a client-bound {@link Handle}. Does NOT
      * wait for terminal status. Mirrors {@link Recipe.submit}.
+     *
+     * @param webhook Absolute callback URL the server POSTs lifecycle events to.
+     * @param options Opt-out / tune the best-effort video probe-before-create
+     *   (2nd optional param so the positional `webhook` arg stays compatible).
      */
-    async submit(webhook) {
+    async submit(webhook, options) {
         if (this.client === undefined) {
             throw new GislConfigError('MergedRecipe.submit() requires a client; build the merge via gisl().files(...).merge(...) rather than constructing MergedRecipe directly.', { reason: 'no_client' });
         }
-        const created = await this._uploadAllAndCreate(webhook, undefined);
+        const created = await this._uploadAllAndCreate(webhook, undefined, undefined, undefined, options?.probeBeforeCreate, options?.probeTimeoutMs);
         return new Handle(created.workflowId, created.webhookSecret != null ? created.webhookSecret : undefined, this.client, null);
     }
     // ---------------------------------------------------------------------------
@@ -1185,9 +1257,13 @@ export class MergedRecipe {
      * workflow. Rejects fewer than 2 inputs BEFORE any upload fires. Shared first
      * half of {@link run} + {@link submit}.
      */
-    async _uploadAllAndCreate(webhook, deadline, onProgress, signal) {
+    async _uploadAllAndCreate(webhook, deadline, onProgress, signal, probeBeforeCreate, probeTimeoutMs) {
         this.validatePreUpload();
         const fileIds = [];
+        // Per-input video detection: merge's inferMediaKind decides the OUTPUT
+        // media, not each input's, so detect per input via _detectCompressMedia.
+        // A pre-uploaded id carries no local mime/size, so it is never probed.
+        const probeTargets = [];
         for (const input of this.inputs) {
             _checkAborted(signal);
             if (deadline !== undefined && Date.now() >= deadline) {
@@ -1209,12 +1285,36 @@ export class MergedRecipe {
                         : {}),
                 });
                 fileIds.push(up.fileId);
+                probeTargets.push({
+                    fileId: up.fileId,
+                    isVideo: _detectCompressMedia(source) === 'video',
+                    sizeBytes: up.sizeBytes,
+                });
             }
         }
         _checkAborted(signal);
         if (deadline !== undefined && Date.now() >= deadline) {
             throw new GislTimeoutError('Uploads completed but maxWait elapsed before the merge workflow could be created');
         }
+        // Best-effort, concurrent probe-before-create for the multipart-video
+        // inputs (never-bounce; each capped to the remaining maxWait budget so the
+        // waits cannot push createWorkflow past the caller's deadline).
+        const cappedProbeTimeoutMs = _cappedProbeTimeoutMs(probeTimeoutMs, deadline);
+        await Promise.all(probeTargets.map((t) => this.client.maybeWaitForVideoProbe(t.fileId, {
+            enabled: probeBeforeCreate ?? true,
+            isVideo: t.isVideo,
+            sizeBytes: t.sizeBytes,
+            timeoutMs: cappedProbeTimeoutMs,
+            signal,
+        })));
+        // A cancel arriving during a FINAL successful probe request must not still
+        // create the workflow (the probe waits return landed without a final abort
+        // re-check), so check here BEFORE createWorkflow.
+        _checkAborted(signal);
+        // RE-CHECK the deadline AFTER the probe waits (they consume time).
+        if (deadline !== undefined && Date.now() >= deadline) {
+            throw new GislTimeoutError('Probe wait completed but maxWait elapsed before the merge workflow could be created');
+        }
         const created = await this.client.createWorkflow(this.toWorkflowPayload(fileIds, webhook));
         _checkAborted(signal);
         return created;
@@ -1369,7 +1469,7 @@ export class ArchivedRecipe {
             throw new GislConfigError('ArchivedRecipe.run() requires a client; build the bundle via gisl().files(...).archive(...) rather than constructing ArchivedRecipe directly.', { reason: 'no_client' });
         }
         const deadline = Date.now() + _parseMaxWait(options.maxWait ?? 300_000);
-        const created = await this._uploadAllAndCreate(undefined, deadline, onProgress, signal);
+        const created = await this._uploadAllAndCreate(undefined, deadline, onProgress, signal, options.probeBeforeCreate, options.probeTimeoutMs);
         let finalStatus;
         try {
             finalStatus = await _consumeSseToTerminal(this.client, {
@@ -1409,18 +1509,26 @@ export class ArchivedRecipe {
      * Fire-and-forget: upload + create the archive workflow (wiring `webhook` into
      * `callback_url` when given), return a client-bound {@link Handle}. Mirrors
      * {@link MergedRecipe.submit}.
+     *
+     * @param webhook Absolute callback URL the server POSTs lifecycle events to.
+     * @param options Opt-out / tune the best-effort video probe-before-create
+     *   (2nd optional param so the positional `webhook` arg stays compatible).
      */
-    async submit(webhook) {
+    async submit(webhook, options) {
         if (this.client === undefined) {
             throw new GislConfigError('ArchivedRecipe.submit() requires a client; build the bundle via gisl().files(...).archive(...) rather than constructing ArchivedRecipe directly.', { reason: 'no_client' });
         }
-        const created = await this._uploadAllAndCreate(webhook, undefined);
+        const created = await this._uploadAllAndCreate(webhook, undefined, undefined, undefined, options?.probeBeforeCreate, options?.probeTimeoutMs);
         return new Handle(created.workflowId, created.webhookSecret != null ? created.webhookSecret : undefined, this.client, null);
     }
     // ---------------------------------------------------------------------------
-    async _uploadAllAndCreate(webhook, deadline, onProgress, signal) {
+    async _uploadAllAndCreate(webhook, deadline, onProgress, signal, probeBeforeCreate, probeTimeoutMs) {
         this.validatePreUpload();
         const fileIds = [];
+        // Archive is media-agnostic (no inference) — detect per input via
+        // _detectCompressMedia so only video uploads are probed. A pre-uploaded id
+        // carries no local mime/size, so it is never probed.
+        const probeTargets = [];
         for (const input of this.inputs) {
             _checkAborted(signal);
             if (deadline !== undefined && Date.now() >= deadline) {
@@ -1442,12 +1550,36 @@ export class ArchivedRecipe {
                         : {}),
                 });
                 fileIds.push(up.fileId);
+                probeTargets.push({
+                    fileId: up.fileId,
+                    isVideo: _detectCompressMedia(source) === 'video',
+                    sizeBytes: up.sizeBytes,
+                });
             }
         }
         _checkAborted(signal);
         if (deadline !== undefined && Date.now() >= deadline) {
             throw new GislTimeoutError('Uploads completed but maxWait elapsed before the archive workflow could be created');
         }
+        // Best-effort, concurrent probe-before-create for the multipart-video
+        // inputs (never-bounce; each capped to the remaining maxWait budget so the
+        // waits cannot push createWorkflow past the caller's deadline).
+        const cappedProbeTimeoutMs = _cappedProbeTimeoutMs(probeTimeoutMs, deadline);
+        await Promise.all(probeTargets.map((t) => this.client.maybeWaitForVideoProbe(t.fileId, {
+            enabled: probeBeforeCreate ?? true,
+            isVideo: t.isVideo,
+            sizeBytes: t.sizeBytes,
+            timeoutMs: cappedProbeTimeoutMs,
+            signal,
+        })));
+        // A cancel arriving during a FINAL successful probe request must not still
+        // create the workflow (the probe waits return landed without a final abort
+        // re-check), so check here BEFORE createWorkflow.
+        _checkAborted(signal);
+        // RE-CHECK the deadline AFTER the probe waits (they consume time).
+        if (deadline !== undefined && Date.now() >= deadline) {
+            throw new GislTimeoutError('Probe wait completed but maxWait elapsed before the archive workflow could be created');
+        }
         const created = await this.client.createWorkflow(this.toWorkflowPayload(fileIds, webhook));
         _checkAborted(signal);
         return created;

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/merge.d.ts

@@ -137,6 +137,15 @@ export declare class MergeBuilder {
     private planSequence;
     private inferMediaKind;
     private uploadUniqueAssets;
+    /**
+     * Best-effort, concurrent probe-before-create for the multipart-video
+     * inputs (never-bounce; each bounded by the SAME capped timeout, so the
+     * aggregate wall-clock stays ~timeout rather than N×timeout). When `deadline`
+     * is set (the `run()` path) the timeout is capped to the remaining maxWait
+     * budget so the waits cannot push createWorkflow past the caller's deadline;
+     * `submit()` passes `undefined` (fire-and-forget, no cap).
+     */
+    private waitForVideoProbes;
     private buildPayload;
     private opOptionsForResolved;
     private awaitTerminal;

package/dist/merge.js

@@ -27,7 +27,7 @@
  */
 import { uploadSource, jobOutputSource } from './types.js';
 import { GislConfigError, GislNetworkError, GislPerInputOptionsNotSupportedError, GislTimeoutError, GislUndeclaredAssetError, GislUnusedAssetError, SseEndedWithoutTerminal, } from './errors.js';
-import { _checkAborted, _consumeSseToTerminal, _parseMaxWait, _pollToTerminal, _projectResult, } from './builder.js';
+import { _cappedProbeTimeoutMs, _checkAborted, _consumeSseToTerminal, _detectCompressMedia, _parseMaxWait, _pollToTerminal, _projectResult, } from './builder.js';
 import { Handle } from './handle.js';
 /**
  * Construct a path-asset. Bare-string arguments to `merge(...)` are
@@ -91,15 +91,28 @@ export class MergeBuilder {
         const plan = this.planSequence();
         // 2. Upload each unique asset exactly ONCE. Pass the deadline so the
         // upload loop can abort mid-batch on a slow connection.
+        const probeTargets = [];
         const uploadedByAssetId = await this.uploadUniqueAssets(plan.uniqueAssets, {
             signal,
             onProgress,
             deadline,
+            probeTargets,
         });
         _checkAborted(signal);
         if (Date.now() >= deadline) {
             throw new GislTimeoutError(`Upload(s) completed but maxWait elapsed before merge workflow could be created`);
         }
+        // Best-effort probe-before-create for the multipart-video inputs (capped to
+        // the remaining maxWait budget).
+        await this.waitForVideoProbes(probeTargets, options.probeBeforeCreate, options.probeTimeoutMs, signal, deadline);
+        // A cancel arriving during a FINAL successful probe request must not still
+        // create the workflow (the probe waits return landed without a final abort
+        // re-check), so check here BEFORE createWorkflow.
+        _checkAborted(signal);
+        // RE-CHECK the deadline AFTER the probe waits (they consume time).
+        if (Date.now() >= deadline) {
+            throw new GislTimeoutError(`Probe wait completed but maxWait elapsed before merge workflow could be created`);
+        }
         // 3. Build the merge JobDefinitionPayload (multi-input).
         const payload = this.buildPayload(plan, uploadedByAssetId);
         const created = await this.client.createWorkflow(payload);
@@ -135,7 +148,11 @@ export class MergeBuilder {
     }
     async submit(options) {
         const plan = this.planSequence();
-        const uploadedByAssetId = await this.uploadUniqueAssets(plan.uniqueAssets, {});
+        const probeTargets = [];
+        const uploadedByAssetId = await this.uploadUniqueAssets(plan.uniqueAssets, { probeTargets });
+        // Best-effort probe-before-create for the multipart-video inputs.
+        // Fire-and-forget — no deadline, so no cap (mirrors Recipe::submit()).
+        await this.waitForVideoProbes(probeTargets, options.probeBeforeCreate, options.probeTimeoutMs, undefined, undefined);
         const payload = this.buildPayload(plan, uploadedByAssetId);
         payload.callback_url = options.webhook;
         const created = await this.client.createWorkflow(payload);
@@ -281,9 +298,32 @@ export class MergeBuilder {
             }
             const resp = await this.client.uploadFile(a.path, uploadOpts);
             uploaded.set(id, resp.fileId);
+            opts.probeTargets?.push({
+                fileId: resp.fileId,
+                isVideo: _detectCompressMedia(a.path) === 'video',
+                sizeBytes: resp.sizeBytes,
+            });
         }
         return uploaded;
     }
+    /**
+     * Best-effort, concurrent probe-before-create for the multipart-video
+     * inputs (never-bounce; each bounded by the SAME capped timeout, so the
+     * aggregate wall-clock stays ~timeout rather than N×timeout). When `deadline`
+     * is set (the `run()` path) the timeout is capped to the remaining maxWait
+     * budget so the waits cannot push createWorkflow past the caller's deadline;
+     * `submit()` passes `undefined` (fire-and-forget, no cap).
+     */
+    async waitForVideoProbes(probeTargets, probeBeforeCreate, probeTimeoutMs, signal, deadline) {
+        const cappedProbeTimeoutMs = _cappedProbeTimeoutMs(probeTimeoutMs, deadline);
+        await Promise.all(probeTargets.map((t) => this.client.maybeWaitForVideoProbe(t.fileId, {
+            enabled: probeBeforeCreate ?? true,
+            isVideo: t.isVideo,
+            sizeBytes: t.sizeBytes,
+            timeoutMs: cappedProbeTimeoutMs,
+            signal,
+        })));
+    }
     buildPayload(plan, uploadedByAssetId) {
         // p0SuJEeK — the API rejects upload-direct multi-input
         // (`MultiInputSource` excludes the `upload` leaf: "use type=job_output").

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.14.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",