alepha 0.19.0 → 0.19.2

package/src/billing/providers/BillingProvider.ts

@@ -0,0 +1,79 @@
+import type { PaymentIntentEntity } from "../entities/paymentIntents.ts";
+
+export interface CreateSessionResult {
+  url: string;
+  providerRef: string;
+}
+
+export interface RefundResult {
+  providerRef: string;
+}
+
+export interface WebhookEvent {
+  providerRef: string;
+  status: string;
+  raw: unknown;
+}
+
+export interface CreatePaymentMethodResult {
+  providerRef: string;
+  type: string;
+  brand?: string;
+  last4?: string;
+  expMonth?: number;
+  expYear?: number;
+}
+
+export abstract class BillingProvider {
+  /**
+   * Create a checkout session with the PSP.
+   * Returns a URL to redirect the user to, and the PSP's reference ID.
+   */
+  abstract createSession(
+    intent: PaymentIntentEntity,
+    options: { returnUrl: string; authorize?: boolean },
+  ): Promise<CreateSessionResult>;
+
+  /**
+   * Capture a previously authorized payment.
+   * Amount can differ from the original authorization (partial capture).
+   */
+  abstract capturePayment(providerRef: string, amount: number): Promise<void>;
+
+  /**
+   * Void/cancel a previously authorized payment before capture.
+   */
+  abstract voidPayment(providerRef: string): Promise<void>;
+
+  /**
+   * Refund a captured payment (partial or full).
+   */
+  abstract refundPayment(
+    providerRef: string,
+    amount: number,
+  ): Promise<RefundResult>;
+
+  /**
+   * Parse an incoming PSP webhook request into a normalized event.
+   */
+  abstract parseWebhook(request: Request): Promise<WebhookEvent>;
+
+  /**
+   * Store a payment method token with the PSP.
+   */
+  abstract createPaymentMethod(
+    userId: string,
+    token: string,
+  ): Promise<CreatePaymentMethodResult>;
+
+  /**
+   * Delete a stored payment method from the PSP.
+   */
+  abstract deletePaymentMethod(providerRef: string): Promise<void>;
+
+  /**
+   * Expire/cancel a checkout session on the PSP side.
+   * Called during stale session cleanup.
+   */
+  abstract expireSession(providerRef: string): Promise<void>;
+}

package/src/billing/providers/MemoryBillingProvider.ts

