@giveitsmaller/sdk 0.4.0 → 0.6.0

package/dist/errors.d.ts

@@ -1,4 +1,4 @@
-import type { AuthErrorResponse, BalanceExhaustedResponse, FeatureNotAvailableResponse, FeatureTierRestrictedResponse, TierRestrictionResponse, WorkflowExpiredResponse } from '@giveitsmaller/contracts/openapi';
+import type { AuthErrorResponse, BalanceExhaustedResponse, FeatureNotAvailableResponse, FeatureTierRestrictedResponse, TierRestrictionResponse, UploadDurationExceedsTierResponse, UploadSizeExceedsTierResponse, WorkflowExpiredResponse } from '@giveitsmaller/contracts/openapi';
 export declare class GislError extends Error {
     constructor(message: string);
 }
@@ -70,9 +70,113 @@ export declare class GislAuthError extends GislApiError {
     readonly payload: AuthErrorResponse;
     constructor(statusCode: number, errorMessage: string, payload: AuthErrorResponse, path?: string, extra?: Omit<GislApiErrorOptions, 'payload'>);
 }
+/**
+ * Discriminates the four upload-too-big shapes the server can return:
+ * - `size_tier`        — 422 `upload_size_exceeds_tier` (typed payload present)
+ * - `duration_tier`    — 422 `upload_duration_exceeds_tier` (typed payload present)
+ * - `absolute_413`     — 413, the absolute across-tier cap. The contract models
+ *                        413 as a plain `ErrorEnvelope` with NO `error_type`
+ *                        discriminator, so there is NO typed payload for it.
+ * - `cap_v2_multipart` — 422 `FILE_TOO_LARGE_FOR_MULTIPART` (SDK-3 / Wb6ebOMM,
+ *                        pre-S3 capacity reject on the resume-support endpoints).
+ *                        The contract carries no structured payload for this
+ *                        code today — `payload` is undefined for this kind.
+ *
+ * **Caveat for exhaustive-narrowing consumers.** The `cap_v2_multipart` value
+ * was added in TS SDK 0.5.0 / PHP SDK 0.3.0. A consumer writing
+ * `switch (e.kind) { case 'size_tier': ... case 'duration_tier': ... default:
+ * absurd(e.kind); }` against the prior 3-value union now sees a non-exhaustive
+ * switch and must add the new arm. The bump is logged in CHANGELOG.md.
+ */
+export type GislUploadCapKind = 'size_tier' | 'duration_tier' | 'absolute_413' | 'cap_v2_multipart';
+/**
+ * A single class covering all three "upload exceeds a size/duration cap"
+ * responses (422 size-tier, 422 duration-tier, 413 absolute).
+ *
+ * CONSCIOUS DEVIATION from the one-typed-payload-per-class invariant that the
+ * other structured subclasses follow (`GislBalanceExhaustedError`,
+ * `GislWorkflowExpiredError`, …). Justification: the card mandates this single
+ * `GislUploadCapExceededError` name and SDK-3 / E2E-1 are blocked-on it, so
+ * splitting into size/duration subclasses would break a cross-ticket naming
+ * contract; and 413 carries no typed envelope at all (plain `ErrorEnvelope`),
+ * so a one-payload-per-class split could not cover it uniformly anyway. The
+ * `kind` discriminant + a union-typed (possibly absent) `payload` is the
+ * deliberate trade-off. This is the only structured error in the tree that
+ * does not bind exactly one payload type — documented here in the same spirit
+ * as the inline PHP↔TS divergence notes.
+ *
+ * The two multipart-part errors below are deliberately NOT folded in with a
+ * `kind`: they carry different fields (`partNumber`/`uploadId` for an instance
+ * PUT failure vs `requiredParts`/`maxParts` for the count-ceiling guard) and
+ * are thrown from the multipart path, not the response handler.
+ */
+export declare class GislUploadCapExceededError extends GislApiError {
+    readonly kind: GislUploadCapKind;
+    readonly payload: UploadSizeExceedsTierResponse | UploadDurationExceedsTierResponse | undefined;
+    constructor(statusCode: number, errorMessage: string, kind: GislUploadCapKind, payload: UploadSizeExceedsTierResponse | UploadDurationExceedsTierResponse | undefined, path?: string, extra?: Omit<GislApiErrorOptions, 'payload'>);
+}
+/**
+ * 404 `MULTIPART_SESSION_NOT_FOUND` — the durable multipart session referenced
+ * by a resume / status / presign / keepalive call cannot be located (expired
+ * past its 48h manifest TTL, deleted, or never existed). Thrown by the SDK-3
+ * resume-support endpoints (`getUploadStatus`, `presignParts`,
+ * `keepaliveUpload`, and the resume branch of `uploadFile`).
+ *
+ * Carries no typed structured payload — the contract for the 3 resume-support
+ * endpoints models this code as a plain `ErrorEnvelope`. Consumers should
+ * detect via `instanceof` and abandon the resume; a fresh `uploadFile()` call
+ * (without `resumeUploadId`) will start a new session.
+ */
+export declare class GislMultipartSessionNotFoundError extends GislApiError {
+    constructor(statusCode: number, errorMessage: string, path?: string, options?: GislApiErrorOptions);
+}
+/**
+ * 403 `MULTIPART_SESSION_OWNERSHIP` — the caller is authenticated but the
+ * multipart session belongs to a different user. Thrown by the SDK-3
+ * resume-support endpoints. The session itself exists (otherwise the server
+ * would return 404 NOT_FOUND); the caller's identity simply doesn't match
+ * `manifest.userId`. Consumers should abandon the resume.
+ */
+export declare class GislMultipartSessionOwnershipError extends GislApiError {
+    constructor(statusCode: number, errorMessage: string, path?: string, options?: GislApiErrorOptions);
+}
+/**
+ * 403 `MULTIPART_SESSION_AUTH_REQUIRED` — the multipart session was initiated
+ * anonymously (no `manifest.userId`) and the SDK-3 resume-support endpoints
+ * refuse to serve it on an authed caller. There is no "claim" workflow today
+ * to bind an authed identity to an anonymously-started session; that is the
+ * future flip tracked at upstream ticket 8LABloaz. Consumers hitting this on
+ * resume should abandon and re-upload from scratch under the authed identity.
+ */
+export declare class GislMultipartSessionAuthRequiredError extends GislApiError {
+    constructor(statusCode: number, errorMessage: string, path?: string, options?: GislApiErrorOptions);
+}
 export declare class GislTimeoutError extends GislError {
     constructor(message: string);
 }
 export declare class GislAbortError extends GislError {
     constructor(message: string);
 }
