@boostengine/payments 1.0.0 → 1.1.0

package/README.md

@@ -1,15 +1,17 @@
 # @boostengine/payments
 
-> **Unified Multi-Gateway Payment Orchestration Layer** for Indian & Global eCommerce. Seamlessly plug in **Razorpay, Cashfree, PhonePe, Paytm, Stripe, and COD** through a single unified API with smart routing, automatic fallbacks, and signature verification.
+> **Unified Multi-Gateway Payment Orchestration Layer** for Indian & Global eCommerce. Seamlessly integrate **Razorpay, Cashfree, PhonePe, Paytm, Stripe, and Cash On Delivery (COD)** through a single unified API with smart routing, automatic fallbacks, Next.js App Router webhook helpers, and React checkout hooks.
 
 ---
 
-## ⚡ Why @boostengine/payments?
+## ⚡ Key Highlights
 
-- 🔌 **Unified API**: Write your payment flow once. Switch or combine Razorpay, Cashfree, PhonePe, or Stripe without rewriting checkout logic.
-- 🛡️ **Smart Fallback**: If your primary payment gateway has a downtime or failure, transactions automatically failover to your secondary gateway!
-- 💱 **Multi-Currency Auto-Routing**: Automatically route USD/EUR to Stripe and INR to Razorpay/Cashfree/PhonePe.
-- 🔐 **Built-in Signature Verification**: Native verification for Razorpay HMAC, Cashfree webhook, PhonePe SHA-256 + Salt `X-VERIFY`, and Stripe webhooks.
+- 🔌 **Universal Checkout API**: Pass standard amounts (e.g. `1499.00`). Subunits (paise/cents) are normalized internally!
+- 🛡️ **High-Availability Fallback**: If your primary gateway is down or bank servers timeout, automatically failover to your secondary gateway!
+- 💱 **Smart Currency Routing**: Automatically route USD/EUR to Stripe and INR to Cashfree/Razorpay/PhonePe.
+- ⚡ **Next.js App Router Native**: 2-line webhook verification with `payments.verifyNextJsWebhook(req, { gateway: 'razorpay' })`.
+- 🏷️ **Normalized Webhook Events**: Standardized events like `'PAYMENT_SUCCESS'`, `'PAYMENT_FAILED'`, `'REFUND_PROCESSED'`.
+- ⚛️ **Client Checkout Hook**: `useBoostPayment()` hook to open Razorpay modals or Cashfree dropin with automatic SDK loading!
 - 🪶 **Zero Dependency Bloat**: Uses native Node.js `fetch` and `crypto`. No 10 heavy third-party vendor SDKs.
 
 ---
@@ -22,18 +24,14 @@ npm install @boostengine/payments
 
 ---
 
-## 🚀 Quickstart
-
-### 1. Initialize PaymentManager
+## 🚀 1. Server-Side Setup (`lib/payments.ts`)
 
 ```typescript
 import { createPaymentManager } from '@boostengine/payments';
 
 export const payments = createPaymentManager({
-  // Default gateway when none is specified
   defaultGateway: 'cashfree',
 
-  // Configure any or all gateways
   gateways: {
     cashfree: {
       appId: process.env.CASHFREE_APP_ID!,
@@ -62,7 +60,7 @@ export const payments = createPaymentManager({
     },
   },
 
-  // Smart Routing & Fallbacks
+  // Smart Routing & Resilience
   smartRouting: {
     currencyMap: {
       USD: 'stripe',
@@ -76,43 +74,131 @@ export const payments = createPaymentManager({
 
 ---
 
-### 2. Create an Order (Single or Multi-Gateway)
+## 💳 2. Unified Order Creation (Server Route)
+
+Always pass standard human currency units (e.g. `1499.00`). Package handles paise/cents conversions automatically:
 
 ```typescript
