@giveitsmaller/sdk 0.2.2 → 0.4.0

package/dist/errors.d.ts

@@ -1,21 +1,78 @@
+import type { AuthErrorResponse, BalanceExhaustedResponse, FeatureNotAvailableResponse, FeatureTierRestrictedResponse, TierRestrictionResponse, WorkflowExpiredResponse } from '@giveitsmaller/contracts/openapi';
 export declare class GislError extends Error {
     constructor(message: string);
 }
+/**
+ * Optional structured fields carried alongside a typed API error. The
+ * localisation triple (`messageKey`, `locale`, `messageParams`) mirrors the
+ * `ErrorEnvelope` localisation contract from `compression_contracts`
+ * (ticket I26). `payload` carries the full typed response envelope for the
+ * structured error subclasses that have one.
+ */
+export interface GislApiErrorOptions {
+    readonly messageKey?: string;
+    readonly locale?: string;
+    readonly messageParams?: Record<string, unknown>;
+    readonly payload?: unknown;
+}
 export declare class GislApiError extends GislError {
     readonly statusCode: number;
     readonly errorMessage: string;
-    constructor(statusCode: number, errorMessage: string);
+    readonly path?: string;
+    readonly details?: unknown;
+    readonly messageKey?: string;
+    readonly locale?: string;
+    readonly messageParams?: Record<string, unknown>;
+    readonly payload?: unknown;
+    constructor(statusCode: number, errorMessage: string, path?: string, details?: unknown, options?: GislApiErrorOptions);
+}
+/**
+ * Shape of a single validation detail entry. Mirrors the v2
+ * `ValidationErrorEnvelopeDetailsInner` contract: only `message` is required;
+ * `field` / `operation` / `option` are mutually-permissive identifiers (a
+ * given detail may carry one, two, or all three depending on whether the
+ * violation is single-field, per-option, or cross-field).
+ */
+export interface GislValidationDetail {
+    readonly message: string;
+    readonly field?: string;
+    readonly operation?: string;
+    readonly option?: string;
+    readonly messageKey?: string;
+    readonly locale?: string;
+    readonly messageParams?: Record<string, unknown>;
 }
 export declare class GislValidationError extends GislApiError {
-    readonly details: Array<{
-        field: string;
-        message: string;
-    }>;
-    constructor(statusCode: number, errorMessage: string, details: Array<{
-        field: string;
-        message: string;
-    }>);
+    readonly details: GislValidationDetail[];
+    constructor(statusCode: number, errorMessage: string, details: GislValidationDetail[], path?: string, options?: GislApiErrorOptions);
+}
+export declare class GislBalanceExhaustedError extends GislApiError {
+    readonly payload: BalanceExhaustedResponse;
+    constructor(statusCode: number, errorMessage: string, payload: BalanceExhaustedResponse, path?: string, extra?: Omit<GislApiErrorOptions, 'payload'>);
+}
+export declare class GislTierRestrictedError extends GislApiError {
+    readonly payload: TierRestrictionResponse;
+    constructor(statusCode: number, errorMessage: string, payload: TierRestrictionResponse, path?: string, extra?: Omit<GislApiErrorOptions, 'payload'>);
+}
+export declare class GislFeatureTierRestrictedError extends GislApiError {
+    readonly payload: FeatureTierRestrictedResponse;
+    constructor(statusCode: number, errorMessage: string, payload: FeatureTierRestrictedResponse, path?: string, extra?: Omit<GislApiErrorOptions, 'payload'>);
+}
+export declare class GislFeatureNotAvailableError extends GislApiError {
+    readonly payload: FeatureNotAvailableResponse;
+    constructor(statusCode: number, errorMessage: string, payload: FeatureNotAvailableResponse, path?: string, extra?: Omit<GislApiErrorOptions, 'payload'>);
+}
+export declare class GislWorkflowExpiredError extends GislApiError {
+    readonly payload: WorkflowExpiredResponse;
+    constructor(statusCode: number, errorMessage: string, payload: WorkflowExpiredResponse, path?: string, extra?: Omit<GislApiErrorOptions, 'payload'>);
+}
+export declare class GislAuthError extends GislApiError {
+    readonly payload: AuthErrorResponse;
+    constructor(statusCode: number, errorMessage: string, payload: AuthErrorResponse, path?: string, extra?: Omit<GislApiErrorOptions, 'payload'>);
 }
 export declare class GislTimeoutError extends GislError {
     constructor(message: string);
 }
