alepha 0.19.1 → 0.19.2

package/src/billing/controllers/BillingController.ts

@@ -0,0 +1,108 @@
+import { $inject, t } from "alepha";
+import { $secure } from "alepha/security";
+import { $action, okSchema } from "alepha/server";
+import {
+  checkoutResponseSchema,
+  createCheckoutSchema,
+} from "../schemas/intentSchemas.ts";
+import {
+  addPaymentMethodSchema,
+  paymentMethodResourceSchema,
+} from "../schemas/paymentMethodSchemas.ts";
+import { BillingService } from "../services/BillingService.ts";
+import { PaymentMethodService } from "../services/PaymentMethodService.ts";
+
+export class BillingController {
+  protected readonly url = "/billing";
+  protected readonly group = "billing";
+  protected readonly billing = $inject(BillingService);
+  protected readonly paymentMethods = $inject(PaymentMethodService);
+
+  /**
+   * List the current user's saved payment methods.
+   */
+  public readonly listPaymentMethods = $action({
+    path: `${this.url}/payment-methods`,
+    group: this.group,
+    use: [$secure()],
+    description: "List current user's saved payment methods",
+    schema: {
+      response: t.array(paymentMethodResourceSchema),
+    },
+    handler: ({ user }) => this.paymentMethods.listPaymentMethods(user.id),
+  });
+
+  /**
+   * Add a new payment method.
+   */
+  public readonly addPaymentMethod = $action({
+    method: "POST",
+    path: `${this.url}/payment-methods`,
+    group: this.group,
+    use: [$secure()],
+    description: "Tokenize and store a new payment method",
+    schema: {
+      body: addPaymentMethodSchema,
+      response: paymentMethodResourceSchema,
+    },
+    handler: ({ body, user }) =>
+      this.paymentMethods.addPaymentMethod(
+        user.id,
+        user.organization!,
+        body.token,
+      ),
+  });
+
+  /**
+   * Remove a payment method.
+   */
+  public readonly removePaymentMethod = $action({
+    method: "DELETE",
+    path: `${this.url}/payment-methods/:id`,
+    group: this.group,
+    use: [$secure()],
+    description: "Remove own payment method",
+    schema: {
+      params: t.object({ id: t.uuid() }),
+      response: okSchema,
+    },
+    handler: async ({ params, user }) => {
+      await this.paymentMethods.removePaymentMethod(params.id, user.id);
+      return { ok: true, id: params.id };
+    },
+  });
+
+  /**
+   * Set a payment method as default.
+   */
+  public readonly setDefaultPaymentMethod = $action({
+    method: "PATCH",
+    path: `${this.url}/payment-methods/:id/default`,
+    group: this.group,
+    use: [$secure()],
+    description: "Set as default payment method",
+    schema: {
+      params: t.object({ id: t.uuid() }),
+      response: paymentMethodResourceSchema,
+    },
+    handler: ({ params, user }) =>
+      this.paymentMethods.setDefault(params.id, user.id),
+  });
+
+  /**
+   * Create a checkout session.
+   */
+  public readonly createCheckout = $action({
+    method: "POST",
+    path: `${this.url}/checkout`,
+    group: this.group,
+    use: [$secure()],
+    description: "Create checkout session and return URL",
+    schema: {
+      body: createCheckoutSchema,
+      response: checkoutResponseSchema,
+    },
+    handler: ({ body }) =>
+      this.billing.createSession(body.intentId, body.returnUrl, body.authorize),
+  });
+}

package/src/billing/entities/paymentIntents.ts

@@ -0,0 +1,34 @@
+import { type Static, t } from "alepha";
+import { $entity, db } from "alepha/orm";
+
+export const paymentIntents = $entity({
+  name: "payment_intents",
+  schema: t.object({
+    id: db.primaryKey(t.uuid()),
+    version: db.version(),
+    createdAt: db.createdAt(),
+    updatedAt: db.updatedAt(),
+    organizationId: db.organization(),
+    amount: t.integer(),
+    currency: t.text({ size: "short" }),
+    status: t.enum([
+      "created",
+      "processing",
+      "authorized",
+      "captured",
+      "voided",
+      "failed",
+      "cancelled",
+      "refunded",
+      "expired",
+    ]),
+    providerRef: t.optional(t.text()),
+    providerRaw: t.optional(t.json()),
+    metadata: t.optional(t.json()),
+    paymentMethodId: t.optional(t.uuid()),
+    userId: t.optional(t.uuid()),
+  }),
+  indexes: ["status", "organizationId", "userId", "createdAt"],
+});
+
+export type PaymentIntentEntity = Static<typeof paymentIntents.schema>;

