@giveitsmaller/sdk 0.13.0 → 0.15.0

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

@@ -352,6 +352,21 @@ export declare class GislClient {
      * 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

@@ -2136,6 +2136,21 @@ export class GislClient {
                 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

@@ -1,8 +1,14 @@
 import type { ResolvedOptions } from '../builder.js';
 import type { OptimizeFor } from '../generated/sdk_spec/enums.js';
 import { type PresetDefaults, type PresetMedia, type PresetOp } from './presets/index.js';
-/** Bumped on any change to a `*PresetOptions.shippedDefaultsFor(...)` cell value. */
-export declare const PRESET_VERSION = "1.0";
+/**
+ * Bumped on any change to a `*PresetOptions.shippedDefaultsFor(...)` cell value.
+ * Must track the contracts `sdk-spec/version.yaml` `presetVersion` (mirrored in
+ * the generated `sdk_spec/version.ts`). 1.0 → 1.2 on the contracts v2.71.0
+ * (video_compress `audioBitrate` dropped) + v2.73.0 (image Size/Balanced
+ * `outputFormat` Smallest/Auto → Original — VcPeRWdD facade self-422 guard) cuts.
+ */
+export declare const PRESET_VERSION = "1.2";
 /**
  * Inputs to {@link resolveCompressOptions}. `media` selects which leaf
  * DTO drives sdkDefault + clientDefault lookups + invalid-combo

package/dist/ergonomic/preset_resolver.js

@@ -37,8 +37,14 @@
 import { sha256Hex } from '../sha256.js';
 import { GislConfigError } from '../errors.js';
 import { ImageCompressPresetOptions, AudioCompressPresetOptions, VideoCompressPresetOptions, DocumentPdfCompressPresetOptions, DocumentOfficeCompressPresetOptions, DocumentOdfCompressPresetOptions, DocumentEpubCompressPresetOptions, } from './presets/index.js';
-/** Bumped on any change to a `*PresetOptions.shippedDefaultsFor(...)` cell value. */
-export const PRESET_VERSION = '1.0';
+/**
+ * Bumped on any change to a `*PresetOptions.shippedDefaultsFor(...)` cell value.
+ * Must track the contracts `sdk-spec/version.yaml` `presetVersion` (mirrored in
+ * the generated `sdk_spec/version.ts`). 1.0 → 1.2 on the contracts v2.71.0
+ * (video_compress `audioBitrate` dropped) + v2.73.0 (image Size/Balanced
+ * `outputFormat` Smallest/Auto → Original — VcPeRWdD facade self-422 guard) cuts.
+ */
+export const PRESET_VERSION = '1.2';
 // ---------------------------------------------------------------------------
 // Wire-field alias map (declarative — NOT generic toSnakeCase).
 // ---------------------------------------------------------------------------

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
@@ -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);
@@ -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/generated/sdk_spec/presets.js

@@ -9,7 +9,7 @@ export const PRESETS = Object.freeze({
             "metadata": "All",
             "iccProfile": "Strip",
             "progressive": true,
-            "outputFormat": "Smallest",
+            "outputFormat": "Original",
         }),
         Balanced: Object.freeze({
             "mode": "Auto",
@@ -17,7 +17,7 @@ export const PRESETS = Object.freeze({
             "metadata": "Sensitive",
             "iccProfile": "Preserve",
             "progressive": true,
-            "outputFormat": "Auto",
+            "outputFormat": "Original",
         }),
         Quality: Object.freeze({
             "mode": "Lossless",
@@ -48,17 +48,14 @@ export const PRESETS = Object.freeze({
         Size: Object.freeze({
             "crf": 30,
             "preset": "Slow",
-            "audioBitrate": "_96",
         }),
         Balanced: Object.freeze({
             "crf": 23,
             "preset": "Medium",
-            "audioBitrate": "_128",
         }),
         Quality: Object.freeze({
             "crf": 18,
             "preset": "Slow",
-            "audioBitrate": "_192",
         }),
     }),
     "document_pdf_compress": Object.freeze({

package/dist/generated/sdk_spec/version.d.ts

@@ -1,3 +1,3 @@
-export declare const SDK_SPEC_VERSION: "1.5.0";
-export declare const PRESET_VERSION: "1.0";
-export declare const PRESET_CONFIG_HASH: "sha256:3791bd2d0cd474c5029707f6e50480bf49be33899f7fc5c1a4e77edb136f6e95";
+export declare const SDK_SPEC_VERSION: "1.7.0";
+export declare const PRESET_VERSION: "1.2";
+export declare const PRESET_CONFIG_HASH: "sha256:ef4d66a81920cec353633d788061a03f7c8891d622908c1bfca326679725e72b";

package/dist/generated/sdk_spec/version.js

@@ -1,6 +1,6 @@
 // CODE GENERATED — DO NOT EDIT.
 // Source: compression_contracts/sdk-spec/ (see sdk-spec/README.md).
 // Regenerate with: scripts/generate.py.
-export const SDK_SPEC_VERSION = "1.5.0";
-export const PRESET_VERSION = "1.0";
-export const PRESET_CONFIG_HASH = "sha256:3791bd2d0cd474c5029707f6e50480bf49be33899f7fc5c1a4e77edb136f6e95";
+export const SDK_SPEC_VERSION = "1.7.0";
+export const PRESET_VERSION = "1.2";
+export const PRESET_CONFIG_HASH = "sha256:ef4d66a81920cec353633d788061a03f7c8891d622908c1bfca326679725e72b";

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@giveitsmaller/sdk",
-  "version": "0.13.0",
+  "version": "0.15.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.18.0"
+    "@giveitsmaller/contracts": "^0.19.0"
   },
   "devDependencies": {
     "@types/node": "^22",