zkp-sdk-node 0.1.0

package/dist/cjs/index.js

@@ -0,0 +1,39 @@
+"use strict";
+/**
+ * Official Node.js/TypeScript SDK for the ZeroKYC Pay crypto payment gateway.
+ *
+ * Server-side only: API keys and webhook verification must never run in a
+ * browser.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERSION = exports.WebhookVerificationError = exports.NetworkError = exports.APIError = exports.RateLimitError = exports.ValidationError = exports.AuthenticationError = exports.ZeroKYCError = exports.isTerminalStatus = exports.StatusMapper = exports.compareDecimals = exports.ReplayGuard = exports.DEFAULT_TOLERANCE_SECONDS = exports.WebhookVerifier = exports.WebhookEvent = exports.CreateInvoiceResponse = exports.Invoice = exports.DEFAULT_BASE_URL = exports.Config = exports.idempotencyKey = exports.ZeroKYC = void 0;
+var client_js_1 = require("./client.js");
+Object.defineProperty(exports, "ZeroKYC", { enumerable: true, get: function () { return client_js_1.ZeroKYC; } });
+Object.defineProperty(exports, "idempotencyKey", { enumerable: true, get: function () { return client_js_1.idempotencyKey; } });
+var config_js_1 = require("./config.js");
+Object.defineProperty(exports, "Config", { enumerable: true, get: function () { return config_js_1.Config; } });
+Object.defineProperty(exports, "DEFAULT_BASE_URL", { enumerable: true, get: function () { return config_js_1.DEFAULT_BASE_URL; } });
+var invoice_js_1 = require("./models/invoice.js");
+Object.defineProperty(exports, "Invoice", { enumerable: true, get: function () { return invoice_js_1.Invoice; } });
+Object.defineProperty(exports, "CreateInvoiceResponse", { enumerable: true, get: function () { return invoice_js_1.CreateInvoiceResponse; } });
+var webhook_js_1 = require("./models/webhook.js");
+Object.defineProperty(exports, "WebhookEvent", { enumerable: true, get: function () { return webhook_js_1.WebhookEvent; } });
+var verifier_js_1 = require("./webhooks/verifier.js");
+Object.defineProperty(exports, "WebhookVerifier", { enumerable: true, get: function () { return verifier_js_1.WebhookVerifier; } });
+Object.defineProperty(exports, "DEFAULT_TOLERANCE_SECONDS", { enumerable: true, get: function () { return verifier_js_1.DEFAULT_TOLERANCE_SECONDS; } });
+var replay_js_1 = require("./replay.js");
+Object.defineProperty(exports, "ReplayGuard", { enumerable: true, get: function () { return replay_js_1.ReplayGuard; } });
+Object.defineProperty(exports, "compareDecimals", { enumerable: true, get: function () { return replay_js_1.compareDecimals; } });
+var status_js_1 = require("./status.js");
+Object.defineProperty(exports, "StatusMapper", { enumerable: true, get: function () { return status_js_1.StatusMapper; } });
+Object.defineProperty(exports, "isTerminalStatus", { enumerable: true, get: function () { return status_js_1.isTerminalStatus; } });
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "ZeroKYCError", { enumerable: true, get: function () { return errors_js_1.ZeroKYCError; } });
+Object.defineProperty(exports, "AuthenticationError", { enumerable: true, get: function () { return errors_js_1.AuthenticationError; } });
+Object.defineProperty(exports, "ValidationError", { enumerable: true, get: function () { return errors_js_1.ValidationError; } });
+Object.defineProperty(exports, "RateLimitError", { enumerable: true, get: function () { return errors_js_1.RateLimitError; } });
+Object.defineProperty(exports, "APIError", { enumerable: true, get: function () { return errors_js_1.APIError; } });
+Object.defineProperty(exports, "NetworkError", { enumerable: true, get: function () { return errors_js_1.NetworkError; } });
+Object.defineProperty(exports, "WebhookVerificationError", { enumerable: true, get: function () { return errors_js_1.WebhookVerificationError; } });
+var version_js_1 = require("./version.js");
+Object.defineProperty(exports, "VERSION", { enumerable: true, get: function () { return version_js_1.VERSION; } });

package/dist/cjs/invoices.js

@@ -0,0 +1,74 @@
+"use strict";
+/**
+ * Invoice creation options + payload building with local validation.
+ *
+ * Amounts are decimal STRINGS end to end (never JS numbers). Validation
+ * accepts only plain finite positive decimals - the strict ^[0-9]+(\.[0-9]+)?$
+ * grammar (no sign, exponent, NaN/Infinity spellings) with a redundant
+ * finiteness/positivity check, so obvious mistakes never leave the process.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildCreatePayload = buildCreatePayload;
+const errors_js_1 = require("./errors.js");
+/** Plain decimal only: no sign, no exponent, no NaN/Infinity spellings. */
+const AMOUNT_RE = /^[0-9]+(?:\.[0-9]+)?$/;
+function buildCreatePayload(options) {
+    const { amount } = options;
+    if (typeof amount !== "string" || !AMOUNT_RE.test(amount)) {
+        throw new errors_js_1.ValidationError(`amount must be a plain positive decimal string, got ${JSON.stringify(amount)}`);
+    }
+    // belt and suspenders: the regex already rejects NaN/Infinity/0/negatives
+    if (!isFinitePositiveDecimal(amount)) {
+        throw new errors_js_1.ValidationError(`amount must be a positive finite decimal, got ${JSON.stringify(amount)}`);
+    }
+    const currency = options.currency ?? "USD";
+    if (!currency) {
+        throw new errors_js_1.ValidationError("currency must not be empty");
+    }
+    if (options.ttlMinutes !== undefined &&
+        (!Number.isInteger(options.ttlMinutes) ||
+            options.ttlMinutes < 10 || options.ttlMinutes > 4320)) {
+        throw new errors_js_1.ValidationError("ttlMinutes must be an integer between 10 and 4320");
+    }
+    if (options.orderId !== undefined && options.orderId.length > 255) {
+        throw new errors_js_1.ValidationError("orderId must be at most 255 characters");
+    }
+    if (options.description !== undefined && options.description.length > 500) {
+        throw new errors_js_1.ValidationError("description must be at most 500 characters");
+    }
+    if (options.webhookUrl !== undefined && options.webhookUrl.length > 2000) {
+        throw new errors_js_1.ValidationError("webhookUrl must be at most 2000 characters");
+    }
+    if (options.successUrl !== undefined && options.successUrl.length > 2000) {
+        throw new errors_js_1.ValidationError("successUrl must be at most 2000 characters");
+    }
+    const payload = {
+        amount, // stays a string - no float round-trip
+        base_currency: currency,
+        payment_currency: options.paymentCurrency ?? "any",
+    };
+    if (options.orderId !== undefined) {
+        payload.order_id = options.orderId;
+    }
+    if (options.description !== undefined) {
+        payload.description = options.description;
+    }
+    if (options.ttlMinutes !== undefined) {
+        payload.ttl_minutes = options.ttlMinutes;
+    }
+    if (options.webhookUrl !== undefined) {
+        payload.webhook_url = options.webhookUrl;
+    }
+    if (options.successUrl !== undefined) {
+        payload.success_url = options.successUrl;
+    }
+    if (options.metadata && Object.keys(options.metadata).length > 0) {
+        payload.metadata = options.metadata;
+    }
+    return payload;
+}
+/** Rejects "0", "0.000", all-zero decimals; grammar already excludes the rest. */
+function isFinitePositiveDecimal(amount) {
+    const trimmed = amount.replace(/^0+(?=\d)/, "");
+    return !/^0*(\.0+)?$/.test(trimmed);
+}

