feat(licenses): 🎸 support catalog license plan updates

Add license-aware plan update previews, preserve customer definitions
across versioned and in-place edits, and surface the resulting catalog
changes in the dashboard.

Author: johnyeocx

server/src/internal/catalog/actions/catalogPlanPreflight.ts

@@ -8,6 +8,7 @@ import {
 	previewPlanLicenseSync,
 	validatePlanLicenseUpdate,
 } from "@/internal/licenses/actions/links/syncPlanLicenses.js";
+import { previewAffectedLicenses } from "@/internal/product/actions/previewUpdatePlan/previewAffectedLicenses.js";
 import { ProductService } from "@/internal/products/ProductService.js";
 import { sortCatalogPlansByDependencies } from "./catalogPlanDependencies.js";
 
@@ -90,7 +91,15 @@ const preflightCatalogLicenses = async ({
 			newParentVersion: preview.versionable || !current,
 			licenseProducts,
 		});
-		preview.license_changes = licensePreview.changes;
+		preview.license_changes = await previewAffectedLicenses({
+			ctx,
+			currentParentProduct: {
+				...parent,
+				licenses: current?.licenses ?? [],
+			},
+			resolved: licensePreview.prepared?.resolved ?? [],
+			structuralChanges: licensePreview.changes,
+		});
 		if (preview.plan) preview.plan.licenses = licensePreview.licenses;
 	}
 };

server/src/internal/licenses/actions/customize/setupCustomPlanLicenses.ts