package/src/billing/entities/paymentMethods.ts

@@ -0,0 +1,24 @@
+import { type Static, t } from "alepha";
+import { $entity, db } from "alepha/orm";
+
+export const paymentMethods = $entity({
+  name: "payment_methods",
+  schema: t.object({
+    id: db.primaryKey(t.uuid()),
+    version: db.version(),
+    createdAt: db.createdAt(),
+    updatedAt: db.updatedAt(),
+    organizationId: db.organization(),
+    userId: t.uuid(),
+    type: t.text({ size: "short" }),
+    brand: t.optional(t.text({ size: "short" })),
+    last4: t.optional(t.text({ size: "short" })),
+    expMonth: t.optional(t.integer()),
+    expYear: t.optional(t.integer()),
+    isDefault: t.boolean(),
+    providerRef: t.text(),
+  }),
+  indexes: ["userId", "organizationId"],
+});
+
+export type PaymentMethodEntity = Static<typeof paymentMethods.schema>;

package/src/billing/entities/refunds.ts

@@ -0,0 +1,22 @@
+import { type Static, t } from "alepha";
+import { $entity, db } from "alepha/orm";
+
+export const refunds = $entity({
+  name: "refunds",
+  schema: t.object({
+    id: db.primaryKey(t.uuid()),
+    version: db.version(),
+    createdAt: db.createdAt(),
+    updatedAt: db.updatedAt(),
+    organizationId: db.organization(),
+    intentId: t.uuid(),
+    amount: t.integer(),
+    currency: t.text({ size: "short" }),
+    status: t.enum(["pending", "processing", "completed", "failed"]),
+    reason: t.optional(t.text()),
+    providerRef: t.optional(t.text()),
+  }),
+  indexes: ["intentId", "organizationId", "status"],
+});
+
+export type RefundEntity = Static<typeof refunds.schema>;

package/src/billing/errors/BillingError.ts

@@ -0,0 +1,5 @@
+import { AlephaError } from "alepha";
+
+export class BillingError extends AlephaError {
+  public readonly status = 400;
+}

package/src/billing/index.ts

@@ -0,0 +1,76 @@
+import { $module } from "alepha";
+import { AdminBillingController } from "./controllers/AdminBillingController.ts";
+import { BillingController } from "./controllers/BillingController.ts";
+import { BillingProvider } from "./providers/BillingProvider.ts";
+import { MemoryBillingProvider } from "./providers/MemoryBillingProvider.ts";
+import { BillingService } from "./services/BillingService.ts";
+import { PaymentMethodService } from "./services/PaymentMethodService.ts";
+
+export * from "./controllers/AdminBillingController.ts";
+export * from "./controllers/BillingController.ts";
+export * from "./entities/paymentIntents.ts";
+export * from "./entities/paymentMethods.ts";
+export * from "./entities/refunds.ts";
+export * from "./errors/BillingError.ts";
+export * from "./providers/BillingProvider.ts";
+export * from "./providers/MemoryBillingProvider.ts";
+export * from "./schemas/intentSchemas.ts";
+export * from "./schemas/paymentMethodSchemas.ts";
+export * from "./schemas/refundSchemas.ts";
+export * from "./services/BillingService.ts";
+export * from "./services/PaymentMethodService.ts";
+
+declare module "alepha" {
+  interface Hooks {
+    "billing:authorized": {
+      intentId: string;
+      amount: number;
+      currency: string;
+      metadata?: unknown;
+    };
+    "billing:captured": {
+      intentId: string;
+      amount: number;
+      currency: string;
+      metadata?: unknown;
+    };
+    "billing:failed": {
+      intentId: string;
+      amount: number;
+      currency: string;
+      metadata?: unknown;
+    };
+    "billing:voided": {
+      intentId: string;
+      amount: number;
+      currency: string;
+      metadata?: unknown;
+    };
+    "billing:refunded": {
+      intentId: string;
+      refundId: string;
+      amount: number;
+      currency: string;
+      metadata?: unknown;
+    };
+  }
+}
+
+export const AlephaBilling = $module({
+  name: "alepha.billing",
+  services: [
+    AdminBillingController,
+    BillingController,
+    BillingProvider,
+    MemoryBillingProvider,
+    BillingService,
+    PaymentMethodService,
+  ],
+  register: (alepha) => {
+    alepha.with({
+      optional: true,
+      provide: BillingProvider,
+      use: MemoryBillingProvider,
+    });
+  },
+});

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