package/dist/cjs/models/invoice.js

@@ -0,0 +1,189 @@
+"use strict";
+/** Typed invoice models (create + get responses share the shape). */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CreateInvoiceResponse = exports.Invoice = void 0;
+const status_js_1 = require("../status.js");
+class Invoice {
+    id;
+    orderId;
+    description;
+    /** Decimal string - never a JS number. */
+    amount;
+    baseCurrency;
+    paymentCurrency;
+    rawStatus;
+    status;
+    ttlMinutes;
+    expiresAt;
+    createdAt;
+    checkoutUrl;
+    metadata;
+    options;
+    observations;
+    paidAmount;
+    paidAsset;
+    /** Full decoded response (unknown fields preserved). */
+    raw;
+    constructor(data, raw) {
+        this.id = data.id;
+        this.orderId = data.order_id ?? null;
+        this.description = data.description ?? null;
+        this.amount = data.amount;
+        this.baseCurrency = data.base_currency;
+        this.paymentCurrency = data.payment_currency;
+        this.rawStatus = data.status;
+        this.status = status_js_1.StatusMapper.normalize(data.status) ?? "FAILED";
+        this.ttlMinutes = data.ttl_minutes;
+        this.expiresAt = data.expires_at;
+        this.createdAt = data.created_at;
+        this.checkoutUrl = data.checkout_url;
+        this.metadata = data.metadata ?? {};
+        this.options = data.options ?? [];
+        this.observations = data.observations ?? [];
+        this.paidAmount = data.paid_amount ?? null;
+        this.paidAsset = data.paid_asset ?? null;
+        this.raw = raw;
+    }
+    static fromJson(data) {
+        if (typeof data !== "object" || data === null || Array.isArray(data)) {
+            throw new Error("invoice response is not a JSON object");
+        }
+        const d = data;
+        // Every declared field is validated and built explicitly; unknown extras
+        // live in `raw` only and can never overwrite a checked/normalized value.
+        return new Invoice({
+            id: requiredString(d, "id"),
+            order_id: nullableString(d.order_id, "order_id"),
+            description: nullableString(d.description, "description"),
+            amount: requiredDecimalString(d.amount, "amount"),
+            base_currency: requiredString(d, "base_currency"),
+            payment_currency: requiredString(d, "payment_currency"),
+            status: requiredString(d, "status"),
+            ttl_minutes: requiredInteger(d.ttl_minutes, "ttl_minutes"),
+            expires_at: requiredString(d, "expires_at"),
+            created_at: requiredString(d, "created_at"),
+            checkout_url: requiredString(d, "checkout_url"),
+            metadata: requiredObject(d.metadata, "metadata"),
+            options: requiredOptions(d.options),
+            observations: requiredObservations(d.observations),
+            paid_amount: nullableDecimalString(d.paid_amount, "paid_amount"),
+            paid_asset: nullableString(d.paid_asset, "paid_asset"),
+        }, d);
+    }
+    get isPaid() {
+        return this.status === "PAID";
+    }
+    get isTerminal() {
+        return (0, status_js_1.isTerminalStatus)(this.status);
+    }
+    /** Payment option by asset id (e.g. "USDT_TRON"), or null. */
+    option(asset) {
+        return this.options.find((o) => o.asset === asset) ?? null;
+    }
+}
+exports.Invoice = Invoice;
+class CreateInvoiceResponse {
+    invoice;
+    idempotentReplay;
+    constructor(invoice, 
+    /** True when the API returned a previously created invoice for the same
+     *  Idempotency-Key (safe timeout/retry path). */
+    idempotentReplay) {
+        this.invoice = invoice;
+        this.idempotentReplay = idempotentReplay;
+    }
+}
+exports.CreateInvoiceResponse = CreateInvoiceResponse;
+// --- runtime validation helpers (public types are the contract) -------------
+const DECIMAL_STRING_RE = /^[0-9]+(?:\.[0-9]+)?$/;
+function requiredString(d, field) {
+    const value = d[field];
+    if (typeof value !== "string" || value === "") {
+        throw new Error(`invoice response field '${field}' must be a non-empty string`);
+    }
+    return value;
+}
+function nullableString(value, field) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    if (typeof value !== "string") {
+        throw new Error(`invoice response field '${field}' must be a string or null`);
+    }
+    return value;
+}
+function requiredDecimalString(value, field) {
+    if (typeof value !== "string" || !DECIMAL_STRING_RE.test(value)) {
+        throw new Error(`invoice response field '${field}' must be a decimal string`);
+    }
+    return value;
+}
+function nullableDecimalString(value, field) {
+    if (value === undefined || value === null) {
+        return null;
+    }
+    if (typeof value !== "string" || !DECIMAL_STRING_RE.test(value)) {
+        throw new Error(`invoice response field '${field}' must be a decimal string or null`);
+    }
+    return value;
+}
+function requiredInteger(value, field) {
+    if (!Number.isInteger(value)) {
+        throw new Error(`invoice response field '${field}' must be an integer`);
+    }
+    return value;
+}
+function requiredObject(value, field) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error(`invoice response field '${field}' must be a JSON object`);
+    }
+    return value;
+}
+function requiredArray(value, field) {
+    if (!Array.isArray(value)) {
+        throw new Error(`invoice response field '${field}' must be an array`);
+    }
+    return value;
+}
+function requiredOptions(value) {
+    return requiredArray(value, "options").map((raw, i) => {
+        const o = requiredObject(raw, `options[${i}]`);
+        return {
+            ...o,
+            asset: optionString(o, "asset", i),
+            network: optionString(o, "network", i),
+            payment_address: optionString(o, "payment_address", i),
+            amount_crypto: optionDecimal(o, "amount_crypto", i),
+            rate: optionString(o, "rate", i),
+            status: optionString(o, "status", i),
+        };
+    });
+}
+function optionString(o, field, i) {
+    const value = o[field];
+    if (typeof value !== "string" || value === "") {
+        throw new Error(`invoice response field 'options[${i}].${field}' must be a non-empty string`);
+    }
+    return value;
+}
+function optionDecimal(o, field, i) {
+    const value = o[field];
+    if (typeof value !== "string" || !DECIMAL_STRING_RE.test(value)) {
+        throw new Error(`invoice response field 'options[${i}].${field}' must be a decimal string`);
+    }
+    return value;
+}
+function requiredObservations(value) {
+    return requiredArray(value, "observations").map((raw, i) => {
+        const o = requiredObject(raw, `observations[${i}]`);
+        return {
+            ...o,
+            option_id: optionString(o, "option_id", i),
+            tx_hash: optionString(o, "tx_hash", i),
+            output_index: requiredInteger(o.output_index, `observations[${i}].output_index`),
+            amount_paid: optionDecimal(o, "amount_paid", i),
+            confirmations: requiredInteger(o.confirmations, `observations[${i}].confirmations`),
+            seen_at: optionString(o, "seen_at", i),
+        };
+    });
+}

