@spreadspace/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1004 @@
+import { verifyWebhook, verifyAndParseWebhook } from './webhooks.js';
+export { DocumentFailedPayload, DocumentProcessedPayload, ExtractionReadyPayload, JobCompletedPayload, LoanClassifiedPayload, VerifyAndParseResult, VerifyWebhookOptions, WebhookEvent, WebhookEventType, WebhookSignatureError } from './webhooks.js';
+import { Decimal } from 'decimal.js';
+export { Decimal } from 'decimal.js';
+
+/**
+ * Shared wire-shape and request-option types. Hand-written; the generated core
+ * (src/generated) is the source of truth for the full per-endpoint surface.
+ */
+/**
+ * Cursor-paginated envelope. One shape across every list endpoint:
+ *
+ *   { data: T[], limit: number, next_cursor: string | null }
+ *
+ * `next_cursor === null` (or absent) means end-of-stream; any non-null value is
+ * an opaque token to pass back as `?cursor=...`. There is NO `has_more` and NO
+ * `total` — stop iterating when `next_cursor` is null.
+ */
+interface CursorPaginated<T> {
+    data: T[];
+    limit: number;
+    next_cursor?: string | null;
+}
+/** Query-param value types accepted by the transport. `undefined` is skipped. */
+type QueryParams = Record<string, string | number | boolean | undefined>;
+/**
+ * Per-request overrides accepted by every resource method. Optional; the
+ * transport fills sensible defaults for everything below.
+ */
+interface RequestOptions {
+    /**
+     * Override the auto-generated idempotency key for this single non-GET
+     * request. Pass `null` to suppress automatic generation entirely. Omit to
+     * let the transport generate one (default: `crypto.randomUUID()`).
+     */
+    idempotencyKey?: string | null;
+    /** Override the `SpreadSpace-Version` header for this single request. */
+    apiVersion?: string;
+    /** `AbortSignal` for canceling the request. Composed with the per-attempt timeout. */
+    signal?: AbortSignal;
+    /** Override `maxRetries` for this single request. */
+    maxRetries?: number;
+}
+/**
+ * Internal options for the low-level `request()` method. Resource methods
+ * compose these on top of `RequestOptions`.
+ */
+interface InternalRequestOptions extends RequestOptions {
+    /** JSON-serializable request body. Encoded as `application/json`. */
+    body?: unknown;
+    /** Query parameters appended to the URL. `undefined` values are skipped. */
+    query?: QueryParams;
+}
+
+/**
+ * HTTP transport: auth, version header, idempotency, retries, error mapping.
+ *
+ * The configured client every helper sits on top of. Hand-written, not
+ * generated. Responsibilities:
+ *
+ *   - `Authorization: Bearer <key>` + `SpreadSpace-Version` on every API request.
+ *   - Auto `Idempotency-Key` (uuid) on non-GET methods, suppressible per call.
+ *   - Retry 429 + 5xx + transport errors with exponential backoff + full jitter,
+ *     honoring `Retry-After`.
+ *   - Map the canonical error envelope to typed errors carrying `requestId`,
+ *     preferring the `X-Request-ID` response header.
+ *
+ * `fetch` and `sleep` are injectable so unit tests stub the network and never
+ * actually delay. Success bodies decode via `parseBodyWithExactMoney` so money
+ * fields come back as exact `Decimal`s (lossless-json + decimal.js) — the wire
+ * is unchanged (money stays a JSON number); only the decoded JS type differs.
+ * The error envelope still uses plain `JSON.parse` (no money there).
+ */
+
+declare const DEFAULT_BASE_URL = "https://api.spreadspace.ai";
+type HttpMethod = 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
+interface TransportOptions {
+    /** API key. `ss_live_` -> live tenant, `ss_test_` -> sandbox tenant. */
+    apiKey: string;
+    /** Base URL. Defaults to `https://api.spreadspace.ai` (trailing slash trimmed). */
+    baseUrl?: string;
+    /** Override the SDK-pinned `SpreadSpace-Version` header. */
+    apiVersion?: string;
+    /** Per-attempt request timeout in ms. Default 60000. Retries get a fresh window. */
+    timeout?: number;
+    /**
+     * Max retry attempts after the initial request. Default 2. Retries on 429,
+     * 5xx, and transport failures; other 4xx never retry.
+     */
+    maxRetries?: number;
+    /** `fetch` implementation. Defaults to `globalThis.fetch`. Inject a mock in tests. */
+    fetch?: typeof fetch;
+    /** Sleep used between retries. Injectable so tests don't actually wait. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Idempotency-key generator. Defaults to `crypto.randomUUID()`. */
+    idempotencyKeyGenerator?: () => string;
+}
+/** Configured HTTP client wrapping `fetch` with SpreadSpace conventions. */
+declare class Transport {
+    /** Resolved base URL (no trailing slash). */
+    readonly baseUrl: string;
+    /** Resolved API version (the `SpreadSpace-Version` header value). */
+    readonly apiVersion: string;
+    /** Default retry ceiling. Public so helpers can construct URLs / pagers off it. */
+    readonly maxRetries: number;
+    private readonly apiKey;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    private readonly sleepImpl;
+    private readonly idempotencyKeyGenerator;
+    private readonly userAgent;
+    constructor(options: TransportOptions);
+    /**
+     * Issue an API request and return the decoded JSON body (or `undefined` for
+     * an empty / 204 response). Integrators can call this directly to hit
+     * endpoints not yet surfaced via a typed resource.
+     */
+    request<T>(method: HttpMethod, path: string, options?: InternalRequestOptions): Promise<T>;
+    /**
+     * Single retry path shared by `request()` and `putPresigned()` (mirrors the
+     * Python `_send`). Issues `fetch` with a per-attempt timeout, retrying 429 +
+     * 5xx + transport failures on the full-jitter backoff curve, honoring
+     * `Retry-After`. Returns the final `Response` (success OR a non-retryable /
+     * retries-exhausted error status — callers decide what to do with it); throws
+     * `NetworkError` only when transport failures exhaust retries.
+     */
+    private send;
+    /**
+     * PUT raw bytes straight to a presigned S3 URL (out-of-band, no auth).
+     *
+     * `contentType` MUST equal the value sent when minting the URL — it is part
+     * of the V4 signature. No SSE headers (bucket-default KMS applies). No
+     * Authorization / version headers; this does not hit a SpreadSpace endpoint.
+     * Retries on transport/5xx like `request()`; throws `SpreadSpaceError` on a
+     * non-2xx S3 status.
+     */
+    putPresigned(url: string, data: BodyInit, contentType: string, options?: {
+        maxRetries?: number;
+        signal?: AbortSignal;
+    }): Promise<Response>;
+    private buildUrl;
+    private buildHeaders;
+    /**
+     * Next retry delay. Exponential backoff with full jitter, floored by
+     * `Retry-After` when the server provided one (never retry faster than asked).
+     *
+     *   base  = min(maxDelay, baseDelay * 2^attempt)
+     *   delay = random(0, base)
+     *
+     * Full jitter (AWS-recommended) minimizes thundering-herd across clients.
+     */
+    private computeRetryDelay;
+    private parseSuccessBody;
+    private buildErrorFromResponse;
+}
+
+/**
+ * Cursor pagination over `CursorPaginated<T>` list envelopes.
+ *
+ * The API pages with `{ data: T[], limit: number, next_cursor: string | null }`;
+ * the ONLY end-of-stream signal is `next_cursor === null` (no `has_more`, no
+ * `total`). One route diverges (`GET /api/async-operations`: items under
+ * `operations`), so `itemsKey` is overridable. The returned pager is an
+ * `AsyncIterable<T>` that yields items lazily, auto-fetching pages until the
+ * cursor is exhausted, plus `.pages()` (envelope-at-a-time) and `.toArray()`.
+ */
+
+/**
+ * Lazy pager over a cursor-paginated list endpoint. Three ways to consume:
+ *
+ * 1. **`for await`** — every item across all pages (the common case).
+ * 2. **`.pages()`** — one `CursorPaginated<T>` envelope per HTTP round-trip.
+ * 3. **`.toArray()`** — eagerly drain into a single array (bounded queries only).
+ */
+interface AsyncPager<T> extends AsyncIterable<T> {
+    /** Page-by-page async iterator; each value is a full envelope. */
+    pages(): AsyncIterableIterator<CursorPaginated<T>>;
+    /** Eagerly drain every page into one array. Throws if any request fails. */
+    toArray(): Promise<T[]>;
+}
+/** Options for {@link paginate}. */
+interface PaginateOptions {
+    /** Base query params, merged into every page request. Never mutated. */
+    params?: QueryParams;
+    /** Response key holding the item array. `"data"`, or `"operations"` for async-ops. */
+    itemsKey?: string;
+    /** Query param carrying the opaque next-page token. Default `"cursor"`. */
+    cursorParam?: string;
+    /** Override the `SpreadSpace-Version` header for every page request. */
+    apiVersion?: string;
+}
+/** Build a pager that walks a cursor-paginated list endpoint. */
+declare function paginate<T>(transport: Transport, path: string, options?: PaginateOptions): AsyncPager<T>;
+
+/**
+ * Public error hierarchy for the SpreadSpace SDK.
+ *
+ * Any non-2xx API response is thrown as one of the subclasses below so
+ * integrators pattern-match on the type without parsing bodies. Shape mirrors
+ * the canonical envelope:
+ *
+ *   { error: { type, message, request_id, details? } }
+ *
+ * `requestId` is preserved on every thrown error (prefer the `X-Request-ID`
+ * response header over the body's `request_id`). Transport-level failures
+ * surface as `NetworkError`.
+ */
+interface SpreadSpaceErrorParams {
+    type: string;
+    message: string;
+    statusCode: number;
+    requestId?: string;
+    rawBody?: unknown;
+    details?: Record<string, string>;
+    /** `Retry-After` seconds echoed from a 429/503, when present. */
+    retryAfter?: number;
+}
+/** Base class for every API-shaped error. */
+declare class SpreadSpaceError extends Error {
+    /** Stable machine code from `error.type` (match on this, never `message`). */
+    readonly type: string;
+    /** HTTP status code. */
+    readonly statusCode: number;
+    /** `X-Request-ID` echoed from the server. Quote in support tickets. */
+    readonly requestId?: string;
+    /** Raw response body for debugging — parsed JSON or a string. */
+    readonly rawBody?: unknown;
+    /** Optional structured details (e.g. a field name on a validation error). */
+    readonly details?: Record<string, string>;
+    /** `Retry-After` seconds, when the server provided one. */
+    readonly retryAfter?: number;
+    constructor(params: SpreadSpaceErrorParams);
+}
+/** 400 Bad Request — typically schema validation or an invalid cursor/version. */
+declare class InvalidRequestError extends SpreadSpaceError {
+}
+/** 401 Unauthorized — missing, expired, or invalid API key. */
+declare class AuthenticationError extends SpreadSpaceError {
+}
+/** 403 Forbidden — authenticated but not allowed (scope, plan, mode, PII claim). */
+declare class PermissionError extends SpreadSpaceError {
+}
+/** 404 Not Found. */
+declare class NotFoundError extends SpreadSpaceError {
+}
+/** 409 Conflict — idempotency-key mismatch or cancel-on-terminal-operation. */
+declare class ConflictError extends SpreadSpaceError {
+}
+/**
+ * 429 Too Many Requests. The SDK retries automatically up to `maxRetries`,
+ * honoring `Retry-After`; this surfaces only when retries are exhausted.
+ */
+declare class RateLimitError extends SpreadSpaceError {
+}
+/** 5xx Server Error. Retries are exhausted by the time this surfaces. */
+declare class ServerError extends SpreadSpaceError {
+}
+/**
+ * Transport-level failure — DNS, TCP reset, fetch abort, or a JSON parse
+ * failure on a 2xx response. Distinct from API-shaped errors.
+ */
+declare class NetworkError extends Error {
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+/**
+ * Map an HTTP status + canonical `error.type` to an error class. Status is the
+ * primary signal (a bodyless 500 still becomes `ServerError`); `type` is
+ * accepted for future sharpening at the same status. Mapping:
+ *   400->InvalidRequest, 401->Authentication, 403->Permission, 404->NotFound,
+ *   409->Conflict, 429->RateLimit, >=500->Server. Unlisted 4xx (e.g. the 402
+ *   billing wall) -> the generic `SpreadSpaceError` base — NOT InvalidRequest,
+ *   which would misrepresent them as 400-style validation errors. Mirrors the
+ *   Python `classify` fallthrough (unlisted 4xx -> APIStatusError base).
+ */
+declare function classifyError(statusCode: number, _type: string | undefined): typeof SpreadSpaceError;
+
+/**
+ * Async operations: extraction-export create + poll-to-terminal.
+ *
+ * Long-running server work (e.g. extraction export) is exposed as an *async
+ * operation*: a POST enqueues it and returns an envelope you poll via
+ * `GET /api/async-operations/{id}` until terminal. Create / get / cancel all
+ * return the same `AsyncOperationResponse` envelope, modeled as `AsyncOperation`.
+ *
+ * Terminal statuses are `succeeded` / `failed` / `cancelled` (double-L); the
+ * non-terminal ones are `queued` / `running` (there is no "pending").
+ * `AsyncOperationHandle.wait` polls with light backoff until terminal, rejecting
+ * on `failed` / timeout. The clock and sleep are injectable so tests never wait.
+ *
+ * New to TS — the node-sdk has no waiter; ported from the Python reference.
+ */
+
+/** Operation statuses considered terminal — `wait()` stops on these. */
+declare const TERMINAL_STATUSES: Set<string>;
+/** Minimal transport surface this helper needs. `Transport.request` satisfies it. */
+type OperationsTransport = Pick<Transport, 'request'>;
+/** Mapped `AsyncOperationResponse` envelope. Raw body kept on `.raw` for forward-compat. */
+interface AsyncOperation {
+    operationId: string;
+    kind: string;
+    status: string;
+    progress: {
+        completed?: number;
+        total?: number;
+    };
+    result: unknown;
+    resultUrl?: string;
+    resultExpiresAt?: string;
+    errorCode?: string;
+    errorMessage?: string;
+    createdAt?: string;
+    startedAt?: string;
+    completedAt?: string;
+    expiresAt?: string;
+    links: {
+        self?: string;
+        cancel?: string;
+    };
+    /** Full decoded body, for fields not yet mapped. */
+    raw: Record<string, unknown>;
+}
+/** Body for `POST /api/async-operations/extraction_export`. All fields optional. */
+interface ExtractionExportParams {
+    borrowerId?: string;
+    loanId?: string;
+    documentIds?: string[];
+    format?: string;
+    deliveryMode?: string;
+}
+/** Tuning + injected clock for `AsyncOperationHandle.wait`. */
+interface WaitOptions$1 {
+    /** Give up after this many ms (default 300000). Rejects with `AsyncOperationTimeout`. `null` = forever (parity with Python `timeout=None`). */
+    timeoutMs?: number | null;
+    /** Initial poll interval in ms (default 2000); backs off ×2 up to a 10s cap. */
+    pollIntervalMs?: number;
+    /** Sleep impl. Injectable so tests don't actually wait. Defaults to `setTimeout`. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Monotonic clock in ms. Injectable for deterministic timeout tests. Defaults to `Date.now`. */
+    now?: () => number;
+}
+/** True when the operation reached a terminal status. */
+declare function isTerminal(operation: AsyncOperation): boolean;
+/**
+ * A waited-on operation ended in status `failed`. Carries the operation's
+ * `error_code` (as `type`) / `error_message`, plus the terminal op on `.operation`.
+ */
+declare class AsyncOperationError extends SpreadSpaceError {
+    readonly operation: AsyncOperation;
+    constructor(operation: AsyncOperation);
+}
+/** `wait()` exceeded its timeout before the operation reached a terminal state. */
+declare class AsyncOperationTimeout extends SpreadSpaceError {
+    readonly operation: AsyncOperation;
+    constructor(message: string, operation: AsyncOperation);
+}
+/** Live handle to one async operation: refresh, cancel, wait-to-terminal. */
+declare class AsyncOperationHandle {
+    private readonly transport;
+    private op;
+    constructor(transport: OperationsTransport, operation: AsyncOperation);
+    get id(): string;
+    /** Last-known state — does not hit the network. */
+    get operation(): AsyncOperation;
+    /** GET the operation once and cache the result. */
+    refresh(options?: RequestOptions): Promise<AsyncOperation>;
+    /** POST the cancel route and cache the returned state. */
+    cancel(options?: RequestOptions): Promise<AsyncOperation>;
+    /**
+     * Poll until terminal. Resolves the `AsyncOperation` on `succeeded` /
+     * `cancelled`; rejects with `AsyncOperationError` on `failed`, or
+     * `AsyncOperationTimeout` if `timeoutMs` elapses while still non-terminal.
+     * `sleep` and `now` are injectable so tests never actually wait.
+     */
+    wait(options?: WaitOptions$1): Promise<AsyncOperation>;
+}
+/**
+ * Enqueue an extraction export and return a handle to poll/cancel it. All
+ * fields are optional; `undefined` values are omitted from the body rather than
+ * sent as wire nulls.
+ *
+ *   POST /api/async-operations/extraction_export
+ */
+declare function createExtractionExport(transport: OperationsTransport, params?: ExtractionExportParams, options?: RequestOptions): Promise<AsyncOperationHandle>;
+/**
+ * Fetch one async operation by id.
+ *
+ *   GET /api/async-operations/{operationId}
+ */
+declare function getOperation(transport: OperationsTransport, operationId: string, options?: RequestOptions): Promise<AsyncOperation>;
+/**
+ * Request cancellation. Cancelling a terminal (non-cancelled) op → 409
+ * (`ConflictError`); cancelling an already-cancelled op is idempotent (200).
+ *
+ *   POST /api/async-operations/{operationId}/cancel
+ */
+declare function cancelOperation(transport: OperationsTransport, operationId: string, options?: RequestOptions): Promise<AsyncOperation>;
+
+/**
+ * Document upload: mint presigned URL -> PUT bytes to S3 -> confirm -> poll.
+ *
+ * Three-step dance so raw bytes never transit a SpreadSpace endpoint body — they
+ * go straight to S3:
+ *
+ *   1. `POST /api/documents/presigned-url` mints a short-lived V4-signed S3 URL
+ *      plus the `jobId` that tracks processing. The response is **camelCase** (the
+ *      DTO carries no `[JsonPropertyName]`); `parsePresignedUrl` reads camelCase
+ *      and falls back to snake_case defensively. This endpoint can also return
+ *      **402** (`SubscriptionRequiredResponse`, a non-canonical `{error,message}`
+ *      body) when billing is inactive — the transport raises; we let it propagate
+ *      so callers see the billing wall rather than a hang.
+ *   2. HTTP `PUT` the raw bytes to that URL. The `Content-Type` MUST equal the one
+ *      sent in step 1 — it is baked into the V4 signature, so a mismatch is a 403.
+ *   3. `POST /api/documents/{jobId}/confirm-upload` kicks off the Step Functions
+ *      pipeline; the job goes `PROCESSING`.
+ *
+ * `JobHandle.wait` then polls `GET /api/documents/{jobId}/status` to a terminal
+ * job status. Terminal job statuses are `COMPLETED` / `FAILED` (per the API's
+ * `JobsController.IsTerminalStatus`); `PENDING` / `PROCESSING` are in-flight.
+ * (`REJECTED` is a per-*document* outcome, not a job status — a FAILED job is what
+ * surfaces as "rejected" in the UI.)
+ */
+
+declare const TERMINAL_JOB_STATUSES: ReadonlySet<string>;
+/** A minted upload target (`PresignedUrlResponse`). */
+interface PresignedUrl {
+    jobId: string;
+    uploadUrl: string;
+    s3Key: string;
+    expiresInSeconds?: number;
+}
+/**
+ * Parse the presigned-url response, tolerating camelCase or snake_case keys.
+ *
+ * The live DTO is camelCase (`jobId`, `uploadUrl`, ...); we read those first and
+ * fall back to snake_case so the helper survives a future wire rename.
+ */
+declare function parsePresignedUrl(body: Record<string, unknown>): PresignedUrl;
+/**
+ * Upload failed, or the job reached a terminal failure status. Carries the
+ * last-known status body on `.statusBody` when a waited-on job ended `FAILED`.
+ */
+declare class UploadError extends SpreadSpaceError {
+    readonly statusBody?: Record<string, unknown>;
+    constructor(message: string, statusBody?: Record<string, unknown>);
+}
+/** `wait()` exceeded its timeout before the job reached a terminal status. */
+declare class UploadTimeout extends SpreadSpaceError {
+    readonly statusBody?: Record<string, unknown>;
+    constructor(message: string, statusBody?: Record<string, unknown>);
+}
+/** Options for {@link JobHandle.wait}. Clock and sleep are injectable for tests. */
+interface WaitOptions {
+    /** Overall budget in ms before raising {@link UploadTimeout}. Default 600000. `null` = forever. */
+    timeoutMs?: number | null;
+    /** Delay between status polls, in ms. Default 3000. */
+    pollIntervalMs?: number;
+    /** Terminal statuses that end the poll. Default {@link TERMINAL_JOB_STATUSES}. */
+    terminalStatuses?: ReadonlySet<string>;
+    /** Sleep used between polls. Injectable so tests don't actually wait. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Monotonic clock (ms). Injectable so tests don't actually wait. */
+    now?: () => number;
+}
+/** Live handle to one upload job: fetch status, wait-to-terminal. */
+declare class JobHandle {
+    private readonly transport;
+    readonly id: string;
+    private status_?;
+    private raw;
+    constructor(transport: Transport, id: string, status?: string, raw?: Record<string, unknown>);
+    /** GET the status route once; cache and return the decoded body. */
+    status(): Promise<Record<string, unknown>>;
+    /**
+     * Poll status until terminal; return the final status body.
+     *
+     * Raises {@link UploadError} if the job ends in a failure status (`FAILED`),
+     * {@link UploadTimeout} if `timeoutMs` elapses while the job is still
+     * non-terminal. Clock and sleep are injectable so tests never actually wait.
+     */
+    wait(options?: WaitOptions): Promise<Record<string, unknown>>;
+}
+/**
+ * Accepted upload sources. Node and web friendly:
+ *   - `string` path -> read via `node:fs`, derive name + content-type
+ *   - `Uint8Array` / `Buffer` -> `fileName` + `contentType` required
+ *   - `Blob` / `File` -> uses `.name` / `.type` when present
+ *   - `Readable` (or any async/sync iterable of chunks) -> collected to bytes;
+ *     `fileName` + `contentType` required
+ */
+type UploadSource = string | Uint8Array | Blob | NodeJS.ReadableStream | AsyncIterable<Uint8Array | string> | Iterable<Uint8Array | string>;
+/** Options for {@link uploadDocument}. */
+interface UploadOptions {
+    /** Overrides the derived file name. Required for raw bytes / streams. <=255 chars. */
+    fileName?: string;
+    /** Overrides the derived content type. Required for raw bytes / streams. */
+    contentType?: string;
+    /** Byte length sent to the server. Defaults to the resolved payload length. */
+    fileSize?: number;
+    /** Associate the upload with a borrower. */
+    borrowerId?: string;
+    /** Associate the upload with a loan. */
+    loanId?: string;
+    /** sha256 hex digest for server-side dedup. Computed from bytes when omitted. */
+    contentHash?: string;
+    /** Compute + send a sha256 digest when `contentHash` is absent. Default true. */
+    computeHash?: boolean;
+    /** Marks the upload as a sample document in confirm-upload. */
+    sampleDocument?: string;
+    /** Poll to a terminal job status before returning. Default false. */
+    wait?: boolean;
+    /** Forwarded to {@link JobHandle.wait} when `wait` is true. */
+    waitOptions?: WaitOptions;
+    /** `AbortSignal` propagated to every API + S3 request. */
+    signal?: AbortSignal;
+}
+/**
+ * Upload a document: presigned-url -> S3 PUT -> confirm-upload.
+ *
+ * `file` may be a path string, raw `Uint8Array`/`Buffer`, a `Blob`/`File`, or a
+ * `Readable`/iterable of chunks. For raw bytes and streams, `fileName` and
+ * `contentType` are required; otherwise they are derived from the path /
+ * `Blob.name` + a small extension map.
+ *
+ * When `computeHash` is true and no `contentHash` is given, a sha256 hex digest of
+ * the bytes is computed and sent (the server uses it for dedup). `fileSize`
+ * defaults to the byte length.
+ *
+ * Returns a {@link JobHandle} for the `PROCESSING` job. With `wait: true`, also
+ * polls to a terminal job status before returning.
+ *
+ * Throws: `TypeError` for an unsupported `file`; `Error` when a required
+ * `fileName`/`contentType` is missing; whatever the transport raises on a non-2xx
+ * — e.g. the **402** billing wall on `presigned-url`.
+ */
+declare function uploadDocument(transport: Transport, file: UploadSource, options?: UploadOptions): Promise<JobHandle>;
+
+/**
+ * `client.webhooks` — webhook endpoint registration management plus the
+ * signature-verification helpers surfaced as static methods for discoverability.
+ *
+ * The verification helpers are also exported as bare functions from
+ * `@spreadspace/sdk/webhooks` for tree-shakeable import in webhook-receiver
+ * Lambdas (where the full client would otherwise pull in the resource layer).
+ */
+
+/** Filters for {@link WebhooksResource.list} / {@link WebhooksResource.deliveries}. */
+interface WebhookListParams {
+    /** Page size hint forwarded to the server. */
+    limit?: number;
+    /** Override the `SpreadSpace-Version` header for these page requests. */
+    apiVersion?: string;
+}
+/** `client.webhooks` — manage webhook endpoints (`/api/admin/webhooks/*`). */
+declare class WebhooksResource {
+    private readonly transport;
+    /**
+     * Verify a `SpreadSpace-Signature` header against a body and signing secret.
+     * Throws `WebhookSignatureError` on any failure.
+     */
+    static readonly verifySignature: typeof verifyWebhook;
+    /**
+     * Verify a webhook signature and JSON-parse the body into a typed
+     * `WebhookEvent`. Throws `WebhookSignatureError` on signature failure or
+     * invalid JSON.
+     */
+    static readonly verifyAndParse: typeof verifyAndParseWebhook;
+    constructor(transport: Transport);
+    /** Low-level request shim onto the shared transport. */
+    private request;
+    /**
+     * List configured webhook endpoints for this organization.
+     *
+     *   GET /api/admin/webhooks
+     */
+    list<T = Record<string, unknown>>(params?: WebhookListParams): AsyncPager<T>;
+    /**
+     * Retrieve a single webhook endpoint.
+     *
+     *   GET /api/admin/webhooks/{id}
+     */
+    retrieve<T = unknown>(endpointId: string, options?: RequestOptions): Promise<T>;
+    /**
+     * Create a new webhook endpoint. The response carries the plaintext signing
+     * secret exactly once — store it server-side, do not log it.
+     *
+     *   POST /api/admin/webhooks
+     */
+    create<T = unknown>(params: Record<string, unknown>, options?: RequestOptions): Promise<T>;
+    /**
+     * Update endpoint metadata (URL, subscribed event types, enabled flag).
+     *
+     *   PATCH /api/admin/webhooks/{id}
+     */
+    update<T = unknown>(endpointId: string, params: Record<string, unknown>, options?: RequestOptions): Promise<T>;
+    /**
+     * Delete a webhook endpoint.
+     *
+     *   DELETE /api/admin/webhooks/{id}
+     */
+    delete<T = unknown>(endpointId: string, options?: RequestOptions): Promise<T>;
+    /**
+     * Rotate an endpoint's signing secret. The old secret stays valid for a grace
+     * window so in-flight deliveries aren't dropped. Returns the new plaintext
+     * secret exactly once.
+     *
+     *   POST /api/admin/webhooks/{id}/rotate
+     */
+    rotateSecret<T = unknown>(endpointId: string, params?: Record<string, unknown>, options?: RequestOptions): Promise<T>;
+    /**
+     * Iterate delivery attempts for an endpoint.
+     *
+     *   GET /api/admin/webhooks/{id}/deliveries
+     */
+    deliveries<T = Record<string, unknown>>(endpointId: string, params?: WebhookListParams): AsyncPager<T>;
+    /**
+     * Manually replay a delivery (e.g. after fixing a downstream outage).
+     *
+     *   POST /api/admin/webhooks/{id}/deliveries/{deliveryId}/replay
+     */
+    replayDelivery<T = unknown>(endpointId: string, deliveryId: string, params?: Record<string, unknown>, options?: RequestOptions): Promise<T>;
+}
+
+/**
+ * `client.embed` — mint short-lived embed credentials scoped to a single loan.
+ *
+ * Mint server-side with the integrator's `embed:write` API key, then hand the
+ * resulting `embed_token` (or signed iframe URL) to the browser to bootstrap the
+ * SpreadSpace review widget. The minted `ss_embed_` token is capped to a closed
+ * read-only allowlist (`documents:read`, `extractions:read`, `spreads:read`) and
+ * is locked to its `loan_id` — it cannot reach other loans or mint further tokens.
+ *
+ * Wire is snake_case throughout. Source of truth:
+ * `api/src/Controllers/EmbedSessionsController.cs`.
+ */
+
+/** Body for {@link EmbedSessionsResource.create}. */
+interface CreateEmbedSessionParams {
+    /** The loan the minted token is locked to. Required. */
+    loan_id: string;
+    /** Subset of the minting key's scopes; capped to the embed allowlist. Omit to inherit. */
+    scopes?: string[];
+    /** Token lifetime. Default 3600 (1h); must be > 0; cap 86400 (24h). */
+    expires_in_seconds?: number;
+}
+/** `POST /api/embed/sessions` response shape. */
+interface EmbedSessionResult {
+    /** The `ss_embed_*` bearer — shown ONCE, no retrieval endpoint. */
+    embed_token: string;
+    session_id: string;
+    /** RFC3339 token expiry. */
+    expires_at: string;
+    loan_id: string;
+    borrower_id: string;
+    /** The granted scope subset. */
+    scopes: string[];
+}
+/** Body for {@link EmbedIframeUrlsResource.create}. */
+interface CreateEmbedIframeUrlParams {
+    /** The loan the handle/token is locked to. Required. */
+    loan_id: string;
+    /** Embed surface key (e.g. `"spreading"`), validated against the server allowlist. Required. */
+    surface: string;
+    /** Subset of the minting key's scopes; capped to the embed allowlist. */
+    scopes?: string[];
+    /** Handle lifetime. Default 60; must be > 0; cap 300 (5 min). */
+    handle_lifetime_seconds?: number;
+    /** Minted-token lifetime after exchange. Default 3600; must be > 0; cap 86400 (24h). */
+    token_lifetime_seconds?: number;
+}
+/** `POST /api/embed/iframe-urls` response shape. */
+interface EmbedIframeUrlResult {
+    /** Drop straight into `<iframe src>`. */
+    signed_url: string;
+    /** Correlation id for the integrator's audit log. */
+    handle_id: string;
+    /** RFC3339 HANDLE expiry — not the token expiry. */
+    expires_at: string;
+    surface: string;
+    loan_id: string;
+    borrower_id: string;
+    scopes: string[];
+}
+/** `client.embed.sessions` — mint and revoke embed-session tokens. */
+declare class EmbedSessionsResource {
+    private readonly transport;
+    constructor(transport: Transport);
+    private request;
+    /**
+     * Mint an embed-session token for a loan.
+     *
+     *   POST /api/embed/sessions
+     *
+     * Server skips idempotency (`[SkipIdempotency]`); the SDK still sends the
+     * auto-generated `Idempotency-Key` header (harmless — the server ignores it).
+     * Returns the `ss_embed_*` token plus session metadata (shown once).
+     */
+    create<T = EmbedSessionResult>(params: CreateEmbedSessionParams, options?: RequestOptions): Promise<T>;
+    /**
+     * Revoke an embed session early — useful when the integrator's UI flow ends
+     * before the natural expiry, or when reissuing after a logout. Honors
+     * `Idempotency-Key`. Resolves to `void` on the `204 No Content`.
+     *
+     *   DELETE /api/embed/sessions/{sessionId}
+     */
+    revoke<T = void>(sessionId: string, options?: RequestOptions): Promise<T>;
+}
+/** `client.embed.iframeUrls` — mint signed iframe-URL handles. */
+declare class EmbedIframeUrlsResource {
+    private readonly transport;
+    constructor(transport: Transport);
+    private request;
+    /**
+     * Mint a signed-URL handle to drop into an `<iframe src>`. The browser then
+     * exchanges the handle (single-use) for an embed token at the iframe origin.
+     *
+     *   POST /api/embed/iframe-urls
+     */
+    create<T = EmbedIframeUrlResult>(params: CreateEmbedIframeUrlParams, options?: RequestOptions): Promise<T>;
+}
+/**
+ * Top-level `client.embed` namespace. Surfaces the `sessions` and `iframeUrls`
+ * sub-resources.
+ */
+declare class EmbedResource {
+    /** `embed.sessions` — mint/revoke embed-session tokens. */
+    readonly sessions: EmbedSessionsResource;
+    /** `embed.iframeUrls` — mint signed iframe-URL handles. */
+    readonly iframeUrls: EmbedIframeUrlsResource;
+    constructor(transport: Transport);
+}
+
+/**
+ * The `SpreadSpace` client facade.
+ *
+ * Thin ergonomic namespaces over the transport + helpers. These wrap the
+ * cross-cutting flows a generator can't produce (cursor pagination, the async
+ * operation waiter, the three-step upload sequence). A fully typed
+ * method-per-endpoint surface is expected to come from a generated core in CI;
+ * until then `request()` is the escape hatch to any endpoint not yet wrapped.
+ *
+ * Constructed from `{ apiKey?, baseUrl?, apiVersion?, timeoutMs?, maxRetries?,
+ * fetch? }`. An `ss_test_` key routes to the isolated sandbox tenant; `ss_live_`
+ * operates on real workspace data. Both hit the same base URL.
+ *
+ * Money note: amounts decode to a JS `number` (TS has no decimal type). See the
+ * README precision caveat — do not treat them as exact decimals.
+ */
+
+/** Constructor options for {@link SpreadSpace}. All optional; sensible defaults. */
+interface SpreadSpaceOptions {
+    /**
+     * API key. `ss_live_` -> live tenant, `ss_test_` -> sandbox tenant. Falls back
+     * to `SPREADSPACE_API_KEY` when omitted.
+     */
+    apiKey?: string;
+    /** Base URL. Defaults to `https://api.spreadspace.ai` (trailing slash trimmed). */
+    baseUrl?: string;
+    /** Override the SDK-pinned `SpreadSpace-Version` header (per-call overridable too). */
+    apiVersion?: string;
+    /** Per-attempt request timeout in ms. Default 60000. Retries get a fresh window. */
+    timeoutMs?: number;
+    /** Max retry attempts after the initial request. Default 2. */
+    maxRetries?: number;
+    /** `fetch` implementation. Defaults to `globalThis.fetch`. Inject a mock in tests. */
+    fetch?: typeof fetch;
+    /**
+     * Pre-built transport. When supplied, the connection options above are
+     * ignored — used by tests to share a stubbed transport with the helpers.
+     */
+    transport?: Transport;
+}
+/** Filters for {@link SpreadSpace.borrowers}.list. */
+interface ListBorrowersParams {
+    /** Restrict to borrowers in the intake/triage queue when set. */
+    intake?: boolean;
+    /** Page size hint forwarded to the server. */
+    limit?: number;
+    /** Override the `SpreadSpace-Version` header for these page requests. */
+    apiVersion?: string;
+}
+/** Filters for {@link SpreadSpace.loans}.list. */
+interface ListLoansParams {
+    /** Scope to one borrower (`GET /api/borrowers/{id}/loans`); omit for all loans. */
+    borrowerId?: string;
+    /** Page size hint forwarded to the server. */
+    limit?: number;
+    /** Override the `SpreadSpace-Version` header for these page requests. */
+    apiVersion?: string;
+}
+/** Filters for {@link SpreadSpace.jobs}.list. */
+interface ListJobsParams {
+    /** Page size hint forwarded to the server. */
+    limit?: number;
+    /** Override the `SpreadSpace-Version` header for these page requests. */
+    apiVersion?: string;
+}
+/** Filters for {@link SpreadSpace.asyncOperations}.list. */
+interface ListAsyncOperationsParams {
+    /** Filter by operation kind (e.g. `extraction_export`). */
+    kind?: string;
+    /** Filter by status (`queued` / `running` / `succeeded` / `failed` / `cancelled`). */
+    status?: string;
+    /** Page size hint forwarded to the server. */
+    limit?: number;
+    /** Override the `SpreadSpace-Version` header for these page requests. */
+    apiVersion?: string;
+}
+/** `client.borrowers` — list borrowers. */
+declare class BorrowersResource {
+    private readonly transport;
+    constructor(transport: Transport);
+    /** Paginate `GET /api/borrowers`. Lazy async-iterable of borrower records. */
+    list<T = Record<string, unknown>>(params?: ListBorrowersParams): AsyncPager<T>;
+}
+/** `client.loans` — list loans, optionally scoped to a borrower. */
+declare class LoansResource {
+    private readonly transport;
+    constructor(transport: Transport);
+    /**
+     * Paginate loans. With `borrowerId`, hits `GET /api/borrowers/{id}/loans`;
+     * otherwise the org-wide `GET /api/loans`.
+     */
+    list<T = Record<string, unknown>>(params?: ListLoansParams): AsyncPager<T>;
+}
+/** `client.jobs` — list document-package jobs. */
+declare class JobsResource {
+    private readonly transport;
+    constructor(transport: Transport);
+    /** Paginate `GET /api/jobs`. */
+    list<T = Record<string, unknown>>(params?: ListJobsParams): AsyncPager<T>;
+}
+/** `client.asyncOperations` — list / get / cancel long-running operations. */
+declare class AsyncOperationsResource {
+    private readonly transport;
+    constructor(transport: Transport);
+    /**
+     * Paginate `GET /api/async-operations`. Divergent envelope: items live under
+     * `operations` (no `data`/`limit`), so the items key is overridden here.
+     */
+    list<T = Record<string, unknown>>(params?: ListAsyncOperationsParams): AsyncPager<T>;
+    /** `GET /api/async-operations/{id}` — fetch one operation's current state. */
+    get(operationId: string, options?: RequestOptions): Promise<AsyncOperation>;
+    /**
+     * `POST /api/async-operations/{id}/cancel`. Cancelling a terminal
+     * (non-cancelled) op -> 409 (`ConflictError`); cancelling an already-cancelled
+     * op is idempotent (200).
+     */
+    cancel(operationId: string, options?: RequestOptions): Promise<AsyncOperation>;
+}
+/** `client.exports` — create extraction exports and poll their operations. */
+declare class ExportsResource {
+    private readonly transport;
+    constructor(transport: Transport);
+    /**
+     * `POST /api/async-operations/extraction_export`. All fields optional; `null`/
+     * `undefined` are omitted from the body. Returns a handle whose `.wait()` polls
+     * the operation to a terminal state.
+     */
+    create(params?: ExtractionExportParams, options?: RequestOptions): Promise<AsyncOperationHandle>;
+    /** `GET /api/async-operations/{id}` — fetch the export operation's state. */
+    get(operationId: string, options?: RequestOptions): Promise<AsyncOperation>;
+}
+/** `client.documents` — upload a file and poll its job. */
+declare class DocumentsResource {
+    private readonly transport;
+    constructor(transport: Transport);
+    /**
+     * Upload a document: presigned-url -> S3 PUT -> confirm-upload. `file` may be a
+     * path string, raw bytes, a `Blob`/`File`, or a `Readable`/iterable of chunks.
+     * With `wait: true`, polls to a terminal job status before resolving.
+     */
+    upload(file: UploadSource, options?: UploadOptions): Promise<JobHandle>;
+    /** `GET /api/documents/{jobId}/status` — fetch one job's current status body. */
+    status(jobId: string): Promise<Record<string, unknown>>;
+}
+/**
+ * Entry point. `new SpreadSpace({ apiKey: 'ss_test_...' })` or set
+ * `SPREADSPACE_API_KEY`.
+ *
+ *   const client = new SpreadSpace({ apiKey: 'ss_test_...' });
+ *   for await (const borrower of client.borrowers.list()) {
+ *     // ...
+ *   }
+ */
+declare class SpreadSpace {
+    /** Borrowers: `list()`. */
+    readonly borrowers: BorrowersResource;
+    /** Loans: `list({ borrowerId?, limit? })`. */
+    readonly loans: LoansResource;
+    /** Jobs: `list()`. */
+    readonly jobs: JobsResource;
+    /** Async operations: `list({ kind?, status? })` / `get(id)` / `cancel(id)`. */
+    readonly asyncOperations: AsyncOperationsResource;
+    /** Extraction exports: `create(...)` / `get(id)`. */
+    readonly exports: ExportsResource;
+    /** Documents: `upload(file, opts)` / `status(jobId)`. */
+    readonly documents: DocumentsResource;
+    /** Webhooks: `create/list/retrieve/update/delete` endpoints + static `verifySignature`/`verifyAndParse`. */
+    readonly webhooks: WebhooksResource;
+    /** Embed: `sessions.create(...)` mints a loan-scoped `ss_embed_` token. */
+    readonly embed: EmbedResource;
+    private readonly _transport;
+    constructor(options?: SpreadSpaceOptions);
+    /** The underlying configured transport. */
+    get transport(): Transport;
+    /**
+     * Low-level escape hatch to any endpoint the resource helpers don't wrap.
+     * Returns the decoded JSON body (or `undefined` for an empty / 204 response).
+     */
+    request<T = unknown>(method: HttpMethod, path: string, options?: InternalRequestOptions): Promise<T>;
+}
+
+/**
+ * Exact-decimal money decoding.
+ *
+ * The SpreadSpace wire encodes money as a JSON `number`. Routed through the
+ * stock `JSON.parse`, every amount is forced through IEEE-754 float64 the
+ * instant it is read — so `0.1 + 0.2`-class drift and >2^53 truncation are
+ * baked in before any caller touches the value. Python (`parse_float=Decimal`)
+ * and C# (`System.Decimal`) already read money exactly; only TS was lossy.
+ *
+ * This module closes that gap WITHOUT touching the wire (money stays a JSON
+ * number outbound and inbound — non-breaking). It parses the body with
+ * `lossless-json`, which keeps every numeric literal as a string-backed
+ * {@link LosslessNumber} (no float64 round-trip), then deep-walks the decoded
+ * tree converting money fields to a `decimal.js` {@link Decimal} and every other
+ * numeric back to a plain `number`. The net effect: money is exact, everything
+ * else keeps its ordinary `number` type.
+ *
+ * ## Matching strategy (two tiers, one walk)
+ *
+ *   - **Tier 1 — {@link SCALAR_MONEY_KEYS} (global).** The named scalar money
+ *     fields on the typed public surface (`net_amount`, `requested_amount`, …).
+ *     All are `decimal`/`decimal?` server-side and none collide with a non-money
+ *     typed field, so they are converted wherever they appear. Complete + exact.
+ *
+ *   - **Tier 2 — {@link PAYLOAD_MONEY_KEYS} (scoped).** The money key names that
+ *     live ONLY inside the opaque `payload` blob (the spread / P&L / cash-flow /
+ *     aging / bank-analysis report tree — `values`, `vals`, `total`, `net`, …).
+ *     Several are generic words (`total`, `net`, `value`) that DO collide with
+ *     non-money numbers elsewhere — e.g. `progress.total` is an int counter — so
+ *     they are converted ONLY once the walk has descended through a `payload`
+ *     key. Scoping is what makes including those generic names safe.
+ *
+ * `span` (the `BankCounterpartyTransactionDto.span` bounding box) is deliberately
+ * NOT a money scope: its numeric keys (`x0`, `top`, `x1`, `bottom`,
+ * `page_width`, `page_height`) are PDF geometry, never dollars. It carries no
+ * Tier-2 key names, so the default (non-payload) handling leaves it as plain
+ * numbers — exactly right.
+ *
+ * ## Honest coverage
+ *
+ * Tier 1 is complete and exact. Tier 2 is a heuristic keyed on field names
+ * inside a fully-opaque `JsonElement`: it covers the entire *current* payload
+ * money vocabulary, but if the server later emits a NEW money key inside the
+ * payload under a name not in {@link PAYLOAD_MONEY_KEYS}, that one field is
+ * handed back as a plain `number` (lossy) until the set is extended. The failure
+ * mode is "a future field stays float64", never "a non-money field becomes a
+ * Decimal" — non-payload numbers outside Tier 1 are never touched.
+ */
+
+/**
+ * The decoded runtime type of a money field: an arbitrary-precision decimal.
+ * Matches the Python / C# semantics (`Decimal` / `System.Decimal`). Callers do
+ * `amount.toFixed(2)`, `amount.plus(other)`, `amount.toString()`; to send a
+ * value back to the API (wire stays a JSON number) use `amount.toNumber()`.
+ */
+type Money = Decimal;
+/**
+ * Tier 1 — scalar money field names, converted wherever they appear in a
+ * response. Every one is `decimal`/`decimal?` server-side and unambiguous
+ * across the public surface (none names a non-money typed field). Sourced from
+ * `api/src/Models/*.cs` (the C# declared type is ground truth — `System.Decimal`
+ * serializes as a JSON number, so `format: double` in OpenAPI cannot tell money
+ * from rate on its own).
+ */
+declare const SCALAR_MONEY_KEYS: ReadonlySet<string>;
+/**
+ * Tier 2 — money key names that exist ONLY inside the opaque `payload` blob
+ * (`LoanSpreadEnvelope.payload` — the spread / tax / P&L / cash-flow / aging /
+ * bank-analysis report tree). Each is `decimal` or `List<decimal>` server-side
+ * (`ExtractionDtos.cs`, `Spreading/PayloadBank.cs`). Converted ONLY within a
+ * `payload` subtree — several names (`total`, `net`, `value`) collide with
+ * non-money numbers at the top level, so the scope guard is load-bearing.
+ *
+ * Array elements count: a `List<decimal>` (e.g. `values`, `vals`, `total_vals`,
+ * a `total` row) decodes to an array whose every numeric element is money.
+ */
+declare const PAYLOAD_MONEY_KEYS: ReadonlySet<string>;
+/**
+ * Parse a SpreadSpace JSON response body with exact-decimal money.
+ *
+ * Drop-in for `JSON.parse(text)` on the success path: same return shape, except
+ * money fields are {@link Decimal} instead of `number`. Throws the same
+ * `SyntaxError`-family error as `JSON.parse` on malformed JSON (callers map it
+ * to a `NetworkError`), so error handling upstream is unchanged.
+ */
+declare function parseBodyWithExactMoney(text: string): unknown;
+
+declare const SDK_VERSION = "0.1.0";
+declare const DEFAULT_API_VERSION = "2026-05-03";
+
+export { type AsyncOperation, AsyncOperationError, AsyncOperationHandle, AsyncOperationTimeout, type AsyncPager, AuthenticationError, ConflictError, type CreateEmbedIframeUrlParams, type CreateEmbedSessionParams, type CursorPaginated, DEFAULT_API_VERSION, DEFAULT_BASE_URL, type EmbedIframeUrlResult, EmbedIframeUrlsResource, EmbedResource, type EmbedSessionResult, EmbedSessionsResource, type ExtractionExportParams, type HttpMethod, type InternalRequestOptions, InvalidRequestError, JobHandle, type ListAsyncOperationsParams, type ListBorrowersParams, type ListJobsParams, type ListLoansParams, type Money, NetworkError, NotFoundError, type WaitOptions$1 as OperationWaitOptions, type OperationsTransport, PAYLOAD_MONEY_KEYS, type PaginateOptions, PermissionError, type PresignedUrl, type QueryParams, RateLimitError, type RequestOptions, SCALAR_MONEY_KEYS, SDK_VERSION, ServerError, SpreadSpace, SpreadSpaceError, type SpreadSpaceErrorParams, type SpreadSpaceOptions, TERMINAL_JOB_STATUSES, TERMINAL_STATUSES, Transport, type TransportOptions, UploadError, type UploadOptions, type UploadSource, UploadTimeout, type WaitOptions as UploadWaitOptions, type WebhookListParams, WebhooksResource, cancelOperation, classifyError, createExtractionExport, getOperation, isTerminal, paginate, parseBodyWithExactMoney, parsePresignedUrl, uploadDocument, verifyAndParseWebhook, verifyWebhook };