@spreadspace/sdk 0.1.0

package/README.md

@@ -0,0 +1,197 @@
+# SpreadSpace TypeScript SDK
+
+Official TypeScript SDK for the [SpreadSpace](https://spreadspace.ai) API —
+document ingestion, extraction, and spreads for lending workflows.
+
+- Typed error hierarchy, automatic retries with backoff, and idempotency.
+- Cursor pagination as a native `for await ... of` async iterable.
+- First-class helpers for the async-operation (export) and document-upload flows.
+- ESM + CommonJS, full type declarations, zero runtime dependencies.
+
+Node `>= 18` (uses the platform `fetch` and Web Crypto).
+
+## Install
+
+```bash
+npm i @spreadspace/sdk
+```
+
+> Building **from source**? The typed request/response substrate is generated
+> from the public OpenAPI spec into `src/generated/` (gitignored). Run
+> `bash scripts/generate.sh` once before `npm run build` / `tsc`. Consuming the
+> published package needs none of that — `dist/` is shipped prebuilt.
+
+## Quickstart
+
+```ts
+import { SpreadSpace } from '@spreadspace/sdk';
+
+// ss_test_ -> isolated sandbox tenant; ss_live_ -> real workspace data. Same
+// base URL. You can also set SPREADSPACE_API_KEY and call `new SpreadSpace()`.
+const client = new SpreadSpace({ apiKey: 'ss_test_...' });
+```
+
+### List borrowers (auto-paged)
+
+List methods return a lazy async iterable that fetches pages on demand and stops
+when the cursor is exhausted (`next_cursor === null`). There is no `has_more` or
+`total` — just iterate.
+
+```ts
+for await (const borrower of client.borrowers.list()) {
+  console.log(borrower.id);
+}
+
+// Filters + page size:
+for await (const b of client.borrowers.list({ intake: true, limit: 50 })) { /* ... */ }
+
+// Loans (optionally scoped to a borrower) and jobs iterate the same way:
+for await (const loan of client.loans.list({ borrowerId: 'abc123' })) { /* ... */ }
+for await (const job of client.jobs.list()) { /* ... */ }
+```
+
+Each `list()` is generic — pass your own row type: `client.borrowers.list<Borrower>()`.
+
+### Create an extraction export and wait for it
+
+Long-running work is an **async operation**: `create()` enqueues it and resolves
+to a handle; `wait()` polls to a terminal status. Terminal states are
+`succeeded` / `failed` / `cancelled` (note the double-L). A `failed` operation
+rejects with `AsyncOperationError` carrying `errorCode` / `errorMessage`.
+
+```ts
+const operation = await client.exports.create({ borrowerId: 'abc123', format: 'xlsx' });
+
+// Poll until terminal. Rejects with AsyncOperationError on "failed",
+// AsyncOperationTimeout if it doesn't finish in time.
+const op = await operation.wait({ timeoutMs: 5 * 60_000 });
+
+console.log(op.status);    // 'succeeded'
+console.log(op.resultUrl); // download link, when present
+
+// Cancel a still-running operation (cancelling a terminal op rejects with
+// ConflictError; cancelling an already-cancelled op is an idempotent success):
+await client.asyncOperations.cancel(op.operationId);
+```
+
+### Upload a document and wait for processing
+
+Upload is a three-step dance the helper handles for you: mint a presigned URL,
+`PUT` the bytes straight to S3, then confirm. Raw bytes never transit a
+SpreadSpace endpoint body. `file` may be a path string, raw bytes, a `Blob` /
+`File`, or a `Readable` / iterable of chunks.
+
+```ts
+// wait: true also polls to a terminal job status before resolving.
+const job = await client.documents.upload('./statement.pdf', {
+  borrowerId: 'abc123',
+  wait: true,
+});
+
+console.log(job.id);
+
+// From bytes / a Blob — fileName + contentType are required there:
+await client.documents.upload(bytes, {
+  fileName: 'statement.pdf',
+  contentType: 'application/pdf',
+});
+
+// Poll a job's status yourself:
+const status = await client.documents.status(job.id);
+```
+
+Terminal **job** statuses are `COMPLETED` / `FAILED`; `PENDING` / `PROCESSING`
+are in flight. A `FAILED` job rejects `wait()` with `UploadError`. (`REJECTED`
+is a per-*document* outcome, not a job status — a failed job is what surfaces as
+"rejected" in the UI.)
+
+> If billing is inactive, minting the presigned URL returns **402** and the SDK
+> throws (rather than hanging) so you see the billing wall immediately.
+
+## Errors
+
+Every API error maps to a typed error. Match on the class; for the stable machine
+code read `err.type` (the wire `error.type`), never the message. Each error
+carries `requestId` (preferred from the `X-Request-ID` response header) — quote
+it in support tickets.
+
+| Error | HTTP |
+|---|---|
+| `InvalidRequestError` | 400 |
+| `AuthenticationError` | 401 |
+| `PermissionError` | 403 |
+| `NotFoundError` | 404 |
+| `ConflictError` | 409 |
+| `RateLimitError` | 429 (honors `Retry-After`) |
+| `ServerError` | 5xx |
+| `NetworkError` | transport failure (no HTTP response) |
+
+The HTTP-status errors derive from `SpreadSpaceError`.
+
+```ts
+import { RateLimitError, SpreadSpaceError } from '@spreadspace/sdk';
+
+try {
+  for await (const b of client.borrowers.list()) { /* ... */ }
+} catch (err) {
+  if (err instanceof RateLimitError) {
+    console.log(`rate limited; retry after ${err.retryAfter}s (request ${err.requestId})`);
+  } else if (err instanceof SpreadSpaceError) {
+    console.log(`${err.type}: ${err.message} (request ${err.requestId})`);
+  }
+}
+```
+
+`429` and `5xx` (and transport errors) are retried automatically with exponential
+backoff + full jitter, honoring `Retry-After`. Other `4xx` are never retried.
+Tune with `maxRetries` in the constructor.
+
+## Idempotency
+
+Non-`GET` requests automatically get a generated `Idempotency-Key` (a UUID).
+Supply your own (via the request options on the low-level `request()` escape
+hatch) to safely retry a specific call across restarts, or pass `null` to
+suppress it.
+
+## Pinning the API version
+
+Every request sends a `SpreadSpace-Version` header. The SDK pins a known-good
+default (`DEFAULT_API_VERSION`); override it globally with `apiVersion` in the
+constructor, or per call via the `apiVersion` option on `list()` and the helpers.
+
+```ts
+const client = new SpreadSpace({
+  apiKey: 'ss_test_...',
+  apiVersion: '2026-05-03',
+  maxRetries: 4,
+});
+```
+
+## ⚠️ Money is a `number` (not exact — read this)
+
+Monetary amounts decode to a plain JavaScript `number` (IEEE-754 float64).
+**TypeScript has no decimal type**, so very large amounts or sub-cent arithmetic
+can lose precision — do **not** treat these values as exact decimals, and do not
+sum many of them naively where cents must reconcile.
+
+This is a deliberate, temporary stance: the wire currently encodes money as a
+JSON number. A future API change will move money to a **decimal string** for
+lossless transport; that will be a coordinated, breaking change and this SDK will
+adopt it then. For exact arithmetic today, read the raw string from the response
+body yourself, or defer the math to the server-side spread/export. (The .NET SDK
+decodes money as `System.Decimal` and *is* exact — this caveat is TS-specific.)
+
+## Escape hatch
+
+For any endpoint the resource helpers don't wrap, call the raw transport. It
+applies all the cross-cutting behavior (auth, version header, retries,
+idempotency, error mapping) and resolves to the decoded body (or `undefined` on a
+204):
+
+```ts
+const body = await client.request('GET', '/api/some/endpoint');
+```
+
+## License
+
+MIT

package/dist/chunk-2JW6MGIK.js

@@ -0,0 +1,139 @@
+// src/webhooks.ts
+import { createHmac, timingSafeEqual } from "crypto";
+var DEFAULT_FRESHNESS_TOLERANCE_SECONDS = 5 * 60;
+var VERSION_1_PREFIX = "v1";
+var WebhookSignatureError = class _WebhookSignatureError extends Error {
+  cause;
+  constructor(message, cause) {
+    super(message);
+    this.name = "WebhookSignatureError";
+    this.cause = cause;
+    Object.setPrototypeOf(this, _WebhookSignatureError.prototype);
+  }
+};
+function verifyWebhook(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) {
+  verifyWebhook(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;
+}
+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);
+}
+
+export {
+  WebhookSignatureError,
+  verifyWebhook,
+  verifyAndParseWebhook
+};
+//# sourceMappingURL=chunk-2JW6MGIK.js.map

