create-charcole 2.2.2 → 2.3.0

package/template/ts/src/modules/payments/__tests__/payments.service.test.ts

@@ -0,0 +1,135 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+vi.mock('../payments.adapter.ts', () => ({
+  getAdapter: vi.fn(),
+  resetAdapter: vi.fn(),
+}))
+
+import { getAdapter } from '../payments.adapter.ts'
+import * as service from '../payments.service.ts'
+
+beforeEach(() => {
+  vi.clearAllMocks()
+})
+
+describe('payments.service', () => {
+  it('delegates to adapter.createPayment and returns its result', async () => {
+    const mockResult = {
+      id: 'pi_test_123',
+      clientSecret: 'secret_abc',
+      status: 'requires_payment_method',
+      amount: 999,
+      currency: 'usd',
+      metadata: {},
+    }
+    const adapter = { createPayment: vi.fn().mockResolvedValue(mockResult) }
+    getAdapter.mockReturnValue(adapter)
+
+    const result = await service.createPayment({ amount: 999, currency: 'usd' })
+
+    expect(adapter.createPayment).toHaveBeenCalledWith({ amount: 999, currency: 'usd' })
+    expect(result).toEqual(mockResult)
+  })
+
+  it('propagates errors from adapter.createPayment', async () => {
+    const error = new Error('payment failed')
+    const adapter = { createPayment: vi.fn().mockRejectedValue(error) }
+    getAdapter.mockReturnValue(adapter)
+
+    await expect(service.createPayment({ amount: 999, currency: 'usd' })).rejects.toThrow(error)
+  })
+
+  it('delegates to adapter.refundPayment with paymentId and amount', async () => {
+    const mockResult = { id: 're_test_123', status: 'succeeded', amount: 500 }
+    const adapter = { refundPayment: vi.fn().mockResolvedValue(mockResult) }
+    getAdapter.mockReturnValue(adapter)
+
+    const result = await service.refundPayment({ paymentId: 'pi_123', amount: 500 })
+
+    expect(adapter.refundPayment).toHaveBeenCalledWith({ paymentId: 'pi_123', amount: 500 })
+    expect(result).toEqual(mockResult)
+  })
+
+  it('delegates to adapter.refundPayment without amount when not provided', async () => {
+    const mockResult = { id: 're_test_124', status: 'succeeded', amount: 0 }
+    const adapter = { refundPayment: vi.fn().mockResolvedValue(mockResult) }
+    getAdapter.mockReturnValue(adapter)
+
+    const result = await service.refundPayment({ paymentId: 'pi_123' })
+
+    expect(adapter.refundPayment).toHaveBeenCalledWith({ paymentId: 'pi_123', amount: undefined })
+    expect(result).toEqual(mockResult)
+  })
+
+  it('propagates adapter errors from refundPayment', async () => {
+    const error = new Error('refund failed')
+    const adapter = { refundPayment: vi.fn().mockRejectedValue(error) }
+    getAdapter.mockReturnValue(adapter)
+
+    await expect(service.refundPayment({ paymentId: 'pi_123', amount: 500 })).rejects.toThrow(error)
+  })
+
+  it('delegates to adapter.getPaymentStatus with the paymentId string', async () => {
+    const mockResult = { id: 'pi_123', status: 'paid', amount: 999, currency: 'usd', metadata: {} }
+    const adapter = { getPaymentStatus: vi.fn().mockResolvedValue(mockResult) }
+    getAdapter.mockReturnValue(adapter)
+
+    const result = await service.getPaymentStatus('pi_123')
+
+    expect(adapter.getPaymentStatus).toHaveBeenCalledWith('pi_123')
+    expect(result).toEqual(mockResult)
+  })
+
+  it('propagates adapter errors from getPaymentStatus', async () => {
+    const error = new Error('status error')
+    const adapter = { getPaymentStatus: vi.fn().mockRejectedValue(error) }
+    getAdapter.mockReturnValue(adapter)
+
+    await expect(service.getPaymentStatus('pi_123')).rejects.toThrow(error)
+  })
+
+  it('calls adapter.verifyWebhook and returns duplicate:false on first call', async () => {
+    const adapter = { verifyWebhook: vi.fn().mockResolvedValue({ event: 'payment_intent.succeeded', data: { id: 'evt_001' } }) }
+    getAdapter.mockReturnValue(adapter)
+
+    const result = await service.processWebhook(Buffer.from('{"id":"evt_001"}'), 'sig')
+
+    expect(adapter.verifyWebhook).toHaveBeenCalledWith(Buffer.from('{"id":"evt_001"}'), 'sig')
+    expect(result.duplicate).toBe(false)
+    expect(result.event).toBe('payment_intent.succeeded')
+  })
+
+  it('returns duplicate:true on second call with same event id', async () => {
+    const event = { event: 'payment_intent.succeeded', data: { id: 'evt_002' } }
+    const adapter = { verifyWebhook: vi.fn().mockResolvedValue(event) }
+    getAdapter.mockReturnValue(adapter)
+
+    const first = await service.processWebhook(Buffer.from('{"id":"evt_002"}'), 'sig')
+    const second = await service.processWebhook(Buffer.from('{"id":"evt_002"}'), 'sig')
+
+    expect(first.duplicate).toBe(false)
+    expect(second.duplicate).toBe(true)
+    expect(adapter.verifyWebhook).toHaveBeenCalledTimes(2)
+  })
+
+  it('treats events without id as unique using event+timestamp', async () => {
+    const adapter = { verifyWebhook: vi.fn().mockResolvedValue({ event: 'some_event', data: {} }) }
+    getAdapter.mockReturnValue(adapter)
+
+    const first = await service.processWebhook(Buffer.from('{"id":"evt_none_1"}'), 'sig')
+    await new Promise((resolve) => setTimeout(resolve, 1))
+    const second = await service.processWebhook(Buffer.from('{"id":"evt_none_2"}'), 'sig')
+
+    expect(first.duplicate).toBe(false)
+    expect(second.duplicate).toBe(false)
+    expect(adapter.verifyWebhook).toHaveBeenCalledTimes(2)
+  })
+
+  it('propagates PaymentError WEBHOOK_INVALID from adapter', async () => {
+    const error = new Error('bad sig')
+    const adapter = { verifyWebhook: vi.fn().mockRejectedValue(error) }
+    getAdapter.mockReturnValue(adapter)
+
+    await expect(service.processWebhook(Buffer.from('{"id":"evt_003"}'), 'sig')).rejects.toThrow(error)
+  })
+})

