awesome-node-checkout 1.0.1 → 1.0.2

package/dist/interfaces/payment-provider.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment-provider.interface.d.ts","sourceRoot":"","sources":["../../src/interfaces/payment-provider.interface.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AACjE,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAE9E,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE5D,MAAM,WAAW,gBAAgB;IAC/B,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAE3B,8FAA8F;IAC9F,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAE/D,mDAAmD;IACnD,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAEzF,2DAA2D;IAC3D,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAE7D,4DAA4D;IAC5D,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAE1E;;;OAGG;IACH,aAAa,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAEvG;;;OAGG;IACH,cAAc,CAAC,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;CACxE"}

package/dist/interfaces/payment-provider.interface.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=payment-provider.interface.js.map

package/dist/interfaces/payment-provider.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment-provider.interface.js","sourceRoot":"","sources":["../../src/interfaces/payment-provider.interface.ts"],"names":[],"mappings":""}

package/dist/interfaces/transaction-store.interface.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Arbitrary data associated with a transaction.
+ * Extended by providers that need to persist state across async flows
+ * (e.g. correlating a Satispay webhook with the original order).
+ */
+export interface TransactionData {
+    provider: string;
+    orderId?: string;
+    paymentId?: string;
+    createdAt: string;
+    metadata?: Record<string, any>;
+    [key: string]: any;
+}
+/**
+ * Abstraction over transaction state persistence.
+ * Built-in: InMemoryTransactionStore.
+ * Implement this interface to use Redis, PostgreSQL, MongoDB, etc.
+ */
+export interface ITransactionStore {
+    save(key: string, data: TransactionData): Promise<void>;
+    get(key: string): Promise<TransactionData | null>;
+    delete(key: string): Promise<void>;
+}
+//# sourceMappingURL=transaction-store.interface.d.ts.map

package/dist/interfaces/transaction-store.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction-store.interface.d.ts","sourceRoot":"","sources":["../../src/interfaces/transaction-store.interface.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC/B,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAAC;IAClD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC"}

package/dist/interfaces/transaction-store.interface.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=transaction-store.interface.js.map

package/dist/interfaces/transaction-store.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction-store.interface.js","sourceRoot":"","sources":["../../src/interfaces/transaction-store.interface.ts"],"names":[],"mappings":""}

package/dist/models/checkout-config.model.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Global configuration for CheckoutConfigurator.
+ */
+export interface CheckoutConfig {
+    /**
+     * When `true`, the event bus emits lifecycle events for every payment
+     * operation (payment.created, payment.completed, payment.failed, etc.).
+     * @default true
+     */
+    emitEvents?: boolean;
+}
+//# sourceMappingURL=checkout-config.model.d.ts.map

package/dist/models/checkout-config.model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkout-config.model.d.ts","sourceRoot":"","sources":["../../src/models/checkout-config.model.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB"}

package/dist/models/checkout-config.model.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=checkout-config.model.js.map

package/dist/models/checkout-config.model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkout-config.model.js","sourceRoot":"","sources":["../../src/models/checkout-config.model.ts"],"names":[],"mappings":""}

package/dist/models/errors.d.ts

@@ -0,0 +1,7 @@
+export type CheckoutErrorCode = 'PROVIDER_NOT_FOUND' | 'PROVIDER_ALREADY_REGISTERED' | 'PAYMENT_FAILED' | 'WEBHOOK_NOT_SUPPORTED' | 'REDIRECT_NOT_SUPPORTED' | 'TRANSACTION_NOT_FOUND';
+export declare class CheckoutError extends Error {
+    readonly code: CheckoutErrorCode;
+    readonly provider?: string | undefined;
+    constructor(message: string, code: CheckoutErrorCode, provider?: string | undefined);
+}
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/models/errors.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,iBAAiB,GACzB,oBAAoB,GACpB,6BAA6B,GAC7B,gBAAgB,GAChB,uBAAuB,GACvB,wBAAwB,GACxB,uBAAuB,CAAC;AAE5B,qBAAa,aAAc,SAAQ,KAAK;aAGpB,IAAI,EAAE,iBAAiB;aACvB,QAAQ,CAAC,EAAE,MAAM;gBAFjC,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,iBAAiB,EACvB,QAAQ,CAAC,EAAE,MAAM,YAAA;CASpC"}

package/dist/models/errors.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CheckoutError = void 0;
+class CheckoutError extends Error {
+    constructor(message, code, provider) {
+        super(message);
+        this.code = code;
+        this.provider = provider;
+        this.name = 'CheckoutError';
+        // Maintains proper stack trace in V8
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, CheckoutError);
+        }
+    }
+}
+exports.CheckoutError = CheckoutError;
+//# sourceMappingURL=errors.js.map

