@giveitsmaller/sdk 0.4.0 → 0.7.0

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;
@@ -284,4 +282,136 @@ export interface UploadOptions {
      * 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

@@ -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.4.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.3.0"
+    "@giveitsmaller/contracts": "^0.8.0"
   },
   "devDependencies": {
     "@types/node": "^22",