alepha 0.19.2 → 0.19.4

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

package/src/api/subscriptions/controllers/AdminSubscriptionController.ts

@@ -0,0 +1,212 @@
+import { $inject, t } from "alepha";
+import { $secure } from "alepha/security";
+import { $action, okSchema } from "alepha/server";
+import { cancelSubscriptionSchema } from "../schemas/cancelSubscriptionSchema.ts";
+import { changePlanSchema } from "../schemas/changePlanSchema.ts";
+import { mrrSchema } from "../schemas/mrrSchema.ts";
+import { subscriptionQuerySchema } from "../schemas/subscriptionQuerySchema.ts";
+import { subscriptionResourceSchema } from "../schemas/subscriptionResourceSchema.ts";
+import { subscriptionStatsSchema } from "../schemas/subscriptionStatsSchema.ts";
+import { SubscriptionConfig } from "../services/SubscriptionConfig.ts";
+import { SubscriptionService } from "../services/SubscriptionService.ts";
+
+export class AdminSubscriptionController {
+  protected readonly url = "/subscriptions";
+  protected readonly group = "admin:subscriptions";
+  protected readonly service = $inject(SubscriptionService);
+  protected readonly config = $inject(SubscriptionConfig);
+
+  /**
+   * Find subscriptions with pagination and filtering.
+   */
+  public readonly findSubscriptions = $action({
+    path: this.url,
+    group: this.group,
+    use: [$secure({ permissions: ["admin:subscription:read"] })],
+    description: "Find subscriptions with pagination and filtering",
+    schema: {
+      query: subscriptionQuerySchema,
+      response: t.page(subscriptionResourceSchema),
+    },
+    handler: ({ query }) => this.service.findSubscriptions(query),
+  });
+
+  /**
+   * Get a subscription by ID.
+   */
+  public readonly getSubscription = $action({
+    path: `${this.url}/:id`,
+    group: this.group,
+    use: [$secure({ permissions: ["admin:subscription:read"] })],
+    description: "Get a subscription by ID",
+    schema: {
+      params: t.object({ id: t.uuid() }),
+      response: subscriptionResourceSchema,
+    },
+    handler: ({ params }) => this.service.getSubscription(params.id),
+  });
+
+  /**
+   * Get aggregated subscription statistics.
+   */
+  public readonly getStats = $action({
+    path: `${this.url}/stats`,
+    group: this.group,
+    use: [$secure({ permissions: ["admin:subscription:read"] })],
+    description: "Get aggregated subscription statistics",
+    schema: {
+      response: subscriptionStatsSchema,
+    },
+    handler: () => this.service.getStats(),
+  });
+
+  /**
+   * Get revenue data from recent subscription events.
+   */
+  public readonly getRevenue = $action({
+    path: `${this.url}/revenue`,
+    group: this.group,
+    use: [$secure({ permissions: ["admin:subscription:read"] })],
+    description: "Get revenue data from recent subscription events",
+    schema: {
+      query: t.object({
+        days: t.optional(t.integer({ minimum: 1, maximum: 365 })),
+      }),
+      response: t.object({ total: t.integer(), count: t.integer() }),
+    },
+    handler: ({ query }) => this.service.getRevenue(query.days),
+  });
+
+  /**
+   * Get Monthly Recurring Revenue breakdown.
+   */
+  public readonly getMrr = $action({
+    path: `${this.url}/mrr`,
+    group: this.group,
+    use: [$secure({ permissions: ["admin:subscription:read"] })],
+    description: "Get Monthly Recurring Revenue breakdown",
+    schema: {
+      response: mrrSchema,
+    },
+    handler: async () => {
+      const activeSubs = await this.service.findSubscriptions({
+        status: "active",
+        size: 1000,
+      });
+
+      const plans = await this.config.getPlans();
+      const byPlan: Record<string, number> = {};
+      let total = 0;
+
+      for (const sub of activeSubs.content) {
+        const plan = plans.find((p) => p.id === sub.planId);
+        if (!plan) continue;
+
+        const pricing = plan.pricing.find((p) => p.interval === sub.interval);
+        if (!pricing) continue;
+
+        const monthlyAmount =
+          sub.interval === "yearly"
+            ? Math.round(pricing.amount / 12)
+            : pricing.amount;
+
+        byPlan[sub.planId] = (byPlan[sub.planId] ?? 0) + monthlyAmount;
+        total += monthlyAmount;
+      }
+
+      return {
+        total,
+        byPlan,
+        growth: 0,
+        newMrr: 0,
+        expansionMrr: 0,
+        contractionMrr: 0,
+        churnMrr: 0,
+      };
+    },
+  });
+
+  /**
+   * Force a plan change for a subscription (admin action).
+   */
+  public readonly adminChangePlan = $action({
+    method: "POST",
+    path: `${this.url}/:id/change-plan`,
+    group: this.group,
+    use: [$secure({ permissions: ["admin:subscription:update"] })],
+    description: "Force a plan change for a subscription",
+    schema: {
+      params: t.object({ id: t.uuid() }),
+      body: changePlanSchema,
+      response: subscriptionResourceSchema,
+    },
+    handler: async ({ params, body }) => {
+      await this.service.changePlan(params.id, body.planId, body.interval, {
+        immediate: body.immediate,
+      });
+      return this.service.getSubscription(params.id);
+    },
+  });
+
+  /**
+   * Force cancel a subscription (admin action).
+   */
+  public readonly adminCancel = $action({
+    method: "POST",
+    path: `${this.url}/:id/cancel`,
+    group: this.group,
+    use: [$secure({ permissions: ["admin:subscription:update"] })],
+    description: "Force cancel a subscription",
+    schema: {
+      params: t.object({ id: t.uuid() }),
+      body: cancelSubscriptionSchema,
+      response: okSchema,
+    },
+    handler: async ({ params, body }) => {
+      await this.service.cancel(params.id, {
+        reason: body.reason,
+        immediate: body.immediate,
+      });
+      return { ok: true };
+    },
+  });
+
+  /**
+   * Reactivate a suspended subscription (admin action).
+   */
+  public readonly adminReactivate = $action({
+    method: "POST",
+    path: `${this.url}/:id/reactivate`,
+    group: this.group,
+    use: [$secure({ permissions: ["admin:subscription:update"] })],
+    description: "Reactivate a suspended subscription",
+    schema: {
+      params: t.object({ id: t.uuid() }),
+      response: okSchema,
+    },
+    handler: async ({ params }) => {
+      await this.service.reactivate(params.id);
+      return { ok: true };
+    },
+  });
+
+  /**
+   * Extend the trial period for a trialing subscription (admin action).
+   */
+  public readonly adminExtendTrial = $action({
+    method: "POST",
+    path: `${this.url}/:id/extend-trial`,
+    group: this.group,
+    use: [$secure({ permissions: ["admin:subscription:update"] })],
+    description: "Extend the trial period for a subscription",
+    schema: {
+      params: t.object({ id: t.uuid() }),
+      body: t.object({ days: t.integer({ minimum: 1, maximum: 365 }) }),
+      response: okSchema,
+    },
+    handler: async ({ params, body }) => {
+      await this.service.extendTrial(params.id, body.days);
+      return { ok: true };
+    },
+  });
+}