package/dist/models/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/models/errors.ts"],"names":[],"mappings":";;;AAQA,MAAa,aAAc,SAAQ,KAAK;IACtC,YACE,OAAe,EACC,IAAuB,EACvB,QAAiB;QAEjC,KAAK,CAAC,OAAO,CAAC,CAAC;QAHC,SAAI,GAAJ,IAAI,CAAmB;QACvB,aAAQ,GAAR,QAAQ,CAAS;QAGjC,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,qCAAqC;QACrC,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;YAC5B,KAAK,CAAC,iBAAiB,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;CACF;AAbD,sCAaC"}

package/dist/models/payment-request.model.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Unified payment request passed to any provider.
+ * All monetary values are in major currency units (e.g. 9.99 for €9.99).
+ */
+export interface PaymentRequest {
+    /** Amount in major currency units (e.g. 9.99) */
+    amount: number;
+    /** ISO 4217 currency code (e.g. 'EUR', 'USD') */
+    currency: string;
+    /** Human-readable description of the payment */
+    description?: string;
+    /** URL to redirect the user to after a successful payment */
+    returnUrl: string;
+    /** URL to redirect the user to if the payment is cancelled */
+    cancelUrl: string;
+    /** External order identifier from the merchant's system */
+    orderId?: string;
+    /** Arbitrary key-value pairs forwarded to the provider when supported */
+    metadata?: Record<string, any>;
+}
+//# sourceMappingURL=payment-request.model.d.ts.map

package/dist/models/payment-request.model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment-request.model.d.ts","sourceRoot":"","sources":["../../src/models/payment-request.model.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;IAEf,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAC;IAEjB,gDAAgD;IAChD,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,6DAA6D;IAC7D,SAAS,EAAE,MAAM,CAAC;IAElB,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;IAElB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAChC"}

package/dist/models/payment-request.model.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=payment-request.model.js.map

package/dist/models/payment-request.model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment-request.model.js","sourceRoot":"","sources":["../../src/models/payment-request.model.ts"],"names":[],"mappings":""}

package/dist/models/payment-result.model.d.ts

@@ -0,0 +1,23 @@
+/** Unified result returned by all payment operations */
+export interface PaymentResult {
+    success: boolean;
+    /** Provider-specific payment identifier */
+    paymentId?: string;
+    /** Redirect URL for the user (redirect-flow providers: PayPal, Nexi) */
+    approvalUrl?: string;
+    /** Current payment status (provider-specific string, e.g. 'COMPLETED', 'ACCEPTED') */
+    status?: string;
+    /** Error message if success is false */
+    error?: string;
+    /** Raw provider response — useful for debugging or provider-specific fields */
+    raw?: any;
+}
+/** Result returned by handleWebhook() */
+export interface WebhookResult {
+    success: boolean;
+    paymentId?: string;
+    status?: string;
+    error?: string;
+    raw?: any;
+}
+//# sourceMappingURL=payment-result.model.d.ts.map

package/dist/models/payment-result.model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment-result.model.d.ts","sourceRoot":"","sources":["../../src/models/payment-result.model.ts"],"names":[],"mappings":"AAAA,wDAAwD;AACxD,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC;IAEjB,2CAA2C;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,sFAAsF;IACtF,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,+EAA+E;IAC/E,GAAG,CAAC,EAAE,GAAG,CAAC;CACX;AAED,yCAAyC;AACzC,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,GAAG,CAAC;CACX"}

package/dist/models/payment-result.model.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=payment-result.model.js.map

package/dist/models/payment-result.model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment-result.model.js","sourceRoot":"","sources":["../../src/models/payment-result.model.ts"],"names":[],"mappings":""}

package/dist/providers/nexi/nexi.provider.d.ts