-// Works identically across Cashfree, Razorpay, PhonePe, Stripe, and COD!
-const order = await payments.createOrder({
-  amount: 1499.00,
-  currency: 'INR',
-  receipt: `order_${Date.now()}`,
-  customer: {
-    name: 'Aman Sharma',
-    email: 'aman@example.com',
-    phone: '9876543210',
-  },
-  // Optionally override gateway per checkout button:
-  // gateway: 'razorpay' | 'phonepe' | 'cashfree' | 'stripe' | 'cod'
-});
+// Next.js Route Handler / Express
+export async function POST(req: Request) {
+  const { amount, customer, chosenGateway } = await req.json();
+
+  const order = await payments.createOrder({
+    amount: 1499.00, // Always in standard currency (e.g. Rs. 1499.00)
+    currency: 'INR',
+    receipt: `order_${Date.now()}`,
+    customer: {
+      name: customer.name,
+      email: customer.email,
+      phone: customer.phone,
+    },
+    gateway: chosenGateway, // or let smartRouting decide
+  });
 
-console.log(order);
-/*
-Output:
-{
-  gateway: 'cashfree',
-  orderId: 'order_1709923812',
-  gatewayOrderId: 'order_1709923812',
-  amount: 1499,
-  currency: 'INR',
-  status: 'CREATED',
-  paymentSessionId: 'session_cf_109283719283', // Ready for Cashfree Dropin
-  redirectUrl: '...',                          // Available for PhonePe / Stripe
-  rawResponse: { ... }
+  return Response.json(order);
+}
+```
+
+---
+
+## 🔥 3. Next.js App Router Webhook (`app/api/webhooks/[gateway]/route.ts`)
+
+No manual stream parsing or signature math required:
+
+```typescript
+import { payments } from '@/lib/payments';
+
+export async function POST(
+  req: Request,
+  { params }: { params: { gateway: string } }
+) {
+  const result = await payments.verifyNextJsWebhook(req, {
+    gateway: params.gateway as any,
+  });
+
+  if (!result.isValid) {
+    return new Response('Invalid Signature', { status: 400 });
+  }
+
+  // Use standardized normalized events across all gateways!
+  switch (result.normalizedEvent) {
+    case 'PAYMENT_SUCCESS':
+      console.log(`✅ Order ${result.orderId} paid successfully! Amount: ${result.amount}`);
+      // Update database: Order status -> PAID
+      break;
+
+    case 'PAYMENT_FAILED':
+      console.log(`❌ Order ${result.orderId} failed.`);
+      break;
+
+    case 'REFUND_PROCESSED':
+      console.log(`🔄 Refund processed for payment ${result.paymentId}`);
+      break;
+  }
+
+  return new Response('OK');
 }
-*/
 ```
 
 ---
 
-### 3. Smart Fallback (High-Availability Checkout)
+## ⚛️ 4. Frontend Checkout Hook (`useBoostPayment`)
+
+Automatically detects gateway, dynamically loads required vendor script, and triggers modals or redirects:
+
+```tsx
+'use client';
+
+import { useBoostPayment } from '@boostengine/payments/react';
+import { useRouter } from 'next/navigation';
+
+export default function CheckoutButton({ cartTotal, customer }) {
+  const router = useRouter();
+  const { openPaymentModal, isProcessing } = useBoostPayment();
+
+  const handleCheckout = async (gateway: 'razorpay' | 'cashfree' | 'phonepe' | 'cod') => {
+    // 1. Call your server API to create order
+    const res = await fetch('/api/orders/create', {
+      method: 'POST',
+      body: JSON.stringify({ amount: cartTotal, customer, chosenGateway: gateway }),
+    });
+    const order = await res.json();
+
+    // 2. Open checkout modal / redirect automatically
+    openPaymentModal({
+      order,
+      name: 'Boost Engine Store',
+      description: 'Order Checkout',
+      themeColor: '#4f46e5',
+      onSuccess: async (response) => {
+        // Automatically called when Razorpay modal succeeds or COD is chosen
+        router.push(`/order-confirmed?id=${response.orderId}`);
+      },
+      onFailure: (err) => {
+        alert(err.message);
+      },
+    });
+  };
+
+  return (
+    <div className="flex gap-2">
+      <button disabled={isProcessing} onClick={() => handleCheckout('razorpay')}>
+        Pay with Razorpay
+      </button>
+      <button disabled={isProcessing} onClick={() => handleCheckout('cashfree')}>
+        Pay with Cashfree
+      </button>
+      <button disabled={isProcessing} onClick={() => handleCheckout('cod')}>
+        Cash On Delivery
+      </button>
+    </div>
+  );
+}
+```
+
+---
+
+## 🛡️ 5. High-Availability Fallback Checkout
 
 If your primary payment gateway experiences bank server outages or 500 errors, automatic fallback routes the order through the next available gateway:
 
@@ -132,53 +218,24 @@ const order = await payments.createOrderWithFallback({
 
 ---
 
-### 4. Verify Payment & Webhooks
+## 🧰 Explicit TypeScript Type Exports
 
 ```typescript
-// 1. Verify frontend checkout completion:
-const verification = await payments.verifyPayment({
-  gateway: 'razorpay',
-  orderId: 'order_123',
-  paymentId: 'pay_456',
-  signature: req.body.razorpay_signature,
-});
-
-if (verification.isSuccessful) {
-  console.log(`Payment confirmed! ID: ${verification.paymentId}`);
-}
-
-// 2. Universal Webhook Authenticator:
-const webhook = await payments.verifyWebhook({
-  gateway: 'cashfree', // or 'razorpay' | 'phonepe' | 'stripe'
-  rawBody: req.rawBody,
-  headers: req.headers,
-});
-
-if (webhook.isValid) {
-  console.log(`Verified webhook event: ${webhook.event}`, webhook.data);
-}
-```
-
----
-
-### 5. Instant Refunds
-
-```typescript
-const refund = await payments.refund({
-  gateway: 'razorpay',
-  paymentId: 'pay_456',
-  amount: 1499.00, // full or partial
-  reason: 'Customer cancelled before dispatch',
-});
-
-console.log('Refund ID:', refund.refundId, 'Status:', refund.status);
+import type {
+  PaymentOrderResult,
+  VerificationResult,
+  RefundResult,
+  WebhookResult,
+  SupportedGateway,
+  NormalizedWebhookEvent,
+  CreateOrderOptions,
+  BoostPaymentOpenOptions,
+} from '@boostengine/payments';
 ```
 
 ---
 
-## 🛠️ CLI Quickstart
-
-Generate an environment template or check supported gateways:
+## 🛠️ CLI Tool
 
 ```bash
 # List all 6 supported gateways

package/dist/index.cjs

@@ -178,6 +178,7 @@ var RazorpayAdapter = class extends BasePaymentAdapter {
       paymentId: payment.id,
       orderId: options.orderId,
       amount: payment.amount / 100,
+      // Normalized back to standard currency units
       currency: payment.currency,
       paymentMethod: payment.method,
       rawResponse: payment
@@ -202,6 +203,7 @@ var RazorpayAdapter = class extends BasePaymentAdapter {
       refundId: res.id,
       paymentId: options.paymentId,
       amount: res.amount / 100,
+      // Normalized to standard currency units
       status: res.status === "processed" ? "SUCCESS" : "PENDING",
       rawResponse: res
     };
@@ -211,32 +213,58 @@ var RazorpayAdapter = class extends BasePaymentAdapter {
     if (!secret) {
       return {
         isValid: false,
+        normalizedEvent: "UNKNOWN",
         gateway: "razorpay",
         error: "Razorpay webhookSecret is not configured."
       };
     }
     const signature = this.getHeader(options.headers, "x-razorpay-signature");
-    if (!signature || typeof signature !== "string") {
+    if (!signature) {
       return {
         isValid: false,
+        normalizedEvent: "UNKNOWN",
         gateway: "razorpay",
-        error: "Missing X-Razorpay-Signature header."
+        error: "Missing x-razorpay-signature header."
       };
     }
     const rawString = typeof options.rawBody === "string" ? options.rawBody : options.rawBody.toString("utf8");
     const expectedSignature = hmacSha256(rawString, secret);
     const isValid = safeCompare(expectedSignature, signature);
-    let parsedData;
+    let parsed;
     try {
-      parsedData = JSON.parse(rawString);
+      parsed = JSON.parse(rawString);
     } catch {
-      parsedData = null;
+      parsed = null;
     }
+    const rawEvent = parsed?.event || "";
+    let normalizedEvent = "UNKNOWN";
+    if (rawEvent === "order.paid" || rawEvent === "payment.captured" || rawEvent === "payment.authorized") {
+      normalizedEvent = "PAYMENT_SUCCESS";
+    } else if (rawEvent === "payment.failed") {
+      normalizedEvent = "PAYMENT_FAILED";
+    } else if (rawEvent === "refund.processed" || rawEvent === "refund.created") {
+      normalizedEvent = "REFUND_PROCESSED";
+    } else if (rawEvent === "refund.failed") {
+      normalizedEvent = "REFUND_FAILED";
+    } else if (rawEvent?.includes("dispute")) {
+      normalizedEvent = "DISPUTE_CREATED";
+    }
+    const paymentEntity = parsed?.payload?.payment?.entity;
+    const orderEntity = parsed?.payload?.order?.entity;
+    const orderId = orderEntity?.receipt || paymentEntity?.order_id || orderEntity?.id;
+    const paymentId = paymentEntity?.id;
+    const amount = paymentEntity?.amount ? paymentEntity.amount / 100 : orderEntity?.amount ? orderEntity.amount / 100 : void 0;
+    const currency = paymentEntity?.currency || orderEntity?.currency;
     return {
       isValid,
+      normalizedEvent,
+      rawEvent,
       gateway: "razorpay",
-      event: parsedData?.event,
-      data: parsedData?.payload
+      orderId,
+      paymentId,
+      amount,
+      currency,
+      data: parsed?.payload
     };
   }
 };
@@ -369,17 +397,41 @@ var CashfreeAdapter = class extends BasePaymentAdapter {
       ).toString("base64");
       isValid = safeCompare(expectedSignature, signature);
     }
-    let parsedData;
+    let parsed;
     try {
-      parsedData = JSON.parse(rawString);
+      parsed = JSON.parse(rawString);
     } catch {
-      parsedData = null;
+      parsed = null;
+    }
+    const rawEvent = parsed?.type || "";
+    let normalizedEvent = "UNKNOWN";
+    if (rawEvent === "PAYMENT_SUCCESS_WEBHOOK") {
+      normalizedEvent = "PAYMENT_SUCCESS";
+    } else if (rawEvent === "PAYMENT_FAILED_WEBHOOK" || rawEvent === "USER_DROPPED_WEBHOOK") {
+      normalizedEvent = "PAYMENT_FAILED";
+    } else if (rawEvent === "REFUND_STATUS_WEBHOOK") {
+      const refundStatus = parsed?.data?.refund?.refund_status;
+      normalizedEvent = refundStatus === "SUCCESS" ? "REFUND_PROCESSED" : "REFUND_FAILED";
+    } else if (rawEvent?.includes("DISPUTE")) {
+      normalizedEvent = "DISPUTE_CREATED";
     }
+    const orderData = parsed?.data?.order;
+    const paymentData = parsed?.data?.payment;
+    const refundData = parsed?.data?.refund;
+    const orderId = orderData?.order_id || refundData?.order_id;
+    const paymentId = paymentData ? String(paymentData.cf_payment_id) : refundData ? String(refundData.cf_payment_id) : void 0;
+    const amount = paymentData?.payment_amount ?? orderData?.order_amount ?? refundData?.refund_amount;
+    const currency = paymentData?.payment_currency || orderData?.order_currency;
     return {
       isValid,
+      normalizedEvent,
+      rawEvent,
       gateway: "cashfree",
-      event: parsedData?.type,
-      data: parsedData?.data
+      orderId,
+      paymentId,
+      amount,
+      currency,
+      data: parsed?.data
     };
   }
 };
