@spreadspace/sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,1284 @@
+import {
+  WebhookSignatureError,
+  verifyAndParseWebhook,
+  verifyWebhook
+} from "./chunk-2JW6MGIK.js";
+
+// src/transport.ts
+import { randomUUID } from "crypto";
+
+// src/errors.ts
+var SpreadSpaceError = class extends Error {
+  /** Stable machine code from `error.type` (match on this, never `message`). */
+  type;
+  /** HTTP status code. */
+  statusCode;
+  /** `X-Request-ID` echoed from the server. Quote in support tickets. */
+  requestId;
+  /** Raw response body for debugging — parsed JSON or a string. */
+  rawBody;
+  /** Optional structured details (e.g. a field name on a validation error). */
+  details;
+  /** `Retry-After` seconds, when the server provided one. */
+  retryAfter;
+  constructor(params) {
+    super(params.message);
+    this.name = new.target.name;
+    this.type = params.type;
+    this.statusCode = params.statusCode;
+    this.requestId = params.requestId;
+    this.rawBody = params.rawBody;
+    this.details = params.details;
+    this.retryAfter = params.retryAfter;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var InvalidRequestError = class extends SpreadSpaceError {
+};
+var AuthenticationError = class extends SpreadSpaceError {
+};
+var PermissionError = class extends SpreadSpaceError {
+};
+var NotFoundError = class extends SpreadSpaceError {
+};
+var ConflictError = class extends SpreadSpaceError {
+};
+var RateLimitError = class extends SpreadSpaceError {
+};
+var ServerError = class extends SpreadSpaceError {
+};
+var NetworkError = class _NetworkError extends Error {
+  cause;
+  constructor(message, cause) {
+    super(message);
+    this.name = "NetworkError";
+    this.cause = cause;
+    Object.setPrototypeOf(this, _NetworkError.prototype);
+  }
+};
+function classifyError(statusCode, _type) {
+  if (statusCode === 400) return InvalidRequestError;
+  if (statusCode === 401) return AuthenticationError;
+  if (statusCode === 403) return PermissionError;
+  if (statusCode === 404) return NotFoundError;
+  if (statusCode === 409) return ConflictError;
+  if (statusCode === 429) return RateLimitError;
+  if (statusCode >= 500) return ServerError;
+  return SpreadSpaceError;
+}
+
+// src/money.ts
+import { Decimal } from "decimal.js";
+import { isLosslessNumber, parse } from "lossless-json";
+var SCALAR_MONEY_KEYS = /* @__PURE__ */ new Set([
+  // BankCounterparty* (direction splits, rollups, relationship groups, review
+  // items, merge/split responses).
+  "net_amount",
+  "inflow_amount",
+  "outflow_amount",
+  "amount",
+  "advance_amount",
+  "remittance_amount",
+  // BankCounterpartyRelationshipGroup.cost_of_capital — a dollar figure
+  // (`net < 0 ? -net : 0`), NOT a percentage. Money.
+  "cost_of_capital",
+  // Loan create/update/response.
+  "requested_amount",
+  // BorrowerResponse facility-size aggregates.
+  "mean_facility_size",
+  "median_facility_size",
+  // DocumentLogEntry / usage / job-status billing figures (USD).
+  "billed_amount_usd",
+  "estimated_cost_usd"
+]);
+var PAYLOAD_MONEY_KEYS = /* @__PURE__ */ new Set([
+  // P&L / cash-flow / balance-sheet rows (List<decimal>).
+  "values",
+  "total",
+  // AR/AP aging rows (List<decimal>).
+  "vals",
+  "total_vals",
+  // Bank-statement period summary (scalar decimal each).
+  "deposits",
+  "withdrawals",
+  "fees",
+  "interest",
+  "net",
+  // Generic leaf amount inside the payload tree.
+  "amount",
+  // Bank TTM combined month / summary tiles (Spreading/PayloadBank.cs).
+  "total_deposits",
+  "total_withdrawals",
+  "net_change",
+  "total_deposits_ex_internal_transfers",
+  "total_withdrawals_ex_internal_transfers",
+  "net_change_ex_internal_transfers",
+  "ending_balance",
+  "value"
+]);
+var PAYLOAD_SCOPE_KEYS = /* @__PURE__ */ new Set(["payload"]);
+function parseBodyWithExactMoney(text) {
+  const tree = parse(text);
+  return convertDeep(tree, false);
+}
+function convertDeep(value, inPayload, key, inMoneyArray = false) {
+  if (isLosslessNumber(value)) {
+    if (inMoneyArray || isMoneyKey(key, inPayload)) {
+      return losslessToDecimal(value);
+    }
+    return losslessToNumber(value);
+  }
+  if (Array.isArray(value)) {
+    const elementIsMoney = isMoneyKey(key, inPayload);
+    return value.map((item) => convertDeep(item, inPayload, void 0, elementIsMoney));
+  }
+  if (isPlainObject(value)) {
+    const out = {};
+    for (const [childKey, childValue] of Object.entries(value)) {
+      const childInPayload = inPayload || PAYLOAD_SCOPE_KEYS.has(childKey);
+      out[childKey] = convertDeep(childValue, childInPayload, childKey, false);
+    }
+    return out;
+  }
+  return value;
+}
+function isMoneyKey(key, inPayload) {
+  if (key === void 0) return false;
+  if (SCALAR_MONEY_KEYS.has(key)) return true;
+  return inPayload && PAYLOAD_MONEY_KEYS.has(key);
+}
+function losslessToDecimal(value) {
+  return new Decimal(value.toString());
+}
+function losslessToNumber(value) {
+  const v = value.valueOf();
+  return typeof v === "bigint" ? Number(v) : v;
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// src/version.ts
+var SDK_VERSION = "0.1.0";
+var DEFAULT_API_VERSION = "2026-05-03";
+
+// src/transport.ts
+var DEFAULT_BASE_URL = "https://api.spreadspace.ai";
+var DEFAULT_TIMEOUT_MS = 6e4;
+var DEFAULT_MAX_RETRIES = 2;
+var RETRY_BASE_DELAY_MS = 500;
+var RETRY_MAX_DELAY_MS = 3e4;
+var SAFE_METHODS = /* @__PURE__ */ new Set(["GET", "HEAD", "OPTIONS"]);
+var Transport = class {
+  /** Resolved base URL (no trailing slash). */
+  baseUrl;
+  /** Resolved API version (the `SpreadSpace-Version` header value). */
+  apiVersion;
+  /** Default retry ceiling. Public so helpers can construct URLs / pagers off it. */
+  maxRetries;
+  apiKey;
+  timeoutMs;
+  fetchImpl;
+  sleepImpl;
+  idempotencyKeyGenerator;
+  userAgent;
+  constructor(options) {
+    if (!options || typeof options.apiKey !== "string" || options.apiKey.length === 0) {
+      throw new TypeError(
+        "Transport requires an apiKey. Issue one from the dashboard at /settings/api-keys."
+      );
+    }
+    this.apiKey = options.apiKey;
+    let baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;
+    while (baseUrl.endsWith("/")) baseUrl = baseUrl.slice(0, -1);
+    this.baseUrl = baseUrl;
+    this.apiVersion = options.apiVersion ?? DEFAULT_API_VERSION;
+    this.timeoutMs = options.timeout ?? DEFAULT_TIMEOUT_MS;
+    this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+    this.fetchImpl = options.fetch ?? globalThis.fetch;
+    this.sleepImpl = options.sleep ?? defaultSleep;
+    this.idempotencyKeyGenerator = options.idempotencyKeyGenerator ?? randomUUID;
+    this.userAgent = `spreadspace-sdk/${SDK_VERSION} node/${nodeVersion()}`;
+    if (typeof this.fetchImpl !== "function") {
+      throw new TypeError(
+        "Transport requires a fetch implementation. Node 18+ provides one globally; pass a polyfill via options.fetch otherwise."
+      );
+    }
+  }
+  /**
+   * 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.
+   */
+  async request(method, path, options = {}) {
+    const url = this.buildUrl(path, options.query);
+    const headers = this.buildHeaders(method, options);
+    const body = options.body !== void 0 ? JSON.stringify(options.body) : void 0;
+    const response = await this.send(url, { method, headers, body }, {
+      maxRetries: options.maxRetries ?? this.maxRetries,
+      signal: options.signal,
+      describe: `${method} ${url}`
+    });
+    if (response.ok) {
+      return await this.parseSuccessBody(response);
+    }
+    const requestId = response.headers.get("X-Request-ID") ?? void 0;
+    throw await this.buildErrorFromResponse(response, requestId);
+  }
+  /**
+   * 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.
+   */
+  async send(url, init, opts) {
+    const { maxRetries, signal: callerSignal, describe } = opts;
+    let attempt = 0;
+    let lastError;
+    while (attempt <= maxRetries) {
+      const controller = new AbortController();
+      const timeoutHandle = setTimeout(() => controller.abort(), this.timeoutMs);
+      const signal = callerSignal ? composeAbortSignals(controller.signal, callerSignal) : controller.signal;
+      let response;
+      try {
+        response = await this.fetchImpl(url, { ...init, signal });
+      } catch (err) {
+        clearTimeout(timeoutHandle);
+        lastError = err;
+        if (attempt < maxRetries) {
+          await this.sleepImpl(this.computeRetryDelay(attempt, void 0));
+          attempt += 1;
+          continue;
+        }
+        throw new NetworkError(`SpreadSpace request to ${describe} failed: ${describeError(err)}`, err);
+      }
+      clearTimeout(timeoutHandle);
+      const status = response.status;
+      const retryable = status === 429 || status >= 500 && status <= 599;
+      if (retryable && attempt < maxRetries) {
+        const retryAfterSec = parseRetryAfter(response.headers.get("Retry-After"));
+        await this.sleepImpl(this.computeRetryDelay(attempt, retryAfterSec));
+        attempt += 1;
+        try {
+          await response.body?.cancel();
+        } catch {
+        }
+        continue;
+      }
+      return response;
+    }
+    throw new NetworkError(
+      `SpreadSpace request to ${describe} exhausted retries (last error: ${describeError(lastError)}).`,
+      lastError
+    );
+  }
+  /**
+   * 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.
+   */
+  async putPresigned(url, data, contentType, options = {}) {
+    const response = await this.send(
+      url,
+      { method: "PUT", headers: { "Content-Type": contentType }, body: data },
+      {
+        maxRetries: options.maxRetries ?? this.maxRetries,
+        signal: options.signal,
+        describe: `PUT ${url}`
+      }
+    );
+    if (response.ok) {
+      return response;
+    }
+    const text = await safeReadText(response);
+    throw new SpreadSpaceError({
+      type: "presigned_upload_failed",
+      message: `Presigned upload failed: HTTP ${response.status}`,
+      statusCode: response.status,
+      rawBody: text
+    });
+  }
+  // -- internals ----------------------------------------------------------
+  buildUrl(path, query) {
+    const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+    const url = new URL(this.baseUrl + normalizedPath);
+    if (query) {
+      for (const [k, v] of Object.entries(query)) {
+        if (v === void 0) continue;
+        url.searchParams.set(k, String(v));
+      }
+    }
+    return url.toString();
+  }
+  buildHeaders(method, options) {
+    const headers = new Headers();
+    headers.set("Authorization", `Bearer ${this.apiKey}`);
+    headers.set("SpreadSpace-Version", options.apiVersion ?? this.apiVersion);
+    headers.set("Accept", "application/json");
+    headers.set("User-Agent", this.userAgent);
+    if (options.body !== void 0) {
+      headers.set("Content-Type", "application/json; charset=utf-8");
+    }
+    if (!SAFE_METHODS.has(method)) {
+      const explicit = options.idempotencyKey;
+      if (explicit === null) {
+      } else if (typeof explicit === "string" && explicit.length > 0) {
+        headers.set("Idempotency-Key", explicit);
+      } else {
+        headers.set("Idempotency-Key", this.idempotencyKeyGenerator());
+      }
+    }
+    return headers;
+  }
+  /**
+   * 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.
+   */
+  computeRetryDelay(attempt, retryAfterSec) {
+    const expBackoff = Math.min(RETRY_MAX_DELAY_MS, RETRY_BASE_DELAY_MS * 2 ** attempt);
+    const jittered = Math.floor(Math.random() * expBackoff);
+    if (retryAfterSec !== void 0 && retryAfterSec > 0) {
+      return Math.max(jittered, retryAfterSec * 1e3);
+    }
+    return jittered;
+  }
+  async parseSuccessBody(response) {
+    if (response.status === 204) {
+      return void 0;
+    }
+    const text = await response.text();
+    if (text.length === 0) {
+      return void 0;
+    }
+    try {
+      return parseBodyWithExactMoney(text);
+    } catch (err) {
+      throw new NetworkError(
+        `Failed to parse SpreadSpace response as JSON (status=${response.status}): ${describeError(err)}`,
+        err
+      );
+    }
+  }
+  async buildErrorFromResponse(response, requestId) {
+    const status = response.status;
+    let rawBody;
+    let type = "unknown";
+    let message = `SpreadSpace API request failed with status ${status}.`;
+    let details;
+    let resolvedRequestId = requestId;
+    try {
+      const text = await response.text();
+      if (text.length > 0) {
+        try {
+          const parsed = JSON.parse(text);
+          rawBody = parsed;
+          if (typeof parsed === "object" && parsed !== null && "error" in parsed && typeof parsed.error === "object" && parsed.error !== null) {
+            const errBody = parsed.error;
+            if (typeof errBody.type === "string") type = errBody.type;
+            if (typeof errBody.message === "string") message = errBody.message;
+            if (errBody.details && typeof errBody.details === "object" && !Array.isArray(errBody.details)) {
+              details = errBody.details;
+            }
+            if (resolvedRequestId === void 0 && typeof errBody.request_id === "string") {
+              resolvedRequestId = errBody.request_id;
+            }
+          }
+        } catch {
+          rawBody = text;
+        }
+      }
+    } catch {
+    }
+    const retryAfter = parseRetryAfter(response.headers.get("Retry-After"));
+    const ErrorClass = classifyError(status, type);
+    return new ErrorClass({
+      type,
+      message,
+      statusCode: status,
+      requestId: resolvedRequestId,
+      rawBody,
+      details,
+      retryAfter
+    });
+  }
+};
+function defaultSleep(ms) {
+  if (ms <= 0) return Promise.resolve();
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function nodeVersion() {
+  return typeof process !== "undefined" && process.version ? process.version : "unknown";
+}
+function parseRetryAfter(value) {
+  if (value === null || value.length === 0) return void 0;
+  const asInt = Number(value);
+  if (Number.isFinite(asInt) && Number.isInteger(asInt) && asInt >= 0) {
+    return asInt;
+  }
+  const asDate = Date.parse(value);
+  if (!Number.isNaN(asDate)) {
+    const deltaMs = asDate - Date.now();
+    if (deltaMs > 0) return Math.ceil(deltaMs / 1e3);
+  }
+  return void 0;
+}
+function describeError(err) {
+  if (err instanceof Error) return err.message;
+  if (typeof err === "string") return err;
+  return String(err);
+}
+async function safeReadText(response) {
+  try {
+    return await response.text();
+  } catch {
+    return void 0;
+  }
+}
+function composeAbortSignals(a, b) {
+  const maybeAny = AbortSignal.any;
+  if (typeof maybeAny === "function") {
+    return maybeAny([a, b]);
+  }
+  const controller = new AbortController();
+  const onAbort = (source) => {
+    if (controller.signal.aborted) return;
+    const reason = source.reason;
+    controller.abort(reason);
+  };
+  if (a.aborted) onAbort(a);
+  else a.addEventListener("abort", () => onAbort(a), { once: true });
+  if (b.aborted) onAbort(b);
+  else b.addEventListener("abort", () => onAbort(b), { once: true });
+  return controller.signal;
+}
+
+// src/helpers/pagination.ts
+function paginate(transport, path, options = {}) {
+  const itemsKey = options.itemsKey ?? "data";
+  const cursorParam = options.cursorParam ?? "cursor";
+  const apiVersion = options.apiVersion;
+  const baseParams = { ...options.params ?? {} };
+  async function* pageIterator() {
+    let cursor;
+    while (true) {
+      const query = { ...baseParams };
+      if (cursor !== void 0) query[cursorParam] = cursor;
+      const page = await transport.request("GET", path, {
+        query,
+        apiVersion
+      });
+      if (page === null || typeof page !== "object") return;
+      yield page;
+      const next = page.next_cursor ?? null;
+      if (!next) return;
+      if (next === cursor) return;
+      cursor = next;
+    }
+  }
+  async function* itemIterator() {
+    for await (const page of pageIterator()) {
+      const items = page[itemsKey];
+      if (!items) continue;
+      yield* items;
+    }
+  }
+  return {
+    [Symbol.asyncIterator]() {
+      return itemIterator();
+    },
+    pages() {
+      return pageIterator();
+    },
+    async toArray() {
+      const out = [];
+      for await (const item of itemIterator()) out.push(item);
+      return out;
+    }
+  };
+}
+
+// src/helpers/operations.ts
+var OPERATIONS_PATH = "/api/async-operations";
+var BACKOFF_CAP_MS = 1e4;
+var TERMINAL_STATUSES = /* @__PURE__ */ new Set(["succeeded", "failed", "cancelled"]);
+function toAsyncOperation(body) {
+  const b = body ?? {};
+  return {
+    operationId: b["operation_id"],
+    kind: b["kind"],
+    status: b["status"],
+    progress: b["progress"] ?? {},
+    result: b["result"],
+    resultUrl: b["result_url"],
+    resultExpiresAt: b["result_expires_at"],
+    errorCode: b["error_code"],
+    errorMessage: b["error_message"],
+    createdAt: b["created_at"],
+    startedAt: b["started_at"],
+    completedAt: b["completed_at"],
+    expiresAt: b["expires_at"],
+    links: b["links"] ?? {},
+    raw: b
+  };
+}
+function isTerminal(operation) {
+  return TERMINAL_STATUSES.has(operation.status);
+}
+var AsyncOperationError = class _AsyncOperationError extends SpreadSpaceError {
+  operation;
+  constructor(operation) {
+    super({
+      type: operation.errorCode ?? "operation_failed",
+      message: operation.errorMessage ?? "operation failed",
+      statusCode: 0
+    });
+    this.operation = operation;
+    Object.setPrototypeOf(this, _AsyncOperationError.prototype);
+  }
+};
+var AsyncOperationTimeout = class _AsyncOperationTimeout extends SpreadSpaceError {
+  operation;
+  constructor(message, operation) {
+    super({ type: "operation_timeout", message, statusCode: 0 });
+    this.operation = operation;
+    Object.setPrototypeOf(this, _AsyncOperationTimeout.prototype);
+  }
+};
+var AsyncOperationHandle = class {
+  constructor(transport, operation) {
+    this.transport = transport;
+    this.op = operation;
+  }
+  transport;
+  op;
+  get id() {
+    return this.op.operationId;
+  }
+  /** Last-known state — does not hit the network. */
+  get operation() {
+    return this.op;
+  }
+  /** GET the operation once and cache the result. */
+  async refresh(options) {
+    this.op = await getOperation(this.transport, this.id, options);
+    return this.op;
+  }
+  /** POST the cancel route and cache the returned state. */
+  async cancel(options) {
+    this.op = await cancelOperation(this.transport, this.id, options);
+    return this.op;
+  }
+  /**
+   * 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.
+   */
+  async wait(options = {}) {
+    const timeoutMs = options.timeoutMs === void 0 ? 3e5 : options.timeoutMs;
+    const sleep = options.sleep ?? defaultSleep2;
+    const now = options.now ?? Date.now;
+    const deadline = timeoutMs === null ? null : now() + timeoutMs;
+    let delay = options.pollIntervalMs ?? 2e3;
+    for (; ; ) {
+      const op = await this.refresh();
+      if (isTerminal(op)) {
+        if (op.status === "failed") {
+          throw new AsyncOperationError(op);
+        }
+        return op;
+      }
+      if (deadline !== null && now() >= deadline) {
+        throw new AsyncOperationTimeout(
+          `operation ${this.id} did not finish within ${timeoutMs}ms (last status ${JSON.stringify(op.status)})`,
+          op
+        );
+      }
+      await sleep(delay);
+      delay = Math.min(delay * 2, BACKOFF_CAP_MS);
+    }
+  }
+};
+async function createExtractionExport(transport, params = {}, options) {
+  const body = {};
+  if (params.borrowerId !== void 0) body["borrower_id"] = params.borrowerId;
+  if (params.loanId !== void 0) body["loan_id"] = params.loanId;
+  if (params.documentIds !== void 0) body["document_ids"] = params.documentIds;
+  if (params.format !== void 0) body["format"] = params.format;
+  if (params.deliveryMode !== void 0) body["delivery_mode"] = params.deliveryMode;
+  const resp = await transport.request(
+    "POST",
+    `${OPERATIONS_PATH}/extraction_export`,
+    { body, ...options }
+  );
+  return new AsyncOperationHandle(transport, toAsyncOperation(resp));
+}
+async function getOperation(transport, operationId, options) {
+  const resp = await transport.request(
+    "GET",
+    `${OPERATIONS_PATH}/${encodeURIComponent(operationId)}`,
+    options
+  );
+  return toAsyncOperation(resp);
+}
+async function cancelOperation(transport, operationId, options) {
+  const resp = await transport.request(
+    "POST",
+    `${OPERATIONS_PATH}/${encodeURIComponent(operationId)}/cancel`,
+    options
+  );
+  return toAsyncOperation(resp);
+}
+function defaultSleep2(ms) {
+  if (ms <= 0) return Promise.resolve();
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// src/helpers/upload.ts
+import { createHash } from "crypto";
+import { readFile } from "fs/promises";
+import { basename } from "path";
+var TERMINAL_JOB_STATUSES = /* @__PURE__ */ new Set(["COMPLETED", "FAILED"]);
+var FAILURE_JOB_STATUSES = /* @__PURE__ */ new Set(["FAILED"]);
+var DOCUMENTS_PATH = "/api/documents";
+var DEFAULT_CONTENT_TYPE = "application/octet-stream";
+function parsePresignedUrl(body) {
+  const pick = (camel, snake) => {
+    const value = body[camel];
+    return value === void 0 || value === null ? body[snake] : value;
+  };
+  return {
+    jobId: pick("jobId", "job_id"),
+    uploadUrl: pick("uploadUrl", "upload_url"),
+    s3Key: pick("s3Key", "s3_key"),
+    expiresInSeconds: pick("expiresInSeconds", "expires_in_seconds")
+  };
+}
+var UploadError = class _UploadError extends SpreadSpaceError {
+  statusBody;
+  constructor(message, statusBody) {
+    super({ type: "upload_failed", message, statusCode: 0 });
+    this.statusBody = statusBody;
+    Object.setPrototypeOf(this, _UploadError.prototype);
+  }
+};
+var UploadTimeout = class _UploadTimeout extends SpreadSpaceError {
+  statusBody;
+  constructor(message, statusBody) {
+    super({ type: "upload_timeout", message, statusCode: 0 });
+    this.statusBody = statusBody;
+    Object.setPrototypeOf(this, _UploadTimeout.prototype);
+  }
+};
+var JobHandle = class {
+  constructor(transport, id, status, raw) {
+    this.transport = transport;
+    this.id = id;
+    this.status_ = status;
+    this.raw = raw ?? {};
+  }
+  transport;
+  id;
+  status_;
+  raw;
+  /** GET the status route once; cache and return the decoded body. */
+  async status() {
+    const body = await this.transport.request(
+      "GET",
+      `${DOCUMENTS_PATH}/${encodeURIComponent(this.id)}/status`
+    ) ?? {};
+    this.raw = body;
+    if (typeof body.status === "string") this.status_ = body.status;
+    return body;
+  }
+  /**
+   * 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.
+   */
+  async wait(options = {}) {
+    const {
+      timeoutMs = 6e5,
+      pollIntervalMs = 3e3,
+      terminalStatuses = TERMINAL_JOB_STATUSES,
+      sleep = defaultSleep3,
+      now = defaultNow
+    } = options;
+    const deadline = timeoutMs === null ? null : now() + timeoutMs;
+    for (; ; ) {
+      const body = await this.status();
+      const current = typeof body.status === "string" ? body.status : void 0;
+      if (current !== void 0 && terminalStatuses.has(current)) {
+        if (FAILURE_JOB_STATUSES.has(current)) {
+          throw new UploadError(`job ${this.id} ended in status ${current}`, body);
+        }
+        return body;
+      }
+      if (deadline !== null && now() >= deadline) {
+        throw new UploadTimeout(
+          `job ${this.id} did not finish within ${timeoutMs}ms (last status ${String(current)})`,
+          body
+        );
+      }
+      await sleep(pollIntervalMs);
+    }
+  }
+};
+async function uploadDocument(transport, file, options = {}) {
+  const {
+    fileName,
+    contentType,
+    fileSize,
+    borrowerId,
+    loanId,
+    contentHash,
+    computeHash = true,
+    sampleDocument,
+    wait = false,
+    waitOptions,
+    signal
+  } = options;
+  const payload = await resolvePayload(file, { fileName, contentType });
+  if (payload.fileName.length > 255) {
+    throw new Error("fileName must be <= 255 characters.");
+  }
+  const size = fileSize ?? payload.bytes.length;
+  let digest = contentHash;
+  if (digest === void 0 && computeHash) {
+    digest = createHash("sha256").update(payload.bytes).digest("hex");
+  }
+  const presignBody = { file_name: payload.fileName, content_type: payload.contentType };
+  if (size !== void 0) presignBody.file_size = size;
+  if (borrowerId !== void 0) presignBody.borrower_id = borrowerId;
+  if (loanId !== void 0) presignBody.loan_id = loanId;
+  if (digest !== void 0) presignBody.content_hash = digest;
+  const presignResponse = await transport.request(
+    "POST",
+    `${DOCUMENTS_PATH}/presigned-url`,
+    { body: presignBody, signal }
+  );
+  const presigned = parsePresignedUrl(presignResponse ?? {});
+  await transport.putPresigned(presigned.uploadUrl, payload.bytes, payload.contentType, { signal });
+  const confirmBody = sampleDocument !== void 0 ? { sample_document: sampleDocument } : {};
+  const confirmed = await transport.request(
+    "POST",
+    `${DOCUMENTS_PATH}/${encodeURIComponent(presigned.jobId)}/confirm-upload`,
+    { body: confirmBody, signal }
+  ) ?? {};
+  const handle = new JobHandle(
+    transport,
+    typeof confirmed.jobId === "string" ? confirmed.jobId : presigned.jobId,
+    typeof confirmed.status === "string" ? confirmed.status : void 0,
+    confirmed
+  );
+  if (wait) {
+    await handle.wait(waitOptions);
+  }
+  return handle;
+}
+function defaultSleep3(ms) {
+  if (ms <= 0) return Promise.resolve();
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function defaultNow() {
+  return Date.now();
+}
+async function resolvePayload(file, opts) {
+  if (typeof file === "string") {
+    const bytes = toOwnedBytes(await readFile(file));
+    const name = opts.fileName ?? basename(file);
+    const ctype = opts.contentType ?? guessContentType(name) ?? DEFAULT_CONTENT_TYPE;
+    return { bytes, fileName: name, contentType: ctype };
+  }
+  if (isBlob(file)) {
+    const bytes = toOwnedBytes(new Uint8Array(await file.arrayBuffer()));
+    const blobName = typeof file.name === "string" ? file.name : "";
+    const name = opts.fileName ?? blobName;
+    if (!name) {
+      throw new Error("fileName is required for a Blob without a name.");
+    }
+    const ctype = opts.contentType ?? (file.type || void 0) ?? guessContentType(name) ?? DEFAULT_CONTENT_TYPE;
+    return { bytes, fileName: name, contentType: ctype };
+  }
+  if (isBinaryData(file)) {
+    if (!opts.fileName || !opts.contentType) {
+      throw new Error("fileName and contentType are required when uploading raw bytes.");
+    }
+    return { bytes: toOwnedBytes(file), fileName: opts.fileName, contentType: opts.contentType };
+  }
+  if (isAsyncIterable(file) || isIterable(file)) {
+    if (!opts.fileName || !opts.contentType) {
+      throw new Error("fileName and contentType are required when uploading a stream.");
+    }
+    const bytes = await collectChunks(file);
+    return { bytes, fileName: opts.fileName, contentType: opts.contentType };
+  }
+  throw new TypeError(
+    "file must be a path string, Uint8Array/Buffer, Blob/File, or a Readable/iterable of chunks."
+  );
+}
+function isBlob(value) {
+  return typeof Blob !== "undefined" && value instanceof Blob && typeof value.arrayBuffer === "function";
+}
+function isBinaryData(value) {
+  return value instanceof Uint8Array || value instanceof ArrayBuffer || ArrayBuffer.isView(value);
+}
+function toOwnedBytes(value) {
+  const src = value instanceof Uint8Array ? value : value instanceof ArrayBuffer ? new Uint8Array(value) : new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+  const out = new Uint8Array(new ArrayBuffer(src.byteLength));
+  out.set(src);
+  return out;
+}
+function isAsyncIterable(value) {
+  return typeof value === "object" && value !== null && typeof value[Symbol.asyncIterator] === "function";
+}
+function isIterable(value) {
+  return typeof value === "object" && value !== null && typeof value[Symbol.iterator] === "function";
+}
+async function collectChunks(source) {
+  const parts = [];
+  let total = 0;
+  for await (const chunk of source) {
+    const part = typeof chunk === "string" ? new TextEncoder().encode(chunk) : chunk;
+    parts.push(part);
+    total += part.byteLength;
+  }
+  const out = new Uint8Array(new ArrayBuffer(total));
+  let offset = 0;
+  for (const part of parts) {
+    out.set(part, offset);
+    offset += part.byteLength;
+  }
+  return out;
+}
+var CONTENT_TYPE_BY_EXT = {
+  pdf: "application/pdf",
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  tif: "image/tiff",
+  tiff: "image/tiff",
+  csv: "text/csv",
+  txt: "text/plain",
+  xls: "application/vnd.ms-excel",
+  xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  doc: "application/msword",
+  docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
+};
+function guessContentType(name) {
+  const dot = name.lastIndexOf(".");
+  if (dot < 0 || dot === name.length - 1) return void 0;
+  return CONTENT_TYPE_BY_EXT[name.slice(dot + 1).toLowerCase()];
+}
+
+// src/resources/webhooks.ts
+var WebhooksResource = class {
+  constructor(transport) {
+    this.transport = transport;
+  }
+  transport;
+  /**
+   * Verify a `SpreadSpace-Signature` header against a body and signing secret.
+   * Throws `WebhookSignatureError` on any failure.
+   */
+  static verifySignature = verifyWebhook;
+  /**
+   * Verify a webhook signature and JSON-parse the body into a typed
+   * `WebhookEvent`. Throws `WebhookSignatureError` on signature failure or
+   * invalid JSON.
+   */
+  static verifyAndParse = verifyAndParseWebhook;
+  /** Low-level request shim onto the shared transport. */
+  request(method, path, options) {
+    return this.transport.request(method, path, options ?? {});
+  }
+  /**
+   * List configured webhook endpoints for this organization.
+   *
+   *   GET /api/admin/webhooks
+   */
+  list(params = {}) {
+    return paginate(this.transport, "/api/admin/webhooks", {
+      params: { limit: params.limit },
+      apiVersion: params.apiVersion
+    });
+  }
+  /**
+   * Retrieve a single webhook endpoint.
+   *
+   *   GET /api/admin/webhooks/{id}
+   */
+  retrieve(endpointId, options) {
+    return this.request(
+      "GET",
+      `/api/admin/webhooks/${encodeURIComponent(endpointId)}`,
+      options
+    );
+  }
+  /**
+   * 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(params, options) {
+    return this.request("POST", "/api/admin/webhooks", { body: params, ...options });
+  }
+  /**
+   * Update endpoint metadata (URL, subscribed event types, enabled flag).
+   *
+   *   PATCH /api/admin/webhooks/{id}
+   */
+  update(endpointId, params, options) {
+    return this.request(
+      "PATCH",
+      `/api/admin/webhooks/${encodeURIComponent(endpointId)}`,
+      { body: params, ...options }
+    );
+  }
+  /**
+   * Delete a webhook endpoint.
+   *
+   *   DELETE /api/admin/webhooks/{id}
+   */
+  delete(endpointId, options) {
+    return this.request(
+      "DELETE",
+      `/api/admin/webhooks/${encodeURIComponent(endpointId)}`,
+      options
+    );
+  }
+  /**
+   * 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(endpointId, params = {}, options) {
+    return this.request(
+      "POST",
+      `/api/admin/webhooks/${encodeURIComponent(endpointId)}/rotate`,
+      { body: params, ...options }
+    );
+  }
+  /**
+   * Iterate delivery attempts for an endpoint.
+   *
+   *   GET /api/admin/webhooks/{id}/deliveries
+   */
+  deliveries(endpointId, params = {}) {
+    return paginate(
+      this.transport,
+      `/api/admin/webhooks/${encodeURIComponent(endpointId)}/deliveries`,
+      { params: { limit: params.limit }, apiVersion: params.apiVersion }
+    );
+  }
+  /**
+   * Manually replay a delivery (e.g. after fixing a downstream outage).
+   *
+   *   POST /api/admin/webhooks/{id}/deliveries/{deliveryId}/replay
+   */
+  replayDelivery(endpointId, deliveryId, params = {}, options) {
+    return this.request(
+      "POST",
+      `/api/admin/webhooks/${encodeURIComponent(endpointId)}/deliveries/${encodeURIComponent(deliveryId)}/replay`,
+      { body: params, ...options }
+    );
+  }
+};
+
+// src/resources/embed.ts
+var EmbedSessionsResource = class {
+  constructor(transport) {
+    this.transport = transport;
+  }
+  transport;
+  request(method, path, options) {
+    return this.transport.request(method, path, options ?? {});
+  }
+  /**
+   * 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(params, options) {
+    return this.request("POST", "/api/embed/sessions", { body: params, ...options });
+  }
+  /**
+   * 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(sessionId, options) {
+    return this.request(
+      "DELETE",
+      `/api/embed/sessions/${encodeURIComponent(sessionId)}`,
+      options
+    );
+  }
+};
+var EmbedIframeUrlsResource = class {
+  constructor(transport) {
+    this.transport = transport;
+  }
+  transport;
+  request(method, path, options) {
+    return this.transport.request(method, path, options ?? {});
+  }
+  /**
+   * 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(params, options) {
+    return this.request("POST", "/api/embed/iframe-urls", { body: params, ...options });
+  }
+};
+var EmbedResource = class {
+  /** `embed.sessions` — mint/revoke embed-session tokens. */
+  sessions;
+  /** `embed.iframeUrls` — mint signed iframe-URL handles. */
+  iframeUrls;
+  constructor(transport) {
+    this.sessions = new EmbedSessionsResource(transport);
+    this.iframeUrls = new EmbedIframeUrlsResource(transport);
+  }
+};
+
+// src/client.ts
+function envApiKey() {
+  if (typeof process === "undefined" || !process.env) return void 0;
+  const value = process.env.SPREADSPACE_API_KEY;
+  return value && value.length > 0 ? value : void 0;
+}
+var BorrowersResource = class {
+  constructor(transport) {
+    this.transport = transport;
+  }
+  transport;
+  /** Paginate `GET /api/borrowers`. Lazy async-iterable of borrower records. */
+  list(params = {}) {
+    return paginate(this.transport, "/api/borrowers", {
+      params: { limit: params.limit, intake: params.intake },
+      apiVersion: params.apiVersion
+    });
+  }
+};
+var LoansResource = class {
+  constructor(transport) {
+    this.transport = transport;
+  }
+  transport;
+  /**
+   * Paginate loans. With `borrowerId`, hits `GET /api/borrowers/{id}/loans`;
+   * otherwise the org-wide `GET /api/loans`.
+   */
+  list(params = {}) {
+    const path = params.borrowerId ? `/api/borrowers/${encodeURIComponent(params.borrowerId)}/loans` : "/api/loans";
+    return paginate(this.transport, path, {
+      params: { limit: params.limit },
+      apiVersion: params.apiVersion
+    });
+  }
+};
+var JobsResource = class {
+  constructor(transport) {
+    this.transport = transport;
+  }
+  transport;
+  /** Paginate `GET /api/jobs`. */
+  list(params = {}) {
+    return paginate(this.transport, "/api/jobs", {
+      params: { limit: params.limit },
+      apiVersion: params.apiVersion
+    });
+  }
+};
+var AsyncOperationsResource = class {
+  constructor(transport) {
+    this.transport = transport;
+  }
+  transport;
+  /**
+   * Paginate `GET /api/async-operations`. Divergent envelope: items live under
+   * `operations` (no `data`/`limit`), so the items key is overridden here.
+   */
+  list(params = {}) {
+    return paginate(this.transport, "/api/async-operations", {
+      params: { limit: params.limit, kind: params.kind, status: params.status },
+      itemsKey: "operations",
+      apiVersion: params.apiVersion
+    });
+  }
+  /** `GET /api/async-operations/{id}` — fetch one operation's current state. */
+  get(operationId, options) {
+    return getOperation(this.transport, operationId, options);
+  }
+  /**
+   * `POST /api/async-operations/{id}/cancel`. Cancelling a terminal
+   * (non-cancelled) op -> 409 (`ConflictError`); cancelling an already-cancelled
+   * op is idempotent (200).
+   */
+  cancel(operationId, options) {
+    return cancelOperation(this.transport, operationId, options);
+  }
+};
+var ExportsResource = class {
+  constructor(transport) {
+    this.transport = 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 = {}, options) {
+    return createExtractionExport(this.transport, params, options);
+  }
+  /** `GET /api/async-operations/{id}` — fetch the export operation's state. */
+  get(operationId, options) {
+    return getOperation(this.transport, operationId, options);
+  }
+};
+var DocumentsResource = class {
+  constructor(transport) {
+    this.transport = 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, options) {
+    return uploadDocument(this.transport, file, options);
+  }
+  /** `GET /api/documents/{jobId}/status` — fetch one job's current status body. */
+  status(jobId) {
+    return new JobHandle(this.transport, jobId).status();
+  }
+};
+var SpreadSpace = class {
+  /** Borrowers: `list()`. */
+  borrowers;
+  /** Loans: `list({ borrowerId?, limit? })`. */
+  loans;
+  /** Jobs: `list()`. */
+  jobs;
+  /** Async operations: `list({ kind?, status? })` / `get(id)` / `cancel(id)`. */
+  asyncOperations;
+  /** Extraction exports: `create(...)` / `get(id)`. */
+  exports;
+  /** Documents: `upload(file, opts)` / `status(jobId)`. */
+  documents;
+  /** Webhooks: `create/list/retrieve/update/delete` endpoints + static `verifySignature`/`verifyAndParse`. */
+  webhooks;
+  /** Embed: `sessions.create(...)` mints a loan-scoped `ss_embed_` token. */
+  embed;
+  _transport;
+  constructor(options = {}) {
+    if (options.transport) {
+      this._transport = options.transport;
+    } else {
+      const apiKey = options.apiKey ?? envApiKey();
+      if (!apiKey) {
+        throw new TypeError(
+          "SpreadSpace requires an apiKey. Pass { apiKey } or set SPREADSPACE_API_KEY. Issue a key from the dashboard at /settings/api-keys."
+        );
+      }
+      this._transport = new Transport({
+        apiKey,
+        baseUrl: options.baseUrl ?? DEFAULT_BASE_URL,
+        apiVersion: options.apiVersion ?? DEFAULT_API_VERSION,
+        timeout: options.timeoutMs,
+        maxRetries: options.maxRetries,
+        fetch: options.fetch
+      });
+    }
+    this.borrowers = new BorrowersResource(this._transport);
+    this.loans = new LoansResource(this._transport);
+    this.jobs = new JobsResource(this._transport);
+    this.asyncOperations = new AsyncOperationsResource(this._transport);
+    this.exports = new ExportsResource(this._transport);
+    this.documents = new DocumentsResource(this._transport);
+    this.webhooks = new WebhooksResource(this._transport);
+    this.embed = new EmbedResource(this._transport);
+  }
+  /** The underlying configured transport. */
+  get transport() {
+    return this._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(method, path, options) {
+    return this._transport.request(method, path, options);
+  }
+};
+export {
+  AsyncOperationError,
+  AsyncOperationHandle,
+  AsyncOperationTimeout,
+  AuthenticationError,
+  ConflictError,
+  DEFAULT_API_VERSION,
+  DEFAULT_BASE_URL,
+  Decimal,
+  EmbedIframeUrlsResource,
+  EmbedResource,
+  EmbedSessionsResource,
+  InvalidRequestError,
+  JobHandle,
+  NetworkError,
+  NotFoundError,
+  PAYLOAD_MONEY_KEYS,
+  PermissionError,
+  RateLimitError,
+  SCALAR_MONEY_KEYS,
+  SDK_VERSION,
+  ServerError,
+  SpreadSpace,
+  SpreadSpaceError,
+  TERMINAL_JOB_STATUSES,
+  TERMINAL_STATUSES,
+  Transport,
+  UploadError,
+  UploadTimeout,
+  WebhookSignatureError,
+  WebhooksResource,
+  cancelOperation,
+  classifyError,
+  createExtractionExport,
+  getOperation,
+  isTerminal,
+  paginate,
+  parseBodyWithExactMoney,
+  parsePresignedUrl,
+  uploadDocument,
+  verifyAndParseWebhook,
+  verifyWebhook
+};
+//# sourceMappingURL=index.js.map