create-charcole 2.2.1 → 2.3.0

package/packages/payments/src/adapters/LemonSqueezyAdapter.js

@@ -0,0 +1,150 @@
+import {
+  lemonSqueezySetup,
+  createCheckout,
+  getOrder,
+} from "@lemonsqueezy/lemonsqueezy.js";
+import { createHmac } from "crypto";
+import { PaymentAdapter } from "./PaymentAdapter.js";
+import { PaymentError } from "../errors/PaymentError.js";
+
+export class LemonSqueezyAdapter extends PaymentAdapter {
+  #apiKey;
+  #webhookSecret;
+  #storeId;
+
+  constructor({ apiKey, webhookSecret, storeId }) {
+    super();
+    if (!apiKey) {
+      throw new PaymentError(
+        "LemonSqueezy API key is required",
+        "CONFIG_ERROR",
+      );
+    }
+    if (!webhookSecret) {
+      throw new PaymentError(
+        "LemonSqueezy webhook secret is required",
+        "CONFIG_ERROR",
+      );
+    }
+    if (!storeId) {
+      throw new PaymentError(
+        "LemonSqueezy store ID is required",
+        "CONFIG_ERROR",
+      );
+    }
+    this.#apiKey = apiKey;
+    this.#webhookSecret = webhookSecret;
+    this.#storeId = storeId;
+    lemonSqueezySetup({ apiKey });
+  }
+
+  async createPayment({ amount, currency, metadata = {} }) {
+    if (!metadata.variantId) {
+      throw new PaymentError(
+        "variantId is required in metadata for LemonSqueezy",
+        "MISSING_VARIANT_ID",
+      );
+    }
+    try {
+      const checkout = await createCheckout(this.#storeId, metadata.variantId, {
+        checkoutOptions: {
+          embed: false,
+          media: false,
+          logo: false,
+        },
+        checkoutData: {
+          custom: metadata,
+        },
+      });
+      if (checkout.error) {
+        throw new PaymentError(
+          `LemonSqueezy checkout failed: ${checkout.error.message}`,
+          "LS_CHECKOUT_FAILED",
+        );
+      }
+      return {
+        id: String(checkout.data.data.id),
+        checkoutUrl: checkout.data.data.attributes.url,
+        status: "created",
+        amount,
+        currency,
+        metadata: checkout.data,
+      };
+    } catch (error) {
+      if (error instanceof PaymentError) throw error;
+      throw new PaymentError(
+        `LemonSqueezy createPayment failed: ${error.message}`,
+        "LS_CHECKOUT_FAILED",
+      );
+    }
+  }
+
+  async refundPayment({ paymentId, amount }) {
+    try {
+      // LemonSqueezy SDK v4 requires manual refund creation via API
+      // This is a placeholder implementation - full refund support requires
+      // direct API calls with authentication
+      throw new PaymentError(
+        "LemonSqueezy refunds require manual implementation with API client",
+        "LS_REFUND_NOT_SUPPORTED",
+      );
+    } catch (error) {
+      if (error instanceof PaymentError) throw error;
+      throw new PaymentError(
+        `LemonSqueezy refundPayment failed: ${error.message}`,
+        "LS_REFUND_FAILED",
+      );
+    }
+  }
+
+  async getPaymentStatus(paymentId) {
+    try {
+      const order = await getOrder(paymentId);
+      if (order.error) {
+        throw new PaymentError(
+          `LemonSqueezy order not found: ${order.error.message}`,
+          "LS_ORDER_NOT_FOUND",
+        );
+      }
+      const statusMap = {
+        paid: "paid",
+        pending: "pending",
+        failed: "failed",
+        refunded: "refunded",
+      };
+      const normalizedStatus =
+        statusMap[order.data.data.attributes.status] || "pending";
+      return {
+        id: String(order.data.data.id),
+        status: normalizedStatus,
+        amount: order.data.data.attributes.total,
+        currency: order.data.data.attributes.currency,
+        metadata: order.data,
+      };
+    } catch (error) {
+      if (error instanceof PaymentError) throw error;
+      throw new PaymentError(
+        `LemonSqueezy getPaymentStatus failed: ${error.message}`,
+        "LS_ORDER_NOT_FOUND",
+      );
+    }
+  }
+
+  async verifyWebhook(rawBody, signature) {
+    const expectedSignature = createHmac("sha256", this.#webhookSecret)
+      .update(rawBody)
+      .digest("hex");
+    if (signature !== expectedSignature) {
+      throw new PaymentError(
+        "Invalid webhook signature",
+        "WEBHOOK_INVALID",
+        401,
+      );
+    }
+    const payload = JSON.parse(rawBody.toString());
+    return {
+      event: payload.meta.event_name,
+      data: payload.data,
+    };
+  }
+}