@@ -505,17 +557,36 @@ var PhonePeAdapter = class extends BasePaymentAdapter {
     try {
       parsed = JSON.parse(rawString);
     } catch {
-      return { isValid: false, gateway: "phonepe", error: "Invalid JSON payload" };
+      return { isValid: false, normalizedEvent: "UNKNOWN", gateway: "phonepe", error: "Invalid JSON payload" };
     }
     if (!parsed.response) {
-      return { isValid: false, gateway: "phonepe", error: "Missing response field in PhonePe callback" };
+      return { isValid: false, normalizedEvent: "UNKNOWN", gateway: "phonepe", error: "Missing response field in PhonePe callback" };
+    }
+    let decoded = {};
+    try {
+      decoded = JSON.parse(base64Decode(parsed.response));
+    } catch {
+      return { isValid: false, normalizedEvent: "UNKNOWN", gateway: "phonepe", error: "Failed to decode base64 PhonePe response" };
     }
-    const decoded = JSON.parse(base64Decode(parsed.response));
-    decoded.code === "PAYMENT_SUCCESS";
+    const rawEvent = decoded.code || "";
+    let normalizedEvent = "UNKNOWN";
+    if (rawEvent === "PAYMENT_SUCCESS") {
+      normalizedEvent = "PAYMENT_SUCCESS";
+    } else if (rawEvent === "PAYMENT_ERROR" || rawEvent === "PAYMENT_DECLINED") {
+      normalizedEvent = "PAYMENT_FAILED";
+    }
+    const orderId = decoded.data?.merchantTransactionId;
+    const paymentId = decoded.data?.transactionId;
+    const amount = decoded.data?.amount ? decoded.data.amount / 100 : void 0;
     return {
       isValid: true,
+      normalizedEvent,
+      rawEvent,
       gateway: "phonepe",
-      event: decoded.code,
+      orderId,
+      paymentId,
+      amount,
+      currency: "INR",
       data: decoded.data
     };
   }
