@neocleus/razorpay-firebase-functions 1.0.0

package/README.md

@@ -0,0 +1,165 @@
+# @neocleus/razorpay-firebase-functions
+
+Consumable Firebase Cloud Functions for **Razorpay** payments and subscriptions integration using the Factory pattern.
+
+This package provides the core server-side integration triggers and callable handlers for the **Run Payments with Razorpay** Firebase Extension. It can be initialized directly inside your own custom Cloud Functions codebase.
+
+---
+
+## 📥 Installation
+
+Install the package in your Firebase Cloud Functions directory:
+
+```bash
+npm install @neocleus/razorpay-firebase-functions
+```
+
+---
+
+## ⚙️ Quick Start & Initialization
+
+Import `initializeRazorpay` and call it with your API credentials to export all triggers, callable functions, and webhook handlers.
+
+### `src/index.ts`
+```typescript
+import * as admin from 'firebase-admin';
+import { initializeRazorpay } from '@neocleus/razorpay-firebase-functions';
+
+// 1. Initialize the Firebase Admin SDK
+admin.initializeApp();
+
+// 2. Configure and initialize Razorpay functions
+const rzpFuncs = initializeRazorpay({
+    keyId: process.env.RAZORPAY_KEY_ID || '',
+    keySecret: process.env.RAZORPAY_KEY_SECRET || '',
+    webhookSecret: process.env.RAZORPAY_WEBHOOK_SECRET || '',
+    customersCollection: 'customers', // Optional, defaults to 'customers'
+    productsCollection: 'products',   // Optional, defaults to 'products'
+    syncCustomers: true,              // Optional, defaults to true
+});
+
+// 3. Export functions as flat deployable Cloud Functions
+export const createOrder = rzpFuncs.createOrder;
+export const createSubscription = rzpFuncs.createSubscription;
+export const createCustomer = rzpFuncs.createCustomer;
+export const onUserDeleted = rzpFuncs.onUserDeleted;
+export const onCustomerDataDeleted = rzpFuncs.onCustomerDataDeleted;
+export const webhookHandler = rzpFuncs.webhookHandler;
+export const cancelSubscription = rzpFuncs.cancelSubscription;
+export const updateSubscriptionPlan = rzpFuncs.updateSubscriptionPlan;
+export const createPlan = rzpFuncs.createPlan;
+export const syncPlans = rzpFuncs.syncPlans;
+```
+
+---
+
+## 🛡️ Robust Initialization Guard
+
+To prevent silent deployment configuration errors, `initializeRazorpay` validates your keys during initialization. 
+
+If any required credential is missing (`keyId`, `keySecret`, or `webhookSecret`) or if the `keyId` does not start with the mandatory `rzp_` prefix, **the function immediately throws a runtime Error**. This prevents your Cloud Functions from deploying in a misconfigured state.
+
+---
+
+## 🛠️ Exported Functions Reference
+
+1.  **Firestore Lifecycle Triggers**:
+    *   `createOrder`: Watches `customers/{uid}/checkout_sessions/{id}` to securely generate orders on Razorpay's API with transaction locks and duplicate safeguards.
+    *   `createSubscription`: Watches `customers/{uid}/subscriptions/{id}` to register subscription sessions on Razorpay's API.
+2.  **Auth Triggers**:
+    *   `createCustomer`: Listens to `auth.user().onCreate` to lazily sync users into Razorpay.
+    *   `onUserDeleted` / `onCustomerDataDeleted`: Cleans up documents and references.
+3.  **HTTPS Webhook Handler**:
+    *   `webhookHandler`: Deploys as an HTTPS endpoint to listen to Razorpay webhook events. Hardened with HMAC signature checks, deterministic event-ID deduplication, and stuck-event processing recovery.
+4.  **Client Callables**:
+    *   `cancelSubscription`: Handles secure cancellation requests.
+    *   `updateSubscriptionPlan`: Handles secure plan upgrades/downgrades, validating target `planId` against the products catalog collection.
+5.  **Admin Callables**:
+    *   `createPlan` / `syncPlans`: Enabled for users with custom claims (`admin: true`) to batch-sync catalogs from Razorpay using high-performance Firestore write batching.
+
+---
+
+## 🔒 Security Guidelines
+
+*   **Production Credentials**: Never commit plaintext API keys to Git. Configure these variables inside Google Cloud Secret Manager and load them dynamically in production.
+*   **Git Ignore Rules**: Add `.env` and `*.secret.local` to your ignore list:
+    ```
+    **/functions/.env
+    **/*.secret.local
+    ```
+
+### 📄 Required Firestore Security Rules
+
+To enforce catalog-driven pricing, protect payment states, and prevent metadata spoofing, you must apply the following security rules in your `firestore.rules` file:
+
+```javascript
+rules_version = '2';
+service cloud.firestore {
+  match /databases/{database}/documents {
+
+    // ── Products / Plans Catalog ──
+    match /products/{productId} {
+      allow read: if true;
+      allow write: if false;
+    }
+
+    // ── Customer Documents ──
+    match /customers/{uid} {
+      allow read: if request.auth.uid == uid;
+      allow write: if false;
+
+      // ── Checkout Sessions (One-time Orders) ──
+      match /checkout_sessions/{id} {
+        allow read: if request.auth.uid == uid;
+        allow create: if request.auth.uid == uid
+          && request.resource.data.keys().hasOnly(['productId', 'metadata'])
+          && request.resource.data.productId is string
+          && request.resource.data.productId.size() <= 256
+          && (!('metadata' in request.resource.data) || request.resource.data.metadata is map)
+          && request.resource.data.keys().size() <= 5;
+
+        allow update, delete: if false;
+
+        match /razorpay_responses/{docId} {
+          allow read: if request.auth.uid == uid;
+          allow write: if false;
+        }
+      }
+
+      // ── Subscriptions ──
+      match /subscriptions/{id} {
+        allow read: if request.auth.uid == uid;
+        allow create: if request.auth.uid == uid
+          && request.resource.data.keys().hasOnly(['productId', 'interval', 'metadata', 'draftId'])
+          && request.resource.data.productId is string
+          && request.resource.data.productId.size() <= 256
+          && request.resource.data.interval is string
+          && request.resource.data.interval.size() <= 64
+          && (!('metadata' in request.resource.data) || request.resource.data.metadata is map)
+          && (!('draftId' in request.resource.data) || request.resource.data.draftId is string)
+          && request.resource.data.keys().size() <= 5;
+
+        allow update, delete: if false;
+
+        match /payments/{paymentId} {
+          allow read: if request.auth.uid == uid;
+          allow write: if false;
+        }
+
+        match /razorpay_responses/{docId} {
+          allow read: if request.auth.uid == uid;
+          allow write: if false;
+        }
+      }
+    }
+
+    // ── Webhook Events (Backend/Extension Only) ──
+    match /webhook_events/{eventId} {
+      allow read, write: if false;
+    }
+
+    // ── Deny everything else by default ──
+    // No wildcard match — unlisted paths are denied
+  }
+}
+```