@@ -0,0 +1,64 @@
+import { BasePaymentProvider } from '../../abstract/base-payment-provider.abstract';
+import { PaymentRequest } from '../../models/payment-request.model';
+import { PaymentResult } from '../../models/payment-result.model';
+export interface NexiProviderConfig {
+    merchantId: string;
+    macKey: string;
+    /** Optional group identifier */
+    group?: string;
+    /** @default 'sandbox' */
+    environment?: 'sandbox' | 'production';
+}
+/**
+ * Nexi eCommerce provider.
+ * Flow: `redirect` — builds a signed checkout URL, redirects the user to Nexi,
+ * then handles the POST-back via `handleRedirect`.
+ *
+ * Note: Nexi XPay mandates SHA-1 for MAC computation. This is a requirement of
+ * the Nexi API and cannot be changed on the client side.
+ */
+export declare class NexiProvider extends BasePaymentProvider {
+    private readonly config;
+    readonly name = "nexi";
+    readonly flow: "redirect";
+    private readonly apiUrl;
+    constructor(config: NexiProviderConfig);
+    /**
+     * Computes the SHA-1 MAC required by Nexi to authenticate the payment request.
+     * Format: `codTrans={val}divisa={val}importo={val}{macKey}`
+     *
+     * SHA-1 is used here because Nexi XPay mandates it for MAC computation.
+     */
+    private generateMac;
+    /**
+     * Computes the SHA-1 MAC for the status (getPaymentDetails) API call.
+     * Format: `alias={alias}codTrans={codTrans}timestamp={timestamp}{macKey}`
+     */
+    private generateStatusMac;
+    /**
+     * Computes the SHA-1 MAC for the refund (storno) API call.
+     * Format: `alias={alias}codTrans={codTrans}importo={importo}timestamp={timestamp}{macKey}`
+     */
+    private generateRefundMac;
+    /**
+     * Verifies the SHA-1 MAC included in a Nexi POST-back response.
+     * Format: `codTrans={val}esito={val}importo={val}divisa={val}{macKey}`
+     */
+    private verifyResponseMac;
+    createPayment(request: PaymentRequest): Promise<PaymentResult>;
+    /**
+     * Validates the POST-back data from Nexi.
+     * `data` is the query/body object sent by Nexi to the returnUrl.
+     * The MAC is verified before the result is considered authoritative.
+     */
+    executePayment(paymentId: string, data?: Record<string, string>): Promise<PaymentResult>;
+    getPaymentDetails(paymentId: string): Promise<PaymentResult>;
+    refundPayment(paymentId: string, amount?: number): Promise<PaymentResult>;
+    /**
+     * Handles the POST-back from Nexi to the returnUrl.
+     * Nexi sends `esito`, `codTrans`, `importo`, `divisa`, `mac`, etc. as query/body params.
+     * The MAC is verified to ensure the response was not spoofed.
+     */
+    handleRedirect(query: Record<string, string>): Promise<PaymentResult>;
+}
+//# sourceMappingURL=nexi.provider.d.ts.map

package/dist/providers/nexi/nexi.provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nexi.provider.d.ts","sourceRoot":"","sources":["../../../src/providers/nexi/nexi.provider.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,+CAA+C,CAAC;AACpF,OAAO,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACpE,OAAO,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AAElE,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yBAAyB;IACzB,WAAW,CAAC,EAAE,SAAS,GAAG,YAAY,CAAC;CACxC;AAED;;;;;;;GAOG;AACH,qBAAa,YAAa,SAAQ,mBAAmB;IAMvC,OAAO,CAAC,QAAQ,CAAC,MAAM;IALnC,QAAQ,CAAC,IAAI,UAAU;IACvB,QAAQ,CAAC,IAAI,EAAG,UAAU,CAAU;IAEpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEH,MAAM,EAAE,kBAAkB;IAQvD;;;;;OAKG;IACH,OAAO,CAAC,WAAW;IAKnB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAKzB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAUzB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAYnB,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IAiCpE;;;;OAIG;IACG,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC;IAoCxF,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IA2B5D,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAkC/E;;;;OAIG;IACG,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC;CAG5E"}

package/dist/providers/nexi/nexi.provider.js

