zkp-sdk-node 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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.
+ */
+import { Config, type ConfigOptions } from "./config.js";
+import { type FetchLike } from "./http.js";
+import { type CreateInvoiceOptions } from "./invoices.js";
+import { CreateInvoiceResponse, Invoice } from "./models/invoice.js";
+import type { WebhookEvent } from "./models/webhook.js";
+import { WebhookVerifier } from "./webhooks/verifier.js";
+/** Stable idempotency key: zerokyc:{platform}:{entity}:{id} (max 120 chars). */
+export declare function idempotencyKey(...parts: Array<string | number>): string;
+export interface RequestCallOptions {
+    signal?: AbortSignal;
+}
+/** Injectable delay: sync fire-and-forget or (default) a real Promise-based
+ *  sleep that actually waits; the retry loop awaits either form. */
+export type Sleeper = (ms: number) => void | Promise<void>;
+export declare class ZeroKYC {
+    readonly config: Config;
+    private readonly fetchLike;
+    private readonly sleeper;
+    constructor(options?: ConfigOptions & {
+        fetchImpl?: FetchLike;
+        /** Injectable for tests; default is a real Promise-based sleep. */
+        sleeper?: Sleeper;
+    });
+    /** Create an invoice; with an idempotency key a timeout+retry returns the
+     *  same invoice instead of creating a duplicate. */
+    createInvoice(options: CreateInvoiceOptions & RequestCallOptions): Promise<CreateInvoiceResponse>;
+    /** Reconciliation/recovery: poll a status server-to-server. */
+    getInvoice(invoiceId: string, options?: RequestCallOptions): Promise<Invoice>;
+    cancelInvoice(invoiceId: string, options?: RequestCallOptions): Promise<Invoice>;
+    /** Liveness/configuration probe; returns the decoded /v1/ping body. */
+    ping(options?: RequestCallOptions): Promise<Record<string, unknown>>;
+    /** Verify a delivery; throws WebhookVerificationError on any failure. */
+    verifyWebhook(rawBody: string | Uint8Array, signatureHeader: string, options?: {
+        secret?: string;
+    }): WebhookEvent;
+    verifier(secret?: string): WebhookVerifier;
+    /** Await the sleeper; a caller abort during the wait stops the retry loop. */
+    private wait;
+    private request;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,MAAM,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AAQzD,OAAO,EAAgD,KAAK,SAAS,EAAqB,MAAM,WAAW,CAAC;AAC5G,OAAO,EAAsB,KAAK,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAC9E,OAAO,EAAE,qBAAqB,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACrE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAKzD,gFAAgF;AAChF,wBAAgB,cAAc,CAAC,GAAG,KAAK,EAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,GAAG,MAAM,CASvE;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;oEACoE;AACpE,MAAM,MAAM,OAAO,GAAG,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAO3D,qBAAa,OAAO;IAClB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA0D;IACpF,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;gBAGhC,OAAO,GAAE,aAAa,GAAG;QACvB,SAAS,CAAC,EAAE,SAAS,CAAC;QACtB,mEAAmE;QACnE,OAAO,CAAC,EAAE,OAAO,CAAC;KACF;IAOpB;wDACoD;IAC9C,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,kBAAkB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAkBvG,+DAA+D;IACzD,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,OAAO,CAAC;IASjF,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,OAAO,CAAC;IAe1F,uEAAuE;IACjE,IAAI,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAS9E,yEAAyE;IACzE,aAAa,CACX,OAAO,EAAE,MAAM,GAAG,UAAU,EAC5B,eAAe,EAAE,MAAM,EACvB,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO,GAChC,YAAY;IAIf,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,eAAe;IAI1C,8EAA8E;YAChE,IAAI;YAgBJ,OAAO;CAoEtB"}

package/dist/client.js

@@ -0,0 +1,228 @@
+/**
+ * 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.
+ */
+import { Config } from "./config.js";
+import { APIError, AuthenticationError, NetworkError, RateLimitError, ValidationError, } from "./errors.js";
+import { fetchTransport, sdkUserAgent } from "./http.js";
+import { buildCreatePayload } from "./invoices.js";
+import { CreateInvoiceResponse, Invoice } from "./models/invoice.js";
+import { WebhookVerifier } from "./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). */
+export function idempotencyKey(...parts) {
+    const key = `zerokyc:${parts.join(":")}`;
+    if (!key) {
+        throw new ValidationError("idempotency key must not be empty");
+    }
+    if (key.length > 120) {
+        throw new ValidationError("idempotency key must be at most 120 characters");
+    }
+    return key;
+}
+const defaultSleeper = (ms) => new Promise((resolve) => {
+    setTimeout(resolve, ms);
+});
+export class ZeroKYC {
+    config;
+    fetchLike;
+    sleeper;
+    constructor(options = { apiKey: "" }) {
+        this.config = new Config(options);
+        this.fetchLike = options.fetchImpl ?? 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 = 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 CreateInvoiceResponse(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.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.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 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 NetworkError("aborted while waiting to retry");
+        }
+        await new Promise((resolve, reject) => {
+            const onAbort = () => reject(new 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": sdkUserAgent(),
+                        ...opts.headers,
+                    },
+                    body: opts.body,
+                    signal: opts.signal,
+                    redirect: "manual",
+                    timeoutMs: this.config.timeoutMs,
+                });
+            }
+            catch (e) {
+                if (!(e instanceof 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);
+        }
+    }
+}
+function parseJson(response) {
+    try {
+        return JSON.parse(response.body);
+    }
+    catch {
+        throw new 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 AuthenticationError(message);
+    }
+    if (response.status === 429) {
+        return new RateLimitError(message, parseRetryAfter(response.header("Retry-After")));
+    }
+    if (response.status === 400 || response.status === 422) {
+        return new ValidationError(message);
+    }
+    return new 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/config.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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.
+ */
+export declare const DEFAULT_BASE_URL = "https://api.zerokyc-payments.com";
+export declare const SANDBOX = "sandbox";
+export declare const PRODUCTION = "production";
+export type Environment = typeof SANDBOX | typeof PRODUCTION;
+export interface ConfigOptions {
+    apiKey: string;
+    environment?: Environment;
+    webhookSecret?: string;
+    timeoutMs?: number;
+    maxRetries?: number;
+    baseUrl?: string;
+}
+export declare class Config {
+    readonly apiKey: string;
+    readonly environment: Environment;
+    readonly webhookSecret: string;
+    readonly timeoutMs: number;
+    readonly maxRetries: number;
+    readonly baseUrl: string;
+    constructor(options: ConfigOptions);
+    get isSandbox(): boolean;
+}
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAO,MAAM,gBAAgB,qCAAqC,CAAC;AAEnE,eAAO,MAAM,OAAO,YAAY,CAAC;AACjC,eAAO,MAAM,UAAU,eAAe,CAAC;AAEvC,MAAM,MAAM,WAAW,GAAG,OAAO,OAAO,GAAG,OAAO,UAAU,CAAC;AAE7D,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,MAAM;IACjB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBAEb,OAAO,EAAE,aAAa;IAqClC,IAAI,SAAS,IAAI,OAAO,CAEvB;CACF"}

package/dist/config.js

@@ -0,0 +1,50 @@
+/**
+ * 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.
+ */
+export const DEFAULT_BASE_URL = "https://api.zerokyc-payments.com";
+export const SANDBOX = "sandbox";
+export const PRODUCTION = "production";
+export 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_") ? SANDBOX : PRODUCTION);
+        if (environment !== SANDBOX && environment !== 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 === 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 === 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 ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    }
+    get isSandbox() {
+        return this.environment === SANDBOX;
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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.
+ */
+export declare class ZeroKYCError extends Error {
+    constructor(message: string);
+}
+/** 401/403 from the API: missing/invalid key or forbidden scope. Never retried. */
+export declare class AuthenticationError extends ZeroKYCError {
+}
+/** 400/422 from the API (or local request validation). Never retried. */
+export declare class ValidationError extends ZeroKYCError {
+}
+/** 429 from the API; `retryAfter` carries Retry-After seconds when parseable. */
+export declare class RateLimitError extends ZeroKYCError {
+    readonly retryAfter: number | null;
+    constructor(message: string, retryAfter?: number | null);
+}
+/** Unexpected API error (5xx, 402 cutoff, 404, malformed envelope). */
+export declare class APIError extends ZeroKYCError {
+    readonly status: number;
+    readonly errorCode?: string | undefined;
+    readonly docUrl?: string | undefined;
+    constructor(message: string, status?: number, errorCode?: string | undefined, docUrl?: string | undefined);
+}
+/** Transport failure: DNS, connect, TLS, timeout or abort. */
+export declare class NetworkError extends ZeroKYCError {
+}
+/** Webhook verification failed; `reason` is machine-readable. */
+export declare class WebhookVerificationError extends ZeroKYCError {
+    readonly reason: string;
+    static readonly MISSING_HEADER = "missing_header";
+    static readonly MALFORMED_HEADER = "malformed_header";
+    static readonly STALE_TIMESTAMP = "stale_timestamp";
+    static readonly FUTURE_TIMESTAMP = "future_timestamp";
+    static readonly SIGNATURE_MISMATCH = "signature_mismatch";
+    static readonly MALFORMED_PAYLOAD = "malformed_payload";
+    constructor(message: string, reason: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,qBAAa,YAAa,SAAQ,KAAK;gBACzB,OAAO,EAAE,MAAM;CAI5B;AAED,mFAAmF;AACnF,qBAAa,mBAAoB,SAAQ,YAAY;CAAG;AAExD,yEAAyE;AACzE,qBAAa,eAAgB,SAAQ,YAAY;CAAG;AAEpD,iFAAiF;AACjF,qBAAa,cAAe,SAAQ,YAAY;aAG5B,UAAU,EAAE,MAAM,GAAG,IAAI;gBADzC,OAAO,EAAE,MAAM,EACC,UAAU,GAAE,MAAM,GAAG,IAAW;CAInD;AAED,uEAAuE;AACvE,qBAAa,QAAS,SAAQ,YAAY;aAGtB,MAAM,EAAE,MAAM;aACd,SAAS,CAAC,EAAE,MAAM;aAClB,MAAM,CAAC,EAAE,MAAM;gBAH/B,OAAO,EAAE,MAAM,EACC,MAAM,GAAE,MAAU,EAClB,SAAS,CAAC,EAAE,MAAM,YAAA,EAClB,MAAM,CAAC,EAAE,MAAM,YAAA;CAIlC;AAED,8DAA8D;AAC9D,qBAAa,YAAa,SAAQ,YAAY;CAAG;AAEjD,iEAAiE;AACjE,qBAAa,wBAAyB,SAAQ,YAAY;aAUtC,MAAM,EAAE,MAAM;IAThC,MAAM,CAAC,QAAQ,CAAC,cAAc,oBAAoB;IAClD,MAAM,CAAC,QAAQ,CAAC,gBAAgB,sBAAsB;IACtD,MAAM,CAAC,QAAQ,CAAC,eAAe,qBAAqB;IACpD,MAAM,CAAC,QAAQ,CAAC,gBAAgB,sBAAsB;IACtD,MAAM,CAAC,QAAQ,CAAC,kBAAkB,wBAAwB;IAC1D,MAAM,CAAC,QAAQ,CAAC,iBAAiB,uBAAuB;gBAGtD,OAAO,EAAE,MAAM,EACC,MAAM,EAAE,MAAM;CAIjC"}

package/dist/errors.js

@@ -0,0 +1,60 @@
+/**
+ * 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.
+ */
+export class ZeroKYCError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = new.target.name;
+    }
+}
+/** 401/403 from the API: missing/invalid key or forbidden scope. Never retried. */
+export class AuthenticationError extends ZeroKYCError {
+}
+/** 400/422 from the API (or local request validation). Never retried. */
+export class ValidationError extends ZeroKYCError {
+}
+/** 429 from the API; `retryAfter` carries Retry-After seconds when parseable. */
+export class RateLimitError extends ZeroKYCError {
+    retryAfter;
+    constructor(message, retryAfter = null) {
+        super(message);
+        this.retryAfter = retryAfter;
+    }
+}
+/** Unexpected API error (5xx, 402 cutoff, 404, malformed envelope). */
+export class APIError extends ZeroKYCError {
+    status;
+    errorCode;
+    docUrl;
+    constructor(message, status = 0, errorCode, docUrl) {
+        super(message);
+        this.status = status;
+        this.errorCode = errorCode;
+        this.docUrl = docUrl;
+    }
+}
+/** Transport failure: DNS, connect, TLS, timeout or abort. */
+export class NetworkError extends ZeroKYCError {
+}
+/** Webhook verification failed; `reason` is machine-readable. */
+export 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;
+    }
+}

package/dist/http.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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).
+ */
+export interface HttpResponse {
+    status: number;
+    body: string;
+    headers: Record<string, string>;
+    header(name: string): string | null;
+}
+export interface FetchInit {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+    signal?: AbortSignal;
+    redirect: "manual";
+    timeoutMs?: number;
+}
+export type FetchLike = (url: string, init: FetchInit) => Promise<HttpResponse>;
+export declare function httpResponse(status: number, body: string, headers?: Record<string, string>): HttpResponse;
+/**
+ * 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.
+ */
+export declare function fetchTransport(url: string, init: FetchInit): Promise<HttpResponse>;
+/** Identifiable SDK user agent (CDNs commonly block library default UAs). */
+export declare function sdkUserAgent(): string;
+//# sourceMappingURL=http.d.ts.map

