alepha 0.20.5 → 0.20.7

package/src/api/subscriptions/services/SubscriptionService.ts

@@ -0,0 +1,867 @@
+import { $inject, Alepha } from "alepha";
+import { DateTimeProvider } from "alepha/datetime";
+import { $logger } from "alepha/logger";
+import { $repository, type Page } from "alepha/orm";
+import { BadRequestError, NotFoundError } from "alepha/server";
+import {
+  type SubscriptionEventEntity,
+  subscriptionEvents,
+} from "../entities/subscriptionEvents.ts";
+import {
+  type SubscriptionEntity,
+  subscriptions,
+} from "../entities/subscriptions.ts";
+import type { Entitlements } from "../schemas/entitlementsSchema.ts";
+import type { SubscriptionQuery } from "../schemas/subscriptionQuerySchema.ts";
+import type { SubscriptionStats } from "../schemas/subscriptionStatsSchema.ts";
+import { SubscriptionConfig } from "./SubscriptionConfig.ts";
+
+// -----------------------------------------------------------------------------------------------------------------
+
+interface SubscribeOptions {
+  /**
+   * Override plan/global trial days.
+   */
+  trialDays?: number;
+
+  /**
+   * Go straight to active (requires payment).
+   */
+  skipTrial?: boolean;
+
+  /**
+   * Metadata to attach to the subscription.
+   */
+  metadata?: Record<string, unknown>;
+}
+
+// -----------------------------------------------------------------------------------------------------------------
+
+interface CancelOptions {
+  /**
+   * Cancellation reason.
+   */
+  reason?: string;
+
+  /**
+   * Cancel immediately instead of at period end.
+   */
+  immediate?: boolean;
+
+  /**
+   * User who initiated the cancellation.
+   */
+  cancelledBy?: string;
+}
+
+// -----------------------------------------------------------------------------------------------------------------
+
+interface ChangePlanOptions {
+  /**
+   * Apply now (with proration) or at period end.
+   */
+  immediate?: boolean;
+
+  /**
+   * Override settings.prorateOnChange.
+   */
+  prorate?: boolean;
+}
+
+// -----------------------------------------------------------------------------------------------------------------
+
+interface EventContext {
+  previousStatus?: string;
+  newStatus?: string;
+  previousPlanId?: string;
+  newPlanId?: string;
+  paymentIntentId?: string;
+  amount?: number;
+  currency?: string;
+  triggeredBy?: string;
+  userId?: string;
+  note?: string;
+}
+
+// -----------------------------------------------------------------------------------------------------------------
+
+export class SubscriptionService {
+  protected readonly alepha = $inject(Alepha);
+  protected readonly log = $logger();
+  protected readonly dateTime = $inject(DateTimeProvider);
+  protected readonly subscriptionRepo = $repository(subscriptions);
+  protected readonly eventRepo = $repository(subscriptionEvents);
+  protected readonly config = $inject(SubscriptionConfig);
+
+  // ---------------------------------------------------------------------------------------------------------------
+  // Helpers
+  // ---------------------------------------------------------------------------------------------------------------
+
+  /**
+   * Find a subscription by organization ID.
+   * Returns null if no subscription exists.
+   */
+  public async getByOrganization(
+    organizationId: string,
+  ): Promise<SubscriptionEntity | null> {
+    const result = await this.subscriptionRepo.findOne({
+      where: { organizationId: { eq: organizationId } },
+    });
+    return result ?? null;
+  }
+
+  /**
+   * Get a subscription by ID. Throws NotFoundError if not found.
+   */
+  public async getSubscription(id: string): Promise<SubscriptionEntity> {
+    return this.subscriptionRepo.getById(id);
+  }
+
+  /**
+   * Returns true if the subscription currently grants access.
+   * Accessible statuses: trialing, active, past_due (grace period),
+   * or cancelled with cancelAtPeriodEnd before period end.
+   */
+  public isAccessible(sub: SubscriptionEntity): boolean {
+    if (
+      sub.status === "trialing" ||
+      sub.status === "active" ||
+      sub.status === "past_due"
+    ) {
+      return true;
+    }
+
+    if (
+      sub.status === "cancelled" &&
+      sub.cancelAtPeriodEnd &&
+      this.dateTime.now().isBefore(sub.currentPeriodEnd)
+    ) {
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Record a subscription event in the event log.
+   */
+  public 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,
+      previousPlanId: context?.previousPlanId,
+      newPlanId: context?.newPlanId,
+      paymentIntentId: context?.paymentIntentId,
+      amount: context?.amount,
+      currency: context?.currency,
+      triggeredBy: context?.triggeredBy,
+      userId: context?.userId,
+      note: context?.note,
+    });
+  }
+
+  /**
+   * Compute the end of a billing interval from a start date.
+   */
+  public computeIntervalEnd(
+    start: string,
+    interval: "monthly" | "yearly",
+  ): string {
+    const startDate = this.dateTime.of(start);
+    const unit = interval === "monthly" ? "months" : "years";
+    return startDate.add(1, unit).toISOString();
+  }
+
+  // ---------------------------------------------------------------------------------------------------------------
+  // Lifecycle
+  // ---------------------------------------------------------------------------------------------------------------
+
+  /**
+   * Create a new subscription for an organization.
+   */
+  public async subscribe(
+    organizationId: string,
+    planId: string,
+    interval: "monthly" | "yearly",
+    options?: SubscribeOptions,
+  ): Promise<SubscriptionEntity> {
+    const plan = await this.config.getPlan(planId);
+
+    if (!plan.available) {
+      throw new BadRequestError(
+        `Plan '${planId}' is not available for new subscriptions`,
+      );
+    }
+
+    await this.config.getPlanPricing(planId, interval);
+
+    const existing = await this.subscriptionRepo.findOne({
+      where: {
+        organizationId: { eq: organizationId },
+        status: { inArray: ["trialing", "active", "past_due"] },
+      },
+    });
+
+    if (existing) {
+      throw new BadRequestError(
+        "Organization already has an active subscription",
+      );
+    }
+
+    const settings = await this.config.getSettings();
+    const trialDays =
+      options?.trialDays ?? plan.trial?.days ?? settings.trialDays;
+    const skipTrial = options?.skipTrial ?? false;
+    const now = this.dateTime.now();
+    const nowISO = now.toISOString();
+
+    if (trialDays > 0 && !skipTrial) {
+      const trialEnd = now.add(trialDays, "days").toISOString();
+
+      const entity = await this.subscriptionRepo.create({
+        organizationId,
+        planId,
+        interval,
+        status: "trialing",
+        currentPeriodStart: nowISO,
+        currentPeriodEnd: trialEnd,
+        trialStart: nowISO,
+        trialEnd,
+        nextBillingAt: trialEnd,
+        cancelAtPeriodEnd: false,
+        dunningAttempt: 0,
+        metadata: options?.metadata as any,
+      });
+
+      await this.recordEvent(entity.id, organizationId, "created", {
+        newStatus: "trialing",
+      });
+
+      await this.recordEvent(entity.id, organizationId, "trial_started", {
+        newStatus: "trialing",
+      });
+
+      this.log.info("Subscription created with trial", {
+        id: entity.id,
+        organizationId,
+        planId,
+        trialDays,
+      });
+
+      await this.alepha.events.emit("subscription:created" as any, {
+        subscription: entity,
+      });
+
+      return entity;
+    }
+
+    const periodEnd = this.computeIntervalEnd(nowISO, interval);
+
+    const entity = await this.subscriptionRepo.create({
+      organizationId,
+      planId,
+      interval,
+      status: "active",
+      currentPeriodStart: nowISO,
+      currentPeriodEnd: periodEnd,
+      nextBillingAt: periodEnd,
+      cancelAtPeriodEnd: false,
+      dunningAttempt: 0,
+      metadata: options?.metadata as any,
+    });
+
+    await this.recordEvent(entity.id, organizationId, "created", {
+      newStatus: "active",
+    });
+
+    this.log.info("Subscription created", {
+      id: entity.id,
+      organizationId,
+      planId,
+    });
+
+    await this.alepha.events.emit("subscription:created" as any, {
+      subscription: entity,
+    });
+
+    return entity;
+  }
+
+  // ---------------------------------------------------------------------------------------------------------------
+
+  /**
+   * Cancel a subscription.
+   * If immediate, the subscription expires right away.
+   * If at period end, the subscription remains accessible until the period ends.
+   */
+  public async cancel(
+    subscriptionId: string,
+    options?: CancelOptions,
+  ): Promise<void> {
+    const sub = await this.subscriptionRepo.getById(subscriptionId);
+    const orgId = sub.organizationId as string;
+
+    if (
+      sub.status !== "trialing" &&
+      sub.status !== "active" &&
+      sub.status !== "past_due"
+    ) {
+      throw new BadRequestError(
+        `Cannot cancel subscription with status '${sub.status}'`,
+      );
+    }
+
+    const settings = await this.config.getSettings();
+    const immediate = options?.immediate ?? !settings.cancelAtPeriodEnd;
+    const now = this.dateTime.now();
+    const nowISO = now.toISOString();
+    const previousStatus = sub.status;
+
+    if (immediate) {
+      await this.subscriptionRepo.updateById(subscriptionId, {
+        status: "expired",
+        cancelledAt: nowISO,
+        cancelReason: options?.reason,
+        cancelAtPeriodEnd: false,
+      });
+
+      await this.recordEvent(subscriptionId, orgId, "cancelled", {
+        previousStatus,
+        newStatus: "expired",
+        triggeredBy: options?.cancelledBy ? "user" : "system",
+        userId: options?.cancelledBy,
+        note: options?.reason,
+      });
+
+      this.log.info("Subscription cancelled immediately", {
+        id: subscriptionId,
+        organizationId: orgId,
+      });
+    } else {
+      await this.subscriptionRepo.updateById(subscriptionId, {
+        status: "cancelled",
+        cancelledAt: nowISO,
+        cancelReason: options?.reason,
+        cancelAtPeriodEnd: true,
+      });
+
+      await this.recordEvent(subscriptionId, orgId, "cancelled", {
+        previousStatus,
+        newStatus: "cancelled",
+        triggeredBy: options?.cancelledBy ? "user" : "system",
+        userId: options?.cancelledBy,
+        note: options?.reason,
+      });
+
+      this.log.info("Subscription cancelled at period end", {
+        id: subscriptionId,
+        organizationId: orgId,
+        periodEnd: sub.currentPeriodEnd,
+      });
+    }
+
+    await this.alepha.events.emit("subscription:cancelled" as any, {
+      subscription: sub,
+      immediate,
+      reason: options?.reason,
+    });
+  }
+
+  // ---------------------------------------------------------------------------------------------------------------
+
+  /**
+   * Resume a cancelled subscription before its period ends.
+   * Only valid for subscriptions cancelled with cancelAtPeriodEnd.
+   */
+  public async resume(subscriptionId: string): Promise<void> {
+    const sub = await this.subscriptionRepo.getById(subscriptionId);
+    const orgId = sub.organizationId as string;
+
+    if (sub.status !== "cancelled") {
+      throw new BadRequestError(
+        `Cannot resume subscription with status '${sub.status}', must be 'cancelled'`,
+      );
+    }
+
+    if (!sub.cancelAtPeriodEnd) {
+      throw new BadRequestError(
+        "Cannot resume a subscription that was not cancelled at period end",
+      );
+    }
+
+    if (!this.dateTime.now().isBefore(sub.currentPeriodEnd)) {
+      throw new BadRequestError(
+        "Cannot resume subscription, period has already ended",
+      );
+    }
+
+    await this.subscriptionRepo.updateById(subscriptionId, {
+      status: "active",
+      cancelledAt: undefined,
+      cancelReason: undefined,
+      cancelAtPeriodEnd: false,
+    });
+
+    await this.recordEvent(subscriptionId, orgId, "resumed", {
+      previousStatus: "cancelled",
+      newStatus: "active",
+    });
+
+    this.log.info("Subscription resumed", {
+      id: subscriptionId,
+      organizationId: orgId,
+    });
+
+    await this.alepha.events.emit("subscription:resumed" as any, {
+      subscription: sub,
+    });
+  }
+
+  // ---------------------------------------------------------------------------------------------------------------
+
+  /**
+   * Change the plan of a subscription.
+   * If immediate, proration is calculated and the plan changes now.
+   * If at period end, the change is scheduled for the next renewal.
+   * Returns the net proration amount (positive = charge, negative = credit).
+   */
+  public async changePlan(
+    subscriptionId: string,
+    newPlanId: string,
+    newInterval?: "monthly" | "yearly",
+    options?: ChangePlanOptions,
+  ): Promise<number> {
+    const sub = await this.subscriptionRepo.getById(subscriptionId);
+    const orgId = sub.organizationId as string;
+
+    if (sub.status !== "active" && sub.status !== "trialing") {
+      throw new BadRequestError(
+        `Cannot change plan for subscription with status '${sub.status}'`,
+      );
+    }
+
+    const newPlan = await this.config.getPlan(newPlanId);
+
+    if (!newPlan.available) {
+      throw new BadRequestError(
+        `Plan '${newPlanId}' is not available for new subscriptions`,
+      );
+    }
+
+    const effectiveInterval = newInterval ?? sub.interval;
+    await this.config.getPlanPricing(newPlanId, effectiveInterval);
+
+    const settings = await this.config.getSettings();
+    const immediate = options?.immediate ?? true;
+
+    if (!immediate) {
+      await this.subscriptionRepo.updateById(subscriptionId, {
+        pendingPlanId: newPlanId,
+        pendingInterval: effectiveInterval,
+      });
+
+      await this.recordEvent(subscriptionId, orgId, "plan_change_scheduled", {
+        previousPlanId: sub.planId,
+        newPlanId,
+        note: `Scheduled change to '${newPlanId}' (${effectiveInterval}) at period end`,
+      });
+
+      this.log.info("Plan change scheduled for period end", {
+        id: subscriptionId,
+        organizationId: orgId,
+        newPlanId,
+        newInterval: effectiveInterval,
+      });
+
+      await this.alepha.events.emit("subscription:plan_changed" as any, {
+        subscription: sub,
+        previousPlanId: sub.planId,
+        newPlanId,
+        immediate: false,
+      });
+
+      return 0;
+    }
+
+    const shouldProrate = options?.prorate ?? settings.prorateOnChange;
+    let netAmount = 0;
+
+    if (shouldProrate && sub.status === "active") {
+      netAmount = await this.calculateProration(
+        sub,
+        newPlanId,
+        effectiveInterval,
+      );
+    }
+
+    const previousPlanId = sub.planId;
+
+    await this.subscriptionRepo.updateById(subscriptionId, {
+      planId: newPlanId,
+      interval: effectiveInterval,
+      pendingPlanId: undefined,
+      pendingInterval: undefined,
+      metadata:
+        netAmount < 0
+          ? { ...sub.metadata, credit: Math.abs(netAmount) }
+          : sub.metadata,
+    });
+
+    await this.recordEvent(subscriptionId, orgId, "plan_changed", {
+      previousPlanId,
+      newPlanId,
+      amount: netAmount !== 0 ? Math.abs(netAmount) : undefined,
+      note:
+        netAmount > 0
+          ? `Proration charge: ${netAmount}`
+          : netAmount < 0
+            ? `Proration credit: ${Math.abs(netAmount)}`
+            : undefined,
+    });
+
+    this.log.info("Plan changed immediately", {
+      id: subscriptionId,
+      organizationId: orgId,
+      previousPlanId,
+      newPlanId,
+      netAmount,
+    });
+
+    await this.alepha.events.emit("subscription:plan_changed" as any, {
+      subscription: sub,
+      previousPlanId,
+      newPlanId,
+      immediate: true,
+      netAmount,
+    });
+
+    return netAmount;
+  }
+
+  // ---------------------------------------------------------------------------------------------------------------
+
+  /**
+   * Reactivate a suspended subscription (admin action).
+   * Resets dunning state and starts a new billing period.
+   */
+  public async reactivate(subscriptionId: string): Promise<void> {
+    const sub = await this.subscriptionRepo.getById(subscriptionId);
+    const orgId = sub.organizationId as string;
+
+    if (sub.status !== "suspended") {
+      throw new BadRequestError(
+        `Cannot reactivate subscription with status '${sub.status}', must be 'suspended'`,
+      );
+    }
+
+    const now = this.dateTime.now();
+    const nowISO = now.toISOString();
+    const periodEnd = this.computeIntervalEnd(nowISO, sub.interval);
+
+    await this.subscriptionRepo.updateById(subscriptionId, {
+      status: "active",
+      currentPeriodStart: nowISO,
+      currentPeriodEnd: periodEnd,
+      nextBillingAt: periodEnd,
+      dunningStartedAt: undefined,
+      dunningAttempt: 0,
+      dunningNextRetryAt: undefined,
+    });
+
+    await this.recordEvent(subscriptionId, orgId, "reactivated", {
+      previousStatus: "suspended",
+      newStatus: "active",
+    });
+
+    this.log.info("Subscription reactivated", {
+      id: subscriptionId,
+      organizationId: orgId,
+    });
+
+    await this.alepha.events.emit("subscription:reactivated" as any, {
+      subscription: sub,
+    });
+  }
+
+  // ---------------------------------------------------------------------------------------------------------------
+
+  /**
+   * Extend the trial period of a trialing subscription.
+   */
+  public async extendTrial(
+    subscriptionId: string,
+    days: number,
+  ): Promise<void> {
+    const sub = await this.subscriptionRepo.getById(subscriptionId);
+
+    if (sub.status !== "trialing") {
+      throw new BadRequestError(
+        `Cannot extend trial for subscription with status '${sub.status}', must be 'trialing'`,
+      );
+    }
+
+    if (!sub.trialEnd) {
+      throw new BadRequestError("Subscription has no trial end date set");
+    }
+
+    const currentTrialEnd = this.dateTime.of(sub.trialEnd);
+    const newTrialEnd = currentTrialEnd.add(days, "days").toISOString();
+
+    await this.subscriptionRepo.updateById(subscriptionId, {
+      trialEnd: newTrialEnd,
+      currentPeriodEnd: newTrialEnd,
+      nextBillingAt: newTrialEnd,
+    });
+
+    this.log.info("Trial extended", {
+      id: subscriptionId,
+      organizationId: sub.organizationId as string,
+      days,
+      newTrialEnd,
+    });
+  }
+
+  // ---------------------------------------------------------------------------------------------------------------
+  // Entitlements
+  // ---------------------------------------------------------------------------------------------------------------
+
+  /**
+   * Check if an organization has access to a specific feature.
+   */
+  public async can(organizationId: string, feature: string): Promise<boolean> {
+    const sub = await this.getByOrganization(organizationId);
+    if (!sub || !this.isAccessible(sub)) return false;
+    const plan = await this.config.getPlan(sub.planId);
+    return plan.features.includes(feature);
+  }
+
+  /**
+   * Get the usage limit for a resource.
+   * Returns -1 for unlimited, 0 for no access.
+   */
+  public async limit(
+    organizationId: string,
+    resource: string,
+  ): Promise<number> {
+    const sub = await this.getByOrganization(organizationId);
+    if (!sub || !this.isAccessible(sub)) return 0;
+    const plan = await this.config.getPlan(sub.planId);
+    return plan.limits[resource] ?? 0;
+  }
+
+  /**
+   * Get the full entitlements snapshot for an organization.
+   */
+  public async getEntitlements(organizationId: string): Promise<Entitlements> {
+    const sub = await this.getByOrganization(organizationId);
+
+    if (!sub) {
+      throw new NotFoundError(
+        `No subscription found for organization '${organizationId}'`,
+      );
+    }
+
+    const plan = await this.config.getPlan(sub.planId);
+
+    return {
+      planId: plan.id,
+      planName: plan.name,
+      status: sub.status,
+      features: plan.features,
+      limits: plan.limits,
+      trialEndsAt: sub.trialEnd,
+      periodEndsAt: sub.currentPeriodEnd,
+      cancelledAt: sub.cancelledAt,
+    };
+  }
+
+  // ---------------------------------------------------------------------------------------------------------------
+  // Queries
+  // ---------------------------------------------------------------------------------------------------------------
+
+  /**
+   * Find subscriptions with pagination and filtering.
+   */
+  public async findSubscriptions(
+    query: SubscriptionQuery = {},
+  ): Promise<Page<SubscriptionEntity>> {
+    query.sort ??= "-createdAt";
+
+    const where = this.subscriptionRepo.createQueryWhere();
+
+    if (query.status) {
+      where.status = { eq: query.status };
+    }
+
+    if (query.planId) {
+      where.planId = { eq: query.planId };
+    }
+
+    if (query.organizationId) {
+      where.organizationId = { eq: query.organizationId };
+    }
+
+    return this.subscriptionRepo.paginate(query, { where }, { count: true });
+  }
+
+  // ---------------------------------------------------------------------------------------------------------------
+
+  /**
+   * Get the event history for a subscription, ordered by most recent first.
+   */
+  public async getHistory(
+    subscriptionId: string,
+  ): Promise<SubscriptionEventEntity[]> {
+    return this.eventRepo.findMany({
+      where: { subscriptionId: { eq: subscriptionId } },
+      orderBy: { column: "createdAt", direction: "desc" },
+    });
+  }
+
+  // ---------------------------------------------------------------------------------------------------------------
+
+  /**
+   * Get aggregated subscription statistics.
+   */
+  public async getStats(): Promise<SubscriptionStats> {
+    const [trialing, active, pastDue, suspended, cancelled, expired] =
+      await Promise.all([
+        this.subscriptionRepo.count({ status: { eq: "trialing" } }),
+        this.subscriptionRepo.count({ status: { eq: "active" } }),
+        this.subscriptionRepo.count({ status: { eq: "past_due" } }),
+        this.subscriptionRepo.count({ status: { eq: "suspended" } }),
+        this.subscriptionRepo.count({ status: { eq: "cancelled" } }),
+        this.subscriptionRepo.count({ status: { eq: "expired" } }),
+      ]);
+
+    const total = trialing + active + pastDue + suspended + cancelled + expired;
+
+    const trialEndedEvents = await this.eventRepo.count({
+      type: { eq: "trial_ended" },
+    });
+    const activatedEvents = await this.eventRepo.count({
+      type: { eq: "activated" },
+    });
+    const trialConversionRate =
+      trialEndedEvents > 0 ? activatedEvents / trialEndedEvents : 0;
+
+    const cancelledEvents = await this.eventRepo.count({
+      type: { eq: "cancelled" },
+    });
+    const totalSubscribed = active + trialing + pastDue;
+    const churnRate =
+      totalSubscribed + cancelledEvents > 0
+        ? cancelledEvents / (totalSubscribed + cancelledEvents)
+        : 0;
+
+    const plans = await this.config.getPlans();
+    const byPlan: Record<
+      string,
+      { active: number; trialing: number; total: number }
+    > = {};
+
+    for (const plan of plans) {
+      const [planActive, planTrialing] = await Promise.all([
+        this.subscriptionRepo.count({
+          planId: { eq: plan.id },
+          status: { eq: "active" },
+        }),
+        this.subscriptionRepo.count({
+          planId: { eq: plan.id },
+          status: { eq: "trialing" },
+        }),
+      ]);
+
+      byPlan[plan.id] = {
+        active: planActive,
+        trialing: planTrialing,
+        total: planActive + planTrialing,
+      };
+    }
+
+    return {
+      total,
+      trialing,
+      active,
+      pastDue,
+      suspended,
+      cancelled,
+      expired,
+      trialConversionRate,
+      churnRate,
+      byPlan,
+    };
+  }
+
+  // ---------------------------------------------------------------------------------------------------------------
+
+  /**
+   * Get revenue data from recent subscription events.
+   * Sums amounts from renewed and activated events within the specified window.
+   */
+  public async getRevenue(
+    days = 30,
+  ): Promise<{ total: number; count: number }> {
+    const cutoff = this.dateTime.now().subtract(days, "days").toISOString();
+
+    const events = await this.eventRepo.findMany({
+      where: {
+        type: { inArray: ["renewed", "activated"] },
+        createdAt: { gt: cutoff },
+      },
+    });
+
+    let total = 0;
+    for (const event of events) {
+      total += event.amount ?? 0;
+    }
+
+    return { total, count: events.length };
+  }
+
+  // ---------------------------------------------------------------------------------------------------------------
+  // Protected helpers
+  // ---------------------------------------------------------------------------------------------------------------
+
+  /**
+   * Calculate proration for a mid-cycle plan change.
+   * Returns the net amount: positive = charge, negative = credit.
+   */
+  protected async calculateProration(
+    sub: SubscriptionEntity,
+    newPlanId: string,
+    newInterval: "monthly" | "yearly",
+  ): Promise<number> {
+    const oldPricing = await this.config.getPlanPricing(
+      sub.planId,
+      sub.interval,
+    );
+    const newPricing = await this.config.getPlanPricing(newPlanId, newInterval);
+
+    const now = this.dateTime.now();
+    const periodStart = this.dateTime.of(sub.currentPeriodStart);
+    const periodEnd = this.dateTime.of(sub.currentPeriodEnd);
+
+    const daysInPeriod = periodEnd.diff(periodStart, "days");
+    if (daysInPeriod <= 0) return 0;
+
+    const daysUsed = now.diff(periodStart, "days");
+    const daysRemaining = daysInPeriod - daysUsed;
+
+    const oldDailyRate = oldPricing.amount / daysInPeriod;
+    const newDailyRate = newPricing.amount / daysInPeriod;
+
+    const credit = Math.round(daysRemaining * oldDailyRate);
+    const charge = Math.round(daysRemaining * newDailyRate);
+
+    return charge - credit;
+  }
+}