zkp-sdk-node 0.1.0

package/dist/invoices.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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.
+ */
+export interface CreateInvoiceOptions {
+    /** Decimal string, e.g. "19.90". */
+    amount: string;
+    /** Base currency: "USD" | "EUR" | "RUB" | asset id. Default "USD". */
+    currency?: string;
+    paymentCurrency?: string;
+    orderId?: string;
+    description?: string;
+    ttlMinutes?: number;
+    webhookUrl?: string;
+    successUrl?: string;
+    metadata?: Record<string, unknown>;
+    idempotencyKey?: string;
+}
+export interface CreateInvoicePayload {
+    amount: string;
+    base_currency: string;
+    payment_currency: string;
+    order_id?: string;
+    description?: string;
+    ttl_minutes?: number;
+    webhook_url?: string;
+    success_url?: string;
+    metadata?: Record<string, unknown>;
+}
+export declare function buildCreatePayload(options: CreateInvoiceOptions): CreateInvoicePayload;
+//# sourceMappingURL=invoices.d.ts.map

package/dist/invoices.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invoices.d.ts","sourceRoot":"","sources":["../src/invoices.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH,MAAM,WAAW,oBAAoB;IACnC,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,oBAAoB,GAAG,oBAAoB,CAuDtF"}

package/dist/invoices.js

@@ -0,0 +1,71 @@
+/**
+ * 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.
+ */
+import { ValidationError } from "./errors.js";
+/** Plain decimal only: no sign, no exponent, no NaN/Infinity spellings. */
+const AMOUNT_RE = /^[0-9]+(?:\.[0-9]+)?$/;
+export function buildCreatePayload(options) {
+    const { amount } = options;
+    if (typeof amount !== "string" || !AMOUNT_RE.test(amount)) {
+        throw new 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 ValidationError(`amount must be a positive finite decimal, got ${JSON.stringify(amount)}`);
+    }
+    const currency = options.currency ?? "USD";
+    if (!currency) {
+        throw new ValidationError("currency must not be empty");
+    }
+    if (options.ttlMinutes !== undefined &&
+        (!Number.isInteger(options.ttlMinutes) ||
+            options.ttlMinutes < 10 || options.ttlMinutes > 4320)) {
+        throw new ValidationError("ttlMinutes must be an integer between 10 and 4320");
+    }
+    if (options.orderId !== undefined && options.orderId.length > 255) {
+        throw new ValidationError("orderId must be at most 255 characters");
+    }
+    if (options.description !== undefined && options.description.length > 500) {
+        throw new ValidationError("description must be at most 500 characters");
+    }
+    if (options.webhookUrl !== undefined && options.webhookUrl.length > 2000) {
+        throw new ValidationError("webhookUrl must be at most 2000 characters");
+    }
+    if (options.successUrl !== undefined && options.successUrl.length > 2000) {
+        throw new 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/models/invoice.d.ts

@@ -0,0 +1,82 @@
+/** Typed invoice models (create + get responses share the shape). */
+import { type InvoiceStatus } from "../status.js";
+export interface PaymentOption {
+    asset: string;
+    network: string;
+    payment_address: string;
+    amount_crypto: string;
+    rate: string;
+    status: string;
+    window_low?: string | null;
+    window_high?: string | null;
+    payment_url_extra?: string | null;
+    confirmed_tx_hash?: string | null;
+    [key: string]: unknown;
+}
+export interface InvoiceObservation {
+    option_id: string;
+    tx_hash: string;
+    output_index: number;
+    amount_paid: string;
+    confirmations: number;
+    seen_at: string;
+    [key: string]: unknown;
+}
+export interface InvoiceData {
+    id: string;
+    order_id?: string | null;
+    description?: string | null;
+    amount: string;
+    base_currency: string;
+    payment_currency: string;
+    status: string;
+    ttl_minutes: number;
+    expires_at: string;
+    created_at: string;
+    checkout_url: string;
+    metadata: Record<string, unknown>;
+    options: PaymentOption[];
+    observations: InvoiceObservation[];
+    paid_amount?: string | null;
+    paid_asset?: string | null;
+    [key: string]: unknown;
+}
+export declare class Invoice {
+    readonly id: string;
+    readonly orderId: string | null;
+    readonly description: string | null;
+    /** Decimal string - never a JS number. */
+    readonly amount: string;
+    readonly baseCurrency: string;
+    readonly paymentCurrency: string;
+    readonly rawStatus: string;
+    readonly status: InvoiceStatus;
+    readonly ttlMinutes: number;
+    readonly expiresAt: string;
+    readonly createdAt: string;
+    readonly checkoutUrl: string;
+    readonly metadata: Record<string, unknown>;
+    readonly options: PaymentOption[];
+    readonly observations: InvoiceObservation[];
+    readonly paidAmount: string | null;
+    readonly paidAsset: string | null;
+    /** Full decoded response (unknown fields preserved). */
+    readonly raw: InvoiceData;
+    private constructor();
+    static fromJson(data: unknown): Invoice;
+    get isPaid(): boolean;
+    get isTerminal(): boolean;
+    /** Payment option by asset id (e.g. "USDT_TRON"), or null. */
+    option(asset: string): PaymentOption | null;
+}
+export declare class CreateInvoiceResponse {
+    readonly invoice: Invoice;
+    /** True when the API returned a previously created invoice for the same
+     *  Idempotency-Key (safe timeout/retry path). */
+    readonly idempotentReplay: boolean;
+    constructor(invoice: Invoice, 
+    /** True when the API returned a previously created invoice for the same
+     *  Idempotency-Key (safe timeout/retry path). */
+    idempotentReplay: boolean);
+}
+//# sourceMappingURL=invoice.d.ts.map

package/dist/models/invoice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invoice.d.ts","sourceRoot":"","sources":["../../src/models/invoice.ts"],"names":[],"mappings":"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"}

package/dist/models/invoice.js

@@ -0,0 +1,184 @@
+/** Typed invoice models (create + get responses share the shape). */
+import { isTerminalStatus, StatusMapper } from "../status.js";
+export 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 = 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 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;
+    }
+}
+export 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;
+    }
+}
+// --- 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/models/webhook.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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).
+ */
+export interface WebhookEventData {
+    id: string;
+    type: string;
+    invoice_id?: string | null;
+    created_at?: string;
+    data?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export declare class WebhookEvent {
+    readonly id: string;
+    readonly type: string;
+    readonly invoiceId: string | null;
+    readonly data: Record<string, unknown>;
+    readonly raw: WebhookEventData;
+    private constructor();
+    static fromJson(payload: unknown): WebhookEvent;
+    get isPaymentConfirmed(): boolean;
+    /**
+     * 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(): string | null;
+    /** Asset the payment arrived in: ticker ("USDT") or asset id ("USDT_TRON"). */
+    get paidAsset(): string | null;
+    /** Network of the paying option ("tron", "polygon", ...), when present. */
+    get paidNetwork(): string | null;
+    private option;
+}
+export interface VerificationResult {
+    valid: boolean;
+    reason: string | null;
+    event: WebhookEvent | null;
+}
+//# sourceMappingURL=webhook.d.ts.map

package/dist/models/webhook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook.d.ts","sourceRoot":"","sources":["../../src/models/webhook.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,qBAAa,YAAY;IACvB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,QAAQ,CAAC,GAAG,EAAE,gBAAgB,CAAC;IAE/B,OAAO;IAUP,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,YAAY;IAsC/C,IAAI,kBAAkB,IAAI,OAAO,CAEhC;IAED;;;;OAIG;IACH,IAAI,UAAU,IAAI,MAAM,GAAG,IAAI,CAO9B;IAED,+EAA+E;IAC/E,IAAI,SAAS,IAAI,MAAM,GAAG,IAAI,CAI7B;IAED,2EAA2E;IAC3E,IAAI,WAAW,IAAI,MAAM,GAAG,IAAI,CAI/B;IAED,OAAO,CAAC,MAAM;CAMf;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC;CAC5B"}

package/dist/models/webhook.js

@@ -0,0 +1,93 @@
+/**
+ * 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).
+ */
+export 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;
+    }
+}

