@giveitsmaller/sdk 0.2.3 → 0.6.0

package/README.md

@@ -0,0 +1,58 @@
+# @giveitsmaller/sdk
+
+TypeScript / Node.js SDK for the [GISL](https://giveitsmaller.com) (Give It Smaller) file compression and processing API.
+
+## Install
+
+```bash
+npm install @giveitsmaller/sdk
+```
+
+Node.js 18+ required.
+
+## Quickstart
+
+```ts
+import { GislClient, uploadSource, OperationType } from '@giveitsmaller/sdk';
+
+const client = new GislClient({
+  baseUrl: 'https://api.giveitsmaller.com',
+  apiKey: 'REPLACE_ME_API_KEY',
+});
+
+const upload = await client.uploadFile('./photo.jpg');
+
+const workflow = await client.createWorkflow({
+  jobs: [
+    {
+      id: 'compressed',
+      source: uploadSource(upload.fileId),
+      operations: [
+        { type: OperationType.compress, options: { mode: 'lossy', quality: 80 } },
+      ],
+    },
+  ],
+});
+
+await client.waitForWorkflow(workflow.workflowId);
+
+const dls = await client.getWorkflowDownloads(workflow.workflowId);
+console.log('Compressed:', dls.downloads[0].files[0].downloadUrl);
+```
+
+## Full documentation
+
+Docs are published in the [giveitsmaller-sdks](https://github.com/AntonioCS/giveitsmaller-sdks) repository — they are **not** shipped in the npm tarball (only `dist/` is published).
+
+- **Getting started & concepts** — [`docs/typescript/index.md`](https://github.com/AntonioCS/giveitsmaller-sdks/blob/main/docs/typescript/index.md)
+- **Client reference** (all `GislClient` methods + operation option list) — [`docs/typescript/client.md`](https://github.com/AntonioCS/giveitsmaller-sdks/blob/main/docs/typescript/client.md)
+- **Types & authoring primitives** (config, payloads, job factories) — [`docs/typescript/types.md`](https://github.com/AntonioCS/giveitsmaller-sdks/blob/main/docs/typescript/types.md)
+- **SSE / live progress** — [`docs/typescript/sse.md`](https://github.com/AntonioCS/giveitsmaller-sdks/blob/main/docs/typescript/sse.md)
+- **Webhooks** — [`docs/typescript/webhook.md`](https://github.com/AntonioCS/giveitsmaller-sdks/blob/main/docs/typescript/webhook.md)
+- **Errors & retry guidance** — [`docs/typescript/errors.md`](https://github.com/AntonioCS/giveitsmaller-sdks/blob/main/docs/typescript/errors.md)
+- **Troubleshooting** — [`docs/typescript/troubleshooting.md`](https://github.com/AntonioCS/giveitsmaller-sdks/blob/main/docs/typescript/troubleshooting.md)
+- **Examples** — compress, thumbnail, convert, merge, archive — [`docs/typescript/examples/`](https://github.com/AntonioCS/giveitsmaller-sdks/tree/main/docs/typescript/examples)
+
+## License
+
+MIT — see the [LICENSE](https://github.com/AntonioCS/giveitsmaller-sdks/blob/main/LICENSE) file.

package/dist/_audit.d.ts

@@ -0,0 +1 @@
+export declare function _runAudit(): void;

package/dist/_audit.js

@@ -0,0 +1,64 @@
+// Per ticket J65ZERTi (T20) — public-API completeness audit gate.
+//
+// This file sits inside `src/` so it is type-checked by `tsc --noEmit`
+// (the test directory is excluded from `tsconfig.json` so a test-side
+// audit is dead — earlier follow-up review caught this). The list of
+// type-only imports here IS the gate: if a regen drops or renames any
+// symbol, `tsc` fails on the import line.
+//
+// Each `accept<T>()` call resolves the type parameter; the function
+// itself is a no-op. The body is never invoked at runtime — only the
+// import resolution matters.
+function accept(_value) {
+    // intentionally empty — type-presence is the assertion
+}
+// One call per imported type. tsc resolves the type parameter against
+// the import; if the import is broken, the call site fails to compile.
+export function _runAudit() {
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    // SDK-3 (Wb6ebOMM) public-API surface for the 3 resume-support endpoints.
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+    accept();
+}

package/dist/client.d.ts

@@ -1,15 +1,29 @@
-import type { UploadResponse, WorkflowCreateResponse, WorkflowStatusResponse, WorkflowDownloadResponse, MetadataResponse, OperationsSchemaResponse, RetryResponse } from '@giveitsmaller/contracts/openapi';
-import type { GislClientConfig, GislSseEvent, UploadOptions, WaitOptions, WorkflowCreatePayload } from './types.js';
+import type { AudioWatermarkDecodeRequest, AudioWatermarkDecodeResponse, ExternalImportCreatedResponse, ExternalImportRequest, LoginUserRequest, LoginUser200ResponseData, ContactRequest, CreditsBalanceResponse, CreditsUsageResponse, UploadResponse, UploadProbeResponse, WorkflowCancelResponse, WorkflowCreateResponse, WorkflowResumeResponse, WorkflowStatusResponse, WorkflowDownloadResponse, MetadataResponse, RetryResponse } from '@giveitsmaller/contracts/openapi';
+import type { CreditsUsageOptions, GetSchemaOptions, GetSchemaResult, GislClientConfig, GislSseEvent, PreflightClipsResult, UploadOptions, WaitOptions, WorkflowCreatePayload, _Sdk3HandCodedKeepaliveResult, _Sdk3HandCodedMultipartStatusResult, _Sdk3HandCodedPresignPartsResult } from './types.js';
+export declare const MULTIPART_CONCURRENCY_DEFAULT: 4;
 export declare const DEFAULT_MULTIPART_FIRST_CHUNK_SIZE: number;
+export interface ValidationDetail {
+    message: string;
+    field?: string;
+    operation?: string;
+    option?: string;
+    messageKey?: string;
+    locale?: string;
+    messageParams?: Record<string, unknown>;
+}
 export declare class GislClient {
     private readonly baseUrl;
     private readonly headers;
     private readonly timeoutMs;
     private readonly multipartThreshold;
     private readonly multipartConcurrency;
+    private readonly multipartMaxAttempts;
+    private readonly multipartRetryBaseMs;
+    private readonly useSessionCookie;
     constructor(config: GislClientConfig);
     private request;
     private handleResponse;
+    private isAuthErrorType;
     /**
      * Upload a file. Automatically uses multipart upload for files exceeding
      * the configured threshold (default 10 MB).
@@ -31,6 +45,88 @@ export declare class GislClient {
      * post-upload metadata callers should use getMetadata(fileId).
      */
     private multipartUpload;
+    /**
+     * SDK-3 (Wb6ebOMM): resume an in-progress multipart upload.
+     *
+     * Skips `/multipart/initiate` entirely (the original initiate happened in a
+     * prior process). Walks `/status` for the authoritative list of recorded
+     * parts, re-presigns the missing ones in batches of <=100, PUTs only those,
+     * and finalises with `/complete`. Caller's `source` MUST be byte-identical
+     * to the originally-uploaded file at the same offsets (parts whose etags
+     * don't match server state will fail `/complete`).
+     *
+     * Re-runs the same `uploadId` / `chunkSize` / `totalParts` / plan-consistency
+     * guards as the fresh-upload path (`multipartUpload`), using the /status
+     * envelope as the equivalent of the initiate envelope. Reuses the same
+     * `failureController` sibling-wake + `drainResponseBody` cleanup discipline
+     * as the fresh-upload PUT loop. `onProgress` fires on entry seeded from
+     * (uploadedPartNumbers.length * chunkSize) and again after every successful
+     * PUT. `onCheckpoint` fires OUTSIDE the retry-scoped path after every
+     * successful PUT — a callback-throw must not trigger a duplicate PUT.
+     *
+     * TODO(HxUmVr3Y): replace inline hand-coded request body marshalling on regen.
+     */
+    private multipartResume;
+    /**
+     * Fetch the durable status of an in-progress multipart upload session.
+     *
+     * Walks every page of `GET /api/uploads/multipart/{uploadId}/status`
+     * (paginated via `next_part_number_marker` + `is_truncated`) and returns
+     * the aggregated state. Callers see the complete set of recorded parts
+     * across pages without driving the cursor themselves.
+     *
+     * Anonymous-initiated sessions return 403 → `GislMultipartSessionAuthRequiredError`.
+     * Non-existent / expired sessions return 404 → `GislMultipartSessionNotFoundError`.
+     * Authed-but-non-owning callers return 403 → `GislMultipartSessionOwnershipError`.
+     *
+     * TODO(HxUmVr3Y): replace hand-coded response shape on regen.
+     */
+    getUploadStatus(uploadId: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<_Sdk3HandCodedMultipartStatusResult>;
+    /**
+     * Re-presign a batch of missing part numbers on an in-progress multipart
+     * session.
+     *
+     * Validates client-side BEFORE the HTTP round-trip:
+     * - `partNumbers` non-empty
+     * - length <=100 (server raw-body cap is 8 KiB before json_decode)
+     * - every entry an integer in `[2, totalParts]` — part 1 is sealed at
+     *   initiate (re-presigning it would break the etag recorded server-side
+     *   for /complete)
+     * - entries unique
+     * - `totalParts` <=10 000 (S3 hard limit; mirrors the SDK-1 ceiling guard)
+     *
+     * TODO(HxUmVr3Y): replace hand-coded request/response shapes on regen.
+     */
+    presignParts(uploadId: string, partNumbers: readonly number[], totalParts: number, opts?: {
+        signal?: AbortSignal;
+    }): Promise<_Sdk3HandCodedPresignPartsResult>;
+    /**
+     * Extend the manifest TTL of an in-progress multipart upload session.
+     *
+     * The durable session manifest defaults to a 48 h TTL (decoupled from the
+     * shorter presigned-URL TTL). For a long-running resume that spans days
+     * (e.g. an upload paused overnight on flaky Wi-Fi), callers SHOULD invoke
+     * `keepaliveUpload` every **12-24 h** while resuming — the 12-24 h band
+     * leaves >=24 h of slack against the 48 h ceiling even with worst-case
+     * clock skew between client and server. The server atomically refreshes
+     * the Redis EXPIRE for the manifest key; the call is idempotent.
+     *
+     * TODO(HxUmVr3Y): replace hand-coded response shape on regen.
+     */
+    keepaliveUpload(uploadId: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<_Sdk3HandCodedKeepaliveResult>;
+    /**
+     * Private walk-pagination helper for /status. Aggregates every page into
+     * a single `_Sdk3HandCodedMultipartStatusResult`. AbortSignal short-circuits
+     * the loop between page fetches AND propagates into each fetch.
+     *
+     * Limit pinned to 1000 (max per page) so we make the minimum number of
+     * round-trips even for the worst-case ~10 pages on a 10 000-part upload.
+     */
+    private walkUploadStatus;
     /**
      * Create a new workflow.
      */
@@ -43,6 +139,41 @@ export declare class GislClient {
      * Poll until the workflow reaches a terminal status.
      */
     waitForWorkflow(workflowId: string, options?: WaitOptions): Promise<WorkflowStatusResponse>;
+    /**
+     * Cancel a workflow. Idempotent — cancelling an already-cancelled
+     * workflow returns 200 with the same shape (and the original
+     * `cancelledAt`). Cancelling a `completed` / `failed` /
+     * `partially_failed` / `expired` workflow returns 409.
+     *
+     * The response's `billingEffect` field tells the caller what
+     * happened to outstanding reservations:
+     * - `unspent_reservation_released` — workflow was active or paused
+     *   and the unspent portion of the reservation has been refunded.
+     *   The refund appears as a separate `CreditTransaction` with
+     *   `type: refund`.
+     * - `none` — no refund (all reserved credits were already consumed
+     *   by completed jobs, or this is an idempotent re-cancel).
+     *
+     * In-flight operations may continue running briefly after the
+     * cancel response while their Lambda processes terminate; the
+     * response is the binding "no further reservations will be made"
+     * signal.
+     */
+    cancelWorkflow(workflowId: string): Promise<WorkflowCancelResponse>;
+    /**
+     * Resume a workflow that is in `paused_insufficient_credits`.
+     *
+     * Resume succeeds only when `availableCredits` covers the next
+     * reservation. If the balance is still insufficient, throws
+     * `GislBalanceExhaustedError` (402, same envelope as the workflow-
+     * create 402 path) and the workflow stays paused. If the workflow
+     * is past its `expiresAt` (default 7-day TTL from `pausedAt`),
+     * throws `GislWorkflowExpiredError` (422) and the workflow has
+     * transitioned to `expired` — callers cannot un-expire a workflow.
+     * Resuming a workflow that is not in `paused_insufficient_credits`
+     * is a 409 (no-op).
+     */
+    resumeWorkflow(workflowId: string): Promise<WorkflowResumeResponse>;
     /**
      * Get download URLs for a completed workflow.
      */
@@ -50,18 +181,137 @@ export declare class GislClient {
     /**
      * Stream SSE events for a workflow. Returns an async iterable.
      */
-    streamEvents(workflowId: string): Promise<AsyncGenerator<GislSseEvent>>;
+    streamEvents(workflowId: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<AsyncGenerator<GislSseEvent>>;
     /**
      * Get metadata for an uploaded file.
      */
     getMetadata(fileId: string): Promise<MetadataResponse>;
     /**
      * Get the operations schema (available types, options, constraints).
-     * This endpoint returns raw JSON (no envelope) and is CDN-cacheable.
+     *
+     * Returns raw JSON (no envelope). The response is **per-tier private**
+     * (cache key includes the caller's `user_tier`); CDN-style public
+     * caching is not used. Pass `ifNoneMatch` / `ifModifiedSince` from a
+     * previous response to revalidate — a 304 surfaces as
+     * `{ notModified: true, etag, lastModified }` so callers can keep
+     * using their cached copy.
      */
-    getSchema(): Promise<OperationsSchemaResponse>;
+    getSchema(options?: GetSchemaOptions): Promise<GetSchemaResult>;
     /**
      * Retry a failed operation.
      */
     retryOperation(operationId: string): Promise<RetryResponse>;
+    /**
+     * Submit a contact-form message. The endpoint returns 204 No Content on
+     * success, so this method resolves to `void`.
+     *
+     * Validation errors (e.g. missing `email`, non-empty honeypot `website`)
+     * surface as `GislValidationError` from the standard error envelope.
+     */
+    submitContact(payload: ContactRequest): Promise<void>;
+    /**
+     * Get a snapshot of the caller's current credit position. The canonical
+     * billing-state surface — `BalanceExhaustedResponse` (402) on workflow
+     * creation includes pre-error counters for context, but UIs should drive
+     * spend-now affordances and tier-upgrade prompts off this endpoint, not
+     * off the error envelope.
+     */
+    getCreditsBalance(): Promise<CreditsBalanceResponse>;
+    /**
+     * Authenticate with email/password. On success the server issues a
+     * session cookie via `Set-Cookie`; subsequent requests authenticate
+     * via that cookie when the client is configured with
+     * `useSessionCookie: true`.
+     *
+     * Failure modes per ticket FX6mbTJD:
+     * - **401** `invalid_credentials` (collapsed with unverified
+     *   accounts for anti-enumeration) → `GislAuthError`.
+     * - **403** account-state failures (`account_locked`,
+     *   `account_disabled`, `account_deleted`,
+     *   `account_deletion_expired`) → `GislAuthError`.
+     * - **429** infrastructure rate-limit → `GislApiError` with
+     *   the `Retry-After` header echoed on the response.
+     *
+     * Node session persistence (cookie-jar across processes) is out of
+     * scope — this method only touches the request side.
+     */
+    login(credentials: LoginUserRequest): Promise<LoginUser200ResponseData>;
+    /**
+     * Invalidate the current session.
+     *
+     * Idempotent: calling logout without an active session returns 401,
+     * but the SDK collapses both 200 and 401 into a single "logged out"
+     * outcome — `logout()` resolves to `void` in either case so caller
+     * cleanup code does not need to special-case the not-currently-
+     * authenticated path. Other errors (e.g. 500, network failures)
+     * still throw.
+     */
+    logout(): Promise<void>;
+    /**
+     * Register a one-shot bearer URL (S3 presigned, GCS signed, Azure
+     * SAS, Dropbox shared link, public HTTPS) and receive an opaque
+     * `externalSourceId` handle. Subsequent workflows reference the
+     * handle via `WorkflowSource` of `type: external_import` —
+     * compose with the [`externalImportSource()`](./types.ts) factory.
+     *
+     * Per ADR-0005 §"SSRF posture": the server validates 8 rules at
+     * registration time AND again at fetch time. HTTPS-only;
+     * private/loopback/cloud-metadata IPs are rejected (403). The
+     * original URL + password are encrypted at rest and never
+     * returned in any response.
+     *
+     * Currently `availability: planned` — the runtime endpoint returns
+     * 422 `feature_not_available` (or 404, per the cross-repo rollout)
+     * until the external-import infrastructure ships. The method
+     * exists today so consumers can write the integration ahead of
+     * time.
+     */
+    createExternalImport(payload: ExternalImportRequest): Promise<ExternalImportCreatedResponse>;
+    /**
+     * Decode a previously-embedded steganographic audio watermark
+     * (per ticket I20). Pairs with the `audio_watermark` operation —
+     * the operation embeds; this endpoint decodes.
+     *
+     * **Enterprise tier only.** Free / pro callers receive
+     * `GislFeatureTierRestrictedError` (403).
+     *
+     * **Own watermarks only.** The decoder will refuse to extract from
+     * media the caller did not mark themselves — mismatches return 404
+     * (rather than leaking that *some* watermark was detected).
+     *
+     * Currently `availability: planned` — calls return
+     * `GislFeatureNotAvailableError` (422) until the cross-repo Lambda
+     * support ships. Decode requests are rate-limited independently
+     * from workflow-create.
+     */
+    decodeAudioWatermark(payload: AudioWatermarkDecodeRequest): Promise<AudioWatermarkDecodeResponse>;
+    /**
+     * Probe an uploaded file for workflow-readiness — detects corruption,
+     * unsupported codecs, and pre-assigns the processing class the server
+     * would route the file to. Designed for the long-form merge edge case
+     * where a single bad input would fail the whole workflow.
+     *
+     * Currently `availability: planned` — calls return
+     * `GislFeatureNotAvailableError` (422) until the cross-repo Lambda
+     * support ships. Idempotent: probing the same `fileId` twice returns
+     * the cached result.
+     */
+    probeUpload(fileId: string): Promise<UploadProbeResponse>;
+    /**
+     * Probe N uploaded files in parallel and partition the results by
+     * outcome. Returns `{ ok, rejected, errors }` so the caller can
+     * cleanly drop bad clips before submitting a long-form merge
+     * workflow. Probe-call failures (including the
+     * `feature_not_available` 422 returned while the endpoint is
+     * `availability: planned`) land in `errors` rather than throwing,
+     * so a partially-successful batch still yields useful aggregation.
+     */
+    preflightClips(fileIds: string[]): Promise<PreflightClipsResult>;
+    /**
+     * Get a paginated page of credit transaction history for the caller.
+     * Server defaults: `limit=20`, `offset=0`. Most-recent-first.
+     */
+    getCreditsUsage(options?: CreditsUsageOptions): Promise<CreditsUsageResponse>;
 }