alepha 0.19.3 → 0.19.4

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,144 @@
+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,
+  ],
+  register: (alepha) => {
+    alepha
+      .with(SubscriptionConfig)
+      .with(SubscriptionService)
+      .with(BillingService)
+      .with(UsageService)
+      .with(SubscriptionJobs)
+      .with(SubscriptionNotifications)
+      .with(SubscriptionController)
+      .with(AdminSubscriptionController);
+  },
+});

package/src/api/subscriptions/jobs/SubscriptionJobs.ts

@@ -0,0 +1,382 @@
+import { $inject } from "alepha";
+import { $job } from "alepha/api/jobs";
+import { PaymentService } from "alepha/api/payments";
+import { DateTimeProvider } from "alepha/datetime";
+import { $logger } from "alepha/logger";
+import { $repository } from "alepha/orm";
+import type { SubscriptionEventEntity } from "../entities/subscriptionEvents.ts";
+import { subscriptionEvents } from "../entities/subscriptionEvents.ts";
+import { subscriptions } from "../entities/subscriptions.ts";
+import { SubscriptionConfig } from "../services/SubscriptionConfig.ts";
+
+// -----------------------------------------------------------------------------------------------------------------
+
+interface EventContext {
+  previousStatus?: string;
+  newStatus?: string;
+  paymentIntentId?: string;
+  amount?: number;
+  currency?: string;
+  triggeredBy?: string;
+  note?: string;
+}
+
+// -----------------------------------------------------------------------------------------------------------------
+
+export class SubscriptionJobs {
+  protected readonly log = $logger();
+  protected readonly dateTime = $inject(DateTimeProvider);
+  protected readonly paymentService = $inject(PaymentService);
+  protected readonly config = $inject(SubscriptionConfig);
+  protected readonly subscriptionRepo = $repository(subscriptions);
+  protected readonly eventRepo = $repository(subscriptionEvents);
+
+  // ---------------------------------------------------------------------------------------------------------------
+  // Helpers
+  // ---------------------------------------------------------------------------------------------------------------
+
+  /**
+   * Record a subscription event in the event log.
+   */
+  protected async recordEvent(
+    subscriptionId: string,
+    organizationId: string,
+    type: SubscriptionEventEntity["type"],
+    context?: EventContext,
+  ): Promise<void> {
+    await this.eventRepo.create({
+      subscriptionId,
+      organizationId,
+      type,
+      previousStatus: context?.previousStatus,
+      newStatus: context?.newStatus,
+      paymentIntentId: context?.paymentIntentId,
+      amount: context?.amount,
+      currency: context?.currency,
+      triggeredBy: context?.triggeredBy,
+      note: context?.note,
+    });
+  }
+
+  // ---------------------------------------------------------------------------------------------------------------
+  // Jobs
+  // ---------------------------------------------------------------------------------------------------------------
+
+  /**
+   * Creates payment intents for subscriptions due for renewal.
+   * Runs hourly.
+   */
+  public readonly billingCycle = $job({
+    cron: "0 * * * *",
+    lock: true,
+    timeout: [10, "minute"],
+    handler: async ({ now }) => {
+      const nowISO = now.toISOString();
+
+      const due = await this.subscriptionRepo.findMany({
+        where: {
+          nextBillingAt: { lte: nowISO },
+          status: { inArray: ["active", "trialing"] },
+        },
+      });
+
+      this.log.info(`Billing cycle: processing ${due.length} subscription(s)`);
+
+      for (const sub of due) {
+        try {
+          const pricing = await this.config.getPlanPricing(
+            sub.planId,
+            sub.interval,
+          );
+
+          const intent = await this.paymentService.createIntent(
+            pricing.amount,
+            pricing.currency,
+            { subscriptionId: sub.id },
+          );
+
+          await this.subscriptionRepo.updateById(sub.id, {
+            lastPaymentIntentId: intent.id,
+          });
+
+          this.log.debug("Created payment intent for subscription", {
+            subscriptionId: sub.id,
+            intentId: intent.id,
+          });
+        } catch (err) {
+          this.log.error("Failed to create payment intent for subscription", {
+            subscriptionId: sub.id,
+            error: err,
+          });
+        }
+      }
+    },
+  });
+
+  // ---------------------------------------------------------------------------------------------------------------
+
+  /**
+   * Retries failed payments on the dunning schedule.
+   * Runs hourly.
+   */
+  public readonly dunningRetry = $job({
+    cron: "0 * * * *",
+    lock: true,
+    timeout: [10, "minute"],
+    handler: async ({ now }) => {
+      const nowISO = now.toISOString();
+
+      const pastDue = await this.subscriptionRepo.findMany({
+        where: {
+          dunningNextRetryAt: { lte: nowISO },
+          status: { eq: "past_due" },
+        },
+      });
+
+      this.log.info(
+        `Dunning retry: processing ${pastDue.length} subscription(s)`,
+      );
+
+      const settings = await this.config.getSettings();
+
+      for (const sub of pastDue) {
+        try {
+          const pricing = await this.config.getPlanPricing(
+            sub.planId,
+            sub.interval,
+          );
+
+          const intent = await this.paymentService.createIntent(
+            pricing.amount,
+            pricing.currency,
+            { subscriptionId: sub.id },
+          );
+
+          const newAttempt = sub.dunningAttempt + 1;
+          const scheduleDays = settings.dunningSchedule[newAttempt - 1];
+          const nextRetry =
+            scheduleDays !== undefined
+              ? now.add(scheduleDays, "days").toISOString()
+              : undefined;
+
+          await this.subscriptionRepo.updateById(sub.id, {
+            lastPaymentIntentId: intent.id,
+            dunningAttempt: newAttempt,
+            dunningNextRetryAt: nextRetry,
+          });
+
+          await this.recordEvent(
+            sub.id,
+            sub.organizationId as string,
+            "payment_retried",
+            {
+              paymentIntentId: intent.id,
+              note: `Dunning retry attempt ${newAttempt}`,
+            },
+          );
+
+          this.log.debug("Dunning retry payment intent created", {
+            subscriptionId: sub.id,
+            attempt: newAttempt,
+          });
+        } catch (err) {
+          this.log.error("Failed to create dunning retry intent", {
+            subscriptionId: sub.id,
+            error: err,
+          });
+        }
+      }
+    },
+  });
+
+  // ---------------------------------------------------------------------------------------------------------------
+
+  /**
+   * Handles trial expirations.
+   * Runs hourly.
+   */
+  public readonly trialExpiry = $job({
+    cron: "0 * * * *",
+    lock: true,
+    handler: async ({ now }) => {
+      const nowISO = now.toISOString();
+
+      const expired = await this.subscriptionRepo.findMany({
+        where: {
+          trialEnd: { lte: nowISO },
+          status: { eq: "trialing" },
+        },
+      });
+
+      this.log.info(
+        `Trial expiry: processing ${expired.length} subscription(s)`,
+      );
+
+      for (const sub of expired) {
+        try {
+          const pricing = await this.config.getPlanPricing(
+            sub.planId,
+            sub.interval,
+          );
+
+          const intent = await this.paymentService.createIntent(
+            pricing.amount,
+            pricing.currency,
+            { subscriptionId: sub.id },
+          );
+
+          await this.subscriptionRepo.updateById(sub.id, {
+            lastPaymentIntentId: intent.id,
+          });
+
+          this.log.debug("Created payment intent for trial expiry", {
+            subscriptionId: sub.id,
+            intentId: intent.id,
+          });
+        } catch (err) {
+          this.log.error("Failed to process trial expiry", {
+            subscriptionId: sub.id,
+            error: err,
+          });
+        }
+      }
+    },
+  });
+
+  // ---------------------------------------------------------------------------------------------------------------
+
+  /**
+   * Expires cancelled subscriptions that reached period end.
+   * Runs hourly.
+   */
+  public readonly expirationSweep = $job({
+    cron: "0 * * * *",
+    lock: true,
+    handler: async ({ now }) => {
+      const nowISO = now.toISOString();
+
+      const toExpire = await this.subscriptionRepo.findMany({
+        where: {
+          currentPeriodEnd: { lte: nowISO },
+          status: { eq: "cancelled" },
+          cancelAtPeriodEnd: { eq: true },
+        },
+      });
+
+      this.log.info(
+        `Expiration sweep: expiring ${toExpire.length} subscription(s)`,
+      );
+
+      for (const sub of toExpire) {
+        try {
+          await this.subscriptionRepo.updateById(sub.id, {
+            status: "expired",
+          });
+
+          await this.recordEvent(
+            sub.id,
+            sub.organizationId as string,
+            "expired",
+            {
+              previousStatus: "cancelled",
+              newStatus: "expired",
+            },
+          );
+
+          this.log.debug("Subscription expired", { subscriptionId: sub.id });
+        } catch (err) {
+          this.log.error("Failed to expire subscription", {
+            subscriptionId: sub.id,
+            error: err,
+          });
+        }
+      }
+    },
+  });
+
+  // ---------------------------------------------------------------------------------------------------------------
+
+  /**
+   * Suspends past_due subscriptions where grace period has elapsed.
+   * Runs daily at 2 AM.
+   */
+  public readonly gracePeriodSweep = $job({
+    cron: "0 2 * * *",
+    lock: true,
+    handler: async ({ now }) => {
+      const settings = await this.config.getSettings();
+      const gracePeriodDays = settings.gracePeriodDays;
+
+      const pastDueSubs = await this.subscriptionRepo.findMany({
+        where: {
+          status: { eq: "past_due" },
+        },
+      });
+
+      const toSuspend = pastDueSubs.filter((sub) => {
+        if (!sub.dunningStartedAt) return false;
+        const graceEnd = this.dateTime
+          .of(sub.dunningStartedAt)
+          .add(gracePeriodDays, "days");
+        return !now.isBefore(graceEnd.toISOString());
+      });
+
+      this.log.info(
+        `Grace period sweep: suspending ${toSuspend.length} subscription(s)`,
+      );
+
+      for (const sub of toSuspend) {
+        try {
+          await this.subscriptionRepo.updateById(sub.id, {
+            status: "suspended",
+          });
+
+          await this.recordEvent(
+            sub.id,
+            sub.organizationId as string,
+            "suspended",
+            {
+              previousStatus: "past_due",
+              newStatus: "suspended",
+            },
+          );
+
+          this.log.debug("Subscription suspended after grace period", {
+            subscriptionId: sub.id,
+          });
+        } catch (err) {
+          this.log.error("Failed to suspend subscription", {
+            subscriptionId: sub.id,
+            error: err,
+          });
+        }
+      }
+    },
+  });
+
+  // ---------------------------------------------------------------------------------------------------------------
+
+  /**
+   * Purges old subscription events older than 365 days.
+   * Runs daily at 3 AM.
+   */
+  public readonly purgeEvents = $job({
+    cron: "0 3 * * *",
+    lock: true,
+    handler: async ({ now }) => {
+      const cutoff = now.subtract(365, "days").toISOString();
+
+      const old = await this.eventRepo.findMany({
+        where: {
+          createdAt: { lt: cutoff },
+        },
+      });
+
+      this.log.info(`Purge events: removing ${old.length} old event(s)`);
+
+      for (const event of old) {
+        await this.eventRepo.deleteById(event.id);
+      }
+    },
+  });
+}