package/template/ts/src/modules/payments/package.json

@@ -0,0 +1,7 @@
+{
+  "dependencies": {
+    "@charcoles/payments": "^1.0.1",
+    "stripe": "^14.0.0",
+    "@lemonsqueezy/lemonsqueezy.js": "^4.0.0"
+  }
+}

package/template/ts/src/modules/payments/payments.adapter.ts

@@ -0,0 +1,74 @@
+import { env } from "../../config/env.ts";
+import {
+  StripeAdapter,
+  LemonSqueezyAdapter,
+  PaymentError,
+} from "@charcoles/payments";
+import type { PaymentAdapter } from "./payments.types.ts";
+
+let adapter: PaymentAdapter | null = null;
+
+export function getAdapter(): PaymentAdapter {
+  if (adapter) {
+    return adapter;
+  }
+
+  const provider = env.PAYMENT_PROVIDER;
+
+  if (!provider) {
+    const error = new PaymentError(
+      'PAYMENT_PROVIDER env var is not set. Set it to "stripe" or "lemonsqueezy".',
+    );
+    error.code = "PROVIDER_NOT_CONFIGURED";
+    error.statusCode = 500;
+    throw error;
+  }
+
+  if (provider === "stripe") {
+    if (!env.STRIPE_SECRET_KEY || !env.STRIPE_WEBHOOK_SECRET) {
+      const error = new PaymentError(
+        "Stripe configuration is incomplete. Set STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET.",
+      );
+      error.code = "CONFIG_ERROR";
+      error.statusCode = 500;
+      throw error;
+    }
+
+    adapter = new StripeAdapter({
+      secretKey: env.STRIPE_SECRET_KEY,
+      webhookSecret: env.STRIPE_WEBHOOK_SECRET,
+    }) as unknown as PaymentAdapter;
+  } else if (provider === "lemonsqueezy") {
+    if (
+      !env.LEMONSQUEEZY_API_KEY ||
+      !env.LEMONSQUEEZY_WEBHOOK_SECRET ||
+      !env.LEMONSQUEEZY_STORE_ID
+    ) {
+      const error = new PaymentError(
+        "LemonSqueezy configuration is incomplete. Set LEMONSQUEEZY_API_KEY, LEMONSQUEEZY_WEBHOOK_SECRET, and LEMONSQUEEZY_STORE_ID.",
+      );
+      error.code = "CONFIG_ERROR";
+      error.statusCode = 500;
+      throw error;
+    }
+
+    adapter = new LemonSqueezyAdapter({
+      apiKey: env.LEMONSQUEEZY_API_KEY,
+      webhookSecret: env.LEMONSQUEEZY_WEBHOOK_SECRET,
+      storeId: env.LEMONSQUEEZY_STORE_ID,
+    }) as unknown as PaymentAdapter;
+  } else {
+    const error = new PaymentError(
+      `Unknown PAYMENT_PROVIDER: "${provider}". Use "stripe" or "lemonsqueezy".`,
+    );
+    error.code = "CONFIG_ERROR";
+    error.statusCode = 500;
+    throw error;
+  }
+
+  return adapter;
+}
+
+export function resetAdapter(): void {
+  adapter = null;
+}

