create-charcole 2.2.2 → 2.3.0

package/template/js/.env.example

@@ -14,4 +14,22 @@ REQUEST_TIMEOUT=30000
 
 
 # Authentication
-JWT_SECRET=your-secret-key-here
+JWT_SECRET=your-secret-key-here
+
+# ─── Payments ──────────────────────────────────────────────────────────────────
+# PAYMENT_PROVIDER selects the active payment adapter.
+# Options: "stripe" | "lemonsqueezy"
+# Use "lemonsqueezy" if you are in Pakistan — Stripe does not support PKR payouts.
+PAYMENT_PROVIDER=
+
+# Stripe — https://dashboard.stripe.com/apikeys
+# Use test keys during development: sk_test_...
+STRIPE_SECRET_KEY=
+STRIPE_WEBHOOK_SECRET=
+STRIPE_PUBLISHABLE_KEY=
+
+# LemonSqueezy — https://app.lemonsqueezy.com/settings/api
+# LEMONSQUEEZY_STORE_ID is the numeric ID from your store URL
+LEMONSQUEEZY_API_KEY=
+LEMONSQUEEZY_WEBHOOK_SECRET=
+LEMONSQUEEZY_STORE_ID=

package/template/js/README.md

@@ -9,11 +9,12 @@ Welcome! This guide will help you set up and start using the Charcole API framew
 3. [Configuration](#configuration)
 4. [Creating Your First Endpoint](#creating-your-first-endpoint)
 5. [API Documentation with Swagger](#api-documentation-with-swagger)
-6. [Error Handling](#error-handling)
-7. [Validation](#validation)
-8. [Logging](#logging)
-9. [Running Your API](#running-your-api)
-10. [Troubleshooting](#troubleshooting)
+6. [Payment Processing (if enabled)](#payment-processing-if-enabled)
+7. [Error Handling](#error-handling)
+8. [Validation](#validation)
+9. [Logging](#logging)
+10. [Running Your API](#running-your-api)
+11. [Troubleshooting](#troubleshooting)
 
 ---
 
@@ -523,6 +524,133 @@ For protected endpoints:
 
 ---
 
+## 💳 Payment Processing (if enabled)
+
+### Overview
+
+Your API comes with **production-ready payment processing** if you selected the payments module during setup. Choose between:
+
+- **Stripe** - Industry standard payment processing
+- **LemonSqueezy** - Perfect for Pakistani developers (PKR payout support via bank transfer)
+- **Both** - Flexibility to switch providers
+
+### Payment Endpoints
+
+Four ready-to-use payment APIs are auto-configured:
+
+```
+POST   /api/payments/create-intent       # Create payment intent
+POST   /api/payments/refund              # Refund a payment
+GET    /api/payments/status/:paymentId   # Check payment status
+POST   /api/payments/webhook             # Webhook receiver
+```
+
+### Configuration
+
+Add payment provider credentials to `.env`:
+
+```env
+# Payment Provider (stripe, lemonsqueezy, or both)
+PAYMENT_PROVIDER=stripe
+
+# Stripe Configuration
+STRIPE_SECRET_KEY=sk_live_...
+STRIPE_WEBHOOK_SECRET=whsec_...
+
+# LemonSqueezy Configuration
+LEMONSQUEEZY_API_KEY=...
+LEMONSQUEEZY_WEBHOOK_SECRET=...
+```
+
+### Usage Example
+
+```javascript
+import { setupPayments } from "@charcoles/payments";
+
+// In your app.js
+const paymentAdapter = setupPayments({
+  provider: process.env.PAYMENT_PROVIDER,
+  stripeKey: process.env.STRIPE_SECRET_KEY,
+  lemonsqueezyKey: process.env.LEMONSQUEEZY_API_KEY,
+});
+
+// In your controller
+export const createPaymentIntent = asyncHandler(async (req, res) => {
+  const { amount, currency, customerId } = req.body;
+
+  const intent = await paymentAdapter.createPayment({
+    amount,
+    currency,
+    customerId,
+  });
+
+  sendSuccess(res, intent, 201, "Payment intent created");
+});
+```
+
+### Webhook Handling
+
+Webhooks are automatically configured and validated:
+
+```javascript
+// src/modules/payments/payments.routes.js
+// POST /api/payments/webhook automatically handles:
+// - Stripe: payment_intent.succeeded, charge.refunded
+// - LemonSqueezy: order_created, order_refunded
+
+// Raw body middleware auto-configured in app.js
+// app.use('/payments/webhook', express.raw({ type: 'application/json' }))
+```
+
+### Error Handling
+
+Payment errors are automatically caught by the global error handler:
+
+```javascript
+import { PaymentError } from "@charcoles/payments";
+
+// Throws structured error
+throw new PaymentError("Insufficient funds", {
+  code: "insufficient_funds",
+  statusCode: 402,
+});
+
+// Response:
+// {
+//   "success": false,
+//   "message": "Insufficient funds",
+//   "statusCode": 402,
+//   "code": "insufficient_funds"
+// }
+```
+
+### Testing Payments Locally
+
+**Stripe:**
+
+```bash
+STRIPE_SECRET_KEY=sk_test_... npm run dev
+# Use test card: 4242 4242 4242 4242
+```
+
+**LemonSqueezy:**
+
+```bash
+LEMONSQUEEZY_API_KEY=... npm run dev
+# Sandbox mode automatically used with test keys
+```
+
+### Documentation in Swagger
+
+All payment endpoints are automatically documented in Swagger UI when enabled:
+
+1. Start server: `npm run dev`
+2. Visit http://localhost:3000/api-docs
+3. Look for **Payments** tag
+4. Test all endpoints directly from the browser
+
+---
+
 ## ✔️ Validation
 
 ### Zod Schema Basics

package/template/js/basePackage.json

@@ -1,6 +1,6 @@
 {
   "name": "charcole",
-  "version": "2.2.2",
+  "version": "2.3.0",
   "description": "Production-grade Node.js Express API",
   "main": "src/server.js",
   "type": "module",

package/template/js/src/app.js

@@ -1,4 +1,7 @@
 import express from "express";
+import { existsSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
 import { userRepo } from "./repositories/user.repo.js";
 import cors from "cors";
 import { env } from "./config/env.js";
@@ -14,6 +17,13 @@ import { logger } from "./utils/logger.js";
 import routes from "./routes/index.js";
 import swaggerOptions from "./config/swagger.config.js";
 import { setupSwagger } from "@charcoles/swagger";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const paymentsModulePath = join(
+  __dirname,
+  "modules/payments/payments.routes.js",
+);
+
 export const app = express();
 
 // Trust proxy
@@ -30,6 +40,13 @@ app.use(
 );
 
 // Body parsing middleware
+// Webhook raw body — must be registered BEFORE express.json()
+// Required for Stripe and LemonSqueezy webhook signature verification.
+// express.json() destroys the raw bytes needed for HMAC verification.
+if (existsSync(paymentsModulePath)) {
+  app.use("/payments/webhook", express.raw({ type: "application/json" }));
+}
+
 app.use(express.json({ limit: "10mb" }));
 app.use(express.urlencoded({ extended: true, limit: "10mb" }));
 

package/template/js/src/config/env.js

@@ -8,6 +8,14 @@ const envSchema = z.object({
   LOG_LEVEL: z.enum(["debug", "info", "warn", "error"]).default("info"),
   CORS_ORIGIN: z.string().default("*"),
   REQUEST_TIMEOUT: z.coerce.number().default(30000),
+  // Payments — all optional so projects without payments don't fail env validation
+  PAYMENT_PROVIDER: z.enum(["stripe", "lemonsqueezy"]).optional(),
+  STRIPE_SECRET_KEY: z.string().optional(),
+  STRIPE_WEBHOOK_SECRET: z.string().optional(),
+  STRIPE_PUBLISHABLE_KEY: z.string().optional(),
+  LEMONSQUEEZY_API_KEY: z.string().optional(),
+  LEMONSQUEEZY_WEBHOOK_SECRET: z.string().optional(),
+  LEMONSQUEEZY_STORE_ID: z.string().optional(),
 });
 
 const parseEnv = () => {

package/template/js/src/lib/swagger/SWAGGER_GUIDE.md

@@ -96,6 +96,40 @@ That's it! Your Zod schemas are now available as `$ref` in Swagger.
 
 **Result:** 60 lines eliminated! And your schema stays in sync automatically.
 
+### Example 2.1: Documenting a Payments Webhook Endpoint
+
+```javascript
+/**
+ * @swagger
+ * /api/payments/webhook:
+ *   post:
+ *     summary: Receive payment provider webhook events
+ *     tags:
+ *       - Payments
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *     responses:
+ *       200:
+ *         description: Webhook received
+ *       400:
+ *         description: Missing signature header
+ */
+router.post("/webhook", handleWebhook);
+```
+
+When you expose a webhook route, mount raw JSON middleware before `express.json()` so the provider signature verification receives the raw body:
+
+```javascript
+app.use("/payments/webhook", express.raw({ type: "application/json" }));
+app.use(express.json());
+```
+
+This means your final webhook route becomes `/api/payments/webhook` when the payments router is mounted at `/api`.
+
 ---
 
 ## 📚 Complete Examples

package/template/js/src/modules/payments/__tests__/payments.controller.test.js

@@ -0,0 +1,342 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+vi.mock("../payments.service.js", () => ({
+  createPayment: vi.fn(),
+  refundPayment: vi.fn(),
+  getPaymentStatus: vi.fn(),
+  processWebhook: vi.fn(),
+}));
+
+vi.mock("../../../utils/logger.js", () => ({
+  logger: {
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+  },
+}));
+
+import * as controller from "../payments.controller.js";
+import * as service from "../payments.service.js";
+
+function buildMocks(overrides = {}) {
+  const req = {
+    body: {},
+    params: {},
+    headers: {},
+    ...overrides,
+  };
+
+  const res = {
+    status: vi.fn().mockReturnThis(),
+    json: vi.fn().mockReturnThis(),
+  };
+
+  const next = vi.fn();
+
+  return { req, res, next };
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  delete process.env.PAYMENT_PROVIDER;
+});
+
+describe("createPayment controller", () => {
+  it("calls service.createPayment with validated body and responds 201", async () => {
+    const result = {
+      id: "pi_test_123",
+      clientSecret: "secret_abc",
+      status: "requires_payment_method",
+      amount: 999,
+      currency: "usd",
+      metadata: {},
+    };
+    service.createPayment.mockResolvedValue(result);
+
+    const { req, res, next } = buildMocks({
+      body: { amount: 999, currency: "usd" },
+    });
+
+    await controller.createPayment(req, res, next);
+
+    expect(service.createPayment).toHaveBeenCalledTimes(1);
+    expect(service.createPayment).toHaveBeenCalledWith({
+      amount: 999,
+      currency: "usd",
+      metadata: {},
+    });
+    expect(res.status).toHaveBeenCalledWith(201);
+    expect(res.json).toHaveBeenCalledWith(
+      expect.objectContaining({ success: true, data: result }),
+    );
+    expect(next).not.toHaveBeenCalled();
+  });
+
+  it("calls next(err) when schema validation fails", async () => {
+    const { req, res, next } = buildMocks({
+      body: { amount: "not-a-number", currency: "usd" },
+    });
+
+    await controller.createPayment(req, res, next);
+
+    expect(next).toHaveBeenCalled();
+    expect(res.json).not.toHaveBeenCalled();
+  });
+
+  it("calls next(err) when service.createPayment rejects", async () => {
+    const error = new Error("stripe down");
+    service.createPayment.mockRejectedValue(error);
+
+    const { req, res, next } = buildMocks({
+      body: { amount: 999, currency: "usd" },
+    });
+
+    await controller.createPayment(req, res, next);
+
+    expect(next).toHaveBeenCalledWith(error);
+    expect(next.mock.calls[0][0]).toBe(error);
+  });
+
+  it("currency is lowercased by the schema", async () => {
+    const result = {
+      id: "pi_test_123",
+      clientSecret: "secret_abc",
+      status: "requires_payment_method",
+      amount: 100,
+      currency: "usd",
+      metadata: {},
+    };
+    service.createPayment.mockResolvedValue(result);
+
+    const { req, res, next } = buildMocks({
+      body: { amount: 100, currency: "USD" },
+    });
+
+    await controller.createPayment(req, res, next);
+
+    expect(service.createPayment).toHaveBeenCalledWith({
+      amount: 100,
+      currency: "usd",
+      metadata: {},
+    });
+    expect(res.status).toHaveBeenCalledWith(201);
+    expect(res.json).toHaveBeenCalledWith(
+      expect.objectContaining({ success: true, data: result }),
+    );
+    expect(next).not.toHaveBeenCalled();
+  });
+});
+
+describe("refundPayment controller", () => {
+  it("calls service.refundPayment with paymentId and optional amount, responds 200", async () => {
+    const result = { id: "re_test_123", status: "succeeded", amount: 500 };
+    service.refundPayment.mockResolvedValue(result);
+
+    const { req, res, next } = buildMocks({
+      body: { paymentId: "pi_123", amount: 500 },
+    });
+
+    await controller.refundPayment(req, res, next);
+
+    expect(service.refundPayment).toHaveBeenCalledWith({
+      paymentId: "pi_123",
+      amount: 500,
+    });
+    expect(res.status).toHaveBeenCalledWith(200);
+    expect(res.json).toHaveBeenCalledWith(
+      expect.objectContaining({ success: true, data: result }),
+    );
+    expect(next).not.toHaveBeenCalled();
+  });
+
+  it("calls service.refundPayment with just paymentId when amount is omitted", async () => {
+    const result = { id: "re_test_456", status: "succeeded", amount: 0 };
+    service.refundPayment.mockResolvedValue(result);
+
+    const { req, res, next } = buildMocks({ body: { paymentId: "pi_123" } });
+
+    await controller.refundPayment(req, res, next);
+
+    expect(service.refundPayment).toHaveBeenCalledWith({
+      paymentId: "pi_123",
+      amount: undefined,
+    });
+    expect(res.status).toHaveBeenCalledWith(200);
+    expect(res.json).toHaveBeenCalledWith(
+      expect.objectContaining({ success: true, data: result }),
+    );
+    expect(next).not.toHaveBeenCalled();
+  });
+
+  it("calls next(err) when paymentId is missing from body", async () => {
+    const { req, res, next } = buildMocks({ body: { amount: 500 } });
+
+    await controller.refundPayment(req, res, next);
+
+    expect(next).toHaveBeenCalled();
+    expect(res.json).not.toHaveBeenCalled();
+  });
+
+  it("calls next(err) when service.refundPayment rejects", async () => {
+    const error = new Error("refund failed");
+    service.refundPayment.mockRejectedValue(error);
+
+    const { req, res, next } = buildMocks({
+      body: { paymentId: "pi_123", amount: 500 },
+    });
+
+    await controller.refundPayment(req, res, next);
+
+    expect(next).toHaveBeenCalledWith(error);
+  });
+});
+
+describe("getPaymentStatus controller", () => {
+  it("calls service.getPaymentStatus with req.params.paymentId and responds with result", async () => {
+    const result = {
+      id: "pi_123",
+      status: "paid",
+      amount: 999,
+      currency: "usd",
+      metadata: {},
+    };
+    service.getPaymentStatus.mockResolvedValue(result);
+
+    const { req, res, next } = buildMocks({ params: { paymentId: "pi_123" } });
+
+    await controller.getPaymentStatus(req, res, next);
+
+    expect(service.getPaymentStatus).toHaveBeenCalledWith("pi_123");
+    expect(res.status).toHaveBeenCalledWith(200);
+    expect(res.json).toHaveBeenCalledWith(
+      expect.objectContaining({ success: true, data: result }),
+    );
+    expect(next).not.toHaveBeenCalled();
+  });
+
+  it("calls next(err) when service rejects", async () => {
+    const error = new Error("status lookup failed");
+    service.getPaymentStatus.mockRejectedValue(error);
+
+    const { req, res, next } = buildMocks({ params: { paymentId: "pi_123" } });
+
+    await controller.getPaymentStatus(req, res, next);
+
+    expect(next).toHaveBeenCalledWith(error);
+  });
+});
+
+describe("handleWebhook controller", () => {
+  it("reads stripe-signature header when PAYMENT_PROVIDER is stripe", async () => {
+    process.env.PAYMENT_PROVIDER = "stripe";
+    const result = {
+      event: "payment_intent.succeeded",
+      data: {},
+      duplicate: false,
+    };
+    service.processWebhook.mockResolvedValue(result);
+
+    const { req, res, next } = buildMocks({
+      headers: { "stripe-signature": "test-sig" },
+      body: Buffer.from('{"id":"evt_123"}'),
+    });
+
+    await controller.handleWebhook(req, res, next);
+
+    expect(service.processWebhook).toHaveBeenCalledWith(req.body, "test-sig");
+    expect(res.status).toHaveBeenCalledWith(200);
+    expect(res.json).toHaveBeenCalledWith({ received: true });
+    expect(next).not.toHaveBeenCalled();
+  });
+
+  it("reads x-signature header when PAYMENT_PROVIDER is lemonsqueezy", async () => {
+    process.env.PAYMENT_PROVIDER = "lemonsqueezy";
+    const result = { event: "order_created", data: {}, duplicate: false };
+    service.processWebhook.mockResolvedValue(result);
+
+    const { req, res, next } = buildMocks({
+      headers: { "x-signature": "hmac-sig" },
+      body: Buffer.from('{"id":"evt_456"}'),
+    });
+
+    await controller.handleWebhook(req, res, next);
+
+    expect(service.processWebhook).toHaveBeenCalledWith(req.body, "hmac-sig");
+    expect(res.status).toHaveBeenCalledWith(200);
+    expect(res.json).toHaveBeenCalledWith({ received: true });
+    expect(next).not.toHaveBeenCalled();
+  });
+
+  it("responds 200 { received: true, duplicate: true } for duplicate events", async () => {
+    process.env.PAYMENT_PROVIDER = "stripe";
+    const result = {
+      event: "payment_intent.succeeded",
+      data: { id: "evt_789" },
+      duplicate: true,
+    };
+    service.processWebhook.mockResolvedValue(result);
+
+    const { req, res, next } = buildMocks({
+      headers: { "stripe-signature": "test-sig" },
+      body: Buffer.from('{"id":"evt_789"}'),
+    });
+
+    await controller.handleWebhook(req, res, next);
+
+    expect(res.status).toHaveBeenCalledWith(200);
+    expect(res.json).toHaveBeenCalledWith({ received: true, duplicate: true });
+    expect(next).not.toHaveBeenCalled();
+  });
+
+  it("responds 400 when signature header is missing", async () => {
+    process.env.PAYMENT_PROVIDER = "stripe";
+    const { req, res, next } = buildMocks({
+      body: Buffer.from('{"id":"evt_000"}'),
+    });
+
+    await controller.handleWebhook(req, res, next);
+
+    expect(res.status).toHaveBeenCalledWith(400);
+    expect(res.json).toHaveBeenCalledWith({
+      error: "Missing webhook signature header",
+    });
+    expect(next).not.toHaveBeenCalled();
+  });
+
+  it("calls next(err) when processWebhook throws an error", async () => {
+    process.env.PAYMENT_PROVIDER = "stripe";
+    const error = new Error("invalid signature");
+    service.processWebhook.mockRejectedValue(error);
+
+    const { req, res, next } = buildMocks({
+      headers: { "stripe-signature": "test-sig" },
+      body: Buffer.from('{"id":"evt_999"}'),
+    });
+
+    await controller.handleWebhook(req, res, next);
+
+    expect(next).toHaveBeenCalledWith(error);
+  });
+
+  it("passes req.body as a raw Buffer to processWebhook", async () => {
+    process.env.PAYMENT_PROVIDER = "stripe";
+    const result = {
+      event: "payment_intent.succeeded",
+      data: {},
+      duplicate: false,
+    };
+    service.processWebhook.mockResolvedValue(result);
+
+    const { req, res, next } = buildMocks({
+      headers: { "stripe-signature": "test-sig" },
+      body: Buffer.from('{"id":"evt_buffer"}'),
+    });
+
+    await controller.handleWebhook(req, res, next);
+
+    const rawArg = service.processWebhook.mock.calls[0][0];
+    expect(Buffer.isBuffer(rawArg)).toBe(true);
+    expect(rawArg.toString()).toBe('{"id":"evt_buffer"}');
+    expect(next).not.toHaveBeenCalled();
+  });
+});