package/dist/chunk-2JW6MGIK.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/webhooks.ts"],"sourcesContent":["/**\n * Webhook signature verification + typed event envelopes.\n *\n * Byte-for-byte compatible with the server signer `api/src/Webhooks/WebhookSigner.cs`.\n * Wire format mirrors Stripe's `Stripe-Signature`:\n *\n *   SpreadSpace-Signature: t=<unix_seconds>,v1=<hex_hmac_sha256(secret, \"{t}.{body}\")>\n *\n * The verifier:\n *   1. Parses `t=` and `v1=` tokens (tolerant of extra/reordered/unknown pairs to\n *      stay forward-compatible with future schemes).\n *   2. Recomputes HMAC-SHA256 over `\"{timestamp}.{rawBody}\"` with the secret.\n *   3. Compares with `crypto.timingSafeEqual` on decoded bytes — never on hex\n *      strings (`===` short-circuits and leaks prefix info via timing).\n *   4. Two-sided freshness check: rejects timestamps too far in the past (replay\n *      protection) AND too far in the future (attacker-controlled skew).\n *\n * Verification order matches the C# side: HMAC FIRST, then freshness. That way a\n * forged-but-fresh request and a real-but-stale request fail indistinguishably.\n *\n * Tree-shakeable: importable as `@spreadspace/sdk/webhooks` so a webhook-receiver\n * Lambda pulls in only the verifier, not the whole client + resource tree.\n */\n\nimport { createHmac, timingSafeEqual } from 'node:crypto';\n\n/** Default freshness tolerance — matches `WebhookSignatureFormat.DefaultFreshnessTolerance` (300s). */\nconst DEFAULT_FRESHNESS_TOLERANCE_SECONDS = 5 * 60;\n\n/** Wire constant for the v1 HMAC-SHA256 scheme. */\nconst VERSION_1_PREFIX = 'v1';\n\n// ────────────────────────────────────────────────────────────────────────────\n// Webhook event types — discriminated union over the five canonical events.\n//\n// Mirror the C# payload records under `api/src/Webhooks/Events/`. Field names\n// are the exact wire keys (snake_case).\n// ────────────────────────────────────────────────────────────────────────────\n\n/**\n * Canonical webhook event-type identifier strings. Stable wire constants stored\n * verbatim in the envelope `type` field. `*` is a subscription wildcard, never\n * an emitted `type`, so it is deliberately excluded from this union.\n */\nexport type WebhookEventType =\n  | 'document.processed'\n  | 'document.failed'\n  | 'extraction.ready'\n  | 'job.completed'\n  | 'loan.classified';\n\n/** `document.processed` payload. `extraction_id === document_id` if an extraction phase ran, `null` if classified-only. */\nexport interface DocumentProcessedPayload {\n  document_id: string;\n  job_id: string;\n  borrower_id: string;\n  loan_id: string;\n  document_type: string;\n  processed_at: string;\n  extraction_id?: string | null;\n}\n\n/** `document.failed` payload. `reason` mirrors `ExtractedDocument.ErrorMessage`. */\nexport interface DocumentFailedPayload {\n  document_id: string;\n  job_id: string;\n  borrower_id: string;\n  loan_id: string;\n  reason: string;\n  failed_at: string;\n}\n\n/** `extraction.ready` payload. Fired once per doc when extracted line items become queryable. */\nexport interface ExtractionReadyPayload {\n  extraction_id: string;\n  document_id: string;\n  job_id: string;\n  borrower_id: string;\n  loan_id: string;\n  document_type: string;\n  ready_at: string;\n}\n\n/** `job.completed` payload. Terminal package event, fired once every doc reaches a terminal state. */\nexport interface JobCompletedPayload {\n  job_id: string;\n  borrower_id: string;\n  loan_id: string;\n  document_count_total: number;\n  document_count_succeeded: number;\n  document_count_failed: number;\n  completed_at: string;\n}\n\n/** `loan.classified` payload. Fired once per loan after the classification cascade finishes. */\nexport interface LoanClassifiedPayload {\n  loan_id: string;\n  borrower_id: string;\n  job_id: string;\n  document_count: number;\n  classified_at: string;\n}\n\n/**\n * Common envelope fields wrapping every event (the bytes that are signed).\n * Property order is pinned server-side via `JsonPropertyOrder`; the signature is\n * over the raw byte stream, so order is immaterial to the verifier but the\n * fields are documented here for completeness. `livemode` is `false` for the\n * sandbox simulator, `true` otherwise.\n */\ninterface WebhookEnvelopeBase {\n  id: string;\n  created: number;\n  tenant_id: string;\n  livemode: boolean;\n}\n\n/**\n * Discriminated union over the five canonical webhook events. Switch on `type`\n * to narrow `data` to the matching payload.\n */\nexport type WebhookEvent =\n  | (WebhookEnvelopeBase & { type: 'document.processed'; data: DocumentProcessedPayload })\n  | (WebhookEnvelopeBase & { type: 'document.failed'; data: DocumentFailedPayload })\n  | (WebhookEnvelopeBase & { type: 'extraction.ready'; data: ExtractionReadyPayload })\n  | (WebhookEnvelopeBase & { type: 'job.completed'; data: JobCompletedPayload })\n  | (WebhookEnvelopeBase & { type: 'loan.classified'; data: LoanClassifiedPayload });\n\n/** Parsed envelope returned by {@link verifyAndParseWebhook}, narrowed on `type`. */\nexport type VerifyAndParseResult = WebhookEvent;\n\n/** Options for {@link verifyWebhook} / {@link verifyAndParseWebhook}. */\nexport interface VerifyWebhookOptions {\n  /**\n   * Maximum age (and maximum future skew) of the timestamp before rejection.\n   * Symmetric — `Math.abs(now - t)` must be ≤ this value. Default 300 seconds.\n   */\n  freshnessTolerance?: number;\n\n  /**\n   * Override the \"current time\" (unix seconds) used for the freshness check.\n   * Useful in tests; otherwise leave undefined and the verifier reads\n   * `Date.now() / 1000`.\n   */\n  currentTimestamp?: number;\n}\n\n/**\n * Thrown when a webhook signature fails verification or the envelope is\n * structurally malformed. Self-contained — distinct from `SpreadSpaceError`\n * because verifiers don't need the full request/response error machinery.\n */\nexport class WebhookSignatureError extends Error {\n  public readonly cause?: unknown;\n\n  constructor(message: string, cause?: unknown) {\n    super(message);\n    this.name = 'WebhookSignatureError';\n    this.cause = cause;\n    Object.setPrototypeOf(this, WebhookSignatureError.prototype);\n  }\n}\n\n/**\n * Verify a `SpreadSpace-Signature` header against a body and signing secret.\n * Throws {@link WebhookSignatureError} on any failure (malformed header, bad\n * HMAC, stale timestamp, wrong secret); returns `true` on success.\n *\n * @param rawBody  The exact bytes received on the wire — NOT re-serialized JSON.\n *   Any byte-level transformation (re-stringify, gzip decode, encoding change)\n *   invalidates the signature.\n * @param signature  Contents of the `SpreadSpace-Signature` HTTP header.\n * @param secret  The plaintext signing secret (`whsec_...`). Never log this.\n * @param options  Optional freshness window + clock injection.\n */\nexport function verifyWebhook(\n  rawBody: string | Buffer | Uint8Array,\n  signature: string,\n  secret: string,\n  options?: VerifyWebhookOptions,\n): true {\n  if (typeof signature !== 'string' || signature.length === 0) {\n    throw new WebhookSignatureError('SpreadSpace-Signature header is missing or empty.');\n  }\n  if (typeof secret !== 'string' || secret.length === 0) {\n    throw new WebhookSignatureError('Webhook signing secret is missing or empty.');\n  }\n  if (rawBody === null || rawBody === undefined) {\n    throw new WebhookSignatureError('Webhook raw body is missing.');\n  }\n\n  const parsed = parseSignatureHeader(signature);\n  if (!parsed) {\n    throw new WebhookSignatureError('Webhook signature header is malformed.');\n  }\n  const { timestamp, hex } = parsed;\n\n  // HMAC FIRST. Never leak (via timing or distinct error text) whether a request\n  // was a forged signature vs. a real one that aged out — both fail the same way.\n  const bodyString = bodyToString(rawBody);\n  const expectedHex = computeHmacHex(secret, `${timestamp}.${bodyString}`);\n\n  if (!hexEquals(expectedHex, hex)) {\n    throw new WebhookSignatureError('Webhook signature does not match.');\n  }\n\n  // Then freshness. Two-sided: too old OR too far in the future.\n  const tolerance = options?.freshnessTolerance ?? DEFAULT_FRESHNESS_TOLERANCE_SECONDS;\n  const now = options?.currentTimestamp ?? Math.floor(Date.now() / 1000);\n  const age = now - timestamp;\n  if (age > tolerance || age < -tolerance) {\n    throw new WebhookSignatureError(\n      `Webhook timestamp is outside the freshness window of ${tolerance}s.`,\n    );\n  }\n\n  return true;\n}\n\n/**\n * Verify a webhook signature and JSON-parse the body into a typed\n * {@link WebhookEvent} envelope. Throws {@link WebhookSignatureError} on\n * signature failure or invalid JSON. Switch on `event.type` to narrow\n * `event.data` to the matching payload.\n */\nexport function verifyAndParseWebhook(\n  rawBody: string | Buffer | Uint8Array,\n  signature: string,\n  secret: string,\n  options?: VerifyWebhookOptions,\n): VerifyAndParseResult {\n  verifyWebhook(rawBody, signature, secret, options);\n\n  const bodyString = bodyToString(rawBody);\n\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(bodyString);\n  } catch (cause) {\n    throw new WebhookSignatureError('Webhook body is not valid JSON.', cause);\n  }\n\n  if (!isPlainObject(parsed)) {\n    throw new WebhookSignatureError('Webhook body is not a JSON object.');\n  }\n  const candidate = parsed;\n  if (typeof candidate.type !== 'string' || candidate.type.length === 0) {\n    throw new WebhookSignatureError('Webhook body is missing a `type` field.');\n  }\n  if (typeof candidate.id !== 'string' || candidate.id.length === 0) {\n    throw new WebhookSignatureError('Webhook body is missing an `id` field.');\n  }\n  if (typeof candidate.created !== 'number') {\n    throw new WebhookSignatureError('Webhook body is missing a numeric `created` field.');\n  }\n  if (typeof candidate.tenant_id !== 'string' || candidate.tenant_id.length === 0) {\n    throw new WebhookSignatureError('Webhook body is missing a `tenant_id` field.');\n  }\n  if (!isPlainObject(candidate.data)) {\n    throw new WebhookSignatureError('Webhook body is missing a `data` object.');\n  }\n\n  return parsed as unknown as VerifyAndParseResult;\n}\n\n// ────────────────────────────────────────────────────────────────────────────\n// Internals\n// ────────────────────────────────────────────────────────────────────────────\n\ninterface ParsedSignature {\n  timestamp: number;\n  hex: string;\n}\n\n/**\n * Parse a header in the form `t=<long>,v1=<hex>`. Tolerant of whitespace between\n * segments and of additional unrecognized pairs (e.g. a future `v2=...`) — those\n * are silently ignored, keeping the verifier forward-compatible. Duplicate `t=`\n * or `v1=`, an empty value, a missing `=`, or fewer than two segments → reject.\n */\nfunction parseSignatureHeader(header: string): ParsedSignature | null {\n  const segments = header.split(',').filter((s) => s.length > 0);\n  if (segments.length < 2) return null;\n\n  let parsedTs: number | null = null;\n  let parsedV1: string | null = null;\n\n  for (const raw of segments) {\n    const segment = raw.trim();\n    const eq = segment.indexOf('=');\n    if (eq <= 0 || eq === segment.length - 1) {\n      // Missing key, missing value, or `=` at the very end (`v1=`).\n      return null;\n    }\n\n    const key = segment.slice(0, eq).trim();\n    const value = segment.slice(eq + 1).trim();\n\n    if (key === 't') {\n      if (parsedTs !== null) return null; // Duplicate `t=`.\n      // Strict integer parse — reject `1.5`, `1e3`, leading `+`, etc. The C#\n      // verifier uses `long.TryParse(NumberStyles.Integer, Invariant)`, which\n      // accepts an optional leading `-` and digits only. Mirror that.\n      if (!/^-?\\d+$/.test(value)) return null;\n      const ts = Number(value);\n      if (!Number.isFinite(ts) || !Number.isInteger(ts)) return null;\n      parsedTs = ts;\n    } else if (key === VERSION_1_PREFIX) {\n      if (parsedV1 !== null) return null; // Duplicate `v1=`.\n      if (value.length === 0) return null;\n      parsedV1 = value;\n    }\n    // Any other key — silently ignored for forward compatibility.\n  }\n\n  if (parsedTs === null || parsedV1 === null) return null;\n  return { timestamp: parsedTs, hex: parsedV1 };\n}\n\n/**\n * Compute lowercase hex HMAC-SHA256 digest. Matches the C# side's\n * `Convert.ToHexStringLower(hmac.ComputeHash(...))` exactly — both UTF-8 encode\n * the key and message.\n */\nfunction computeHmacHex(secret: string, signedPayload: string): string {\n  const hmac = createHmac('sha256', Buffer.from(secret, 'utf-8'));\n  hmac.update(Buffer.from(signedPayload, 'utf-8'));\n  return hmac.digest('hex'); // Node default is lowercase.\n}\n\n/**\n * Constant-time compare of two hex strings. Decode both sides to bytes before\n * `timingSafeEqual` (it requires equal-length inputs). A length mismatch fails\n * fast — length is public (SHA-256 emits 64 hex chars), not timing-sensitive.\n */\nfunction hexEquals(expectedHex: string, providedHex: string): boolean {\n  if (expectedHex.length !== providedHex.length) return false;\n\n  let expectedBytes: Buffer;\n  let providedBytes: Buffer;\n  try {\n    expectedBytes = Buffer.from(expectedHex, 'hex');\n    providedBytes = Buffer.from(providedHex, 'hex');\n  } catch {\n    return false;\n  }\n\n  // `Buffer.from(..., 'hex')` silently stops at the first non-hex character,\n  // producing a shorter buffer — guard explicitly so invalid hex that truncates\n  // to a matching length can't produce a false equality.\n  if (expectedBytes.length !== providedBytes.length) return false;\n  if (expectedBytes.length * 2 !== expectedHex.length) return false;\n  if (providedBytes.length * 2 !== providedHex.length) return false;\n\n  return timingSafeEqual(\n    new Uint8Array(expectedBytes.buffer, expectedBytes.byteOffset, expectedBytes.byteLength),\n    new Uint8Array(providedBytes.buffer, providedBytes.byteOffset, providedBytes.byteLength),\n  );\n}\n\nfunction bodyToString(body: string | Buffer | Uint8Array): string {\n  if (typeof body === 'string') return body;\n  if (Buffer.isBuffer(body)) return body.toString('utf-8');\n  return Buffer.from(body).toString('utf-8');\n}\n\nfunction isPlainObject(v: unknown): v is Record<string, unknown> {\n  return typeof v === 'object' && v !== null && !Array.isArray(v);\n}\n"],"mappings":"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","names":[]}