@giveitsmaller/sdk 0.2.3 → 0.6.0

package/dist/errors.d.ts

@@ -1,23 +1,182 @@
+import type { AuthErrorResponse, BalanceExhaustedResponse, FeatureNotAvailableResponse, FeatureTierRestrictedResponse, TierRestrictionResponse, UploadDurationExceedsTierResponse, UploadSizeExceedsTierResponse, 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;
     readonly path?: string;
     readonly details?: unknown;
-    constructor(statusCode: number, errorMessage: string, path?: string, 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;
-    }>, path?: 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'>);
+}
+/**
+ * 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

@@ -9,7 +9,11 @@ export class GislApiError extends GislError {
     errorMessage;
     path;
     details;
-    constructor(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}`;
@@ -19,17 +23,178 @@ export class GislApiError extends GislError {
         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 {
-    constructor(statusCode, errorMessage, details, path) {
-        super(statusCode, errorMessage, path, details);
+    constructor(statusCode, errorMessage, details, path, options) {
+        super(statusCode, errorMessage, path, details, options);
         this.name = 'GislValidationError';
     }
 }
+// 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';
+    }
+}
+/**
+ * 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);
         this.name = 'GislTimeoutError';
     }
 }
+export class GislAbortError extends GislError {
+    constructor(message) {
+        super(message);
+        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,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, 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, 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';
-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,33 @@
 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, 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
+// 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/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();
     }
 }