@@ -630,11 +701,21 @@ var PaytmAdapter = class extends BasePaymentAdapter {
       const params = new URLSearchParams(rawString);
       parsed = Object.fromEntries(params.entries());
     }
-    const isSuccess = parsed?.STATUS === "TXN_SUCCESS" || parsed?.resultInfo?.resultStatus === "TXN_SUCCESS";
+    const rawStatus = parsed?.STATUS || parsed?.resultInfo?.resultStatus;
+    const isSuccess = rawStatus === "TXN_SUCCESS";
+    const normalizedEvent = isSuccess ? "PAYMENT_SUCCESS" : "PAYMENT_FAILED";
+    const orderId = parsed?.ORDERID || parsed?.orderId;
+    const paymentId = parsed?.TXNID || parsed?.txnId;
+    const amount = parsed?.TXNAMOUNT ? parseFloat(parsed.TXNAMOUNT) : void 0;
     return {
       isValid: true,
+      normalizedEvent,
+      rawEvent: rawStatus,
       gateway: "paytm",
-      event: isSuccess ? "TXN_SUCCESS" : "TXN_FAILURE",
+      orderId,
+      paymentId,
+      amount,
+      currency: "INR",
       data: parsed
     };
   }
@@ -726,6 +807,7 @@ var StripeAdapter = class extends BasePaymentAdapter {
       refundId: res.id,
       paymentId: options.paymentId,
       amount: res.amount / 100,
+      // Normalized to standard currency units
       status: res.status === "succeeded" ? "SUCCESS" : "PENDING",
       rawResponse: res
     };