package/dist/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;CACrC;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,QAAQ,EAAE,QAAQ,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,SAAS,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;AAEhF,wBAAgB,YAAY,CAC1B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GACnC,YAAY,CAad;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,YAAY,CAAC,CAwCxF;AAED,6EAA6E;AAC7E,wBAAgB,YAAY,IAAI,MAAM,CAErC"}

package/dist/http.js

@@ -0,0 +1,73 @@
+/**
+ * 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).
+ */
+import { NetworkError } from "./errors.js";
+import { VERSION } from "./version.js";
+export 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.
+ */
+export 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 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 NetworkError(`transport failure: ${e.message}`);
+    }
+    finally {
+        clearTimeout(timer);
+        caller?.removeEventListener("abort", onCallerAbort);
+    }
+}
+/** Identifiable SDK user agent (CDNs commonly block library default UAs). */
+export function sdkUserAgent() {
+    return `zerokyc-node/${VERSION}`;
+}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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.
+ */
+export { ZeroKYC, idempotencyKey } from "./client.js";
+export { Config, DEFAULT_BASE_URL } from "./config.js";
+export { Invoice, CreateInvoiceResponse, type PaymentOption, type InvoiceObservation, type InvoiceData, } from "./models/invoice.js";
+export { WebhookEvent, type VerificationResult } from "./models/webhook.js";
+export { WebhookVerifier, DEFAULT_TOLERANCE_SECONDS } from "./webhooks/verifier.js";
+export { ReplayGuard, compareDecimals, type EventStore, type MatchOrderOptions } from "./replay.js";
+export { StatusMapper, isTerminalStatus, type InvoiceStatus } from "./status.js";
+export { ZeroKYCError, AuthenticationError, ValidationError, RateLimitError, APIError, NetworkError, WebhookVerificationError, } from "./errors.js";
+export { VERSION } from "./version.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EACL,OAAO,EACP,qBAAqB,EACrB,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,WAAW,GACjB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,YAAY,EAAE,KAAK,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC5E,OAAO,EAAE,eAAe,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAC;AACpF,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,KAAK,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACpG,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,KAAK,aAAa,EAAE,MAAM,aAAa,CAAC;AACjF,OAAO,EACL,YAAY,EACZ,mBAAmB,EACnB,eAAe,EACf,cAAc,EACd,QAAQ,EACR,YAAY,EACZ,wBAAwB,GACzB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,15 @@
+/**
+ * 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.
+ */
+export { ZeroKYC, idempotencyKey } from "./client.js";
+export { Config, DEFAULT_BASE_URL } from "./config.js";
+export { Invoice, CreateInvoiceResponse, } from "./models/invoice.js";
+export { WebhookEvent } from "./models/webhook.js";
+export { WebhookVerifier, DEFAULT_TOLERANCE_SECONDS } from "./webhooks/verifier.js";
+export { ReplayGuard, compareDecimals } from "./replay.js";
+export { StatusMapper, isTerminalStatus } from "./status.js";
+export { ZeroKYCError, AuthenticationError, ValidationError, RateLimitError, APIError, NetworkError, WebhookVerificationError, } from "./errors.js";
+export { VERSION } from "./version.js";