package/lib/admin.d.ts

@@ -0,0 +1,8 @@
+import Razorpay from 'razorpay';
+import { RazorpaySyncConfig, ProductDoc } from './types';
+export declare const buildCreatePlan: (config: RazorpaySyncConfig, rzp: Razorpay) => import("firebase-functions/v2/https").CallableFunction<any, Promise<ProductDoc>>;
+export declare const buildSyncPlans: (config: RazorpaySyncConfig, rzp: Razorpay) => import("firebase-functions/v2/https").CallableFunction<any, Promise<{
+    status: string;
+    count: number;
+    productsCount: number;
+}>>;

package/lib/admin.js

@@ -0,0 +1,155 @@
+"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.buildSyncPlans = exports.buildCreatePlan = void 0;
+const https_1 = require("firebase-functions/v2/https");
+const admin = __importStar(require("firebase-admin"));
+const firestore_1 = require("firebase-admin/firestore");
+const logs_1 = require("./logs");
+const utils_1 = require("./utils");
+const typedFirestore_1 = require("./utils/typedFirestore");
+const buildCreatePlan = (config, rzp) => {
+    return (0, https_1.onCall)(async (request) => {
+        if (!request.auth || request.auth.token.admin !== true) {
+            throw new https_1.HttpsError('permission-denied', 'Must be an administrative user to initiate plan creation.');
+        }
+        const { period, interval, item, notes } = request.data;
+        if (!period || !interval || !item || !item.name || !item.amount) {
+            throw new https_1.HttpsError('invalid-argument', 'Missing required fields: period, interval, item details.');
+        }
+        try {
+            const plan = await rzp.plans.create({
+                period,
+                interval,
+                item,
+                notes
+            });
+            const db = admin.firestore();
+            const productData = await (0, utils_1.syncPlanToProduct)(plan, db, config);
+            logs_1.logs.info(`Admin created plan: ${plan.id} and synced to product: ${productData.id}`);
+            return productData;
+        }
+        catch (err) {
+            logs_1.logs.error(err);
+            throw new https_1.HttpsError('internal', 'Failed to create plan.', err.message);
+        }
+    });
+};
+exports.buildCreatePlan = buildCreatePlan;
+const buildSyncPlans = (config, rzp) => {
+    return (0, https_1.onCall)(async (request) => {
+        if (!request.auth || request.auth.token.admin !== true) {
+            throw new https_1.HttpsError('permission-denied', 'Must be an administrative user to initiate plan sync.');
+        }
+        try {
+            const db = admin.firestore();
+            const typedFs = new typedFirestore_1.TypedFirestore(db, config);
+            logs_1.logs.info('Starting administrative plan synchronization from Razorpay...');
+            let skip = 0;
+            const count = 100;
+            let hasMore = true;
+            const allPlans = [];
+            const MAX_PLANS = 10000;
+            while (hasMore && allPlans.length < MAX_PLANS) {
+                logs_1.logs.info(`Fetching plans from Razorpay (skip: ${skip}, limit: ${count})...`);
+                const plans = await rzp.plans.all({ skip, count });
+                if (!plans.items || plans.items.length === 0) {
+                    break;
+                }
+                allPlans.push(...plans.items);
+                skip += count;
+                if (plans.items.length < count) {
+                    hasMore = false;
+                }
+            }
+            logs_1.logs.info(`Fetched ${allPlans.length} plans. Grouping by product ID in memory...`);
+            // Group plans by productId in memory
+            const productPlansMap = new Map();
+            for (const plan of allPlans) {
+                const productId = (0, utils_1.generateProductId)(plan);
+                if (!productPlansMap.has(productId)) {
+                    productPlansMap.set(productId, []);
+                }
+                productPlansMap.get(productId).push(plan);
+            }
+            logs_1.logs.info(`Identified ${productPlansMap.size} distinct products. Reading existing products collection...`);
+            // Read all existing products to avoid per-document lookups
+            const productsCollection = typedFs.getProductsCollection();
+            const existingProductsSnap = await productsCollection.get();
+            const existingProducts = new Map();
+            for (const doc of existingProductsSnap.docs) {
+                existingProducts.set(doc.id, doc.data());
+            }
+            logs_1.logs.info('Writing synchronized product catalogs to Firestore via BulkWriter...');
+            const bulkWriter = db.bulkWriter();
+            bulkWriter.onWriteError((error) => {
+                logs_1.logs.error(new Error(`BulkWriter error: ${error.message}`));
+                return false; // Do not retry
+            });
+            for (const [productId, plans] of productPlansMap.entries()) {
+                const productDocRef = typedFs.getProductDoc(productId);
+                const existingProduct = existingProducts.get(productId);
+                const productData = existingProduct || {
+                    id: productId,
+                    name: plans[0].item?.name || 'Razorpay Product',
+                    description: plans[0].item?.description || '',
+                    active: true,
+                    allowedPlans: {},
+                    created_at: firestore_1.FieldValue.serverTimestamp(),
+                };
+                productData.allowedPlans = productData.allowedPlans || {};
+                productData.plans = productData.plans || {};
+                for (const plan of plans) {
+                    const planKey = (0, utils_1.generatePlanKey)(plan);
+                    productData.allowedPlans[planKey] = plan.id;
+                    productData.plans[planKey] = (0, utils_1.sanitizePlan)(plan);
+                }
+                productData.type = 'subscription';
+                productData.updated_at = firestore_1.FieldValue.serverTimestamp();
+                productData._synced_via = 'admin_api';
+                bulkWriter.set(productDocRef, productData, { merge: true });
+            }
+            await bulkWriter.close();
+            logs_1.logs.info(`Admin synced ${allPlans.length} plans successfully across ${productPlansMap.size} products.`);
+            return { status: 'SUCCESS', count: allPlans.length, productsCount: productPlansMap.size };
+        }
+        catch (err) {
+            logs_1.logs.error(err);
+            throw new https_1.HttpsError('internal', 'Sync failed.', err.message);
+        }
+    });
+};
+exports.buildSyncPlans = buildSyncPlans;
+//# sourceMappingURL=admin.js.map