package/packages/payments/src/adapters/PaymentAdapter.js

@@ -0,0 +1,109 @@
+/**
+ * @typedef {Object} CreatePaymentResult
+ * @property {string} id - Provider-specific payment/checkout ID
+ * @property {string} [clientSecret] - Stripe: client_secret for frontend
+ * @property {string} [checkoutUrl] - LemonSqueezy: redirect URL
+ * @property {string} status - 'pending' | 'requires_payment_method' | 'created'
+ * @property {number} amount - Amount in smallest currency unit (cents)
+ * @property {string} currency - ISO 4217 (e.g. 'usd', 'pkr')
+ * @property {Object} metadata - Provider-specific raw response
+ */
+
+/**
+ * @typedef {Object} RefundResult
+ * @property {string} id - Refund ID
+ * @property {string} status - 'succeeded' | 'pending' | 'failed'
+ * @property {number} amount - Refunded amount in smallest unit
+ */
+
+/**
+ * @typedef {Object} PaymentStatus
+ * @property {string} id
+ * @property {string} status - 'pending' | 'paid' | 'failed' | 'refunded'
+ * @property {number} amount
+ * @property {string} currency
+ * @property {Object} metadata
+ */
+
+/**
+ * @typedef {Object} WebhookResult
+ * @property {string} event
+ * @property {Object} data
+ */
+
+/**
+ * Abstract PaymentAdapter interface.
+ * All adapters must implement these methods.
+ */
+export class PaymentAdapter {
+  /**
+   * Create a payment intent (Stripe) or checkout session (LemonSqueezy).
+   * @param {Object} params
+   * @param {number} params.amount - Amount in smallest currency unit
+   * @param {string} params.currency - ISO 4217 currency code
+   * @param {Object} [params.metadata] - Additional metadata
+   * @returns {Promise<CreatePaymentResult>}
+   */
+  async createPayment(params) {
+    throw new Error("createPayment() must be implemented");
+  }
+
+  /**
+   * Refund a payment.
+   * @param {Object} params
+   * @param {string} params.paymentId - Payment ID to refund
+   * @param {number} [params.amount] - Amount to refund (omit for full refund)
+   * @returns {Promise<RefundResult>}
+   */
+  async refundPayment(params) {
+    throw new Error("refundPayment() must be implemented");
+  }
+
+  /**
+   * Get current payment status.
+   * @param {string} paymentId
+   * @returns {Promise<PaymentStatus>}
+   */
+  async getPaymentStatus(paymentId) {
+    throw new Error("getPaymentStatus() must be implemented");
+  }
+
+  /**
+   * Verify and parse a webhook payload.
+   * @param {Buffer} rawBody - Raw webhook body as Buffer
+   * @param {string} signature - Webhook signature from header
+   * @returns {Promise<WebhookResult>}
+   */
+  async verifyWebhook(rawBody, signature) {
+    throw new Error("verifyWebhook() must be implemented");
+  }
+}
+
+/**
+ * Factory function to create an adapter instance.
+ * @param {Object} options
+ * @param {'stripe' | 'lemonsqueezy'} options.provider
+ * @param {string} [options.stripeSecretKey]
+ * @param {string} [options.stripeWebhookSecret]
+ * @param {string} [options.lemonSqueezyApiKey]
+ * @param {string} [options.lemonSqueezyWebhookSecret]
+ * @param {string} [options.lemonSqueezyStoreId]
+ * @returns {PaymentAdapter}
+ */
+export function createAdapter(options) {
+  const { provider } = options;
+  if (provider === "stripe") {
+    return new StripeAdapter({
+      secretKey: options.stripeSecretKey,
+      webhookSecret: options.stripeWebhookSecret,
+    });
+  } else if (provider === "lemonsqueezy") {
+    return new LemonSqueezyAdapter({
+      apiKey: options.lemonSqueezyApiKey,
+      webhookSecret: options.lemonSqueezyWebhookSecret,
+      storeId: options.lemonSqueezyStoreId,
+    });
+  } else {
+    throw new PaymentError("Unknown provider", "CONFIG_ERROR");
+  }
+}

