Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥
TypeScript aiai-agentsai-crawlerai-scrapingai-searchcrawlerdata-extractionhtml-to-markdownllmmarkdownscraperscrapingweb-crawlerweb-dataweb-data-extractionweb-scraperweb-scrapingweb-searchwebscraping
import { vi, beforeEach } from "vitest";
const mockAggregate = vi.fn<(args: any, options?: any) => Promise<any>>();
const mockEntitiesGet = vi.fn<(args: any) => Promise<any>>();
const mockCustomersGetOrCreate = vi.fn<(args: any) => Promise<any>>();
// Historical aggregations override the Autumn client's global 2s timeout.
const EXPECTED_HISTORICAL_TIMEOUT_MS = 15000;
let autumnClientRef: {
events: { aggregate: typeof mockAggregate };
entities: { get: typeof mockEntitiesGet };
customers: { getOrCreate: typeof mockCustomersGetOrCreate };
} | null = {
events: { aggregate: mockAggregate },
entities: { get: mockEntitiesGet },
customers: { getOrCreate: mockCustomersGetOrCreate },
};
let teamLookup = {
data: { org_id: "org-1" },
error: null as unknown,
};
let apiKeysData: Array<{ id: number; name: string }> = [];
const redisStore = new Map<string, string>();
const mockGetValue = vi.fn<(key: string) => Promise<string | null>>();
const mockSetValue =
vi.fn<(key: string, value: string, expire?: number) => Promise<void>>();
vi.mock("../client", () => ({
get autumnClient() {
return autumnClientRef;
},
}));
vi.mock("../../redis", () => ({
getValue: (key: string) => mockGetValue(key),
setValue: (key: string, value: string, expire?: number) =>
mockSetValue(key, value, expire),
}));
vi.mock("../../../db/connection", () => ({
get dbRr() {
return {
select: () => ({
from: () => ({
where: () => {
// api_keys path awaits the builder directly; teams path calls .limit(1)
const apiKeysPromise = Promise.resolve(apiKeysData);
return Object.assign(apiKeysPromise, {
limit: () =>
Promise.resolve(teamLookup.data ? [teamLookup.data] : []),
});
},
}),
}),
};
},
}));
import {
getTeamBalance,
getTeamHistoricalUsage,
getTeamHistoricalUsageByApiKey,
getTeamHistoricalUsageByEndpoint,
} from "../usage";
beforeEach(() => {
vi.clearAllMocks();
autumnClientRef = {
events: { aggregate: mockAggregate },
entities: { get: mockEntitiesGet },
customers: { getOrCreate: mockCustomersGetOrCreate },
};
teamLookup = { data: { org_id: "org-1" }, error: null };
apiKeysData = [];
redisStore.clear();
mockGetValue.mockImplementation(async key => redisStore.get(key) ?? null);
mockSetValue.mockImplementation(async (key, value) => {
redisStore.set(key, value);
});
});
// ---------------------------------------------------------------------------
// getTeamBalance — covers all four billing-period / planCredits bug fixes
// ---------------------------------------------------------------------------
describe("getTeamBalance", () => {
// Bug 1: Autumn returns currentPeriodStart/End as ms timestamps.
// The old code did `new Date(epoch * 1000)` which produced year ~58000.
// The fix passes them directly to `new Date()`.
it("Bug 1 — passes ms timestamps directly without * 1000", async () => {
const startMs = 1712444524000; // 2024-04-06T21:32:04.000Z
const endMs = 1715036524000; // 2024-05-06T21:32:04.000Z
mockEntitiesGet.mockResolvedValue({
balances: {
CREDITS: {
remaining: 461027,
granted: 500000,
usage: 38973,
unlimited: false,
breakdown: [{ planId: "growth", includedGrant: 500000 }],
},
},
subscriptions: [
{
status: "active",
currentPeriodStart: startMs,
currentPeriodEnd: endMs,
},
],
});
const result = await getTeamBalance("team-1");
expect(result).not.toBeNull();
expect(result!.periodStart).toBe(new Date(startMs).toISOString());
expect(result!.periodEnd).toBe(new Date(endMs).toISOString());
// Confirm dates are in a sane range (not year 58000+)
const startYear = new Date(result!.periodStart!).getFullYear();
const endYear = new Date(result!.periodEnd!).getFullYear();
expect(startYear).toBeGreaterThanOrEqual(2020);
expect(startYear).toBeLessThan(2100);
expect(endYear).toBeGreaterThanOrEqual(2020);
expect(endYear).toBeLessThan(2100);
});
// If Autumn ever switches to seconds, this ensures the code produces a
// sane date from whatever epoch format it receives.
it("Bug 1 — would produce year ~58000 if timestamps were erroneously multiplied by 1000", async () => {
const startMs = 1712444524000;
const endMs = 1715036524000;
// Simulating what the OLD code would have done: new Date(startMs * 1000)
const brokenDate = new Date(startMs * 1000);
expect(brokenDate.getFullYear()).toBeGreaterThan(50000);
// The fix: new Date(startMs) directly
const fixedDate = new Date(startMs);
expect(fixedDate.getFullYear()).toBe(2024);
});
// Bug 2: Autumn uses "active"/"scheduled", not Stripe's "trialing"/"past_due".
// The old filter for "active" || "trialing" || "past_due" missed scheduled subs.
it("Bug 2 — finds subscription with 'active' status (Autumn's status model)", async () => {
mockEntitiesGet.mockResolvedValue({
balances: {
CREDITS: {
remaining: 100,
granted: 1000,
usage: 900,
unlimited: false,
breakdown: [{ planId: "standard", includedGrant: 1000 }],
},
},
subscriptions: [
{
status: "active",
currentPeriodStart: 1712444524000,
currentPeriodEnd: 1715036524000,
},
],
});
const result = await getTeamBalance("team-1");
expect(result).not.toBeNull();
expect(result!.periodStart).not.toBeNull();
expect(result!.periodEnd).not.toBeNull();
});
it("Bug 2 — falls back to any subscription with period timestamps when none is 'active'", async () => {
mockEntitiesGet.mockResolvedValue({
balances: {
CREDITS: {
remaining: 50,
granted: 500,
usage: 450,
unlimited: false,
breakdown: [{ planId: "growth", includedGrant: 500 }],
},
},
subscriptions: [
{
status: "scheduled",
currentPeriodStart: 1712444524000,
currentPeriodEnd: 1715036524000,
},
],
});
const result = await getTeamBalance("team-1");
expect(result).not.toBeNull();
expect(result!.periodStart).toBe(new Date(1712444524000).toISOString());
expect(result!.periodEnd).toBe(new Date(1715036524000).toISOString());
});
it("Bug 2 — old Stripe-only statuses (trialing, past_due) without period timestamps produce null dates", async () => {
mockEntitiesGet.mockResolvedValue({
balances: {
CREDITS: {
remaining: 50,
granted: 500,
usage: 450,
unlimited: false,
breakdown: [{ planId: "free", includedGrant: 500 }],
},
},
subscriptions: [
{
status: "trialing",
// No currentPeriodStart/End set
},
],
});
// No customer fallback needed for balances, but subscriptions fallback is triggered
// because entity has subscriptions with length > 0 but no "active" and no period timestamps
const result = await getTeamBalance("team-1");
expect(result).not.toBeNull();
expect(result!.periodStart).toBeNull();
expect(result!.periodEnd).toBeNull();
});
// Bug 3: Entity-scoped lookups may have CREDITS balance but no subscriptions.
// Subscriptions live at customer level. The old code only fell back when CREDITS
// was missing, leaving billing period dates null.
it("Bug 3 — falls back to customer-level subscriptions when entity has CREDITS but no subscriptions", async () => {
mockEntitiesGet.mockResolvedValue({
balances: {
CREDITS: {
remaining: 99475,
granted: 100000,
usage: 525,
unlimited: false,
breakdown: [
{ planId: "standard", includedGrant: 100000 },
{ planId: null, includedGrant: 525 },
],
},
},
subscriptions: [], // no entity-level subscriptions
});
mockCustomersGetOrCreate.mockResolvedValue({
balances: {
CREDITS: {
remaining: 461027,
granted: 500000,
usage: 38973,
unlimited: false,
breakdown: [{ planId: "growth", includedGrant: 500000 }],
},
},
subscriptions: [
{
status: "active",
currentPeriodStart: 1712444524000,
currentPeriodEnd: 1715036524000,
},
],
});
const result = await getTeamBalance("team-1");
expect(result).not.toBeNull();
// Should use entity-scoped CREDITS balance (Standard plan, ~100K)
expect(result!.remaining).toBe(99475);
expect(result!.planCredits).toBe(100000);
// But should get billing period from customer-level subscriptions
expect(result!.periodStart).toBe(new Date(1712444524000).toISOString());
expect(result!.periodEnd).toBe(new Date(1715036524000).toISOString());
// Verify entity was queried first, then customer for subscriptions
expect(mockEntitiesGet).toHaveBeenCalledWith({
customerId: "org-1",
entityId: "team-1",
});
expect(mockCustomersGetOrCreate).toHaveBeenCalledWith({
customerId: "org-1",
autoEnablePlanId: "free",
});
});
it("Bug 3 — does NOT fall back to customer-level when entity has both CREDITS and subscriptions", async () => {
mockEntitiesGet.mockResolvedValue({
balances: {
CREDITS: {
remaining: 5000,
granted: 10000,
usage: 5000,
unlimited: false,
breakdown: [{ planId: "growth", includedGrant: 10000 }],
},
},
subscriptions: [
{
status: "active",
currentPeriodStart: 1712444524000,
currentPeriodEnd: 1715036524000,
},
],
});
const result = await getTeamBalance("team-1");
expect(result).not.toBeNull();
expect(result!.remaining).toBe(5000);
expect(result!.planCredits).toBe(10000);
expect(result!.periodStart).not.toBeNull();
// Customer-level should NOT be called
expect(mockCustomersGetOrCreate).not.toHaveBeenCalled();
});
// Bug 4: planCredits should only sum breakdown entries with planId set.
// One-off grants (planId: null) were inflating planCredits.
it("Bug 4 — excludes one-off grants (planId: null) from planCredits", async () => {
mockEntitiesGet.mockResolvedValue({
balances: {
CREDITS: {
remaining: 100525,
granted: 100525,
usage: 0,
unlimited: false,
breakdown: [
{ planId: "standard", includedGrant: 100000 },
{ planId: null, includedGrant: 500 }, // one-off promo grant
{ planId: null, includedGrant: 25 }, // another small grant
],
},
},
subscriptions: [
{
status: "active",
currentPeriodStart: 1712444524000,
currentPeriodEnd: 1715036524000,
},
],
});
const result = await getTeamBalance("team-1");
expect(result).not.toBeNull();
// planCredits should be 100,000 (only from planId: "standard")
// NOT 100,525 (which includes the one-off grants)
expect(result!.planCredits).toBe(100000);
// But remaining reflects the full amount including grants
expect(result!.remaining).toBe(100525);
});
it("Bug 4 — sums credits from multiple plans correctly", async () => {
mockEntitiesGet.mockResolvedValue({
balances: {
CREDITS: {
remaining: 600500,
granted: 600500,
usage: 0,
unlimited: false,
breakdown: [
{ planId: "growth", includedGrant: 500000 },
{ planId: "addon-100k", includedGrant: 100000 },
{ planId: null, includedGrant: 500 }, // promo grant
],
},
},
subscriptions: [
{
status: "active",
currentPeriodStart: 1712444524000,
currentPeriodEnd: 1715036524000,
},
],
});
const result = await getTeamBalance("team-1");
expect(result).not.toBeNull();
expect(result!.planCredits).toBe(600000);
});
it("Bug 4 — falls back to granted when no breakdown is present", async () => {
mockEntitiesGet.mockResolvedValue({
balances: {
CREDITS: {
remaining: 1000,
granted: 1000,
usage: 0,
unlimited: false,
// No breakdown array
},
},
subscriptions: [
{
status: "active",
currentPeriodStart: 1712444524000,
currentPeriodEnd: 1715036524000,
},
],
});
const result = await getTeamBalance("team-1");
expect(result).not.toBeNull();
expect(result!.planCredits).toBe(1000);
});
// Full fallback path: entity 404 → customer-level used for everything
it("falls back to customer-level entirely when entity returns 404", async () => {
mockEntitiesGet.mockRejectedValue(
Object.assign(new Error("not found"), { statusCode: 404 }),
);
mockCustomersGetOrCreate.mockResolvedValue({
balances: {
CREDITS: {
remaining: 461027,
granted: 500000,
usage: 38973,
unlimited: false,
breakdown: [{ planId: "growth", includedGrant: 500000 }],
},
},
subscriptions: [
{
status: "active",
currentPeriodStart: 1712444524000,
currentPeriodEnd: 1715036524000,
},
],
});
const result = await getTeamBalance("team-1");
expect(result).not.toBeNull();
expect(result!.remaining).toBe(461027);
expect(result!.planCredits).toBe(500000);
expect(result!.periodStart).toBe(new Date(1712444524000).toISOString());
});
it("returns null when no CREDITS balance exists", async () => {
mockEntitiesGet.mockResolvedValue({
balances: {},
subscriptions: [],
});
mockCustomersGetOrCreate.mockResolvedValue({
balances: {},
subscriptions: [],
});
const result = await getTeamBalance("team-1");
expect(result).toBeNull();
});
// Bug 5: Yearly plans have currentPeriodStart/End = null on the subscription.
// The fix derives billing period from the balance's nextResetAt + reset interval.
it("Bug 5 — derives billing period from nextResetAt for yearly plans with monthly reset", async () => {
const nextResetAt = 1777787407000; // 2026-05-03T05:50:07.000Z
mockEntitiesGet.mockResolvedValue({
balances: {
CREDITS: {
remaining: 100525,
granted: 100525,
usage: 0,
unlimited: false,
nextResetAt,
breakdown: [
{
planId: "standard_yearly",
includedGrant: 100000,
reset: { interval: "month", resetsAt: nextResetAt },
},
{
planId: null,
includedGrant: 525,
reset: { interval: "one_off", resetsAt: null },
},
],
},
},
subscriptions: [
{
status: "active",
currentPeriodStart: null,
currentPeriodEnd: null,
},
],
});
const result = await getTeamBalance("team-1");
expect(result).not.toBeNull();
expect(result!.periodEnd).toBe(new Date(nextResetAt).toISOString());
// Monthly reset: start should be 1 month before end
expect(result!.periodStart).toBe("2026-04-03T05:50:07.000Z");
expect(result!.periodEnd).toBe("2026-05-03T05:50:07.000Z");
expect(result!.planCredits).toBe(100000);
});
it("Bug 5 — derives billing period from nextResetAt for yearly reset interval", async () => {
const nextResetAt = 1764741007000; // 2025-12-03T05:50:07.000Z
mockEntitiesGet.mockResolvedValue({
balances: {
CREDITS: {
remaining: 500000,
granted: 500000,
usage: 0,
unlimited: false,
nextResetAt,
breakdown: [
{
planId: "growth_yearly",
includedGrant: 500000,
reset: { interval: "year", resetsAt: nextResetAt },
},
],
},
},
subscriptions: [
{
status: "active",
currentPeriodStart: null,
currentPeriodEnd: null,
},
],
});
const result = await getTeamBalance("team-1");
expect(result).not.toBeNull();
expect(result!.periodEnd).toBe(new Date(nextResetAt).toISOString());
// Yearly reset: start should be 1 year before end
expect(result!.periodStart).toBe("2024-12-03T05:50:07.000Z");
expect(result!.periodEnd).toBe("2025-12-03T05:50:07.000Z");
});
it("Bug 5 — clamps day when month has fewer days (Mar 31 - 1 month = Feb 28)", async () => {
const nextResetAt = Date.parse("2026-03-31T12:00:00.000Z");
mockEntitiesGet.mockResolvedValue({
balances: {
CREDITS: {
remaining: 100000,
granted: 100000,
usage: 0,
unlimited: false,
nextResetAt,
breakdown: [
{
planId: "standard_yearly",
includedGrant: 100000,
reset: { interval: "month", resetsAt: nextResetAt },
},
],
},
},
subscriptions: [
{ status: "active", currentPeriodStart: null, currentPeriodEnd: null },
],
});
const result = await getTeamBalance("team-1");
expect(result).not.toBeNull();
expect(result!.periodStart).toBe("2026-02-28T12:00:00.000Z");
expect(result!.periodEnd).toBe("2026-03-31T12:00:00.000Z");
});
it("Bug 5 — clamps day for leap year (Mar 31 - 1 month in leap year = Feb 29)", async () => {
const nextResetAt = Date.parse("2028-03-31T12:00:00.000Z"); // 2028 is a leap year
mockEntitiesGet.mockResolvedValue({
balances: {
CREDITS: {
remaining: 100000,
granted: 100000,
usage: 0,
unlimited: false,
nextResetAt,
breakdown: [
{
planId: "standard_yearly",
includedGrant: 100000,
reset: { interval: "month", resetsAt: nextResetAt },
},
],
},
},
subscriptions: [
{ status: "active", currentPeriodStart: null, currentPeriodEnd: null },
],
});
const result = await getTeamBalance("team-1");
expect(result).not.toBeNull();
expect(result!.periodStart).toBe("2028-02-29T12:00:00.000Z");
expect(result!.periodEnd).toBe("2028-03-31T12:00:00.000Z");
});
it("Bug 5 — clamps day for yearly subtraction (Feb 29 leap year - 1 year = Feb 28)", async () => {
const nextResetAt = Date.parse("2028-02-29T12:00:00.000Z"); // 2028 is leap, 2027 is not
mockEntitiesGet.mockResolvedValue({
balances: {
CREDITS: {
remaining: 500000,
granted: 500000,
usage: 0,
unlimited: false,
nextResetAt,
breakdown: [
{
planId: "growth_yearly",
includedGrant: 500000,
reset: { interval: "year", resetsAt: nextResetAt },
},
],
},
},
subscriptions: [
{ status: "active", currentPeriodStart: null, currentPeriodEnd: null },
],
});
const result = await getTeamBalance("team-1");
expect(result).not.toBeNull();
expect(result!.periodStart).toBe("2027-02-28T12:00:00.000Z");
expect(result!.periodEnd).toBe("2028-02-29T12:00:00.000Z");
});
it("Bug 5 — leaves both period dates null when nextResetAt exists but no valid interval breakdown", async () => {
const nextResetAt = Date.parse("2026-05-03T05:50:07.000Z");
mockEntitiesGet.mockResolvedValue({
balances: {
CREDITS: {
remaining: 500,
granted: 500,
usage: 0,
unlimited: false,
nextResetAt,
breakdown: [
{
planId: null,
includedGrant: 500,
reset: { interval: "one_off", resetsAt: null },
},
],
},
},
subscriptions: [
{ status: "active", currentPeriodStart: null, currentPeriodEnd: null },
],
});
const result = await getTeamBalance("team-1");
expect(result).not.toBeNull();
// Both should be null — not an asymmetric response with only periodEnd set
expect(result!.periodStart).toBeNull();
expect(result!.periodEnd).toBeNull();
});
it("Bug 5 — leaves period null when no nextResetAt and no subscription periods", async () => {
mockEntitiesGet.mockResolvedValue({
balances: {
CREDITS: {
remaining: 1000,
granted: 1000,
usage: 0,
unlimited: false,
breakdown: [{ planId: "free", includedGrant: 1000 }],
},
},
subscriptions: [
{
status: "active",
currentPeriodStart: null,
currentPeriodEnd: null,
},
],
});
const result = await getTeamBalance("team-1");
expect(result).not.toBeNull();
expect(result!.periodStart).toBeNull();
expect(result!.periodEnd).toBeNull();
});
it("returns correct structure with unlimited credits", async () => {
mockEntitiesGet.mockResolvedValue({
balances: {
CREDITS: {
remaining: 0,
granted: 0,
usage: 12345,
unlimited: true,
},
},
subscriptions: [
{
status: "active",
currentPeriodStart: 1712444524000,
currentPeriodEnd: 1715036524000,
},
],
});
const result = await getTeamBalance("team-1");
expect(result).not.toBeNull();
expect(result!.unlimited).toBe(true);
expect(result!.usage).toBe(12345);
});
// Autumn caps `balance.remaining` at 0, so the raw field can't show
// negative balances for teams in overage. We derive the signed value from
// granted - usage instead.
it("returns a negative remaining when usage exceeds granted (overage)", async () => {
mockEntitiesGet.mockResolvedValue({
balances: {
CREDITS: {
remaining: 0,
granted: 25250000,
usage: 29688178,
unlimited: false,
overage_allowed: false,
breakdown: [{ planId: "enterprise", includedGrant: 10000000 }],
},
},
subscriptions: [
{
status: "active",
currentPeriodStart: 1712444524000,
currentPeriodEnd: 1715036524000,
},
],
});
const result = await getTeamBalance("team-1");
expect(result).not.toBeNull();
expect(result!.remaining).toBe(-4438178);
expect(result!.usage).toBe(29688178);
});
});
// ---------------------------------------------------------------------------
// getTeamHistoricalUsage
// ---------------------------------------------------------------------------
describe("getTeamHistoricalUsage", () => {
it("aggregates 90 days of daily usage into calendar-month buckets", async () => {
mockAggregate.mockResolvedValue({
list: [
{
period: Date.parse("2026-03-30T00:00:00.000Z"),
values: { CREDITS: 20 },
},
{
period: Date.parse("2026-03-31T00:00:00.000Z"),
values: { CREDITS: 333 },
},
{
period: Date.parse("2026-04-01T00:00:00.000Z"),
values: { CREDITS: 1 },
},
],
});
await expect(getTeamHistoricalUsage("team-1")).resolves.toEqual([
{
startDate: "2026-03-01T00:00:00.000Z",
endDate: "2026-04-01T00:00:00.000Z",
creditsUsed: 353,
},
{
startDate: "2026-04-01T00:00:00.000Z",
endDate: null,
creditsUsed: 1,
},
]);
expect(mockAggregate).toHaveBeenCalledWith(
expect.objectContaining({
customerId: "org-1",
entityId: "team-1",
featureId: "CREDITS",
range: "90d",
binSize: "day",
}),
expect.objectContaining({ timeoutMs: EXPECTED_HISTORICAL_TIMEOUT_MS }),
);
});
// The aggregate is scoped strictly to the team's entity. When the entity is
// missing the team simply has no usage of its own — we return an empty
// history rather than falling back to the org-wide total.
it("returns an empty history (no org fallback) when the entity is missing", async () => {
mockAggregate.mockRejectedValueOnce(
Object.assign(new Error("not found"), { statusCode: 404 }),
);
await expect(getTeamHistoricalUsage("team-1")).resolves.toEqual([]);
// Only the entity-scoped call is made; no customer-level retry.
expect(mockAggregate).toHaveBeenCalledTimes(1);
expect(mockAggregate).toHaveBeenNthCalledWith(
1,
expect.objectContaining({
customerId: "org-1",
entityId: "team-1",
range: "90d",
binSize: "day",
}),
expect.objectContaining({ timeoutMs: EXPECTED_HISTORICAL_TIMEOUT_MS }),
);
});
it("rethrows non-404 aggregate errors", async () => {
mockAggregate.mockRejectedValueOnce(
Object.assign(new Error("boom"), { statusCode: 500 }),
);
await expect(getTeamHistoricalUsage("team-1")).rejects.toThrow("boom");
});
it("uses the next calendar month as endDate when a month has zero usage", async () => {
mockAggregate.mockResolvedValue({
list: [
{
period: Date.parse("2026-01-31T00:00:00.000Z"),
values: { CREDITS: 12 },
},
{
period: Date.parse("2026-03-01T00:00:00.000Z"),
values: { CREDITS: 7 },
},
],
});
await expect(getTeamHistoricalUsage("team-1")).resolves.toEqual([
{
startDate: "2026-01-01T00:00:00.000Z",
endDate: "2026-02-01T00:00:00.000Z",
creditsUsed: 12,
},
{
startDate: "2026-03-01T00:00:00.000Z",
endDate: null,
creditsUsed: 7,
},
]);
});
it("buckets daily usage by UTC day when asked for day bins", async () => {
mockAggregate.mockResolvedValue({
list: [
{
period: Date.parse("2026-03-30T00:00:00.000Z"),
values: { CREDITS: 20 },
},
{
period: Date.parse("2026-04-01T00:00:00.000Z"),
values: { CREDITS: 1 },
},
],
});
await expect(getTeamHistoricalUsage("team-1", "day")).resolves.toEqual([
{
startDate: "2026-03-30T00:00:00.000Z",
endDate: "2026-03-31T00:00:00.000Z",
creditsUsed: 20,
},
{
startDate: "2026-04-01T00:00:00.000Z",
endDate: null,
creditsUsed: 1,
},
]);
expect(mockAggregate).toHaveBeenCalledWith(
expect.objectContaining({
featureId: "CREDITS",
range: "90d",
binSize: "day",
}),
expect.anything(),
);
});
});
// The byApiKey breakdown asks Autumn for fixed 7-day slices. At this instant
// the 90-day window starts 2026-01-20T00:00Z; the epoch-aligned slices run
// from 2026-01-15 to 2026-04-23, fourteen of them, and the one holding today
// is 2026-04-16..2026-04-23.
const BY_API_KEY_NOW = "2026-04-20T12:00:00.000Z";
const BY_API_KEY_SLICE_COUNT = 14;
const CURRENT_SLICE_START = Date.parse("2026-04-16T00:00:00.000Z");
/**
* Stands in for Autumn's grouped aggregate: answers each call with the days
* inside its `customRange`. The end is inclusive, so a bin that sits exactly
* on a slice boundary comes back from both neighbouring slices.
*/
function autumnServesDays(
days: Array<{ day: string; credits: Record<string, number> }>,
) {
mockAggregate.mockImplementation(async (args: any) => ({
list: days
.map(d => ({
period: Date.parse(d.day),
grouped_values: { CREDITS: d.credits },
}))
.filter(
entry =>
entry.period >= args.customRange.start &&
entry.period <= args.customRange.end,
),
}));
}
describe("getTeamHistoricalUsageByApiKey", () => {
beforeEach(() => {
vi.useFakeTimers({ toFake: ["Date"] });
vi.setSystemTime(new Date(BY_API_KEY_NOW));
});
afterEach(() => {
vi.useRealTimers();
});
it("aggregates daily grouped usage into calendar-month buckets", async () => {
apiKeysData = [
{ id: 101, name: "Default" },
{ id: 202, name: "postman" },
];
autumnServesDays([
{ day: "2026-03-30T00:00:00.000Z", credits: { "101": 10, "202": 3 } },
{ day: "2026-03-31T00:00:00.000Z", credits: { "101": 26 } },
{ day: "2026-04-02T00:00:00.000Z", credits: { "202": 5 } },
]);
await expect(getTeamHistoricalUsageByApiKey("team-1")).resolves.toEqual([
{
startDate: "2026-03-01T00:00:00.000Z",
endDate: "2026-04-01T00:00:00.000Z",
apiKey: "Default",
creditsUsed: 36,
},
{
startDate: "2026-03-01T00:00:00.000Z",
endDate: "2026-04-01T00:00:00.000Z",
apiKey: "postman",
creditsUsed: 3,
},
{
startDate: "2026-04-01T00:00:00.000Z",
endDate: null,
apiKey: "postman",
creditsUsed: 5,
},
]);
});
it("buckets grouped usage by UTC day when asked for day bins", async () => {
apiKeysData = [
{ id: 101, name: "Default" },
{ id: 202, name: "postman" },
];
autumnServesDays([
{ day: "2026-03-31T00:00:00.000Z", credits: { "101": 26, "202": 3 } },
{ day: "2026-04-02T00:00:00.000Z", credits: { "202": 5 } },
]);
await expect(
getTeamHistoricalUsageByApiKey("team-1", "day"),
).resolves.toEqual([
{
startDate: "2026-03-31T00:00:00.000Z",
endDate: "2026-04-01T00:00:00.000Z",
apiKey: "Default",
creditsUsed: 26,
},
{
startDate: "2026-03-31T00:00:00.000Z",
endDate: "2026-04-01T00:00:00.000Z",
apiKey: "postman",
creditsUsed: 3,
},
{
startDate: "2026-04-02T00:00:00.000Z",
endDate: null,
apiKey: "postman",
creditsUsed: 5,
},
]);
});
it("asks Autumn for 7-day slices across the window, today's slice first", async () => {
autumnServesDays([]);
await getTeamHistoricalUsageByApiKey("team-1");
expect(mockAggregate).toHaveBeenCalledTimes(BY_API_KEY_SLICE_COUNT);
const [firstArgs] = mockAggregate.mock.calls[0];
expect(firstArgs.customRange).toEqual({
start: CURRENT_SLICE_START,
end: Date.parse(BY_API_KEY_NOW),
});
for (const [args, options] of mockAggregate.mock.calls) {
expect(args).toEqual(
expect.objectContaining({
customerId: "org-1",
entityId: "team-1",
featureId: "CREDITS",
binSize: "day",
groupBy: "properties.apiKeyId",
maxGroups: 250,
}),
);
expect(args.range).toBeUndefined();
expect(options).toEqual(
expect.objectContaining({
timeoutMs: EXPECTED_HISTORICAL_TIMEOUT_MS,
retryCodes: ["429"],
}),
);
}
// The slices tile the window with no gap and no overlap.
const ranges = mockAggregate.mock.calls
.map(([args]) => args.customRange)
.sort((a, b) => a.start - b.start);
expect(ranges[0].start).toBe(Date.parse("2026-01-15T00:00:00.000Z"));
for (let i = 1; i < ranges.length; i++) {
expect(ranges[i].start).toBe(ranges[i - 1].end);
expect(ranges[i - 1].end - ranges[i - 1].start).toBe(7 * 86_400_000);
}
});
it("counts a day on a slice boundary once, though both slices return it", async () => {
apiKeysData = [{ id: 101, name: "Default" }];
// 2026-03-26 is where one slice ends and the next begins.
autumnServesDays([
{ day: "2026-03-26T00:00:00.000Z", credits: { "101": 5 } },
]);
await expect(getTeamHistoricalUsageByApiKey("team-1")).resolves.toEqual([
{
startDate: "2026-03-01T00:00:00.000Z",
endDate: null,
apiKey: "Default",
creditsUsed: 5,
},
]);
});
it("leaves out days before the window that the oldest slice returns", async () => {
apiKeysData = [{ id: 101, name: "Default" }];
autumnServesDays([
{ day: "2026-01-16T00:00:00.000Z", credits: { "101": 1000 } },
{ day: "2026-01-20T00:00:00.000Z", credits: { "101": 4 } },
]);
await expect(getTeamHistoricalUsageByApiKey("team-1")).resolves.toEqual([
{
startDate: "2026-01-01T00:00:00.000Z",
endDate: null,
apiKey: "Default",
creditsUsed: 4,
},
]);
});
it("serves settled slices from the cache on the next request", async () => {
apiKeysData = [{ id: 101, name: "Default" }];
autumnServesDays([
{ day: "2026-02-10T00:00:00.000Z", credits: { "101": 7 } },
{ day: "2026-04-17T00:00:00.000Z", credits: { "101": 2 } },
]);
const first = await getTeamHistoricalUsageByApiKey("team-1");
expect(mockAggregate).toHaveBeenCalledTimes(BY_API_KEY_SLICE_COUNT);
expect(mockSetValue).toHaveBeenCalledTimes(BY_API_KEY_SLICE_COUNT - 1);
for (const [key, , expire] of mockSetValue.mock.calls) {
expect(key).toMatch(/^historical-usage-by-api-key:v1:team-1:\d+$/);
expect(key).not.toContain(String(CURRENT_SLICE_START));
// Settled at least a day after it ends, a slice leaves the window at
// most ~91 days after it ends, so a 90-day TTL outlives its use.
expect(expire).toBe(90 * 24 * 60 * 60);
}
mockAggregate.mockClear();
const second = await getTeamHistoricalUsageByApiKey("team-1");
expect(second).toEqual(first);
expect(mockAggregate).toHaveBeenCalledTimes(1);
expect(mockAggregate.mock.calls[0][0].customRange.start).toBe(
CURRENT_SLICE_START,
);
});
it("keeps asking Autumn for a slice that ended less than a day ago", async () => {
// Ten hours into the 2026-04-16 slice: the 2026-04-09 slice has ended but
// has not settled yet.
vi.setSystemTime(new Date("2026-04-16T10:00:00.000Z"));
const previousSliceStart = Date.parse("2026-04-09T00:00:00.000Z");
autumnServesDays([]);
await getTeamHistoricalUsageByApiKey("team-1");
expect(
mockSetValue.mock.calls.some(([key]) =>
key.endsWith(`:${previousSliceStart}`),
),
).toBe(false);
mockAggregate.mockClear();
await getTeamHistoricalUsageByApiKey("team-1");
expect(
mockAggregate.mock.calls.map(([args]) => args.customRange.start).sort(),
).toEqual([previousSliceStart, CURRENT_SLICE_START]);
});
it("asks Autumn again for a slice whose cache entry is malformed", async () => {
apiKeysData = [{ id: 101, name: "Default" }];
autumnServesDays([
{ day: "2026-02-10T00:00:00.000Z", credits: { "101": 7 } },
]);
mockGetValue.mockResolvedValue(JSON.stringify([{ period: "yesterday" }]));
await expect(getTeamHistoricalUsageByApiKey("team-1")).resolves.toEqual([
{
startDate: "2026-02-01T00:00:00.000Z",
endDate: null,
apiKey: "Default",
creditsUsed: 7,
},
]);
expect(mockAggregate).toHaveBeenCalledTimes(BY_API_KEY_SLICE_COUNT);
});
it("answers from Autumn when the cache cannot be read or written", async () => {
apiKeysData = [{ id: 101, name: "Default" }];
autumnServesDays([
{ day: "2026-02-10T00:00:00.000Z", credits: { "101": 7 } },
]);
mockGetValue.mockRejectedValue(new Error("redis down"));
mockSetValue.mockRejectedValue(new Error("redis down"));
await expect(getTeamHistoricalUsageByApiKey("team-1")).resolves.toEqual([
{
startDate: "2026-02-01T00:00:00.000Z",
endDate: null,
apiKey: "Default",
creditsUsed: 7,
},
]);
});
it("fails the request when a slice fails, without starting further slices", async () => {
mockAggregate.mockImplementation(async (args: any) => {
if (args.customRange.start === Date.parse("2026-01-15T00:00:00.000Z")) {
throw Object.assign(new Error("gateway timeout"), { statusCode: 504 });
}
return { list: [] };
});
await expect(getTeamHistoricalUsageByApiKey("team-1")).rejects.toThrow(
"gateway timeout",
);
// Today's slice, the failing oldest slice, and the one other slice that
// was already in flight beside it.
expect(mockAggregate.mock.calls.length).toBeLessThanOrEqual(3);
});
it("rethrows a non-404 error from today's slice", async () => {
mockAggregate.mockRejectedValueOnce(
Object.assign(new Error("boom"), { statusCode: 500 }),
);
await expect(getTeamHistoricalUsageByApiKey("team-1")).rejects.toThrow(
"boom",
);
expect(mockAggregate).toHaveBeenCalledTimes(1);
});
it("labels unresolvable apiKeyIds as 'Unknown' instead of echoing raw values", async () => {
apiKeysData = [];
autumnServesDays([
{
day: "2026-04-15T00:00:00.000Z",
credits: { ba9045fffbd34fc8aabc2597df6ba044: 11, "99999999": 7 },
},
]);
await expect(getTeamHistoricalUsageByApiKey("team-1")).resolves.toEqual([
{
startDate: "2026-04-01T00:00:00.000Z",
endDate: null,
apiKey: "Unknown",
creditsUsed: 18,
},
]);
});
it("uses the next calendar month as endDate for grouped data when a month has zero usage", async () => {
apiKeysData = [{ id: 101, name: "Default" }];
autumnServesDays([
{ day: "2026-01-31T00:00:00.000Z", credits: { "101": 12 } },
{ day: "2026-03-01T00:00:00.000Z", credits: { "101": 7 } },
]);
await expect(getTeamHistoricalUsageByApiKey("team-1")).resolves.toEqual([
{
startDate: "2026-01-01T00:00:00.000Z",
endDate: "2026-02-01T00:00:00.000Z",
apiKey: "Default",
creditsUsed: 12,
},
{
startDate: "2026-03-01T00:00:00.000Z",
endDate: null,
apiKey: "Default",
creditsUsed: 7,
},
]);
});
it("returns an empty history (no org fallback) when the entity is missing", async () => {
mockAggregate.mockRejectedValueOnce(
Object.assign(new Error("not found"), { statusCode: 404 }),
);
await expect(getTeamHistoricalUsageByApiKey("team-1")).resolves.toEqual([]);
// Only today's entity-scoped slice is asked for; no customer-level retry.
expect(mockAggregate).toHaveBeenCalledTimes(1);
expect(mockAggregate).toHaveBeenNthCalledWith(
1,
expect.objectContaining({
customerId: "org-1",
entityId: "team-1",
groupBy: "properties.apiKeyId",
customRange: {
start: CURRENT_SLICE_START,
end: Date.parse(BY_API_KEY_NOW),
},
}),
expect.objectContaining({ timeoutMs: EXPECTED_HISTORICAL_TIMEOUT_MS }),
);
});
});
/**
* Like `autumnServesDays`, but each day carries grouped values per feature,
* the shape Autumn answers with when several features are asked for at once.
*/
function autumnServesGroupedDays(
days: Array<{ day: string; grouped: Record<string, Record<string, number>> }>,
) {
mockAggregate.mockImplementation(async (args: any) => ({
list: days
.map(d => ({ period: Date.parse(d.day), groupedValues: d.grouped }))
.filter(
entry =>
entry.period >= args.customRange.start &&
entry.period <= args.customRange.end,
),
}));
}
describe("getTeamHistoricalUsageByEndpoint", () => {
beforeEach(() => {
vi.useFakeTimers({ toFake: ["Date"] });
vi.setSystemTime(new Date(BY_API_KEY_NOW));
});
afterEach(() => {
vi.useRealTimers();
});
it("asks Autumn for credit and search usage grouped by endpoint, in 7-day slices", async () => {
autumnServesGroupedDays([]);
await getTeamHistoricalUsageByEndpoint("team-1");
expect(mockAggregate).toHaveBeenCalledTimes(BY_API_KEY_SLICE_COUNT);
expect(mockAggregate.mock.calls[0][0].customRange).toEqual({
start: CURRENT_SLICE_START,
end: Date.parse(BY_API_KEY_NOW),
});
for (const [args, options] of mockAggregate.mock.calls) {
expect(args).toEqual(
expect.objectContaining({
customerId: "org-1",
entityId: "team-1",
featureId: ["CREDITS", "SEARCH_CREDITS"],
binSize: "day",
groupBy: "properties.endpoint",
maxGroups: 250,
}),
);
expect(options).toEqual(
expect.objectContaining({
timeoutMs: EXPECTED_HISTORICAL_TIMEOUT_MS,
retryCodes: ["429"],
}),
);
}
});
it("sums each endpoint across features into calendar-month buckets", async () => {
autumnServesGroupedDays([
{
day: "2026-03-30T00:00:00.000Z",
grouped: {
CREDITS: { scrape: 10, crawl: 40 },
SEARCH_CREDITS: { search: 6 },
},
},
{
day: "2026-03-31T00:00:00.000Z",
grouped: { CREDITS: { scrape: 5 }, SEARCH_CREDITS: { search: 2 } },
},
{
day: "2026-04-02T00:00:00.000Z",
grouped: { CREDITS: { scrape: 1 } },
},
]);
await expect(getTeamHistoricalUsageByEndpoint("team-1")).resolves.toEqual([
{
startDate: "2026-03-01T00:00:00.000Z",
endDate: "2026-04-01T00:00:00.000Z",
endpoint: "crawl",
creditsUsed: 40,
},
{
startDate: "2026-03-01T00:00:00.000Z",
endDate: "2026-04-01T00:00:00.000Z",
endpoint: "scrape",
creditsUsed: 15,
},
{
startDate: "2026-03-01T00:00:00.000Z",
endDate: "2026-04-01T00:00:00.000Z",
endpoint: "search",
creditsUsed: 8,
},
{
startDate: "2026-04-01T00:00:00.000Z",
endDate: null,
endpoint: "scrape",
creditsUsed: 1,
},
]);
});
it("buckets endpoint usage by UTC day when asked for day bins", async () => {
autumnServesGroupedDays([
{
day: "2026-04-17T00:00:00.000Z",
grouped: { CREDITS: { scrape: 3 }, SEARCH_CREDITS: { search: 2 } },
},
{
day: "2026-04-19T00:00:00.000Z",
grouped: { CREDITS: { map: 1 } },
},
]);
await expect(
getTeamHistoricalUsageByEndpoint("team-1", "day"),
).resolves.toEqual([
{
startDate: "2026-04-17T00:00:00.000Z",
endDate: "2026-04-18T00:00:00.000Z",
endpoint: "scrape",
creditsUsed: 3,
},
{
startDate: "2026-04-17T00:00:00.000Z",
endDate: "2026-04-18T00:00:00.000Z",
endpoint: "search",
creditsUsed: 2,
},
{
startDate: "2026-04-19T00:00:00.000Z",
endDate: null,
endpoint: "map",
creditsUsed: 1,
},
]);
});
it("labels usage without an endpoint as 'unknown'", async () => {
autumnServesGroupedDays([
{
day: "2026-04-17T00:00:00.000Z",
grouped: { CREDITS: { "": 4, scrape: 1 } },
},
]);
await expect(getTeamHistoricalUsageByEndpoint("team-1")).resolves.toEqual([
{
startDate: "2026-04-01T00:00:00.000Z",
endDate: null,
endpoint: "scrape",
creditsUsed: 1,
},
{
startDate: "2026-04-01T00:00:00.000Z",
endDate: null,
endpoint: "unknown",
creditsUsed: 4,
},
]);
});
it("caches settled slices under its own key, apart from the byApiKey breakdown", async () => {
autumnServesGroupedDays([
{
day: "2026-02-10T00:00:00.000Z",
grouped: { CREDITS: { scrape: 7 } },
},
]);
await getTeamHistoricalUsageByEndpoint("team-1");
expect(mockSetValue).toHaveBeenCalledTimes(BY_API_KEY_SLICE_COUNT - 1);
for (const [key] of mockSetValue.mock.calls) {
expect(key).toMatch(/^historical-usage-by-endpoint:v1:team-1:\d+$/);
}
mockAggregate.mockClear();
autumnServesDays([]);
await getTeamHistoricalUsageByApiKey("team-1");
// Nothing cached for the endpoint breakdown answers the byApiKey one.
expect(mockAggregate).toHaveBeenCalledTimes(BY_API_KEY_SLICE_COUNT);
});
it("returns an empty history (no org fallback) when the entity is missing", async () => {
mockAggregate.mockRejectedValueOnce(
Object.assign(new Error("not found"), { statusCode: 404 }),
);
await expect(getTeamHistoricalUsageByEndpoint("team-1")).resolves.toEqual(
[],
);
expect(mockAggregate).toHaveBeenCalledTimes(1);
});
});
// ---------------------------------------------------------------------------
// Per-call Autumn timeout for the historical aggregations
// ---------------------------------------------------------------------------
// These aggregations bin by day (and optionally group by API key), so Autumn
// walks raw events and the call cost scales with the team's event volume. The
// Autumn client's global 2s timeout is sized for the latency-sensitive balance
// checks, so each historical call must override it or high-volume teams get a
// timeout error surfaced as a 500.
describe("historical usage Autumn timeout override", () => {
it("passes a 15s per-call timeout for the ungrouped aggregate", async () => {
mockAggregate.mockResolvedValue({ list: [] });
await getTeamHistoricalUsage("team-1");
expect(mockAggregate).toHaveBeenCalledTimes(1);
const [, options] = mockAggregate.mock.calls[0];
expect(options).toEqual({ timeoutMs: 15000 });
});
it("passes a 15s per-call timeout for every grouped byApiKey slice", async () => {
mockAggregate.mockResolvedValue({ list: [] });
await getTeamHistoricalUsageByApiKey("team-1");
expect(mockAggregate.mock.calls.length).toBeGreaterThan(1);
for (const [, options] of mockAggregate.mock.calls) {
expect(options?.timeoutMs).toBe(15000);
}
});
it("overrides the Autumn client's global 2s timeout with a larger value", async () => {
mockAggregate.mockResolvedValue({ list: [] });
await getTeamHistoricalUsage("team-1");
await getTeamHistoricalUsageByApiKey("team-1");
expect(mockAggregate.mock.calls.length).toBeGreaterThan(2);
for (const [, options] of mockAggregate.mock.calls) {
expect(options?.timeoutMs).toBeGreaterThan(2000);
}
});
});