package/template/ts/src/modules/payments/payments.constants.ts

@@ -0,0 +1,18 @@
+export const PAYMENT_PROVIDERS = {
+  STRIPE: "stripe",
+  LEMONSQUEEZY: "lemonsqueezy",
+} as const;
+
+export const PAYMENT_EVENTS = {
+  STRIPE_PAYMENT_SUCCEEDED: "payment_intent.succeeded",
+  STRIPE_PAYMENT_FAILED: "payment_intent.payment_failed",
+  STRIPE_REFUND_CREATED: "charge.refunded",
+  LS_ORDER_CREATED: "order_created",
+  LS_ORDER_REFUNDED: "order_refunded",
+  LS_SUBSCRIPTION_CANCELLED: "subscription_cancelled",
+} as const;
+
+export const WEBHOOK_HEADERS = {
+  stripe: "stripe-signature",
+  lemonsqueezy: "x-signature",
+} as const;

package/template/ts/src/modules/payments/payments.controller.ts

@@ -0,0 +1,104 @@
+import { Request, Response, NextFunction } from "express";
+import * as paymentsService from "./payments.service.ts";
+import { sendSuccess } from "../../utils/response.ts";
+import {
+  createPaymentSchema,
+  refundPaymentSchema,
+} from "./payments.schemas.ts";
+import { PAYMENT_EVENTS, WEBHOOK_HEADERS } from "./payments.constants.ts";
+import { logger } from "../../utils/logger.ts";
+
+export const createPayment = async (
+  req: Request,
+  res: Response,
+  next: NextFunction,
+): Promise<void> => {
+  try {
+    const validated = createPaymentSchema.parse(req.body);
+    const result = await paymentsService.createPayment(validated);
+    sendSuccess(res, result, 201);
+  } catch (err) {
+    next(err);
+  }
+};
+
+export const refundPayment = async (
+  req: Request,
+  res: Response,
+  next: NextFunction,
+): Promise<void> => {
+  try {
+    const validated = refundPaymentSchema.parse(req.body);
+    const result = await paymentsService.refundPayment(validated);
+    sendSuccess(res, result);
+  } catch (err) {
+    next(err);
+  }
+};
+
+export const getPaymentStatus = async (
+  req: Request,
+  res: Response,
+  next: NextFunction,
+): Promise<void> => {
+  try {
+    const result = await paymentsService.getPaymentStatus(req.params.paymentId);
+    sendSuccess(res, result);
+  } catch (err) {
+    next(err);
+  }
+};
+
+export const handleWebhook = async (
+  req: Request,
+  res: Response,
+  next: NextFunction,
+): Promise<void> => {
+  try {
+    const provider = process.env.PAYMENT_PROVIDER;
+    const headerName =
+      provider === "stripe"
+        ? WEBHOOK_HEADERS.stripe
+        : WEBHOOK_HEADERS.lemonsqueezy;
+
+    const signature = req.headers[headerName] as string | undefined;
+
+    if (!signature) {
+      res.status(400).json({ error: "Missing webhook signature header" });
+      return;
+    }
+
+    const rawBody = req.body as Buffer;
+    const result = await paymentsService.processWebhook(rawBody, signature);
+
+    if (result.duplicate) {
+      logger.info(
+        `Duplicate webhook event received and ignored: ${result.event}`,
+      );
+      res.status(200).json({ received: true, duplicate: true });
+      return;
+    }
+
+    logger.info(`Webhook event received: ${result.event}`);
+
+    switch (result.event) {
+      case PAYMENT_EVENTS.STRIPE_PAYMENT_SUCCEEDED:
+      case PAYMENT_EVENTS.LS_ORDER_CREATED:
+        logger.info("Payment confirmed. Add your fulfillment logic here.");
+        break;
+      case PAYMENT_EVENTS.STRIPE_PAYMENT_FAILED:
+        logger.warn("Payment failed. Add your failure handling logic here.");
+        break;
+      case PAYMENT_EVENTS.LS_ORDER_REFUNDED:
+      case PAYMENT_EVENTS.STRIPE_REFUND_CREATED:
+        logger.info("Refund processed. Add your refund handling logic here.");
+        break;
+      default:
+        logger.info(`Unhandled webhook event: ${result.event}`);
+    }
+
+    res.status(200).json({ received: true });
+  } catch (err) {
+    next(err);
+  }
+};

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

