alepha 0.20.6 → 0.20.8

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

package/src/api/subscriptions/entities/subscriptionEvents.ts

@@ -0,0 +1,54 @@
+import { type Static, t } from "alepha";
+import { $entity, db } from "alepha/orm";
+import { subscriptions } from "./subscriptions.ts";
+
+export const subscriptionEvents = $entity({
+  name: "subscription_events",
+  schema: t.object({
+    id: db.primaryKey(t.uuid()),
+    createdAt: db.createdAt(),
+    subscriptionId: db.ref(t.uuid(), () => subscriptions.cols.id, {
+      onDelete: "cascade",
+    }),
+    organizationId: db.organization(),
+
+    type: t.enum([
+      "created",
+      "trial_started",
+      "trial_ended",
+      "activated",
+      "renewed",
+      "payment_failed",
+      "payment_retried",
+      "past_due",
+      "suspended",
+      "reactivated",
+      "plan_changed",
+      "plan_change_scheduled",
+      "cancelled",
+      "expired",
+      "resumed",
+    ]),
+
+    // Context
+    previousStatus: t.optional(t.string()),
+    newStatus: t.optional(t.string()),
+    previousPlanId: t.optional(t.string()),
+    newPlanId: t.optional(t.string()),
+    paymentIntentId: t.optional(t.uuid()),
+    amount: t.optional(t.integer()),
+    currency: t.optional(t.string()),
+
+    // Who / why
+    triggeredBy: t.optional(t.string()),
+    userId: t.optional(t.uuid()),
+    note: t.optional(t.string()),
+  }),
+  indexes: [
+    { columns: ["subscriptionId", "createdAt"] },
+    { columns: ["organizationId", "createdAt"] },
+    { columns: ["type"] },
+  ],
+});
+
+export type SubscriptionEventEntity = Static<typeof subscriptionEvents.schema>;

package/src/api/subscriptions/entities/subscriptions.ts

@@ -0,0 +1,68 @@
+import { type Static, t } from "alepha";
+import { $entity, db } from "alepha/orm";
+
+export const subscriptions = $entity({
+  name: "subscriptions",
+  schema: t.object({
+    id: db.primaryKey(t.uuid()),
+    version: db.version(),
+    createdAt: db.createdAt(),
+    updatedAt: db.updatedAt(),
+    organizationId: db.organization(),
+
+    // Plan
+    planId: t.string(),
+    interval: t.enum(["monthly", "yearly"]),
+
+    // Status
+    status: t.enum([
+      "trialing",
+      "active",
+      "past_due",
+      "suspended",
+      "cancelled",
+      "expired",
+    ]),
+
+    // Billing cycle
+    currentPeriodStart: t.datetime(),
+    currentPeriodEnd: t.datetime(),
+
+    // Trial
+    trialStart: t.optional(t.datetime()),
+    trialEnd: t.optional(t.datetime()),
+
+    // Cancellation
+    cancelledAt: t.optional(t.datetime()),
+    cancelReason: t.optional(t.string()),
+    cancelAtPeriodEnd: t.boolean({ default: false }),
+
+    // Payment tracking
+    lastPaymentIntentId: t.optional(t.uuid()),
+    lastPaymentAt: t.optional(t.datetime()),
+    nextBillingAt: t.optional(t.datetime()),
+
+    // Dunning state
+    dunningStartedAt: t.optional(t.datetime()),
+    dunningAttempt: t.integer({ default: 0 }),
+    dunningNextRetryAt: t.optional(t.datetime()),
+
+    // Plan change (pending)
+    pendingPlanId: t.optional(t.string()),
+    pendingInterval: t.optional(t.enum(["monthly", "yearly"])),
+
+    // Metadata
+    metadata: t.optional(t.record(t.text(), t.any())),
+  }),
+  indexes: [
+    { columns: ["organizationId"], unique: true },
+    { columns: ["status"] },
+    { columns: ["planId", "status"] },
+    { columns: ["nextBillingAt"] },
+    { columns: ["trialEnd"] },
+    { columns: ["dunningNextRetryAt"] },
+    { columns: ["currentPeriodEnd"] },
+  ],
+});
+
+export type SubscriptionEntity = Static<typeof subscriptions.schema>;

package/src/api/subscriptions/index.ts

