@giveitsmaller/sdk 0.7.0 → 0.9.0

package/dist/index.d.ts

@@ -4,15 +4,22 @@ export { parseSseStream } from './sse.js';
 export type { CreditsUsageOptions, GetSchemaOptions, GetSchemaResult, PreflightClipError, PreflightClipsResult, GislClientConfig, GislSseEvent, UploadOptions, WaitOptions, WorkflowCreatePayload, OperationDef, WorkflowSourcePayload, UploadSourcePayload, JobOutputSourcePayload, ExternalImportSourcePayload, ConnectionSourcePayload, JobInputV2Payload, JobDefinitionPayload, ExternalDestinationPayload, DeliveryPayload, DeliveryModePayload, DeliveryBundleFormatPayload, DeliverySelectionPayload, DeliverySelectionTypePayload, DeliveryOutputRefPayload, WorkflowProcessingPayload, ProcessingClassHintPayload, MultipartCheckpointState, _Sdk3HandCodedUploadedPart, _Sdk3HandCodedMultipartStatusResult, _Sdk3HandCodedPresignedPart, _Sdk3HandCodedPresignPartsResult, _Sdk3HandCodedKeepaliveResult, } from './types.js';
 export { uploadSource, jobOutputSource, externalImportSource, connectionSource, } from './types.js';
 export type { GislConfigErrorMetadata } from './errors.js';
-export { GislError, GislApiError, GislValidationError, GislBalanceExhaustedError, GislTierRestrictedError, GislFeatureTierRestrictedError, GislFeatureNotAvailableError, GislWorkflowExpiredError, GislProbePendingError, GislAuthError, GislUploadCapExceededError, GislMultipartPartError, GislMultipartPartCountError, GislMultipartSessionNotFoundError, GislMultipartSessionOwnershipError, GislMultipartSessionAuthRequiredError, GislTimeoutError, GislAbortError, GislConfigError, GislMissingCredentialsError, GislFeatureRequiresAuthError, GislUndeclaredAssetError, GislUnusedAssetError, GislPerInputOptionsNotSupportedError, GislChainCardinalityMismatchError, } from './errors.js';
+export { GislError, GislApiError, GislValidationError, GislBalanceExhaustedError, GislTierRestrictedError, GislFeatureTierRestrictedError, GislFeatureNotAvailableError, GislWorkflowExpiredError, GislProbePendingError, GislAuthError, GislUploadCapExceededError, GislMultipartPartError, GislMultipartPartCountError, GislMultipartSessionNotFoundError, GislMultipartSessionOwnershipError, GislMultipartSessionAuthRequiredError, GislTimeoutError, GislAbortError, GislNetworkError, GislConfigError, GislMissingCredentialsError, GislFeatureRequiresAuthError, GislUndeclaredAssetError, GislUnusedAssetError, GislPerInputOptionsNotSupportedError, GislChainCardinalityMismatchError, GislNoSuchKeyError, GislSinkError, GislResultNotReadyError, } from './errors.js';
 export type { GislApiErrorOptions, GislUploadCapKind } from './errors.js';
+export { RunResult } from './file-first.js';
+export type { OutputFile, ItemResult, ItemFailure, Manifest, Downloader, } from './file-first.js';
+export { Recipe, fileInput } from './file-first.js';
+export type { FileInput } from './file-first.js';
+export { FilesRecipe } from './file-first.js';
+export { HttpDownloader } from './http-downloader.js';
+export { Handle, StatusSnapshot } from './handle.js';
 export { gisl, create } from './gisl.js';
 export type { GislCreateOptions, Environment, ErgonomicClient } from './gisl.js';
 export { presetDefaults, PresetDefaults, type PresetMedia, type PresetOp, type AnyPresetOptions, ImageCompressPresetOptions, type ImageCompressPresetOptionsInput, AudioCompressPresetOptions, type AudioCompressPresetOptionsInput, VideoCompressPresetOptions, type VideoCompressPresetOptionsInput, DocumentPdfCompressPresetOptions, type DocumentPdfCompressPresetOptionsInput, DocumentOfficeCompressPresetOptions, type DocumentOfficeCompressPresetOptionsInput, DocumentOdfCompressPresetOptions, type DocumentOdfCompressPresetOptionsInput, DocumentEpubCompressPresetOptions, type DocumentEpubCompressPresetOptionsInput, OptimizeFor, ImageMode, ImageFit, ImageMetadataPolicy, IccProfilePolicy, ImageFormat, VideoCodec, VideoPreset, VideoFit, AudioBitrate, AudioCodec, AudioSampleRate, PdfProfile, PdfColorspace, } from './ergonomic/presets/index.js';
 export { OperationBuilder, MapEachBuilder } from './builder.js';
 export { MergeBuilder, asset, handle, clip } from './merge.js';
 export type { Asset, ClipEntry, ClipOptions, MergeMediaKind, MergeOptions, SequenceEntry, } from './merge.js';