package/dist/cjs/models/webhook.js

@@ -0,0 +1,97 @@
+"use strict";
+/**
+ * Verified webhook event model.
+ *
+ * Production payloads keep the invoice id inside `data` and the paid asset as
+ * a TICKER nested in `data.option`; the docs test vector uses a simplified
+ * top-level shape. Both resolve transparently (same as the PHP/Python SDKs).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhookEvent = void 0;
+class WebhookEvent {
+    id;
+    type;
+    invoiceId;
+    data;
+    raw;
+    constructor(payload) {
+        this.id = payload.id;
+        this.type = payload.type;
+        const data = payload.data ?? {};
+        const invoiceId = payload.invoice_id ?? data["invoice_id"];
+        this.invoiceId = typeof invoiceId === "string" ? invoiceId : null;
+        this.data = data;
+        this.raw = payload;
+    }
+    static fromJson(payload) {
+        if (typeof payload !== "object" || payload === null || Array.isArray(payload)) {
+            throw new Error("webhook payload is not a JSON object");
+        }
+        const p = payload;
+        // id/type are required non-empty strings - a signed `{}` must not pass
+        if (typeof p.id !== "string" || p.id === "") {
+            throw new Error("webhook payload is missing required field 'id'");
+        }
+        if (typeof p.type !== "string" || p.type === "") {
+            throw new Error("webhook payload is missing required field 'type'");
+        }
+        if (p.data !== undefined &&
+            (typeof p.data !== "object" || p.data === null || Array.isArray(p.data))) {
+            throw new Error("webhook payload field 'data' must be a JSON object");
+        }
+        for (const key of ["invoice_id"]) {
+            const value = p[key];
+            if (value !== undefined && value !== null &&
+                (typeof value !== "string" || value === "")) {
+                throw new Error(`webhook payload field '${key}' must be a non-empty string`);
+            }
+        }
+        const data = p.data ?? {};
+        const dataInvoiceId = data["invoice_id"];
+        if (dataInvoiceId !== undefined && dataInvoiceId !== null &&
+            (typeof dataInvoiceId !== "string" || dataInvoiceId === "")) {
+            throw new Error("webhook payload field 'data.invoice_id' must be a non-empty string");
+        }
+        const invoiceId = p.invoice_id ?? dataInvoiceId;
+        if (p.type === "payment.confirmed" &&
+            (typeof invoiceId !== "string" || invoiceId === "")) {
+            // crediting an order requires knowing which invoice was paid
+            throw new Error("payment.confirmed payload is missing the invoice id");
+        }
+        return new WebhookEvent(payload);
+    }
+    get isPaymentConfirmed() {
+        return this.type === "payment.confirmed";
+    }
+    /**
+     * Crypto amount actually received (payment.* events carry it under
+     * data.option.paid_amount; docs-vector shape: data.amount). For non-stable
+     * assets compare against the amount_crypto you invoiced, not the base total.
+     */
+    get paidAmount() {
+        const option = this.option();
+        const paid = option ? option["paid_amount"] : undefined;
+        const fallback = this.data["amount_paid"] ?? this.data["amount"] ?? undefined;
+        const value = paid ?? fallback;
+        return typeof value === "string" && value !== "" ? value : null;
+    }
+    /** Asset the payment arrived in: ticker ("USDT") or asset id ("USDT_TRON"). */
+    get paidAsset() {
+        const option = this.option();
+        const asset = (option ? option["asset"] : undefined) ?? this.data["asset"];
+        return typeof asset === "string" && asset !== "" ? asset : null;
+    }
+    /** Network of the paying option ("tron", "polygon", ...), when present. */
+    get paidNetwork() {
+        const option = this.option();
+        const network = option ? option["network"] : undefined;
+        return typeof network === "string" && network !== "" ? network : null;
+    }
+    option() {
+        const option = this.data["option"];
+        return typeof option === "object" && option !== null && !Array.isArray(option)
+            ? option
+            : null;
+    }
+}
+exports.WebhookEvent = WebhookEvent;

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/cjs/replay.js

