@boostengine/payments 1.0.0

package/README.md

@@ -0,0 +1,197 @@
+# @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.
+
+---
+
+## ⚡ Why @boostengine/payments?
+
+- 🔌 **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.
+- 🪶 **Zero Dependency Bloat**: Uses native Node.js `fetch` and `crypto`. No 10 heavy third-party vendor SDKs.
+
+---
+
+## 📦 Installation
+
+```bash
+npm install @boostengine/payments
+```
+
+---
+
+## 🚀 Quickstart
+
+### 1. Initialize PaymentManager
+
+```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!,
+      secretKey: process.env.CASHFREE_SECRET_KEY!,
+      env: 'PRODUCTION', // or 'SANDBOX'
+    },
+    razorpay: {
+      keyId: process.env.RAZORPAY_KEY_ID!,
+      keySecret: process.env.RAZORPAY_KEY_SECRET!,
+      webhookSecret: process.env.RAZORPAY_WEBHOOK_SECRET,
+    },
+    phonepe: {
+      merchantId: process.env.PHONEPE_MERCHANT_ID!,
+      saltKey: process.env.PHONEPE_SALT_KEY!,
+      saltIndex: '1',
+      env: 'PRODUCTION', // or 'UAT'
+    },
+    stripe: {
+      secretKey: process.env.STRIPE_SECRET_KEY!,
+      webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
+    },
+    cod: {
+      minOrderValue: 200,
+      maxOrderValue: 10000,
+      extraFee: 49, // Rs. 49 COD handling charge
+    },
+  },
+
+  // Smart Routing & Fallbacks
+  smartRouting: {
+    currencyMap: {
+      USD: 'stripe',
+      EUR: 'stripe',
+      INR: 'cashfree',
+    },
+    fallbackChain: ['cashfree', 'razorpay', 'phonepe'],
+  },
+});
+```
+
+---
+
+### 2. Create an Order (Single or Multi-Gateway)
+
+```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'
+});
+
+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: { ... }
+}
+*/
+```
+
+---
+
+### 3. Smart Fallback (High-Availability Checkout)
+
+If your primary payment gateway experiences bank server outages or 500 errors, automatic fallback routes the order through the next available gateway:
+
+```typescript
+const order = await payments.createOrderWithFallback({
+  amount: 1499.00,
+  currency: 'INR',
+  receipt: `order_${Date.now()}`,
+  customer: {
+    name: 'Aman Sharma',
+    email: 'aman@example.com',
+    phone: '9876543210',
+  },
+  fallbackChain: ['razorpay', 'cashfree', 'phonepe'],
+});
+```
+
+---
+
+### 4. Verify Payment & Webhooks
+
+```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);
+```
+
+---
+
+## 🛠️ CLI Quickstart
+
+Generate an environment template or check supported gateways:
+
+```bash
+# List all 6 supported gateways
+npx @boostengine/payments list
+
+# Generate .env.payments.example template
+npx @boostengine/payments init-env
+
+# Compute quick SHA-256 hash
+npx @boostengine/payments hash "my_test_payload"
+```
+
+---
+
+## 📄 License
+MIT © Boost Engine Team

package/bin/cli.cjs

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const args = process.argv.slice(2);
+const command = args[0] || 'help';
+
+console.log('\n=======================================================');
+console.log('⚡ @boostengine/payments - Multi-Gateway CLI');
+console.log('=======================================================\n');
+
+switch (command) {
+  case 'list': {
+    console.log('Supported Payment Gateways:\n');
+    const gateways = [
+      { name: 'Razorpay', key: 'razorpay', type: 'Cards, UPI, Netbanking, Smart Collect', region: 'India' },
+      { name: 'Cashfree', key: 'cashfree', type: 'Drop-in, Seamless UPI/Cards, Verification, Payouts', region: 'India' },
+      { name: 'PhonePe', key: 'phonepe', type: 'Standard Hosted Pay, Mobile App Intent, UPI Collect', region: 'India' },
+      { name: 'Paytm', key: 'paytm', type: 'All-In-One Checkout SDK, txnToken, Status', region: 'India' },
+      { name: 'Stripe', key: 'stripe', type: 'Checkout Sessions, PaymentIntents, Global Cards', region: 'Global' },
+      { name: 'COD', key: 'cod', type: 'Cash On Delivery with fee rules & limit thresholds', region: 'Local' },
+    ];
+    console.table(gateways);
+    break;
+  }
+
+  case 'init-env': {
+    const envContent = `# Boost Engine Payments - Multi-Gateway Environment Variables
+
+# Default Gateway (razorpay | cashfree | phonepe | paytm | stripe | cod)
+DEFAULT_PAYMENT_GATEWAY=cashfree
+
+# Razorpay
+RAZORPAY_KEY_ID=rzp_test_your_key_id
+RAZORPAY_KEY_SECRET=your_razorpay_secret
+RAZORPAY_WEBHOOK_SECRET=your_razorpay_webhook_secret
+
+# Cashfree
+CASHFREE_APP_ID=your_cashfree_app_id
+CASHFREE_SECRET_KEY=your_cashfree_secret_key
+CASHFREE_ENV=SANDBOX
+
+# PhonePe
+PHONEPE_MERCHANT_ID=PGTESTPAYUAT
+PHONEPE_SALT_KEY=099eb0cd-02cf-4e2a-8aca-3e6c6aff0399
+PHONEPE_SALT_INDEX=1
+PHONEPE_ENV=UAT
+
+# Paytm
+PAYTM_MID=YOUR_PAYTM_MID
+PAYTM_MERCHANT_KEY=YOUR_PAYTM_MERCHANT_KEY
+PAYTM_ENV=STAGE
+
+# Stripe
+STRIPE_SECRET_KEY=sk_test_your_stripe_secret
+STRIPE_WEBHOOK_SECRET=whsec_your_stripe_webhook_secret
+
+# Cash On Delivery (COD) Rules
+COD_MIN_ORDER=200
+COD_MAX_ORDER=10000
+COD_EXTRA_FEE=49
+`;
+    const targetFile = path.join(process.cwd(), '.env.payments.example');
+    fs.writeFileSync(targetFile, envContent, 'utf8');
+    console.log(`✅ Created environment template: ${targetFile}`);
+    console.log('Copy desired variables into your project .env file.\n');
+    break;
+  }
+
+  case 'hash': {
+    const text = args[1];
+    if (!text) {
+      console.log('Usage: npx @boostengine/payments hash "<text>"');
+      break;
+    }
+    const hash = crypto.createHash('sha256').update(text).digest('hex');
+    console.log(`Input:  ${text}`);
+    console.log(`SHA256: ${hash}\n`);
+    break;
+  }
+
+  default: {
+    console.log('Usage:');
+    console.log('  npx @boostengine/payments list        - List all 6 supported gateways');
+    console.log('  npx @boostengine/payments init-env    - Generate .env.payments.example template');
+    console.log('  npx @boostengine/payments hash <text> - Calculate SHA256 checksum');
+    console.log('\nDocumentation: https://github.com/boostengine/payments\n');
+    break;
+  }
+}