@giveitsmaller/sdk 0.9.0 → 0.10.0

package/dist/merge.js

@@ -26,7 +26,7 @@
  * assets both fail fast so the caller saves bandwidth on typo'd composes.
  */
 import { uploadSource, jobOutputSource } from './types.js';
-import { GislConfigError, GislPerInputOptionsNotSupportedError, GislTimeoutError, GislUndeclaredAssetError, GislUnusedAssetError, } from './errors.js';
+import { GislConfigError, GislNetworkError, GislPerInputOptionsNotSupportedError, GislTimeoutError, GislUndeclaredAssetError, GislUnusedAssetError, SseEndedWithoutTerminal, } from './errors.js';
 import { _checkAborted, _consumeSseToTerminal, _parseMaxWait, _pollToTerminal, _projectResult, } from './builder.js';
 import { Handle } from './handle.js';
 /**
@@ -118,6 +118,12 @@ export class MergeBuilder {
             throw new GislTimeoutError(`Merge workflow ${created.workflowId} reached terminal status but maxWait elapsed before downloads could be fetched`);
         }
         const downloads = await this.client.getWorkflowDownloads(created.workflowId);
+        // TDqmkWpX: the maxWait deadline also covers the downloads fetch itself —
+        // re-check AFTER the call so a slow getWorkflowDownloads cannot return a
+        // success past the advertised whole-run deadline.
+        if (Date.now() >= deadline) {
+            throw new GislTimeoutError(`Merge workflow ${created.workflowId} downloads fetch completed after maxWait elapsed`);
+        }
         // p0SuJEeK — project ONLY the merge job's output. getWorkflowDownloads
         // returns a download group per terminal job, which now INCLUDES the
         // `passthrough` source jobs (their output is the unchanged upload). Those
@@ -125,7 +131,7 @@ export class MergeBuilder {
         // would pollute the Result with the raw inputs. The merge job's ref is
         // 'merge' (see buildPayload); the source jobs are 'src_N'.
         const mergeDownloads = downloads.downloads.filter((d) => d.ref === 'merge');
-        return _projectResult(finalStatus, mergeDownloads, this.opOptionsForResolved());
+        return _projectResult(finalStatus, mergeDownloads, this.opOptionsForResolved(plan.mediaKind));
     }
     async submit(options) {
         const plan = this.planSequence();
@@ -202,6 +208,32 @@ export class MergeBuilder {
         if (positions.length > 10) {
             throw new GislConfigError(`merge accepts at most 10 inputs (got ${positions.length}). Reduce the sequence or split the merge.`);
         }
+        // Validate merge-level options BEFORE upload (parity with PHP MergeBuilder).
+        // A `targetSize: 'garbage'` typo must fail locally rather than burning N
+        // uploads before parseSizeString fires from wireMergeOptions().
+        //
+        // Gated to video (codex #176 r3 DCJUvvfA) — `target_size_bytes` only
+        // crosses the wire for video merges (see wireMergeOptions); for image/audio
+        // the field is silently dropped, so validating its string form would reject
+        // a merge over a value that never leaves the SDK.
+        if (mediaKind === 'video' && typeof this.opOptions.targetSize === 'string') {
+            try {
+                parseSizeString(this.opOptions.targetSize);
+            }
+            catch {
+                throw new GislConfigError(`Invalid targetSize string '${this.opOptions.targetSize}' — expected '<num>[B|KB|MB|GB]'.`);
+            }
+        }
+        // Image merges require an `output_type` (the generated merge schema marks
+        // `output_type` required for image kind). Without this check the SDK would
+        // upload all assets then receive a server-side validation failure instead
+        // of a free local one. Parity with PHP MergeBuilder.
+        if (mediaKind === 'image' &&
+            this.opOptions.output == null &&
+            this.opOptions.outputType == null) {
+            throw new GislConfigError('image merges require an explicit output_type — set MergeOptions(output: "video"|"gif") or ' +
+                'MergeOptions(outputType: ...). The server rejects image merge requests with no output_type.');
+        }
         return { mediaKind, positions, uniqueAssets: uploadSet };
     }
     inferMediaKind() {
@@ -308,12 +340,55 @@ export class MergeBuilder {
         };
         return { jobs: [...sourceJobs, mergeJob] };
     }
-    opOptionsForResolved() {
-        // Strip the SDK-only fields before exposing on resolvedOptions.applied.
-        const { mediaKind: _m, allowUnusedAssets: _a, ...rest } = this.opOptions;
-        void _m;
-        void _a;
-        return { ...rest };
+    opOptionsForResolved(mediaKind) {
+        // Mirror wireMergeOptions's per-media allowlist (and PHP
+        // opOptionsForResolved) so resolvedOptions.applied reports ONLY the
+        // options that actually crossed the wire for this media kind — not the
+        // raw option bag (which would falsely claim dropped fields were applied).
+        const o = this.opOptions;
+        const out = {};
+        // All media kinds.
+        if (o.output !== undefined)
+            out.output = o.output;
+        if (o.outputType !== undefined)
+            out.outputType = o.outputType;
+        if (o.transition !== undefined)
+            out.transition = o.transition;
+        // Video + audio.
+        if (mediaKind === 'video' || mediaKind === 'audio') {
+            if (o.crossfadeDuration !== undefined)
+                out.crossfadeDuration = o.crossfadeDuration;
+            if (o.normalizeAudio !== undefined)
+                out.normalizeAudio = o.normalizeAudio;
+        }
+        // Audio only.
+        if (mediaKind === 'audio' && o.gapDuration !== undefined)
+            out.gapDuration = o.gapDuration;
+        // Video only.
+        if (mediaKind === 'video') {
+            if (o.codec !== undefined)
+                out.codec = o.codec;
+            if (o.crf !== undefined)
+                out.crf = o.crf;
+            if (o.preset !== undefined)
+                out.preset = o.preset;
+            if (o.targetSize !== undefined)
+                out.targetSize = o.targetSize;
+        }
+        // Image only.
+        if (mediaKind === 'image') {
+            if (o.transitionDuration !== undefined)
+                out.transitionDuration = o.transitionDuration;
+            if (o.fps !== undefined)
+                out.fps = o.fps;
+            if (o.durationPerImage !== undefined)
+                out.durationPerImage = o.durationPerImage;
+            if (o.loopCount !== undefined)
+                out.loopCount = o.loopCount;
+            if (o.videoFormat !== undefined)
+                out.videoFormat = o.videoFormat;
+        }
+        return out;
     }
     async awaitTerminal(args) {
         if (args.useSSE) {
@@ -321,10 +396,12 @@ export class MergeBuilder {
                 return await _consumeSseToTerminal(this.client, args);
             }
             catch (err) {
-                if (err instanceof GislTimeoutError)
-                    throw err;
-                if (err instanceof DOMException && err.name === 'AbortError')
+                // TDqmkWpX: poll-fallback ONLY on a clean SSE stream-end or a typed
+                // transport error; rethrow everything else (timeout, abort, API, an
+                // onProgress callback throw, anything unexpected) so it isn't masked.
+                if (!(err instanceof SseEndedWithoutTerminal || err instanceof GislNetworkError)) {
                     throw err;
+                }
             }
         }
         return await _pollToTerminal(this.client, args);
@@ -367,45 +444,67 @@ function assetIdentity(a) {
     // anything else is a separate upload" — predictable.
     return `path:${a.path}`;
 }
-function wireMergeOptions(opts, mediaKind) {
+/**
+ * Project the merge-level {@link MergeOptions} into the per-media wire
+ * allowlist. Exported so the file-first `MergedRecipe`
+ * (`files([...]).merge(...)`) lowers identically to this operation-first
+ * `client.merge(...)` builder — one allowlist, no drift. Mirrors the PHP
+ * `MergeBuilder::wireMergeOptions()` public-static seam.
+ *
+ * @internal Not re-exported from `index.ts`; shared between the two merge
+ *   surfaces only.
+ */
+export function wireMergeOptions(opts, mediaKind) {
     const out = {};
-    if (opts.transition !== undefined)
-        out.transition = opts.transition;
-    if (opts.crossfadeDuration !== undefined)
-        out.crossfade_duration = opts.crossfadeDuration;
-    // Codex r2 medium ab2422e56ea0 — merge-level `gap_duration` is on
-    // MergeAudioOptions only (not MergeVideoOptions or MergeImageOptions).
-    // Drop it for non-audio merges instead of shipping an invalid payload.
-    if (opts.gapDuration !== undefined && mediaKind === 'audio')
-        out.gap_duration = opts.gapDuration;
-    if (opts.normalizeAudio !== undefined)
-        out.normalize_audio = opts.normalizeAudio;
-    if (opts.codec !== undefined)
-        out.codec = opts.codec;
-    if (opts.crf !== undefined)
-        out.crf = opts.crf;
-    if (opts.preset !== undefined)
-        out.preset = opts.preset;
-    if (opts.targetSize !== undefined) {
-        out.target_size_bytes = typeof opts.targetSize === 'number'
-            ? opts.targetSize
-            : parseSizeString(opts.targetSize);
-        out.encoding_mode = 'target_size';
-    }
-    if (opts.transitionDuration !== undefined)
-        out.transition_duration = opts.transitionDuration;
-    if (opts.fps !== undefined)
-        out.fps = opts.fps;
-    if (opts.durationPerImage !== undefined)
-        out.duration_per_image = opts.durationPerImage;
-    if (opts.loopCount !== undefined)
-        out.loop_count = opts.loopCount;
+    // Per-media wire allowlist — mirror of PHP MergeBuilder::wireMergeOptions
+    // (codex 30d…/parity): a field set on the wrong media kind is DROPPED
+    // locally rather than shipped as an invalid payload the server 422s.
+    // All media kinds.
     if (opts.output !== undefined)
         out.output_type = opts.output;
     if (opts.outputType !== undefined)
         out.output_type = opts.outputType;
-    if (opts.videoFormat !== undefined)
-        out.video_format = opts.videoFormat;
+    if (opts.transition !== undefined)
+        out.transition = opts.transition;
+    // Video + audio.
+    if (mediaKind === 'video' || mediaKind === 'audio') {
+        if (opts.crossfadeDuration !== undefined)
+            out.crossfade_duration = opts.crossfadeDuration;
+        if (opts.normalizeAudio !== undefined)
+            out.normalize_audio = opts.normalizeAudio;
+    }
+    // Audio only — merge-level `gap_duration` is on MergeAudioOptions only
+    // (codex r2 medium ab2422e56ea0).
+    if (mediaKind === 'audio' && opts.gapDuration !== undefined)
+        out.gap_duration = opts.gapDuration;
+    // Video only.
+    if (mediaKind === 'video') {
+        if (opts.codec !== undefined)
+            out.codec = opts.codec;
+        if (opts.crf !== undefined)
+            out.crf = opts.crf;
+        if (opts.preset !== undefined)
+            out.preset = opts.preset;
+        if (opts.targetSize !== undefined) {
+            out.target_size_bytes = typeof opts.targetSize === 'number'
+                ? opts.targetSize
+                : parseSizeString(opts.targetSize);
+            out.encoding_mode = 'target_size';
+        }
+    }
+    // Image only.
+    if (mediaKind === 'image') {
+        if (opts.transitionDuration !== undefined)
+            out.transition_duration = opts.transitionDuration;
+        if (opts.fps !== undefined)
+            out.fps = opts.fps;
+        if (opts.durationPerImage !== undefined)
+            out.duration_per_image = opts.durationPerImage;
+        if (opts.loopCount !== undefined)
+            out.loop_count = opts.loopCount;
+        if (opts.videoFormat !== undefined)
+            out.video_format = opts.videoFormat;
+    }
     return out;
 }
 /**

package/dist/node-fs.browser.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Browser stub for `node-fs.ts` — selected via the package.json `browser` field
+ * file-remap so browser bundlers (vite/webpack/esbuild) never pull `node:fs` /
+ * `node:path`. These are only reached by path-string uploads, which are
+ * Node-only; a browser caller passes a `Blob`/`File` (handled by
+ * `blobByteSource`, no filesystem) and never invokes these. If somehow called
+ * in a browser, they throw a clear error rather than a missing-module crash.
+ *
+ * The signatures intentionally mirror the `node-fs.ts` re-exports
+ * (`node:fs/promises` `open`/`stat`, `node:path` `basename`) so `client.ts`
+ * type-checks identically against either module.
+ */
+import type { open as NodeOpen, stat as NodeStat } from 'node:fs/promises';
+import type { basename as NodeBasename } from 'node:path';
+export declare const open: typeof NodeOpen;
+export declare const stat: typeof NodeStat;
+export declare const basename: typeof NodeBasename;