package/packages/payments/src/adapters/StripeAdapter.js

@@ -0,0 +1,114 @@
+import Stripe from "stripe";
+import { PaymentAdapter } from "./PaymentAdapter.js";
+import { PaymentError } from "../errors/PaymentError.js";
+
+export class StripeAdapter extends PaymentAdapter {
+  #stripe;
+  #webhookSecret;
+
+  constructor({ secretKey, webhookSecret }) {
+    super();
+    if (!secretKey) {
+      throw new PaymentError("Stripe secret key is required", "CONFIG_ERROR");
+    }
+    if (!webhookSecret) {
+      throw new PaymentError(
+        "Stripe webhook secret is required",
+        "CONFIG_ERROR",
+      );
+    }
+    this.#stripe = new Stripe(secretKey, { apiVersion: "2024-06-20" });
+    this.#webhookSecret = webhookSecret;
+  }
+
+  async createPayment({ amount, currency, metadata = {} }) {
+    try {
+      const intent = await this.#stripe.paymentIntents.create({
+        amount,
+        currency,
+        metadata,
+        automatic_payment_methods: { enabled: true },
+      });
+      return {
+        id: intent.id,
+        clientSecret: intent.client_secret,
+        status: intent.status,
+        amount: intent.amount,
+        currency: intent.currency,
+        metadata: intent,
+      };
+    } catch (error) {
+      throw new PaymentError(
+        `Stripe createPayment failed: ${error.message}`,
+        "STRIPE_ERROR",
+      );
+    }
+  }
+
+  async refundPayment({ paymentId, amount }) {
+    try {
+      const params = { payment_intent: paymentId };
+      if (amount) {
+        params.amount = amount;
+      }
+      const refund = await this.#stripe.refunds.create(params);
+      return {
+        id: refund.id,
+        status: refund.status,
+        amount: refund.amount,
+      };
+    } catch (error) {
+      throw new PaymentError(
+        `Stripe refundPayment failed: ${error.message}`,
+        "STRIPE_ERROR",
+      );
+    }
+  }
+
+  async getPaymentStatus(paymentId) {
+    try {
+      const intent = await this.#stripe.paymentIntents.retrieve(paymentId);
+      const statusMap = {
+        succeeded: "paid",
+        requires_payment_method: "pending",
+        requires_confirmation: "pending",
+        processing: "pending",
+        canceled: "failed",
+        requires_action: "pending",
+      };
+      const normalizedStatus = statusMap[intent.status] || "pending";
+      return {
+        id: intent.id,
+        status: normalizedStatus,
+        amount: intent.amount,
+        currency: intent.currency,
+        metadata: intent,
+      };
+    } catch (error) {
+      throw new PaymentError(
+        `Stripe getPaymentStatus failed: ${error.message}`,
+        "STRIPE_ERROR",
+      );
+    }
+  }
+
+  async verifyWebhook(rawBody, signature) {
+    try {
+      const event = this.#stripe.webhooks.constructEvent(
+        rawBody,
+        signature,
+        this.#webhookSecret,
+      );
+      return {
+        event: event.type,
+        data: event.data.object,
+      };
+    } catch (error) {
+      throw new PaymentError(
+        "Invalid webhook signature",
+        "WEBHOOK_INVALID",
+        401,
+      );
+    }
+  }
+}

package/packages/payments/src/controllers/payments.controller.js

@@ -0,0 +1,48 @@
+import * as paymentsService from "../services/payments.service.js";
+import {
+  createPaymentSchema,
+  refundPaymentSchema,
+} from "../schemas/payments.schemas.js";
+import { extractSignature } from "../helpers/webhookUtils.js";
+import { PaymentError } from "../errors/PaymentError.js";
+
+export const createPayment = async (req, res, next) => {
+  try {
+    const validated = createPaymentSchema.parse(req.body);
+    const result = await paymentsService.createPayment(validated);
+    res.status(201).json({ success: true, data: result });
+  } catch (err) {
+    next(err);
+  }
+};
+
+export const refundPayment = async (req, res, next) => {
+  try {
+    const validated = refundPaymentSchema.parse(req.body);
+    const result = await paymentsService.refundPayment(validated);
+    res.json({ success: true, data: result });
+  } catch (err) {
+    next(err);
+  }
+};
+
+export const getPaymentStatus = async (req, res, next) => {
+  try {
+    const result = await paymentsService.getPaymentStatus(req.params.paymentId);
+    res.json({ success: true, data: result });
+  } catch (err) {
+    next(err);
+  }
+};
+
+export const handleWebhook = async (req, res, next) => {
+  try {
+    const provider = process.env.PAYMENT_PROVIDER;
+    const signature = extractSignature(req, provider);
+    const result = await paymentsService.processWebhook(req.body, signature);
+    console.log(`Webhook received: ${result.event}`);
+    res.status(200).json({ received: true });
+  } catch (err) {
+    next(err);
+  }
+};

