create-charcole 2.2.2 → 2.3.0

package/CHANGELOG.md

@@ -5,9 +5,40 @@ All notable changes to Charcole will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [2.2.2] – 2026-02-06
+## [2.3.0] – 2026-05-05
+
+### Added
+
+- **Payments module** — optional, production-ready payment processing for scaffolded projects
+- `@charcoles/payments` standalone npm package — drop-in payment support for any Express app
+- **Stripe adapter** — full payment intent lifecycle: create, refund, status check, webhook verification
+- **LemonSqueezy adapter** — checkout sessions, order retrieval, refunds, and webhook HMAC verification
+  - Added specifically for Pakistani developers: Stripe does not support PKR payouts; LemonSqueezy provides merchant-of-record payments with full Pakistani bank payout support
+- Adapter pattern for provider abstraction — switch between Stripe and LemonSqueezy via `PAYMENT_PROVIDER` env var
+- New CLI prompt: "Include payments module?" with provider selection (Stripe / LemonSqueezy / Both)
+- `src/modules/payments/` module in both JS and TS templates with:
+  - `payments.adapter.js/ts` — provider factory with singleton caching
+  - `payments.service.js/ts` — service layer with in-memory webhook deduplication
+  - `payments.controller.js/ts` — request handlers for all 4 endpoints
+  - `payments.routes.js/ts` — Express router with Swagger JSDoc comments
+  - `payments.schemas.js/ts` — Zod validation schemas for all request bodies
+  - `payments.constants.js/ts` — provider names, event names, webhook header names
+- Four new API endpoints in scaffolded projects:
+  - `POST /payments/create-intent` — create Stripe PaymentIntent or LemonSqueezy checkout session
+  - `POST /payments/refund` — full or partial refunds
+  - `GET /payments/status/:paymentId` — normalized payment status across providers
+  - `POST /payments/webhook` — secure webhook event handling with signature verification
+- Webhook raw body middleware auto-configured in `app.js` when payments module is selected
+- Conditional route loading for payments (same `existsSync` pattern as auth and swagger)
+- Payment env vars added to Zod env schema in both templates (all optional)
+- Payment section added to `.env.example` in both templates with inline documentation
+- Swagger JSDoc comments on all 4 payment endpoints
+- `## Payments Module` section added to `SWAGGER_GUIDE.md` in both templates
+- Payments section added to root `README.md` including migration guide for existing projects
+- Integration tests for payments controller, service, schemas, and routes in both JS and TS templates
+- `PaymentError` custom error class with `code` and `statusCode` fields, compatible with existing error handler
 
-### 🎉 Major Release: Auto-Generated Swagger Documentation
+## [2.2.2] – 2026-02-06
 
 #### ✨ **New Features**
 

package/README.md

@@ -1,6 +1,6 @@
-# Charcole API v2.2
+# Charcole API v2.3
 
