@pandait.tech/payment-nuvei 0.1.0

package/dist/handlers/index.d.ts

@@ -0,0 +1,413 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { Auth } from 'firebase-admin/auth';
+import { Firestore } from 'firebase-admin/firestore';
+
+/** Firestore document shape — handlers treat data as generic records. Consumer's onPaymentSucceeded callback gets the full doc and can cast to its own typed Order. */
+type FirestoreData = Record<string, unknown>;
+/** Order shape the handler reads/writes. Permissive on purpose — consumer extends. */
+interface MinimalOrder extends FirestoreData {
+    id?: string;
+    status?: string;
+    userId?: string;
+    items?: Array<{
+        productId: string;
+        name: string;
+        price: number;
+        quantity: number;
+    }>;
+    total?: number;
+    subtotal?: number;
+    vat?: number;
+    discount?: number;
+    promotionId?: string;
+    couponCode?: string;
+    shippingAddress?: {
+        fullName?: string;
+    } & FirestoreData;
+    postPurchaseNote?: string;
+    paymentLinkId?: string;
+    tallerId?: string;
+    courseId?: string;
+    /** Set by charge.ts when the user opted out of saving the card AND the order
+     *  enters an intermediate status (3ds-pending / otp-pending). The downstream
+     *  handler that finalizes the payment (3ds-complete, webhook BY_CRES) reads
+     *  these to call deleteCard on the SDK once the order transitions to paid. */
+    deleteCardAfterPayment?: boolean;
+    /** Nuvei card token. Persisted alongside deleteCardAfterPayment so the
+     *  downstream handler can pass it to deleteCard(token, userId). */
+    paymentToken?: string;
+}
+/** Args passed to email.sendPaymentConfirmation. */
+interface PaymentConfirmationArgs {
+    to: string;
+    customerName: string;
+    orderId: string;
+    transactionId: string;
+    authorizationCode: string;
+    items: MinimalOrder["items"];
+    subtotal: number;
+    discount?: number;
+    couponCode?: string;
+    vat: number;
+    total: number;
+    postPurchaseNote?: string;
+}
+/** Args passed to email.sendPaymentFailed. `retryUrl` is optional — consumers' email templates typically have their own absolute default (e.g. `https://shop.example.com/checkout`). If the handler's `getRetryUrl` dep is not configured, this field is omitted and the template default applies. */
+interface PaymentFailedArgs {
+    to: string;
+    customerName: string;
+    orderId: string;
+    errorMessage: string;
+    items: MinimalOrder["items"];
+    total: number;
+    retryUrl?: string;
+}
+/** Args passed to email.sendPaymentPending (webhook fallback when auth_code missing). */
+interface PaymentPendingArgs {
+    to: string;
+    customerName: string;
+    orderId: string;
+    transactionId: string;
+    items: MinimalOrder["items"];
+    subtotal: number;
+    discount?: number;
+    couponCode?: string;
+    vat: number;
+    total: number;
+}
+/** Email service contract — full surface used across all handlers. Each handler factory picks which methods it requires via Pick<>. */
+interface EmailService {
+    sendPaymentConfirmation: (args: PaymentConfirmationArgs) => Promise<{
+        success: boolean;
+    }>;
+    sendPaymentFailed: (args: PaymentFailedArgs) => Promise<unknown>;
+    sendPaymentPending: (args: PaymentPendingArgs) => Promise<unknown>;
+}
+/** Firebase admin services the handler needs. */
+interface FirebaseDeps {
+    db: Firestore;
+    auth: Auth;
+}
+/** Rate limit check. Returns true if allowed, false if rate-limited. */
+type RateLimitFn = (key: string, limit: number, windowMs: number) => Promise<boolean>;
+/** Turnstile (Cloudflare bot protection) verification. */
+type TurnstileFn = (token: string, ip?: string) => Promise<{
+    success: boolean;
+}>;
+/** Pricing function — receives product data, returns the effective final subtotal. */
+type GetPriceDisplayFn = (product: {
+    price: number;
+    autoDiscounts?: unknown;
+}) => {
+    finalSubtotal: number;
+};
+/** Custom order validation result. Used for non-standard order flows (paymentLinks, talleres). */
+type CustomOrderValidationResult = {
+    handled: false;
+} | {
+    handled: true;
+    valid: true;
+} | {
+    handled: true;
+    valid: false;
+    error: string;
+    status: number;
+};
+/** Custom order validator. Receives the order doc + amount; returns whether this is a custom-flow order and whether it's valid. */
+type ValidateCustomOrderFn = (args: {
+    orderId: string;
+    orderData: MinimalOrder;
+    amount: number;
+}) => Promise<CustomOrderValidationResult>;
+
+/** Dependencies the charge handler factory needs. */
+interface ChargeHandlerDeps {
+    /** Firebase Admin services. Provided by the consumer (so the package never owns its own Firebase init). */
+    firebase: FirebaseDeps;
+    /** Email service. Consumer wires up Resend (or any provider) with their own branding/templates. */
+    email: EmailService;
+    /** Pricing function — receives product fields and returns the effective final subtotal. Consumer-specific because pricing rules vary per business. */
+    getPriceDisplay: GetPriceDisplayFn;
+    /** Merchant name. Used as fallback for the Nuvei transaction description when the request body doesn't provide one (visible to the cardholder in their bank statement). */
+    merchantName: string;
+    /** Optional rate limit check. If omitted, no rate limiting is applied. */
+    rateLimit?: RateLimitFn;
+    /** Optional Turnstile (Cloudflare bot protection) verification. If omitted, the turnstileToken from the body is ignored. */
+    turnstile?: TurnstileFn;
+    /** Optional Cloud Functions base URL for the 3DS challenge callback (termUrl). If omitted, falls back to `process.env.CLOUD_FUNCTIONS_BASE_URL`. */
+    cloudFunctionsBaseUrl?: string;
+    /** Optional custom order validator — used for non-standard order flows (e.g. paymentLinks, taller-specific orders). If returned result is `{ handled: false }` the handler runs standard product/promotion validation. */
+    validateCustomOrder?: ValidateCustomOrderFn;
+    /** Optional post-success hook — runs after the order is marked paid and the Firestore batch commits. Use this for course enrollment, paymentLink usage tracking, fulfillment triggers, etc. Errors are caught and logged but don't fail the response. */
+    onPaymentSucceeded?: (order: MinimalOrder & {
+        id: string;
+    }) => Promise<void>;
+    /** Optional retry URL builder for payment-failed emails. Receives the order, returns the URL the customer should be sent to. Default: `https://${request.host}/checkout`. */
+    getRetryUrl?: (order: MinimalOrder & {
+        id: string;
+    }) => string;
+    /** Optional logger (defaults to console). */
+    logger?: Pick<Console, "log" | "error" | "warn">;
+}
+/**
+ * Creates a Next.js App Router POST handler for the `/api/payment/charge` endpoint.
+ *
+ * Performs: session verification, rate limiting, Turnstile, order/stock/price/coupon
+ * validation, Nuvei debit call, 3DS/OTP handling, Firestore order updates, email
+ * dispatch, and optional post-success side effects via `onPaymentSucceeded`.
+ */
+declare function createChargeHandler(deps: ChargeHandlerDeps): (request: NextRequest) => Promise<NextResponse<{
+    error: string;
+}> | NextResponse<{
+    success: boolean;
+    transactionId: string;
+    authorizationCode: string | null;
+    orderId: string;
+    emailSent: boolean;
+}> | NextResponse<{
+    review: boolean;
+    orderId: string;
+    transactionId: string;
+}> | NextResponse<{
+    challenge: boolean;
+    challengeHtml: string;
+    isDeviceFingerprint: boolean;
+    orderId: string;
+    nuveiTransactionId: string;
+    statusDetail: number;
+}> | NextResponse<{
+    otpRequired: boolean;
+    orderId: string;
+    nuveiTransactionId: string;
+    statusDetail: number;
+}>>;
+
+interface NuveiWebhookPayload {
+    transaction: {
+        id: string;
+        status: string;
+        status_detail: number;
+        dev_reference: string;
+        amount: number;
+        authorization_code: string | null;
+        message: string | null;
+        carrier_code: string | null;
+    };
+    user: {
+        id: string;
+        email: string;
+    };
+}
+/** Dependencies the webhook handler factory needs. */
+interface WebhookHandlerDeps {
+    firebase: FirebaseDeps;
+    email: Pick<EmailService, "sendPaymentConfirmation" | "sendPaymentPending">;
+    /** Optional post-success hook. Fires when the webhook transitions an order to "paid" (either via direct status_detail=3 or via verify BY_CRES). Used for enrollment, fulfillment triggers, paymentLink usage tracking, etc. */
+    onPaymentSucceeded?: (order: MinimalOrder & {
+        id: string;
+    }) => Promise<void>;
+    /** Optional custom dev_reference handler. If the webhook's `transaction.dev_reference` matches a custom format (e.g. "pn_<id>" for Plan Novios), the consumer returns a NextResponse and the standard order flow is skipped. Return null to fall through to standard order processing. */
+    handleCustomDevReference?: (devReference: string, transaction: NuveiWebhookPayload["transaction"], payload: NuveiWebhookPayload) => Promise<NextResponse | null>;
+    logger?: Pick<Console, "log" | "error" | "warn">;
+}
+/**
+ * Creates a Next.js App Router POST handler for the Nuvei webhook callback.
+ * Reference: https://developers.paymentez.com/api/#webhook
+ */
+declare function createWebhookHandler(deps: WebhookHandlerDeps): (request: NextRequest) => Promise<NextResponse<unknown>>;
+
+/** Dependencies the 3DS callback handler factory needs. */
+interface ThreeDSCallbackHandlerDeps {
+    firebase: {
+        db: Firestore;
+    };
+    logger?: Pick<Console, "log" | "error" | "warn">;
+}
+/**
+ * Creates a Next.js App Router route module for the 3DS callback endpoint.
+ * Returns `{ POST, GET }` because the ACS may call either depending on bank/issuer.
+ *
+ * Usage:
+ *   export const { POST, GET } = create3dsCallbackHandler({ firebase: { db } });
+ */
+declare function create3dsCallbackHandler(deps: ThreeDSCallbackHandlerDeps): {
+    POST: (request: NextRequest) => Promise<NextResponse<unknown>>;
+    GET: (request: NextRequest) => Promise<NextResponse<unknown>>;
+};
+
+/** Dependencies the 3DS complete handler factory needs. */
+interface ThreeDSCompleteHandlerDeps {
+    firebase: FirebaseDeps;
+    email: Pick<EmailService, "sendPaymentConfirmation" | "sendPaymentFailed">;
+    /** Optional post-success hook for consumer-specific side effects after verify succeeds. */
+    onPaymentSucceeded?: (order: MinimalOrder & {
+        id: string;
+    }) => Promise<void>;
+    /** Optional retry URL builder for payment-failed emails sent when 3DS verification fails or the auth status is rejected. If omitted, the consumer's email template default is used. */
+    getRetryUrl?: (order: MinimalOrder & {
+        id: string;
+    }) => string;
+    logger?: Pick<Console, "log" | "error" | "warn">;
+}
+/**
+ * Creates a Next.js App Router POST handler for the 3DS complete endpoint.
+ * Called by the client after challenge completion to finalize the payment.
+ */
+declare function create3dsCompleteHandler(deps: ThreeDSCompleteHandlerDeps): (request: NextRequest) => Promise<NextResponse<{
+    error: string;
+}> | NextResponse<{
+    success: boolean;
+    transactionId: unknown;
+    authorizationCode: {} | null;
+    orderId: string;
+}> | NextResponse<{
+    stillPending: boolean;
+}> | NextResponse<{
+    challenge: boolean;
+    challengeHtml: string;
+    isDeviceFingerprint: boolean;
+    orderId: string;
+    nuveiTransactionId: {};
+    statusDetail: number;
+}>>;
+
+/** Dependencies the 3DS timeout handler factory needs. */
+interface ThreeDSTimeoutHandlerDeps {
+    firebase: FirebaseDeps;
+    email: Pick<EmailService, "sendPaymentFailed">;
+    /** Optional retry URL builder. Default: "/checkout". */
+    getRetryUrl?: (order: MinimalOrder & {
+        id: string;
+    }) => string;
+    logger?: Pick<Console, "log" | "error" | "warn">;
+}
+declare function create3dsTimeoutHandler(deps: ThreeDSTimeoutHandlerDeps): (request: NextRequest) => Promise<NextResponse<{
+    error: string;
+}> | NextResponse<{
+    alreadyResolved: boolean;
+}> | NextResponse<{
+    ok: boolean;
+}>>;
+
+/** Dependencies the refund handler factory needs. */
+interface RefundHandlerDeps {
+    firebase: FirebaseDeps;
+    /** Optional hook after a successful refund (e.g. revoke course access, send email). */
+    onRefundSucceeded?: (order: MinimalOrder & {
+        id: string;
+    }) => Promise<void>;
+    logger?: Pick<Console, "log" | "error" | "warn">;
+}
+declare function createRefundHandler(deps: RefundHandlerDeps): (request: NextRequest) => Promise<NextResponse<{
+    error: string;
+}> | NextResponse<{
+    success: boolean;
+    detail: string;
+}>>;
+
+/** Dependencies the init-checkout handler factory needs. */
+interface InitCheckoutHandlerDeps {
+    firebase: {
+        auth: Auth;
+    };
+    /** Default description shown to the customer in the Nuvei checkout if the request body doesn't provide one. Use the merchant name (e.g. "Pago Acme Shop"). */
+    defaultDescription: string;
+    /** Theme colors for the Nuvei checkout modal. */
+    themeColors: {
+        primary: string;
+        secondary: string;
+    };
+    logger?: Pick<Console, "log" | "error" | "warn">;
+}
+declare function createInitCheckoutHandler(deps: InitCheckoutHandlerDeps): (request: NextRequest) => Promise<NextResponse<{
+    error: string;
+}> | NextResponse<{
+    reference: string;
+    checkoutUrl: string | undefined;
+}>>;
+
+/** Dependencies the cards handler factory needs. */
+interface CardsHandlerDeps {
+    firebase: FirebaseDeps;
+    /** Whether to consult users/{uid}/verifiedCards to upgrade "review" status to "valid" client-side. Defaults to true. Set false if your client doesn't use the Diners/Pichincha verify flow. */
+    enableVerifiedCardsTracking?: boolean;
+    logger?: Pick<Console, "log" | "error" | "warn">;
+}
+/**
+ * Creates a Next.js App Router route module for the cards endpoint.
+ * Returns `{ GET, DELETE }` to be re-exported by the consumer's route.ts.
+ *
+ * Usage:
+ *   export const { GET, DELETE } = createCardsHandler({ firebase: { db, auth } });
+ */
+declare function createCardsHandler(deps: CardsHandlerDeps): {
+    GET: (request: NextRequest) => Promise<NextResponse<{
+        error: string;
+    }> | NextResponse<{
+        cards: {
+            bin: string;
+            status: string;
+            token: string;
+            holder_name: string;
+            expiry_year: string;
+            expiry_month: string;
+            transaction_reference: string;
+            type: string;
+            number: string;
+        }[];
+    }>>;
+    DELETE: (request: NextRequest) => Promise<NextResponse<{
+        error: string;
+    }> | NextResponse<{
+        message: string;
+    }>>;
+};
+
+/** Dependencies the verify handler factory needs. */
+interface VerifyHandlerDeps {
+    firebase: FirebaseDeps;
+    /** Whether to persist verification in users/{uid}/verifiedCards/{token}. Defaults to true. */
+    enableVerifiedCardsTracking?: boolean;
+    logger?: Pick<Console, "log" | "error" | "warn">;
+}
+declare function createVerifyHandler(deps: VerifyHandlerDeps): (request: NextRequest) => Promise<NextResponse<{
+    error: string;
+}> | NextResponse<{
+    success: boolean;
+    transaction: {
+        status: string;
+        status_detail: number;
+        id: string;
+        message: string | null;
+    } | undefined;
+}>>;
+
+/** Dependencies the test-charge handler factory needs. */
+interface TestChargeHandlerDeps {
+    firebase: {
+        auth: Auth;
+    };
+    /** Default description shown in Nuvei when the request body omits one. Defaults to "Test charge". */
+    defaultDescription?: string;
+    logger?: Pick<Console, "log" | "error" | "warn">;
+}
+declare function createTestChargeHandler(deps: TestChargeHandlerDeps): (request: NextRequest) => Promise<NextResponse<{
+    error: string;
+}> | NextResponse<{
+    success: boolean;
+    transaction: {
+        status: string;
+        current_status: string;
+        id: string;
+        message: string | null;
+        status_detail: number;
+        authorization_code: string | null;
+    };
+    card: {
+        bin: string;
+        type: string;
+        number: string;
+    } | undefined;
+}>>;
+
+export { type CardsHandlerDeps, type ChargeHandlerDeps, type CustomOrderValidationResult, type EmailService, type FirebaseDeps, type FirestoreData, type GetPriceDisplayFn, type InitCheckoutHandlerDeps, type MinimalOrder, type PaymentConfirmationArgs, type PaymentFailedArgs, type PaymentPendingArgs, type RateLimitFn, type RefundHandlerDeps, type TestChargeHandlerDeps, type ThreeDSCallbackHandlerDeps, type ThreeDSCompleteHandlerDeps, type ThreeDSTimeoutHandlerDeps, type TurnstileFn, type ValidateCustomOrderFn, type VerifyHandlerDeps, type WebhookHandlerDeps, create3dsCallbackHandler, create3dsCompleteHandler, create3dsTimeoutHandler, createCardsHandler, createChargeHandler, createInitCheckoutHandler, createRefundHandler, createTestChargeHandler, createVerifyHandler, createWebhookHandler };