+export declare class GislAbortError extends GislError {
+    constructor(message: string);
+}

package/dist/errors.js

@@ -7,19 +7,76 @@ export class GislError extends Error {
 export class GislApiError extends GislError {
     statusCode;
     errorMessage;
-    constructor(statusCode, errorMessage) {
-        super(`API error ${statusCode}: ${errorMessage}`);
+    path;
+    details;
+    messageKey;
+    locale;
+    messageParams;
+    payload;
+    constructor(statusCode, errorMessage, path, details, options) {
+        const prefix = path
+            ? `API error ${statusCode} at ${path}`
+            : `API error ${statusCode}`;
+        super(`${prefix}: ${errorMessage}`);
         this.name = 'GislApiError';
         this.statusCode = statusCode;
         this.errorMessage = errorMessage;
+        this.path = path;
+        this.details = details;
+        if (options) {
+            this.messageKey = options.messageKey;
+            this.locale = options.locale;
+            this.messageParams = options.messageParams;
+            this.payload = options.payload;
+        }
     }
 }
 export class GislValidationError extends GislApiError {
-    details;
-    constructor(statusCode, errorMessage, details) {
-        super(statusCode, errorMessage);
+    constructor(statusCode, errorMessage, details, path, options) {
+        super(statusCode, errorMessage, path, details, options);
         this.name = 'GislValidationError';
-        this.details = details;
+    }
+}
+// Shared constructor body for the structured-payload subclasses. Five of the
+// six subclasses below differ only in their typed `payload` and `name` —
+// factor the common construction here so each subclass remains a one-liner.
+function buildOptionsWithPayload(payload, extra) {
+    return { ...extra, payload };
+}
+export class GislBalanceExhaustedError extends GislApiError {
+    constructor(statusCode, errorMessage, payload, path, extra) {
+        super(statusCode, errorMessage, path, undefined, buildOptionsWithPayload(payload, extra));
+        this.name = 'GislBalanceExhaustedError';
+    }
+}
+export class GislTierRestrictedError extends GislApiError {
+    constructor(statusCode, errorMessage, payload, path, extra) {
+        super(statusCode, errorMessage, path, undefined, buildOptionsWithPayload(payload, extra));
+        this.name = 'GislTierRestrictedError';
+    }
+}
+export class GislFeatureTierRestrictedError extends GislApiError {
+    constructor(statusCode, errorMessage, payload, path, extra) {
+        super(statusCode, errorMessage, path, undefined, buildOptionsWithPayload(payload, extra));
+        this.name = 'GislFeatureTierRestrictedError';
+    }
+}
+export class GislFeatureNotAvailableError extends GislApiError {
+    constructor(statusCode, errorMessage, payload, path, extra) {
+        super(statusCode, errorMessage, path, undefined, buildOptionsWithPayload(payload, extra));
+        this.name = 'GislFeatureNotAvailableError';
+    }
+}
+export class GislWorkflowExpiredError extends GislApiError {
+    constructor(statusCode, errorMessage, payload, path, extra) {
+        super(statusCode, errorMessage, path, undefined, buildOptionsWithPayload(payload, extra));
+        this.name = 'GislWorkflowExpiredError';
+    }
+}
+export class GislAuthError extends GislApiError {
+    constructor(statusCode, errorMessage, payload, path, extra) {
+        super(statusCode, errorMessage, path, undefined, buildOptionsWithPayload(payload, extra));
+        this.name = 'GislAuthError';
     }
 }
 export class GislTimeoutError extends GislError {
@@ -28,3 +85,9 @@ export class GislTimeoutError extends GislError {
         this.name = 'GislTimeoutError';
     }
 }
+export class GislAbortError extends GislError {
+    constructor(message) {
+        super(message);
+        this.name = 'GislAbortError';
+    }
+}

package/dist/index.d.ts

@@ -1,10 +1,17 @@
 export { GislClient, DEFAULT_MULTIPART_FIRST_CHUNK_SIZE } from './client.js';
 export { verifyWebhook } from './webhook.js';
 export { parseSseStream } from './sse.js';
-export type { GislClientConfig, GislSseEvent, UploadOptions, WaitOptions, WorkflowCreatePayload, OperationDef, FileJobPayload, SourceJobPayload, InputsJobPayload, JobDefinitionPayload, } from './types.js';
-export { fileJob, sourceJob, inputsJob } from './types.js';
-export { GislError, GislApiError, GislValidationError, GislTimeoutError, } from './errors.js';
-export type { UploadResponse, WorkflowCreateResponse, WorkflowStatusResponse, WorkflowDownloadResponse, MetadataResponse, OperationsSchemaResponse, RetryResponse, JobDownload, OperationDownload, WebhookPayload, JobResponse, OperationResponse, OperationResult, ExportConfig, } from '@giveitsmaller/contracts/openapi';
-export { WorkflowStatus, OperationType, SseEventType, CallbackEventType, OperationStatus, JobStatus, } from '@giveitsmaller/contracts/openapi';
+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, } from './types.js';
+export { uploadSource, jobOutputSource, externalImportSource, connectionSource, } from './types.js';
+export { GislError, GislApiError, GislValidationError, GislBalanceExhaustedError, GislTierRestrictedError, GislFeatureTierRestrictedError, GislFeatureNotAvailableError, GislWorkflowExpiredError, GislAuthError, GislTimeoutError, GislAbortError, } from './errors.js';
+export type { GislApiErrorOptions } from './errors.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, 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, AuthErrorResponse, } from '@giveitsmaller/contracts/openapi';
+export { AudioWatermarkDecodeRequestMethodHintEnum, AudioWatermarkDecodeResponseMethodEnum, OperationInputModel, ExternalImportRequestProviderHintEnum, ContactSubject, CreditTransactionSourceBucket, UploadProbeStatus, UploadProbeProcessingClass, WorkflowCancelBillingEffect, WorkflowPauseRequiredAction, WorkflowStatus, WarningType, WorkflowWarningSeverity, OperationType, SseEventType, CallbackEventType, OperationStatus, JobStatus, JobInputV2RoleEnum, AuthErrorType, TierRestrictionKind, BalanceExhaustedResponseRequiredActionEnum, ProcessingClassReason, DeliveryPlanReason, UserTier, ProcessingClass, } from '@giveitsmaller/contracts/openapi';
 export type { SseOperationProgressData, SseOperationCompletedData, SseOperationFailedData, SseJobCompletedData, SseJobFailedData, SseWorkflowTerminalData, } from '@giveitsmaller/contracts/openapi';
-export type { CompressImageOptions, CompressVideoOptions, CompressAudioOptions, CompressDocumentPdfOptions, CompressDocumentOfficeOptions, CompressDocumentOdfOptions, CompressDocumentEpubOptions, ThumbnailImageOptions, ThumbnailVideoOptions, ThumbnailDocumentOptions, ConvertImageOptions, ConvertVideoOptions, ConvertAudioOptions, ConvertDocumentPdfOptions, MergeImageOptions, MergeVideoOptions, MergeAudioOptions, MergeDocumentOptions, ArchiveOptions, } from '@giveitsmaller/contracts/operations';
+export type { MultiOutputCompletion, PageIndexed, PositionIndexed, Unindexed, } from '@giveitsmaller/contracts/asyncapi';
+import type { MultiOutputCompletion as _MultiOutputCompletion } from '@giveitsmaller/contracts/asyncapi';
+export type OperationResultOutputEntry = _MultiOutputCompletion['outputs'][number];
+export type { CompressImageOptions, CompressVideoOptions, CompressAudioOptions, CompressDocumentPdfOptions, CompressDocumentOfficeOptions, CompressDocumentOdfOptions, CompressDocumentEpubOptions, ThumbnailImageOptions, ThumbnailVideoOptions, ThumbnailDocumentOptions, ConvertImageOptions, ConvertVideoOptions, ConvertAudioOptions, ConvertDocumentPdfOptions, MergeImageOptions, MergeVideoOptions, MergeVideoPerInputOptions, MergeAudioOptions, MergeAudioPerInputOptions, ArchiveOptions, ImageWatermarkImageOptions, ImageWatermarkImageGifOptions, ImageWatermarkVideoOptions, TextWatermarkImageOptions, CustomLumaVideoOptions, AudioOverlayAudioOptions, AudioOverlayVideoOptions, AudioWatermarkAudioOptions, AudioWatermarkVideoOptions, } from '@giveitsmaller/contracts/operations';
+export { ImageWatermarkImageAnchor, ImageWatermarkImageGifAnchor, ImageWatermarkVideoAnchor, TextWatermarkImageAnchor, TextWatermarkImageFontFamily, TextWatermarkImageWatermarkMode, AudioOverlayAudioMode, AudioOverlayVideoMode, AudioOverlayVideoNoAudioTrackBehaviour, AudioWatermarkAudioMethod, AudioWatermarkAudioRobustness, AudioWatermarkAudioDensity, AudioWatermarkVideoMethod, AudioWatermarkVideoRobustness, AudioWatermarkVideoDensity, } from '@giveitsmaller/contracts/operations';
+export { archiveMetadata, audioOverlayMetadata, audioWatermarkMetadata, compressMetadata, convertMetadata, customLumaMetadata, imageWatermarkMetadata, mergeMetadata, textWatermarkMetadata, thumbnailMetadata, } from '@giveitsmaller/contracts/operations';
+export type { OperationMetadata, AvailabilityValue, AvailabilityEntry, FeatureEntry, MimeGroupMetadata, OptionMetadata, ProcessingClassConstraints, } from '@giveitsmaller/contracts/operations';

package/dist/index.js

@@ -2,7 +2,31 @@
 export { GislClient, DEFAULT_MULTIPART_FIRST_CHUNK_SIZE } from './client.js';
 export { verifyWebhook } from './webhook.js';
 export { parseSseStream } from './sse.js';
-export { fileJob, sourceJob, inputsJob } from './types.js';
+export { uploadSource, jobOutputSource, externalImportSource, connectionSource, } from './types.js';
 // Errors
-export { GislError, GislApiError, GislValidationError, GislTimeoutError, } from './errors.js';
-export { WorkflowStatus, OperationType, SseEventType, CallbackEventType, OperationStatus, JobStatus, } from '@giveitsmaller/contracts/openapi';
+export { GislError, GislApiError, GislValidationError, GislBalanceExhaustedError, GislTierRestrictedError, GislFeatureTierRestrictedError, GislFeatureNotAvailableError, GislWorkflowExpiredError, GislAuthError, GislTimeoutError, GislAbortError, } from './errors.js';
+export { AudioWatermarkDecodeRequestMethodHintEnum, AudioWatermarkDecodeResponseMethodEnum, 
+// OperationInputModel — value-bearing enum (`single` | `multi`).
+// Surfaced on OperationSchemaDefinition.inputModel so form-renderers
+// can decide whether to render a single-file picker or a multi-file
+// input list.
+OperationInputModel, ExternalImportRequestProviderHintEnum, ContactSubject, CreditTransactionSourceBucket, UploadProbeStatus, UploadProbeProcessingClass, WorkflowCancelBillingEffect, WorkflowPauseRequiredAction, WorkflowStatus, WarningType, WorkflowWarningSeverity, OperationType, SseEventType, CallbackEventType, OperationStatus, JobStatus, JobInputV2RoleEnum, 
+// Error-payload discriminator enums — pair with the typed payload
+// types above for narrowing inside `error instanceof Gisl<X>Error`
+// branches.
+AuthErrorType, TierRestrictionKind, BalanceExhaustedResponseRequiredActionEnum, ProcessingClassReason, DeliveryPlanReason, 
+// UserTier + ProcessingClass — value-bearing forms (typeof const +
+// type alias). Sourced from openapi so consumers can do
+// `Object.values(UserTier)` for tier dropdowns or
+// `if (tier === UserTier.enterprise)` for narrowing typed error
+// payloads. The operations metadata-types versions are pure type
+// aliases (no runtime value); the openapi versions carry both the
+// string-union type and a const map. Per audit follow-up.
+UserTier, ProcessingClass, } from '@giveitsmaller/contracts/openapi';
+export { ImageWatermarkImageAnchor, ImageWatermarkImageGifAnchor, ImageWatermarkVideoAnchor, TextWatermarkImageAnchor, TextWatermarkImageFontFamily, TextWatermarkImageWatermarkMode, AudioOverlayAudioMode, AudioOverlayVideoMode, AudioOverlayVideoNoAudioTrackBehaviour, AudioWatermarkAudioMethod, AudioWatermarkAudioRobustness, AudioWatermarkAudioDensity, AudioWatermarkVideoMethod, AudioWatermarkVideoRobustness, AudioWatermarkVideoDensity, } from '@giveitsmaller/contracts/operations';
+// Per-operation metadata sidecars. Inspect `availability`,
+// `required_tier`, per-value gating, mime-group availability and
+// per-feature flags before submitting a workflow — the API will
+// otherwise reject planned ops with `feature_not_available` (422,
+// surfaces as `GislFeatureNotAvailableError`).
+export { archiveMetadata, audioOverlayMetadata, audioWatermarkMetadata, compressMetadata, convertMetadata, customLumaMetadata, imageWatermarkMetadata, mergeMetadata, textWatermarkMetadata, thumbnailMetadata, } from '@giveitsmaller/contracts/operations';

package/dist/types.d.ts

@@ -1,54 +1,144 @@
-import type { OperationType, CallbackEventType, SseEventType, SseOperationProgressData, SseOperationCompletedData, SseOperationFailedData, SseJobCompletedData, SseJobFailedData, SseWorkflowTerminalData } from '@giveitsmaller/contracts/openapi';
+import type { OperationType, OperationsSchemaResponse, CallbackEventType, SseEventType, SseOperationProgressData, SseOperationCompletedData, SseOperationFailedData, SseJobCompletedData, SseJobFailedData, SseWorkflowTerminalData, MultipartInitiateRequestMetadataHint, UploadProbeResponse } from '@giveitsmaller/contracts/openapi';
+import type { JobInputV2RoleEnum } from '@giveitsmaller/contracts/openapi';
 export interface GislClientConfig {
     baseUrl: string;
     apiKey?: string;
     headers?: Record<string, string>;
     timeout?: number;
+    /**
+     * Send credentials (cookies) on every fetch — required in browsers when
+     * authenticating via the session cookie issued by `POST /api/auth/login`
+     * (Symfony firewall). Default `false` — the SDK ships in API-key mode by
+     * default. Set to `true` for browser SPAs that drive the auth flow via
+     * `client.login()` / `client.logout()` so the session cookie persists
+     * across requests.
+     *
+     * Node session persistence (cookie-jar across processes) is out of scope —
+     * this flag only flips fetch's `credentials` option; cookie storage is the
+     * environment's responsibility.
+     */
+    useSessionCookie?: boolean;
     /** Threshold in bytes above which multipart upload is used (default: 10MB) */
     multipartThreshold?: number;
-    /** Max concurrent chunk uploads for multipart (default: 4) */
+    /**
+     * Max concurrent chunk uploads for multipart (default: 4). Non-finite or
+     * fractional values are coerced via `Math.floor`; `NaN`/`Infinity` and
+     * non-positive values fall back to the default. Zero workers would produce
+     * a multipart-complete with an incomplete parts array (silent corruption),
+     * so the sanitiser snaps below-1 to default rather than to 1.
+     */
     multipartConcurrency?: number;
+    /**
+     * Max total attempts per multipart S3 PUT, including the first try
+     * (default: 3 — one initial + two retries). 0 or 1 disables retry.
+     * Non-finite or fractional values are coerced via `Math.floor` and
+     * floored at 1; `NaN`/`Infinity` fall back to the default.
+     * Retries fire on 5xx/429 responses and on network TypeError; 4xx (other
+     * than 429) and abort signals fail fast.
+     */
+    multipartMaxAttempts?: number;
+    /**
+     * Base milliseconds for full-jitter exponential backoff between multipart
+     * retry attempts (default: 500). Each retry's delay is `random(0, base * 2^n)`
+     * where n is the zero-indexed retry number. `0` opts out of backoff (retries
+     * fire immediately) — useful for tests; not recommended for production where
+     * jitter is the only defence against thundering-herd retry storms against
+     * shared-throttling sources like S3. `NaN`/`Infinity` fall back to the default.
+     */
+    multipartRetryBaseMs?: number;
 }
 export interface OperationDef {
     type: OperationType;
     options?: Record<string, unknown>;
 }
-/** Job sourced from an uploaded file */
-export interface FileJobPayload {
-    ref: string;
+export interface UploadSourcePayload {
+    type: 'upload';
     file_id: string;
-    operations: OperationDef[];
 }
-/** Job sourced from a single upstream job's output */
-export interface SourceJobPayload {
-    ref: string;
-    source: {
-        ref: string;
-        operation?: string;
-    };
-    operations: OperationDef[];
+export interface JobOutputSourcePayload {
+    type: 'job_output';
+    from: string;
+    operation?: string;
 }
-/** Job sourced from multiple upstream jobs (merge/archive) */
-export interface InputsJobPayload {
-    ref: string;
-    inputs: Array<{
-        ref: string;
-        operation?: string;
-        per_input_options?: Record<string, unknown>;
-    }>;
+export interface ExternalImportSourcePayload {
+    type: 'external_import';
+    external_source_id: string;
+}
+export interface ConnectionSourcePayload {
+    type: 'connection';
+    connection_id: string;
+    path: string;
+}
+export type WorkflowSourcePayload = UploadSourcePayload | 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;
+    role?: JobInputV2RoleEnum;
+    per_input_options?: Record<string, unknown>;
+}
+export interface JobDefinitionPayload {
+    /**
+     * Optional local identifier within the workflow. Server auto-generates
+     * `^job_\d+$` when omitted; the SDK MUST NOT auto-generate. Required
+     * when this job is referenced by another job's `JobOutputSource.from`,
+     * `workflow_edges`, or `delivery.selection.explicit.refs[]`.
+     */
+    id?: string;
+    /** Single-input source. Mutually exclusive with `inputs[]` (server enforces). */
+    source?: WorkflowSourcePayload;
+    /** Multi-input list for merge / archive / image_watermark / custom_luma / audio_overlay. */
+    inputs?: JobInputV2Payload[];
     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;
 }
-export type JobDefinitionPayload = FileJobPayload | SourceJobPayload | InputsJobPayload;
-export declare function fileJob(ref: string, fileId: string, operations: OperationDef[]): FileJobPayload;
-export declare function sourceJob(ref: string, source: {
-    ref: string;
-    operation?: string;
-}, operations: OperationDef[]): SourceJobPayload;
-export declare function inputsJob(ref: string, inputs: Array<{
+export type ExternalDestinationPayload = {
+    type: 'connection';
+    connection_id: string;
+    path: string;
+} | {
+    type: 'external_import';
+    external_source_id: string;
+};
+export type DeliveryModePayload = 'individual' | 'bundle' | 'both';
+export type DeliveryBundleFormatPayload = 'zip' | 'tar_gz';
+export type DeliverySelectionTypePayload = 'terminal' | 'all_outputs' | 'explicit';
+export interface DeliveryOutputRefPayload {
     ref: string;
     operation?: string;
-    per_input_options?: Record<string, unknown>;
-}>, operations: OperationDef[]): InputsJobPayload;
+}
+export interface DeliverySelectionPayload {
+    type: DeliverySelectionTypePayload;
+    refs?: DeliveryOutputRefPayload[];
+}
+export interface DeliveryPayload {
+    mode?: DeliveryModePayload;
+    bundle_format?: DeliveryBundleFormatPayload;
+    bundle_filename?: string;
+    include_metadata?: boolean;
+    selection?: DeliverySelectionPayload;
+}
+export type ProcessingClassHintPayload = 'auto' | 'short_form_only' | 'long_form_allowed' | 'long_form_preferred';
+export interface WorkflowProcessingPayload {
+    class_hint?: ProcessingClassHintPayload;
+}
 export interface WorkflowCreatePayload {
     jobs: JobDefinitionPayload[];
     workflow_edges?: Array<{
@@ -57,12 +147,87 @@ export interface WorkflowCreatePayload {
     }>;
     callback_url?: string;
     callback_events?: CallbackEventType[];
-    export?: {
-        service: 's3';
-        bucket: string;
-        key_prefix?: string;
-        role_arn: string;
-    };
+    export?: ExternalDestinationPayload;
+    delivery?: DeliveryPayload;
+    processing?: WorkflowProcessingPayload;
+}
+/**
+ * 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
+ * POST /api/workflows. Not re-exported from `index.ts`; this is reachable
+ * 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 interface GetSchemaOptions {
+    /** Filter the schema to operations that accept this MIME type (e.g. `image/jpeg`). */
+    mimeType?: string;
+    /** Filter the schema to a single operation type. */
+    operation?: OperationType;
+    /**
+     * Conditional revalidation: send the previously-received `ETag` value to
+     * receive a 304-not-modified sentinel when the cached response is still
+     * fresh. Strong-ETag comparison.
+     */
+    ifNoneMatch?: string;
+    /**
+     * Conditional revalidation: send the previously-received `Last-Modified`
+     * value (HTTP-date) to receive a 304-not-modified sentinel when the
+     * cached response is still fresh.
+     */
+    ifModifiedSince?: string;
+    /** Cancel an in-flight schema fetch. Surfaces as `GislAbortError`. */
+    signal?: AbortSignal;
+}
+export type GetSchemaResult = {
+    notModified: false;
+    data: OperationsSchemaResponse;
+    etag?: string;
+    lastModified?: string;
+} | {
+    notModified: true;
+    etag?: string;
+    lastModified?: string;
+};
+export interface CreditsUsageOptions {
+    /**
+     * Page size. Server defaults to 20 and rejects values outside `[1, 100]`
+     * with a 400 validation envelope.
+     */
+    limit?: number;
+    /** Page offset (zero-based). Server default is 0. */
+    offset?: number;
+}
+/**
+ * Aggregated result of a `preflightClips()` batch probe — N parallel calls
+ * to `POST /api/uploads/{id}/probe`, partitioned by outcome so the caller
+ * can drop bad clips before submitting a long-form merge workflow (per
+ * plan v5 round 10 / F11). Aggregation is structural — `ok` is everything
+ * the server marked workflow-ready, `rejected` is everything else with a
+ * typed probe response, and `errors` carries probe-call failures (e.g.
+ * the 422 `feature_not_available` envelope returned while the endpoint is
+ * still `availability: planned`).
+ */
+export interface PreflightClipsResult {
+    /** Probes that returned `probe_status: 'ok'`. Safe to include in a workflow. */
+    ok: UploadProbeResponse[];
+    /**
+     * Probes that returned a non-`ok` `probe_status` (`corrupt`,
+     * `unsupported_codec`, `missing_metadata`). The caller should exclude
+     * these or convert them first.
+     */
+    rejected: UploadProbeResponse[];
+    /**
+     * Probe calls that themselves failed. Includes the
+     * `feature_not_available` (422) responses returned while the endpoint
+     * is `availability: planned` — narrow on `instanceof
+     * GislFeatureNotAvailableError` to detect that case.
+     */
+    errors: PreflightClipError[];
+}
+export interface PreflightClipError {
+    fileId: string;
+    error: unknown;
 }
 export interface WaitOptions {
     /** Poll interval in milliseconds (default: 2000) */
@@ -103,4 +268,20 @@ export type GislSseEvent = {
 export interface UploadOptions {
     /** Called with bytes uploaded so far (only for multipart) */
     onProgress?: (uploadedBytes: number, totalBytes: number) => void;
+    /**
+     * Cancel an in-flight upload. Aborting rejects the `uploadFile` promise with
+     * `GislAbortError`. Applies to the API requests (initiate, complete) and
+     * every S3 part PUT. Composes with the client-level per-request timeout —
+     * whichever callback fires first determines the error class: user abort
+     * first → `GislAbortError`; timer first → `GislTimeoutError`.
+     */
+    signal?: AbortSignal;
+    /**
+     * Optional metadata hint forwarded to multipart initiate so the server
+     * can size-check and preflight-route based on caller-asserted dimensions.
+     * Single-shot uploads ignore this field (the multipart initiate is the
+     * only endpoint that accepts it). Wire-encoded as a JSON-stringified
+     * single FormData field on the multipart/initiate request.
+     */
+    metadataHint?: MultipartInitiateRequestMetadataHint;
 }

package/dist/types.js

@@ -1,12 +1,33 @@
 // ---------------------------------------------------------------------------
-// Job factory functions
+// Source factories — return wire-format objects with the `type` discriminator
 // ---------------------------------------------------------------------------
-export function fileJob(ref, fileId, operations) {
-    return { ref, file_id: fileId, operations };
+export function uploadSource(fileId) {
+    return { type: 'upload', file_id: fileId };
 }
-export function sourceJob(ref, source, operations) {
-    return { ref, source, operations };
+export function jobOutputSource(from, operation) {
+    return operation === undefined
+        ? { type: 'job_output', from }
+        : { type: 'job_output', from, operation };
 }
-export function inputsJob(ref, inputs, operations) {
-    return { ref, inputs, operations };
+export function externalImportSource(externalSourceId) {
+    return { type: 'external_import', external_source_id: externalSourceId };
 }
+export function connectionSource(connectionId, path) {
+    return { type: 'connection', connection_id: connectionId, path };
+}
+/**
+ * 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
+ * POST /api/workflows. Not re-exported from `index.ts`; this is reachable
+ * only via deep imports and should not be treated as public API.
+ * @internal
+ */
+export const WORKFLOW_CREATE_PAYLOAD_KEYS = Object.freeze([
+    'jobs',
+    'workflow_edges',
+    'callback_url',
+    'callback_events',
+    'export',
+    'delivery',
+    'processing',
+]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@giveitsmaller/sdk",
-  "version": "0.2.2",
+  "version": "0.4.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.1.0"
+    "@giveitsmaller/contracts": "^0.3.0"
   },
   "devDependencies": {
     "@types/node": "^22",
@@ -31,6 +31,8 @@
     "build": "tsc",
     "prepack": "npm run build",
     "check": "tsc --noEmit",
-    "test": "vitest run"
+    "test": "vitest run",
+    "test:parity": "vitest run tests/parity",
+    "parity:update": "UPDATE_PARITY_FIXTURES=1 vitest run tests/parity"
   }
 }