@@ -0,0 +1,109 @@
+"use strict";
+/**
+ * At-least-once delivery protection and payment matching (P0).
+ *
+ * `isDuplicate()` is a PURE lookup: it never mutates the store. An event is
+ * marked processed only via `markProcessed()` AFTER the local order update
+ * succeeded - marking earlier would turn any crash in between into a
+ * permanently unpaid order (the retry would be skipped as a duplicate).
+ *
+ * Concurrent deliveries of the same event can both pass `isDuplicate()`;
+ * apps needing strict single-processing should implement an atomic claim
+ * (INSERT ... ON CONFLICT / unique constraint) in their EventStore and use
+ * it as the source of truth.
+ *
+ * Monetary validation is fail-closed: an unparseable amount never compares
+ * as "enough" - `matchesOrder()` returns false and `compareDecimals()`
+ * throws instead of silently comparing garbage.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReplayGuard = void 0;
+exports.isValidDecimal = isValidDecimal;
+exports.compareDecimals = compareDecimals;
+/** Plain non-negative decimal only: no sign, exponent, spaces, extra dots or
+ *  NaN/Infinity spellings. Zero is a syntactically valid amount. */
+const DECIMAL_RE = /^[0-9]+(?:\.[0-9]+)?$/;
+/** True only for plain non-negative decimal strings (no float arithmetic). */
+function isValidDecimal(value) {
+    return typeof value === "string" && DECIMAL_RE.test(value);
+}
+/**
+ * Compare two plain non-negative decimal strings WITHOUT floats.
+ * Throws TypeError on anything that is not a plain decimal - garbage must
+ * never compare silently (validate first; matchesOrder does).
+ */
+function compareDecimals(a, b) {
+    for (const value of [a, b]) {
+        if (!DECIMAL_RE.test(value)) {
+            throw new TypeError(`not a plain non-negative decimal string: ${JSON.stringify(value)}`);
+        }
+    }
+    const [ai = "0", af = ""] = a.split(".");
+    const [bi = "0", bf = ""] = b.split(".");
+    // normalize BEFORE comparing: leading zeros must not affect length/value
+    // ("0002" is 2, not a 4-digit number greater than "10")
+    const norm = (s) => s.replace(/^0+(?=\d)/, "");
+    const nAi = norm(ai);
+    const nBi = norm(bi);
+    const intCmp = nAi.length !== nBi.length ? nAi.length - nBi.length : nAi.localeCompare(nBi);
+    const fracCmp = af.padEnd(bf.length, "0").localeCompare(bf.padEnd(af.length, "0"));
+    return intCmp || fracCmp; // never -0 (0 stays 0 via ||)
+}
+class ReplayGuard {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    /** Pure check: true when the event was already processed. No side effects. */
+    async isDuplicate(eventId) {
+        return await this.store.has(eventId);
+    }
+    /** Call only after the local order update has succeeded. */
+    async markProcessed(eventId) {
+        await this.store.markProcessed(eventId);
+    }
+    /**
+     * Signature validity alone is NOT enough to credit an order: match the
+     * invoice id, the paid crypto amount (>= minAmount) and the asset.
+     * Fail-closed: invalid amount data means "not enough", never "paid".
+     */
+    matchesOrder(event, expectedInvoiceId, options = {}) {
+        if (event.invoiceId !== expectedInvoiceId) {
+            return false;
+        }
+        if (options.asset !== undefined && !assetMatches(event, options.asset)) {
+            return false;
+        }
+        if (options.minAmount !== undefined) {
+            const paid = event.paidAmount;
+            if (paid === null || !isValidDecimal(paid) || !isValidDecimal(options.minAmount)) {
+                return false;
+            }
+            if (compareDecimals(paid, options.minAmount) < 0) {
+                return false;
+            }
+        }
+        return true;
+    }
+}
+exports.ReplayGuard = ReplayGuard;
+function assetMatches(event, expected) {
+    const paidRaw = (event.paidAsset ?? "").toLowerCase();
+    if (!paidRaw) {
+        return false;
+    }
+    const [expTicker, expNetwork] = expected.toLowerCase().split("_");
+    const [paidTicker] = paidRaw.split("_");
+    if (paidTicker !== expTicker) {
+        return false;
+    }
+    if (expNetwork !== undefined && expNetwork !== "") {
+        // asset id expected: the webhook MUST carry the network explicitly;
+        // missing or different network is a mismatch (fail-closed)
+        const paidNetwork = (event.paidNetwork ?? "").toLowerCase();
+        if (paidNetwork !== expNetwork) {
+            return false;
+        }
+    }
+    return true;
+}