@@ -733,11 +815,11 @@ var StripeAdapter = class extends BasePaymentAdapter {
   async verifyWebhook(options) {
     const secret = options.webhookSecret || this.config.webhookSecret;
     if (!secret) {
-      return { isValid: false, gateway: "stripe", error: "Stripe webhookSecret is not configured." };
+      return { isValid: false, normalizedEvent: "UNKNOWN", gateway: "stripe", error: "Stripe webhookSecret is not configured." };
     }
     const sigHeader = this.getHeader(options.headers, "stripe-signature");
     if (!sigHeader || typeof sigHeader !== "string") {
-      return { isValid: false, gateway: "stripe", error: "Missing stripe-signature header." };
+      return { isValid: false, normalizedEvent: "UNKNOWN", gateway: "stripe", error: "Missing stripe-signature header." };
     }
     const parts = sigHeader.split(",");
     let timestamp = "";
@@ -757,11 +839,32 @@ var StripeAdapter = class extends BasePaymentAdapter {
     } catch {
       parsed = null;
     }
+    const rawEvent = parsed?.type || "";
+    let normalizedEvent = "UNKNOWN";
+    if (rawEvent === "checkout.session.completed" || rawEvent === "payment_intent.succeeded") {
+      normalizedEvent = "PAYMENT_SUCCESS";
+    } else if (rawEvent === "payment_intent.payment_failed") {
+      normalizedEvent = "PAYMENT_FAILED";
+    } else if (rawEvent === "charge.refunded") {
+      normalizedEvent = "REFUND_PROCESSED";
+    } else if (rawEvent?.includes("dispute")) {
+      normalizedEvent = "DISPUTE_CREATED";
+    }
+    const obj = parsed?.data?.object;
+    const orderId = obj?.client_reference_id || obj?.metadata?.order_id || obj?.id;
+    const paymentId = obj?.payment_intent || obj?.id;
+    const amount = obj?.amount_total ? obj.amount_total / 100 : obj?.amount ? obj.amount / 100 : void 0;
+    const currency = obj?.currency ? obj.currency.toUpperCase() : void 0;
     return {
       isValid,
+      normalizedEvent,
+      rawEvent,
       gateway: "stripe",
-      event: parsed?.type,
-      data: parsed?.data?.object
+      orderId,
+      paymentId,
+      amount,
+      currency,
+      data: obj
     };
   }
 };
