alepha 0.20.6 → 0.20.8

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

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

@@ -0,0 +1,49 @@
+import { $context, createMiddleware, type Middleware } from "alepha";
+import { ForbiddenError } from "alepha/server";
+import { SubscriptionService } from "../services/SubscriptionService.ts";
+
+/**
+ * Middleware that gates access to a handler behind a subscription feature flag.
+ *
+ * Resolves the organization from `args[0].user.organization` and checks whether
+ * the organization's current plan includes the given feature.
+ * Throws `ForbiddenError` if no organization is present or the feature is not available.
+ *
+ * ```typescript
+ * class ReportController {
+ *   generate = $action({
+ *     use: [$requirePlan("advanced_reports")],
+ *     handler: async ({ user }) => { ... },
+ *   });
+ * }
+ * ```
+ *
+ * @param feature The feature identifier to check against the plan's feature list.
+ */
+export const $requirePlan = (feature: string): Middleware => {
+  const { alepha } = $context();
+  const subscriptionService = alepha.inject(SubscriptionService);
+
+  return createMiddleware({
+    name: "$requirePlan",
+    options: { feature } as Record<string, unknown>,
+    handler: ({ next }) => {
+      return async (...args: any[]) => {
+        const user = args[0]?.user;
+        if (!user?.organization) {
+          throw new ForbiddenError("Organization required");
+        }
+        const allowed = await subscriptionService.can(
+          user.organization,
+          feature,
+        );
+        if (!allowed) {
+          throw new ForbiddenError(
+            `Feature '${feature}' not available on your plan`,
+          );
+        }
+        return next(...args);
+      };
+    },
+  });
+};

package/src/api/subscriptions/notifications/SubscriptionNotifications.ts

@@ -0,0 +1,110 @@
+import { t } from "alepha";
+import { $notification } from "alepha/api/notifications";
+
+export class SubscriptionNotifications {
+  /**
+   * Sent when a trial is ending soon.
+   */
+  protected readonly trialEnding = $notification({
+    name: "subscription-trial-ending",
+    category: "subscriptions",
+    schema: t.object({
+      planName: t.text(),
+      trialEndDate: t.text(),
+      amount: t.text(),
+      interval: t.text(),
+    }),
+    email: {
+      subject: "Your trial is ending soon",
+      body: (v) =>
+        `Your ${v.planName} trial is ending on ${v.trialEndDate}. You'll be charged ${v.amount}/${v.interval}.`,
+    },
+  });
+
+  /**
+   * Sent when a payment fails. Critical notification.
+   */
+  protected readonly paymentFailed = $notification({
+    name: "subscription-payment-failed",
+    category: "subscriptions",
+    critical: true,
+    schema: t.object({
+      planName: t.text(),
+      amount: t.text(),
+      retryDate: t.optional(t.text()),
+    }),
+    email: {
+      subject: "Payment failed for your subscription",
+      body: (v) =>
+        `We couldn't charge your card for ${v.planName} (${v.amount}). ${v.retryDate ? `We'll retry on ${v.retryDate}.` : "Please update your payment method."}`,
+    },
+  });
+
+  /**
+   * Sent when a subscription is suspended due to failed payments. Critical notification.
+   */
+  protected readonly subscriptionSuspended = $notification({
+    name: "subscription-suspended",
+    category: "subscriptions",
+    critical: true,
+    schema: t.object({ planName: t.text() }),
+    email: {
+      subject: "Your subscription has been suspended",
+      body: (v) =>
+        `Your ${v.planName} subscription has been suspended due to failed payments. Update your payment method to reactivate.`,
+    },
+  });
+
+  /**
+   * Sent when a subscription is successfully renewed.
+   */
+  protected readonly subscriptionRenewed = $notification({
+    name: "subscription-renewed",
+    category: "subscriptions",
+    schema: t.object({
+      planName: t.text(),
+      amount: t.text(),
+      nextBillingDate: t.text(),
+    }),
+    email: {
+      subject: "Payment received — subscription renewed",
+      body: (v) =>
+        `Your ${v.planName} subscription has been renewed. Amount: ${v.amount}. Next billing: ${v.nextBillingDate}.`,
+    },
+  });
+
+  /**
+   * Sent when a subscription plan is changed.
+   */
+  protected readonly planChanged = $notification({
+    name: "subscription-plan-changed",
+    category: "subscriptions",
+    schema: t.object({
+      oldPlanName: t.text(),
+      newPlanName: t.text(),
+      effectiveDate: t.text(),
+    }),
+    email: {
+      subject: "Your subscription plan has been changed",
+      body: (v) =>
+        `Your plan has been changed from ${v.oldPlanName} to ${v.newPlanName}, effective ${v.effectiveDate}.`,
+    },
+  });
+
+  /**
+   * Sent when a subscription is cancelled.
+   */
+  protected readonly cancellationConfirmed = $notification({
+    name: "subscription-cancelled",
+    category: "subscriptions",
+    schema: t.object({
+      planName: t.text(),
+      accessUntil: t.optional(t.text()),
+    }),
+    email: {
+      subject: "Your subscription has been cancelled",
+      body: (v) =>
+        `Your ${v.planName} subscription has been cancelled.${v.accessUntil ? ` You'll have access until ${v.accessUntil}.` : ""}`,
+    },
+  });
+}

