feat(balances): describe the blocking cap on limit_reached

balances.limit_reached carries a usage_limit block (limit, interval,
anchor, usage, remaining, window bounds) when a usage limit blocked the
event, resolved from the FullSubject the way alerts resolve it. The
schema also declares the filter field the payload already sent.

Author: charlietlamb

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

@@ -4,12 +4,56 @@ import {
 	apiBalanceToAllowed,
 	type Feature,
 	type FullCustomer,
+	type FullSubject,
 	fullCustomerToTags,
+	fullSubjectToUsageWindowLimits,
+	getCurrentUsageWindowUsage,
+	orgToInStatuses,
+	type UsageLimitWebhookBlock,
 	usageLimitFilterMatchesProperties,
 	WebhookEventType,
 } from "@autumn/shared";
 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. */
+const findBlockingUsageLimit = ({
+	ctx,
+	fullSubject,
+	feature,
+	eventProperties,
+	now,
+}: {
+	ctx: AutumnContext;
+	fullSubject: FullSubject;
+	feature: Feature;
+	eventProperties?: Record<string, unknown> | null;
+	now: number;
+}): UsageLimitWebhookBlock | undefined => {
+	const limits = fullSubjectToUsageWindowLimits({
+		fullSubject,
+		featureIds: [feature.id],
+		features: ctx.features,
+		now,
+		inStatuses: orgToInStatuses({ org: ctx.org }),
+	});
+	const usageWindows = fullSubject.usage_windows ?? [];
+
+	for (const limit of limits) {
+		const appliesToEvent = usageLimitFilterMatchesProperties({
+			filterProperties: limit.filter_properties,
+			eventProperties,
+		});
+		if (!appliesToEvent) continue;
+
+		const usage = getCurrentUsageWindowUsage({ usageWindows, limit, now });
+		if (usage < limit.limit) continue;
+
+		return usageWindowLimitToWebhookBlock({ limit, usage }) ?? undefined;
+	}
+	return undefined;
+};
 
 // Subjects must be built via buildEvaluationSubject, or plan-level / percentage
 // caps are invisible here and the allowed -> blocked transition never fires.