@@ -0,0 +1,227 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NexiProvider = void 0;
+const crypto = __importStar(require("crypto"));
+const base_payment_provider_abstract_1 = require("../../abstract/base-payment-provider.abstract");
+/**
+ * Nexi eCommerce provider.
+ * Flow: `redirect` — builds a signed checkout URL, redirects the user to Nexi,
+ * then handles the POST-back via `handleRedirect`.
+ *
+ * Note: Nexi XPay mandates SHA-1 for MAC computation. This is a requirement of
+ * the Nexi API and cannot be changed on the client side.
+ */
+class NexiProvider extends base_payment_provider_abstract_1.BasePaymentProvider {
+    constructor(config) {
+        super();
+        this.config = config;
+        this.name = 'nexi';
+        this.flow = 'redirect';
+        this.apiUrl =
+            config.environment === 'production'
+                ? 'https://ecommerce.nexi.it'
+                : 'https://int-ecommerce.nexi.it';
+    }
+    /**
+     * Computes the SHA-1 MAC required by Nexi to authenticate the payment request.
+     * Format: `codTrans={val}divisa={val}importo={val}{macKey}`
+     *
+     * SHA-1 is used here because Nexi XPay mandates it for MAC computation.
+     */
+    generateMac(codTrans, divisa, importoCents) {
+        const raw = `codTrans=${codTrans}divisa=${divisa}importo=${importoCents}${this.config.macKey}`;
+        return crypto.createHash('sha1').update(raw).digest('hex');
+    }
+    /**
+     * Computes the SHA-1 MAC for the status (getPaymentDetails) API call.
+     * Format: `alias={alias}codTrans={codTrans}timestamp={timestamp}{macKey}`
+     */
+    generateStatusMac(alias, codTrans, timestamp) {
+        const raw = `alias=${alias}codTrans=${codTrans}timestamp=${timestamp}${this.config.macKey}`;
+        return crypto.createHash('sha1').update(raw).digest('hex');
+    }
+    /**
+     * Computes the SHA-1 MAC for the refund (storno) API call.
+     * Format: `alias={alias}codTrans={codTrans}importo={importo}timestamp={timestamp}{macKey}`
+     */
+    generateRefundMac(alias, codTrans, importo, timestamp) {
+        const raw = `alias=${alias}codTrans=${codTrans}importo=${importo}timestamp=${timestamp}${this.config.macKey}`;
+        return crypto.createHash('sha1').update(raw).digest('hex');
+    }
+    /**
+     * Verifies the SHA-1 MAC included in a Nexi POST-back response.
+     * Format: `codTrans={val}esito={val}importo={val}divisa={val}{macKey}`
+     */
+    verifyResponseMac(codTrans, esito, importo, divisa, mac) {
+        const raw = `codTrans=${codTrans}esito=${esito}importo=${importo}divisa=${divisa}${this.config.macKey}`;
+        const expected = crypto.createHash('sha1').update(raw).digest('hex');
+        return crypto.timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(mac, 'hex'));
+    }
+    async createPayment(request) {
+        try {
+            const amountCents = Math.round(request.amount * 100);
+            const orderId = request.orderId ?? `ORD-${Date.now()}`;
+            const mac = this.generateMac(orderId, request.currency, amountCents);
+            const params = {
+                alias: this.config.merchantId,
+                importo: amountCents.toString(),
+                divisa: request.currency,
+                codTrans: orderId,
+                url: request.returnUrl,
+                url_back: request.cancelUrl,
+                mac,
+            };
+            if (this.config.group) {
+                params.gruppo = this.config.group;
+            }
+            const approvalUrl = `${this.apiUrl}/ecomm/ecomm/DispatcherServlet?${new URLSearchParams(params)}`;
+            return {
+                success: true,
+                paymentId: orderId,
+                approvalUrl,
+                status: 'CREATED',
+            };
+        }
+        catch (error) {
+            return this.errorResult(error, 'Failed to create Nexi payment');
+        }
+    }
+    /**
+     * Validates the POST-back data from Nexi.
+     * `data` is the query/body object sent by Nexi to the returnUrl.
+     * The MAC is verified before the result is considered authoritative.
+     */
+    async executePayment(paymentId, data) {
+        try {
+            const esito = data?.esito ?? '';
+            const codTrans = data?.codTrans ?? paymentId;
+            const importo = data?.importo ?? '';
+            const divisa = data?.divisa ?? '';
+            const mac = data?.mac ?? '';
+            if (mac) {
+                let macValid;
+                try {
+                    macValid = this.verifyResponseMac(codTrans, esito, importo, divisa, mac);
+                }
+                catch {
+                    macValid = false;
+                }
+                if (!macValid) {
+                    return {
+                        success: false,
+                        paymentId: codTrans,
+                        status: 'FAILED',
+                        error: 'MAC verification failed: response may have been tampered with',
+                    };
+                }
+            }
+            return {
+                success: esito === 'OK',
+                paymentId: codTrans,
+                status: esito === 'OK' ? 'COMPLETED' : 'FAILED',
+                raw: data,
+            };
+        }
+        catch (error) {
+            return this.errorResult(error, 'Failed to execute Nexi payment');
+        }
+    }
+    async getPaymentDetails(paymentId) {
+        try {
+            const timestamp = new Date().toISOString();
+            const mac = this.generateStatusMac(this.config.merchantId, paymentId, timestamp);
+            const params = {
+                alias: this.config.merchantId,
+                codTrans: paymentId,
+                timestamp,
+                mac,
+            };
+            const response = await fetch(`${this.apiUrl}/ecomm/api/vas/igfs/status/plain`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+                body: new URLSearchParams(params),
+            });
+            if (!response.ok)
+                throw new Error(`Nexi API error: ${response.statusText}`);
+            const result = await response.json();
+            return { success: true, paymentId, status: result['status'], raw: result };
+        }
+        catch (error) {
+            return this.errorResult(error, 'Failed to get Nexi payment details');
+        }
+    }
+    async refundPayment(paymentId, amount) {
+        try {
+            const timestamp = new Date().toISOString();
+            const importo = amount ? Math.round(amount * 100).toString() : '';
+            const mac = this.generateRefundMac(this.config.merchantId, paymentId, importo, timestamp);
+            const params = {
+                alias: this.config.merchantId,
+                codTrans: paymentId,
+                importo,
+                timestamp,
+                mac,
+            };
+            const response = await fetch(`${this.apiUrl}/ecomm/api/vas/igfs/storno/plain`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+                body: new URLSearchParams(params),
+            });
+            if (!response.ok)
+                throw new Error(`Nexi API error: ${response.statusText}`);
+            const result = await response.json();
+            return {
+                success: result['esito'] === 'OK',
+                paymentId,
+                status: result['esito'] === 'OK' ? 'REFUNDED' : 'REFUND_FAILED',
+                raw: result,
+            };
+        }
+        catch (error) {
+            return this.errorResult(error, 'Failed to refund Nexi payment');
+        }
+    }
+    /**
+     * Handles the POST-back from Nexi to the returnUrl.
+     * Nexi sends `esito`, `codTrans`, `importo`, `divisa`, `mac`, etc. as query/body params.
+     * The MAC is verified to ensure the response was not spoofed.
+     */
+    async handleRedirect(query) {
+        return this.executePayment(query['codTrans'] ?? '', query);
+    }
+}
+exports.NexiProvider = NexiProvider;
+//# sourceMappingURL=nexi.provider.js.map