package/src/api/subscriptions/schemas/cancelSubscriptionSchema.ts

@@ -0,0 +1,8 @@
+import { type Static, t } from "alepha";
+
+export const cancelSubscriptionSchema = t.object({
+  reason: t.optional(t.string()),
+  immediate: t.optional(t.boolean()),
+});
+
+export type CancelSubscription = Static<typeof cancelSubscriptionSchema>;

package/src/api/subscriptions/schemas/changePlanSchema.ts

@@ -0,0 +1,9 @@
+import { type Static, t } from "alepha";
+
+export const changePlanSchema = t.object({
+  planId: t.string(),
+  interval: t.optional(t.enum(["monthly", "yearly"])),
+  immediate: t.optional(t.boolean()),
+});
+
+export type ChangePlan = Static<typeof changePlanSchema>;

package/src/api/subscriptions/schemas/createSubscriptionSchema.ts

@@ -0,0 +1,11 @@
+import { type Static, t } from "alepha";
+
+export const createSubscriptionSchema = t.object({
+  planId: t.string(),
+  interval: t.enum(["monthly", "yearly"]),
+  paymentMethodId: t.optional(t.uuid()),
+  skipTrial: t.optional(t.boolean()),
+  metadata: t.optional(t.record(t.text(), t.any())),
+});
+
+export type CreateSubscription = Static<typeof createSubscriptionSchema>;

package/src/api/subscriptions/schemas/entitlementsSchema.ts

@@ -0,0 +1,21 @@
+import { type Static, t } from "alepha";
+
+export const entitlementsSchema = t.object({
+  planId: t.string(),
+  planName: t.string(),
+  status: t.enum([
+    "trialing",
+    "active",
+    "past_due",
+    "suspended",
+    "cancelled",
+    "expired",
+  ]),
+  features: t.array(t.string()),
+  limits: t.record(t.text(), t.integer()),
+  trialEndsAt: t.optional(t.datetime()),
+  periodEndsAt: t.datetime(),
+  cancelledAt: t.optional(t.datetime()),
+});
+
+export type Entitlements = Static<typeof entitlementsSchema>;

package/src/api/subscriptions/schemas/mrrSchema.ts

@@ -0,0 +1,13 @@
+import { type Static, t } from "alepha";
+
+export const mrrSchema = t.object({
+  total: t.integer(),
+  byPlan: t.record(t.text(), t.integer()),
+  growth: t.integer(),
+  newMrr: t.integer(),
+  expansionMrr: t.integer(),
+  contractionMrr: t.integer(),
+  churnMrr: t.integer(),
+});
+
+export type MrrData = Static<typeof mrrSchema>;