package/lib/admin.js.map

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

package/lib/api.d.ts

@@ -0,0 +1,4 @@
+import Razorpay from 'razorpay';
+import { Channel } from 'firebase-admin/eventarc';
+import { RazorpaySyncConfig } from './types';
+export declare const buildWebhookHandler: (config: RazorpaySyncConfig, rzp: Razorpay, eventChannel: Channel | null) => import("firebase-functions/v2/https").HttpsFunction;

package/lib/api.js

@@ -0,0 +1,203 @@
+"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.buildWebhookHandler = void 0;
+const https_1 = require("firebase-functions/v2/https");
+const crypto = __importStar(require("crypto"));
+const admin = __importStar(require("firebase-admin"));
+const firestore_1 = require("firebase-admin/firestore");
+const security_1 = require("./security");
+const logs_1 = require("./logs");
+const subscriptions_1 = require("./handlers/subscriptions");
+const payments_1 = require("./handlers/payments");
+const retry_1 = require("./utils/retry");
+const typedFirestore_1 = require("./utils/typedFirestore");
+const ALLOWED_EVENTS = new Set([
+    "payment.authorized",
+    "payment.failed",
+    "payment.captured",
+    "payment.dispute.created",
+    "order.paid",
+    "order.notification.delivered",
+    "order.notification.failed",
+    "subscription.authenticated",
+    "subscription.paused",
+    "subscription.resumed",
+    "subscription.activated",
+    "subscription.pending",
+    "subscription.halted",
+    "subscription.charged",
+    "subscription.cancelled",
+    "subscription.completed",
+    "subscription.updated",
+    "payment.dispute.won",
+    "payment.dispute.lost",
+    "payment.dispute.closed",
+    "payment.dispute.under_review",
+    "payment.dispute.action_required",
+    "payment.downtime.started",
+    "payment.downtime.updated",
+    "payment.downtime.resolved"
+]);
+const buildWebhookHandler = (config, rzp, eventChannel) => {
+    const webhookHandlerFunc = async (req, res) => {
+        if (req.method !== 'POST') {
+            res.status(405).send('Method Not Allowed');
+            return;
+        }
+        const signature = req.headers['x-razorpay-signature'];
+        let rawBody = '';
+        if (typeof req.rawBody === 'string') {
+            rawBody = req.rawBody;
+        }
+        else if (Buffer.isBuffer(req.rawBody)) {
+            rawBody = req.rawBody.toString('utf8');
+        }
+        else {
+            logs_1.logs.error(new Error('req.rawBody is missing or not a Buffer/String. Ensure you are not parsing the body before this handler.'));
+            res.status(400).send('Invalid Body');
+            return;
+        }
+        if (!(0, security_1.verifyWebhookSignature)(rawBody, signature, config.webhookSecret)) {
+            logs_1.logs.invalidSignature();
+            res.status(401).json({
+                error: 'Unauthorized',
+            });
+            return;
+        }
+        const event = req.body;
+        logs_1.logs.startWebhook(event.event);
+        if (!ALLOWED_EVENTS.has(event.event)) {
+            res.status(200).send('Event not handled');
+            return;
+        }
+        const eventId = event.id ||
+            req.headers['x-razorpay-event-id'] ||
+            `evt_${crypto.createHash('sha256').update(rawBody).digest('hex')}`;
+        const db = admin.firestore();
+        const typedFs = new typedFirestore_1.TypedFirestore(db, config);
+        const webhookEventRef = typedFs.getWebhookEventDoc(eventId);
+        try {
+            const expireAt = new Date(Date.now() + 7 * 24 * 60 * 60 * 1000); // 7 days from now
+            await webhookEventRef.create({
+                event: event.event,
+                status: 'processing',
+                created_at: firestore_1.FieldValue.serverTimestamp(),
+                updated_at: firestore_1.FieldValue.serverTimestamp(),
+                expireAt,
+            });
+        }
+        catch (e) {
+            if (e.code === 6 || e.code === 'already-exists') {
+                const canRetry = await db.runTransaction(async (tx) => {
+                    const doc = await tx.get(webhookEventRef);
+                    if (!doc.exists)
+                        return true;
+                    const data = doc.data();
+                    const updatedAt = data?.updated_at;
+                    const isTimestamp = updatedAt instanceof admin.firestore.Timestamp;
+                    const isStuck = data?.status === 'processing' &&
+                        updatedAt &&
+                        isTimestamp &&
+                        (Date.now() - updatedAt.toMillis() > 2 * 60 * 1000); // 2 mins
+                    if (data?.status === 'failed' || isStuck) {
+                        tx.update(webhookEventRef, {
+                            status: 'processing',
+                            updated_at: firestore_1.FieldValue.serverTimestamp(),
+                        });
+                        return true;
+                    }
+                    return false;
+                });
+                if (!canRetry) {
+                    logs_1.logs.info(`Webhook event ${eventId} already processed or in-flight. Skipping.`);
+                    res.status(200).send('Already Processed');
+                    return;
+                }
+            }
+            else {
+                logs_1.logs.error(e);
+                res.status(500).send('Webhook processing failed internally');
+                return;
+            }
+        }
+        try {
+            if (event.event.startsWith('subscription.')) {
+                await (0, subscriptions_1.handleSubscriptionEvent)(event, db, rzp, config);
+            }
+            else if (event.event.startsWith('payment.') || event.event.startsWith('order.')) {
+                await (0, payments_1.handlePaymentEvent)(event, db, rzp, config);
+            }
+            if (eventChannel) {
+                await eventChannel.publish({
+                    type: `com.razorpay.v1.${event.event}`,
+                    data: event.payload,
+                });
+            }
+            await webhookEventRef.update({
+                status: 'completed',
+                completed_at: firestore_1.FieldValue.serverTimestamp(),
+            }).catch((err) => {
+                logs_1.logs.error(`Failed to update webhook event status to completed (ID: ${eventId})`, err);
+            });
+            res.status(200).send('Webhook Processed');
+        }
+        catch (err) {
+            logs_1.logs.error(`Webhook processing failed for event: ${event.event} (ID: ${eventId})`, err);
+            const isRetryable = (0, retry_1.isTransientError)(err);
+            if (isRetryable) {
+                await webhookEventRef.update({ status: 'failed', updated_at: firestore_1.FieldValue.serverTimestamp() }).catch((err) => {
+                    logs_1.logs.error(`Failed to update webhook event status to failed (ID: ${eventId})`, err);
+                });
+                res.status(500).send('Webhook processing failed internally - retryable');
+            }
+            else {
+                logs_1.logs.error(`PERMANENT WEBHOOK FAILURE — event ${event.event} (ID: ${eventId}) will NOT be retried. Manual investigation required.`);
+                await webhookEventRef.update({ status: 'permanently_failed', completed_at: firestore_1.FieldValue.serverTimestamp() }).catch((err) => {
+                    logs_1.logs.error(`Failed to update webhook event status to permanently_failed (ID: ${eventId})`, err);
+                });
+                res.status(200).send('Webhook processing failed permanently');
+            }
+        }
+    };
+    return (0, https_1.onRequest)({
+        timeoutSeconds: 120,
+        memory: '512MiB',
+        maxInstances: 100,
+        minInstances: 0,
+    }, webhookHandlerFunc);
+};
+exports.buildWebhookHandler = buildWebhookHandler;
+//# sourceMappingURL=api.js.map

package/lib/api.js.map

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

package/lib/callables/subscriptions.d.ts

@@ -0,0 +1,9 @@
+import Razorpay from 'razorpay';
+import { RazorpaySyncConfig } from '../types';
+export declare const buildCancelSubscription: (config: RazorpaySyncConfig, rzp: Razorpay) => import("firebase-functions/v2/https").CallableFunction<any, Promise<{
+    status: "cancelled" | "active" | "pending" | "created" | "expired" | "authenticated" | "halted" | "completed";
+}>>;
+export declare const buildUpdateSubscriptionPlan: (config: RazorpaySyncConfig, rzp: Razorpay) => import("firebase-functions/v2/https").CallableFunction<any, Promise<{
+    plan_id: string;
+    status: "cancelled" | "active" | "pending" | "created" | "expired" | "authenticated" | "halted" | "completed";
+}>>;