@spreadspace/embed 0.1.0

package/dist/index.js

@@ -0,0 +1,1131 @@
+import { createHmac, timingSafeEqual, randomUUID } from 'crypto';
+
+// src/client.ts
+
+// src/errors.ts
+var SpreadSpaceError = class extends Error {
+  /**
+   * The canonical `error.type` string from the API envelope, e.g.
+   * `invalid_request`, `rate_limited`, `idempotency_request_mismatch`.
+   * Stable across versions — clients pattern-match on this.
+   */
+  type;
+  /** HTTP status code. */
+  statusCode;
+  /** `X-Request-ID` echoed from the server. Quote in support tickets. */
+  requestId;
+  /** Raw response body for debugging. May be the parsed JSON or a string. */
+  rawBody;
+  /** Optional structured details (e.g. `borrower_id` on `pii_claim_required`). */
+  details;
+  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;
+    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 InvalidRequestError;
+}
+
+// src/pagination.ts
+function paginate(client, path, params, options) {
+  let cursor;
+  let exhausted = false;
+  async function fetchPage() {
+    if (exhausted) return null;
+    const query = { ...params ?? {} };
+    if (cursor !== void 0) query.cursor = cursor;
+    const response = await client.request("GET", path, {
+      query,
+      ...options
+    });
+    const next = response.next_cursor ?? null;
+    if (!next) {
+      exhausted = true;
+    } else {
+      cursor = next;
+    }
+    return response;
+  }
+  async function* itemIterator() {
+    while (true) {
+      const page = await fetchPage();
+      if (!page) return;
+      for (const item of page.data) {
+        yield item;
+      }
+      if (exhausted) return;
+    }
+  }
+  async function* pageIterator() {
+    while (true) {
+      const page = await fetchPage();
+      if (!page) return;
+      yield page;
+      if (exhausted) return;
+    }
+  }
+  const iter = itemIterator();
+  const pager = {
+    async next() {
+      return iter.next();
+    },
+    async return(value) {
+      exhausted = true;
+      return { value, done: true };
+    },
+    async throw(err) {
+      exhausted = true;
+      throw err;
+    },
+    [Symbol.asyncIterator]() {
+      return pager;
+    },
+    async toArray() {
+      const out = [];
+      for await (const item of pager) {
+        out.push(item);
+      }
+      return out;
+    },
+    pages() {
+      return pageIterator();
+    }
+  };
+  return pager;
+}
+
+// src/resources/borrowers.ts
+var BorrowersResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /**
+   * Retrieve a borrower by id.
+   *
+   *   GET /api/borrowers/{id}
+   */
+  async retrieve(borrowerId, options) {
+    return this.client.request(
+      "GET",
+      `/api/borrowers/${encodeURIComponent(borrowerId)}`,
+      options
+    );
+  }
+  /**
+   * Create a new borrower.
+   *
+   *   POST /api/borrowers
+   */
+  async create(params, options) {
+    return this.client.request("POST", "/api/borrowers", { body: params, ...options });
+  }
+  /**
+   * Iterate every borrower visible to the calling principal.
+   *
+   *   GET /api/borrowers
+   */
+  list(params, options) {
+    return this.client.paginate(
+      "/api/borrowers",
+      params,
+      options
+    );
+  }
+  /**
+   * Assign a lender to this borrower.
+   *
+   *   POST /api/borrowers/{id}/assign
+   */
+  async assign(borrowerId, params, options) {
+    return this.client.request(
+      "POST",
+      `/api/borrowers/${encodeURIComponent(borrowerId)}/assign`,
+      { body: params, ...options }
+    );
+  }
+  /**
+   * Claim PII access on a borrower. Required by SOC 2 / GLBA before an
+   * admin can view the borrower's extracted financials. Surfaced as a verb
+   * method (rather than `update()`) because the audit log records this as
+   * a distinct event and integrators reading the SDK want to see the flow
+   * by name.
+   *
+   *   POST /api/borrowers/{id}/claim
+   */
+  async claim(borrowerId, params, options) {
+    return this.client.request(
+      "POST",
+      `/api/borrowers/${encodeURIComponent(borrowerId)}/claim`,
+      { body: params, ...options }
+    );
+  }
+  /**
+   * Fetch the audit log for a borrower (PII access events, claim grants,
+   * etc.).
+   *
+   *   GET /api/borrowers/{id}/audit-log
+   */
+  async auditLog(borrowerId, options) {
+    return this.client.request(
+      "GET",
+      `/api/borrowers/${encodeURIComponent(borrowerId)}/audit-log`,
+      options
+    );
+  }
+  /**
+   * List loans associated with a borrower.
+   *
+   *   GET /api/borrowers/{borrowerId}/loans
+   */
+  loans(borrowerId, params, options) {
+    return this.client.paginate(
+      `/api/borrowers/${encodeURIComponent(borrowerId)}/loans`,
+      params,
+      options
+    );
+  }
+  /**
+   * List jobs (document packages) for a borrower.
+   *
+   *   GET /api/borrowers/{id}/jobs
+   */
+  jobs(borrowerId, params, options) {
+    return this.client.paginate(
+      `/api/borrowers/${encodeURIComponent(borrowerId)}/jobs`,
+      params,
+      options
+    );
+  }
+  /**
+   * Fetch results for a specific job under a borrower.
+   *
+   *   GET /api/borrowers/{id}/jobs/{jobId}/results
+   */
+  async jobResults(borrowerId, jobId, options) {
+    return this.client.request(
+      "GET",
+      `/api/borrowers/${encodeURIComponent(borrowerId)}/jobs/${encodeURIComponent(jobId)}/results`,
+      options
+    );
+  }
+};
+
+// src/resources/documents.ts
+var DocumentsResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /**
+   * Request a presigned S3 PUT URL for a single document upload.
+   *
+   *   POST /api/documents/presigned-url
+   */
+  async presignedUrl(params, options) {
+    return this.client.request("POST", "/api/documents/presigned-url", {
+      body: params,
+      ...options
+    });
+  }
+  /**
+   * Confirm a single uploaded document, kicking off the extraction
+   * pipeline.
+   *
+   *   POST /api/documents/{jobId}/confirm-upload
+   */
+  async confirmUpload(jobId, params = {}, options) {
+    return this.client.request(
+      "POST",
+      `/api/documents/${encodeURIComponent(jobId)}/confirm-upload`,
+      { body: params, ...options }
+    );
+  }
+  /**
+   * Confirm a batch of uploaded documents in a single request. Faster than
+   * looping `confirmUpload()` when the integrator has many files in one
+   * package.
+   *
+   *   POST /api/documents/confirm-uploads
+   */
+  async batchConfirm(params, options) {
+    return this.client.request("POST", "/api/documents/confirm-uploads", {
+      body: params,
+      ...options
+    });
+  }
+  /**
+   * Get a presigned S3 GET URL to download a previously-uploaded document.
+   *
+   *   GET /api/documents/{jobId}/download-url
+   */
+  async downloadUrl(jobId, options) {
+    return this.client.request(
+      "GET",
+      `/api/documents/${encodeURIComponent(jobId)}/download-url`,
+      options
+    );
+  }
+  /**
+   * Fetch processing status for a document upload.
+   *
+   *   GET /api/documents/{jobId}/status
+   */
+  async status(jobId, options) {
+    return this.client.request(
+      "GET",
+      `/api/documents/${encodeURIComponent(jobId)}/status`,
+      options
+    );
+  }
+};
+
+// src/resources/embed.ts
+var EmbedSessionsResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /**
+   * Mint an embed-session token for a loan. The minted token has a strict
+   * subset of the calling API key's scopes and is locked to the supplied
+   * `loan_id` — it cannot be used to access other loans or to mint further
+   * tokens.
+   *
+   *   POST /api/embed/sessions
+   *
+   *   Body: { loan_id, scopes?, expires_in_seconds? }
+   *   Returns: { embed_token, expires_at, ... }
+   */
+  async create(params, options) {
+    return this.client.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.
+   *
+   *   DELETE /api/embed/sessions/{sessionId}
+   */
+  async revoke(sessionId, options) {
+    return this.client.request(
+      "DELETE",
+      `/api/embed/sessions/${encodeURIComponent(sessionId)}`,
+      options
+    );
+  }
+};
+var EmbedResource = class {
+  sessions;
+  constructor(client) {
+    this.sessions = new EmbedSessionsResource(client);
+  }
+};
+
+// src/resources/extractions.ts
+var ExtractionsResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /**
+   * Iterate every extraction for a borrower.
+   *
+   *   GET /api/borrowers/{borrowerId}/extractions
+   */
+  list(borrowerId, params, options) {
+    return this.client.paginate(
+      `/api/borrowers/${encodeURIComponent(borrowerId)}/extractions`,
+      params,
+      options
+    );
+  }
+  /**
+   * Structured query across a borrower's extractions. Filter by document
+   * type, period, and other metadata.
+   *
+   *   POST /api/borrowers/{borrowerId}/extractions/query
+   */
+  async query(borrowerId, params, options) {
+    return this.client.request(
+      "POST",
+      `/api/borrowers/${encodeURIComponent(borrowerId)}/extractions/query`,
+      { body: params, ...options }
+    );
+  }
+  /**
+   * Move an extracted document to a different loan under the same
+   * borrower. Use when the user uploaded a doc to the wrong package.
+   *
+   *   POST /api/borrowers/{borrowerId}/extractions/{docId}/move
+   */
+  async move(borrowerId, docId, params, options) {
+    return this.client.request(
+      "POST",
+      `/api/borrowers/${encodeURIComponent(borrowerId)}/extractions/${encodeURIComponent(docId)}/move`,
+      { body: params, ...options }
+    );
+  }
+  /**
+   * Roll-up of the borrower's bank-statement analyses across all
+   * uploaded statements.
+   *
+   *   GET /api/borrowers/{borrowerId}/extractions/bank-statement-analysis
+   */
+  async bankStatementAnalysis(borrowerId, options) {
+    return this.client.request(
+      "GET",
+      `/api/borrowers/${encodeURIComponent(borrowerId)}/extractions/bank-statement-analysis`,
+      options
+    );
+  }
+  /**
+   * Roll-up of the borrower's balance sheet across all uploaded
+   * balance-sheet documents.
+   */
+  async balanceSheet(borrowerId, options) {
+    return this.client.request(
+      "GET",
+      `/api/borrowers/${encodeURIComponent(borrowerId)}/extractions/balance-sheet`,
+      options
+    );
+  }
+  /** P&L roll-up across uploaded P&L documents. */
+  async pl(borrowerId, options) {
+    return this.client.request(
+      "GET",
+      `/api/borrowers/${encodeURIComponent(borrowerId)}/extractions/pl`,
+      options
+    );
+  }
+  /** Cash-flow roll-up. */
+  async cashFlow(borrowerId, options) {
+    return this.client.request(
+      "GET",
+      `/api/borrowers/${encodeURIComponent(borrowerId)}/extractions/cash-flow`,
+      options
+    );
+  }
+  /** Accounts payable roll-up. */
+  async accountsPayable(borrowerId, options) {
+    return this.client.request(
+      "GET",
+      `/api/borrowers/${encodeURIComponent(borrowerId)}/extractions/accounts-payable`,
+      options
+    );
+  }
+  /** Accounts receivable roll-up. */
+  async accountsReceivable(borrowerId, options) {
+    return this.client.request(
+      "GET",
+      `/api/borrowers/${encodeURIComponent(borrowerId)}/extractions/accounts-receivable`,
+      options
+    );
+  }
+  /**
+   * Generic report endpoint — pass the report type as a path segment.
+   * Useful for report types added after this SDK release.
+   *
+   *   GET /api/borrowers/{borrowerId}/extractions/reports/{reportType}
+   */
+  async report(borrowerId, reportType, options) {
+    return this.client.request(
+      "GET",
+      `/api/borrowers/${encodeURIComponent(borrowerId)}/extractions/reports/${encodeURIComponent(reportType)}`,
+      options
+    );
+  }
+};
+
+// src/resources/jobs.ts
+var JobsResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /**
+   * Iterate jobs visible to the calling principal.
+   *
+   *   GET /api/jobs
+   */
+  list(params, options) {
+    return this.client.paginate(
+      "/api/jobs",
+      params,
+      options
+    );
+  }
+  /**
+   * Fetch processing status for a job.
+   *
+   *   GET /api/jobs/{jobId}/status
+   */
+  async status(jobId, options) {
+    return this.client.request(
+      "GET",
+      `/api/jobs/${encodeURIComponent(jobId)}/status`,
+      options
+    );
+  }
+  /**
+   * Fetch results for a job — the rolled-up extraction outcomes.
+   *
+   *   GET /api/jobs/{jobId}/results
+   */
+  async results(jobId, options) {
+    return this.client.request(
+      "GET",
+      `/api/jobs/${encodeURIComponent(jobId)}/results`,
+      options
+    );
+  }
+};
+
+// src/resources/loans.ts
+var LoansResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /**
+   * Retrieve a loan by id.
+   *
+   *   GET /api/loans/{loanId}
+   */
+  async retrieve(loanId, options) {
+    return this.client.request("GET", `/api/loans/${encodeURIComponent(loanId)}`, options);
+  }
+  /**
+   * Create a new loan.
+   *
+   *   POST /api/loans
+   */
+  async create(params, options) {
+    return this.client.request("POST", "/api/loans", { body: params, ...options });
+  }
+  /**
+   * Update an existing loan.
+   *
+   *   PATCH /api/loans/{loanId}
+   */
+  async update(loanId, params, options) {
+    return this.client.request("PATCH", `/api/loans/${encodeURIComponent(loanId)}`, {
+      body: params,
+      ...options
+    });
+  }
+  /**
+   * Iterate every loan visible to the calling principal. Returns an
+   * `AsyncPager<T>` — consume with `for await`, `.toArray()`, or
+   * `.pages()`.
+   *
+   *   GET /api/loans
+   */
+  list(params, options) {
+    return this.client.paginate(
+      "/api/loans",
+      params,
+      options
+    );
+  }
+  /**
+   * Assign a lender to this loan. Calls `POST /api/loans/{id}/assign`.
+   * Surfaced as a verb method rather than forcing it through `update()`
+   * because the assignment flow is semantically distinct from a generic
+   * field patch (it touches the lender-access table, not the loan row).
+   */
+  async assign(loanId, params, options) {
+    return this.client.request("POST", `/api/loans/${encodeURIComponent(loanId)}/assign`, {
+      body: params,
+      ...options
+    });
+  }
+  /**
+   * Fetch the audit log for a loan.
+   *
+   *   GET /api/loans/{loanId}/audit-log
+   */
+  async auditLog(loanId, options) {
+    return this.client.request(
+      "GET",
+      `/api/loans/${encodeURIComponent(loanId)}/audit-log`,
+      options
+    );
+  }
+};
+var DEFAULT_FRESHNESS_TOLERANCE_SECONDS = 5 * 60;
+var VERSION_1_PREFIX = "v1";
+function verifyWebhookSignature(rawBody, signature, secret, options) {
+  if (typeof signature !== "string" || signature.length === 0) {
+    throw new WebhookSignatureError("SpreadSpace-Signature header is missing or empty.");
+  }
+  if (typeof secret !== "string" || secret.length === 0) {
+    throw new WebhookSignatureError("Webhook signing secret is missing or empty.");
+  }
+  if (rawBody === null || rawBody === void 0) {
+    throw new WebhookSignatureError("Webhook raw body is missing.");
+  }
+  const parsed = parseSignatureHeader(signature);
+  if (!parsed) {
+    throw new WebhookSignatureError("Webhook signature header is malformed.");
+  }
+  const { timestamp, hex } = parsed;
+  const bodyString = bodyToString(rawBody);
+  const expectedHex = computeHmacHex(secret, `${timestamp}.${bodyString}`);
+  if (!hexEquals(expectedHex, hex)) {
+    throw new WebhookSignatureError("Webhook signature does not match.");
+  }
+  const tolerance = options?.freshnessTolerance ?? DEFAULT_FRESHNESS_TOLERANCE_SECONDS;
+  const now = options?.currentTimestamp ?? Math.floor(Date.now() / 1e3);
+  const age = now - timestamp;
+  if (age > tolerance || age < -tolerance) {
+    throw new WebhookSignatureError(
+      `Webhook timestamp is outside the freshness window of ${tolerance}s.`
+    );
+  }
+  return true;
+}
+function verifyAndParseWebhook(rawBody, signature, secret, options) {
+  verifyWebhookSignature(rawBody, signature, secret, options);
+  const bodyString = bodyToString(rawBody);
+  let parsed;
+  try {
+    parsed = JSON.parse(bodyString);
+  } catch (cause) {
+    throw new WebhookSignatureError("Webhook body is not valid JSON.", cause);
+  }
+  if (!isPlainObject(parsed)) {
+    throw new WebhookSignatureError("Webhook body is not a JSON object.");
+  }
+  const candidate = parsed;
+  if (typeof candidate.type !== "string" || candidate.type.length === 0) {
+    throw new WebhookSignatureError("Webhook body is missing a `type` field.");
+  }
+  if (typeof candidate.id !== "string" || candidate.id.length === 0) {
+    throw new WebhookSignatureError("Webhook body is missing an `id` field.");
+  }
+  if (typeof candidate.created !== "number") {
+    throw new WebhookSignatureError("Webhook body is missing a numeric `created` field.");
+  }
+  if (typeof candidate.tenant_id !== "string" || candidate.tenant_id.length === 0) {
+    throw new WebhookSignatureError("Webhook body is missing a `tenant_id` field.");
+  }
+  if (!isPlainObject(candidate.data)) {
+    throw new WebhookSignatureError("Webhook body is missing a `data` object.");
+  }
+  return parsed;
+}
+var WebhookSignatureError = class _WebhookSignatureError extends Error {
+  cause;
+  constructor(message, cause) {
+    super(message);
+    this.name = "WebhookSignatureError";
+    this.cause = cause;
+    Object.setPrototypeOf(this, _WebhookSignatureError.prototype);
+  }
+};
+function parseSignatureHeader(header) {
+  const segments = header.split(",").filter((s) => s.length > 0);
+  if (segments.length < 2) return null;
+  let parsedTs = null;
+  let parsedV1 = null;
+  for (const raw of segments) {
+    const segment = raw.trim();
+    const eq = segment.indexOf("=");
+    if (eq <= 0 || eq === segment.length - 1) {
+      return null;
+    }
+    const key = segment.slice(0, eq).trim();
+    const value = segment.slice(eq + 1).trim();
+    if (key === "t") {
+      if (parsedTs !== null) return null;
+      if (!/^-?\d+$/.test(value)) return null;
+      const ts = Number(value);
+      if (!Number.isFinite(ts) || !Number.isInteger(ts)) return null;
+      parsedTs = ts;
+    } else if (key === VERSION_1_PREFIX) {
+      if (parsedV1 !== null) return null;
+      if (value.length === 0) return null;
+      parsedV1 = value;
+    }
+  }
+  if (parsedTs === null || parsedV1 === null) return null;
+  return { timestamp: parsedTs, hex: parsedV1 };
+}
+function computeHmacHex(secret, signedPayload) {
+  const hmac = createHmac("sha256", Buffer.from(secret, "utf-8"));
+  hmac.update(Buffer.from(signedPayload, "utf-8"));
+  return hmac.digest("hex");
+}
+function hexEquals(expectedHex, providedHex) {
+  if (expectedHex.length !== providedHex.length) return false;
+  let expectedBytes;
+  let providedBytes;
+  try {
+    expectedBytes = Buffer.from(expectedHex, "hex");
+    providedBytes = Buffer.from(providedHex, "hex");
+  } catch {
+    return false;
+  }
+  if (expectedBytes.length !== providedBytes.length) return false;
+  if (expectedBytes.length * 2 !== expectedHex.length) return false;
+  if (providedBytes.length * 2 !== providedHex.length) return false;
+  return timingSafeEqual(
+    new Uint8Array(expectedBytes.buffer, expectedBytes.byteOffset, expectedBytes.byteLength),
+    new Uint8Array(providedBytes.buffer, providedBytes.byteOffset, providedBytes.byteLength)
+  );
+}
+function bodyToString(body) {
+  if (typeof body === "string") return body;
+  if (Buffer.isBuffer(body)) return body.toString("utf-8");
+  return Buffer.from(body).toString("utf-8");
+}
+function isPlainObject(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+// src/resources/webhooks.ts
+var WebhooksResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /**
+   * Verify a `SpreadSpace-Signature` header against a body and signing
+   * secret. Throws `WebhookSignatureError` on any failure.
+   */
+  static verifySignature = verifyWebhookSignature;
+  /**
+   * Verify a webhook signature and JSON-parse the body into a typed
+   * `WebhookEvent`. Throws `WebhookSignatureError` on signature failure or
+   * invalid JSON.
+   */
+  static verifyAndParse = verifyAndParseWebhook;
+  /**
+   * List configured webhook endpoints for this organization.
+   *
+   *   GET /api/webhooks
+   */
+  list(params, options) {
+    return this.client.paginate(
+      "/api/webhooks",
+      params,
+      options
+    );
+  }
+  /**
+   * Retrieve a single webhook endpoint.
+   *
+   *   GET /api/webhooks/{id}
+   */
+  async retrieve(endpointId, options) {
+    return this.client.request(
+      "GET",
+      `/api/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/webhooks
+   */
+  async create(params, options) {
+    return this.client.request("POST", "/api/webhooks", { body: params, ...options });
+  }
+  /**
+   * Update endpoint metadata (URL, subscribed event types, enabled flag).
+   *
+   *   PATCH /api/webhooks/{id}
+   */
+  async update(endpointId, params, options) {
+    return this.client.request(
+      "PATCH",
+      `/api/webhooks/${encodeURIComponent(endpointId)}`,
+      { body: params, ...options }
+    );
+  }
+  /**
+   * Delete a webhook endpoint.
+   *
+   *   DELETE /api/webhooks/{id}
+   */
+  async delete(endpointId, options) {
+    return this.client.request(
+      "DELETE",
+      `/api/webhooks/${encodeURIComponent(endpointId)}`,
+      options
+    );
+  }
+  /**
+   * Rotate an endpoint's signing secret. The old secret remains valid for
+   * a grace window so deliveries in flight aren't dropped. Returns the new
+   * plaintext secret exactly once.
+   *
+   *   POST /api/webhooks/{id}/rotate
+   */
+  async rotateSecret(endpointId, params = {}, options) {
+    return this.client.request(
+      "POST",
+      `/api/webhooks/${encodeURIComponent(endpointId)}/rotate`,
+      { body: params, ...options }
+    );
+  }
+  /**
+   * Iterate delivery attempts for an endpoint.
+   *
+   *   GET /api/webhooks/{id}/deliveries
+   */
+  deliveries(endpointId, params, options) {
+    return this.client.paginate(
+      `/api/webhooks/${encodeURIComponent(endpointId)}/deliveries`,
+      params,
+      options
+    );
+  }
+  /**
+   * Manually replay a delivery (e.g. after fixing a downstream outage).
+   *
+   *   POST /api/webhooks/{id}/deliveries/{deliveryId}/replay
+   */
+  async replayDelivery(endpointId, deliveryId, params = {}, options) {
+    return this.client.request(
+      "POST",
+      `/api/webhooks/${encodeURIComponent(endpointId)}/deliveries/${encodeURIComponent(deliveryId)}/replay`,
+      { body: params, ...options }
+    );
+  }
+};
+
+// src/version.ts
+var SDK_VERSION = "0.1.0";
+var DEFAULT_API_VERSION = "2026-05-03";
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.spreadspace.app";
+var DEFAULT_TIMEOUT_MS = 3e4;
+var DEFAULT_MAX_RETRIES = 3;
+var RETRY_BASE_DELAY_MS = 500;
+var RETRY_MAX_DELAY_MS = 3e4;
+var SpreadSpaceClient = class {
+  /** Resolved base URL (no trailing slash). */
+  baseUrl;
+  /** Resolved API version string (the `SpreadSpace-Version` header value). */
+  apiVersion;
+  /** Public so resource files can pull it for `paginate()` URL construction. */
+  maxRetries;
+  // ── Resources ────────────────────────────────────────────────────────────
+  loans;
+  borrowers;
+  documents;
+  extractions;
+  jobs;
+  webhooks;
+  embed;
+  // ── Internals ────────────────────────────────────────────────────────────
+  apiKey;
+  timeoutMs;
+  fetchImpl;
+  idempotencyKeyGenerator;
+  constructor(options) {
+    if (!options || typeof options.apiKey !== "string" || options.apiKey.length === 0) {
+      throw new TypeError(
+        "SpreadSpaceClient 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.idempotencyKeyGenerator = options.idempotencyKeyGenerator ?? randomUUID;
+    if (typeof this.fetchImpl !== "function") {
+      throw new TypeError(
+        "SpreadSpaceClient requires a fetch implementation. Node 18+ provides one globally; pass a polyfill via options.fetch otherwise."
+      );
+    }
+    this.loans = new LoansResource(this);
+    this.borrowers = new BorrowersResource(this);
+    this.documents = new DocumentsResource(this);
+    this.extractions = new ExtractionsResource(this);
+    this.jobs = new JobsResource(this);
+    this.webhooks = new WebhooksResource(this);
+    this.embed = new EmbedResource(this);
+  }
+  /**
+   * Low-level request method. Resource layer wraps this with ergonomic
+   * method names; integrators can call it directly to hit endpoints not yet
+   * surfaced via a typed resource.
+   *
+   * Returns the parsed JSON body. For 204 No Content responses (currently
+   * none in the API but reserved), returns `undefined as T`.
+   */
+  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 maxRetries = options.maxRetries ?? this.maxRetries;
+    let attempt = 0;
+    let lastError;
+    while (attempt <= maxRetries) {
+      const controller = new AbortController();
+      const timeoutHandle = setTimeout(() => controller.abort(), this.timeoutMs);
+      const signal = options.signal ? composeAbortSignals(controller.signal, options.signal) : controller.signal;
+      let response;
+      try {
+        response = await this.fetchImpl(url, {
+          method,
+          headers,
+          body,
+          signal
+        });
+      } catch (err) {
+        clearTimeout(timeoutHandle);
+        lastError = err;
+        if (attempt < maxRetries) {
+          await sleep(this.computeRetryDelay(attempt, void 0));
+          attempt += 1;
+          continue;
+        }
+        throw new NetworkError(
+          `SpreadSpace request to ${method} ${url} failed: ${describeError(err)}`,
+          err
+        );
+      }
+      clearTimeout(timeoutHandle);
+      const requestId = response.headers.get("X-Request-ID") ?? void 0;
+      if (response.ok) {
+        return await this.parseSuccessBody(response);
+      }
+      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 sleep(this.computeRetryDelay(attempt, retryAfterSec));
+        attempt += 1;
+        try {
+          await response.body?.cancel();
+        } catch {
+        }
+        continue;
+      }
+      throw await this.buildErrorFromResponse(response, requestId);
+    }
+    throw new NetworkError(
+      `SpreadSpace request to ${method} ${url} exhausted retries (last error: ${describeError(lastError)}).`,
+      lastError
+    );
+  }
+  /**
+   * Convenience wrapper around `paginate()` for resource list methods. Lets
+   * each resource simply do `return this.client.paginate(...)` rather than
+   * importing the helper directly.
+   */
+  paginate(path, params, options) {
+    return paginate(this, path, params, options);
+  }
+  // ────────────────────────────────────────────────────────────────────────
+  // 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.buildUserAgent());
+    if (options.body !== void 0) {
+      headers.set("Content-Type", "application/json; charset=utf-8");
+    }
+    if (method !== "GET") {
+      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;
+  }
+  buildUserAgent() {
+    const nodeVersion = typeof process !== "undefined" ? process.version : "unknown";
+    return `spreadspace-node/${SDK_VERSION} node/${nodeVersion}`;
+  }
+  /**
+   * Compute the next retry delay. Exponential backoff with full jitter,
+   * floored by `Retry-After` if the server provided one (we never retry
+   * faster than the server asked us to).
+   *
+   *   base = min(maxDelay, baseDelay * 2^attempt)
+   *   delay = random(0, base)
+   *
+   * Full jitter (vs. equal jitter) is the AWS-recommended default — it
+   * minimizes thundering-herd across many concurrent retrying 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) {
+      const retryAfterMs = retryAfterSec * 1e3;
+      return Math.max(jittered, retryAfterMs);
+    }
+    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 JSON.parse(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 ErrorClass = classifyError(status);
+    const ctorParams = {
+      type,
+      message,
+      statusCode: status,
+      requestId: resolvedRequestId,
+      rawBody,
+      details
+    };
+    return new ErrorClass(ctorParams);
+  }
+};
+function sleep(ms) {
+  if (ms <= 0) return Promise.resolve();
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+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);
+}
+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;
+}
+
+export { AuthenticationError, BorrowersResource, ConflictError, DEFAULT_API_VERSION, DocumentsResource, EmbedResource, EmbedSessionsResource, ExtractionsResource, InvalidRequestError, JobsResource, LoansResource, NetworkError, NotFoundError, PermissionError, RateLimitError, SDK_VERSION, ServerError, SpreadSpaceClient, SpreadSpaceError, WebhookSignatureError, WebhooksResource, verifyAndParseWebhook, verifyWebhookSignature };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map