@@ -0,0 +1,139 @@
+import { randomUUID } from "node:crypto";
+import type { PaymentIntentEntity } from "../entities/paymentIntents.ts";
+import type {
+  BillingProvider,
+  CreatePaymentMethodResult,
+  CreateSessionResult,
+  RefundResult,
+  WebhookEvent,
+} from "./BillingProvider.ts";
+
+interface MemoryCharge {
+  providerRef: string;
+  amount: number;
+  status: string;
+}
+
+interface MemoryRefund {
+  providerRef: string;
+  chargeRef: string;
+  amount: number;
+}
+
+export class MemoryBillingProvider implements BillingProvider {
+  protected readonly charges: Map<string, MemoryCharge> = new Map();
+  protected readonly refundRecords: Map<string, MemoryRefund> = new Map();
+  protected readonly methods: Map<string, CreatePaymentMethodResult> =
+    new Map();
+  protected readonly expiredSessions: Set<string> = new Set();
+
+  public async createSession(
+    intent: PaymentIntentEntity,
+    options: { returnUrl: string; authorize?: boolean },
+  ): Promise<CreateSessionResult> {
+    const providerRef = `mem_session_${randomUUID()}`;
+    const status = options.authorize ? "authorized" : "captured";
+    this.charges.set(providerRef, {
+      providerRef,
+      amount: intent.amount,
+      status,
+    });
+    return {
+      url: `/billing/mock-checkout/${intent.id}`,
+      providerRef,
+    };
+  }
+
+  public async capturePayment(
+    providerRef: string,
+    amount: number,
+  ): Promise<void> {
+    const charge = this.charges.get(providerRef);
+    if (charge) {
+      charge.status = "captured";
+      charge.amount = amount;
+    }
+  }
+
+  public async voidPayment(providerRef: string): Promise<void> {
+    const charge = this.charges.get(providerRef);
+    if (charge) {
+      charge.status = "voided";
+    }
+  }
+
+  public async refundPayment(
+    providerRef: string,
+    amount: number,
+  ): Promise<RefundResult> {
+    const refundRef = `mem_refund_${randomUUID()}`;
+    this.refundRecords.set(refundRef, {
+      providerRef: refundRef,
+      chargeRef: providerRef,
+      amount,
+    });
+    return { providerRef: refundRef };
+  }
+
+  public async parseWebhook(request: Request): Promise<WebhookEvent> {
+    const body = (await request.json()) as {
+      providerRef: string;
+      status: string;
+    };
+    return {
+      providerRef: body.providerRef,
+      status: body.status,
+      raw: body,
+    };
+  }
+
+  public async createPaymentMethod(
+    userId: string,
+    token: string,
+  ): Promise<CreatePaymentMethodResult> {
+    const providerRef = `mem_pm_${randomUUID()}`;
+    const result: CreatePaymentMethodResult = {
+      providerRef,
+      type: "card",
+      brand: "visa",
+      last4: "4242",
+      expMonth: 12,
+      expYear: 2030,
+    };
+    this.methods.set(providerRef, result);
+    return result;
+  }
+
+  public async deletePaymentMethod(providerRef: string): Promise<void> {
+    this.methods.delete(providerRef);
+  }
+
+  public async expireSession(providerRef: string): Promise<void> {
+    this.expiredSessions.add(providerRef);
+  }
+
+  // --- Test assertion helpers ---
+
+  public wasCharged(providerRef: string): boolean {
+    const charge = this.charges.get(providerRef);
+    return charge?.status === "captured";
+  }
+
+  public wasRefunded(providerRef: string): boolean {
+    return Array.from(this.refundRecords.values()).some(
+      (r) => r.chargeRef === providerRef,
+    );
+  }
+
+  public wasExpired(providerRef: string): boolean {
+    return this.expiredSessions.has(providerRef);
+  }
+
+  public getCharges(): MemoryCharge[] {
+    return Array.from(this.charges.values());
+  }
+
+  public getRefunds(): MemoryRefund[] {
+    return Array.from(this.refundRecords.values());
+  }
+}

package/src/billing/schemas/intentSchemas.ts

@@ -0,0 +1,60 @@
+import type { Static } from "alepha";
+import { t } from "alepha";
+import { pageQuerySchema } from "alepha/orm";
+import { paymentIntents } from "../entities/paymentIntents.ts";
+
+export const createIntentSchema = t.object({
+  amount: t.integer({ minimum: 1 }),
+  currency: t.text({ size: "short" }),
+  metadata: t.optional(t.json()),
+  paymentMethodId: t.optional(t.uuid()),
+});
+
+export type CreateIntent = Static<typeof createIntentSchema>;
+
+export const createCheckoutSchema = t.object({
+  intentId: t.uuid(),
+  returnUrl: t.text(),
+  authorize: t.optional(t.boolean()),
+});
+
+export type CreateCheckout = Static<typeof createCheckoutSchema>;
+
+export const checkoutResponseSchema = t.object({
+  url: t.text(),
+  intentId: t.text(),
+});
+
+export type CheckoutResponse = Static<typeof checkoutResponseSchema>;
+
+export const captureIntentSchema = t.object({
+  amount: t.optional(t.integer({ minimum: 1 })),
+});
+
+export type CaptureIntent = Static<typeof captureIntentSchema>;
+
+export const refundIntentSchema = t.object({
+  amount: t.integer({ minimum: 1 }),
+  reason: t.optional(t.text()),
+});
+
+export type RefundIntent = Static<typeof refundIntentSchema>;
+
+export const recordCashSchema = t.object({
+  amount: t.integer({ minimum: 1 }),
+  currency: t.text({ size: "short" }),
+  metadata: t.optional(t.json()),
+});
+
+export type RecordCash = Static<typeof recordCashSchema>;
+
+export const intentQuerySchema = t.extend(pageQuerySchema, {
+  status: t.optional(t.text({ description: "Filter by status" })),
+  userId: t.optional(t.uuid({ description: "Filter by user ID" })),
+});
+
+export type IntentQuery = Static<typeof intentQuerySchema>;
+
+export const intentResourceSchema = paymentIntents.schema;
+
+export type IntentResource = Static<typeof intentResourceSchema>;

package/src/billing/schemas/paymentMethodSchemas.ts