package/dist/cjs/status.js

@@ -0,0 +1,46 @@
+"use strict";
+/**
+ * Normalized invoice status + raw-API status mapping.
+ *
+ * Raw statuses (created/pending/detecting/confirmed/underpaid/expired/canceled)
+ * never leak into billing logic: platforms consume InvoiceStatus
+ * (mirrors the PHP/Python SDKs).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StatusMapper = void 0;
+exports.isTerminalStatus = isTerminalStatus;
+const MAP = {
+    created: "PENDING",
+    pending: "PENDING",
+    detecting: "CONFIRMING",
+    confirmed: "PAID",
+    underpaid: "UNDERPAID",
+    expired: "EXPIRED",
+    canceled: "CANCELLED",
+    // overpayment is credited and confirmed server-side; kept for forward
+    // compatibility and local bookkeeping
+    overpaid: "OVERPAID",
+};
+const RAW_TERMINAL = new Set(["confirmed", "underpaid", "expired", "canceled"]);
+class StatusMapper {
+    static normalize(raw) {
+        return MAP[raw] ?? null;
+    }
+    static normalizeOrFail(raw) {
+        const status = MAP[raw];
+        if (!status) {
+            throw new Error(`unknown invoice status '${raw}'`);
+        }
+        return status;
+    }
+    static isTerminal(raw) {
+        return RAW_TERMINAL.has(raw);
+    }
+    static isPaid(raw) {
+        return raw === "confirmed";
+    }
+}
+exports.StatusMapper = StatusMapper;
+function isTerminalStatus(status) {
+    return status !== "PENDING" && status !== "CONFIRMING";
+}

package/dist/cjs/version.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERSION = void 0;
+/** Single source of truth for the SDK version. */
+exports.VERSION = "0.1.0";

