@giveitsmaller/sdk 0.2.3 → 0.6.0

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,152 @@ 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;
+    /**
+     * Resume an in-progress multipart upload (SDK-3 / Wb6ebOMM).
+     *
+     * When set, `uploadFile()` skips `/multipart/initiate` entirely. Instead it
+     * walks `GET /api/uploads/multipart/{uploadId}/status` (paginated via
+     * `next_part_number_marker` / `is_truncated`), computes which parts are
+     * still missing, re-presigns them in batches of <=100 via
+     * `POST /api/uploads/multipart/{uploadId}/presign`, PUTs only the missing
+     * parts, then `POST /api/uploads/multipart/complete`.
+     *
+     * The caller's `file` argument MUST be byte-identical to the file used in
+     * the original initiate call (same byte content at the same offsets).
+     * Mismatched bytes will produce S3 etags that don't match the server's
+     * recorded state, and `/multipart/complete` will reject.
+     *
+     * Anonymous-initiated sessions cannot be resumed by an authed caller
+     * (server returns 403 → `GislMultipartSessionAuthRequiredError`); a
+     * non-existent or expired session returns 404 →
+     * `GislMultipartSessionNotFoundError`.
+     */
+    resumeUploadId?: string;
+    /**
+     * Called after every successful part PUT during fresh-upload AND resume
+     * paths. Receives a JSON-serialisable snapshot of the upload state — round-
+     * trippable via `JSON.stringify` for persistence across process restarts,
+     * so a future `uploadFile({ resumeUploadId: state.uploadId, ... })` can
+     * pick up where the prior process stopped.
+     *
+     * The callback is invoked OUTSIDE the per-part retry-scoped path: a throw
+     * here will fail the upload but NEVER trigger a duplicate PUT (mirrors the
+     * `onProgress` discipline at `client.ts:1195-1199`).
+     */
+    onCheckpoint?: (state: MultipartCheckpointState) => void;
+}
+/**
+ * JSON-serialisable snapshot of an in-progress multipart upload, emitted
+ * after every successful part PUT via `UploadOptions.onCheckpoint`. Designed
+ * to round-trip through `JSON.stringify` / `JSON.parse` so consumers can
+ * persist it across process restarts and resume via
+ * `uploadFile({ resumeUploadId: state.uploadId, ... })`.
+ *
+ * All fields are primitive: no `Date` (use the ISO-8601 string on
+ * `manifestExpiresAt`), no `Buffer`, no functions.
+ */
+export interface MultipartCheckpointState {
+    /** The server-assigned `upload_id` (UUID) used as `resumeUploadId` later. */
+    readonly uploadId: string;
+    /** Total parts the server computed for this upload. <=10 000. */
+    readonly totalParts: number;
+    /**
+     * Part numbers (1-indexed) that have been successfully PUT to S3 so far.
+     * Includes part 1 (the initiate first chunk) once a part >= 2 lands. Sorted
+     * ascending. Excluded numbers in `[1, totalParts]` are the still-missing
+     * set a resume must re-PUT.
+     */
+    readonly uploadedPartNumbers: readonly number[];
+    /**
+     * ISO-8601 wall-clock instant at which the server's durable manifest for
+     * this `uploadId` expires (currently a 48h TTL per the API-2 contract). On
+     * resume, clients SHOULD call `keepaliveUpload(uploadId)` every 12-24h to
+     * extend this, leaving >=24h of slack against the 48h ceiling even with
+     * worst-case clock skew between client and server.
+     */
+    readonly manifestExpiresAt: string;
+}
+/**
+ * One entry in `_Sdk3HandCodedMultipartStatusResult.uploadedParts`. Aggregated
+ * across all pages of the underlying `GET /status` endpoint by the SDK's
+ * walk-pagination loop.
+ *
+ * TODO(HxUmVr3Y): replace hand-coded shape on regen.
+ */
+export interface _Sdk3HandCodedUploadedPart {
+    readonly partNumber: number;
+    readonly etag: string;
+    readonly sizeBytes: number;
+    /** ISO-8601 last-modified instant of the S3 part. */
+    readonly lastModified: string;
+}
+/**
+ * Aggregated result of `getUploadStatus()` after the SDK has walked every
+ * page of the underlying `GET /api/uploads/multipart/{uploadId}/status`
+ * endpoint (paginated via `next_part_number_marker` / `is_truncated`).
+ * `uploadedParts` is the merged-and-sorted list of every part the server
+ * has recorded across all pages — callers see the complete state without
+ * needing to drive the pagination cursor themselves.
+ *
+ * TODO(HxUmVr3Y): replace hand-coded shape on regen.
+ */
+export interface _Sdk3HandCodedMultipartStatusResult {
+    readonly uploadId: string;
+    readonly multipartUploadId: string;
+    readonly cloudKey: string;
+    readonly totalParts: number;
+    /** Sorted ascending by `partNumber`; complete across all server-side pages. */
+    readonly uploadedParts: readonly _Sdk3HandCodedUploadedPart[];
+    /** ISO-8601 wall-clock when the durable session manifest expires. */
+    readonly manifestExpiresAt: string;
+    /** Server-recommended chunk size in bytes (matches the initiate envelope). */
+    readonly recommendedChunkSize: number;
+}
+/**
+ * One entry in `_Sdk3HandCodedPresignPartsResult.presignedUrls`. Shape mirrors
+ * the contract-pinned `PresignedUrlPart` from the initiate envelope; kept
+ * hand-coded here so the resume path does not depend on the generator's name
+ * for that shape (decoupling for the HxUmVr3Y regen window).
+ *
+ * TODO(HxUmVr3Y): replace hand-coded shape on regen.
+ */
+export interface _Sdk3HandCodedPresignedPart {
+    readonly partNumber: number;
+    readonly url: string;
+    readonly expiresAt: string;
+}
+/**
+ * Result of `presignParts()` — the server-issued presigned PUT URLs for the
+ * requested part numbers.
+ *
+ * TODO(HxUmVr3Y): replace hand-coded shape on regen.
+ */
+export interface _Sdk3HandCodedPresignPartsResult {
+    readonly uploadId: string;
+    readonly presignedUrls: readonly _Sdk3HandCodedPresignedPart[];
+}
+/**
+ * Result of `keepaliveUpload()` — the refreshed manifest TTL expiry instant.
+ *
+ * TODO(HxUmVr3Y): replace hand-coded shape on regen.
+ */
+export interface _Sdk3HandCodedKeepaliveResult {
+    readonly uploadId: string;
+    readonly manifestExpiresAt: string;
 }

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.3",
+  "version": "0.6.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.2.3"
+    "@giveitsmaller/contracts": "^0.4.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"
   }
 }