zkp-sdk-node 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ZeroKYC Payments Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,191 @@
+# zkp-sdk-node
+
+Official Node.js/TypeScript SDK for the [ZeroKYC Pay](https://zerokyc-payments.com)
+crypto payment gateway. Framework-agnostic, zero runtime dependencies (built-in
+`fetch`, `AbortController`, `node:crypto`), Node.js **20+** (22+ recommended),
+TypeScript `strict`. **Server-side only** — API keys and webhook verification
+must never run in a browser.
+
+The same public contract and security guarantees as
+[zkp-sdk-php](https://github.com/zerokyc-payments/zkp-sdk-php) and
+[zkp-sdk-python](https://github.com/zerokyc-payments/zkp-sdk-python).
+
+## Install
+
+```bash
+npm install zkp-sdk-node
+```
+
+(If the package is not on npm yet, install from source:
+
+```bash
+npm install github:zerokyc-payments/zkp-sdk-node
+```
+)
+
+## Quickstart (sandbox invoice in 5 minutes)
+
+1. Create an account at [console.zerokyc-payments.com](https://console.zerokyc-payments.com)
+   and copy a **sandbox** API key (`pk_test_...`) from *API keys*.
+2. Create an invoice and send the buyer to the hosted checkout:
+
+```ts
+import { idempotencyKey, ZeroKYC } from "zkp-sdk-node";
+
+const zkp = new ZeroKYC({
+  apiKey: process.env.ZEROKYC_API_KEY!, // pk_test_... / pk_live_...
+  environment: "sandbox",
+});
+
+const response = await zkp.createInvoice({
+  amount: "19.90",
+  currency: "USD",
+  orderId: "INV-1042",
+  description: "VPS plan: starter",
+  idempotencyKey: idempotencyKey("myshop", "order", 1042), // stable per order
+});
+
+res.redirect(response.invoice.checkoutUrl);
+```
+
+3. Get paid: ZeroKYC detects the on-chain payment and POSTs a signed webhook.
+   **A verified webhook (or a server-side `getInvoice()`) is the only proof of
+   payment — never a browser success URL.**
+
+```ts
+import { WebhookVerificationError } from "zkp-sdk-node";
+
+try {
+  const event = zkp.verifyWebhook(rawBody, req.header("X-ZKP-Signature") ?? "");
+} catch (error) {
+  if (error instanceof WebhookVerificationError) {
+    res.status(400).end();
+  } else throw error;
+}
+```
+
+Full production flow with duplicate protection and payment matching:
+[examples/safe-webhook-handler-express.ts](examples/safe-webhook-handler-express.ts)
+/ [examples/safe-webhook-handler-nextjs.ts](examples/safe-webhook-handler-nextjs.ts).
+
+## API surface
+
+| Method | Purpose |
+|---|---|
+| `createInvoice({ amount, currency, ... })` | create an invoice (idempotent with `idempotencyKey`) |
+| `getInvoice(invoiceId)` | reconciliation / polling / lost-webhook recovery |
+| `cancelInvoice(invoiceId)` | cancel an unpaid invoice |
+| `ping()` | liveness / configuration probe |
+| `verifyWebhook(rawBody, signatureHeader)` | HMAC verification of a delivery |
+
+Every method accepts `{ signal }` (standard `AbortSignal`) as the last option;
+a per-request timeout (`timeoutMs`, default 15 s) is enforced via `AbortController`.
+
+## Raw bodies for webhook verification (important)
+
+The signature covers the **exact raw bytes**. Never verify re-serialized JSON:
+
+- **Express**: enable the raw-body capture before the JSON parser:
+  `app.use(express.json({ verify: (req, _res, buf) => { req.rawBody = buf; } }))`
+- **Next.js App Router**: `await request.text()` in a `route.ts` with
+  `export const runtime = "nodejs"` — that *is* the raw body.
+- **Fastify**: `addContentTypeParser("application/json", { parseAs: "buffer" }, ...)`.
+
+## Configuration
+
+`new ZeroKYC({ apiKey, environment?, webhookSecret?, timeoutMs?, maxRetries?, baseUrl? })`
+
+- `apiKey`: `pk_test_...` (sandbox) / `pk_live_...` (production).
+- `environment`: `"sandbox" | "production"`; inferred from the key; a mismatch throws.
+- `webhookSecret`: `whsec_...` from console → Webhooks (used by `verifyWebhook`).
+- `baseUrl`: tests/local development only — the URL is defined centrally.
+
+## Status normalization
+
+Raw API statuses never leak into your billing logic:
+
+| API (raw)                | `InvoiceStatus` |
+|--------------------------|-----------------|
+| `created`, `pending`     | `"PENDING"`     |
+| `detecting`              | `"CONFIRMING"`  |
+| `confirmed`              | `"PAID"`        |
+| `underpaid`              | `"UNDERPAID"`   |
+| `expired`                | `"EXPIRED"`     |
+| `canceled`               | `"CANCELLED"`   |
+| unknown                  | `"FAILED"` (alert) |
+
+`invoice.isPaid` / `invoice.isTerminal` answer the common questions. Monetary
+amounts are **decimal strings everywhere** — never JavaScript numbers.
+
+## Idempotency
+
+```ts
+import { idempotencyKey } from "zkp-sdk-node";
+idempotencyKey("whmcs", "invoice", 1042); // zerokyc:whmcs:invoice:1042 (<=120 chars)
+```
+
+A timeout + retry then returns **the same** invoice
+(`response.idempotentReplay === true`) instead of a duplicate.
+
+## Error handling & retries
+
+| Error                    | HTTP          | Retried automatically? |
+|--------------------------|---------------|------------------------|
+| `AuthenticationError`    | 401 / 403     | never                  |
+| `ValidationError`        | 400 / 422     | never                  |
+| `RateLimitError`         | 429           | yes (Retry-After up to 5 s, max twice) |
+| `APIError`               | 5xx, 402, 404 | only GET / idempotent POST |
+| `NetworkError`           | transport/abort | only GET / idempotent POST (never a caller abort) |
+| `WebhookVerificationError` | n/a         | n/a (machine-readable `.reason`) |
+
+`RateLimitError.retryAfter` is the parsed Retry-After in seconds or `null`
+(malformed, negative, fractional and HTTP-date values map to `null` safely).
+Backoff is bounded exponential (300 ms → 600 ms → 1200 ms, capped by `maxRetries`).
+
+## Webhook security checklist
+
+- verify against the **exact raw body** (never re-serialized JSON);
+- strict `t=`/`v1=` header format, lowercase hex, `timingSafeEqual` (built in);
+- default ±300 s window (`new WebhookVerifier(secret, 600)` to widen);
+- at-least-once delivery: `ReplayGuard.isDuplicate()` is a **pure** check —
+  call `markProcessed()` only after the local order update succeeded;
+- match invoice id / amount / asset before crediting (`matchesOrder()`);
+- secrets never appear in exceptions or logs.
+
+Self-test against the documented vector:
+
+```ts
+import { WebhookVerifier } from "zkp-sdk-node";
+
+const event = new WebhookVerifier("whsec_zkp_test_vector_2026").verify(
+  '{"id":"evt_test_001","type":"payment.confirmed","invoice_id":"inv_test_001"}',
+  "t=1788788073,v1=ade537fa13aec79a6d1648bd7f197872066c161676c389243ab5c6b13fea7f52",
+  { now: 1788788073 },
+);
+```
+
+## Assets
+
+USDT (TRC-20), USDC/USDT (Polygon, Arbitrum), BTC, XMR, TON, USDT-TON. Pin one
+via `paymentCurrency: "USDT_TRON"`, or let the buyer choose with `"any"` (default).
+
+## Node support & SemVer
+
+Node 20 / 22 / 24 (CI-tested; 22+ recommended). The SDK itself runs on plain Node 20;
+developing it (running the test suite) needs Node 20.12+ because of vitest. ESM and CommonJS entry points
+with full type declarations. SemVer: 0.x collects integration feedback,
+breaking changes before 1.0 land in minor bumps and are listed in the
+[CHANGELOG](CHANGELOG.md).
+
+## Development
+
+```bash
+npm ci
+npm run lint && npm run typecheck
+npm test               # vitest
+npm run build && npm pack --dry-run
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/SECURITY.md

@@ -0,0 +1,34 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+Please **do not** report security vulnerabilities through public GitHub issues.
+
+Report privately via GitHub's *Report a vulnerability* flow on this repository
+(Report a vulnerability -> Security tab), or email **security@zerokyc-payments.com**.
+
+Include a description, reproduction steps and affected versions. We aim to
+respond within 72 hours and will credit reporters in release notes unless you
+prefer to stay anonymous.
+
+## Scope
+
+- This SDK repository (client, webhook verification, examples).
+- For platform/product vulnerabilities (API, checkout, console) use the same
+  channel - we route internally.
+
+## Out of scope
+
+- Attacks requiring a compromised merchant API key or webhook secret.
+- Rate limiting/resource exhaustion of our public endpoints without a proof
+  of impact.
+
+## Verification notes for auditors
+
+- Webhook signature comparison uses `crypto.timingSafeEqual` for constant-time
+  comparison (length-checked before the call).
+- Timestamp tolerance defaults to +-300 seconds and is enforced before the
+  HMAC comparison.
+- Secrets are never included in exceptions or logs by the SDK itself.
+- The SDK is server-side only; API keys and webhook secrets must never reach
+  a browser bundle.

package/dist/cjs/client.js

@@ -0,0 +1,233 @@
+"use strict";
+/**
+ * HTTP client with typed error mapping and a bounded, idempotency-aware
+ * retry policy. Adapters never talk to the API directly.
+ *
+ * Retry rules (identical to the PHP/Python SDKs):
+ * - GET: retry NetworkError and selected retryable statuses (429/408/5xx);
+ * - POST invoices: retry ONLY when an idempotency key is present;
+ * - 429: honors Retry-After up to a 5s cap (plain non-negative integers
+ *   only; malformed, negative, fractional and HTTP-date values safely map
+ *   to retryAfter: null and never break error construction);
+ * - 400/401/403/422: never retried;
+ * - bounded exponential backoff (300ms -> 600ms -> 1200ms), no infinite loops.
+ *
+ * Requests accept an AbortSignal; a per-request timeout is enforced via
+ * AbortController. Secrets never appear in exceptions.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZeroKYC = void 0;
+exports.idempotencyKey = idempotencyKey;
+const config_js_1 = require("./config.js");
+const errors_js_1 = require("./errors.js");
+const http_js_1 = require("./http.js");
+const invoices_js_1 = require("./invoices.js");
+const invoice_js_1 = require("./models/invoice.js");
+const verifier_js_1 = require("./webhooks/verifier.js");
+const RETRYABLE_STATUSES = new Set([429, 408]);
+const RETRY_AFTER_CAP_SECONDS = 5;
+/** Stable idempotency key: zerokyc:{platform}:{entity}:{id} (max 120 chars). */
+function idempotencyKey(...parts) {
+    const key = `zerokyc:${parts.join(":")}`;
+    if (!key) {
+        throw new errors_js_1.ValidationError("idempotency key must not be empty");
+    }
+    if (key.length > 120) {
+        throw new errors_js_1.ValidationError("idempotency key must be at most 120 characters");
+    }
+    return key;
+}
+const defaultSleeper = (ms) => new Promise((resolve) => {
+    setTimeout(resolve, ms);
+});
+class ZeroKYC {
+    config;
+    fetchLike;
+    sleeper;
+    constructor(options = { apiKey: "" }) {
+        this.config = new config_js_1.Config(options);
+        this.fetchLike = options.fetchImpl ?? http_js_1.fetchTransport;
+        this.sleeper = options.sleeper ?? defaultSleeper;
+    }
+    /** Create an invoice; with an idempotency key a timeout+retry returns the
+     *  same invoice instead of creating a duplicate. */
+    async createInvoice(options) {
+        const { signal, ...create } = options;
+        const payload = (0, invoices_js_1.buildCreatePayload)(create);
+        const headers = { "Content-Type": "application/json" };
+        if (create.idempotencyKey !== undefined) {
+            headers["Idempotency-Key"] = create.idempotencyKey;
+        }
+        const response = await this.request("POST", "/v1/invoices", {
+            headers,
+            body: JSON.stringify(payload),
+            mayRetry: create.idempotencyKey !== undefined,
+            expectedStatus: 201,
+            signal,
+        });
+        const replay = (response.header("Idempotent-Replay") ?? "").toLowerCase() === "true";
+        return new invoice_js_1.CreateInvoiceResponse(invoice_js_1.Invoice.fromJson(parseJson(response)), replay);
+    }
+    /** Reconciliation/recovery: poll a status server-to-server. */
+    async getInvoice(invoiceId, options = {}) {
+        const response = await this.request("GET", `/v1/invoices/${encodeURIComponent(invoiceId)}`, {
+            mayRetry: true,
+            expectedStatus: 200,
+            signal: options.signal,
+        });
+        return invoice_js_1.Invoice.fromJson(parseJson(response));
+    }
+    async cancelInvoice(invoiceId, options = {}) {
+        const response = await this.request("POST", `/v1/invoices/${encodeURIComponent(invoiceId)}/cancel`, {
+            headers: { "Content-Type": "application/json" },
+            body: "{}",
+            mayRetry: false,
+            expectedStatus: 200,
+            signal: options.signal,
+        });
+        return invoice_js_1.Invoice.fromJson(parseJson(response));
+    }
+    /** Liveness/configuration probe; returns the decoded /v1/ping body. */
+    async ping(options = {}) {
+        const response = await this.request("GET", "/v1/ping", {
+            mayRetry: true,
+            expectedStatus: 200,
+            signal: options.signal,
+        });
+        return parseJson(response);
+    }
+    /** Verify a delivery; throws WebhookVerificationError on any failure. */
+    verifyWebhook(rawBody, signatureHeader, options = {}) {
+        return this.verifier(options.secret).verify(rawBody, signatureHeader);
+    }
+    verifier(secret) {
+        return new verifier_js_1.WebhookVerifier(secret ?? this.config.webhookSecret);
+    }
+    /** Await the sleeper; a caller abort during the wait stops the retry loop. */
+    async wait(ms, signal) {
+        const sleep = Promise.resolve(this.sleeper(ms));
+        if (!signal) {
+            await sleep;
+            return;
+        }
+        if (signal.aborted) {
+            throw new errors_js_1.NetworkError("aborted while waiting to retry");
+        }
+        await new Promise((resolve, reject) => {
+            const onAbort = () => reject(new errors_js_1.NetworkError("aborted while waiting to retry"));
+            signal.addEventListener("abort", onAbort, { once: true });
+            void sleep.then(resolve, reject).finally(() => signal.removeEventListener("abort", onAbort));
+        });
+    }
+    async request(method, path, opts) {
+        let attempt = 0;
+        for (;;) {
+            let response;
+            try {
+                response = await this.fetchLike(this.config.baseUrl + path, {
+                    method,
+                    headers: {
+                        Authorization: `Bearer ${this.config.apiKey}`,
+                        Accept: "application/json",
+                        "User-Agent": (0, http_js_1.sdkUserAgent)(),
+                        ...opts.headers,
+                    },
+                    body: opts.body,
+                    signal: opts.signal,
+                    redirect: "manual",
+                    timeoutMs: this.config.timeoutMs,
+                });
+            }
+            catch (e) {
+                if (!(e instanceof errors_js_1.NetworkError)) {
+                    throw e;
+                }
+                // the caller cancelled: retrying their own abort is pointless
+                if (opts.signal?.aborted) {
+                    throw e;
+                }
+                if (!opts.mayRetry || attempt >= this.config.maxRetries) {
+                    throw e;
+                }
+                await this.wait(backoffMs(attempt), opts.signal);
+                attempt += 1;
+                continue;
+            }
+            if (response.status === opts.expectedStatus) {
+                return response;
+            }
+            if ((RETRYABLE_STATUSES.has(response.status) || response.status >= 500) &&
+                opts.mayRetry &&
+                attempt < this.config.maxRetries) {
+                const delayMs = response.status === 429
+                    ? retryAfterMs(response.header("Retry-After"))
+                    : backoffMs(attempt);
+                if (delayMs !== null) {
+                    await this.wait(delayMs, opts.signal);
+                    attempt += 1;
+                    continue;
+                }
+                // Retry-After beyond the cap: fall through and surface the 429
+            }
+            throw mapError(response);
+        }
+    }
+}
+exports.ZeroKYC = ZeroKYC;
+function parseJson(response) {
+    try {
+        return JSON.parse(response.body);
+    }
+    catch {
+        throw new errors_js_1.APIError("response was not valid JSON", response.status);
+    }
+}
+function mapError(response) {
+    let error = {};
+    try {
+        const decoded = JSON.parse(response.body);
+        if (decoded && typeof decoded === "object" && typeof decoded.error === "object") {
+            error = decoded.error;
+        }
+    }
+    catch {
+        // non-JSON error body
+    }
+    const message = typeof error.message === "string" && error.message
+        ? error.message
+        : `unexpected HTTP ${response.status}`;
+    if (response.status === 401 || response.status === 403) {
+        return new errors_js_1.AuthenticationError(message);
+    }
+    if (response.status === 429) {
+        return new errors_js_1.RateLimitError(message, parseRetryAfter(response.header("Retry-After")));
+    }
+    if (response.status === 400 || response.status === 422) {
+        return new errors_js_1.ValidationError(message);
+    }
+    return new errors_js_1.APIError(message, response.status, typeof error.code === "string" ? error.code : undefined, typeof error.doc_url === "string" ? error.doc_url : undefined);
+}
+/** Seconds from Retry-After: plain non-negative integers only, else null. */
+function parseRetryAfter(header) {
+    if (header === null) {
+        return null;
+    }
+    const value = header.trim();
+    return /^\d+$/.test(value) ? Number(value) : null;
+}
+/** Delay for a 429 retry; null means "surface the error immediately". */
+function retryAfterMs(header) {
+    if (header === null) {
+        return backoffMs(0);
+    }
+    const seconds = parseRetryAfter(header);
+    if (seconds === null) {
+        // malformed or HTTP-date: unsupported -> retryAfter reported as null,
+        // still retry on the default bounded backoff
+        return backoffMs(0);
+    }
+    return seconds <= RETRY_AFTER_CAP_SECONDS ? seconds * 1000 : null;
+}
+function backoffMs(attempt) {
+    return 300 * 2 ** attempt;
+}

package/dist/cjs/config.js

@@ -0,0 +1,54 @@
+"use strict";
+/**
+ * SDK configuration: sandbox/production, base URL, timeouts, retries.
+ *
+ * The base URL is defined centrally here; the override exists for tests and
+ * local development only - adapters must never hard-code URLs.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Config = exports.PRODUCTION = exports.SANDBOX = exports.DEFAULT_BASE_URL = void 0;
+exports.DEFAULT_BASE_URL = "https://api.zerokyc-payments.com";
+exports.SANDBOX = "sandbox";
+exports.PRODUCTION = "production";
+class Config {
+    apiKey;
+    environment;
+    webhookSecret;
+    timeoutMs;
+    maxRetries;
+    baseUrl;
+    constructor(options) {
+        const { apiKey } = options;
+        if (!apiKey) {
+            throw new Error("apiKey is required");
+        }
+        const environment = options.environment ?? (apiKey.startsWith("pk_test_") ? exports.SANDBOX : exports.PRODUCTION);
+        if (environment !== exports.SANDBOX && environment !== exports.PRODUCTION) {
+            throw new Error(`environment must be 'sandbox' or 'production', got '${environment}'`);
+        }
+        // Mixing up sandbox and live keys is the classic production incident:
+        // refuse the mismatch outright instead of hoping for the best.
+        const isTestKey = apiKey.startsWith("pk_test_");
+        if (environment === exports.PRODUCTION && isTestKey) {
+            throw new Error("environment is production but the apiKey is a sandbox key (pk_test_...); " +
+                "use a pk_live_... key or set environment: 'sandbox'");
+        }
+        if (environment === exports.SANDBOX && !isTestKey) {
+            throw new Error("environment is sandbox but the apiKey is not a sandbox key; expected a pk_test_... key");
+        }
+        const maxRetries = options.maxRetries ?? 2;
+        if (!Number.isInteger(maxRetries) || maxRetries < 0 || maxRetries > 5) {
+            throw new Error("maxRetries must be an integer between 0 and 5");
+        }
+        this.apiKey = apiKey;
+        this.environment = environment;
+        this.webhookSecret = options.webhookSecret ?? "";
+        this.timeoutMs = options.timeoutMs ?? 15_000;
+        this.maxRetries = maxRetries;
+        this.baseUrl = (options.baseUrl ?? exports.DEFAULT_BASE_URL).replace(/\/+$/, "");
+    }
+    get isSandbox() {
+        return this.environment === exports.SANDBOX;
+    }
+}
+exports.Config = Config;

package/dist/cjs/errors.js

@@ -0,0 +1,70 @@
+"use strict";
+/**
+ * Typed error hierarchy.
+ *
+ * Mapping: 401/403 -> AuthenticationError, 400/422 -> ValidationError,
+ * 429 -> RateLimitError (carries retryAfter seconds when sent), 5xx/402/404
+ * -> APIError, transport failures (timeout/DNS/connect/abort) ->
+ * NetworkError, webhook verification -> WebhookVerificationError
+ * (machine-readable `reason`).
+ *
+ * Secrets never appear in messages: they carry API-provided text only.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebhookVerificationError = exports.NetworkError = exports.APIError = exports.RateLimitError = exports.ValidationError = exports.AuthenticationError = exports.ZeroKYCError = void 0;
+class ZeroKYCError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}
+exports.ZeroKYCError = ZeroKYCError;
+/** 401/403 from the API: missing/invalid key or forbidden scope. Never retried. */
+class AuthenticationError extends ZeroKYCError {
+}
+exports.AuthenticationError = AuthenticationError;
+/** 400/422 from the API (or local request validation). Never retried. */
+class ValidationError extends ZeroKYCError {
+}
+exports.ValidationError = ValidationError;
+/** 429 from the API; `retryAfter` carries Retry-After seconds when parseable. */
+class RateLimitError extends ZeroKYCError {
+    retryAfter;
+    constructor(message, retryAfter = null) {
+        super(message);
+        this.retryAfter = retryAfter;
+    }
+}
+exports.RateLimitError = RateLimitError;
+/** Unexpected API error (5xx, 402 cutoff, 404, malformed envelope). */
+class APIError extends ZeroKYCError {
+    status;
+    errorCode;
+    docUrl;
+    constructor(message, status = 0, errorCode, docUrl) {
+        super(message);
+        this.status = status;
+        this.errorCode = errorCode;
+        this.docUrl = docUrl;
+    }
+}
+exports.APIError = APIError;
+/** Transport failure: DNS, connect, TLS, timeout or abort. */
+class NetworkError extends ZeroKYCError {
+}
+exports.NetworkError = NetworkError;
+/** Webhook verification failed; `reason` is machine-readable. */
+class WebhookVerificationError extends ZeroKYCError {
+    reason;
+    static MISSING_HEADER = "missing_header";
+    static MALFORMED_HEADER = "malformed_header";
+    static STALE_TIMESTAMP = "stale_timestamp";
+    static FUTURE_TIMESTAMP = "future_timestamp";
+    static SIGNATURE_MISMATCH = "signature_mismatch";
+    static MALFORMED_PAYLOAD = "malformed_payload";
+    constructor(message, reason) {
+        super(message);
+        this.reason = reason;
+    }
+}
+exports.WebhookVerificationError = WebhookVerificationError;

package/dist/cjs/http.js

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * HTTP transport: built-in fetch with per-request timeout via
+ * AbortController, an injectable fetch for tests, and redirect: "manual"
+ * (a 3xx must surface - the same rule as the PHP/Python SDKs).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.httpResponse = httpResponse;
+exports.fetchTransport = fetchTransport;
+exports.sdkUserAgent = sdkUserAgent;
+const errors_js_1 = require("./errors.js");
+const version_js_1 = require("./version.js");
+function httpResponse(status, body, headers = {}) {
+    const normalized = {};
+    for (const [k, v] of Object.entries(headers)) {
+        normalized[k.toLowerCase()] = v;
+    }
+    return {
+        status,
+        body,
+        headers: normalized,
+        header(name) {
+            return normalized[name.toLowerCase()] ?? null;
+        },
+    };
+}
+/**
+ * Built-in fetch transport: per-request timeout via AbortController, caller
+ * aborts forwarded into the same controller (original reason preserved),
+ * redirect: "manual" - a 3xx must surface (same rule as the PHP/Python SDKs).
+ * Listener and timer lifecycles are leak-free: everything is cleaned in
+ * finally, so a reused caller signal never accumulates handlers.
+ */
+async function fetchTransport(url, init) {
+    // ONE request controller: caller aborts are forwarded into it, and the
+    // forwarding listener plus the timeout timer are always removed in finally
+    // (a reused caller signal must never accumulate listeners).
+    const controller = new AbortController();
+    const timer = setTimeout(() => {
+        controller.abort(new Error("request timeout"));
+    }, init.timeoutMs ?? 15_000);
+    const caller = init.signal;
+    const onCallerAbort = () => {
+        // surface the caller's own abort reason, not a generic one
+        controller.abort(caller?.reason);
+    };
+    if (caller?.aborted) {
+        clearTimeout(timer);
+        throw new errors_js_1.NetworkError(`transport failure: ${String(caller.reason ?? "aborted")}`);
+    }
+    caller?.addEventListener("abort", onCallerAbort, { once: true });
+    try {
+        const response = await fetch(url, {
+            method: init.method,
+            headers: init.headers,
+            body: init.body,
+            signal: controller.signal,
+            redirect: "manual",
+        });
+        const headers = {};
+        response.headers.forEach((value, key) => {
+            headers[key] = value;
+        });
+        return httpResponse(response.status, await response.text(), headers);
+    }
+    catch (e) {
+        // fetch rejects on network/timeout/abort; DNS/connect arrive as TypeError
+        throw new errors_js_1.NetworkError(`transport failure: ${e.message}`);
+    }
+    finally {
+        clearTimeout(timer);
+        caller?.removeEventListener("abort", onCallerAbort);
+    }
+}
+/** Identifiable SDK user agent (CDNs commonly block library default UAs). */
+function sdkUserAgent() {
+    return `zerokyc-node/${version_js_1.VERSION}`;
+}