fix(billing): 🐛 merge latest dev into pooled balances

Author: og2701

ai

@@ -1,6 +1,6 @@
 import type { StripeWebhookContext } from "../../webhookMiddlewares/stripeWebhookContext.js";
 import { setupStripeSubscriptionCreatedContext } from "./setupStripeSubscriptionCreatedContext.js";
-import { autoSyncFromSubscription } from "./tasks/autoSyncFromSubscription.js";
+import { autoSyncFromSubscriptionWithLock } from "./tasks/autoSyncFromSubscription.js";
 import { linkScheduledCustomerProductsToSubscription } from "./tasks/linkScheduledCustomerProductsToSubscription.js";
 
 export const handleStripeSubscriptionCreated = async ({
@@ -17,5 +17,5 @@ export const handleStripeSubscriptionCreated = async ({
 		subscription: subscriptionCreatedContext.subscription,
 	});
 
-	await autoSyncFromSubscription({ ctx, subscriptionCreatedContext });
+	await autoSyncFromSubscriptionWithLock({ ctx, subscriptionCreatedContext });
 };

server/src/external/stripe/webhookHandlers/handleStripeSubscriptionCreated/handleStripeSubscriptionCreated.ts

@@ -3,27 +3,35 @@ import { billingActions } from "@/internal/billing/v2/actions";
 import { canAutoSync } from "@/internal/billing/v2/actions/sync/canAutoSync/index.js";
 import { subscriptionToSyncParams } from "@/internal/billing/v2/actions/sync/subscriptionToSyncParams.js";
 import { isAutumnCheckoutSubscription } from "@/internal/billing/v2/actions/sync/utils/isAutumnCheckoutSubscription.js";
+import { withStripeSyncCustomerLock } from "@/internal/billing/v2/actions/sync/utils/withStripeSyncCustomerLock.js";
+import { CusService } from "@/internal/customers/CusService.js";
 import { shouldSkipSubscriptionSync } from "../../common/subscriptionSync/shouldSkipSubscriptionSync.js";
 import type { StripeSubscriptionCreatedContext } from "../setupStripeSubscriptionCreatedContext.js";
 
 /**
  * Custom base prices can auto-sync; custom feature prices and unresolved items
  * still abort via canAutoSync.
  */
-export const autoSyncFromSubscription = async ({
-	ctx,
-	subscriptionCreatedContext,
-}: {
+type AutoSyncFromSubscriptionParams = {
 	ctx: StripeWebhookContext;
 	subscriptionCreatedContext: StripeSubscriptionCreatedContext;
-}) => {
+};
+
+const autoSyncFromSubscription = async ({
+	ctx,
+	subscriptionCreatedContext,
+}: AutoSyncFromSubscriptionParams) => {
 	const { logger, stripeCli } = ctx;
 	const { subscription, fullCustomer } = subscriptionCreatedContext;
 	const customerId = fullCustomer.id ?? fullCustomer.internal_id;
+	const currentCustomer = await CusService.getFull({
+		ctx,
+		idOrInternalId: customerId,
+	});
 
 	const skip = shouldSkipSubscriptionSync({
 		subscription,
-		fullCustomer,
+		fullCustomer: currentCustomer,
 		requireRecent: false,
 	});
 	if (skip.skip) {
@@ -44,7 +52,7 @@ export const autoSyncFromSubscription = async ({
 		ctx,
 		customerId,
 		subscription,
-		customerProducts: fullCustomer.customer_products,
+		customerProducts: currentCustomer.customer_products,
 	});
 
 	const eligibility = canAutoSync({ match });
@@ -57,3 +65,17 @@ export const autoSyncFromSubscription = async ({
 
 	await billingActions.syncV2({ ctx, params });
 };
+
+export const autoSyncFromSubscriptionWithLock = async (
+	params: AutoSyncFromSubscriptionParams,
+) => {
+	const { ctx, subscriptionCreatedContext } = params;
+	const customerId =
+		subscriptionCreatedContext.fullCustomer.id ??
+		subscriptionCreatedContext.fullCustomer.internal_id;
+	await withStripeSyncCustomerLock({
+		ctx,
+		customerId,
+		run: () => autoSyncFromSubscription(params),
+	});
+};

server/src/external/stripe/webhookHandlers/handleStripeSubscriptionCreated/tasks/autoSyncFromSubscription.ts

@@ -5,6 +5,7 @@ import {
 	findMainScheduledCustomerProductByGroup,
 	isCustomerProductOnStripeSubscription,
 	isCustomerProductPaid,
+	isCustomerProductScheduled,
 } from "@autumn/shared";
 import type { StripeWebhookContext } from "@/external/stripe/webhookMiddlewares/stripeWebhookContext";
 import { executeAutumnBillingPlan } from "@/internal/billing/v2/execute/executeAutumnBillingPlan.js";
@@ -22,14 +23,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,
@@ -54,7 +48,10 @@ export const expireAndActivateCustomerProducts = async ({
 	// Prepare from a stable snapshot. Completion and tracking mutate both the
 	// event-context product list and FullCustomer, but only after the merged
 	// lifecycle plan has committed successfully.
-	for (const customerProduct of [...customerProducts]) {
+	const liveCustomerProducts = customerProducts.filter(
+		(customerProduct) => !isCustomerProductScheduled(customerProduct),
+	);
+	for (const customerProduct of liveCustomerProducts) {
 		const onStripeSubscription = isCustomerProductOnStripeSubscription({
 			customerProduct,
 			stripeSubscriptionId: stripeSubscription.id,
@@ -160,10 +157,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

@@ -16,15 +16,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,
@@ -60,15 +52,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 });
 };