@@ -0,0 +1,13 @@
+import type { Static } from "alepha";
+import { t } from "alepha";
+import { paymentMethods } from "../entities/paymentMethods.ts";
+
+export const addPaymentMethodSchema = t.object({
+  token: t.text(),
+});
+
+export type AddPaymentMethod = Static<typeof addPaymentMethodSchema>;
+
+export const paymentMethodResourceSchema = paymentMethods.schema;
+
+export type PaymentMethodResource = Static<typeof paymentMethodResourceSchema>;

package/src/billing/schemas/refundSchemas.ts

@@ -0,0 +1,6 @@
+import type { Static } from "alepha";
+import { refunds } from "../entities/refunds.ts";
+
+export const refundResourceSchema = refunds.schema;
+
+export type RefundResource = Static<typeof refundResourceSchema>;

package/src/billing/services/BillingService.ts

@@ -0,0 +1,325 @@
+import { $inject, Alepha } from "alepha";
+import { $job } from "alepha/api/jobs";
+import { DateTimeProvider } from "alepha/datetime";
+import { $logger } from "alepha/logger";
+import { $repository } from "alepha/orm";
+import {
+  type PaymentIntentEntity,
+  paymentIntents,
+} from "../entities/paymentIntents.ts";
+import { type RefundEntity, refunds } from "../entities/refunds.ts";
+import { BillingError } from "../errors/BillingError.ts";
+import { BillingProvider } from "../providers/BillingProvider.ts";
+
+export class BillingService {
+  protected readonly alepha = $inject(Alepha);
+  protected readonly log = $logger();
+  protected readonly dateTime = $inject(DateTimeProvider);
+  protected readonly provider = $inject(BillingProvider);
+  protected readonly intentRepo = $repository(paymentIntents);
+  protected readonly refundRepo = $repository(refunds);
+
+  /**
+   * Expires stale payment intents that have been in "processing" status
+   * for more than 30 minutes. Runs every 15 minutes.
+   */
+  protected readonly expireStaleIntents = $job({
+    cron: "*/15 * * * *",
+    handler: async () => {
+      const cutoff = this.dateTime.now().subtract(30, "minutes").toISOString();
+
+      const stale = await this.intentRepo.findMany({
+        where: { status: { eq: "processing" }, createdAt: { lt: cutoff } },
+      });
+
+      for (const intent of stale) {
+        if (intent.providerRef) {
+          try {
+            await this.provider.expireSession(intent.providerRef);
+          } catch (error) {
+            this.log.warn(
+              `Failed to expire session for intent ${intent.id}`,
+              error,
+            );
+          }
+        }
+        await this.intentRepo.updateById(intent.id, { status: "expired" });
+        this.log.info(`Expired stale intent ${intent.id}`);
+      }
+    },
+  });
+
+  /**
+   * Create a new payment intent in "created" status.
+   */
+  public async createIntent(
+    amount: number,
+    currency: string,
+    metadata?: unknown,
+    options?: { paymentMethodId?: string; userId?: string },
+  ): Promise<PaymentIntentEntity> {
+    return await this.intentRepo.create({
+      amount,
+      currency,
+      status: "created",
+      metadata: metadata as any,
+      paymentMethodId: options?.paymentMethodId,
+      userId: options?.userId,
+    });
+  }
+
+  /**
+   * Create a checkout session with the payment provider and
+   * transition the intent to "processing".
+   */
+  public async createSession(
+    intentId: string,
+    returnUrl: string,
+    authorize?: boolean,
+  ): Promise<{ url: string; intentId: string }> {
+    const intent = await this.getIntent(intentId);
+    this.assertStatus(intent, "created", "createSession");
+
+    const result = await this.provider.createSession(intent, {
+      returnUrl,
+      authorize,
+    });
+
+    await this.intentRepo.updateById(intent.id, {
+      status: "processing",
+      providerRef: result.providerRef,
+    });
+
+    return { url: result.url, intentId: intent.id };
+  }
+
+  /**
+   * Handle an incoming webhook from the payment provider.
+   */
+  public async handleWebhook(request: Request): Promise<void> {
+    const event = await this.provider.parseWebhook(request);
+    const intents = await this.intentRepo.findMany({
+      where: { providerRef: { eq: event.providerRef } },
+      limit: 1,
+    });
+
+    if (intents.length === 0) {
+      this.log.warn(`Webhook for unknown providerRef: ${event.providerRef}`);
+      return;
+    }
+
+    const intent = intents[0];
+    await this.handleWebhookEvent(intent.id, event.status, event.raw);
+  }
+
+  /**
+   * Process a webhook event by updating the intent status and emitting
+   * the corresponding billing event.
+   */
+  public async handleWebhookEvent(
+    intentId: string,
+    status: string,
+    raw?: unknown,
+  ): Promise<void> {
+    const intent = await this.getIntent(intentId);
+
+    const eventMap = {
+      authorized: "billing:authorized",
+      captured: "billing:captured",
+      failed: "billing:failed",
+    } as const;
+
+    type WebhookStatus = keyof typeof eventMap;
+    if (!(status in eventMap)) {
+      this.log.warn(`Unknown webhook status: ${status}`);
+      return;
+    }
+
+    const webhookStatus = status as WebhookStatus;
+
+    await this.intentRepo.updateById(intent.id, {
+      status: webhookStatus,
+      providerRaw: raw as any,
+    });
+
+    await this.alepha.events.emit(eventMap[webhookStatus], {
+      intentId: intent.id,
+      amount: intent.amount,
+      currency: intent.currency,
+      metadata: intent.metadata,
+    });
+  }
+
+  /**
+   * Capture a previously authorized payment. Optionally specify a different
+   * amount for partial capture.
+   */
+  public async capture(
+    intentId: string,
+    finalAmount?: number,
+  ): Promise<PaymentIntentEntity> {
+    const intent = await this.getIntent(intentId);
+    this.assertStatus(intent, "authorized", "capture");
+
+    const amount = finalAmount ?? intent.amount;
+    if (intent.providerRef) {
+      await this.provider.capturePayment(intent.providerRef, amount);
+    }
+
+    const updated = await this.intentRepo.updateById(intent.id, {
+      status: "captured",
+      amount,
+    });
+
+    await this.alepha.events.emit("billing:captured", {
+      intentId: intent.id,
+      amount,
+      currency: intent.currency,
+      metadata: intent.metadata,
+    });
+
+    return updated;
+  }
+
+  /**
+   * Void a previously authorized payment before capture.
+   */
+  public async void(intentId: string): Promise<PaymentIntentEntity> {
+    const intent = await this.getIntent(intentId);
+    this.assertStatus(intent, "authorized", "void");
+
+    if (intent.providerRef) {
+      await this.provider.voidPayment(intent.providerRef);
+    }
+
+    const updated = await this.intentRepo.updateById(intent.id, {
+      status: "voided",
+    });
+
+    await this.alepha.events.emit("billing:voided", {
+      intentId: intent.id,
+      amount: intent.amount,
+      currency: intent.currency,
+      metadata: intent.metadata,
+    });
+
+    return updated;
+  }
+
+  /**
+   * Refund a captured payment (partial or full).
+   */
+  public async refund(
+    intentId: string,
+    amount: number,
+    reason?: string,
+  ): Promise<RefundEntity> {
+    const intent = await this.getIntent(intentId);
+    this.assertStatus(intent, "captured", "refund");
+
+    let refundProviderRef: string | undefined;
+    if (intent.providerRef) {
+      const result = await this.provider.refundPayment(
+        intent.providerRef,
+        amount,
+      );
+      refundProviderRef = result.providerRef;
+    }
+
+    const refund = await this.refundRepo.create({
+      intentId: intent.id,
+      organizationId: intent.organizationId,
+      amount,
+      currency: intent.currency,
+      status: "completed",
+      reason,
+      providerRef: refundProviderRef,
+    });
+
+    await this.intentRepo.updateById(intent.id, { status: "refunded" });
+
+    await this.alepha.events.emit("billing:refunded", {
+      intentId: intent.id,
+      refundId: refund.id,
+      amount,
+      currency: intent.currency,
+      metadata: intent.metadata,
+    });
+
+    return refund;
+  }
+
+  /**
+   * Record a cash or offline payment directly as captured,
+   * bypassing the checkout flow.
+   */
+  public async recordCashPayment(
+    amount: number,
+    currency: string,
+    metadata?: unknown,
+  ): Promise<PaymentIntentEntity> {
+    const intent = await this.intentRepo.create({
+      amount,
+      currency,
+      status: "captured",
+      metadata: metadata as any,
+    });
+
+    await this.alepha.events.emit("billing:captured", {
+      intentId: intent.id,
+      amount,
+      currency,
+      metadata,
+    });
+
+    return intent;
+  }
+
+  /**
+   * Cancel a payment intent that has not yet entered processing.
+   */
+  public async cancel(intentId: string): Promise<PaymentIntentEntity> {
+    const intent = await this.getIntent(intentId);
+    this.assertStatus(intent, "created", "cancel");
+
+    return await this.intentRepo.updateById(intent.id, {
+      status: "cancelled",
+    });
+  }
+
+  /**
+   * Get a payment intent by ID. Throws NotFoundError if not found.
+   */
+  public async getIntent(intentId: string): Promise<PaymentIntentEntity> {
+    return await this.intentRepo.getById(intentId);
+  }
+
+  /**
+   * Find payment intents with optional filters and pagination.
+   */
+  public async findIntents(query: {
+    status?: string;
+    userId?: string;
+    sort?: string;
+    size?: number;
+    page?: number;
+  }) {
+    const where = this.intentRepo.createQueryWhere();
+    if (query.status)
+      where.status = { eq: query.status as PaymentIntentEntity["status"] };
+    if (query.userId) where.userId = { eq: query.userId };
+    return await this.intentRepo.paginate(query, { where }, { count: true });
+  }
+
+  protected assertStatus(
+    intent: PaymentIntentEntity,
+    expected: PaymentIntentEntity["status"],
+    operation: string,
+  ): void {
+    if (intent.status !== expected) {
+      throw new BillingError(
+        `Cannot ${operation}: intent ${intent.id} is '${intent.status}', expected '${expected}'`,
+      );
+    }
+  }
+}

