Skip to content

Commit bae2ac9

Browse files
author
Zoo (VP)
committed
feat: add usage statistics event store and contracts
1 parent 7918f6b commit bae2ac9

14 files changed

Lines changed: 3857 additions & 0 deletions
Lines changed: 323 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,323 @@
1+
import {
2+
UsageEventStatus,
3+
UsageValueSource,
4+
InclusionRule,
5+
SourcedNumber,
6+
UsageEventV1,
7+
StatsQuery,
8+
StatsBucket,
9+
StatsSnapshot,
10+
} from "../usage-stats.js"
11+
12+
describe("usage-stats schemas", () => {
13+
// ── Enums ────────────────────────────────────────────────────────────
14+
15+
describe("UsageEventStatus", () => {
16+
it("should accept all valid statuses", () => {
17+
expect(UsageEventStatus.parse("completed")).toBe("completed")
18+
expect(UsageEventStatus.parse("failed")).toBe("failed")
19+
expect(UsageEventStatus.parse("cancelled")).toBe("cancelled")
20+
})
21+
22+
it("should reject invalid status", () => {
23+
expect(() => UsageEventStatus.parse("success")).toThrow()
24+
})
25+
})
26+
27+
describe("UsageValueSource", () => {
28+
it("should accept all valid sources", () => {
29+
expect(UsageValueSource.parse("provider")).toBe("provider")
30+
expect(UsageValueSource.parse("estimated")).toBe("estimated")
31+
expect(UsageValueSource.parse("backfilled")).toBe("backfilled")
32+
})
33+
34+
it("should reject invalid source", () => {
35+
expect(() => UsageValueSource.parse("guessed")).toThrow()
36+
})
37+
})
38+
39+
describe("InclusionRule", () => {
40+
it("should accept all valid rules", () => {
41+
expect(InclusionRule.parse("included")).toBe("included")
42+
expect(InclusionRule.parse("excluded")).toBe("excluded")
43+
expect(InclusionRule.parse("unknown")).toBe("unknown")
44+
})
45+
})
46+
47+
// ── SourcedNumber ─────────────────────────────────────────────────────
48+
49+
describe("SourcedNumber", () => {
50+
it("should parse a valid SourcedNumber", () => {
51+
const result = SourcedNumber.parse({ value: 42, source: "provider" })
52+
expect(result).toEqual({ value: 42, source: "provider" })
53+
})
54+
55+
it("should reject missing source", () => {
56+
expect(() => SourcedNumber.parse({ value: 42 })).toThrow()
57+
})
58+
59+
it("should reject missing value", () => {
60+
expect(() => SourcedNumber.parse({ source: "estimated" })).toThrow()
61+
})
62+
})
63+
64+
// ── UsageEventV1 ────────────────────────────────────────────────────────
65+
66+
describe("UsageEventV1", () => {
67+
const validEvent = {
68+
schemaVersion: 1,
69+
eventId: "evt-001",
70+
idempotencyKey: "idem-001",
71+
occurredAt: "2026-07-18T12:00:00.000Z",
72+
timezoneOffsetMinutes: -540,
73+
status: "completed",
74+
attempt: 1,
75+
taskId: "task-001",
76+
provider: "anthropic",
77+
model: "claude-sonnet-4-20250514",
78+
mode: "code",
79+
usage: {
80+
inputTokens: { value: 1000, source: "provider" },
81+
outputTokens: { value: 500, source: "provider" },
82+
costUsd: { value: 0.015, source: "provider" },
83+
},
84+
semantics: {
85+
cacheReadInInput: "included",
86+
cacheWriteInInput: "included",
87+
reasoningInOutput: "excluded",
88+
},
89+
provenance: "live",
90+
}
91+
92+
it("should parse a valid complete event", () => {
93+
const result = UsageEventV1.parse(validEvent)
94+
expect(result.eventId).toBe("evt-001")
95+
expect(result.schemaVersion).toBe(1)
96+
expect(result.usage.inputTokens?.value).toBe(1000)
97+
})
98+
99+
it("should accept optional parentTaskId", () => {
100+
const result = UsageEventV1.parse({ ...validEvent, parentTaskId: "task-000" })
101+
expect(result.parentTaskId).toBe("task-000")
102+
})
103+
104+
it("should work without optional usage fields", () => {
105+
const minimal = { ...validEvent, usage: {} }
106+
const result = UsageEventV1.parse(minimal)
107+
expect(result.usage.inputTokens).toBeUndefined()
108+
})
109+
110+
it("should accept backfilled provenance", () => {
111+
const result = UsageEventV1.parse({ ...validEvent, provenance: "history-backfill" })
112+
expect(result.provenance).toBe("history-backfill")
113+
})
114+
115+
it("should reject schemaVersion !== 1", () => {
116+
expect(() => UsageEventV1.parse({ ...validEvent, schemaVersion: 2 })).toThrow()
117+
})
118+
119+
it("should reject missing semantics", () => {
120+
const { semantics: _semantics, ...withoutSemantics } = validEvent
121+
expect(() => UsageEventV1.parse(withoutSemantics)).toThrow()
122+
})
123+
124+
it("should reject invalid provenance", () => {
125+
expect(() => UsageEventV1.parse({ ...validEvent, provenance: "imported" })).toThrow()
126+
})
127+
128+
it("should reject missing required fields (eventId)", () => {
129+
const { eventId: _eventId, ...withoutEventId } = validEvent
130+
expect(() => UsageEventV1.parse(withoutEventId)).toThrow()
131+
})
132+
133+
it("should reject negative attempt", () => {
134+
// z.number() accepts negatives, but attempt should be >= 0 logically
135+
// This test confirms the schema accepts any number (no min constraint in V1)
136+
const result = UsageEventV1.parse({ ...validEvent, attempt: 0 })
137+
expect(result.attempt).toBe(0)
138+
})
139+
})
140+
141+
// ── StatsQuery ───────────────────────────────────────────────────────
142+
143+
describe("StatsQuery", () => {
144+
it("should parse a valid query with preset", () => {
145+
const result = StatsQuery.parse({
146+
preset: "7d",
147+
timezone: "Asia/Seoul",
148+
groupBy: ["day"],
149+
})
150+
expect(result.preset).toBe("7d")
151+
expect(result.includeCancelled).toBe(false) // default
152+
})
153+
154+
it("should parse a query with from/to range", () => {
155+
const result = StatsQuery.parse({
156+
from: "2026-07-01T00:00:00Z",
157+
to: "2026-07-18T00:00:00Z",
158+
timezone: "UTC",
159+
groupBy: ["provider", "model"],
160+
})
161+
expect(result.from).toBe("2026-07-01T00:00:00Z")
162+
expect(result.groupBy).toHaveLength(2)
163+
})
164+
165+
it("should default includeCancelled to false", () => {
166+
const result = StatsQuery.parse({
167+
timezone: "UTC",
168+
groupBy: [],
169+
})
170+
expect(result.includeCancelled).toBe(false)
171+
})
172+
173+
it("should accept includeCancelled: true", () => {
174+
const result = StatsQuery.parse({
175+
timezone: "UTC",
176+
groupBy: [],
177+
includeCancelled: true,
178+
})
179+
expect(result.includeCancelled).toBe(true)
180+
})
181+
182+
it("should reject more than 3 groupBy dimensions", () => {
183+
expect(() =>
184+
StatsQuery.parse({
185+
timezone: "UTC",
186+
groupBy: ["day", "week", "month", "provider"],
187+
}),
188+
).toThrow()
189+
})
190+
191+
it("should reject invalid preset", () => {
192+
expect(() =>
193+
StatsQuery.parse({
194+
preset: "90d",
195+
timezone: "UTC",
196+
groupBy: [],
197+
}),
198+
).toThrow()
199+
})
200+
201+
it("should reject missing timezone", () => {
202+
expect(() =>
203+
StatsQuery.parse({
204+
groupBy: [],
205+
}),
206+
).toThrow()
207+
})
208+
209+
it("should reject invalid groupBy dimension", () => {
210+
expect(() =>
211+
StatsQuery.parse({
212+
timezone: "UTC",
213+
groupBy: ["hour"],
214+
}),
215+
).toThrow()
216+
})
217+
})
218+
219+
// ── StatsBucket ──────────────────────────────────────────────────────
220+
221+
describe("StatsBucket", () => {
222+
const validBucket = {
223+
key: { day: "2026-07-18" },
224+
events: 10,
225+
completedCalls: 8,
226+
failedCalls: 1,
227+
cancelledCalls: 1,
228+
inputTokens: 5000,
229+
outputTokens: 2500,
230+
cacheReadTokens: 1000,
231+
cacheWriteTokens: 500,
232+
reasoningTokens: 200,
233+
totalTokens: 7500,
234+
costUsd: 0.075,
235+
unknownEventCount: 0,
236+
}
237+
238+
it("should parse a valid bucket", () => {
239+
const result = StatsBucket.parse(validBucket)
240+
expect(result.events).toBe(10)
241+
expect(result.key.day).toBe("2026-07-18")
242+
})
243+
244+
it("should reject missing required numeric field", () => {
245+
const { costUsd: _costUsd, ...withoutCost } = validBucket
246+
expect(() => StatsBucket.parse(withoutCost)).toThrow()
247+
})
248+
249+
it("should accept empty key record", () => {
250+
const result = StatsBucket.parse({ ...validBucket, key: {} })
251+
expect(Object.keys(result.key)).toHaveLength(0)
252+
})
253+
})
254+
255+
// ── StatsSnapshot ─────────────────────────────────────────────────────
256+
257+
describe("StatsSnapshot", () => {
258+
const validQuery = {
259+
timezone: "UTC",
260+
groupBy: ["day"],
261+
}
262+
const validBucket = {
263+
key: { day: "2026-07-18" },
264+
events: 5,
265+
completedCalls: 4,
266+
failedCalls: 1,
267+
cancelledCalls: 0,
268+
inputTokens: 2000,
269+
outputTokens: 1000,
270+
cacheReadTokens: 0,
271+
cacheWriteTokens: 0,
272+
reasoningTokens: 0,
273+
totalTokens: 3000,
274+
costUsd: 0.03,
275+
unknownEventCount: 0,
276+
}
277+
const validSnapshot = {
278+
query: validQuery,
279+
generatedAt: "2026-07-18T12:00:00.000Z",
280+
buckets: [validBucket],
281+
totals: validBucket,
282+
coverage: {
283+
firstEventAt: "2026-07-01T00:00:00.000Z",
284+
lastEventAt: "2026-07-18T12:00:00.000Z",
285+
recordingPaused: false,
286+
backfilledEventCount: 0,
287+
},
288+
}
289+
290+
it("should parse a valid snapshot", () => {
291+
const result = StatsSnapshot.parse(validSnapshot)
292+
expect(result.buckets).toHaveLength(1)
293+
expect(result.coverage.recordingPaused).toBe(false)
294+
})
295+
296+
it("should accept empty buckets array", () => {
297+
const result = StatsSnapshot.parse({ ...validSnapshot, buckets: [] })
298+
expect(result.buckets).toHaveLength(0)
299+
})
300+
301+
it("should accept optional firstEventAt/lastEventAt omitted", () => {
302+
const result = StatsSnapshot.parse({
303+
...validSnapshot,
304+
coverage: {
305+
recordingPaused: true,
306+
backfilledEventCount: 0,
307+
},
308+
})
309+
expect(result.coverage.firstEventAt).toBeUndefined()
310+
expect(result.coverage.lastEventAt).toBeUndefined()
311+
})
312+
313+
it("should reject missing coverage", () => {
314+
const { coverage: _coverage, ...withoutCoverage } = validSnapshot
315+
expect(() => StatsSnapshot.parse(withoutCoverage)).toThrow()
316+
})
317+
318+
it("should reject missing totals", () => {
319+
const { totals: _totals, ...withoutTotals } = validSnapshot
320+
expect(() => StatsSnapshot.parse(withoutTotals)).toThrow()
321+
})
322+
})
323+
})

‎packages/types/src/index.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ export * from "./provider-settings.js"
2323
export * from "./task.js"
2424
export * from "./todo.js"
2525
export * from "./skills.js"
26+
export * from "./usage-stats.js"
2627
export * from "./rules.js"
2728
export * from "./marketplace.js"
2829
export * from "./telemetry.js"

0 commit comments

Comments
 (0)