package/dist/cjs/webhooks/verifier.js

@@ -0,0 +1,100 @@
+"use strict";
+/**
+ * Webhook signature verification - security critical (P0).
+ *
+ * Every delivery carries one header:
+ *
+ *     X-ZKP-Signature: t=<unix seconds>,v1=<64-char lowercase hex>
+ *
+ * v1 = HMAC-SHA256(webhookSecret, "{t}.{rawBody}") where rawBody is the exact
+ * request body as received - never re-serialized JSON. Verification is strict
+ * (header format, ±tolerance window) and constant-time (timingSafeEqual).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhookVerifier = exports.DEFAULT_TOLERANCE_SECONDS = void 0;
+const node_crypto_1 = require("node:crypto");
+const errors_js_1 = require("../errors.js");
+const webhook_js_1 = require("../models/webhook.js");
+const HEADER_RE = /^t=(\d{1,12}),v1=([0-9a-f]{64})$/;
+exports.DEFAULT_TOLERANCE_SECONDS = 300;
+const MESSAGES = {
+    [errors_js_1.WebhookVerificationError.MISSING_HEADER]: "X-ZKP-Signature header is missing",
+    [errors_js_1.WebhookVerificationError.MALFORMED_HEADER]: "signature header is malformed (expected t=<int>,v1=<64 lowercase hex>)",
+    [errors_js_1.WebhookVerificationError.STALE_TIMESTAMP]: "signature timestamp is outside the tolerance window (stale)",
+    [errors_js_1.WebhookVerificationError.FUTURE_TIMESTAMP]: "signature timestamp is outside the tolerance window (future)",
+    [errors_js_1.WebhookVerificationError.SIGNATURE_MISMATCH]: "signature does not match the raw body",
+    [errors_js_1.WebhookVerificationError.MALFORMED_PAYLOAD]: "verified body is not a JSON object",
+};
+class WebhookVerifier {
+    secret;
+    toleranceSeconds;
+    constructor(webhookSecret, toleranceSeconds = exports.DEFAULT_TOLERANCE_SECONDS) {
+        if (!webhookSecret) {
+            throw new Error("webhook secret must not be empty");
+        }
+        if (!Number.isInteger(toleranceSeconds) || toleranceSeconds < 1) {
+            throw new Error("tolerance must be at least 1 second");
+        }
+        this.secret = webhookSecret;
+        this.toleranceSeconds = toleranceSeconds;
+    }
+    /** Verify and decode; throws WebhookVerificationError on any failure. */
+    verify(rawBody, signatureHeader, options = {}) {
+        const result = this.check(rawBody, signatureHeader, options);
+        if (!result.event) {
+            throw new errors_js_1.WebhookVerificationError(MESSAGES[result.reason ?? ""] ?? "verification failed", result.reason ?? "invalid");
+        }
+        return result.event;
+    }
+    /** Non-throwing variant returning a VerificationResult. */
+    check(rawBody, signatureHeader, options = {}) {
+        if (!signatureHeader) {
+            return { valid: false, reason: errors_js_1.WebhookVerificationError.MISSING_HEADER, event: null };
+        }
+        const match = HEADER_RE.exec(signatureHeader);
+        if (!match) {
+            return { valid: false, reason: errors_js_1.WebhookVerificationError.MALFORMED_HEADER, event: null };
+        }
+        const [, timestamp, signature] = match;
+        const now = options.now ?? Math.floor(Date.now() / 1000);
+        const skew = now - Number(timestamp);
+        if (skew > this.toleranceSeconds) {
+            return { valid: false, reason: errors_js_1.WebhookVerificationError.STALE_TIMESTAMP, event: null };
+        }
+        if (-skew > this.toleranceSeconds) {
+            return { valid: false, reason: errors_js_1.WebhookVerificationError.FUTURE_TIMESTAMP, event: null };
+        }
+        const expected = this.signPayload(timestamp, rawBody);
+        if (expected.length !== signature.length ||
+            !(0, node_crypto_1.timingSafeEqual)(Buffer.from(expected, "utf8"), Buffer.from(signature, "utf8"))) {
+            return { valid: false, reason: errors_js_1.WebhookVerificationError.SIGNATURE_MISMATCH, event: null };
+        }
+        let payload;
+        try {
+            const text = typeof rawBody === "string" ? rawBody : Buffer.from(rawBody).toString("utf8");
+            payload = JSON.parse(text);
+        }
+        catch {
+            return { valid: false, reason: errors_js_1.WebhookVerificationError.MALFORMED_PAYLOAD, event: null };
+        }
+        if (typeof payload !== "object" || payload === null || Array.isArray(payload)) {
+            return { valid: false, reason: errors_js_1.WebhookVerificationError.MALFORMED_PAYLOAD, event: null };
+        }
+        try {
+            return { valid: true, reason: null, event: webhook_js_1.WebhookEvent.fromJson(payload) };
+        }
+        catch {
+            return { valid: false, reason: errors_js_1.WebhookVerificationError.MALFORMED_PAYLOAD, event: null };
+        }
+    }
+    /** Build a signature header for a body (tests and local replay tooling). */
+    sign(rawBody, timestamp) {
+        const t = timestamp ?? Math.floor(Date.now() / 1000);
+        return `t=${t},v1=${this.signPayload(String(t), rawBody)}`;
+    }
+    signPayload(timestamp, rawBody) {
+        const body = typeof rawBody === "string" ? Buffer.from(rawBody, "utf8") : Buffer.from(rawBody);
+        return (0, node_crypto_1.createHmac)("sha256", this.secret).update(timestamp + ".").update(body).digest("hex");
+    }
+}
+exports.WebhookVerifier = WebhookVerifier;