package/packages/payments/src/errors/PaymentError.js

@@ -0,0 +1,8 @@
+export class PaymentError extends Error {
+  constructor(message, code = "PAYMENT_ERROR", statusCode = 400) {
+    super(message);
+    this.name = "PaymentError";
+    this.code = code;
+    this.statusCode = statusCode;
+  }
+}

package/packages/payments/src/helpers/webhookUtils.js

@@ -0,0 +1,27 @@
+import { PaymentError } from "../errors/PaymentError.js";
+
+export function getWebhookSignatureHeader(provider) {
+  if (provider === "stripe") {
+    return "stripe-signature";
+  } else if (provider === "lemonsqueezy") {
+    return "x-signature";
+  } else {
+    throw new PaymentError(
+      "Unknown provider for webhook header",
+      "CONFIG_ERROR",
+    );
+  }
+}
+
+export function extractSignature(req, provider) {
+  const headerName = getWebhookSignatureHeader(provider);
+  const signature = req.headers[headerName];
+  if (!signature) {
+    throw new PaymentError(
+      "Webhook signature header missing",
+      "WEBHOOK_INVALID",
+      401,
+    );
+  }
+  return signature;
+}

package/packages/payments/src/index.d.ts

@@ -0,0 +1,87 @@
+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;
+}
+
+export declare function setupPayments(
+  app: any,
+  options?: SetupPaymentsOptions,
+): void;
+export declare function createAdapter(
+  options: SetupPaymentsOptions,
+): PaymentAdapter;
+export declare class StripeAdapter implements PaymentAdapter {
+  constructor(options: { secretKey: string; webhookSecret: string });
+  createPayment(params: CreatePaymentParams): Promise<CreatePaymentResult>;
+  refundPayment(params: RefundParams): Promise<RefundResult>;
+  getPaymentStatus(paymentId: string): Promise<PaymentStatus>;
+  verifyWebhook(rawBody: Buffer, signature: string): Promise<WebhookResult>;
+}
+export declare class LemonSqueezyAdapter implements PaymentAdapter {
+  constructor(options: {
+    apiKey: string;
+    webhookSecret: string;
+    storeId: string;
+  });
+  createPayment(params: CreatePaymentParams): Promise<CreatePaymentResult>;
+  refundPayment(params: RefundParams): Promise<RefundResult>;
+  getPaymentStatus(paymentId: string): Promise<PaymentStatus>;
+  verifyWebhook(rawBody: Buffer, signature: string): Promise<WebhookResult>;
+}
+export declare class PaymentError extends Error {
+  code: string;
+  statusCode: number;
+}
+export declare function resetAdapter(): void;

package/packages/payments/src/index.js

@@ -0,0 +1,6 @@
+export { setupPayments } from "./routes/payments.routes.js";
+export { createAdapter } from "./adapters/PaymentAdapter.js";
+export { StripeAdapter } from "./adapters/StripeAdapter.js";
+export { LemonSqueezyAdapter } from "./adapters/LemonSqueezyAdapter.js";
+export { PaymentError } from "./errors/PaymentError.js";
+export { resetAdapter } from "./services/payments.service.js";

package/packages/payments/src/routes/payments.routes.js