package/dist/node-fs.browser.js

@@ -0,0 +1,7 @@
+const pathUploadsAreNodeOnly = () => {
+    throw new Error('Path-string file uploads require Node.js (node:fs). In a browser, pass a ' +
+        'Blob/File to uploadFile()/file() instead.');
+};
+export const open = pathUploadsAreNodeOnly;
+export const stat = pathUploadsAreNodeOnly;
+export const basename = pathUploadsAreNodeOnly;

package/dist/node-fs.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Node-only filesystem/path access used by path-string uploads in `client.ts`.
+ *
+ * @internal — isolated in its own module so the browser build can swap it for
+ * `node-fs.browser.ts` via the package.json `browser` field, keeping `node:fs`
+ * out of browser bundles. `client.ts` imports these STATICALLY (not via dynamic
+ * `import()`), which is deliberate: a static re-export chain stays interceptable
+ * by `vi.mock('node:fs/promises')` in the test suite, whereas a dynamic import
+ * of a `node:` builtin is not mocked by vitest. Browser callers upload a
+ * `Blob`/`File` (which never reaches this module); a browser bundle resolves the
+ * `.browser` stub instead, so these symbols are never loaded there.
+ */
+export { open, stat } from 'node:fs/promises';
+export { basename } from 'node:path';