package/src/billing/services/PaymentMethodService.ts

@@ -0,0 +1,82 @@
+import { $inject } from "alepha";
+import { $logger } from "alepha/logger";
+import { $repository } from "alepha/orm";
+import {
+  type PaymentMethodEntity,
+  paymentMethods,
+} from "../entities/paymentMethods.ts";
+import { BillingError } from "../errors/BillingError.ts";
+import { BillingProvider } from "../providers/BillingProvider.ts";
+
+export class PaymentMethodService {
+  protected readonly log = $logger();
+  protected readonly provider = $inject(BillingProvider);
+  protected readonly methodRepo = $repository(paymentMethods);
+
+  public async addPaymentMethod(
+    userId: string,
+    organizationId: string,
+    token: string,
+  ): Promise<PaymentMethodEntity> {
+    const result = await this.provider.createPaymentMethod(userId, token);
+
+    const existing = await this.methodRepo.findMany({
+      where: { userId: { eq: userId } },
+    });
+
+    return await this.methodRepo.create({
+      userId,
+      organizationId,
+      type: result.type,
+      brand: result.brand,
+      last4: result.last4,
+      expMonth: result.expMonth,
+      expYear: result.expYear,
+      isDefault: existing.length === 0,
+      providerRef: result.providerRef,
+    });
+  }
+
+  public async listPaymentMethods(
+    userId: string,
+  ): Promise<PaymentMethodEntity[]> {
+    return await this.methodRepo.findMany({
+      where: { userId: { eq: userId } },
+    });
+  }
+
+  public async removePaymentMethod(
+    methodId: string,
+    userId: string,
+  ): Promise<void> {
+    const method = await this.methodRepo.getById(methodId);
+    if (method.userId !== userId) {
+      throw new BillingError("Cannot remove another user's payment method");
+    }
+
+    await this.provider.deletePaymentMethod(method.providerRef);
+    await this.methodRepo.deleteById(method.id);
+  }
+
+  public async setDefault(
+    methodId: string,
+    userId: string,
+  ): Promise<PaymentMethodEntity> {
+    const method = await this.methodRepo.getById(methodId);
+    if (method.userId !== userId) {
+      throw new BillingError("Cannot modify another user's payment method");
+    }
+
+    const userMethods = await this.methodRepo.findMany({
+      where: { userId: { eq: userId } },
+    });
+
+    for (const m of userMethods) {
+      if (m.isDefault) {
+        await this.methodRepo.updateById(m.id, { isDefault: false });
+      }
+    }
+
+    return await this.methodRepo.updateById(method.id, { isDefault: true });
+  }
+}