alepha 0.20.6 → 0.20.7

package/src/api/payments/providers/PaymentProvider.ts

@@ -31,7 +31,12 @@ export abstract class PaymentProvider {
    */
   abstract createSession(
     intent: PaymentIntentEntity,
-    options: { returnUrl: string; authorize?: boolean },
+    options: {
+      returnUrl: string;
+      authorize?: boolean;
+      stripeAccount?: string;
+      applicationFeeAmount?: number;
+    },
   ): Promise<CreateSessionResult>;
 
   /**
@@ -54,19 +59,29 @@ export abstract class PaymentProvider {
   ): Promise<RefundResult>;
 
   /**
-   * Parse and verify an incoming PSP webhook request.
+   * Parse and verify the authenticity of 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).
+   * Implementations MUST establish authenticity before returning. Two
+   * common strategies, both acceptable:
    *
-   * Failure to verify signatures allows attackers to forge payment
-   * confirmations by POSTing fake webhook events.
+   * - Signature verification (Stripe, Adyen): verify an HMAC header
+   *   against the raw body using a shared secret. Throw if invalid.
+   * - Re-fetch (Mollie, legacy webhooks): the body only carries an id;
+   *   call back into the PSP API with your authenticated client to
+   *   fetch the real resource state. The fetch itself is the auth —
+   *   an attacker can POST a fake id but cannot influence the result.
+   *
+   * Throw an error if authenticity cannot be established. This endpoint
+   * has no $secure middleware; provider verification is its only auth.
    */
   abstract parseWebhook(request: Request): Promise<WebhookEvent>;
 
   /**
-   * Store a payment method token with the PSP.
+   * Store a payment method token with the PSP and return the saved
+   * instrument's reference. Implementations that don't support
+   * tokenize-then-attach (e.g. Mollie, where mandates are created by
+   * making a "first" payment) MAY throw to signal the host app to use
+   * the checkout flow with `setup_future_usage`-style options instead.
    */
   abstract createPaymentMethod(
     userId: string,
@@ -74,7 +89,8 @@ export abstract class PaymentProvider {
   ): Promise<CreatePaymentMethodResult>;
 
   /**
-   * Delete a stored payment method from the PSP.
+   * Delete a stored payment method from the PSP. Implementations that
+   * don't manage payment methods directly MAY no-op.
    */
   abstract deletePaymentMethod(providerRef: string): Promise<void>;
 

package/src/api/payments/services/PaymentService.ts

@@ -79,6 +79,7 @@ export class PaymentService {
     returnUrl: string,
     authorize?: boolean,
     userId?: string,
+    options?: { stripeAccount?: string; applicationFeeAmount?: number },
   ): Promise<{ url: string; intentId: string }> {
     const intent = await this.getIntent(intentId);
     this.assertStatus(intent, "created", "createSession");
@@ -96,6 +97,8 @@ export class PaymentService {
     const result = await this.provider.createSession(intent, {
       returnUrl,
       authorize,
+      stripeAccount: options?.stripeAccount,
+      applicationFeeAmount: options?.applicationFeeAmount,
     });
 
     await this.intentRepo.updateById(intent.id, {

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

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

@@ -0,0 +1,278 @@
+import { randomUUID } from "node:crypto";
+import { Alepha } from "alepha";
+import { AlephaOrmPostgres } from "alepha/orm/postgres";
+import { BadRequestError } from "alepha/server";
+import { describe, it } from "vitest";
+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 });
+  }
+}
+
+// -----------------------------------------------------------------------------------------------------------------
+
+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;
+  await alepha.start();
+
+  await config.seedPlans(testPlans);
+
+  return { alepha, service, config };
+};
+
+// -----------------------------------------------------------------------------------------------------------------
+
+describe("SubscriptionService", () => {
+  // ---------------------------------------------------------------------------------------------------------------
+
+  describe("subscribe", () => {
+    it("should create a trialing subscription with trial days", async ({
+      expect,
+    }) => {
+      const { service } = await setup();
+      const orgId = randomUUID();
+
+      const sub = await service.subscribe(orgId, "pro", "monthly");
+
+      expect(sub.status).toBe("trialing");
+      expect(sub.planId).toBe("pro");
+      expect(sub.interval).toBe("monthly");
+      expect(sub.organizationId).toBe(orgId);
+      expect(sub.trialStart).toBeDefined();
+      expect(sub.trialEnd).toBeDefined();
+    });
+
+    it("should create an active subscription when skipTrial", async ({
+      expect,
+    }) => {
+      const { service } = await setup();
+      const orgId = randomUUID();
+
+      const sub = await service.subscribe(orgId, "pro", "monthly", {
+        skipTrial: true,
+      });
+
+      expect(sub.status).toBe("active");
+      expect(sub.planId).toBe("pro");
+      expect(sub.trialStart).toBeUndefined();
+      expect(sub.trialEnd).toBeUndefined();
+    });
+
+    it("should reject when plan not found", async ({ expect }) => {
+      const { service } = await setup();
+      const orgId = randomUUID();
+
+      await expect(
+        service.subscribe(orgId, "nonexistent", "monthly"),
+      ).rejects.toThrow(BadRequestError);
+    });
+
+    it("should reject duplicate subscription for same org", async ({
+      expect,
+    }) => {
+      const { service } = await setup();
+      const orgId = randomUUID();
+
+      await service.subscribe(orgId, "pro", "monthly", {
+        skipTrial: true,
+      });
+
+      await expect(service.subscribe(orgId, "free", "monthly")).rejects.toThrow(
+        BadRequestError,
+      );
+    });
+  });
+
+  // ---------------------------------------------------------------------------------------------------------------
+
+  describe("cancel", () => {
+    it("should cancel at period end", async ({ expect }) => {
+      const { service } = await setup();
+      const orgId = randomUUID();
+
+      const sub = await service.subscribe(orgId, "pro", "monthly", {
+        skipTrial: true,
+      });
+
+      await service.cancel(sub.id, { immediate: false });
+
+      const updated = await service.getSubscription(sub.id);
+      expect(updated.status).toBe("cancelled");
+      expect(updated.cancelAtPeriodEnd).toBe(true);
+      expect(updated.cancelledAt).toBeDefined();
+    });
+
+    it("should cancel immediately with expired status", async ({ expect }) => {
+      const { service } = await setup();
+      const orgId = randomUUID();
+
+      const sub = await service.subscribe(orgId, "pro", "monthly", {
+        skipTrial: true,
+      });
+
+      await service.cancel(sub.id, { immediate: true });
+
+      const updated = await service.getSubscription(sub.id);
+      expect(updated.status).toBe("expired");
+      expect(updated.cancelAtPeriodEnd).toBe(false);
+      expect(updated.cancelledAt).toBeDefined();
+    });
+  });
+
+  // ---------------------------------------------------------------------------------------------------------------
+
+  describe("resume", () => {
+    it("should resume a cancelled subscription back to active", async ({
+      expect,
+    }) => {
+      const { service } = await setup();
+      const orgId = randomUUID();
+
+      const sub = await service.subscribe(orgId, "pro", "monthly", {
+        skipTrial: true,
+      });
+
+      await service.cancel(sub.id, { immediate: false });
+
+      const cancelled = await service.getSubscription(sub.id);
+      expect(cancelled.status).toBe("cancelled");
+
+      await service.resume(sub.id);
+
+      const resumed = await service.getSubscription(sub.id);
+      expect(resumed.status).toBe("active");
+      expect(resumed.cancelAtPeriodEnd).toBe(false);
+    });
+  });
+
+  // ---------------------------------------------------------------------------------------------------------------
+
+  describe("changePlan", () => {
+    it("should schedule plan change at period end", async ({ expect }) => {
+      const { service } = await setup();
+      const orgId = randomUUID();
+
+      const sub = await service.subscribe(orgId, "free", "monthly", {
+        skipTrial: true,
+      });
+
+      await service.changePlan(sub.id, "pro", "monthly", {
+        immediate: false,
+      });
+
+      const updated = await service.getSubscription(sub.id);
+      expect(updated.pendingPlanId).toBe("pro");
+      expect(updated.planId).toBe("free");
+    });
+
+    it("should apply immediate plan change", async ({ expect }) => {
+      const { service } = await setup();
+      const orgId = randomUUID();
+
+      const sub = await service.subscribe(orgId, "free", "monthly", {
+        skipTrial: true,
+      });
+
+      await service.changePlan(sub.id, "pro", "monthly", {
+        immediate: true,
+      });
+
+      const updated = await service.getSubscription(sub.id);
+      expect(updated.planId).toBe("pro");
+      expect(updated.pendingPlanId).toBeUndefined();
+    });
+  });
+
+  // ---------------------------------------------------------------------------------------------------------------
+
+  describe("entitlements", () => {
+    it("should return true for included feature", async ({ expect }) => {
+      const { service } = await setup();
+      const orgId = randomUUID();
+
+      await service.subscribe(orgId, "pro", "monthly", {
+        skipTrial: true,
+      });
+
+      const canAnalytics = await service.can(orgId, "analytics");
+      expect(canAnalytics).toBe(true);
+    });
+
+    it("should return false for excluded feature", async ({ expect }) => {
+      const { service } = await setup();
+      const orgId = randomUUID();
+
+      await service.subscribe(orgId, "free", "monthly", {
+        skipTrial: true,
+      });
+
+      const canAnalytics = await service.can(orgId, "analytics");
+      expect(canAnalytics).toBe(false);
+    });
+
+    it("should return correct limit value", async ({ expect }) => {
+      const { service } = await setup();
+      const orgId = randomUUID();
+
+      await service.subscribe(orgId, "pro", "monthly", {
+        skipTrial: true,
+      });
+
+      const seats = await service.limit(orgId, "seats");
+      expect(seats).toBe(10);
+
+      const apiCalls = await service.limit(orgId, "api-calls");
+      expect(apiCalls).toBe(10000);
+    });
+
+    it("should return 0 limit for no subscription", async ({ expect }) => {
+      const { service } = await setup();
+      const orgId = randomUUID();
+
+      const seats = await service.limit(orgId, "seats");
+      expect(seats).toBe(0);
+    });
+  });
+});