package/dist/providers/nexi/nexi.provider.js.map

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

package/dist/providers/paypal/paypal.provider.d.ts

@@ -0,0 +1,33 @@
+import { BasePaymentProvider } from '../../abstract/base-payment-provider.abstract';
+import { PaymentRequest } from '../../models/payment-request.model';
+import { PaymentResult } from '../../models/payment-result.model';
+export interface PayPalProviderConfig {
+    clientId: string;
+    clientSecret: string;
+    /** @default 'sandbox' */
+    environment?: 'sandbox' | 'live';
+}
+/**
+ * PayPal Checkout provider.
+ * Flow: `redirect` — creates an order, redirects the user to PayPal,
+ * then captures the payment on return via `handleRedirect`.
+ */
+export declare class PayPalProvider extends BasePaymentProvider {
+    private readonly config;
+    readonly name = "paypal";
+    readonly flow: "redirect";
+    private client;
+    private ordersController;
+    private paymentsController;
+    constructor(config: PayPalProviderConfig);
+    createPayment(request: PaymentRequest): Promise<PaymentResult>;
+    executePayment(paymentId: string): Promise<PaymentResult>;
+    getPaymentDetails(paymentId: string): Promise<PaymentResult>;
+    refundPayment(paymentId: string, amount?: number): Promise<PaymentResult>;
+    /**
+     * Handles the redirect from PayPal after the user approves the payment.
+     * PayPal appends `token` (order ID) and `PayerID` to the returnUrl.
+     */
+    handleRedirect(query: Record<string, string>): Promise<PaymentResult>;
+}
+//# sourceMappingURL=paypal.provider.d.ts.map

package/dist/providers/paypal/paypal.provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paypal.provider.d.ts","sourceRoot":"","sources":["../../../src/providers/paypal/paypal.provider.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,mBAAmB,EAAE,MAAM,+CAA+C,CAAC;AACpF,OAAO,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACpE,OAAO,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AAElE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,yBAAyB;IACzB,WAAW,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC;CAClC;AAED;;;;GAIG;AACH,qBAAa,cAAe,SAAQ,mBAAmB;IAQzC,OAAO,CAAC,QAAQ,CAAC,MAAM;IAPnC,QAAQ,CAAC,IAAI,YAAY;IACzB,QAAQ,CAAC,IAAI,EAAG,UAAU,CAAU;IAEpC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,gBAAgB,CAAmB;IAC3C,OAAO,CAAC,kBAAkB,CAAqB;gBAElB,MAAM,EAAE,oBAAoB;IAoBnD,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IA0C9D,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAkBzD,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAiB5D,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAuD/E;;;OAGG;IACG,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC;CAU5E"}