@@ -18,17 +62,21 @@ export const checkLimitReached = async ({
 	oldEvalSubject,
 	newEvalSubject,
 	newFullCus,
+	newFullSubject,
 	feature,
 	entityId,
 	eventProperties,
+	now = Date.now(),
 }: {
 	ctx: AutumnContext;
 	oldEvalSubject: ApiCustomerV5 | ApiEntityV2;
 	newEvalSubject: ApiCustomerV5 | ApiEntityV2;
 	newFullCus: FullCustomer;
+	newFullSubject?: FullSubject;
 	feature: Feature;
 	entityId?: string;
 	eventProperties?: Record<string, unknown> | null;
+	now?: number;
 }) => {
 	try {
 		const oldBalance = oldEvalSubject.balances?.[feature.id];
@@ -54,10 +102,12 @@ 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 =
-			newResult.limitType === "usage_limit" && eventProperties
+			blockedByUsageLimit && eventProperties
 				? newEvalSubject.billing_controls?.usage_limits?.find(
 						(usageLimit) =>
 							usageLimit.feature_id === feature.id &&
@@ -71,6 +121,17 @@ export const checkLimitReached = async ({
 					)?.filter
 				: undefined;
 
+		const usageLimitBlock =
+			blockedByUsageLimit && newFullSubject
+				? findBlockingUsageLimit({
+						ctx,
+						fullSubject: newFullSubject,
+						feature,
+						eventProperties,
+						now,
+					})
+				: undefined;
+
 		const customerId = newFullCus.id || newFullCus.internal_id;
 		const tags = fullCustomerToTags({ fullCustomer: newFullCus });
 
@@ -83,6 +144,7 @@ export const checkLimitReached = async ({
 				limit_type: newResult.limitType ?? "included",
 				...(entityId && { entity_id: entityId }),
 				...(blockedFilter && { filter: blockedFilter }),
+				...(usageLimitBlock && { usage_limit: usageLimitBlock }),
 			},
 			tags,
 		});

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

@@ -110,9 +110,11 @@ export const fireTrackWebhooks = ({
 				oldEvalSubject,
 				newEvalSubject,
 				newFullCus,
+				newFullSubject,
 				feature: affectedFeature,
 				entityId,
 				eventProperties,
+				now,
 			});
 		}
 	})().catch((error) => {

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

@@ -0,0 +1,210 @@
+/**
+ * TDD test for the `usage_limit` block on `balances.limit_reached`.
+ *
+ * Contract under test:
+ *   New types/fields:
+ *     - limit_reached.filter (schema catch-up; already emitted for filtered caps)
+ *     - limit_reached.usage_limit { limit, interval, anchor, usage, remaining, window_start_at, window_end_at }
+ *       present iff limit_type is usage_limit; absent for included / spend_limit / max_purchase
+ *
+ * Pre-impl red: payload has no usage_limit block.
+ * Post-impl green: checkLimitReached reads the resolved window limit off the FullSubject.
+ */
+
+import { afterAll, beforeAll, expect, test } from "bun:test";
+import {
+	ApiVersion,
+	EntInterval,
+	getUsageWindowBounds,
+	ResetInterval,
+} from "@autumn/shared";
+import {
+	getTestSvixAppId,
+	setupWebhookTest,
+	type WebhookTestSetup,
+	waitForWebhook,
+} from "@tests/integration/utils/svixWebhookTestUtils.js";
+import { TestFeature } from "@tests/setup/v2Features.js";
+import { items } from "@tests/utils/fixtures/items.js";
+import { products } from "@tests/utils/fixtures/products.js";
+import { timeout } from "@tests/utils/genUtils.js";
+import ctx from "@tests/utils/testInitUtils/createTestContext.js";
+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";
+
+const autumnV2_3 = new AutumnInt({ version: ApiVersion.V2_3 });
+
+type LimitReachedPayload = {
+	type: string;
+	data: {
+		customer_id: string;
+		feature_id: string;
+		limit_type: string;
+		entity_id?: string;
+		filter?: { properties: Record<string, string> };
+		usage_limit?: {
+			limit: number;
+			interval: string;
+			anchor: string;
+			usage: number;
+			remaining: number;
+			window_start_at: number;
+			window_end_at: number;
+		};
+	};
+};
+
+let webhook: WebhookTestSetup;
+let playToken: string;
+
+beforeAll(async () => {
+	const appId = getTestSvixAppId({ svixConfig: ctx.org.svix_config });
+	webhook = await setupWebhookTest({
+		appId,
+		filterTypes: ["balances.limit_reached"],
+	});
+	playToken = webhook.playToken;
+});
+
+afterAll(async () => {
+	await webhook?.cleanup();
+});
+
+const waitForLimitReached = ({
+	customerId,
+	limitType,
+}: {
+	customerId: string;
+	limitType: string;
+}) =>
+	waitForWebhook<LimitReachedPayload>({
+		token: playToken,
+		predicate: (payload) =>
+			payload.type === "balances.limit_reached" &&
+			payload.data?.customer_id === customerId &&
+			payload.data?.limit_type === limitType,
+		timeoutMs: 15000,
+	});
+
+test(`${chalk.yellowBright("limit-reached-ul1: a usage_limit block describes the cap that blocked")}`, async () => {
+	const customerId = "lr-ul-block-1";
+	const plan = products.base({
+		id: "lr-ul-block",
+		items: [items.monthlyMessages({ includedUsage: 10000 })],
+	});
+	await initScenario({
+		customerId,
+		setup: [s.customer({ testClock: false }), s.products({ list: [plan] })],
+		actions: [s.billing.attach({ productId: plan.id })],
+	});
+	await setCustomerUsageLimit({
+		autumn: autumnV2_3,
+		customerId,
+		featureId: TestFeature.Messages,
+		limit: 5,
+		interval: ResetInterval.Day,
+		anchor: "utc",
+	});
+
+	await autumnV2_3.track({
+		customer_id: customerId,
+		feature_id: TestFeature.Messages,
+		value: 5,
+	});
+
+	const result = await waitForLimitReached({
+		customerId,
+		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({
+		limit: 5,
+		interval: "day",
+		anchor: "utc",
+		usage: 5,
+		remaining: 0,
+		window_start_at: bounds.windowStartAt,
+		window_end_at: bounds.windowEndAt,
+	});
+});
+
+test(`${chalk.yellowBright("limit-reached-ul2: a filtered cap echoes its filter and filtered counter")}`, async () => {
+	const customerId = "lr-ul-filter-1";
+	const plan = products.base({
+		id: "lr-ul-filter",
+		items: [items.monthlyMessages({ includedUsage: 10000 })],
+	});
+	await initScenario({
+		customerId,
+		setup: [s.customer({ testClock: false }), s.products({ list: [plan] })],
+		actions: [s.billing.attach({ productId: plan.id })],
+	});
+	await timeout(2000);
+	await autumnV2_3.customers.update(customerId, {
+		billing_controls: {
+			usage_limits: [
+				{
+					feature_id: TestFeature.Messages,
+					enabled: true,
+					limit: 5,
+					interval: ResetInterval.Day,
+					anchor: "utc",
+					filter: { properties: { apiKeyId: "key-a" } },
+				},
+			],
+		},
+	});
+	await timeout(3000);
+
+	await autumnV2_3.track({
+		customer_id: customerId,
+		feature_id: TestFeature.Messages,
+		value: 5,
+		properties: { apiKeyId: "key-a" },
+	});
+
+	const result = await waitForLimitReached({
+		customerId,
+		limitType: "usage_limit",
+	});
+	expect(result).not.toBeNull();
+	expect(result!.payload.data.filter).toEqual({
+		properties: { apiKeyId: "key-a" },
+	});
+	expect(result!.payload.data.usage_limit?.limit).toBe(5);
+	expect(result!.payload.data.usage_limit?.usage).toBe(5);
+	expect(result!.payload.data.usage_limit?.remaining).toBe(0);
+});
+
+test(`${chalk.yellowBright("limit-reached-ul3: an included-allowance block carries no usage_limit")}`, async () => {
+	const customerId = "lr-ul-included-1";
+	const plan = products.base({
+		id: "lr-ul-included",
+		items: [items.monthlyMessages({ includedUsage: 100 })],
+	});
+	await initScenario({
+		customerId,
+		setup: [s.customer({ testClock: false }), s.products({ list: [plan] })],
+		actions: [s.billing.attach({ productId: plan.id })],
+	});
+
+	await autumnV2_3.track({
+		customer_id: customerId,
+		feature_id: TestFeature.Messages,
+		value: 100,
+	});
+
+	const result = await waitForLimitReached({
+		customerId,
+		limitType: "included",
+	});
+	expect(result).not.toBeNull();
+	expect(result!.payload.data.usage_limit).toBeUndefined();
+});

shared/api/webhooks/balances/balancesLimitReached.ts

@@ -1,4 +1,6 @@
 import { z } from "zod/v4";
+import { UsageLimitFilterSchema } from "../../../models/cusModels/billingControls/usageLimit.js";
+import { UsageLimitWebhookBlockSchema } from "./usageLimitWebhookBlock.js";
 
 export const LimitType = z.enum([
 	"included",
@@ -30,6 +32,14 @@ export const BalancesLimitReachedSchema = z
 			description:
 				"Which limit was hit: included allowance, max purchase cap, spend limit, or a usage-limit billing control.",
 		}),
+		filter: UsageLimitFilterSchema.optional().meta({
+			description:
+				"The filter of the usage limit that blocked, when a filtered cap was hit.",
+		}),
+		usage_limit: UsageLimitWebhookBlockSchema.optional().meta({
+			description:
+				"The usage limit that blocked, with its live window. Present only when limit_type is usage_limit.",
+		}),
 	})
 	.meta({
 		examples: [BALANCES_LIMIT_REACHED_EXAMPLE],