package/dist/replay.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 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.
+ */
+import type { WebhookEvent } from "./models/webhook.js";
+/** Storage backed by your DB: sync (in-memory) or async - both awaited. */
+export interface EventStore {
+    has(eventId: string): boolean | Promise<boolean>;
+    markProcessed(eventId: string): void | Promise<void>;
+}
+/** True only for plain non-negative decimal strings (no float arithmetic). */
+export declare function isValidDecimal(value: string): boolean;
+/**
+ * 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).
+ */
+export declare function compareDecimals(a: string, b: string): number;
+export interface MatchOrderOptions {
+    minAmount?: string;
+    /** Bare ticker ("USDT": any network) or asset id ("USDT_TRON": the webhook
+     *  MUST carry a matching network - a missing network is a mismatch). */
+    asset?: string;
+}
+export declare class ReplayGuard {
+    private readonly store;
+    constructor(store: EventStore);
+    /** Pure check: true when the event was already processed. No side effects. */
+    isDuplicate(eventId: string): Promise<boolean>;
+    /** Call only after the local order update has succeeded. */
+    markProcessed(eventId: string): Promise<void>;
+    /**
+     * 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: WebhookEvent, expectedInvoiceId: string, options?: MatchOrderOptions): boolean;
+}
+//# sourceMappingURL=replay.d.ts.map

package/dist/replay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay.d.ts","sourceRoot":"","sources":["../src/replay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,2EAA2E;AAC3E,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACjD,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtD;AAMD,8EAA8E;AAC9E,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAErD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAiB5D;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;4EACwE;IACxE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,WAAW;IACV,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAL,KAAK,EAAE,UAAU;IAE9C,8EAA8E;IACxE,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIpD,4DAA4D;IACtD,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAInD;;;;OAIG;IACH,YAAY,CACV,KAAK,EAAE,YAAY,EACnB,iBAAiB,EAAE,MAAM,EACzB,OAAO,GAAE,iBAAsB,GAC9B,OAAO;CAkBX"}