alepha 0.19.3 → 0.19.4

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>;

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

@@ -0,0 +1,71 @@
+import { type Static, t } from "alepha";
+
+export const planDefinitionSchema = t.object({
+  /**
+   * Unique plan identifier (e.g., "free", "starter", "pro", "enterprise").
+   */
+  id: t.string({ minLength: 1, maxLength: 50 }),
+
+  /**
+   * Display name (e.g., "Pro Plan").
+   */
+  name: t.string(),
+
+  /**
+   * Optional description.
+   */
+  description: t.optional(t.string()),
+
+  /**
+   * Whether this plan is available for new subscriptions.
+   */
+  available: t.boolean({ default: true }),
+
+  /**
+   * Pricing per billing interval.
+   * Multiple entries for monthly/yearly.
+   */
+  pricing: t.array(
+    t.object({
+      interval: t.enum(["monthly", "yearly"]),
+      amount: t.integer({ minimum: 0 }),
+      currency: t.string({ minLength: 3, maxLength: 3 }),
+    }),
+  ),
+
+  /**
+   * Trial configuration for this plan.
+   * Overrides global settings.trialDays if set.
+   */
+  trial: t.optional(
+    t.object({
+      days: t.integer({ minimum: 0, maximum: 365 }),
+      requirePaymentMethod: t.boolean({ default: false }),
+    }),
+  ),
+
+  /**
+   * Feature entitlements. Boolean flags for feature access.
+   * Checked via SubscriptionService.can("feature-name").
+   */
+  features: t.array(t.string()),
+
+  /**
+   * Usage limits. Numeric caps on resources.
+   * Checked via SubscriptionService.limit("resource-name").
+   * -1 = unlimited.
+   */
+  limits: t.record(t.text(), t.integer()),
+
+  /**
+   * Sort order for display (lower = first).
+   */
+  order: t.integer({ default: 0 }),
+
+  /**
+   * Metadata for app-specific plan data.
+   */
+  metadata: t.optional(t.record(t.text(), t.any())),
+});
+
+export type PlanDefinition = Static<typeof planDefinitionSchema>;

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

@@ -0,0 +1,25 @@
+import { type Static, t } from "alepha";
+
+export const planResourceSchema = t.object({
+  id: t.string(),
+  name: t.string(),
+  description: t.optional(t.string()),
+  pricing: t.array(
+    t.object({
+      interval: t.enum(["monthly", "yearly"]),
+      amount: t.integer(),
+      currency: t.string(),
+    }),
+  ),
+  features: t.array(t.string()),
+  limits: t.record(t.text(), t.integer()),
+  trial: t.optional(
+    t.object({
+      days: t.integer(),
+      requirePaymentMethod: t.boolean(),
+    }),
+  ),
+  order: t.integer(),
+});
+
+export type PlanResource = Static<typeof planResourceSchema>;

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

@@ -0,0 +1,8 @@
+import type { Static } from "alepha";
+import { subscriptionEvents } from "../entities/subscriptionEvents.ts";
+
+export const subscriptionEventResourceSchema = subscriptionEvents.schema;
+
+export type SubscriptionEventResource = Static<
+  typeof subscriptionEventResourceSchema
+>;

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

@@ -0,0 +1,19 @@
+import { type Static, t } from "alepha";
+import { pageQuerySchema } from "alepha/orm";
+
+export const subscriptionQuerySchema = t.extend(pageQuerySchema, {
+  status: t.optional(
+    t.enum([
+      "trialing",
+      "active",
+      "past_due",
+      "suspended",
+      "cancelled",
+      "expired",
+    ]),
+  ),
+  planId: t.optional(t.string()),
+  organizationId: t.optional(t.uuid()),
+});
+
+export type SubscriptionQuery = Static<typeof subscriptionQuerySchema>;

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

@@ -0,0 +1,6 @@
+import type { Static } from "alepha";
+import { subscriptions } from "../entities/subscriptions.ts";
+
+export const subscriptionResourceSchema = subscriptions.schema;
+
+export type SubscriptionResource = Static<typeof subscriptionResourceSchema>;

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

@@ -0,0 +1,32 @@
+import { type Static, t } from "alepha";
+
+export const subscriptionSettingsSchema = t.object({
+  /**
+   * Default trial days (overridden per-plan if plan.trial.days is set).
+   */
+  trialDays: t.integer({ default: 14, minimum: 0, maximum: 365 }),
+
+  /**
+   * Days after payment failure before suspension.
+   * During grace period, subscription remains active but flagged.
+   */
+  gracePeriodDays: t.integer({ default: 7, minimum: 0, maximum: 30 }),
+
+  /**
+   * Days after first payment failure to retry, relative to the failure date.
+   * e.g., [1, 3, 5, 7] means retry on day 1, 3, 5, 7 after failure.
+   */
+  dunningSchedule: t.array(t.integer({ minimum: 1 })),
+
+  /**
+   * When user cancels, wait until period end (true) or cancel immediately (false).
+   */
+  cancelAtPeriodEnd: t.boolean({ default: true }),
+
+  /**
+   * Prorate charges when changing plans mid-cycle.
+   */
+  prorateOnChange: t.boolean({ default: true }),
+});
+
+export type SubscriptionSettings = Static<typeof subscriptionSettingsSchema>;

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

@@ -0,0 +1,23 @@
+import { type Static, t } from "alepha";
+
+export const subscriptionStatsSchema = t.object({
+  total: t.integer(),
+  trialing: t.integer(),
+  active: t.integer(),
+  pastDue: t.integer(),
+  suspended: t.integer(),
+  cancelled: t.integer(),
+  expired: t.integer(),
+  trialConversionRate: t.number(),
+  churnRate: t.number(),
+  byPlan: t.record(
+    t.text(),
+    t.object({
+      active: t.integer(),
+      trialing: t.integer(),
+      total: t.integer(),
+    }),
+  ),
+});
+
+export type SubscriptionStats = Static<typeof subscriptionStatsSchema>;