@@ -1,3 +1,4 @@
+import { isDeepStrictEqual } from "node:util";
 import type {
 	CustomizePlanLicense,
 	DbPlanLicense,
@@ -45,8 +46,7 @@ const matchesCatalogLink = ({
 		return false;
 	if (
 		entry.metadata !== undefined &&
-		JSON.stringify(entry.metadata) !==
-			JSON.stringify(catalogLink.metadata ?? {})
+		!isDeepStrictEqual(entry.metadata, catalogLink.metadata ?? {})
 	)
 		return false;
 	return true;

server/src/internal/licenses/actions/customize/toApiPlanLicenseWithCustomize.ts

@@ -2,9 +2,28 @@ import {
 	type ApiPlanV1,
 	diffPlanV1,
 	type FullPlanLicense,
+	type LicenseCustomize,
 } from "@autumn/shared";
 import { toApiPlanLicenses } from "@/internal/licenses/licenseUtils.js";
 
+export const diffLicensePlanCustomize = ({
+	basePlan,
+	effectivePlan,
+}: {
+	basePlan: ApiPlanV1;
+	effectivePlan: ApiPlanV1;
+}): LicenseCustomize | undefined => {
+	const diff = diffPlanV1({ from: basePlan, to: effectivePlan });
+	const customize = {
+		...(diff.price !== undefined ? { price: diff.price } : {}),
+		...(diff.add_items !== undefined ? { add_items: diff.add_items } : {}),
+		...(diff.remove_items !== undefined
+			? { remove_items: diff.remove_items }
+			: {}),
+	};
+	return Object.keys(customize).length > 0 ? customize : undefined;
+};
+
 export const toApiPlanLicenseWithCustomize = async ({
 	license,
 	resolvePlan,
@@ -19,16 +38,10 @@ export const toApiPlanLicenseWithCustomize = async ({
 		resolvePlan(license.base_product),
 		resolvePlan(license.product),
 	]);
-	const diff = diffPlanV1({ from: basePlan, to: effectivePlan });
+	const customize = diffLicensePlanCustomize({ basePlan, effectivePlan });
 
 	return {
 		...response,
-		customize: {
-			...(diff.price !== undefined ? { price: diff.price } : {}),
-			...(diff.add_items !== undefined ? { add_items: diff.add_items } : {}),
-			...(diff.remove_items !== undefined
-				? { remove_items: diff.remove_items }
-				: {}),
-		},
+		...(customize ? { customize } : {}),
 	};
 };

server/src/internal/licenses/actions/links/retireCatalogPlanLicenseIfReferenced.ts

@@ -0,0 +1,61 @@
+import { isDeepStrictEqual } from "node:util";
+import type { DbPlanLicense, PlanLicenseParams } from "@autumn/shared";
+import type { DrizzleCli } from "@/db/initDrizzle.js";
+import { planLicenseRepo } from "@/internal/licenses/repos/planLicenseRepo.js";
+
+type ItemCustomizationMode = "preserve" | "clear" | "replace";
+
+const planLicenseWillChange = ({
+	current,
+	entry,
+	included,
+	prepaidOnly,
+	itemCustomizationMode,
+}: {
+	current: DbPlanLicense;
+	entry: PlanLicenseParams;
+	included: number;
+	prepaidOnly: boolean;
+	itemCustomizationMode: ItemCustomizationMode;
+}) =>
+	current.included !== included ||
+	current.prepaid_only !== prepaidOnly ||
+	(entry.metadata !== undefined &&
+		!isDeepStrictEqual(current.metadata ?? {}, entry.metadata)) ||
+	itemCustomizationMode === "replace" ||
+	(itemCustomizationMode === "clear" && current.customized);
+
+/** Retires a changed catalog link when a customer still references its definition. */
+export const retireCatalogPlanLicenseIfReferenced = async ({
+	db,
+	current,
+	entry,
+	included,
+	prepaidOnly,
+	itemCustomizationMode,
+	hasCustomerReference,
+}: {
+	db: DrizzleCli;
+	current: DbPlanLicense;
+	entry: PlanLicenseParams;
+	included: number;
+	prepaidOnly: boolean;
+	itemCustomizationMode: ItemCustomizationMode;
+	hasCustomerReference: boolean;
+}) => {
+	if (
+		!planLicenseWillChange({
+			current,
+			entry,
+			included,
+			prepaidOnly,
+			itemCustomizationMode,
+		})
+	) {
+		return;
+	}
+
+	if (!hasCustomerReference) return;
+
+	await planLicenseRepo.retireCatalogById({ db, id: current.id });
+};

server/src/internal/licenses/actions/links/syncPlanLicenses.ts

@@ -1,4 +1,5 @@
 import {
+	type DbPlanLicense,
 	type Entitlement,
 	ErrCode,
 	type FullProduct,
@@ -18,14 +19,20 @@ import {
 	getFullLicenseProduct,
 	toApiPlanLicenses,
 } from "../../licenseUtils.js";
+import { customerLicenseRepo } from "../../repos/customerLicenseRepo.js";
 import { licenseAssignmentRepo } from "../../repos/licenseAssignmentRepo.js";
 import { licenseItemRepo } from "../../repos/licenseItemRepo.js";
 import { planLicenseRepo } from "../../repos/planLicenseRepo.js";
 import { logLicenseAction } from "../logs/logLicenseAction.js";
+import { retireCatalogPlanLicenseIfReferenced } from "./retireCatalogPlanLicenseIfReferenced.js";
 import { validateLicenseLink } from "./validateLicenseLink.js";
 
 type LicenseItemCustomization =
-	| { mode: "preserve"; sourcePlanLicenseId?: string }
+	| {
+			mode: "preserve";
+			sourcePlanLicenseId?: string;
+			sourceCustomized?: boolean;
+	  }
 	| { mode: "clear" }
 	| {
 			mode: "replace";
@@ -34,17 +41,19 @@ type LicenseItemCustomization =
 			items: ReturnType<typeof derivePlanLicenseItemRefs>;
 	  };
 
-type ResolvedLink = {
+export type ResolvedPlanLicenseLink = {
 	entry: PlanLicenseParams;
 	licenseProduct: FullProduct;
+	effectiveProduct: FullProduct;
 	included: number;
 	prepaidOnly: boolean;
 	itemCustomization: LicenseItemCustomization;
+	sourcePlanLicense?: DbPlanLicense;
 };
 
 export type PreparedPlanLicenseSync = {
 	parentProduct: FullProduct;
-	resolved: ResolvedLink[];
+	resolved: ResolvedPlanLicenseLink[];
 	removed: Awaited<
 		ReturnType<typeof planLicenseRepo.listCatalogByParentInternalProductIds>
 	>;
@@ -98,7 +107,7 @@ export const previewPlanLicenseSync = async (
 			];
 		},
 	);
-	return { licenses: current, changes };
+	return { licenses: current, changes, prepared };
 };
 
 /** Resolves and validates one link without writing it. */
@@ -121,7 +130,7 @@ const resolveLink = async ({
 		PreparedPlanLicenseSync["removed"][number]
 	>;
 	sourceProductByLicenseInternalId: Map<string, FullProduct>;
-}): Promise<ResolvedLink> => {
+}): Promise<ResolvedPlanLicenseLink> => {
 	const pinnedInternalId =
 		entry.version === undefined
 			? pinnedInternalIdByPublicId.get(entry.license_plan_id)
@@ -152,6 +161,7 @@ const resolveLink = async ({
 		itemCustomization = {
 			mode: "preserve",
 			sourcePlanLicenseId: sourceLink?.id,
+			sourceCustomized: sourceLink?.customized,
 		};
 		if (sourceLink?.customized) {
 			effectiveProduct =
@@ -185,12 +195,36 @@ const resolveLink = async ({
 	return {
 		entry,
 		licenseProduct,
+		effectiveProduct,
 		included: entry.included ?? 0,
 		prepaidOnly: entry.prepaid_only ?? true,
 		itemCustomization,
+		sourcePlanLicense: sourceLink,
 	};
 };
 
+/** Nesting is not supported: a plan offered as a license under other plans
+ * cannot offer licenses of its own. Clearing (`licenses: []`) stays allowed. */
+const assertParentNotLicensed = ({
+	parentProduct,
+	licenses,
+}: {
+	parentProduct: FullProduct;
+	licenses: PlanLicenseParams[];
+}) => {
+	const parentIds = [
+		...new Set(
+			(parentProduct.parent_plan_licenses ?? []).map((link) => link.product.id),
+		),
+	];
+	if (licenses.length === 0 || parentIds.length === 0) return;
+	throw new RecaseError({
+		message: `Cannot add licenses to ${parentProduct.id}: it is offered as a license under ${parentIds.join(", ")}.`,
+		code: ErrCode.InvalidRequest,
+		statusCode: 400,
+	});
+};
+
 /** A plan cannot drop below what customers are already using. */
 const assertCapacityAllowed = async ({
 	ctx,
@@ -246,20 +280,23 @@ export const preparePlanLicenseSync = async ({
 			statusCode: 400,
 		});
 	}
+	assertParentNotLicensed({ parentProduct, licenses });
 
 	const sourceLinks =
-		await planLicenseRepo.listCatalogByParentInternalProductIds({
+		parentProduct.licenses
+			?.filter(
+				(link) => link.parent_internal_product_id === fromInternalProductId,
+			)
+			.map(({ product: _, base_product: __, ...link }) => link) ??
+		(await planLicenseRepo.listCatalogByParentInternalProductIds({
 			db: ctx.db,
 			parentInternalProductIds: [fromInternalProductId],
-		});
-	const existingLinkProducts = await planLicenseRepo.listProductsByInternalIds({
-		db: ctx.db,
-		internalProductIds: sourceLinks.map(
-			(link) => link.license_internal_product_id,
-		),
-	});
+		}));
 	const pinnedInternalIdByPublicId = new Map(
-		existingLinkProducts.map((product) => [product.id, product.internal_id]),
+		(parentProduct.licenses ?? []).map((link) => [
+			link.product.id,
+			link.license_internal_product_id,
+		]),
 	);
 	const sourceLinkByLicenseInternalId = new Map(
 		sourceLinks.map((link) => [link.license_internal_product_id, link]),
@@ -352,7 +389,37 @@ export const applyPreparedPlanLicenseSync = async ({
 
 	await ctx.db.transaction(async (tx) => {
 		const txDb = tx as unknown as DrizzleCli;
+		const sourcePlanLicenses = resolved.flatMap(({ sourcePlanLicense }) =>
+			sourcePlanLicense?.parent_internal_product_id === parentInternalProductId
+				? [sourcePlanLicense]
+				: [],
+		);
+		const referencedPlanLicenseIds =
+			await customerLicenseRepo.listReferencedPlanLicenseIds({
+				db: txDb,
+				planLicenseIds: sourcePlanLicenses.map(({ id }) => id),
+			});
+		const sourceLinkByLicenseInternalId = new Map(
+			sourcePlanLicenses.map((link) => [
+				link.license_internal_product_id,
+				link,
+			]),
+		);
 		for (const link of resolved) {
+			const current = sourceLinkByLicenseInternalId.get(
+				link.licenseProduct.internal_id,
+			);
+			if (current) {
+				await retireCatalogPlanLicenseIfReferenced({
+					db: txDb,
+					current,
+					entry: link.entry,
+					included: link.included,
+					prepaidOnly: link.prepaidOnly,
+					itemCustomizationMode: link.itemCustomization.mode,
+					hasCustomerReference: referencedPlanLicenseIds.has(current.id),
+				});
+			}
 			const planLicense = await planLicenseRepo.upsert({
 				db: txDb,
 				parentInternalProductId,
@@ -388,7 +455,7 @@ export const applyPreparedPlanLicenseSync = async ({
 					db: txDb,
 					fromPlanLicenseId: customization.sourcePlanLicenseId,
 					toPlanLicenseId: planLicense.id,
-					customized: true,
+					customized: customization.sourceCustomized,
 				});
 			}
 		}

server/src/internal/licenses/repos/customerLicenseRepo.ts

@@ -87,6 +87,25 @@ const listByParentCustomerProductIds = async ({
 	});
 };
 
+const listReferencedPlanLicenseIds = async ({
+	db,
+	planLicenseIds,
+}: {
+	db: DrizzleCli;
+	planLicenseIds: string[];
+}): Promise<Set<string>> => {
+	if (planLicenseIds.length === 0) return new Set();
+	const rows = await db
+		.select({ planLicenseId: customerLicenses.plan_license_id })
+		.from(customerLicenses)
+		.where(inArray(customerLicenses.plan_license_id, planLicenseIds));
+	return new Set(
+		rows.flatMap(({ planLicenseId }) =>
+			planLicenseId === null ? [] : [planLicenseId],
+		),
+	);
+};
+
 /** Idempotent ensure + granted sync for a (parent, license) balance row.
  * Stamps plan_license_id when provided so stale links converge too. */
 const upsertGranted = async ({
@@ -330,6 +349,7 @@ export const customerLicenseRepo = {
 	getByParentAndLicense,
 	listByInternalCustomerId,
 	listByParentCustomerProductIds,
+	listReferencedPlanLicenseIds,
 	listBillingPriceRows,
 	update,
 	deleteByIds,