alepha 0.19.3 → 0.19.4

package/src/{billing → api/payments}/index.ts

@@ -1,76 +1,82 @@
 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 { AdminPaymentController } from "./controllers/AdminPaymentController.ts";
+import { PaymentController } from "./controllers/PaymentController.ts";
+import { MemoryPaymentProvider } from "./providers/MemoryPaymentProvider.ts";
+import { PaymentProvider } from "./providers/PaymentProvider.ts";
 import { PaymentMethodService } from "./services/PaymentMethodService.ts";
+import { PaymentService } from "./services/PaymentService.ts";
 
-export * from "./controllers/AdminBillingController.ts";
-export * from "./controllers/BillingController.ts";
+export * from "./controllers/AdminPaymentController.ts";
+export * from "./controllers/PaymentController.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 "./errors/PaymentError.ts";
+export * from "./providers/MemoryPaymentProvider.ts";
+export * from "./providers/PaymentProvider.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";
+export * from "./services/PaymentService.ts";
 
 declare module "alepha" {
   interface Hooks {
-    "billing:authorized": {
+    "payments:authorized": {
       intentId: string;
       amount: number;
       currency: string;
       metadata?: unknown;
     };
-    "billing:captured": {
+    "payments:captured": {
       intentId: string;
       amount: number;
       currency: string;
       metadata?: unknown;
     };
-    "billing:failed": {
+    "payments:failed": {
       intentId: string;
       amount: number;
       currency: string;
       metadata?: unknown;
     };
-    "billing:voided": {
+    "payments:voided": {
       intentId: string;
       amount: number;
       currency: string;
       metadata?: unknown;
     };
-    "billing:refunded": {
+    "payments:refunded": {
       intentId: string;
       refundId: string;
       amount: number;
       currency: string;
       metadata?: unknown;
     };
+    "payments:cancelled": {
+      intentId: string;
+      amount: number;
+      currency: string;
+      metadata?: unknown;
+    };
   }
 }
 
-export const AlephaBilling = $module({
-  name: "alepha.billing",
+export const AlephaApiPayments = $module({
+  name: "alepha.api.payments",
   services: [
-    AdminBillingController,
-    BillingController,
-    BillingProvider,
-    MemoryBillingProvider,
-    BillingService,
+    AdminPaymentController,
+    PaymentController,
+    PaymentProvider,
+    MemoryPaymentProvider,
+    PaymentService,
     PaymentMethodService,
   ],
   register: (alepha) => {
     alepha.with({
       optional: true,
-      provide: BillingProvider,
-      use: MemoryBillingProvider,
+      provide: PaymentProvider,
+      use: MemoryPaymentProvider,
     });
   },
 });

package/src/{billing/providers/MemoryBillingProvider.ts → api/payments/providers/MemoryPaymentProvider.ts}

@@ -1,12 +1,12 @@
 import { randomUUID } from "node:crypto";
 import type { PaymentIntentEntity } from "../entities/paymentIntents.ts";
 import type {
-  BillingProvider,
   CreatePaymentMethodResult,
   CreateSessionResult,
+  PaymentProvider,
   RefundResult,
   WebhookEvent,
-} from "./BillingProvider.ts";
+} from "./PaymentProvider.ts";
 
 interface MemoryCharge {
   providerRef: string;
@@ -20,7 +20,7 @@ interface MemoryRefund {
   amount: number;
 }
 
-export class MemoryBillingProvider implements BillingProvider {
+export class MemoryPaymentProvider implements PaymentProvider {
   protected readonly charges: Map<string, MemoryCharge> = new Map();
   protected readonly refundRecords: Map<string, MemoryRefund> = new Map();
   protected readonly methods: Map<string, CreatePaymentMethodResult> =
@@ -39,7 +39,7 @@ export class MemoryBillingProvider implements BillingProvider {
       status,
     });
     return {
-      url: `/billing/mock-checkout/${intent.id}`,
+      url: `/payments/mock-checkout/${intent.id}`,
       providerRef,
     };
   }

package/src/{billing/providers/BillingProvider.ts → api/payments/providers/PaymentProvider.ts}

@@ -24,7 +24,7 @@ export interface CreatePaymentMethodResult {
   expYear?: number;
 }
 
-export abstract class BillingProvider {
+export abstract class PaymentProvider {
   /**
    * Create a checkout session with the PSP.
    * Returns a URL to redirect the user to, and the PSP's reference ID.
@@ -54,7 +54,14 @@ export abstract class BillingProvider {
   ): Promise<RefundResult>;
 
   /**
-   * Parse an incoming PSP webhook request into a normalized event.
+   * Parse and verify an incoming PSP webhook request.
+   *
+   * Implementations MUST verify the webhook signature before returning.
+   * Throw an error if the signature is invalid or missing — this is the
+   * only authentication on the webhook endpoint (no $secure middleware).
+   *
+   * Failure to verify signatures allows attackers to forge payment
+   * confirmations by POSTing fake webhook events.
    */
   abstract parseWebhook(request: Request): Promise<WebhookEvent>;
 

package/src/{billing → api/payments}/services/PaymentMethodService.ts

@@ -5,12 +5,12 @@ import {
   type PaymentMethodEntity,
   paymentMethods,
 } from "../entities/paymentMethods.ts";
-import { BillingError } from "../errors/BillingError.ts";
-import { BillingProvider } from "../providers/BillingProvider.ts";
+import { PaymentError } from "../errors/PaymentError.ts";
+import { PaymentProvider } from "../providers/PaymentProvider.ts";
 
 export class PaymentMethodService {
   protected readonly log = $logger();
-  protected readonly provider = $inject(BillingProvider);
+  protected readonly provider = $inject(PaymentProvider);
   protected readonly methodRepo = $repository(paymentMethods);
 
   public async addPaymentMethod(
@@ -51,7 +51,7 @@ export class PaymentMethodService {
   ): Promise<void> {
     const method = await this.methodRepo.getById(methodId);
     if (method.userId !== userId) {
-      throw new BillingError("Cannot remove another user's payment method");
+      throw new PaymentError("Cannot remove another user's payment method");
     }
 
     await this.provider.deletePaymentMethod(method.providerRef);
@@ -64,7 +64,7 @@ export class PaymentMethodService {
   ): Promise<PaymentMethodEntity> {
     const method = await this.methodRepo.getById(methodId);
     if (method.userId !== userId) {
-      throw new BillingError("Cannot modify another user's payment method");
+      throw new PaymentError("Cannot modify another user's payment method");
     }
 
     const userMethods = await this.methodRepo.findMany({

package/src/{billing/services/BillingService.ts → api/payments/services/PaymentService.ts}

@@ -8,14 +8,14 @@ import {
   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";
+import { PaymentError } from "../errors/PaymentError.ts";
+import { PaymentProvider } from "../providers/PaymentProvider.ts";
 
-export class BillingService {
+export class PaymentService {
   protected readonly alepha = $inject(Alepha);
   protected readonly log = $logger();
   protected readonly dateTime = $inject(DateTimeProvider);
-  protected readonly provider = $inject(BillingProvider);
+  protected readonly provider = $inject(PaymentProvider);
   protected readonly intentRepo = $repository(paymentIntents);
   protected readonly refundRepo = $repository(refunds);
 
@@ -60,7 +60,7 @@ export class BillingService {
   ): Promise<PaymentIntentEntity> {
     return await this.intentRepo.create({
       amount,
-      currency,
+      currency: currency.toLowerCase(),
       status: "created",
       metadata: metadata as any,
       paymentMethodId: options?.paymentMethodId,
@@ -76,10 +76,21 @@ export class BillingService {
     intentId: string,
     returnUrl: string,
     authorize?: boolean,
+    userId?: string,
   ): Promise<{ url: string; intentId: string }> {
     const intent = await this.getIntent(intentId);
     this.assertStatus(intent, "created", "createSession");
 
+    // Verify intent ownership if userId is provided
+    if (userId && intent.userId && intent.userId !== userId) {
+      throw new PaymentError("Payment intent does not belong to this user");
+    }
+
+    // Associate intent with user if not already set
+    if (userId && !intent.userId) {
+      await this.intentRepo.updateById(intent.id, { userId });
+    }
+
     const result = await this.provider.createSession(intent, {
       returnUrl,
       authorize,
@@ -114,8 +125,20 @@ export class BillingService {
 
   /**
    * Process a webhook event by updating the intent status and emitting
-   * the corresponding billing event.
+   * the corresponding payment event.
    */
+  /**
+   * Valid status transitions from webhook events.
+   * Only these transitions are allowed — all others are silently ignored.
+   */
+  protected static readonly VALID_WEBHOOK_TRANSITIONS: Record<
+    string,
+    string[]
+  > = {
+    processing: ["authorized", "captured", "failed"],
+    authorized: ["captured", "failed"],
+  };
+
   public async handleWebhookEvent(
     intentId: string,
     status: string,
@@ -124,9 +147,9 @@ export class BillingService {
     const intent = await this.getIntent(intentId);
 
     const eventMap = {
-      authorized: "billing:authorized",
-      captured: "billing:captured",
-      failed: "billing:failed",
+      authorized: "payments:authorized",
+      captured: "payments:captured",
+      failed: "payments:failed",
     } as const;
 
     type WebhookStatus = keyof typeof eventMap;
@@ -137,6 +160,16 @@ export class BillingService {
 
     const webhookStatus = status as WebhookStatus;
 
+    // Validate status transition
+    const allowed = PaymentService.VALID_WEBHOOK_TRANSITIONS[intent.status];
+    if (!allowed?.includes(webhookStatus)) {
+      this.log.warn(
+        `Ignoring webhook: cannot transition ${intent.status} → ${webhookStatus}`,
+        { intentId: intent.id },
+      );
+      return;
+    }
+
     await this.intentRepo.updateById(intent.id, {
       status: webhookStatus,
       providerRaw: raw as any,
@@ -162,6 +195,12 @@ export class BillingService {
     this.assertStatus(intent, "authorized", "capture");
 
     const amount = finalAmount ?? intent.amount;
+    if (amount > intent.amount) {
+      throw new PaymentError(
+        `Capture amount ${amount} exceeds authorized amount ${intent.amount}`,
+      );
+    }
+
     if (intent.providerRef) {
       await this.provider.capturePayment(intent.providerRef, amount);
     }
@@ -171,7 +210,7 @@ export class BillingService {
       amount,
     });
 
-    await this.alepha.events.emit("billing:captured", {
+    await this.alepha.events.emit("payments:captured", {
       intentId: intent.id,
       amount,
       currency: intent.currency,
@@ -196,7 +235,7 @@ export class BillingService {
       status: "voided",
     });
 
-    await this.alepha.events.emit("billing:voided", {
+    await this.alepha.events.emit("payments:voided", {
       intentId: intent.id,
       amount: intent.amount,
       currency: intent.currency,
@@ -215,7 +254,29 @@ export class BillingService {
     reason?: string,
   ): Promise<RefundEntity> {
     const intent = await this.getIntent(intentId);
-    this.assertStatus(intent, "captured", "refund");
+
+    // Allow refunds from both "captured" and "partially_refunded" states
+    if (
+      intent.status !== "captured" &&
+      intent.status !== "partially_refunded"
+    ) {
+      throw new PaymentError(
+        `Cannot refund: intent ${intent.id} is '${intent.status}', expected 'captured' or 'partially_refunded'`,
+      );
+    }
+
+    // Validate refund amount against remaining refundable amount
+    const existingRefunds = await this.refundRepo.findMany({
+      where: { intentId: { eq: intent.id } },
+    });
+    const totalRefunded = existingRefunds.reduce((sum, r) => sum + r.amount, 0);
+    const remaining = intent.amount - totalRefunded;
+
+    if (amount > remaining) {
+      throw new PaymentError(
+        `Refund amount ${amount} exceeds remaining refundable amount ${remaining}`,
+      );
+    }
 
     let refundProviderRef: string | undefined;
     if (intent.providerRef) {
@@ -236,9 +297,15 @@ export class BillingService {
       providerRef: refundProviderRef,
     });
 
-    await this.intentRepo.updateById(intent.id, { status: "refunded" });
+    // Set status based on whether fully or partially refunded
+    const newTotalRefunded = totalRefunded + amount;
+    const newStatus =
+      newTotalRefunded >= intent.amount ? "refunded" : "partially_refunded";
+    await this.intentRepo.updateById(intent.id, {
+      status: newStatus,
+    });
 
-    await this.alepha.events.emit("billing:refunded", {
+    await this.alepha.events.emit("payments:refunded", {
       intentId: intent.id,
       refundId: refund.id,
       amount,
@@ -260,12 +327,12 @@ export class BillingService {
   ): Promise<PaymentIntentEntity> {
     const intent = await this.intentRepo.create({
       amount,
-      currency,
+      currency: currency.toLowerCase(),
       status: "captured",
       metadata: metadata as any,
     });
 
-    await this.alepha.events.emit("billing:captured", {
+    await this.alepha.events.emit("payments:captured", {
       intentId: intent.id,
       amount,
       currency,
@@ -282,9 +349,18 @@ export class BillingService {
     const intent = await this.getIntent(intentId);
     this.assertStatus(intent, "created", "cancel");
 
-    return await this.intentRepo.updateById(intent.id, {
+    const cancelled = await this.intentRepo.updateById(intent.id, {
       status: "cancelled",
     });
+
+    await this.alepha.events.emit("payments:cancelled", {
+      intentId: intent.id,
+      amount: intent.amount,
+      currency: intent.currency,
+      metadata: intent.metadata,
+    });
+
+    return cancelled;
   }
 
   /**
@@ -317,7 +393,7 @@ export class BillingService {
     operation: string,
   ): void {
     if (intent.status !== expected) {
-      throw new BillingError(
+      throw new PaymentError(
         `Cannot ${operation}: intent ${intent.id} is '${intent.status}', expected '${expected}'`,
       );
     }

package/src/api/subscriptions/__tests__/BillingService.spec.ts

@@ -0,0 +1,218 @@
+import { randomUUID } from "node:crypto";
+import { Alepha } from "alepha";
+import { $repository } from "alepha/orm";
+import { AlephaOrmPostgres } from "alepha/orm/postgres";
+import { describe, it } from "vitest";
+import { subscriptions } from "../entities/subscriptions.ts";
+import { AlephaApiSubscriptions } from "../index.ts";
+import type { PlanDefinition } from "../schemas/planDefinitionSchema.ts";
+import { SubscriptionConfig } from "../services/SubscriptionConfig.ts";
+import { SubscriptionService } from "../services/SubscriptionService.ts";
+
+// -----------------------------------------------------------------------------------------------------------------
+
+class TestSubscriptionConfig extends SubscriptionConfig {
+  public async seedPlans(plans: PlanDefinition[]): Promise<void> {
+    await this.plans.set({ plans });
+  }
+}
+
+/**
+ * Helper to directly update subscription records for test setup.
+ */
+class TestRepositories {
+  subscriptionRepo = $repository(subscriptions);
+}
+
+// -----------------------------------------------------------------------------------------------------------------
+
+const testPlans: PlanDefinition[] = [
+  {
+    id: "free",
+    name: "Free",
+    available: true,
+    pricing: [{ interval: "monthly", amount: 0, currency: "usd" }],
+    features: ["dashboard"],
+    limits: { seats: 1, "api-calls": 100 },
+    order: 0,
+  },
+  {
+    id: "pro",
+    name: "Pro",
+    available: true,
+    pricing: [
+      { interval: "monthly", amount: 2900, currency: "usd" },
+      { interval: "yearly", amount: 29000, currency: "usd" },
+    ],
+    trial: { days: 14, requirePaymentMethod: false },
+    features: ["dashboard", "analytics", "export"],
+    limits: { seats: 10, "api-calls": 10000 },
+    order: 1,
+  },
+];
+
+// -----------------------------------------------------------------------------------------------------------------
+
+const setup = async () => {
+  const alepha = Alepha.create()
+    .with(AlephaOrmPostgres)
+    .with({ provide: SubscriptionConfig, use: TestSubscriptionConfig })
+    .with(AlephaApiSubscriptions);
+
+  const service = alepha.inject(SubscriptionService);
+  const config = alepha.inject(
+    TestSubscriptionConfig,
+  ) as TestSubscriptionConfig;
+  const repos = alepha.inject(TestRepositories);
+  await alepha.start();
+
+  await config.seedPlans(testPlans);
+
+  /**
+   * Helper: create a subscription and attach a payment intent ID for billing lookup.
+   */
+  const createSubscriptionWithIntent = async (
+    planId: string,
+    intentId: string,
+    options?: { skipTrial?: boolean },
+  ) => {
+    const orgId = randomUUID();
+    const sub = await service.subscribe(orgId, planId, "monthly", options);
+    await repos.subscriptionRepo.updateById(sub.id, {
+      lastPaymentIntentId: intentId,
+    });
+    return service.getSubscription(sub.id);
+  };
+
+  return { alepha, service, config, repos, createSubscriptionWithIntent };
+};
+
+// -----------------------------------------------------------------------------------------------------------------
+
+describe("BillingService", () => {
+  // ---------------------------------------------------------------------------------------------------------------
+
+  describe("payment captured", () => {
+    it("should activate a trialing subscription after payment", async ({
+      expect,
+    }) => {
+      const { alepha, service, createSubscriptionWithIntent } = await setup();
+
+      const intentId = randomUUID();
+      const sub = await createSubscriptionWithIntent("pro", intentId);
+      expect(sub.status).toBe("trialing");
+
+      await alepha.events.emit("payments:captured", {
+        intentId,
+        amount: 2900,
+        currency: "usd",
+      });
+
+      const updated = await service.getSubscription(sub.id);
+      expect(updated.status).toBe("active");
+      expect(updated.lastPaymentIntentId).toBe(intentId);
+    });
+
+    it("should renew an active subscription and advance period", async ({
+      expect,
+    }) => {
+      const { alepha, service, createSubscriptionWithIntent } = await setup();
+
+      const intentId = randomUUID();
+      const sub = await createSubscriptionWithIntent("pro", intentId, {
+        skipTrial: true,
+      });
+      expect(sub.status).toBe("active");
+
+      const originalPeriodEnd = sub.currentPeriodEnd;
+
+      await alepha.events.emit("payments:captured", {
+        intentId,
+        amount: 2900,
+        currency: "usd",
+      });
+
+      const updated = await service.getSubscription(sub.id);
+      expect(updated.status).toBe("active");
+      expect(updated.currentPeriodStart).toBe(originalPeriodEnd);
+      expect(updated.currentPeriodEnd).not.toBe(originalPeriodEnd);
+    });
+
+    it("should recover from dunning", async ({ expect }) => {
+      const { alepha, service, repos, createSubscriptionWithIntent } =
+        await setup();
+
+      const intentId = randomUUID();
+      const sub = await createSubscriptionWithIntent("pro", intentId, {
+        skipTrial: true,
+      });
+
+      await repos.subscriptionRepo.updateById(sub.id, {
+        status: "past_due",
+        dunningAttempt: 2,
+        dunningStartedAt: new Date().toISOString(),
+      });
+
+      await alepha.events.emit("payments:captured", {
+        intentId,
+        amount: 2900,
+        currency: "usd",
+      });
+
+      const updated = await service.getSubscription(sub.id);
+      expect(updated.status).toBe("active");
+      expect(updated.dunningAttempt).toBe(0);
+    });
+  });
+
+  // ---------------------------------------------------------------------------------------------------------------
+
+  describe("payment failed", () => {
+    it("should start dunning on first failure", async ({ expect }) => {
+      const { alepha, service, createSubscriptionWithIntent } = await setup();
+
+      const intentId = randomUUID();
+      const sub = await createSubscriptionWithIntent("pro", intentId, {
+        skipTrial: true,
+      });
+      expect(sub.status).toBe("active");
+
+      await alepha.events.emit("payments:failed", {
+        intentId,
+        amount: 2900,
+        currency: "usd",
+      });
+
+      const updated = await service.getSubscription(sub.id);
+      expect(updated.status).toBe("past_due");
+      expect(updated.dunningAttempt).toBe(1);
+      expect(updated.dunningStartedAt).toBeDefined();
+    });
+
+    it("should increment dunning on subsequent failure", async ({ expect }) => {
+      const { alepha, service, repos, createSubscriptionWithIntent } =
+        await setup();
+
+      const intentId = randomUUID();
+      const sub = await createSubscriptionWithIntent("pro", intentId, {
+        skipTrial: true,
+      });
+
+      await repos.subscriptionRepo.updateById(sub.id, {
+        status: "past_due",
+        dunningAttempt: 1,
+        dunningStartedAt: new Date().toISOString(),
+      });
+
+      await alepha.events.emit("payments:failed", {
+        intentId,
+        amount: 2900,
+        currency: "usd",
+      });
+
+      const updated = await service.getSubscription(sub.id);
+      expect(updated.status).toBe("past_due");
+      expect(updated.dunningAttempt).toBe(2);
+    });
+  });
+});