@spreadspace/sdk 0.1.0

package/dist/webhooks.d.cts

@@ -0,0 +1,156 @@
+/**
+ * Webhook signature verification + typed event envelopes.
+ *
+ * Byte-for-byte compatible with the server signer `api/src/Webhooks/WebhookSigner.cs`.
+ * Wire format mirrors Stripe's `Stripe-Signature`:
+ *
+ *   SpreadSpace-Signature: t=<unix_seconds>,v1=<hex_hmac_sha256(secret, "{t}.{body}")>
+ *
+ * The verifier:
+ *   1. Parses `t=` and `v1=` tokens (tolerant of extra/reordered/unknown pairs to
+ *      stay forward-compatible with future schemes).
+ *   2. Recomputes HMAC-SHA256 over `"{timestamp}.{rawBody}"` with the secret.
+ *   3. Compares with `crypto.timingSafeEqual` on decoded bytes — never on hex
+ *      strings (`===` short-circuits and leaks prefix info via timing).
+ *   4. Two-sided freshness check: rejects timestamps too far in the past (replay
+ *      protection) AND too far in the future (attacker-controlled skew).
+ *
+ * Verification order matches the C# side: HMAC FIRST, then freshness. That way a
+ * forged-but-fresh request and a real-but-stale request fail indistinguishably.
+ *
+ * Tree-shakeable: importable as `@spreadspace/sdk/webhooks` so a webhook-receiver
+ * Lambda pulls in only the verifier, not the whole client + resource tree.
+ */
+/**
+ * Canonical webhook event-type identifier strings. Stable wire constants stored
+ * verbatim in the envelope `type` field. `*` is a subscription wildcard, never
+ * an emitted `type`, so it is deliberately excluded from this union.
+ */
+type WebhookEventType = 'document.processed' | 'document.failed' | 'extraction.ready' | 'job.completed' | 'loan.classified';
+/** `document.processed` payload. `extraction_id === document_id` if an extraction phase ran, `null` if classified-only. */
+interface DocumentProcessedPayload {
+    document_id: string;
+    job_id: string;
+    borrower_id: string;
+    loan_id: string;
+    document_type: string;
+    processed_at: string;
+    extraction_id?: string | null;
+}
+/** `document.failed` payload. `reason` mirrors `ExtractedDocument.ErrorMessage`. */
+interface DocumentFailedPayload {
+    document_id: string;
+    job_id: string;
+    borrower_id: string;
+    loan_id: string;
+    reason: string;
+    failed_at: string;
+}
+/** `extraction.ready` payload. Fired once per doc when extracted line items become queryable. */
+interface ExtractionReadyPayload {
+    extraction_id: string;
+    document_id: string;
+    job_id: string;
+    borrower_id: string;
+    loan_id: string;
+    document_type: string;
+    ready_at: string;
+}
+/** `job.completed` payload. Terminal package event, fired once every doc reaches a terminal state. */
+interface JobCompletedPayload {
+    job_id: string;
+    borrower_id: string;
+    loan_id: string;
+    document_count_total: number;
+    document_count_succeeded: number;
+    document_count_failed: number;
+    completed_at: string;
+}
+/** `loan.classified` payload. Fired once per loan after the classification cascade finishes. */
+interface LoanClassifiedPayload {
+    loan_id: string;
+    borrower_id: string;
+    job_id: string;
+    document_count: number;
+    classified_at: string;
+}
+/**
+ * Common envelope fields wrapping every event (the bytes that are signed).
+ * Property order is pinned server-side via `JsonPropertyOrder`; the signature is
+ * over the raw byte stream, so order is immaterial to the verifier but the
+ * fields are documented here for completeness. `livemode` is `false` for the
+ * sandbox simulator, `true` otherwise.
+ */
+interface WebhookEnvelopeBase {
+    id: string;
+    created: number;
+    tenant_id: string;
+    livemode: boolean;
+}
+/**
+ * Discriminated union over the five canonical webhook events. Switch on `type`
+ * to narrow `data` to the matching payload.
+ */
+type WebhookEvent = (WebhookEnvelopeBase & {
+    type: 'document.processed';
+    data: DocumentProcessedPayload;
+}) | (WebhookEnvelopeBase & {
+    type: 'document.failed';
+    data: DocumentFailedPayload;
+}) | (WebhookEnvelopeBase & {
+    type: 'extraction.ready';
+    data: ExtractionReadyPayload;
+}) | (WebhookEnvelopeBase & {
+    type: 'job.completed';
+    data: JobCompletedPayload;
+}) | (WebhookEnvelopeBase & {
+    type: 'loan.classified';
+    data: LoanClassifiedPayload;
+});
+/** Parsed envelope returned by {@link verifyAndParseWebhook}, narrowed on `type`. */
+type VerifyAndParseResult = WebhookEvent;
+/** Options for {@link verifyWebhook} / {@link verifyAndParseWebhook}. */
+interface VerifyWebhookOptions {
+    /**
+     * Maximum age (and maximum future skew) of the timestamp before rejection.
+     * Symmetric — `Math.abs(now - t)` must be ≤ this value. Default 300 seconds.
+     */
+    freshnessTolerance?: number;
+    /**
+     * Override the "current time" (unix seconds) used for the freshness check.
+     * Useful in tests; otherwise leave undefined and the verifier reads
+     * `Date.now() / 1000`.
+     */
+    currentTimestamp?: number;
+}
+/**
+ * Thrown when a webhook signature fails verification or the envelope is
+ * structurally malformed. Self-contained — distinct from `SpreadSpaceError`
+ * because verifiers don't need the full request/response error machinery.
+ */
+declare class WebhookSignatureError extends Error {
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+/**
+ * Verify a `SpreadSpace-Signature` header against a body and signing secret.
+ * Throws {@link WebhookSignatureError} on any failure (malformed header, bad
+ * HMAC, stale timestamp, wrong secret); returns `true` on success.
+ *
+ * @param rawBody  The exact bytes received on the wire — NOT re-serialized JSON.
+ *   Any byte-level transformation (re-stringify, gzip decode, encoding change)
+ *   invalidates the signature.
+ * @param signature  Contents of the `SpreadSpace-Signature` HTTP header.
+ * @param secret  The plaintext signing secret (`whsec_...`). Never log this.
+ * @param options  Optional freshness window + clock injection.
+ */
+declare function verifyWebhook(rawBody: string | Buffer | Uint8Array, signature: string, secret: string, options?: VerifyWebhookOptions): true;
+/**
+ * Verify a webhook signature and JSON-parse the body into a typed
+ * {@link WebhookEvent} envelope. Throws {@link WebhookSignatureError} on
+ * signature failure or invalid JSON. Switch on `event.type` to narrow
+ * `event.data` to the matching payload.
+ */
+declare function verifyAndParseWebhook(rawBody: string | Buffer | Uint8Array, signature: string, secret: string, options?: VerifyWebhookOptions): VerifyAndParseResult;
+
+export { type DocumentFailedPayload, type DocumentProcessedPayload, type ExtractionReadyPayload, type JobCompletedPayload, type LoanClassifiedPayload, type VerifyAndParseResult, type VerifyWebhookOptions, type WebhookEvent, type WebhookEventType, WebhookSignatureError, verifyAndParseWebhook, verifyWebhook };

package/dist/webhooks.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Webhook signature verification + typed event envelopes.
+ *
+ * Byte-for-byte compatible with the server signer `api/src/Webhooks/WebhookSigner.cs`.
+ * Wire format mirrors Stripe's `Stripe-Signature`:
+ *
+ *   SpreadSpace-Signature: t=<unix_seconds>,v1=<hex_hmac_sha256(secret, "{t}.{body}")>
+ *
+ * The verifier:
+ *   1. Parses `t=` and `v1=` tokens (tolerant of extra/reordered/unknown pairs to
+ *      stay forward-compatible with future schemes).
+ *   2. Recomputes HMAC-SHA256 over `"{timestamp}.{rawBody}"` with the secret.
+ *   3. Compares with `crypto.timingSafeEqual` on decoded bytes — never on hex
+ *      strings (`===` short-circuits and leaks prefix info via timing).
+ *   4. Two-sided freshness check: rejects timestamps too far in the past (replay
+ *      protection) AND too far in the future (attacker-controlled skew).
+ *
+ * Verification order matches the C# side: HMAC FIRST, then freshness. That way a
+ * forged-but-fresh request and a real-but-stale request fail indistinguishably.
+ *
+ * Tree-shakeable: importable as `@spreadspace/sdk/webhooks` so a webhook-receiver
+ * Lambda pulls in only the verifier, not the whole client + resource tree.
+ */
+/**
+ * Canonical webhook event-type identifier strings. Stable wire constants stored
+ * verbatim in the envelope `type` field. `*` is a subscription wildcard, never
+ * an emitted `type`, so it is deliberately excluded from this union.
+ */
+type WebhookEventType = 'document.processed' | 'document.failed' | 'extraction.ready' | 'job.completed' | 'loan.classified';
+/** `document.processed` payload. `extraction_id === document_id` if an extraction phase ran, `null` if classified-only. */
+interface DocumentProcessedPayload {
+    document_id: string;
+    job_id: string;
+    borrower_id: string;
+    loan_id: string;
+    document_type: string;
+    processed_at: string;
+    extraction_id?: string | null;
+}
+/** `document.failed` payload. `reason` mirrors `ExtractedDocument.ErrorMessage`. */
+interface DocumentFailedPayload {
+    document_id: string;
+    job_id: string;
+    borrower_id: string;
+    loan_id: string;
+    reason: string;
+    failed_at: string;
+}
+/** `extraction.ready` payload. Fired once per doc when extracted line items become queryable. */
+interface ExtractionReadyPayload {
+    extraction_id: string;
+    document_id: string;
+    job_id: string;
+    borrower_id: string;
+    loan_id: string;
+    document_type: string;
+    ready_at: string;
+}
+/** `job.completed` payload. Terminal package event, fired once every doc reaches a terminal state. */
+interface JobCompletedPayload {
+    job_id: string;
+    borrower_id: string;
+    loan_id: string;
+    document_count_total: number;
+    document_count_succeeded: number;
+    document_count_failed: number;
+    completed_at: string;
+}
+/** `loan.classified` payload. Fired once per loan after the classification cascade finishes. */
+interface LoanClassifiedPayload {
+    loan_id: string;
+    borrower_id: string;
+    job_id: string;
+    document_count: number;
+    classified_at: string;
+}
+/**
+ * Common envelope fields wrapping every event (the bytes that are signed).
+ * Property order is pinned server-side via `JsonPropertyOrder`; the signature is
+ * over the raw byte stream, so order is immaterial to the verifier but the
+ * fields are documented here for completeness. `livemode` is `false` for the
+ * sandbox simulator, `true` otherwise.
+ */
+interface WebhookEnvelopeBase {
+    id: string;
+    created: number;
+    tenant_id: string;
+    livemode: boolean;
+}
+/**
+ * Discriminated union over the five canonical webhook events. Switch on `type`
+ * to narrow `data` to the matching payload.
+ */
+type WebhookEvent = (WebhookEnvelopeBase & {
+    type: 'document.processed';
+    data: DocumentProcessedPayload;
+}) | (WebhookEnvelopeBase & {
+    type: 'document.failed';
+    data: DocumentFailedPayload;
+}) | (WebhookEnvelopeBase & {
+    type: 'extraction.ready';
+    data: ExtractionReadyPayload;
+}) | (WebhookEnvelopeBase & {
+    type: 'job.completed';
+    data: JobCompletedPayload;
+}) | (WebhookEnvelopeBase & {
+    type: 'loan.classified';
+    data: LoanClassifiedPayload;
+});
+/** Parsed envelope returned by {@link verifyAndParseWebhook}, narrowed on `type`. */
+type VerifyAndParseResult = WebhookEvent;
+/** Options for {@link verifyWebhook} / {@link verifyAndParseWebhook}. */
+interface VerifyWebhookOptions {
+    /**
+     * Maximum age (and maximum future skew) of the timestamp before rejection.
+     * Symmetric — `Math.abs(now - t)` must be ≤ this value. Default 300 seconds.
+     */
+    freshnessTolerance?: number;
+    /**
+     * Override the "current time" (unix seconds) used for the freshness check.
+     * Useful in tests; otherwise leave undefined and the verifier reads
+     * `Date.now() / 1000`.
+     */
+    currentTimestamp?: number;
+}
+/**
+ * Thrown when a webhook signature fails verification or the envelope is
+ * structurally malformed. Self-contained — distinct from `SpreadSpaceError`
+ * because verifiers don't need the full request/response error machinery.
+ */
+declare class WebhookSignatureError extends Error {
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+/**
+ * Verify a `SpreadSpace-Signature` header against a body and signing secret.
+ * Throws {@link WebhookSignatureError} on any failure (malformed header, bad
+ * HMAC, stale timestamp, wrong secret); returns `true` on success.
+ *
+ * @param rawBody  The exact bytes received on the wire — NOT re-serialized JSON.
+ *   Any byte-level transformation (re-stringify, gzip decode, encoding change)
+ *   invalidates the signature.
+ * @param signature  Contents of the `SpreadSpace-Signature` HTTP header.
+ * @param secret  The plaintext signing secret (`whsec_...`). Never log this.
+ * @param options  Optional freshness window + clock injection.
+ */
+declare function verifyWebhook(rawBody: string | Buffer | Uint8Array, signature: string, secret: string, options?: VerifyWebhookOptions): true;
+/**
+ * Verify a webhook signature and JSON-parse the body into a typed
+ * {@link WebhookEvent} envelope. Throws {@link WebhookSignatureError} on
+ * signature failure or invalid JSON. Switch on `event.type` to narrow
+ * `event.data` to the matching payload.
+ */
+declare function verifyAndParseWebhook(rawBody: string | Buffer | Uint8Array, signature: string, secret: string, options?: VerifyWebhookOptions): VerifyAndParseResult;
+
+export { type DocumentFailedPayload, type DocumentProcessedPayload, type ExtractionReadyPayload, type JobCompletedPayload, type LoanClassifiedPayload, type VerifyAndParseResult, type VerifyWebhookOptions, type WebhookEvent, type WebhookEventType, WebhookSignatureError, verifyAndParseWebhook, verifyWebhook };

package/dist/webhooks.js

@@ -0,0 +1,11 @@
+import {
+  WebhookSignatureError,
+  verifyAndParseWebhook,
+  verifyWebhook
+} from "./chunk-2JW6MGIK.js";
+export {
+  WebhookSignatureError,
+  verifyAndParseWebhook,
+  verifyWebhook
+};
+//# sourceMappingURL=webhooks.js.map

package/dist/webhooks.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@spreadspace/sdk",
+  "version": "0.1.0",
+  "description": "Official TypeScript SDK for the SpreadSpace API.",
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./webhooks": {
+      "types": "./dist/webhooks.d.ts",
+      "import": "./dist/webhooks.js",
+      "require": "./dist/webhooks.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint \"src/**/*.ts\" \"test/**/*.ts\""
+  },
+  "dependencies": {
+    "decimal.js": "10.6.0",
+    "lossless-json": "4.3.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.5",
+    "@typescript-eslint/eslint-plugin": "^8.59.3",
+    "@typescript-eslint/parser": "^8.59.3",
+    "eslint": "^10.4.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.5"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "spreadspace",
+    "api",
+    "sdk",
+    "typescript",
+    "lending",
+    "documents"
+  ]
+}