fix(balances): limit_reached reports the tightest cap and its filter from one source

Author: charlietlamb

server/src/internal/balances/trackWebhooks/checkLimitReached.ts

@@ -9,6 +9,7 @@ import {
 	fullSubjectToUsageWindowLimits,
 	getCurrentUsageWindowUsage,
 	orgToInStatuses,
+	type UsageLimitFilter,
 	type UsageLimitWebhookBlock,
 	usageLimitFilterMatchesProperties,
 	WebhookEventType,
@@ -17,7 +18,15 @@ import { sendSvixEvent } from "@/external/svix/svixHelpers.js";
 import type { AutumnContext } from "@/honoUtils/HonoEnv.js";
 import { usageWindowLimitToWebhookBlock } from "@/internal/balances/utils/usageWindows/usageWindowLimitToWebhookBlock.js";
 
-/** The exhausted cap that blocked this event: the first matching limit with no headroom left. */
+type BlockingUsageLimit = {
+	block: UsageLimitWebhookBlock;
+	filter: UsageLimitFilter | undefined;
+};
+
+/**
+ * The cap that blocked this event. Enforcement stops at the cap with the least
+ * headroom, so the webhook reports that one, filter included, from one source.
+ */
 const findBlockingUsageLimit = ({
 	ctx,
 	fullSubject,
@@ -30,31 +39,69 @@ const findBlockingUsageLimit = ({
 	feature: Feature;
 	eventProperties?: Record<string, unknown> | null;
 	now: number;
-}): UsageLimitWebhookBlock | undefined => {
-	const limits = fullSubjectToUsageWindowLimits({
+}): BlockingUsageLimit | undefined => {
+	const usageWindows = fullSubject.usage_windows ?? [];
+	const measured = fullSubjectToUsageWindowLimits({
 		fullSubject,
 		featureIds: [feature.id],
 		features: ctx.features,
 		now,
 		inStatuses: orgToInStatuses({ org: ctx.org }),
-	});
-	const usageWindows = fullSubject.usage_windows ?? [];
+	})
+		.filter((limit) =>
+			usageLimitFilterMatchesProperties({
+				filterProperties: limit.filter_properties,
+				eventProperties,
+			}),
+		)
+		.map((limit) => ({
+			limit,
+			usage: getCurrentUsageWindowUsage({ usageWindows, limit, now }),
+		}))
+		.sort(
+			(left, right) =>
+				left.limit.limit - left.usage - (right.limit.limit - right.usage),
+		);
 
-	for (const limit of limits) {
-		const appliesToEvent = usageLimitFilterMatchesProperties({
-			filterProperties: limit.filter_properties,
-			eventProperties,
-		});
-		if (!appliesToEvent) continue;
+	const tightest = measured[0];
+	if (!tightest || tightest.usage < tightest.limit.limit) return undefined;
 
-		const usage = getCurrentUsageWindowUsage({ usageWindows, limit, now });
-		if (usage < limit.limit) continue;
+	const block = usageWindowLimitToWebhookBlock({
+		limit: tightest.limit,
+		usage: tightest.usage,
+	});
+	if (!block) return undefined;
 
-		return usageWindowLimitToWebhookBlock({ limit, usage }) ?? undefined;
-	}
-	return undefined;
+	return {
+		block,
+		filter: tightest.limit.filter_properties
+			? { properties: tightest.limit.filter_properties }
+			: undefined,
+	};
 };
 
+/** Legacy deductions carry no FullSubject; read the exhausted filtered cap off the evaluated subject. */
+const findBlockedFilterOnSubject = ({
+	subject,
+	feature,
+	eventProperties,
+}: {
+	subject: ApiCustomerV5 | ApiEntityV2;
+	feature: Feature;
+	eventProperties?: Record<string, unknown> | null;
+}): UsageLimitFilter | undefined =>
+	subject.billing_controls?.usage_limits?.find(
+		(usageLimit) =>
+			usageLimit.feature_id === feature.id &&
+			usageLimit.enabled !== false &&
+			usageLimit.filter != null &&
+			usageLimitFilterMatchesProperties({
+				filterProperties: usageLimit.filter.properties,
+				eventProperties,
+			}) &&
+			(usageLimit.usage ?? 0) >= usageLimit.limit,
+	)?.filter;
+
 // Subjects must be built via buildEvaluationSubject, or plan-level / percentage
 // caps are invisible here and the allowed -> blocked transition never fires.
 export const checkLimitReached = async ({
@@ -103,25 +150,7 @@ export const checkLimitReached = async ({
 		if (!oldResult.allowed || newResult.allowed) return;
 
 		const blockedByUsageLimit = newResult.limitType === "usage_limit";
-
-		// When the blocking cap is a filtered usage limit, attach its filter so
-		// the receiver knows WHICH slice (e.g. which API key) hit its cap.
-		const blockedFilter =
-			blockedByUsageLimit && eventProperties
-				? newEvalSubject.billing_controls?.usage_limits?.find(
-						(usageLimit) =>
-							usageLimit.feature_id === feature.id &&
-							usageLimit.enabled !== false &&
-							usageLimit.filter != null &&
-							usageLimitFilterMatchesProperties({
-								filterProperties: usageLimit.filter.properties,
-								eventProperties,
-							}) &&
-							(usageLimit.usage ?? 0) >= usageLimit.limit,
-					)?.filter
-				: undefined;
-
-		const usageLimitBlock =
+		const blocking =
 			blockedByUsageLimit && newFullSubject
 				? findBlockingUsageLimit({
 						ctx,
@@ -131,6 +160,15 @@ export const checkLimitReached = async ({
 						now,
 					})
 				: undefined;
+		const blockedFilter =
+			blocking?.filter ??
+			(blockedByUsageLimit && eventProperties
+				? findBlockedFilterOnSubject({
+						subject: newEvalSubject,
+						feature,
+						eventProperties,
+					})
+				: undefined);
 
 		const customerId = newFullCus.id || newFullCus.internal_id;
 		const tags = fullCustomerToTags({ fullCustomer: newFullCus });
@@ -144,7 +182,7 @@ export const checkLimitReached = async ({
 				limit_type: newResult.limitType ?? "included",
 				...(entityId && { entity_id: entityId }),
 				...(blockedFilter && { filter: blockedFilter }),
-				...(usageLimitBlock && { usage_limit: usageLimitBlock }),
+				...(blocking && { usage_limit: blocking.block }),
 			},
 			tags,
 		});

server/tests/integration/balances/track/limit-reached/limit-reached-usage-limit-block.test.ts

@@ -12,12 +12,7 @@
  */
 
 import { afterAll, beforeAll, expect, test } from "bun:test";
-import {
-	ApiVersion,
-	EntInterval,
-	getUsageWindowBounds,
-	ResetInterval,
-} from "@autumn/shared";
+import { ApiVersion, ResetInterval } from "@autumn/shared";
 import {
 	getTestSvixAppId,
 	setupWebhookTest,
@@ -33,8 +28,10 @@ import { initScenario, s } from "@tests/utils/testInitUtils/initScenario.js";
 import chalk from "chalk";
 import { AutumnInt } from "@/external/autumn/autumnCli.js";
 import { setCustomerUsageLimit } from "../../utils/usage-limit-utils/customerUsageLimitUtils.js";
+import { expectUsageLimitWindowContains } from "../../utils/usage-limit-utils/expectUsageLimitWindowContains.js";
 
 const autumnV2_3 = new AutumnInt({ version: ApiVersion.V2_3 });
+const ONE_DAY_MS = 24 * 60 * 60 * 1000;
 
 type LimitReachedPayload = {
 	type: string;
@@ -108,6 +105,7 @@ test(`${chalk.yellowBright("limit-reached-ul1: a usage_limit block describes the
 		anchor: "utc",
 	});
 
+	const trackedAt = Date.now();
 	await autumnV2_3.track({
 		customer_id: customerId,
 		feature_id: TestFeature.Messages,
@@ -119,19 +117,18 @@ test(`${chalk.yellowBright("limit-reached-ul1: a usage_limit block describes the
 		limitType: "usage_limit",
 	});
 	expect(result).not.toBeNull();
-	const bounds = getUsageWindowBounds({
-		interval: EntInterval.Day,
-		now: Date.now(),
-	});
 	expect(result!.payload.data.filter).toBeUndefined();
-	expect(result!.payload.data.usage_limit).toEqual({
+	expect(result!.payload.data.usage_limit).toMatchObject({
 		limit: 5,
 		interval: "day",
 		anchor: "utc",
 		usage: 5,
 		remaining: 0,
-		window_start_at: bounds.windowStartAt,
-		window_end_at: bounds.windowEndAt,
+	});
+	expectUsageLimitWindowContains({
+		usageLimit: result!.payload.data.usage_limit,
+		at: trackedAt,
+		intervalMs: ONE_DAY_MS,
 	});
 });