@@ -0,0 +1,125 @@
+import { Router } from "express";
+import { validateRequest } from "../../middlewares/validateRequest.ts";
+import * as controller from "./payments.controller.ts";
+import {
+  createPaymentSchema,
+  refundPaymentSchema,
+} from "./payments.schemas.ts";
+
+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/ts/src/modules/payments/payments.schemas.ts

@@ -0,0 +1,31 @@
+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(),
+});
+
+export type CreatePaymentInput = z.infer<typeof createPaymentSchema>;
+export type RefundPaymentInput = z.infer<typeof refundPaymentSchema>;

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

@@ -0,0 +1,51 @@
+import { getAdapter } from "./payments.adapter.ts";
+import type {
+  CreatePaymentParams,
+  CreatePaymentResult,
+  RefundParams,
+  RefundResult,
+  PaymentStatus,
+  WebhookResult,
+} from "./payments.types.ts";
+
+const processedWebhookIds = new Set<string>();
+
+export async function createPayment(
+  params: CreatePaymentParams,
+): Promise<CreatePaymentResult> {
+  const adapter = getAdapter();
+  return adapter.createPayment(params);
+}
+
+export async function refundPayment(
+  params: RefundParams,
+): Promise<RefundResult> {
+  const adapter = getAdapter();
+  return adapter.refundPayment(params);
+}
+
+export async function getPaymentStatus(
+  paymentId: string,
+): Promise<PaymentStatus> {
+  const adapter = getAdapter();
+  return adapter.getPaymentStatus(paymentId);
+}
+
+export async function processWebhook(
+  rawBody: Buffer,
+  signature: string,
+): Promise<WebhookResult & { duplicate: boolean }> {
+  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/ts/src/modules/payments/payments.types.ts

@@ -0,0 +1,56 @@
+export interface CreatePaymentParams {
+  amount: number;
+  currency: string;
+  metadata?: Record<string, string>;
+}
+
+export interface CreatePaymentResult {
+  id: string;
+  clientSecret?: string;
+  checkoutUrl?: string;
+  status: "pending" | "requires_payment_method" | "created";
+  amount: number;
+  currency: string;
+  metadata: Record<string, unknown>;
+}
+
+export interface RefundParams {
+  paymentId: string;
+  amount?: number;
+}
+
+export interface RefundResult {
+  id: string;
+  status: "succeeded" | "pending" | "failed";
+  amount: number;
+}
+
+export interface PaymentStatus {
+  id: string;
+  status: "pending" | "paid" | "failed" | "refunded";
+  amount: number;
+  currency: string;
+  metadata: Record<string, unknown>;
+}
+
+export interface WebhookResult {
+  event: string;
+  data: Record<string, unknown>;
+}
+
+export interface PaymentAdapter {
+  createPayment(params: CreatePaymentParams): Promise<CreatePaymentResult>;
+  refundPayment(params: RefundParams): Promise<RefundResult>;
+  getPaymentStatus(paymentId: string): Promise<PaymentStatus>;
+  verifyWebhook(rawBody: Buffer, signature: string): Promise<WebhookResult>;
+}
+
+export interface SetupPaymentsOptions {
+  provider: "stripe" | "lemonsqueezy";
+  stripeSecretKey?: string;
+  stripeWebhookSecret?: string;
+  lemonSqueezyApiKey?: string;
+  lemonSqueezyWebhookSecret?: string;
+  lemonSqueezyStoreId?: string;
+  mountPath?: string;
+}

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

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

package/template/ts/src/routes/index.ts

@@ -1,4 +1,6 @@
 import { Router } from "express";
+import { dirname } from "path";
+import { fileURLToPath } from "url";
 import {
   getHealth,
   createItem,
@@ -7,6 +9,9 @@ import {
 import { validateRequest } from "../middlewares/validateRequest.ts";
 import protectedRoutes from "./protected.ts";
 import authRoutes from "../modules/auth/auth.routes.ts";
+import paymentsRoutes from "../modules/payments/payments.routes.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
 const router = Router();
 
 // Health check
@@ -18,6 +23,9 @@ router.post("/items", validateRequest(createItemSchema), createItem);
 // 🔐 Auth routes
 router.use("/auth", authRoutes);
 
+// 💳 Payment routes
+router.use("/payments", paymentsRoutes);
+
 // 🔐 Protected routes (REQUIRED BEARER TOKEN FOR THEM)
 router.use("/protected", protectedRoutes);