@@ -0,0 +1,41 @@
+import { Router } from "express";
+import express from "express";
+import * as controller from "../controllers/payments.controller.js";
+
+const router = Router();
+
+router.post("/create-intent", controller.createPayment);
+router.post("/refund", controller.refundPayment);
+router.get("/status/:paymentId", controller.getPaymentStatus);
+router.post("/webhook", controller.handleWebhook);
+
+export default router;
+
+export function setupPayments(app, options = {}) {
+  const {
+    provider,
+    stripeSecretKey,
+    stripeWebhookSecret,
+    lemonSqueezyApiKey,
+    lemonSqueezyWebhookSecret,
+    lemonSqueezyStoreId,
+    mountPath = "/payments",
+  } = options;
+
+  // Set env vars if provided
+  if (provider) process.env.PAYMENT_PROVIDER = provider;
+  if (stripeSecretKey) process.env.STRIPE_SECRET_KEY = stripeSecretKey;
+  if (stripeWebhookSecret)
+    process.env.STRIPE_WEBHOOK_SECRET = stripeWebhookSecret;
+  if (lemonSqueezyApiKey) process.env.LEMONSQUEEZY_API_KEY = lemonSqueezyApiKey;
+  if (lemonSqueezyWebhookSecret)
+    process.env.LEMONSQUEEZY_WEBHOOK_SECRET = lemonSqueezyWebhookSecret;
+  if (lemonSqueezyStoreId)
+    process.env.LEMONSQUEEZY_STORE_ID = lemonSqueezyStoreId;
+
+  // Register raw body middleware for webhook BEFORE mounting router
+  app.use(`${mountPath}/webhook`, express.raw({ type: "application/json" }));
+
+  // Mount the router
+  app.use(mountPath, router);
+}

package/packages/payments/src/schemas/payments.schemas.js

@@ -0,0 +1,24 @@
+import { z } from "zod";
+
+export const createPaymentSchema = z.object({
+  amount: z
+    .number({ required_error: "amount is required" })
+    .int({ message: "amount must be an integer" })
+    .positive({ message: "amount must be positive" })
+    .max(99999999, "amount exceeds maximum allowed"),
+
+  currency: z
+    .string({ required_error: "currency is required" })
+    .length(3, "currency must be 3 characters")
+    .toLowerCase(),
+
+  metadata: z.record(z.string()).default({}),
+});
+
+export const refundPaymentSchema = z.object({
+  paymentId: z
+    .string({ required_error: "paymentId is required" })
+    .min(1, "paymentId cannot be empty"),
+
+  amount: z.number().int().positive().optional(),
+});

package/packages/payments/src/services/payments.service.js

@@ -0,0 +1,68 @@
+import { StripeAdapter } from "../adapters/StripeAdapter.js";
+import { LemonSqueezyAdapter } from "../adapters/LemonSqueezyAdapter.js";
+import { PaymentError } from "../errors/PaymentError.js";
+
+let adapter = null;
+const processedWebhookIds = new Set();
+
+export function getAdapter() {
+  if (adapter) return adapter;
+
+  const provider = process.env.PAYMENT_PROVIDER;
+  if (!provider) {
+    throw new PaymentError(
+      "PAYMENT_PROVIDER environment variable is required",
+      "PROVIDER_NOT_CONFIGURED",
+    );
+  }
+
+  if (provider === "stripe") {
+    adapter = new StripeAdapter({
+      secretKey: process.env.STRIPE_SECRET_KEY,
+      webhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
+    });
+  } else if (provider === "lemonsqueezy") {
+    adapter = new LemonSqueezyAdapter({
+      apiKey: process.env.LEMONSQUEEZY_API_KEY,
+      webhookSecret: process.env.LEMONSQUEEZY_WEBHOOK_SECRET,
+      storeId: process.env.LEMONSQUEEZY_STORE_ID,
+    });
+  } else {
+    throw new PaymentError(`Unknown provider: ${provider}`, "CONFIG_ERROR");
+  }
+
+  return adapter;
+}
+
+export function resetAdapter() {
+  adapter = null;
+}
+
+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 { event, data } = await adapter.verifyWebhook(rawBody, signature);
+
+  const eventId = data.id ?? `${event}-${Date.now()}`;
+
+  if (processedWebhookIds.has(eventId)) {
+    return { event, data, duplicate: true };
+  }
+
+  processedWebhookIds.add(eventId);
+  return { event, data, duplicate: false };
+}

package/packages/swagger/BACKWARD_COMPATIBILITY.md

@@ -37,7 +37,7 @@ Old setup without new options:
 ```typescript
 setupSwagger(app, {
   title: "My API",
-  version: "1.0.0",
+  version: "1.0.1",
 });
 ```