-export type { Artifact, ArtifactRef, Handle, JobBreakdown, OperationBreakdown, ProcessingProgressEvent, ProgressEvent, ResolvedOptions, ResolvedOptionsSources, Result, RunOptions, SubmitOptions, UploadProgressEvent, } from './builder.js';
+export type { Artifact, ArtifactRef, JobBreakdown, OperationBreakdown, ProcessingProgressEvent, ProgressEvent, ResolvedOptions, ResolvedOptionsSources, Result, RunOptions, SubmitOptions, UploadProgressEvent, } from './builder.js';
 export { PRESET_VERSION, resolveCompressOptions } from './ergonomic/preset_resolver.js';
 export type { ResolveCompressOptionsInput, ResolveCompressOptionsOutput, } from './ergonomic/preset_resolver.js';
 export type { AudioWatermarkDecodeRequest, AudioWatermarkDecodeResponse, ContactRequest, CreditsBalanceResponse, CreditsUsageResponse, CreditTransaction, ExternalImportCreatedResponse, ExternalImportRequest, LoginUserRequest, LoginUser200ResponseData, LoginUser200ResponseDataUser, WorkflowCancelResponse, WorkflowResumeResponse, WorkflowPausedDetail, WorkflowPausedDetailLinks, UploadResponse, UploadConstraintsApplied, UploadProbeResponse, UploadProbeMediaMetadata, MultipartInitiateRequestMetadataHint, WorkflowCreateResponse, WorkflowStatusResponse, WorkflowDownloadResponse, MetadataResponse, MetadataResponseDimensions, MetadataResponseExif, MetadataResponseExifGps, OperationsSchemaResponse, OperationSchemaDefinition, MimeGroupSchema, OptionSchema, PerValueAvailabilityEntry, PerRoleCardinalityEntry, RetryResponse, JobDownload, OperationDownload, WebhookPayload, WebhookOperationContext, JobResponse, OperationResponse, OperationResult, OperationResultMetrics, ExternalDestination, Delivery, DeliveryPlan, DeliveryPlanOutput, WorkflowProcessing, ProcessingPlan, ProcessingPlanJob, WorkflowEdge, WorkflowWarning, JobInputV2, WorkflowSource, UploadSource, JobOutputSource, ConnectionSource, ExternalImportToken, BalanceExhaustedResponse, BalanceExhaustedResponseAllOfLinks, TierRestrictionResponse, FeatureTierRestrictedResponse, FeatureNotAvailableResponse, FeatureViolation, WorkflowExpiredResponse, ProbePendingResponse, AuthErrorResponse, } from '@giveitsmaller/contracts/openapi';

package/dist/index.js