+/**
+ * A single S3 multipart part PUT failed terminally (after the configured
+ * retry attempts) or could not be read. Subclasses `GislError` — NOT
+ * `GislApiError` — because it carries no contract error envelope and is
+ * thrown from the multipart upload path, never from the response handler.
+ * Mirrors the `GislAbortError` shape, plus the failing part's identifiers.
+ */
+export declare class GislMultipartPartError extends GislError {
+    readonly partNumber: number;
+    readonly uploadId: string;
+    constructor(message: string, partNumber: number, uploadId: string);
+}
+/**
+ * The upload would require more than the S3 hard limit of 10 000 multipart
+ * parts at the server-provided chunk size. Client-side guard (Model A: the
+ * server computes the part plan; the SDK asserts the ceiling). Subclasses
+ * `GislError` for the same reason as `GislMultipartPartError`.
+ */
+export declare class GislMultipartPartCountError extends GislError {
+    readonly requiredParts: number;
+    readonly maxParts: number;
+    constructor(message: string, requiredParts: number, maxParts: number);
+}

package/dist/errors.js

@@ -79,6 +79,80 @@ export class GislAuthError extends GislApiError {
         this.name = 'GislAuthError';
     }
 }
+/**
+ * A single class covering all three "upload exceeds a size/duration cap"
+ * responses (422 size-tier, 422 duration-tier, 413 absolute).
+ *
+ * CONSCIOUS DEVIATION from the one-typed-payload-per-class invariant that the
+ * other structured subclasses follow (`GislBalanceExhaustedError`,
+ * `GislWorkflowExpiredError`, …). Justification: the card mandates this single
+ * `GislUploadCapExceededError` name and SDK-3 / E2E-1 are blocked-on it, so
+ * splitting into size/duration subclasses would break a cross-ticket naming
+ * contract; and 413 carries no typed envelope at all (plain `ErrorEnvelope`),
+ * so a one-payload-per-class split could not cover it uniformly anyway. The
+ * `kind` discriminant + a union-typed (possibly absent) `payload` is the
+ * deliberate trade-off. This is the only structured error in the tree that
+ * does not bind exactly one payload type — documented here in the same spirit
+ * as the inline PHP↔TS divergence notes.
+ *
+ * The two multipart-part errors below are deliberately NOT folded in with a
+ * `kind`: they carry different fields (`partNumber`/`uploadId` for an instance
+ * PUT failure vs `requiredParts`/`maxParts` for the count-ceiling guard) and
+ * are thrown from the multipart path, not the response handler.
+ */
+export class GislUploadCapExceededError extends GislApiError {
+    kind;
+    constructor(statusCode, errorMessage, kind, payload, path, extra) {
+        super(statusCode, errorMessage, path, undefined, buildOptionsWithPayload(payload, extra));
+        this.name = 'GislUploadCapExceededError';
+        this.kind = kind;
+    }
+}
+/**
+ * 404 `MULTIPART_SESSION_NOT_FOUND` — the durable multipart session referenced
+ * by a resume / status / presign / keepalive call cannot be located (expired
+ * past its 48h manifest TTL, deleted, or never existed). Thrown by the SDK-3
+ * resume-support endpoints (`getUploadStatus`, `presignParts`,
+ * `keepaliveUpload`, and the resume branch of `uploadFile`).
+ *
+ * Carries no typed structured payload — the contract for the 3 resume-support
+ * endpoints models this code as a plain `ErrorEnvelope`. Consumers should
+ * detect via `instanceof` and abandon the resume; a fresh `uploadFile()` call
+ * (without `resumeUploadId`) will start a new session.
+ */
+export class GislMultipartSessionNotFoundError extends GislApiError {
+    constructor(statusCode, errorMessage, path, options) {
+        super(statusCode, errorMessage, path, undefined, options);
+        this.name = 'GislMultipartSessionNotFoundError';
+    }
+}
+/**
+ * 403 `MULTIPART_SESSION_OWNERSHIP` — the caller is authenticated but the
+ * multipart session belongs to a different user. Thrown by the SDK-3
+ * resume-support endpoints. The session itself exists (otherwise the server
+ * would return 404 NOT_FOUND); the caller's identity simply doesn't match
+ * `manifest.userId`. Consumers should abandon the resume.
+ */
+export class GislMultipartSessionOwnershipError extends GislApiError {
+    constructor(statusCode, errorMessage, path, options) {
+        super(statusCode, errorMessage, path, undefined, options);
+        this.name = 'GislMultipartSessionOwnershipError';
+    }
+}
+/**
+ * 403 `MULTIPART_SESSION_AUTH_REQUIRED` — the multipart session was initiated
+ * anonymously (no `manifest.userId`) and the SDK-3 resume-support endpoints
+ * refuse to serve it on an authed caller. There is no "claim" workflow today
+ * to bind an authed identity to an anonymously-started session; that is the
+ * future flip tracked at upstream ticket 8LABloaz. Consumers hitting this on
+ * resume should abandon and re-upload from scratch under the authed identity.
+ */
+export class GislMultipartSessionAuthRequiredError extends GislApiError {
+    constructor(statusCode, errorMessage, path, options) {
+        super(statusCode, errorMessage, path, undefined, options);
+        this.name = 'GislMultipartSessionAuthRequiredError';
+    }
+}
 export class GislTimeoutError extends GislError {
     constructor(message) {
         super(message);
@@ -91,3 +165,36 @@ export class GislAbortError extends GislError {
         this.name = 'GislAbortError';
     }
 }
+/**
+ * A single S3 multipart part PUT failed terminally (after the configured
+ * retry attempts) or could not be read. Subclasses `GislError` — NOT
+ * `GislApiError` — because it carries no contract error envelope and is
+ * thrown from the multipart upload path, never from the response handler.
+ * Mirrors the `GislAbortError` shape, plus the failing part's identifiers.
+ */
+export class GislMultipartPartError extends GislError {
+    partNumber;
+    uploadId;
+    constructor(message, partNumber, uploadId) {
+        super(message);
+        this.name = 'GislMultipartPartError';
+        this.partNumber = partNumber;
+        this.uploadId = uploadId;
+    }
+}
+/**
+ * The upload would require more than the S3 hard limit of 10 000 multipart
+ * parts at the server-provided chunk size. Client-side guard (Model A: the
+ * server computes the part plan; the SDK asserts the ceiling). Subclasses
+ * `GislError` for the same reason as `GislMultipartPartError`.
+ */
+export class GislMultipartPartCountError extends GislError {
+    requiredParts;
+    maxParts;
+    constructor(message, requiredParts, maxParts) {
+        super(message);
+        this.name = 'GislMultipartPartCountError';
+        this.requiredParts = requiredParts;
+        this.maxParts = maxParts;
+    }
+}

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 export { GislClient, DEFAULT_MULTIPART_FIRST_CHUNK_SIZE } from './client.js';
 export { verifyWebhook } from './webhook.js';
 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, } from './types.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 { GislError, GislApiError, GislValidationError, GislBalanceExhaustedError, GislTierRestrictedError, GislFeatureTierRestrictedError, GislFeatureNotAvailableError, GislWorkflowExpiredError, GislAuthError, GislTimeoutError, GislAbortError, } from './errors.js';