-> **Charcole v2.2 is a production-grade Node.js backend starter CLI that scaffolds enterprise-ready Express APIs with first-class TypeScript or JavaScript support, centralized error handling, Zod validation, structured logging, optional JWT authentication, **auto-generated Swagger documentation**, and a revolutionary repository pattern for database abstraction.**
+> **Charcole v2.3 is a production-grade Node.js backend starter CLI that scaffolds enterprise-ready Express APIs with first-class TypeScript or JavaScript support, centralized error handling, Zod validation, structured logging, optional JWT authentication, **auto-generated Swagger documentation**, **optional payment processing (Stripe & LemonSqueezy)**, and a revolutionary repository pattern for database abstraction.**
 
 [![Node.js](https://img.shields.io/badge/Node.js-18+-green.svg)](https://nodejs.org/)
 [![Express.js](https://img.shields.io/badge/Express-4.18+-blue.svg)](https://expressjs.com/)
@@ -8,9 +8,25 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
 [![License: ISC](https://img.shields.io/badge/License-ISC-yellow.svg)](LICENSE)
 
-## What's New in v2.2
+## What's New in v2.3
 
-### 🎯 Auto-Generated Swagger Documentation (@charcoles/swagger)
+### 💳 Payment Processing Module (@charcoles/payments)
+
+Professional payment processing integrated directly into Charcole projects:
+
+- **Stripe adapter** - Full payment intent lifecycle (create, refund, status, webhook verification)
+- **LemonSqueezy adapter** - Perfect for Pakistani developers (Stripe doesn't support PKR payouts; LemonSqueezy provides merchant-of-record payments with full Pakistani bank payout support)
+- **Adapter pattern** - Switch between Stripe and LemonSqueezy via `PAYMENT_PROVIDER` environment variable
+- **Optional module** - Include/exclude during project creation with provider selection
+- **Webhook handling** - Secure webhook event processing with signature verification
+- **Full APIs included** - Four production-ready endpoints:
+  - `POST /api/payments/create-intent` - Create Stripe PaymentIntent or LemonSqueezy checkout session
+  - `POST /api/payments/refund` - Full or partial refunds
+  - `GET /api/payments/status/:paymentId` - Normalized payment status across providers
+  - `POST /api/payments/webhook` - Secure webhook event handling
+- **Standalone package** - Use `@charcoles/payments` in any Express.js project
+
+### Previous: Auto-Generated Swagger Documentation (@charcoles/swagger)
 
 The game-changing feature that eliminates 60-80% of API documentation overhead:
 
@@ -108,6 +124,7 @@ npx create-charcole@latest
 # 1. Language: TypeScript or JavaScript
 # 2. JWT Authentication: Yes/No (includes complete auth system)
 # 3. Swagger Documentation: Yes/No (auto-generated from Zod schemas)
+# 4. Payment Processing: Yes/No (Stripe, LemonSqueezy, or Both)
 
 # Configure environment
 cp .env.example .env
@@ -173,6 +190,77 @@ setupSwagger(app, {
 
 **See complete guide:** `src/lib/swagger/SWAGGER_GUIDE.md` (when swagger is enabled)
 
+## Payment Processing: Drop-in Payments for Any Provider
+
+### The Problem
+
+Payment integration typically requires:
+
+- Complex Stripe/payment provider setup
+- Different APIs for different providers
+- Manual webhook handling
+- Difficult provider switching
+
+### The Solution
+
+Charcole's payment module abstracts payment providers:
+
+```javascript
+// Switch providers with one environment variable
+PAYMENT_PROVIDER=stripe    // Uses Stripe
+PAYMENT_PROVIDER=lemonsqueezy  // Uses LemonSqueezy
+
+// Same API regardless of provider
+POST /api/payments/create-intent
+POST /api/payments/refund
+GET  /api/payments/status/:paymentId
+POST /api/payments/webhook
+```
+
+### Why Two Providers?
+
+**For Pakistani Developers:**
+
+- ❌ Stripe - Does NOT support PKR payouts to Pakistani bank accounts
+- ✅ LemonSqueezy - Merchant-of-record platform with full Pakistani bank payout support
+
+**For Global Developers:**
+
+- ✅ Stripe - Industry standard with global support
+- ✅ LemonSqueezy - Alternative with regional payment solutions
+
+### Setup
+
+1. **During project creation:**
+
+   ```bash
+   npx create-charcole@latest my-api
+   # Select payment processing: Yes → Choose Stripe/LemonSqueezy/Both
+   ```
+
+2. **For existing projects:**
+
+   ```bash
+   npm install @charcoles/payments
+   ```
+
+3. **Configure environment:**
+   ```env
+   PAYMENT_PROVIDER=stripe  # or lemonsqueezy
+   STRIPE_SECRET_KEY=sk_...
+   STRIPE_WEBHOOK_SECRET=whsec_...
+   LEMONSQUEEZY_API_KEY=...
+   LEMONSQUEEZY_WEBHOOK_SECRET=...
+   ```
+
+### Payment routes
+
+Payment endpoints are automatically documented with Swagger when enabled:
+
+- Routes: `/api/payments/create-intent`, `/api/payments/refund`, `/api/payments/status/{paymentId}`, `/api/payments/webhook`
+- All routes use route-level `@swagger` comments and Zod schemas
+- For webhook routes, raw JSON middleware is auto-configured: `app.use('/payments/webhook', express.raw({ type: 'application/json' }))`
+
 ## Repository Pattern: A Game Changer
 
 ### The Problem
@@ -349,7 +437,6 @@ We welcome contributions! Please:
 6. Update README.md for significant changes
 7. If adding Swagger docs, use Zod schemas as single source of truth
 
-
 Good luck!!!
 
 ## 📄 License

package/bin/index.js

@@ -132,13 +132,31 @@ function copyDirRecursive(src, dest, excludeFiles = [], excludeDirs = []) {
         message: "Include auto-generated Swagger documentation?",
         initial: true,
       },
+      {
+        type: "confirm",
+        name: "includePayments",
+        message: "Include payments module? (Stripe / LemonSqueezy)",
+        initial: false,
+      },
+      {
+        type: (prev, values) => (values.includePayments ? "select" : null),
+        name: "paymentProvider",
+        message: "Which payment provider will you use?",
+        choices: [
+          { title: "Stripe (global)", value: "stripe" },
+          { title: "LemonSqueezy (Pakistan + global)", value: "lemonsqueezy" },
+          { title: "Both (I'll switch via env var)", value: "both" },
+        ],
+        initial: 0,
+      },
     );
 
     const responses = await prompts(questions);
 
     // Use command line project name if provided, otherwise use prompt response
     const projectName = projectNameFromArgs || responses.projectName;
-    const { language, auth, swagger } = responses;
+    const { language, auth, swagger, includePayments, paymentProvider } =
+      responses;
 
     if (!projectName || projectName.trim() === "") {
       console.error("❌ Project name is required");
@@ -347,6 +365,94 @@ function copyDirRecursive(src, dest, excludeFiles = [], excludeDirs = []) {
       }
     }
 
+    // Handle payments module if selected
+    if (includePayments) {
+      console.log("\n📦 Adding payments module...");
+
+      // The payments module is in src/modules/payments in the template
+      const paymentsModulePath = path.join(
+        templateDir,
+        "src",
+        "modules",
+        "payments",
+      );
+
+      if (!fs.existsSync(paymentsModulePath)) {
+        console.error(`❌ Payments module not found at ${paymentsModulePath}`);
+      } else {
+        // 1. Merge payments module's package.json
+        const paymentsPkgPath = path.join(paymentsModulePath, "package.json");
+
+        if (fs.existsSync(paymentsPkgPath)) {
+          try {
+            const paymentsPkg = JSON.parse(
+              fs.readFileSync(paymentsPkgPath, "utf-8"),
+            );
+            console.log("✓ Found payments module package.json");
+
+            mergedPkg = mergePackageJson(mergedPkg, paymentsPkg);
+            console.log("✓ Merged payments module dependencies");
+            console.log(
+              "  Added dependencies:",
+              Object.keys(paymentsPkg.dependencies || {}).join(", "),
+            );
+            if (paymentsPkg.devDependencies) {
+              console.log(
+                "  Added devDependencies:",
+                Object.keys(paymentsPkg.devDependencies).join(", "),
+              );
+            }
+          } catch (error) {
+            console.error(
+              `❌ Failed to parse payments module package.json:`,
+              error.message,
+            );
+          }
+        } else {
+          console.error(
+            "❌ Payments module package.json not found at:",
+            paymentsPkgPath,
+          );
+        }
+
+        const targetPaymentsPath = path.join(targetModulesDir, "payments");
+        console.log(
+          `Copying payments module to: ${targetPaymentsPath} (excluding package.json)`,
+        );
+
+        copyDirRecursive(
+          paymentsModulePath,
+          targetPaymentsPath,
+          ["package.json"],
+          [],
+        );
+        console.log(
+          "✓ Copied payments module files (package.json was excluded)",
+        );
+
+        const copiedPkgPath = path.join(targetPaymentsPath, "package.json");
+        if (fs.existsSync(copiedPkgPath)) {
+          console.warn(
+            "⚠️ package.json was accidentally copied, removing it...",
+          );
+          fs.unlinkSync(copiedPkgPath);
+        }
+      }
+    } else {
+      console.log("\n⏭️  Skipping payments module");
+
+      const targetPaymentsPath = path.join(
+        targetDir,
+        "src",
+        "modules",
+        "payments",
+      );
+      if (fs.existsSync(targetPaymentsPath)) {
+        console.log("Cleaning up payments directory (not selected)...");
+        fs.rmSync(targetPaymentsPath, { recursive: true, force: true });
+      }
+    }
+
     // Remove Swagger imports and setup from app file if not selected
     if (!swagger) {
       console.log("\n🧹 Removing Swagger references from app file...");
@@ -430,6 +536,20 @@ function copyDirRecursive(src, dest, excludeFiles = [], excludeDirs = []) {
           exampleContent = `APP_NAME=CHARCOLE API\n` + exampleContent;
         }
 
+        if (includePayments) {
+          if (paymentProvider === "both") {
+            exampleContent = exampleContent.replace(
+              "PAYMENT_PROVIDER=",
+              'PAYMENT_PROVIDER=   # Set to "stripe" or "lemonsqueezy"',
+            );
+          } else {
+            exampleContent = exampleContent.replace(
+              "PAYMENT_PROVIDER=",
+              `PAYMENT_PROVIDER=${paymentProvider}`,
+            );
+          }
+        }
+
         fs.writeFileSync(envPath, exampleContent, "utf-8");
         console.log("✓ Created .env from .env.example with default APP_NAME");
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-charcole",
-  "version": "2.2.2",
+  "version": "2.3.0",
   "description": "CLI to create production-ready Node.js Express APIs with TypeScript/JavaScript, JWT auth, auto-generated Swagger docs, and repository pattern",
   "license": "MIT",
   "author": {

package/packages/payments/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## [1.0.0] - 2024-04-29
+
+### Added
+
+- Initial release
+- StripeAdapter: createPayment, refundPayment, getPaymentStatus, verifyWebhook
+- LemonSqueezyAdapter: same interface with regional payment support
+- setupPayments() Express integration function
+- Zod validation for all inputs
+- In-memory webhook deduplication
+- Full TypeScript definitions
+- Comprehensive test suite with Vitest

package/packages/payments/README.md

@@ -0,0 +1,222 @@
+# @charcoles/payments
+
+Drop-in payment processing for Express apps. Supports Stripe and LemonSqueezy for regional payments (Pakistan, etc.).
+
+## Installation
+
+```bash
+npm install @charcoles/payments
+```
+
+## Quick Start
+
+### Standalone Express App
+
+```js
+import express from "express";
+import { setupPayments } from "@charcoles/payments";
+
+const app = express();
+
+// IMPORTANT: Register webhook raw body middleware BEFORE express.json()
+app.use("/payments/webhook", express.raw({ type: "application/json" }));
+
+// Global JSON parsing for other routes
+app.use(express.json());
+
+// Setup payments
+setupPayments(app, {
+  provider: "lemonsqueezy",
+  lemonSqueezyApiKey: process.env.LEMONSQUEEZY_API_KEY,
+  lemonSqueezyWebhookSecret: process.env.LEMONSQUEEZY_WEBHOOK_SECRET,
+  lemonSqueezyStoreId: process.env.LEMONSQUEEZY_STORE_ID,
+});
+
+app.listen(3000);
+```
+
+### Environment Variables
+
+| Variable                      | Stripe | LemonSqueezy | Description                        |
+| ----------------------------- | ------ | ------------ | ---------------------------------- |
+| `PAYMENT_PROVIDER`            | ✅     | ✅           | `"stripe"` or `"lemonsqueezy"`     |
+| `STRIPE_SECRET_KEY`           | ✅     | ❌           | `sk_live_...` or `sk_test_...`     |
+| `STRIPE_WEBHOOK_SECRET`       | ✅     | ❌           | `whsec_...` from Stripe dashboard  |
+| `LEMONSQUEEZY_API_KEY`        | ❌     | ✅           | From LS API settings               |
+| `LEMONSQUEEZY_WEBHOOK_SECRET` | ❌     | ✅           | From LS webhook settings           |
+| `LEMONSQUEEZY_STORE_ID`       | ❌     | ✅           | Numeric store ID from LS dashboard |
+
+### Stripe Configuration
+
+```js
+setupPayments(app, {
+  provider: "stripe",
+  stripeSecretKey: "sk_live_...",
+  stripeWebhookSecret: "whsec_...",
+});
+```
+
+### LemonSqueezy Configuration
+
+```js
+setupPayments(app, {
+  provider: "lemonsqueezy",
+  lemonSqueezyApiKey: "your_api_key",
+  lemonSqueezyWebhookSecret: "your_webhook_secret",
+  lemonSqueezyStoreId: "12345",
+});
+```
+
+## API Endpoints
+
+### POST /payments/create-intent
+
+Create a payment intent or checkout session.
+
+**Request:**
+
+```json
+{
+  "amount": 2999,
+  "currency": "usd",
+  "metadata": {
+    "orderId": "order_123"
+  }
+}
+```
+
+**Response (Stripe):**
+
+```json
+{
+  "success": true,
+  "data": {
+    "id": "pi_3abc...",
+    "clientSecret": "pi_..._secret_...",
+    "status": "requires_payment_method",
+    "amount": 2999,
+    "currency": "usd"
+  }
+}
+```
+
+**Response (LemonSqueezy):**
+
+```json
+{
+  "success": true,
+  "data": {
+    "id": "12345",
+    "checkoutUrl": "https://app.lemonsqueezy.com/checkout/...",
+    "status": "created",
+    "amount": 2999,
+    "currency": "usd"
+  }
+}
+```
+
+### POST /payments/refund
+
+Refund a payment.
+
+**Request:**
+
+```json
+{
+  "paymentId": "pi_3abc...",
+  "amount": 1500
+}
+```
+
+### GET /payments/status/:paymentId
+
+Get payment status.
+
+**Response:**
+
+```json
+{
+  "success": true,
+  "data": {
+    "id": "pi_3abc...",
+    "status": "paid",
+    "amount": 2999,
+    "currency": "usd"
+  }
+}
+```
+
+### POST /payments/webhook
+
+Receive provider webhooks. Returns `{"received": true}`.
+
+## LemonSqueezy Notes
+
+### Regional Support
+
+LemonSqueezy is included specifically for developers in regions where Stripe payouts are not available (e.g., Pakistan). LemonSqueezy uses a merchant-of-record model, so you sell through their entity and receive bank transfers.
+
+### Variant IDs Required
+
+Unlike Stripe (which accepts raw amounts), LemonSqueezy requires a Product Variant ID. Create a "Pay What You Want" product in your LemonSqueezy dashboard and pass the variant ID in `metadata.variantId`:
+
+```json
+{
+  "amount": 10000,
+  "currency": "pkr",
+  "metadata": {
+    "variantId": "12345"
+  }
+}
+```
+
+### Raw Body Middleware Warning
+
+⚠️ **Critical**: Webhook endpoints require raw `Buffer` bodies for signature verification. Always register `express.raw({ type: 'application/json' })` on the webhook path **before** `express.json()`:
+
+```js
+// ✅ Correct order
+app.use("/payments/webhook", express.raw({ type: "application/json" }));
+app.use(express.json()); // Global JSON parsing
+
+// ❌ Wrong order — webhooks will fail
+app.use(express.json());
+app.use("/payments/webhook", express.raw({ type: "application/json" }));
+```
+
+## TypeScript Support
+
+Full TypeScript definitions included:
+
+```ts
+import {
+  setupPayments,
+  PaymentAdapter,
+  StripeAdapter,
+} from "@charcoles/payments";
+
+interface MyOptions {
+  provider: "stripe";
+  stripeSecretKey: string;
+  stripeWebhookSecret: string;
+}
+
+setupPayments(app, options);
+```
+
+## Error Handling
+
+All errors are `PaymentError` instances with specific codes:
+
+- `CONFIG_ERROR`: Missing required configuration
+- `WEBHOOK_INVALID`: Invalid webhook signature
+- `STRIPE_ERROR`: Stripe API error
+- `LS_CHECKOUT_FAILED`: LemonSqueezy checkout creation failed
+- `LS_REFUND_FAILED`: LemonSqueezy refund failed
+- `LS_ORDER_NOT_FOUND`: LemonSqueezy order not found
+- `MISSING_VARIANT_ID`: LemonSqueezy variantId not provided
+- `PROVIDER_NOT_CONFIGURED`: PAYMENT_PROVIDER env var missing
+
+## License
+
+ISC

package/packages/payments/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@charcoles/payments",
+  "version": "1.0.1",
+  "description": "Drop-in payment processing for Express apps. Stripe + LemonSqueezy.",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.js",
+      "types": "./src/index.d.ts"
+    }
+  },
+  "author": {
+    "name": "Sheraz Manzoor",
+    "email": "sheraz.dev121@gmail.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sheraz4196/charcole.git",
+    "directory": "packages/payments"
+  },
+  "bugs": {
+    "url": "https://github.com/sheraz4196/charcole/issues"
+  },
+  "homepage": "https://www.charcole.site/guides/payments/introduction",
+  "files": [
+    "src",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "node build.js",
+    "test": "vitest",
+    "test:run": "vitest run"
+  },
+  "peerDependencies": {
+    "express": "^4.18.0 || ^5.0.0"
+  },
+  "dependencies": {
+    "stripe": "^14.0.0",
+    "@lemonsqueezy/lemonsqueezy.js": "^4.0.0",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.0",
+    "@types/node": "^20.0.0",
+    "vitest": "^1.0.0"
+  },
+  "keywords": [
+    "payments",
+    "stripe",
+    "lemonsqueezy",
+    "express",
+    "charcole"
+  ],
+  "license": "ISC",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/packages/payments/smoke-test.js

@@ -0,0 +1,20 @@
+import { PaymentError } from "./src/errors/PaymentError.js";
+import { StripeAdapter } from "./src/adapters/StripeAdapter.js";
+
+// Test 1: PaymentError works
+const err = new PaymentError("test", "TEST_CODE", 400);
+console.assert(err.name === "PaymentError", "FAIL: PaymentError.name");
+console.assert(err.code === "TEST_CODE", "FAIL: PaymentError.code");
+console.assert(err.statusCode === 400, "FAIL: PaymentError.statusCode");
+console.log("✅ PaymentError works");
+
+// Test 2: StripeAdapter rejects missing config
+try {
+  new StripeAdapter({});
+  console.log("❌ StripeAdapter should have thrown");
+} catch (e) {
+  console.assert(e.code === "CONFIG_ERROR", "FAIL: wrong error code");
+  console.log("✅ StripeAdapter rejects missing config");
+}
+
+console.log("\nSmoke test complete.");