@@ -7,6 +7,9 @@ export { uploadSource, jobOutputSource, externalImportSource, connectionSource,
 export { GislError, GislApiError, GislValidationError, GislBalanceExhaustedError, GislTierRestrictedError, GislFeatureTierRestrictedError, GislFeatureNotAvailableError, GislWorkflowExpiredError, GislProbePendingError, GislAuthError, GislUploadCapExceededError, GislMultipartPartError, GislMultipartPartCountError, 
 // SDK-3 (Wb6ebOMM) — typed errors for the 3 resume-support endpoints.
 GislMultipartSessionNotFoundError, GislMultipartSessionOwnershipError, GislMultipartSessionAuthRequiredError, GislTimeoutError, GislAbortError, 
+// FF2b / tywwynmN — transport-level failure (mirrors PHP GislNetworkError);
+// raised by the file-first HttpDownloader when an output URL cannot be read.
+GislNetworkError, 
 // T1 / wVU4xHx3 — local config-error tree (pre-I/O; sibling of GislApiError).
 GislConfigError, GislMissingCredentialsError, GislFeatureRequiresAuthError, 
 // T3 / cuecCmb5 — merge-compose local validation errors.
@@ -14,7 +17,33 @@ GislUndeclaredAssetError, GislUnusedAssetError, GislPerInputOptionsNotSupportedE
 // T6 / aDR1jnyZ — chain-cardinality validation (dormant until chain
 // methods on OperationBuilder ship; type + audit registration land
 // here so the future chain-method PR is a pure addition).
-GislChainCardinalityMismatchError, } from './errors.js';
+GislChainCardinalityMismatchError, 
+// FF1 / 3BIxEnfR — file-first result sink errors.
+GislNoSuchKeyError, GislSinkError, 
+// FF5a / Ao8RPVxD — thrown by the file-first Handle.result() when the
+// workflow is not yet terminal (the non-blocking accessor).
+GislResultNotReadyError, } from './errors.js';
+// File-first result surface (FF1 / 3BIxEnfR) — coexists with the
+// operation-first `Result`/`Artifact` until FF6 removes the old layer.
+export { RunResult } from './file-first.js';
+// File-first builder (FF2a / MfV0PDok) — `client.file(path).op()...` lowering.
+export { Recipe, fileInput } from './file-first.js';
+// File-first homogeneous fan-out (FF3a / u0hBt6fl) — `client.files([...]).op()...`
+// applies one recipe to many inputs in one workflow; run() partitions per input.
+// `projectMultiJobToRunResult` is intentionally NOT re-exported — it is the
+// @internal per-job producer consumed only by FilesRecipe.run (codex).
+export { FilesRecipe } from './file-first.js';
+// File-first execution (FF2b / MfV0PDok) — Node streaming downloader bound by
+// `Recipe.run()` to write pre-signed output URLs to disk.
+export { HttpDownloader } from './http-downloader.js';
+// `projectDownloadsToRunResult` is intentionally NOT re-exported here — it is an
+// @internal helper shared between `file-first.ts` (Recipe.run) and `handle.ts`
+// (Handle.wait/result) via direct intra-package import, not public API (codex).
+// File-first Handle + StatusSnapshot (FF5a / Ao8RPVxD) — method-bearing,
+// client-bound value objects. `Handle` is the return of `submit()` (no client)
+// AND `client.workflow(id)` (client-bound, reattach). Exported as VALUES (the
+// prior `export type { Handle }` is replaced) because `Handle` is now a class.
+export { Handle, StatusSnapshot } from './handle.js';
 // Ergonomic-layer entrypoint (T1 / wVU4xHx3) — `gisl.create()` factory +
 // credential-chain types. `gisl.anonymous()` (public export) lands once
 // the anonymous-capable operation allowlist is non-empty (plan §12).

package/dist/merge.d.ts

@@ -26,7 +26,8 @@
  * assets both fail fast so the caller saves bandwidth on typo'd composes.
  */
 import type { GislClient } from './client.js';
