create-charcole 2.2.2 → 2.3.0

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 };
+}