@@ -0,0 +1,133 @@
+import { $module } from "alepha";
+import { AdminSubscriptionController } from "./controllers/AdminSubscriptionController.ts";
+import { SubscriptionController } from "./controllers/SubscriptionController.ts";
+import { SubscriptionJobs } from "./jobs/SubscriptionJobs.ts";
+import { SubscriptionNotifications } from "./notifications/SubscriptionNotifications.ts";
+import { BillingService } from "./services/BillingService.ts";
+import { SubscriptionConfig } from "./services/SubscriptionConfig.ts";
+import { SubscriptionService } from "./services/SubscriptionService.ts";
+import { UsageService } from "./services/UsageService.ts";
+
+// Controllers
+export * from "./controllers/AdminSubscriptionController.ts";
+export * from "./controllers/SubscriptionController.ts";
+// Entities
+export * from "./entities/subscriptionEvents.ts";
+export * from "./entities/subscriptions.ts";
+// Jobs
+export * from "./jobs/SubscriptionJobs.ts";
+// Middleware
+export * from "./middleware/$requireLimit.ts";
+export * from "./middleware/$requirePlan.ts";
+// Notifications
+export * from "./notifications/SubscriptionNotifications.ts";
+// Schemas
+export * from "./schemas/cancelSubscriptionSchema.ts";
+export * from "./schemas/changePlanSchema.ts";
+export * from "./schemas/createSubscriptionSchema.ts";
+export * from "./schemas/entitlementsSchema.ts";
+export * from "./schemas/mrrSchema.ts";
+export * from "./schemas/planDefinitionSchema.ts";
+export * from "./schemas/planResourceSchema.ts";
+export * from "./schemas/subscriptionEventResourceSchema.ts";
+export * from "./schemas/subscriptionQuerySchema.ts";
+export * from "./schemas/subscriptionResourceSchema.ts";
+export * from "./schemas/subscriptionSettingsSchema.ts";
+export * from "./schemas/subscriptionStatsSchema.ts";
+// Services
+export * from "./services/BillingService.ts";
+export * from "./services/SubscriptionConfig.ts";
+export * from "./services/SubscriptionService.ts";
+export * from "./services/UsageService.ts";
+
+declare module "alepha" {
+  interface Hooks {
+    "subscription:created": {
+      subscriptionId: string;
+      organizationId: string;
+      planId: string;
+      trial: boolean;
+    };
+    "subscription:activated": {
+      subscriptionId: string;
+      organizationId: string;
+      planId: string;
+    };
+    "subscription:renewed": {
+      subscriptionId: string;
+      organizationId: string;
+      planId: string;
+      amount: number;
+      currency: string;
+    };
+    "subscription:cancelled": {
+      subscriptionId: string;
+      organizationId: string;
+      planId: string;
+      reason?: string;
+      immediate: boolean;
+    };
+    "subscription:expired": {
+      subscriptionId: string;
+      organizationId: string;
+      planId: string;
+    };
+    "subscription:resumed": {
+      subscriptionId: string;
+      organizationId: string;
+      planId: string;
+    };
+    "subscription:plan_changed": {
+      subscriptionId: string;
+      organizationId: string;
+      oldPlanId: string;
+      newPlanId: string;
+      immediate: boolean;
+    };
+    "subscription:payment_failed": {
+      subscriptionId: string;
+      organizationId: string;
+      planId: string;
+      attempt: number;
+    };
+    "subscription:suspended": {
+      subscriptionId: string;
+      organizationId: string;
+      planId: string;
+    };
+    "subscription:reactivated": {
+      subscriptionId: string;
+      organizationId: string;
+      planId: string;
+    };
+    "subscription:trial_ending": {
+      subscriptionId: string;
+      organizationId: string;
+      planId: string;
+      endsAt: string;
+    };
+  }
+}
+
+/**
+ * Subscription management module — plan-based access control, billing integration,
+ * usage limits, and lifecycle events (trial, renewal, cancellation, suspension).
+ *
+ * Depends on `AlephaPayments` for payment processing — register it in your app
+ * alongside this module. Use `SubscriptionConfig` to declare your plans and limits.
+ *
+ * @module alepha.api.subscriptions
+ */
+export const AlephaApiSubscriptions = $module({
+  name: "alepha.api.subscriptions",
+  services: [
+    SubscriptionConfig,
+    SubscriptionService,
+    BillingService,
+    UsageService,
+    SubscriptionJobs,
+    SubscriptionNotifications,
+    SubscriptionController,
+    AdminSubscriptionController,
+  ],
+});