Merge pull request #2307 from useautumn/dev

Release dev to main

Author: johnyeocx

ai

@@ -3,6 +3,7 @@ import {
 	findMainScheduledCustomerProductByGroup,
 	isCustomerProductOnStripeSubscription,
 	isCustomerProductPaid,
+	isCustomerProductScheduled,
 } from "@autumn/shared";
 import type { StripeWebhookContext } from "@/external/stripe/webhookMiddlewares/stripeWebhookContext";
 import { customerProductActions } from "@/internal/customers/cusProducts/actions";
@@ -13,14 +14,7 @@ import {
 } from "../../common";
 import type { StripeSubscriptionDeletedContext } from "../setupStripeSubscriptionDeletedContext";
 
-/**
- * Handles customer product state changes when a subscription is deleted.
- *
- * For each customer product on the deleted subscription:
- * 1. Expire the customer product and activate default if needed
- * 2. Delete any scheduled main customer product in the same group
- * 3. Cache expired products so invoice.created can access them
- */
+/** Expires live products, then activates or removes their scheduled successors. */
 export const expireAndActivateCustomerProducts = async ({
 	ctx,
 	eventContext,
@@ -36,13 +30,10 @@ export const expireAndActivateCustomerProducts = async ({
 	);
 
 	const expiredCustomerProducts: FullCusProduct[] = [];
-	// Iterate over a snapshot: `expireAndActivateWithTracking` may insert a
-	// default product, and `trackCustomerProductDeletion` below splices the
-	// paid scheduled product out. Both mutate `customerProducts` in place,
-	// which would otherwise invalidate the for-of cursor and cause elements to
-	// be skipped or re-iterated (see the add-on skip bug in the renewal
-	// handler).
-	for (const customerProduct of [...customerProducts]) {
+	const liveCustomerProducts = customerProducts.filter(
+		(customerProduct) => !isCustomerProductScheduled(customerProduct),
+	);
+	for (const customerProduct of liveCustomerProducts) {
 		// 1. If not on stripe subscription, skip
 		const onStripeSubscription = isCustomerProductOnStripeSubscription({
 			customerProduct,
@@ -84,10 +75,7 @@ export const expireAndActivateCustomerProducts = async ({
 		}
 	}
 
-	/**
-	 * Need to cache expired customer products to invoice.created can access them
-	 * invoice.created creates a final invoice for usage-based prices
-	 */
+	// invoice.created needs the expired snapshots for final usage billing.
 	await customerProductActions.expiredCache.set({
 		stripeSubscriptionId: stripeSubscription.id,
 		customerProducts: expiredCustomerProducts,

server/src/external/stripe/webhookHandlers/handleStripeSubscriptionDeleted/tasks/expireAndActivateCustomerProducts.ts

@@ -7,8 +7,8 @@ import {
 import { ms } from "@shared/utils/common/unixUtils";
 import type { AutumnContext } from "@/honoUtils/HonoEnv";
 import { computeAttachPlan } from "@/internal/billing/v2/actions/attach/compute/computeAttachPlan";
+import { handleAttachComputeErrors } from "@/internal/billing/v2/actions/attach/errors/handleAttachComputeErrors";
 import { handleAttachV2Errors } from "@/internal/billing/v2/actions/attach/errors/handleAttachV2Errors";
-import { handleCurrencyMismatchErrors } from "@/internal/billing/v2/actions/attach/errors/handleCurrencyMismatchErrors";
 import { logAttachContext } from "@/internal/billing/v2/actions/attach/logs/logAttachContext";
 import { setupAttachBillingContext } from "@/internal/billing/v2/actions/attach/setup/setupAttachBillingContext";
 import { checkCheckoutSessionLock } from "@/internal/billing/v2/actions/locks/checkoutSessionLock/checkCheckoutSessionLock";
@@ -60,11 +60,6 @@ export async function attach({
 
 	logAttachContext({ ctx, billingContext });
 
-	// Currency guard runs here (not in handleAttachV2Errors) because
-	// evaluateStripeBillingPlan below creates Stripe prices, so the block must
-	// fire before it. Covers preview too.
-	handleCurrencyMismatchErrors({ ctx, billingContext, params });
-
 	// 2. Compute
 	const autumnBillingPlan = computeAttachPlan({
 		ctx,
@@ -73,6 +68,12 @@ export async function attach({
 	});
 
 	logAutumnBillingPlan({ ctx, plan: autumnBillingPlan, billingContext });
+	await handleAttachComputeErrors({
+		ctx,
+		billingContext,
+		autumnBillingPlan,
+		params,
+	});
 
 	// 3. Evaluate Stripe billing plan (handles checkout mode internally)
 	const stripeBillingPlan = await evaluateStripeBillingPlan({

server/src/internal/billing/v2/actions/attach/attach.ts

@@ -15,15 +15,7 @@ import { computeOneOffPurchaseRebalance } from "./computeOneOffPurchaseRebalance
 import { finalizeAttachPlan } from "./finalizeAttachPlan";
 import { shouldBuildImmediateLineItems } from "./shouldBuildImmediateLineItems";
 
-/**
- * Computes the billing plan for attaching a product.
- *
- * Scenarios:
- * - Add-on/One-time (no currentCustomerProduct): Just insert new product
- * - First main product (no currentCustomerProduct): Just insert new product
- * - Upgrade (currentCustomerProduct exists, planTiming=immediate): Expire current, insert new active
- * - Downgrade (currentCustomerProduct exists, planTiming=end_of_cycle): Cancel current at end of cycle, insert new scheduled
- */
+/** Computes new attachments and immediate or scheduled product transitions. */
 export const computeAttachPlan = ({
 	ctx,
 	attachBillingContext,
@@ -59,15 +51,17 @@ export const computeAttachPlan = ({
 
 	// Customer licenses follow the incoming definitions on immediate swaps;
 	// scheduled swaps transition at activation instead.
+	const computedCustomerLicenseTransitions = currentCustomerProduct
+		? computeCustomerLicenseTransitions({
+				outgoingCustomerProducts: [currentCustomerProduct],
+				incomingCustomerProducts: [newCustomerProduct],
+				customerLicenseBillingContext:
+					attachBillingContext.customerLicenseBillingContext,
+				carryCustomerLicenseState: planTiming === "immediate",
+			})
+		: [];
 	const customerLicenseTransitions =
-		planTiming === "immediate" && currentCustomerProduct
-			? computeCustomerLicenseTransitions({
-					outgoingCustomerProducts: [currentCustomerProduct],
-					incomingCustomerProducts: [newCustomerProduct],
-					customerLicenseBillingContext:
-						attachBillingContext.customerLicenseBillingContext,
-				})
-			: [];
+		planTiming === "immediate" ? computedCustomerLicenseTransitions : [];
 
 	const {
 		entitlements: carriedOverEntitlements,

server/src/internal/billing/v2/actions/attach/compute/computeAttachPlan.ts

@@ -0,0 +1,30 @@
+import type {
+	AttachBillingContext,
+	AttachParamsV1,
+	AutumnBillingPlan,
+} from "@autumn/shared";
+import type { AutumnContext } from "@/honoUtils/HonoEnv";
+import { validateCustomerEntitlementBatchTransitions } from "@/internal/billing/v2/actions/batchTransition/errors/validateCustomerEntitlementBatchTransitions";
+import { handleLicenseTransitionErrors } from "@/internal/billing/v2/common/errors/handleLicenseTransitionErrors";
+import { handleCurrencyMismatchErrors } from "./handleCurrencyMismatchErrors";
+import { handleLicenseErrors } from "./handleLicenseErrors/handleLicenseErrors";
+
+export const handleAttachComputeErrors = async ({
+	ctx,
+	billingContext,
+	autumnBillingPlan,
+	params,
+}: {
+	ctx: AutumnContext;
+	billingContext: AttachBillingContext;
+	autumnBillingPlan: AutumnBillingPlan;
+	params: AttachParamsV1;
+}) => {
+	handleCurrencyMismatchErrors({ ctx, billingContext, params });
+	handleLicenseTransitionErrors({ autumnBillingPlan });
+	handleLicenseErrors({ billingContext });
+	await validateCustomerEntitlementBatchTransitions({
+		ctx,
+		transitions: autumnBillingPlan.customerLicenseTransitions,
+	});
+};

server/src/internal/billing/v2/actions/attach/errors/handleAttachComputeErrors.ts

@@ -19,10 +19,10 @@ import { handleProrationBehaviorErrors } from "@/internal/billing/v2/common/erro
 import { handleCustomLineItemsErrors } from "@/internal/billing/v2/common/errors/handleCustomLineItemsErrors";
 import { handleEntityLicenseAssignmentErrors } from "@/internal/billing/v2/common/errors/handleEntityLicenseAssignmentErrors";
 import { handleExternalPSPErrors } from "@/internal/billing/v2/common/errors/handleExternalPSPErrors";
+import { handleLicenseAttachTargetErrors } from "@/internal/billing/v2/common/errors/handleLicenseAttachTargetErrors";
 import { handleSubscriptionIdErrors } from "@/internal/billing/v2/common/errors/handleSubscriptionIdErrors";
 import { handleStripeBillingPlanErrors } from "@/internal/billing/v2/providers/stripe/errors/handleStripeBillingPlanErrors";
 import { handleCustomPaymentMethodErrorsV2 } from "@/internal/customers/attach/attachUtils/handleAttachErrors";
-import { handleLicenseErrors } from "./handleLicenseErrors/handleLicenseErrors";
 import { handleRevertTrialErrors } from "./handleRevertTrialErrors";
 
 /** Validates attach v2 request before executing the billing plan. */
@@ -60,6 +60,12 @@ export const handleAttachV2Errors = async ({
 		fullCustomer: billingContext.fullCustomer,
 	});
 
+	// 1.4. License linkage preconditions on the attach target
+	handleLicenseAttachTargetErrors({
+		fullCustomer: billingContext.fullCustomer,
+		attachProduct: billingContext.attachProduct,
+	});
+
 	// 2. Current customer product errors (same product)
 	handleCurrentCustomerProductErrors({ billingContext });
 
@@ -112,6 +118,4 @@ export const handleAttachV2Errors = async ({
 	handleRevertTrialErrors({ billingContext });
 
 	handleStripeBillingPlanErrors({ ctx, billingContext, billingPlan });
-
-	handleLicenseErrors({ billingContext, autumnBillingPlan });
 };

server/src/internal/billing/v2/actions/attach/errors/handleAttachV2Errors.ts

@@ -1,41 +1,47 @@
 import {
 	type AttachBillingContext,
-	type AutumnBillingPlan,
 	customerLicenseToUsage,
 	ErrCode,
 	type FullCustomerLicense,
 	RecaseError,
 } from "@autumn/shared";
+import { matchCustomerLicensePlanSuccessors } from "@/internal/billing/v2/compute/customerLicenseTransitions/matchCustomerLicenseSuccessors.js";
 
 const licensePlanIdOf = (customerLicense: FullCustomerLicense) =>
 	customerLicense.planLicense?.product.id ??
 	customerLicense.license_internal_product_id;
 
+/** Blocks an immediate switch that would strand active assignments: a used
+ * outgoing pool must have a successor (same license plan, or a 1:1 group
+ * match) on the incoming plan. */
 export const handleDroppedLicenseErrors = ({
 	billingContext,
-	autumnBillingPlan,
 }: {
 	billingContext: AttachBillingContext;
-	autumnBillingPlan: AutumnBillingPlan;
 }) => {
 	const { currentCustomerProduct, planTiming } = billingContext;
 	if (planTiming !== "immediate" || !currentCustomerProduct) return;
 
-	const incomingLicensePlanIds = new Set(
-		(autumnBillingPlan.insertCustomerProducts ?? []).flatMap(
-			(customerProduct) =>
-				(customerProduct.customer_licenses ?? []).map(licensePlanIdOf),
-		),
-	);
+	const { unmatched } = matchCustomerLicensePlanSuccessors({
+		outgoingCustomerLicenses: currentCustomerProduct.customer_licenses ?? [],
+		incomingPlanLicenses: billingContext.attachProduct.licenses ?? [],
+	});
 
-	for (const outgoingPool of currentCustomerProduct.customer_licenses ?? []) {
-		const used = customerLicenseToUsage({ customerLicense: outgoingPool });
+	for (const { outgoingCustomerLicense, reason, group } of unmatched) {
+		const used = customerLicenseToUsage({
+			customerLicense: outgoingCustomerLicense,
+		});
 		if (used === 0) continue;
-		if (incomingLicensePlanIds.has(licensePlanIdOf(outgoingPool))) continue;
+
+		const licensePlanId = licensePlanIdOf(outgoingCustomerLicense);
+		const conflict =
+			reason === "ambiguous"
+				? `the licenses in group "${group}" are not a 1:1 match on the incoming plan`
+				: "the incoming plan drops the license";
 		throw new RecaseError({
 			message:
 				`License changes conflict with active license assignments: ` +
-				`${used} assigned for ${licensePlanIdOf(outgoingPool)}, but the incoming plan drops the license. Release licenses first.`,
+				`${used} assigned for ${licensePlanId}, but ${conflict}. Release licenses first.`,
 			code: ErrCode.InvalidRequest,
 			statusCode: 400,
 		});

server/src/internal/billing/v2/actions/attach/errors/handleLicenseErrors/handleDroppedLicenseErrors.ts

@@ -1,14 +1,10 @@
-import type { AttachBillingContext, AutumnBillingPlan } from "@autumn/shared";
-import { handleLicenseTransitionErrors } from "@/internal/billing/v2/common/errors/handleLicenseTransitionErrors";
+import type { AttachBillingContext } from "@autumn/shared";
 import { handleDroppedLicenseErrors } from "./handleDroppedLicenseErrors";
 
 export const handleLicenseErrors = ({
 	billingContext,
-	autumnBillingPlan,
 }: {
 	billingContext: AttachBillingContext;
-	autumnBillingPlan: AutumnBillingPlan;
 }) => {
-	handleLicenseTransitionErrors({ autumnBillingPlan });
-	handleDroppedLicenseErrors({ billingContext, autumnBillingPlan });
+	handleDroppedLicenseErrors({ billingContext });
 };

server/src/internal/billing/v2/actions/attach/errors/handleLicenseErrors/handleLicenseErrors.ts

@@ -149,6 +149,8 @@ export const setupAttachBillingContext = async ({
 
 	const customerLicenseQuantities = setupCustomerLicenseQuantityContext({
 		params,
+		fullProduct: attachProduct,
+		customerProduct: currentCustomerProduct,
 	});
 
 	const invoiceMode = await setupInvoiceModeContext({ ctx, params });

server/src/internal/billing/v2/actions/attach/setup/setupAttachBillingContext.ts

@@ -9,14 +9,7 @@ import type Stripe from "stripe";
 import { getLatestPeriodEnd } from "@/external/stripe/stripeSubUtils/convertSubUtils";
 import { getLargestInterval } from "@/internal/products/prices/priceUtils/priceIntervalUtils";
 
-/**
- * Computes the end of cycle timestamp for scheduled product attachments.
- * Used for:
- * - Downgrades (transition from existing product)
- * - Merged subscription scheduling (entity joins existing subscription at renewal)
- *
- * Returns undefined if planTiming is "immediate" or no billing cycle can be determined.
- */
+/** Resolves a scheduled attachment's cycle boundary from Autumn or Stripe. */
 export const setupAttachEndOfCycleMs = ({
 	planTiming,
 	currentCustomerProduct,
@@ -45,17 +38,16 @@ export const setupAttachEndOfCycleMs = ({
 			excludeOneOff: true,
 		});
 
-		if (!largestInterval) {
-			return undefined;
+		if (largestInterval) {
+			return getCycleEnd({
+				anchor: billingCycleAnchorMs,
+				interval: largestInterval.interval,
+				intervalCount: largestInterval.intervalCount,
+				now: currentEpochMs,
+				floor:
+					billingCycleAnchorMs === "now" ? undefined : billingCycleAnchorMs,
+			});
 		}
-
-		return getCycleEnd({
-			anchor: billingCycleAnchorMs,
-			interval: largestInterval.interval,
-			intervalCount: largestInterval.intervalCount,
-			now: currentEpochMs,
-			floor: billingCycleAnchorMs === "now" ? undefined : billingCycleAnchorMs,
-		});
 	}
 
 	const latestPeriodEndSeconds = getLatestPeriodEnd({