package/src/api/subscriptions/controllers/SubscriptionController.ts

@@ -0,0 +1,189 @@
+import { $inject, t } from "alepha";
+import { $secure } from "alepha/security";
+import { $action, NotFoundError, okSchema } from "alepha/server";
+import { cancelSubscriptionSchema } from "../schemas/cancelSubscriptionSchema.ts";
+import { changePlanSchema } from "../schemas/changePlanSchema.ts";
+import { createSubscriptionSchema } from "../schemas/createSubscriptionSchema.ts";
+import { entitlementsSchema } from "../schemas/entitlementsSchema.ts";
+import { planResourceSchema } from "../schemas/planResourceSchema.ts";
+import { subscriptionEventResourceSchema } from "../schemas/subscriptionEventResourceSchema.ts";
+import { subscriptionResourceSchema } from "../schemas/subscriptionResourceSchema.ts";
+import { SubscriptionConfig } from "../services/SubscriptionConfig.ts";
+import { SubscriptionService } from "../services/SubscriptionService.ts";
+
+export class SubscriptionController {
+  protected readonly url = "/subscriptions";
+  protected readonly group = "subscriptions";
+  protected readonly service = $inject(SubscriptionService);
+  protected readonly config = $inject(SubscriptionConfig);
+
+  /**
+   * List available subscription plans with pricing.
+   */
+  public readonly getPlans = $action({
+    path: `${this.url}/plans`,
+    group: this.group,
+    description: "List available subscription plans",
+    schema: {
+      response: t.array(planResourceSchema),
+    },
+    handler: async () => {
+      const plans = await this.config.getPlans();
+      return plans
+        .filter((p) => p.available)
+        .map((p) => ({
+          id: p.id,
+          name: p.name,
+          description: p.description,
+          pricing: p.pricing,
+          features: p.features,
+          limits: p.limits,
+          trial: p.trial,
+          order: p.order,
+        }));
+    },
+  });
+
+  /**
+   * Get the current organization's subscription.
+   */
+  public readonly getMySubscription = $action({
+    path: `${this.url}/mine`,
+    group: this.group,
+    use: [$secure()],
+    description: "Get the current organization subscription",
+    schema: {
+      response: subscriptionResourceSchema,
+    },
+    handler: async ({ user }) => {
+      const sub = await this.service.getByOrganization(user.organization!);
+      if (!sub)
+        throw new NotFoundError("No subscription found for your organization");
+      return sub;
+    },
+  });
+
+  /**
+   * Create a new subscription for the current organization.
+   */
+  public readonly subscribe = $action({
+    method: "POST",
+    path: this.url,
+    group: this.group,
+    use: [$secure({ permissions: ["subscription:create"] })],
+    description: "Create a new subscription",
+    schema: {
+      body: createSubscriptionSchema,
+      response: subscriptionResourceSchema,
+    },
+    handler: ({ body, user }) =>
+      this.service.subscribe(user.organization!, body.planId, body.interval, {
+        skipTrial: body.skipTrial,
+        metadata: body.metadata,
+      }),
+  });
+
+  /**
+   * Change the plan for the current organization's subscription.
+   */
+  public readonly changePlan = $action({
+    method: "POST",
+    path: `${this.url}/mine/change-plan`,
+    group: this.group,
+    use: [$secure({ permissions: ["subscription:update"] })],
+    description: "Upgrade or downgrade the subscription plan",
+    schema: {
+      body: changePlanSchema,
+      response: subscriptionResourceSchema,
+    },
+    handler: async ({ body, user }) => {
+      const sub = await this.service.getByOrganization(user.organization!);
+      if (!sub)
+        throw new NotFoundError("No subscription found for your organization");
+      await this.service.changePlan(sub.id, body.planId, body.interval, {
+        immediate: body.immediate,
+      });
+      return this.service.getSubscription(sub.id);
+    },
+  });
+
+  /**
+   * Cancel the current organization's subscription.
+   */
+  public readonly cancel = $action({
+    method: "POST",
+    path: `${this.url}/mine/cancel`,
+    group: this.group,
+    use: [$secure({ permissions: ["subscription:update"] })],
+    description: "Cancel the current subscription",
+    schema: {
+      body: cancelSubscriptionSchema,
+      response: okSchema,
+    },
+    handler: async ({ body, user }) => {
+      const sub = await this.service.getByOrganization(user.organization!);
+      if (!sub)
+        throw new NotFoundError("No subscription found for your organization");
+      await this.service.cancel(sub.id, {
+        reason: body.reason,
+        immediate: body.immediate,
+      });
+      return { ok: true };
+    },
+  });
+
+  /**
+   * Resume a cancelled subscription before the period ends.
+   */
+  public readonly resume = $action({
+    method: "POST",
+    path: `${this.url}/mine/resume`,
+    group: this.group,
+    use: [$secure({ permissions: ["subscription:update"] })],
+    description: "Resume a cancelled subscription",
+    schema: {
+      response: okSchema,
+    },
+    handler: async ({ user }) => {
+      const sub = await this.service.getByOrganization(user.organization!);
+      if (!sub)
+        throw new NotFoundError("No subscription found for your organization");
+      await this.service.resume(sub.id);
+      return { ok: true };
+    },
+  });
+
+  /**
+   * Get the billing event history for the current organization's subscription.
+   */
+  public readonly getSubscriptionHistory = $action({
+    path: `${this.url}/mine/history`,
+    group: this.group,
+    use: [$secure()],
+    description: "Get the subscription billing event history",
+    schema: {
+      response: t.array(subscriptionEventResourceSchema),
+    },
+    handler: async ({ user }) => {
+      const sub = await this.service.getByOrganization(user.organization!);
+      if (!sub)
+        throw new NotFoundError("No subscription found for your organization");
+      return this.service.getHistory(sub.id);
+    },
+  });
+
+  /**
+   * Get the feature and usage limit entitlements for the current organization.
+   */
+  public readonly getEntitlements = $action({
+    path: `${this.url}/mine/entitlements`,
+    group: this.group,
+    use: [$secure()],
+    description:
+      "Get the feature and limit entitlements for the current organization",
+    schema: {
+      response: entitlementsSchema,
+    },
+    handler: ({ user }) => this.service.getEntitlements(user.organization!),
+  });
+}