@@ -830,8 +933,9 @@ var CODAdapter = class extends BasePaymentAdapter {
   async verifyWebhook(_options) {
     return {
       isValid: true,
+      normalizedEvent: "PAYMENT_SUCCESS",
+      rawEvent: "COD_ORDER",
       gateway: "cod",
-      event: "COD_ORDER",
       data: {}
     };
   }
@@ -962,6 +1066,60 @@ var PaymentManager = class {
     const adapter = this.getAdapter(options.gateway);
     return adapter.verifyWebhook(options);
   }
+  /**
+   * Ready-made Next.js 13/14/15 App Router Route Handler Webhook Authenticator.
+   * Directly consumes the standard web Request object with raw stream body handling:
+   *
+   * ```typescript
+   * export async function POST(req: Request) {
+   *   const result = await payments.verifyNextJsWebhook(req, { gateway: 'razorpay' });
+   *   if (!result.isValid) return new Response('Invalid Signature', { status: 400 });
+   *   console.log('Event:', result.normalizedEvent, result.orderId);
+   *   return new Response('OK');
+   * }
+   * ```
+   */
+  async verifyNextJsWebhook(request, options) {
+    try {
+      let rawBody = "";
+      if (typeof request.text === "function") {
+        rawBody = await request.text();
+      } else if (typeof request.body === "string") {
+        rawBody = request.body;
+      } else if (Buffer.isBuffer(request.body)) {
+        rawBody = request.body.toString("utf8");
+      }
+      const headers = {};
+      if (request.headers) {
+        if (typeof request.headers.forEach === "function") {
+          request.headers.forEach((val, key) => {
+            headers[key.toLowerCase()] = val;
+          });
+        } else if (typeof request.headers.entries === "function") {
+          for (const [key, val] of request.headers.entries()) {
+            headers[key.toLowerCase()] = val;
+          }
+        } else if (typeof request.headers === "object") {
+          Object.entries(request.headers).forEach(([k, v]) => {
+            headers[k.toLowerCase()] = Array.isArray(v) ? v[0] : v;
+          });
+        }
+      }
+      return this.verifyWebhook({
+        gateway: options.gateway,
+        rawBody,
+        headers,
+        webhookSecret: options.webhookSecret
+      });
+    } catch (err) {
+      return {
+        isValid: false,
+        normalizedEvent: "UNKNOWN",
+        gateway: options.gateway,
+        error: `Failed to process Next.js webhook: ${err.message}`
+      };
+    }
+  }
 };
 function createPaymentManager(options) {
   return new PaymentManager(options);