package/src/api/subscriptions/middleware/$requireLimit.ts

@@ -0,0 +1,50 @@
+import { $context, createMiddleware, type Middleware } from "alepha";
+import { ForbiddenError } from "alepha/server";
+import { UsageService } from "../services/UsageService.ts";
+
+/**
+ * Middleware that enforces a per-organization usage limit for a resource.
+ *
+ * Resolves the organization from `args[0].user.organization`, increments the
+ * usage counter for the given resource, and throws `ForbiddenError` if the
+ * plan limit has been reached.
+ * Throws `ForbiddenError` if no organization is present or the limit is exceeded.
+ *
+ * ```typescript
+ * class ApiController {
+ *   search = $action({
+ *     use: [$requireLimit("api_calls")],
+ *     handler: async ({ query }) => { ... },
+ *   });
+ * }
+ * ```
+ *
+ * @param resource The resource identifier to track (e.g., "api_calls", "exports").
+ */
+export const $requireLimit = (resource: string): Middleware => {
+  const { alepha } = $context();
+  const usageService = alepha.inject(UsageService);
+
+  return createMiddleware({
+    name: "$requireLimit",
+    options: { resource } as Record<string, unknown>,
+    handler: ({ next }) => {
+      return async (...args: any[]) => {
+        const user = args[0]?.user;
+        if (!user?.organization) {
+          throw new ForbiddenError("Organization required");
+        }
+        const result = await usageService.increment(
+          user.organization,
+          resource,
+        );
+        if (!result.allowed) {
+          throw new ForbiddenError(
+            `Usage limit for '${resource}' has been reached (${result.current}/${result.limit})`,
+          );
+        }
+        return next(...args);
+      };
+    },
+  });
+};