@giveitsmaller/sdk 0.6.0 → 0.7.0

package/dist/merge.js

@@ -0,0 +1,411 @@
+/**
+ * Merge-compose layer for the SDK ergonomic surface (T3 / cuecCmb5).
+ *
+ * `client.merge(...assets, options?)` returns a `MergeBuilder`. The builder
+ * separates WHAT (the asset set) from ORDER (the timeline):
+ *
+ * - `merge(a, b, c)` declares the asset set — each unique input is uploaded
+ *   ONCE per run, even if referenced multiple times in the sequence.
+ * - `.sequence(...refs)` defines the play order. References may repeat
+ *   freely; entries may be bare asset refs or `clip(ref, opts)` objects
+ *   carrying per-position options.
+ * - No `.sequence(...)` => play in declared order, no transitions.
+ *
+ * Wire-truth boundaries (lowering.md §sequences):
+ * - Video merge per-input options: `transition`, `crossfadeDuration` only.
+ * - Audio merge per-input options: `transition`, `crossfadeDuration`,
+ *   `gapDuration` only.
+ * - Image merge has NO per-input options today — `clip(ref)` is reuse/order
+ *   only. Per-position transitions on image merges throw locally as
+ *   `GislPerInputOptionsNotSupportedError`.
+ * - No per-clip `trimStart`/`trimEnd` today (contracts ticket iZzn5QrS
+ *   tracks the fix). Workaround: pre-trim each clip via a chained
+ *   `compress(file, trimStart, trimEnd)`.
+ *
+ * Local validation runs BEFORE any upload — undeclared refs and unused
+ * assets both fail fast so the caller saves bandwidth on typo'd composes.
+ */
+import { uploadSource } from './types.js';
+import { GislConfigError, GislPerInputOptionsNotSupportedError, GislTimeoutError, GislUndeclaredAssetError, GislUnusedAssetError, } from './errors.js';
+import { _checkAborted, _consumeSseToTerminal, _parseMaxWait, _pollToTerminal, _projectResult, } from './builder.js';
+/**
+ * Construct a path-asset. Bare-string arguments to `merge(...)` are
+ * implicitly wrapped via this helper.
+ */
+export function asset(path) {
+    return { type: 'path', path };
+}
+/**
+ * Wrap an already-uploaded file_id as a merge asset. Use this when the
+ * SAME logical file should be referenced from multiple merge runs with
+ * guaranteed-single-upload semantics.
+ */
+export function handle(fileId) {
+    return { type: 'handle', fileId };
+}
+/**
+ * Construct a clip entry for `.sequence(...)`. The asset MUST already
+ * be in the merge's declared asset set.
+ */
+export function clip(ref, options = {}) {
+    return { type: 'clip', asset: ref, options };
+}
+// ---------------------------------------------------------------------------
+// MergeBuilder
+// ---------------------------------------------------------------------------
+/**
+ * Captures the (declared assets, options) for a merge. `.sequence(...)`
+ * pins the play order; without it, the declared order is used as-is
+ * with no per-input options.
+ *
+ * Local validation runs at `.run()`/`.submit()` time (BEFORE any upload)
+ * and throws one of `GislUndeclaredAssetError`, `GislUnusedAssetError`,
+ * or `GislPerInputOptionsNotSupportedError` if the compose is invalid.
+ */
+export class MergeBuilder {
+    client;
+    assets;
+    opOptions;
+    sequenceEntries = null;
+    constructor(client, assets, opOptions) {
+        this.client = client;
+        this.assets = assets;
+        this.opOptions = opOptions;
+    }
+    /**
+     * Pin the merge play order. Each entry must reference an asset that
+     * was declared in the parent `merge(...)` call. Repeats are allowed
+     * and deduped on upload (one upload per unique declared asset).
+     */
+    sequence(...entries) {
+        this.sequenceEntries = entries;
+        return this;
+    }
+    async run(options) {
+        const deadline = Date.now() + _parseMaxWait(options.maxWait);
+        const signal = options.signal;
+        const onProgress = options.onProgress;
+        const useSSE = options.useSSE ?? true;
+        // 1. Validate locally BEFORE any upload.
+        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 uploadedByAssetId = await this.uploadUniqueAssets(plan.uniqueAssets, {
+            signal,
+            onProgress,
+            deadline,
+        });
+        _checkAborted(signal);
+        if (Date.now() >= deadline) {
+            throw new GislTimeoutError(`Upload(s) 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);
+        _checkAborted(signal);
+        // 4. Wait to terminal status.
+        const finalStatus = await this.awaitTerminal({
+            workflowId: created.workflowId,
+            deadline,
+            signal,
+            onProgress,
+            useSSE,
+            pollIntervalMs: options.pollIntervalMs,
+        });
+        // 5. Fetch downloads + project.
+        if (Date.now() >= deadline) {
+            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);
+        return _projectResult(finalStatus, downloads.downloads, this.opOptionsForResolved());
+    }
+    async submit(options) {
+        const plan = this.planSequence();
+        const uploadedByAssetId = await this.uploadUniqueAssets(plan.uniqueAssets, {});
+        const payload = this.buildPayload(plan, uploadedByAssetId);
+        payload.callback_url = options.webhook;
+        const created = await this.client.createWorkflow(payload);
+        const handle = {
+            workflowId: created.workflowId,
+            ...(created.webhookSecret != null ? { webhookSecret: created.webhookSecret } : {}),
+        };
+        return handle;
+    }
+    // ---------------------------------------------------------------------------
+    /**
+     * Resolve the declared assets + sequence (or fall back to declared order),
+     * dedupe by identity, and run the local validators. The returned plan
+     * carries the SEQUENCE (positional entries) + the UNIQUE assets to upload.
+     */
+    planSequence() {
+        const declaredIds = this.assets.map(assetIdentity);
+        const declaredSet = new Map();
+        for (let i = 0; i < this.assets.length; i += 1) {
+            const id = declaredIds[i];
+            if (!declaredSet.has(id))
+                declaredSet.set(id, this.assets[i]);
+        }
+        // Use the explicit sequence if set; otherwise the declared order as-is.
+        const rawEntries = this.sequenceEntries ?? this.assets.map((a) => a);
+        // Validate per-entry: undeclared ref + image-merge-clip-with-opts.
+        const mediaKind = this.inferMediaKind();
+        const positions = [];
+        const refIds = new Set();
+        for (const entry of rawEntries) {
+            const isClip = entry !== null && typeof entry === 'object' && 'type' in entry && entry.type === 'clip';
+            const assetRef = isClip ? entry.asset : entry;
+            const id = assetIdentity(assetRef);
+            if (!declaredSet.has(id)) {
+                throw new GislUndeclaredAssetError(id, Array.from(declaredSet.keys()));
+            }
+            refIds.add(id);
+            if (isClip) {
+                const opts = entry.options;
+                const hasOpts = opts.transition !== undefined ||
+                    opts.crossfadeDuration !== undefined ||
+                    opts.gapDuration !== undefined;
+                if (hasOpts && mediaKind === 'image') {
+                    throw new GislPerInputOptionsNotSupportedError('image');
+                }
+                positions.push({ assetId: id, options: opts });
+            }
+            else {
+                positions.push({ assetId: id, options: {} });
+            }
+        }
+        // Unused-asset check.
+        if (this.sequenceEntries !== null && this.opOptions.allowUnusedAssets !== true) {
+            const unused = Array.from(declaredSet.keys()).filter((id) => !refIds.has(id));
+            if (unused.length > 0)
+                throw new GislUnusedAssetError(unused);
+        }
+        // Codex r1 medium edb1bb641d81 — when an explicit sequence is set,
+        // restrict the upload set to only the referenced assets. This prevents
+        // wasted uploads of declared-but-unsequenced assets (e.g. when the
+        // user passes allowUnusedAssets: true).
+        const uploadSet = this.sequenceEntries === null
+            ? declaredSet
+            : new Map(Array.from(declaredSet.entries()).filter(([id]) => refIds.has(id)));
+        // Codex r1 medium 5c86b67c979b — enforce merge schema input bounds
+        // (min_inputs: 2, max_inputs: 10 per generated/typescript/operations/merge.ts).
+        // Validate sequence position count, NOT unique-asset count: the merge job
+        // sends N inputs where N = position count (repeats included).
+        if (positions.length < 2) {
+            throw new GislConfigError(`merge requires at least 2 inputs (got ${positions.length}). Declare more assets or check the sequence.`);
+        }
+        if (positions.length > 10) {
+            throw new GislConfigError(`merge accepts at most 10 inputs (got ${positions.length}). Reduce the sequence or split the merge.`);
+        }
+        return { mediaKind, positions, uniqueAssets: uploadSet };
+    }
+    inferMediaKind() {
+        if (this.opOptions.mediaKind !== undefined)
+            return this.opOptions.mediaKind;
+        const first = this.assets[0];
+        if (first === undefined)
+            return 'video';
+        if (first.type === 'path' && typeof first.path === 'string') {
+            const lower = first.path.toLowerCase();
+            if (/\.(jpe?g|png|webp|avif|gif|heic|tiff?)$/.test(lower))
+                return 'image';
+            if (/\.(mp3|wav|flac|aac|ogg|m4a)$/.test(lower))
+                return 'audio';
+            return 'video';
+        }
+        if (first.type === 'path' && first.path instanceof Blob) {
+            if (first.path.type.startsWith('image/'))
+                return 'image';
+            if (first.path.type.startsWith('audio/'))
+                return 'audio';
+            return 'video';
+        }
+        return 'video';
+    }
+    async uploadUniqueAssets(uniqueAssets, opts) {
+        const uploaded = new Map();
+        for (const [id, a] of uniqueAssets) {
+            // Codex r1 medium 797b4113431f — check the deadline between uploads
+            // so a multi-file merge doesn't keep uploading past `maxWait`.
+            if (opts.deadline !== undefined && Date.now() >= opts.deadline) {
+                throw new GislTimeoutError(`maxWait elapsed mid-upload (after ${uploaded.size} of ${uniqueAssets.size} merge assets)`);
+            }
+            if (a.type === 'handle') {
+                uploaded.set(id, a.fileId);
+                continue;
+            }
+            const uploadOpts = {};
+            if (opts.signal !== undefined)
+                uploadOpts.signal = opts.signal;
+            if (opts.onProgress !== undefined) {
+                uploadOpts.onProgress = (uploadedBytes, totalBytes) => {
+                    opts.onProgress?.({ phase: 'upload', uploadedBytes, totalBytes });
+                };
+            }
+            const resp = await this.client.uploadFile(a.path, uploadOpts);
+            uploaded.set(id, resp.fileId);
+        }
+        return uploaded;
+    }
+    buildPayload(plan, uploadedByAssetId) {
+        const inputs = plan.positions.map((pos) => {
+            const fileId = uploadedByAssetId.get(pos.assetId);
+            if (fileId === undefined) {
+                // Defensive — planSequence should have rejected this.
+                throw new Error(`Asset '${pos.assetId}' was never uploaded — internal builder bug`);
+            }
+            // Codex r1 HIGH 502c6bf232c2 — per_input_options goes on EACH
+            // JobInputV2Payload (per-input entry), NOT on operations[0].options.
+            // Skip emission for image merges (planSequence already rejects opts
+            // on image-merge clips). Project per ClipOptions per media kind
+            // (codex r1 medium 128404fa16a9 — gapDuration is audio-only).
+            const wireOpts = plan.mediaKind === 'image'
+                ? {}
+                : wirePerInputOptions(pos.options, plan.mediaKind);
+            const input = { source: uploadSource(fileId) };
+            if (Object.keys(wireOpts).length > 0) {
+                input.per_input_options = wireOpts;
+            }
+            return input;
+        });
+        // Merge-level options (excluding the SDK-side mediaKind/allowUnusedAssets).
+        const mergeOpts = wireMergeOptions(this.opOptions, plan.mediaKind);
+        const job = {
+            id: 'merge',
+            inputs,
+            operations: [{ type: 'merge', options: mergeOpts }],
+        };
+        return { jobs: [job] };
+    }
+    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 };
+    }
+    async awaitTerminal(args) {
+        if (args.useSSE) {
+            try {
+                return await _consumeSseToTerminal(this.client, args);
+            }
+            catch (err) {
+                if (err instanceof GislTimeoutError)
+                    throw err;
+                if (err instanceof DOMException && err.name === 'AbortError')
+                    throw err;
+            }
+        }
+        return await _pollToTerminal(this.client, args);
+    }
+}
+/**
+ * Per-Blob identity tokens — referential dedupe via WeakMap. Two distinct
+ * Blob objects with the same size + MIME would otherwise hash to the
+ * SAME identity (silent data loss; code-reviewer P1 conf 8). Reference
+ * identity guarantees same-Blob = same-upload and different-Blob = two
+ * uploads, irrespective of content sniffing.
+ */
+const _blobTokens = new WeakMap();
+let _blobCounter = 0;
+/**
+ * Asset identity for dedupe. Handles use their fileId; paths use a
+ * trim+trailing-separator-strip normalised string (NOT case-folded —
+ * case-insensitive dedupe would silently merge `A.mp4` and `a.mp4` on a
+ * case-sensitive filesystem; code-reviewer P1 conf 7). Blobs use
+ * referential identity via a WeakMap-backed token. Bare-string path
+ * dedupe is best-effort — use `handle()` for guaranteed reuse.
+ */
+function assetIdentity(a) {
+    if (a.type === 'handle')
+        return `handle:${a.fileId}`;
+    if (a.path instanceof Blob) {
+        let token = _blobTokens.get(a.path);
+        if (token === undefined) {
+            _blobCounter += 1;
+            token = `${_blobCounter}`;
+            _blobTokens.set(a.path, token);
+        }
+        return `blob:${token}`;
+    }
+    // Codex r2 medium bb500566a683 — dedupe by the EXACT caller-provided
+    // string. Previous trim+trailing-slash-strip would collapse
+    // `'clip.mp4'` and `'clip.mp4 '` into one upload while uploadFile later
+    // received the original string. Exact-string dedupe = upload identity
+    // matches dedupe identity. Best-effort = "two identical strings dedupe;
+    // anything else is a separate upload" — predictable.
+    return `path:${a.path}`;
+}
+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;
+    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;
+    return out;
+}
+/**
+ * Project a ClipOptions into the wire-shape per_input_options object.
+ * Codex r1 medium 128404fa16a9 — `gap_duration` is on AUDIO per-input
+ * only (`MergeAudioPerInputOptions`), NOT video. Splitting by mediaKind
+ * here keeps the wire payload honest and prevents the server from
+ * silently rejecting/ignoring an out-of-spec field.
+ */
+function wirePerInputOptions(opts, mediaKind) {
+    const out = {};
+    if (opts.transition !== undefined)
+        out.transition = opts.transition;
+    if (opts.crossfadeDuration !== undefined)
+        out.crossfade_duration = opts.crossfadeDuration;
+    if (opts.gapDuration !== undefined && mediaKind === 'audio') {
+        out.gap_duration = opts.gapDuration;
+    }
+    return out;
+}
+function parseSizeString(s) {
+    const m = /^(\d+(?:\.\d+)?)\s*(KB|MB|GB|B)?$/i.exec(s.trim());
+    if (m === null)
+        throw new TypeError(`Invalid targetSize string '${s}'`);
+    const n = Number(m[1]);
+    const unit = (m[2] ?? 'B').toUpperCase();
+    switch (unit) {
+        case 'B': return Math.round(n);
+        case 'KB': return Math.round(n * 1_000);
+        case 'MB': return Math.round(n * 1_000_000);
+        case 'GB': return Math.round(n * 1_000_000_000);
+        /* istanbul ignore next */
+        default: throw new TypeError(`Unknown size unit '${unit}'`);
+    }
+}

package/dist/types.d.ts

@@ -94,21 +94,19 @@ export interface JobDefinitionPayload {
     operations: OperationDef[];
     /** Per-job hide-intermediates promotion flag per ADR-0003. */
     deliver?: boolean;
-    /**
-     * Per-job opt-out of the "compress required in every chain" gate.
-     * When `true`, the server accepts a chain that doesn't terminate in a
-     * `compress` operation — required for chains that observe multi-output
-     * fan-out (e.g. convert PDF -> N images per ADR-0009 §D2) without
-     * collapsing the N outputs through a trailing chained compress.
-     *
-     * Accepted by the API at `compression/src/Jobs/.../JobDefinition.php`
-     * (`skipCompression`) and validated against the chain-ordering rule at
-     * `Job::validateChainOrdering`. Currently undocumented in
-     * `contracts/openapi/api.yaml` JobDefinition schema — spec follow-up
-     * pending; the SDK exposes the field to unblock e2e A8-FLIP.
-     */
-    skip_compression?: boolean;
 }
+/**
+ * Single source of truth for JobDefinitionPayload's top-level wire keys.
+ * Read by `contract-drift-fields.test.ts` to cross-check against the spec
+ * at `JobDefinition`. Not re-exported from `index.ts`; this is reachable
+ * only via deep imports and should not be treated as public API.
+ *
+ * The V1-only `skip_compression` field is deliberately absent (eQnUMW68);
+ * the runtime drift test will fail if the spec re-introduces it OR adds
+ * any other V1-leak field to the V2 JobDefinition schema.
+ * @internal
+ */
+export declare const JOB_DEFINITION_PAYLOAD_KEYS: readonly ["id", "source", "inputs", "operations", "deliver"];
 export type ExternalDestinationPayload = {
     type: 'connection';
     connection_id: string;

package/dist/types.js

@@ -15,6 +15,24 @@ export function externalImportSource(externalSourceId) {
 export function connectionSource(connectionId, path) {
     return { type: 'connection', connection_id: connectionId, path };
 }
+/**
+ * Single source of truth for JobDefinitionPayload's top-level wire keys.
+ * Read by `contract-drift-fields.test.ts` to cross-check against the spec
+ * at `JobDefinition`. Not re-exported from `index.ts`; this is reachable
+ * only via deep imports and should not be treated as public API.
+ *
+ * The V1-only `skip_compression` field is deliberately absent (eQnUMW68);
+ * the runtime drift test will fail if the spec re-introduces it OR adds
+ * any other V1-leak field to the V2 JobDefinition schema.
+ * @internal
+ */
+export const JOB_DEFINITION_PAYLOAD_KEYS = Object.freeze([
+    'id',
+    'source',
+    'inputs',
+    'operations',
+    'deliver',
+]);
 /**
  * Single source of truth for WorkflowCreatePayload's top-level wire keys.
  * Read by `contract-drift-fields.test.ts` to cross-check against the spec at

package/package.json

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