-export type { GislApiErrorOptions } from './errors.js';
+export { GislError, GislApiError, GislValidationError, GislBalanceExhaustedError, GislTierRestrictedError, GislFeatureTierRestrictedError, GislFeatureNotAvailableError, GislWorkflowExpiredError, GislAuthError, GislUploadCapExceededError, GislMultipartPartError, GislMultipartPartCountError, GislMultipartSessionNotFoundError, GislMultipartSessionOwnershipError, GislMultipartSessionAuthRequiredError, GislTimeoutError, GislAbortError, } from './errors.js';
+export type { GislApiErrorOptions, GislUploadCapKind } 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';

package/dist/index.js

@@ -4,7 +4,9 @@ export { verifyWebhook } from './webhook.js';
 export { parseSseStream } from './sse.js';
 export { uploadSource, jobOutputSource, externalImportSource, connectionSource, } from './types.js';
 // Errors
-export { GislError, GislApiError, GislValidationError, GislBalanceExhaustedError, GislTierRestrictedError, GislFeatureTierRestrictedError, GislFeatureNotAvailableError, GislWorkflowExpiredError, GislAuthError, GislTimeoutError, GislAbortError, } from './errors.js';
+export { GislError, GislApiError, GislValidationError, GislBalanceExhaustedError, GislTierRestrictedError, GislFeatureTierRestrictedError, GislFeatureNotAvailableError, GislWorkflowExpiredError, GislAuthError, GislUploadCapExceededError, GislMultipartPartError, GislMultipartPartCountError, 
+// SDK-3 (Wb6ebOMM) — typed errors for the 3 resume-support endpoints.
+GislMultipartSessionNotFoundError, GislMultipartSessionOwnershipError, GislMultipartSessionAuthRequiredError, GislTimeoutError, GislAbortError, } from './errors.js';
 export { AudioWatermarkDecodeRequestMethodHintEnum, AudioWatermarkDecodeResponseMethodEnum, 
 // OperationInputModel — value-bearing enum (`single` | `multi`).
 // Surfaced on OperationSchemaDefinition.inputModel so form-renderers

package/dist/sse.d.ts

@@ -7,5 +7,24 @@ import type { GislSseEvent } from './types.js';
  * - Multi-line `data:` fields (concatenated with newlines)
  * - Comment lines (`:` prefix) used as keep-alives
  * - `retry:` field (ignored, SDK manages its own reconnection)
+ *
+ * `opts.signal` (optional): when it aborts, the underlying body reader is
+ * cancelled. This is the ONLY way to promptly stop a stream parked on a
+ * quiet socket: `reader.read()` is suspended, so the generator's `finally`
+ * cannot run until that read settles — calling `reader.cancel()` from the
+ * abort listener settles it (`{ done: true }`) and runs the stream's cancel
+ * algorithm, freeing the connection. (MDN/TC39: an async generator's
+ * `return()` is itself unreachable while suspended at `await`; cancellation
+ * must be driven externally via an AbortSignal.) `GislClient.streamEvents`
+ * owns the controller and wires `return()`/`throw()` → `abort()`.
+ *
+ * By-design limitation: when called WITHOUT `opts.signal`, there is no
+ * cancellation path while `reader.read()` is suspended — a consumer that
+ * `break`s / `gen.return()`s on a quiet socket stays stuck until the
+ * server sends data or closes (an inherent JS async-generator constraint,
+ * not a defect). Pass `opts.signal`, or prefer `GislClient.streamEvents`
+ * (which always wires one), whenever early termination must be prompt.
  */
-export declare function parseSseStream(response: Response): AsyncGenerator<GislSseEvent>;
+export declare function parseSseStream(response: Response, opts?: {
+    signal?: AbortSignal;
+}): AsyncGenerator<GislSseEvent>;

package/dist/sse.js

@@ -6,13 +6,51 @@
  * - Multi-line `data:` fields (concatenated with newlines)
  * - Comment lines (`:` prefix) used as keep-alives
  * - `retry:` field (ignored, SDK manages its own reconnection)
+ *
+ * `opts.signal` (optional): when it aborts, the underlying body reader is
+ * cancelled. This is the ONLY way to promptly stop a stream parked on a
+ * quiet socket: `reader.read()` is suspended, so the generator's `finally`
+ * cannot run until that read settles — calling `reader.cancel()` from the
+ * abort listener settles it (`{ done: true }`) and runs the stream's cancel
+ * algorithm, freeing the connection. (MDN/TC39: an async generator's
+ * `return()` is itself unreachable while suspended at `await`; cancellation
+ * must be driven externally via an AbortSignal.) `GislClient.streamEvents`
+ * owns the controller and wires `return()`/`throw()` → `abort()`.
+ *
+ * By-design limitation: when called WITHOUT `opts.signal`, there is no
+ * cancellation path while `reader.read()` is suspended — a consumer that
+ * `break`s / `gen.return()`s on a quiet socket stays stuck until the
+ * server sends data or closes (an inherent JS async-generator constraint,
+ * not a defect). Pass `opts.signal`, or prefer `GislClient.streamEvents`
+ * (which always wires one), whenever early termination must be prompt.
  */
-export async function* parseSseStream(response) {
+export async function* parseSseStream(response, opts = {}) {
     const body = response.body;
     if (!body) {
         return;
     }
+    const signal = opts.signal;
+    if (signal?.aborted) {
+        // Pre-aborted: the body is still unlocked (no reader yet), so cancel it
+        // directly to free the connection, then yield nothing.
+        await body.cancel().catch(() => { });
+        return;
+    }
     const reader = body.getReader();
+    // `reader.cancel()` is valid while the reader holds the lock (unlike
+    // `body.cancel()`, which throws "Cannot cancel a locked stream"). It
+    // settles the in-flight `reader.read()` with `{ done: true }` and runs
+    // the stream's cancel algorithm. We track `aborted` so the post-loop
+    // trailing flush below does NOT emit a partial, never-terminated event
+    // once the consumer has abandoned the stream (the cancelled read looks
+    // exactly like a clean EOF — `{ done: true }` — but a buffered
+    // unterminated `data:` run after an abort is garbage, not an event).
+    let aborted = false;
+    const onAbort = () => {
+        aborted = true;
+        void reader.cancel().catch(() => { });
+    };
+    signal?.addEventListener('abort', onAbort, { once: true });
     const decoder = new TextDecoder();
     let buffer = '';
     let eventType = '';
@@ -28,6 +66,12 @@ export async function* parseSseStream(response) {
             // Keep the last (potentially incomplete) line in the buffer
             buffer = lines.pop() ?? '';
             for (const line of lines) {
+                // If a single read delivered multiple complete events and the
+                // consumer aborted after receiving an earlier one (we were
+                // suspended at `yield`), do NOT keep emitting the remaining
+                // buffered events on resume — stop processing this batch.
+                if (aborted)
+                    break;
                 if (line === '') {
                     // Empty line = end of event
                     if (dataLines.length > 0) {
@@ -73,8 +117,12 @@ export async function* parseSseStream(response) {
                 }
             }
         }
-        // Flush any remaining buffered event
-        if (dataLines.length > 0) {
+        // Flush any remaining buffered event — but ONLY on a genuine
+        // end-of-stream (server closed without a final blank line). After an
+        // abort, the cancelled read also surfaces as `{ done: true }`, yet a
+        // partial unterminated `data:` buffer is not a real event and must
+        // not be yielded once the consumer has abandoned the stream.
+        if (!aborted && dataLines.length > 0) {
             const rawData = dataLines.join('\n');
             let parsed;
             try {
@@ -90,6 +138,17 @@ export async function* parseSseStream(response) {
         }
     }
     finally {
+        signal?.removeEventListener('abort', onAbort);
+        // Cancel the body so the underlying HTTP connection is released on
+        // EVERY exit path (early `return()`/abort AND normal completion) — a
+        // bare `releaseLock()` leaves the socket open until GC. Cancelling an
+        // already-closed/cancelled stream is a harmless no-op that resolves.
+        try {
+            await reader.cancel();
+        }
+        catch {
+            /* stream already errored/closed — nothing to release */
+        }
         reader.releaseLock();
     }
 }

package/dist/types.d.ts

@@ -284,4 +284,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@giveitsmaller/sdk",
-  "version": "0.4.0",
+  "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.3.0"
+    "@giveitsmaller/contracts": "^0.4.0"
   },
   "devDependencies": {
     "@types/node": "^22",