create-charcole 2.2.1 → 2.3.0

package/template/js/src/modules/payments/payments.routes.js

@@ -0,0 +1,125 @@
+import { Router } from "express";
+import { validateRequest } from "../../middlewares/validateRequest.js";
+import * as controller from "./payments.controller.js";
+import {
+  createPaymentSchema,
+  refundPaymentSchema,
+} from "./payments.schemas.js";
+
+const router = Router();
+
+/**
+ * @swagger
+ * /api/payments/create-intent:
+ *   post:
+ *     summary: Create a payment intent or checkout session
+ *     tags:
+ *       - Payments
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             required: [amount, currency]
+ *             properties:
+ *               amount:
+ *                 type: integer
+ *                 description: Amount in smallest currency unit (cents for USD, paisas for PKR)
+ *                 example: 2999
+ *               currency:
+ *                 type: string
+ *                 description: ISO 4217 currency code
+ *                 example: usd
+ *               metadata:
+ *                 type: object
+ *                 description: Optional metadata. LemonSqueezy requires variantId here.
+ *     responses:
+ *       201:
+ *         description: Payment intent created
+ *       400:
+ *         description: Validation error
+ */
+router.post(
+  "/create-intent",
+  validateRequest(createPaymentSchema),
+  controller.createPayment,
+);
+
+/**
+ * @swagger
+ * /api/payments/refund:
+ *   post:
+ *     summary: Refund a payment
+ *     tags:
+ *       - Payments
+ *     requestBody:
+ *       required: true
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             required: [paymentId]
+ *             properties:
+ *               paymentId:
+ *                 type: string
+ *                 example: pi_123456789
+ *               amount:
+ *                 type: integer
+ *                 description: Optional refund amount in smallest currency unit
+ *                 example: 2999
+ *     responses:
+ *       200:
+ *         description: Refund processed
+ *       400:
+ *         description: Validation error
+ */
+router.post(
+  "/refund",
+  validateRequest(refundPaymentSchema),
+  controller.refundPayment,
+);
+
+/**
+ * @swagger
+ * /api/payments/status/{paymentId}:
+ *   get:
+ *     summary: Get payment status
+ *     tags:
+ *       - Payments
+ *     parameters:
+ *       - in: path
+ *         name: paymentId
+ *         required: true
+ *         schema:
+ *           type: string
+ *     responses:
+ *       200:
+ *         description: Payment status retrieved
+ *       404:
+ *         description: Payment not found
+ */
+router.get("/status/:paymentId", controller.getPaymentStatus);
+
+/**
+ * @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", controller.handleWebhook);
+
+export default router;

package/template/js/src/modules/payments/payments.schemas.js

@@ -0,0 +1,28 @@
+import { z } from "zod";
+
+export const createPaymentSchema = z.object({
+  amount: z
+    .number({ required_error: "amount is required" })
+    .int("amount must be an integer (smallest currency unit, e.g. cents)")
+    .positive("amount must be positive")
+    .max(99999999, "amount exceeds maximum"),
+
+  currency: z
+    .string({ required_error: "currency is required" })
+    .length(3, "currency must be a 3-letter ISO 4217 code (e.g. usd, pkr)")
+    .toLowerCase(),
+
+  metadata: z.record(z.string()).optional().default({}),
+});
+
+export const refundPaymentSchema = z.object({
+  paymentId: z
+    .string({ required_error: "paymentId is required" })
+    .min(1, "paymentId cannot be empty"),
+
+  amount: z
+    .number()
+    .int("amount must be an integer")
+    .positive("amount must be positive")
+    .optional(),
+});

package/template/js/src/modules/payments/payments.service.js

@@ -0,0 +1,34 @@
+import { getAdapter } from "./payments.adapter.js";
+
+const processedWebhookIds = new Set();
+
+export async function createPayment({ amount, currency, metadata }) {
+  const adapter = getAdapter();
+  return adapter.createPayment({ amount, currency, metadata });
+}
+
+export async function refundPayment({ paymentId, amount }) {
+  const adapter = getAdapter();
+  return adapter.refundPayment({ paymentId, amount });
+}
+
+export async function getPaymentStatus(paymentId) {
+  const adapter = getAdapter();
+  return adapter.getPaymentStatus(paymentId);
+}
+
+export async function processWebhook(rawBody, signature) {
+  const adapter = getAdapter();
+  const result = await adapter.verifyWebhook(rawBody, signature);
+
+  const eventId = result.data?.id
+    ? String(result.data.id)
+    : `${result.event}-${Date.now()}`;
+
+  if (processedWebhookIds.has(eventId)) {
+    return { ...result, duplicate: true };
+  }
+
+  processedWebhookIds.add(eventId);
+  return { ...result, duplicate: false };
+}

package/template/js/src/modules/swagger/package.json

@@ -1,5 +1,5 @@
 {
   "dependencies": {
-    "@charcoles/swagger": "file:./charcole-swagger-1.0.0.tgz"
+    "@charcoles/swagger": "^1.0.1"
   }
 }

package/template/js/src/routes/index.js

@@ -1,4 +1,7 @@
 import { Router } from "express";
+import { existsSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
 import {
   getHealth,
   createItem,
@@ -8,6 +11,9 @@ import { validateRequest } from "../middlewares/validateRequest.js";
 import { requireAuth } from "../modules/auth/auth.middlewares.js";
 import protectedRoutes from "./protected.js";
 import authRoutes from "../modules/auth/auth.routes.js";
+import paymentsRoutes from "../modules/payments/payments.routes.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
 const router = Router();
 
 // Health check
@@ -19,6 +25,16 @@ router.post("/items", validateRequest(createItemSchema), createItem);
 // 🔐 Auth routes
 router.use("/auth", authRoutes);
 
+// Payments routes — only loaded if the payments module was included during scaffolding
+const paymentsRoutesPath = join(
+  __dirname,
+  "../modules/payments/payments.routes.js",
+);
+if (existsSync(paymentsRoutesPath)) {
+  const { default: paymentsRoutes } = await import(paymentsRoutesPath);
+  router.use("/payments", paymentsRoutes);
+}
+
 // 🔐 Protected routes (REQUIRED BEARER TOKEN FOR THEM)
 router.use("/protected", protectedRoutes);
 

package/template/ts/.env.example

@@ -1,4 +1,5 @@
 # Server Configuration
+APP_NAME=CHARCOLE API
 NODE_ENV=development
 PORT=3000
 
@@ -13,4 +14,20 @@ 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
+STRIPE_SECRET_KEY=
+STRIPE_WEBHOOK_SECRET=
+STRIPE_PUBLISHABLE_KEY=
+
+# LemonSqueezy — https://app.lemonsqueezy.com/settings/api
+LEMONSQUEEZY_API_KEY=
+LEMONSQUEEZY_WEBHOOK_SECRET=
+LEMONSQUEEZY_STORE_ID=

package/template/ts/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)
 
 ---
 
@@ -34,9 +35,13 @@ Welcome! This guide will help you set up and start using the Charcole API framew
 
 2. **Create environment file**
 
-   ```bash
-   cp .env.example .env
-   ```
+The `create-charcole` CLI will automatically create a `.env` from `.env.example` and initialize a Git repository for you. Edit the generated `.env` as needed.
+
+If you prefer to create it manually:
+
+```bash
+cp .env.example .env
+```
 
 3. **Run the charcole**
    ```bash
@@ -519,6 +524,135 @@ 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
+
+```typescript
+import { setupPayments } from "@charcoles/payments";
+
+// In your app.ts
+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: Request, res: Response) => {
+    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:
+
+```typescript
+// src/modules/payments/payments.routes.ts
+// POST /api/payments/webhook automatically handles:
+// - Stripe: payment_intent.succeeded, charge.refunded
+// - LemonSqueezy: order_created, order_refunded
+
+// Raw body middleware auto-configured in app.ts
+// app.use('/payments/webhook', express.raw({ type: 'application/json' }))
+```
+
+### Error Handling
+
+Payment errors are automatically caught by the global error handler:
+
+```typescript
+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/ts/basePackage.json

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

package/template/ts/src/app.ts

@@ -1,4 +1,7 @@
 import express, { Request, Response, NextFunction } from "express";
+import { existsSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
 import cors from "cors";
 import { userRepo } from "./repositories/user.repo.ts";
 import { env } from "./config/env.ts";
@@ -14,6 +17,12 @@ import routes from "./routes/index.ts";
 import swaggerOptions from "./config/swagger.config.ts";
 import { setupSwagger } from "@charcoles/swagger";
 
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const paymentsModulePath = join(
+  __dirname,
+  "modules/payments/payments.routes.ts",
+);
+
 export const app = express();
 
 app.set("trust proxy", 1);
@@ -27,6 +36,10 @@ app.use(
   }),
 );
 
+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/ts/src/config/env.ts

@@ -8,6 +8,13 @@ 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),
+  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(),
 });
 
 type EnvSchema = z.infer<typeof envSchema>;

package/template/ts/src/config/swagger.config.ts

@@ -3,7 +3,7 @@ import { createItemSchema } from "../modules/health/controller.ts";
 
 const swaggerConfig = {
   title: process.env.APP_NAME || "Charcole API",
-  version: process.env.APP_VERSION || "1.0.0",
+  version: process.env.APP_VERSION || "1.0.1",
   description: "Production-ready Node.js Express API",
   path: "/api-docs",
   servers: [

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

@@ -18,7 +18,7 @@ import { createItemSchema } from "../modules/health/controller.ts";
 
 const swaggerConfig = {
   title: "My API",
-  version: "1.0.0",
+  version: "1.0.1",
   // Auto-register schemas - they'll be converted to OpenAPI automatically!
   schemas: {
     registerSchema,
@@ -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
+
+```typescript
+/**
+ * @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:
+
+```typescript
+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
@@ -472,7 +506,7 @@ const app = express();
 
 setupSwagger(app, {
   title: "My API",
-  version: "1.0.0",
+  version: "1.0.1",
   schemas: {
     mySchema, // Your Zod schemas
   },