package/dist/node-fs.js

@@ -0,0 +1,14 @@
+/**
+ * Node-only filesystem/path access used by path-string uploads in `client.ts`.
+ *
+ * @internal — isolated in its own module so the browser build can swap it for
+ * `node-fs.browser.ts` via the package.json `browser` field, keeping `node:fs`
+ * out of browser bundles. `client.ts` imports these STATICALLY (not via dynamic
+ * `import()`), which is deliberate: a static re-export chain stays interceptable
+ * by `vi.mock('node:fs/promises')` in the test suite, whereas a dynamic import
+ * of a `node:` builtin is not mocked by vitest. Browser callers upload a
+ * `Blob`/`File` (which never reaches this module); a browser bundle resolves the
+ * `.browser` stub instead, so these symbols are never loaded there.
+ */
+export { open, stat } from 'node:fs/promises';
+export { basename } from 'node:path';

package/dist/sha256.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Dependency-free, **synchronous** SHA-256 — browser- and Node-safe.
+ *
+ * @internal — NOT re-exported from `index.ts`. Exists so the ergonomic
+ * preset-resolver fingerprint (`preset_resolver.ts`) can hash without importing
+ * `node:crypto`, which would drag a Node-only built-in into the browser entry
+ * graph. Output is byte-identical to Node's
+ * `createHash('sha256').update(input, 'utf8').digest('hex')` and to PHP's
+ * `hash('sha256', $input)` — the resolver fingerprint is parity-pinned
+ * (`tests/unit/preset-resolver.test.ts` asserts exact digests; "do NOT relax to
+ * a regex"). Web Crypto's `subtle.digest` is async and would force the resolver
+ * sync→async, so a small sync implementation is used instead.
+ *
+ * Standard FIPS 180-4 SHA-256. Input is hashed as UTF-8 bytes.
+ */
+/**
+ * Compute the SHA-256 of `input` (hashed as its UTF-8 byte encoding) and return
+ * the lowercase 64-character hex digest.
+ */
+export declare function sha256Hex(input: string): string;

package/dist/sha256.js

@@ -0,0 +1,108 @@
+/**
+ * Dependency-free, **synchronous** SHA-256 — browser- and Node-safe.
+ *
+ * @internal — NOT re-exported from `index.ts`. Exists so the ergonomic
+ * preset-resolver fingerprint (`preset_resolver.ts`) can hash without importing
+ * `node:crypto`, which would drag a Node-only built-in into the browser entry
+ * graph. Output is byte-identical to Node's
+ * `createHash('sha256').update(input, 'utf8').digest('hex')` and to PHP's
+ * `hash('sha256', $input)` — the resolver fingerprint is parity-pinned
+ * (`tests/unit/preset-resolver.test.ts` asserts exact digests; "do NOT relax to
+ * a regex"). Web Crypto's `subtle.digest` is async and would force the resolver
+ * sync→async, so a small sync implementation is used instead.
+ *
+ * Standard FIPS 180-4 SHA-256. Input is hashed as UTF-8 bytes.
+ */
+// First 32 bits of the fractional parts of the cube roots of the first 64 primes.
+const K = new Uint32Array([
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+    0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+    0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+    0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+    0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+    0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+    0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+function rotr(value, bits) {
+    return (value >>> bits) | (value << (32 - bits));
+}
+/**
+ * Compute the SHA-256 of `input` (hashed as its UTF-8 byte encoding) and return
+ * the lowercase 64-character hex digest.
+ */
+export function sha256Hex(input) {
+    const bytes = new TextEncoder().encode(input); // UTF-8, matching Node `.update(str)`
+    // --- Padding (FIPS 180-4 §5.1.1) ---
+    const bitLength = bytes.length * 8;
+    // message + 0x80 + zero-pad to 56 mod 64 + 8-byte big-endian length
+    const paddedLength = ((bytes.length + 8) >> 6 << 6) + 64;
+    const buffer = new Uint8Array(paddedLength);
+    buffer.set(bytes);
+    buffer[bytes.length] = 0x80;
+    // 64-bit big-endian bit length in the final 8 bytes. Both words are written:
+    // the high word via Math.floor (exact for the Number range, well beyond any
+    // realistic input) and the low word via `>>> 0`. Fingerprint inputs are tiny,
+    // so the high word is effectively always zero, but it is set for correctness.
+    const view = new DataView(buffer.buffer);
+    view.setUint32(paddedLength - 4, bitLength >>> 0, false);
+    view.setUint32(paddedLength - 8, Math.floor(bitLength / 0x100000000), false);
+    // --- Initial hash values: fractional parts of the square roots of the first 8 primes. ---
+    let h0 = 0x6a09e667;
+    let h1 = 0xbb67ae85;
+    let h2 = 0x3c6ef372;
+    let h3 = 0xa54ff53a;
+    let h4 = 0x510e527f;
+    let h5 = 0x9b05688c;
+    let h6 = 0x1f83d9ab;
+    let h7 = 0x5be0cd19;
+    const w = new Uint32Array(64);
+    for (let offset = 0; offset < paddedLength; offset += 64) {
+        for (let i = 0; i < 16; i++) {
+            w[i] = view.getUint32(offset + i * 4, false);
+        }
+        for (let i = 16; i < 64; i++) {
+            const s0 = rotr(w[i - 15], 7) ^ rotr(w[i - 15], 18) ^ (w[i - 15] >>> 3);
+            const s1 = rotr(w[i - 2], 17) ^ rotr(w[i - 2], 19) ^ (w[i - 2] >>> 10);
+            w[i] = (w[i - 16] + s0 + w[i - 7] + s1) | 0;
+        }
+        let a = h0;
+        let b = h1;
+        let c = h2;
+        let d = h3;
+        let e = h4;
+        let f = h5;
+        let g = h6;
+        let h = h7;
+        for (let i = 0; i < 64; i++) {
+            const S1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+            const ch = (e & f) ^ (~e & g);
+            const temp1 = (h + S1 + ch + K[i] + w[i]) | 0;
+            const S0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+            const maj = (a & b) ^ (a & c) ^ (b & c);
+            const temp2 = (S0 + maj) | 0;
+            h = g;
+            g = f;
+            f = e;
+            e = (d + temp1) | 0;
+            d = c;
+            c = b;
+            b = a;
+            a = (temp1 + temp2) | 0;
+        }
+        h0 = (h0 + a) | 0;
+        h1 = (h1 + b) | 0;
+        h2 = (h2 + c) | 0;
+        h3 = (h3 + d) | 0;
+        h4 = (h4 + e) | 0;
+        h5 = (h5 + f) | 0;
+        h6 = (h6 + g) | 0;
+        h7 = (h7 + h) | 0;
+    }
+    const out = [h0, h1, h2, h3, h4, h5, h6, h7];
+    let hex = '';
+    for (const value of out) {
+        hex += (value >>> 0).toString(16).padStart(8, '0');
+    }
+    return hex;
+}

package/dist/types.d.ts

@@ -18,6 +18,20 @@ export interface GislClientConfig {
      * environment's responsibility.
      */
     useSessionCookie?: boolean;
+    /**
+     * Preferred response language. When set, the SDK sends
+     * `Accept-Language: <locale>` on every GISL-API request (e.g. `'fr-FR'`,
+     * `'de'`). The server echoes the language it actually resolved via the
+     * `Content-Language` response header, surfaced on
+     * `GislApiError.contentLanguage`. When no supported language matches, the
+     * server falls back to its default (typically `en-GB`).
+     *
+     * A dedicated `locale` wins over any `Accept-Language` passed through
+     * `headers` (mirrors how `apiKey` wins over a caller-supplied
+     * `Authorization` header); the conflicting `headers` entry is dropped
+     * case-insensitively so the request never carries two variants.
+     */
+    locale?: string;
     /** Threshold in bytes above which multipart upload is used (default: 10MB) */
     multipartThreshold?: number;
     /**
@@ -70,12 +84,27 @@ export interface ConnectionSourcePayload {
     path: string;
 }
 export type WorkflowSourcePayload = UploadSourcePayload | JobOutputSourcePayload | ExternalImportSourcePayload | ConnectionSourcePayload;
+/**
+ * The source leaves a multi-input `JobInputV2Payload.source` may take —
+ * `WorkflowSourcePayload` minus the `upload` leaf. Per the contract
+ * (`MultiInputSource` in `openapi/api.yaml`), multi-input operations
+ * (merge / archive / image_watermark / custom_luma / audio_overlay) do NOT
+ * accept upload-direct: an uploaded file enters a multi-input job via a
+ * `passthrough` source job referenced downstream by `{ type: 'job_output' }`.
+ * Single-input `JobDefinitionPayload.source` keeps the wider
+ * `WorkflowSourcePayload` (upload-direct is valid there).
+ *
+ * Named with the SDK's `*Payload` suffix to match every sibling source type
+ * and to avoid colliding with the generated `MultiInputSource` model (a
+ * different, deep-import-only type family).
+ */
+export type MultiInputSourcePayload = JobOutputSourcePayload | ExternalImportSourcePayload | ConnectionSourcePayload;
 export declare function uploadSource(fileId: string): UploadSourcePayload;
 export declare function jobOutputSource(from: string, operation?: string): JobOutputSourcePayload;
 export declare function externalImportSource(externalSourceId: string): ExternalImportSourcePayload;
 export declare function connectionSource(connectionId: string, path: string): ConnectionSourcePayload;
 export interface JobInputV2Payload {
-    source: WorkflowSourcePayload;
+    source: MultiInputSourcePayload;
     role?: JobInputV2RoleEnum;
     per_input_options?: Record<string, unknown>;
 }
@@ -139,6 +168,17 @@ export interface WorkflowProcessingPayload {
 }
 export interface WorkflowCreatePayload {
     jobs: JobDefinitionPayload[];
+    /**
+     * Flat single-job form (with `operations`): top-level input source, exactly
+     * equivalent to `jobs: [{ source, operations }]` (contracts D0Gsri8V, v2.64.0).
+     * The spec's `oneOf` makes `jobs` and `source`+`operations` mutually exclusive;
+     * the SDK builders always emit the explicit `jobs[]` form, so these are typed
+     * optional for spec-completeness (a consumer hand-building the flat form omits
+     * `jobs`). Builder adoption of the flat form is a follow-up.
+     */
+    source?: WorkflowSourcePayload;
+    /** Flat-form operation set (with `source`); equivalent to one job's `operations`. */
+    operations?: OperationDef[];
     workflow_edges?: Array<{
         from: string;
         to: string;
@@ -156,7 +196,7 @@ export interface WorkflowCreatePayload {
  * only via deep imports and should not be treated as public API.
  * @internal
  */
-export declare const WORKFLOW_CREATE_PAYLOAD_KEYS: readonly ["jobs", "workflow_edges", "callback_url", "callback_events", "export", "delivery", "processing"];
+export declare const WORKFLOW_CREATE_PAYLOAD_KEYS: readonly ["jobs", "source", "operations", "workflow_edges", "callback_url", "callback_events", "export", "delivery", "processing"];
 export interface GetSchemaOptions {
     /** Filter the schema to operations that accept this MIME type (e.g. `image/jpeg`). */
     mimeType?: string;
@@ -196,6 +236,18 @@ export interface CreditsUsageOptions {
     /** Page offset (zero-based). Server default is 0. */
     offset?: number;
 }
+export interface ListWorkflowsOptions {
+    /**
+     * Opaque pagination cursor from a previous page's `nextCursor`. Omit for
+     * the first page; treat the value as opaque (do not parse).
+     */
+    cursor?: string;
+    /**
+     * Rows per page. Server defaults to 20 and rejects values outside `[1, 100]`
+     * with a 400 validation envelope.
+     */
+    limit?: number;
+}
 /**
  * Aggregated result of a `preflightClips()` batch probe — N parallel calls
  * to `POST /api/uploads/{id}/probe`, partitioned by outcome so the caller

package/dist/types.js

@@ -42,6 +42,8 @@ export const JOB_DEFINITION_PAYLOAD_KEYS = Object.freeze([
  */
 export const WORKFLOW_CREATE_PAYLOAD_KEYS = Object.freeze([
     'jobs',
+    'source',
+    'operations',
     'workflow_edges',
     'callback_url',
     'callback_events',

package/package.json

@@ -1,16 +1,28 @@
 {
   "name": "@giveitsmaller/sdk",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Node.js SDK for the GISL (Give It Smaller) file compression and processing API",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
   "exports": {
     ".": {
+      "browser": {
+        "types": "./dist/index.browser.d.ts",
+        "default": "./dist/index.browser.js"
+      },
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./browser": {
+      "types": "./dist/index.browser.d.ts",
+      "default": "./dist/index.browser.js"
     }
   },
+  "browser": {
+    "./dist/index.js": "./dist/index.browser.js",
+    "./dist/node-fs.js": "./dist/node-fs.browser.js"
+  },
   "types": "./dist/index.d.ts",
   "files": [
     "dist/"
@@ -19,10 +31,11 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@giveitsmaller/contracts": "^0.9.0"
+    "@giveitsmaller/contracts": "^0.16.0"
   },
   "devDependencies": {
     "@types/node": "^22",
+    "esbuild": "^0.27",
     "typescript": "^5.7",
     "vitest": "^3.1 <3.2.5",
     "yaml": "^2.6"