-import { type Handle, type Result, type RunOptions, type SubmitOptions } from './builder.js';
+import { type Result, type RunOptions, type SubmitOptions } from './builder.js';
+import { Handle } from './handle.js';
 /**
  * A declared merge asset. `path` carries a string or Blob (deduped by
  * normalised source key); `handle` wraps an already-uploaded file (deduped

package/dist/merge.js

@@ -25,9 +25,10 @@
  * 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 { uploadSource, jobOutputSource } from './types.js';
 import { GislConfigError, GislPerInputOptionsNotSupportedError, GislTimeoutError, GislUndeclaredAssetError, GislUnusedAssetError, } from './errors.js';
 import { _checkAborted, _consumeSseToTerminal, _parseMaxWait, _pollToTerminal, _projectResult, } from './builder.js';
+import { Handle } from './handle.js';
 /**
  * Construct a path-asset. Bare-string arguments to `merge(...)` are
  * implicitly wrapped via this helper.
@@ -117,7 +118,14 @@ 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);
-        return _projectResult(finalStatus, downloads.downloads, this.opOptionsForResolved());
+        // 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
+        // are plumbing, not the merge deliverable — surfacing them as artifacts
+        // 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());
     }
     async submit(options) {
         const plan = this.planSequence();
@@ -125,11 +133,9 @@ export class MergeBuilder {
         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;
+        // No client passed → the returned Handle's status()/wait()/result()
+        // throw `no_client`; the merge submit reconciles via webhook.
+        return new Handle(created.workflowId, created.webhookSecret != null ? created.webhookSecret : undefined);
     }
     // ---------------------------------------------------------------------------
     /**
@@ -247,12 +253,38 @@ export class MergeBuilder {
         return uploaded;
     }
     buildPayload(plan, uploadedByAssetId) {
-        const inputs = plan.positions.map((pos) => {
+        // p0SuJEeK — the API rejects upload-direct multi-input
+        // (`MultiInputSource` excludes the `upload` leaf: "use type=job_output").
+        // So each uploaded asset is wrapped in its OWN single-input `passthrough`
+        // source job, and the merge job references those via `job_output` — the
+        // shape the v2.35.0 `v2_merge_two_uploads` example prescribes. One source
+        // job per UNIQUE asset (in first-seen position order); a repeated asset
+        // re-uses its src job. `passthrough` is a lossless inert op (it does NOT
+        // get the implicit compress an empty `operations: []` job would).
+        const srcIdByAsset = new Map();
+        const sourceJobs = [];
+        for (const pos of plan.positions) {
+            if (srcIdByAsset.has(pos.assetId))
+                continue;
             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`);
             }
+            const srcId = `src_${sourceJobs.length}`;
+            srcIdByAsset.set(pos.assetId, srcId);
+            sourceJobs.push({
+                id: srcId,
+                source: uploadSource(fileId),
+                operations: [{ type: 'passthrough' }],
+            });
+        }
+        const inputs = plan.positions.map((pos) => {
+            // Defensive — srcIdByAsset was populated for every position's asset above.
+            const srcId = srcIdByAsset.get(pos.assetId);
+            if (srcId === undefined) {
+                throw new Error(`Asset '${pos.assetId}' has no source job — 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
@@ -261,7 +293,7 @@ export class MergeBuilder {
             const wireOpts = plan.mediaKind === 'image'
                 ? {}
                 : wirePerInputOptions(pos.options, plan.mediaKind);
-            const input = { source: uploadSource(fileId) };
+            const input = { source: jobOutputSource(srcId) };
             if (Object.keys(wireOpts).length > 0) {
                 input.per_input_options = wireOpts;
             }
@@ -269,12 +301,12 @@ export class MergeBuilder {
         });
         // Merge-level options (excluding the SDK-side mediaKind/allowUnusedAssets).
         const mergeOpts = wireMergeOptions(this.opOptions, plan.mediaKind);
-        const job = {
+        const mergeJob = {
             id: 'merge',
             inputs,
             operations: [{ type: 'merge', options: mergeOpts }],
         };
-        return { jobs: [job] };
+        return { jobs: [...sourceJobs, mergeJob] };
     }
     opOptionsForResolved() {
         // Strip the SDK-only fields before exposing on resolvedOptions.applied.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@giveitsmaller/sdk",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Node.js SDK for the GISL (Give It Smaller) file compression and processing API",
   "license": "MIT",
   "type": "module",
@@ -19,12 +19,12 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@giveitsmaller/contracts": "^0.8.0"
+    "@giveitsmaller/contracts": "^0.9.0"
   },
   "devDependencies": {
     "@types/node": "^22",
     "typescript": "^5.7",
-    "vitest": "^3.1",
+    "vitest": "^3.1 <3.2.5",
     "yaml": "^2.6"
   },
   "scripts": {