@conquext/observa-core 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/dist/index.d.ts +606 -0
- package/dist/index.js +657 -0
- package/dist/index.js.map +1 -0
- package/package.json +28 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 Rasheed Alabi
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,606 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
|
|
3
|
+
interface UserContext {
|
|
4
|
+
id: string;
|
|
5
|
+
name?: string;
|
|
6
|
+
email?: string;
|
|
7
|
+
team?: string;
|
|
8
|
+
plan?: string;
|
|
9
|
+
}
|
|
10
|
+
interface TaskContext {
|
|
11
|
+
id: string;
|
|
12
|
+
title?: string;
|
|
13
|
+
type?: string;
|
|
14
|
+
priority?: "low" | "medium" | "high" | "critical";
|
|
15
|
+
}
|
|
16
|
+
interface SessionContext {
|
|
17
|
+
id: string;
|
|
18
|
+
conversationId?: string;
|
|
19
|
+
parentCallId?: string;
|
|
20
|
+
}
|
|
21
|
+
interface ObservabilityContext {
|
|
22
|
+
user?: UserContext;
|
|
23
|
+
task?: TaskContext;
|
|
24
|
+
session?: SessionContext;
|
|
25
|
+
labels?: Record<string, string>;
|
|
26
|
+
}
|
|
27
|
+
interface UsageEventInput {
|
|
28
|
+
model: string;
|
|
29
|
+
provider: string;
|
|
30
|
+
requested_model?: string;
|
|
31
|
+
input_tokens: number;
|
|
32
|
+
output_tokens: number;
|
|
33
|
+
total_tokens?: number;
|
|
34
|
+
cost?: number;
|
|
35
|
+
latency_ms: number;
|
|
36
|
+
status: "success" | "error";
|
|
37
|
+
error?: string;
|
|
38
|
+
streaming?: boolean;
|
|
39
|
+
time_to_first_token_ms?: number;
|
|
40
|
+
cache_read_tokens?: number;
|
|
41
|
+
cache_write_tokens?: number;
|
|
42
|
+
context?: ObservabilityContext;
|
|
43
|
+
}
|
|
44
|
+
interface UsageEvent extends UsageEventInput {
|
|
45
|
+
id: string;
|
|
46
|
+
timestamp: Date;
|
|
47
|
+
total_tokens: number;
|
|
48
|
+
cost: number;
|
|
49
|
+
pricing_miss?: boolean;
|
|
50
|
+
}
|
|
51
|
+
interface ExtractedUsage {
|
|
52
|
+
model: string;
|
|
53
|
+
input_tokens: number;
|
|
54
|
+
output_tokens: number;
|
|
55
|
+
cache_read_tokens?: number;
|
|
56
|
+
cache_write_tokens?: number;
|
|
57
|
+
}
|
|
58
|
+
interface TrackedStream<T> extends AsyncIterable<T> {
|
|
59
|
+
getUsage(): Promise<ExtractedUsage>;
|
|
60
|
+
}
|
|
61
|
+
interface ProviderAdapter {
|
|
62
|
+
name: string;
|
|
63
|
+
extractUsage(response: unknown): ExtractedUsage;
|
|
64
|
+
extractStreamUsage(stream: AsyncIterable<unknown>): TrackedStream<unknown>;
|
|
65
|
+
instrumentedMethods: string[];
|
|
66
|
+
}
|
|
67
|
+
interface ModelPricing {
|
|
68
|
+
provider: string;
|
|
69
|
+
input_per_million: number;
|
|
70
|
+
output_per_million: number;
|
|
71
|
+
cache_read_per_million?: number;
|
|
72
|
+
cache_write_per_million?: number;
|
|
73
|
+
}
|
|
74
|
+
interface PricingTable {
|
|
75
|
+
models: Record<string, ModelPricing>;
|
|
76
|
+
updatedAt: string;
|
|
77
|
+
}
|
|
78
|
+
type PricingConfig = "builtin" | PricingTable | {
|
|
79
|
+
base: "builtin";
|
|
80
|
+
overrides: Record<string, ModelPricing>;
|
|
81
|
+
};
|
|
82
|
+
interface BatchConfig {
|
|
83
|
+
maxSize: number;
|
|
84
|
+
flushInterval: number;
|
|
85
|
+
}
|
|
86
|
+
type BudgetWindow = "hourly" | "daily" | "monthly" | "total";
|
|
87
|
+
interface BudgetLimits {
|
|
88
|
+
hourly?: number;
|
|
89
|
+
daily?: number;
|
|
90
|
+
monthly?: number;
|
|
91
|
+
total?: number;
|
|
92
|
+
}
|
|
93
|
+
interface BudgetConfig {
|
|
94
|
+
perUser?: BudgetLimits;
|
|
95
|
+
perTeam?: BudgetLimits;
|
|
96
|
+
perTask?: BudgetLimits;
|
|
97
|
+
enforcement: "hard" | "soft" | "downgrade";
|
|
98
|
+
downgrades?: Record<string, string>;
|
|
99
|
+
downgradeThreshold?: number;
|
|
100
|
+
}
|
|
101
|
+
interface CostThresholdCallback {
|
|
102
|
+
threshold: number;
|
|
103
|
+
handler: (event: UsageEvent) => void;
|
|
104
|
+
}
|
|
105
|
+
interface BudgetCallback {
|
|
106
|
+
hourly?: number;
|
|
107
|
+
daily?: number;
|
|
108
|
+
monthly?: number;
|
|
109
|
+
total?: number;
|
|
110
|
+
handler: (scopeId: string, spent: number, limit: number, window: BudgetWindow) => void;
|
|
111
|
+
}
|
|
112
|
+
interface ErrorSpikeCallback {
|
|
113
|
+
threshold: number;
|
|
114
|
+
window: string;
|
|
115
|
+
handler: (model: string, errorRate: number) => void;
|
|
116
|
+
}
|
|
117
|
+
interface CallbackConfig {
|
|
118
|
+
costThreshold?: CostThresholdCallback;
|
|
119
|
+
userBudget?: BudgetCallback;
|
|
120
|
+
taskBudget?: BudgetCallback;
|
|
121
|
+
errorSpike?: ErrorSpikeCallback;
|
|
122
|
+
event?: (event: UsageEvent) => void;
|
|
123
|
+
}
|
|
124
|
+
interface TrackOptions {
|
|
125
|
+
provider: ProviderAdapter;
|
|
126
|
+
context?: ObservabilityContext;
|
|
127
|
+
}
|
|
128
|
+
interface MiddlewareOptions {
|
|
129
|
+
extractContext: (req: unknown) => ObservabilityContext;
|
|
130
|
+
}
|
|
131
|
+
interface ObservatoryConfig {
|
|
132
|
+
backend: StorageBackend;
|
|
133
|
+
pricing?: PricingConfig;
|
|
134
|
+
budgets?: BudgetConfig;
|
|
135
|
+
on?: CallbackConfig;
|
|
136
|
+
disabled?: boolean;
|
|
137
|
+
defaultContext?: ObservabilityContext;
|
|
138
|
+
batching?: Partial<BatchConfig>;
|
|
139
|
+
}
|
|
140
|
+
type AggregateFunction = "sum" | "count" | "avg" | "p50" | "p95" | "p99";
|
|
141
|
+
type AggregateField = "cost" | "input_tokens" | "output_tokens" | "total_tokens" | "latency_ms";
|
|
142
|
+
type GroupByField = "model" | "provider" | "user" | "task" | "team";
|
|
143
|
+
type QueryInterval = "1m" | "5m" | "1h" | "1d";
|
|
144
|
+
interface UsageQuery {
|
|
145
|
+
user?: string;
|
|
146
|
+
task?: string;
|
|
147
|
+
session?: string;
|
|
148
|
+
model?: string;
|
|
149
|
+
provider?: string;
|
|
150
|
+
labels?: Record<string, string>;
|
|
151
|
+
from: Date;
|
|
152
|
+
to: Date;
|
|
153
|
+
aggregate?: {
|
|
154
|
+
fn: AggregateFunction;
|
|
155
|
+
field: AggregateField;
|
|
156
|
+
groupBy?: GroupByField[];
|
|
157
|
+
interval?: QueryInterval;
|
|
158
|
+
};
|
|
159
|
+
}
|
|
160
|
+
interface StorageBackend {
|
|
161
|
+
write(events: UsageEvent[]): Promise<void>;
|
|
162
|
+
query(query: UsageQuery): Promise<UsageEvent[]>;
|
|
163
|
+
close(): Promise<void>;
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
declare const UserContextSchema: z.ZodObject<{
|
|
167
|
+
id: z.ZodString;
|
|
168
|
+
name: z.ZodOptional<z.ZodString>;
|
|
169
|
+
email: z.ZodOptional<z.ZodString>;
|
|
170
|
+
team: z.ZodOptional<z.ZodString>;
|
|
171
|
+
plan: z.ZodOptional<z.ZodString>;
|
|
172
|
+
}, "strip", z.ZodTypeAny, {
|
|
173
|
+
id: string;
|
|
174
|
+
team?: string | undefined;
|
|
175
|
+
name?: string | undefined;
|
|
176
|
+
email?: string | undefined;
|
|
177
|
+
plan?: string | undefined;
|
|
178
|
+
}, {
|
|
179
|
+
id: string;
|
|
180
|
+
team?: string | undefined;
|
|
181
|
+
name?: string | undefined;
|
|
182
|
+
email?: string | undefined;
|
|
183
|
+
plan?: string | undefined;
|
|
184
|
+
}>;
|
|
185
|
+
declare const TaskContextSchema: z.ZodObject<{
|
|
186
|
+
id: z.ZodString;
|
|
187
|
+
title: z.ZodOptional<z.ZodString>;
|
|
188
|
+
type: z.ZodOptional<z.ZodString>;
|
|
189
|
+
priority: z.ZodOptional<z.ZodEnum<["low", "medium", "high", "critical"]>>;
|
|
190
|
+
}, "strip", z.ZodTypeAny, {
|
|
191
|
+
id: string;
|
|
192
|
+
type?: string | undefined;
|
|
193
|
+
title?: string | undefined;
|
|
194
|
+
priority?: "low" | "medium" | "high" | "critical" | undefined;
|
|
195
|
+
}, {
|
|
196
|
+
id: string;
|
|
197
|
+
type?: string | undefined;
|
|
198
|
+
title?: string | undefined;
|
|
199
|
+
priority?: "low" | "medium" | "high" | "critical" | undefined;
|
|
200
|
+
}>;
|
|
201
|
+
declare const SessionContextSchema: z.ZodObject<{
|
|
202
|
+
id: z.ZodString;
|
|
203
|
+
conversationId: z.ZodOptional<z.ZodString>;
|
|
204
|
+
parentCallId: z.ZodOptional<z.ZodString>;
|
|
205
|
+
}, "strip", z.ZodTypeAny, {
|
|
206
|
+
id: string;
|
|
207
|
+
conversationId?: string | undefined;
|
|
208
|
+
parentCallId?: string | undefined;
|
|
209
|
+
}, {
|
|
210
|
+
id: string;
|
|
211
|
+
conversationId?: string | undefined;
|
|
212
|
+
parentCallId?: string | undefined;
|
|
213
|
+
}>;
|
|
214
|
+
declare const ObservabilityContextSchema: z.ZodObject<{
|
|
215
|
+
user: z.ZodOptional<z.ZodObject<{
|
|
216
|
+
id: z.ZodString;
|
|
217
|
+
name: z.ZodOptional<z.ZodString>;
|
|
218
|
+
email: z.ZodOptional<z.ZodString>;
|
|
219
|
+
team: z.ZodOptional<z.ZodString>;
|
|
220
|
+
plan: z.ZodOptional<z.ZodString>;
|
|
221
|
+
}, "strip", z.ZodTypeAny, {
|
|
222
|
+
id: string;
|
|
223
|
+
team?: string | undefined;
|
|
224
|
+
name?: string | undefined;
|
|
225
|
+
email?: string | undefined;
|
|
226
|
+
plan?: string | undefined;
|
|
227
|
+
}, {
|
|
228
|
+
id: string;
|
|
229
|
+
team?: string | undefined;
|
|
230
|
+
name?: string | undefined;
|
|
231
|
+
email?: string | undefined;
|
|
232
|
+
plan?: string | undefined;
|
|
233
|
+
}>>;
|
|
234
|
+
task: z.ZodOptional<z.ZodObject<{
|
|
235
|
+
id: z.ZodString;
|
|
236
|
+
title: z.ZodOptional<z.ZodString>;
|
|
237
|
+
type: z.ZodOptional<z.ZodString>;
|
|
238
|
+
priority: z.ZodOptional<z.ZodEnum<["low", "medium", "high", "critical"]>>;
|
|
239
|
+
}, "strip", z.ZodTypeAny, {
|
|
240
|
+
id: string;
|
|
241
|
+
type?: string | undefined;
|
|
242
|
+
title?: string | undefined;
|
|
243
|
+
priority?: "low" | "medium" | "high" | "critical" | undefined;
|
|
244
|
+
}, {
|
|
245
|
+
id: string;
|
|
246
|
+
type?: string | undefined;
|
|
247
|
+
title?: string | undefined;
|
|
248
|
+
priority?: "low" | "medium" | "high" | "critical" | undefined;
|
|
249
|
+
}>>;
|
|
250
|
+
session: z.ZodOptional<z.ZodObject<{
|
|
251
|
+
id: z.ZodString;
|
|
252
|
+
conversationId: z.ZodOptional<z.ZodString>;
|
|
253
|
+
parentCallId: z.ZodOptional<z.ZodString>;
|
|
254
|
+
}, "strip", z.ZodTypeAny, {
|
|
255
|
+
id: string;
|
|
256
|
+
conversationId?: string | undefined;
|
|
257
|
+
parentCallId?: string | undefined;
|
|
258
|
+
}, {
|
|
259
|
+
id: string;
|
|
260
|
+
conversationId?: string | undefined;
|
|
261
|
+
parentCallId?: string | undefined;
|
|
262
|
+
}>>;
|
|
263
|
+
labels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
|
|
264
|
+
}, "strip", z.ZodTypeAny, {
|
|
265
|
+
user?: {
|
|
266
|
+
id: string;
|
|
267
|
+
team?: string | undefined;
|
|
268
|
+
name?: string | undefined;
|
|
269
|
+
email?: string | undefined;
|
|
270
|
+
plan?: string | undefined;
|
|
271
|
+
} | undefined;
|
|
272
|
+
task?: {
|
|
273
|
+
id: string;
|
|
274
|
+
type?: string | undefined;
|
|
275
|
+
title?: string | undefined;
|
|
276
|
+
priority?: "low" | "medium" | "high" | "critical" | undefined;
|
|
277
|
+
} | undefined;
|
|
278
|
+
session?: {
|
|
279
|
+
id: string;
|
|
280
|
+
conversationId?: string | undefined;
|
|
281
|
+
parentCallId?: string | undefined;
|
|
282
|
+
} | undefined;
|
|
283
|
+
labels?: Record<string, string> | undefined;
|
|
284
|
+
}, {
|
|
285
|
+
user?: {
|
|
286
|
+
id: string;
|
|
287
|
+
team?: string | undefined;
|
|
288
|
+
name?: string | undefined;
|
|
289
|
+
email?: string | undefined;
|
|
290
|
+
plan?: string | undefined;
|
|
291
|
+
} | undefined;
|
|
292
|
+
task?: {
|
|
293
|
+
id: string;
|
|
294
|
+
type?: string | undefined;
|
|
295
|
+
title?: string | undefined;
|
|
296
|
+
priority?: "low" | "medium" | "high" | "critical" | undefined;
|
|
297
|
+
} | undefined;
|
|
298
|
+
session?: {
|
|
299
|
+
id: string;
|
|
300
|
+
conversationId?: string | undefined;
|
|
301
|
+
parentCallId?: string | undefined;
|
|
302
|
+
} | undefined;
|
|
303
|
+
labels?: Record<string, string> | undefined;
|
|
304
|
+
}>;
|
|
305
|
+
declare const UsageEventInputSchema: z.ZodObject<{
|
|
306
|
+
model: z.ZodString;
|
|
307
|
+
provider: z.ZodString;
|
|
308
|
+
requested_model: z.ZodOptional<z.ZodString>;
|
|
309
|
+
input_tokens: z.ZodNumber;
|
|
310
|
+
output_tokens: z.ZodNumber;
|
|
311
|
+
total_tokens: z.ZodOptional<z.ZodNumber>;
|
|
312
|
+
cost: z.ZodOptional<z.ZodNumber>;
|
|
313
|
+
latency_ms: z.ZodNumber;
|
|
314
|
+
status: z.ZodEnum<["success", "error"]>;
|
|
315
|
+
error: z.ZodOptional<z.ZodString>;
|
|
316
|
+
streaming: z.ZodOptional<z.ZodBoolean>;
|
|
317
|
+
time_to_first_token_ms: z.ZodOptional<z.ZodNumber>;
|
|
318
|
+
cache_read_tokens: z.ZodOptional<z.ZodNumber>;
|
|
319
|
+
cache_write_tokens: z.ZodOptional<z.ZodNumber>;
|
|
320
|
+
context: z.ZodOptional<z.ZodObject<{
|
|
321
|
+
user: z.ZodOptional<z.ZodObject<{
|
|
322
|
+
id: z.ZodString;
|
|
323
|
+
name: z.ZodOptional<z.ZodString>;
|
|
324
|
+
email: z.ZodOptional<z.ZodString>;
|
|
325
|
+
team: z.ZodOptional<z.ZodString>;
|
|
326
|
+
plan: z.ZodOptional<z.ZodString>;
|
|
327
|
+
}, "strip", z.ZodTypeAny, {
|
|
328
|
+
id: string;
|
|
329
|
+
team?: string | undefined;
|
|
330
|
+
name?: string | undefined;
|
|
331
|
+
email?: string | undefined;
|
|
332
|
+
plan?: string | undefined;
|
|
333
|
+
}, {
|
|
334
|
+
id: string;
|
|
335
|
+
team?: string | undefined;
|
|
336
|
+
name?: string | undefined;
|
|
337
|
+
email?: string | undefined;
|
|
338
|
+
plan?: string | undefined;
|
|
339
|
+
}>>;
|
|
340
|
+
task: z.ZodOptional<z.ZodObject<{
|
|
341
|
+
id: z.ZodString;
|
|
342
|
+
title: z.ZodOptional<z.ZodString>;
|
|
343
|
+
type: z.ZodOptional<z.ZodString>;
|
|
344
|
+
priority: z.ZodOptional<z.ZodEnum<["low", "medium", "high", "critical"]>>;
|
|
345
|
+
}, "strip", z.ZodTypeAny, {
|
|
346
|
+
id: string;
|
|
347
|
+
type?: string | undefined;
|
|
348
|
+
title?: string | undefined;
|
|
349
|
+
priority?: "low" | "medium" | "high" | "critical" | undefined;
|
|
350
|
+
}, {
|
|
351
|
+
id: string;
|
|
352
|
+
type?: string | undefined;
|
|
353
|
+
title?: string | undefined;
|
|
354
|
+
priority?: "low" | "medium" | "high" | "critical" | undefined;
|
|
355
|
+
}>>;
|
|
356
|
+
session: z.ZodOptional<z.ZodObject<{
|
|
357
|
+
id: z.ZodString;
|
|
358
|
+
conversationId: z.ZodOptional<z.ZodString>;
|
|
359
|
+
parentCallId: z.ZodOptional<z.ZodString>;
|
|
360
|
+
}, "strip", z.ZodTypeAny, {
|
|
361
|
+
id: string;
|
|
362
|
+
conversationId?: string | undefined;
|
|
363
|
+
parentCallId?: string | undefined;
|
|
364
|
+
}, {
|
|
365
|
+
id: string;
|
|
366
|
+
conversationId?: string | undefined;
|
|
367
|
+
parentCallId?: string | undefined;
|
|
368
|
+
}>>;
|
|
369
|
+
labels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
|
|
370
|
+
}, "strip", z.ZodTypeAny, {
|
|
371
|
+
user?: {
|
|
372
|
+
id: string;
|
|
373
|
+
team?: string | undefined;
|
|
374
|
+
name?: string | undefined;
|
|
375
|
+
email?: string | undefined;
|
|
376
|
+
plan?: string | undefined;
|
|
377
|
+
} | undefined;
|
|
378
|
+
task?: {
|
|
379
|
+
id: string;
|
|
380
|
+
type?: string | undefined;
|
|
381
|
+
title?: string | undefined;
|
|
382
|
+
priority?: "low" | "medium" | "high" | "critical" | undefined;
|
|
383
|
+
} | undefined;
|
|
384
|
+
session?: {
|
|
385
|
+
id: string;
|
|
386
|
+
conversationId?: string | undefined;
|
|
387
|
+
parentCallId?: string | undefined;
|
|
388
|
+
} | undefined;
|
|
389
|
+
labels?: Record<string, string> | undefined;
|
|
390
|
+
}, {
|
|
391
|
+
user?: {
|
|
392
|
+
id: string;
|
|
393
|
+
team?: string | undefined;
|
|
394
|
+
name?: string | undefined;
|
|
395
|
+
email?: string | undefined;
|
|
396
|
+
plan?: string | undefined;
|
|
397
|
+
} | undefined;
|
|
398
|
+
task?: {
|
|
399
|
+
id: string;
|
|
400
|
+
type?: string | undefined;
|
|
401
|
+
title?: string | undefined;
|
|
402
|
+
priority?: "low" | "medium" | "high" | "critical" | undefined;
|
|
403
|
+
} | undefined;
|
|
404
|
+
session?: {
|
|
405
|
+
id: string;
|
|
406
|
+
conversationId?: string | undefined;
|
|
407
|
+
parentCallId?: string | undefined;
|
|
408
|
+
} | undefined;
|
|
409
|
+
labels?: Record<string, string> | undefined;
|
|
410
|
+
}>>;
|
|
411
|
+
}, "strip", z.ZodTypeAny, {
|
|
412
|
+
input_tokens: number;
|
|
413
|
+
output_tokens: number;
|
|
414
|
+
latency_ms: number;
|
|
415
|
+
model: string;
|
|
416
|
+
provider: string;
|
|
417
|
+
status: "success" | "error";
|
|
418
|
+
error?: string | undefined;
|
|
419
|
+
cost?: number | undefined;
|
|
420
|
+
total_tokens?: number | undefined;
|
|
421
|
+
requested_model?: string | undefined;
|
|
422
|
+
streaming?: boolean | undefined;
|
|
423
|
+
time_to_first_token_ms?: number | undefined;
|
|
424
|
+
cache_read_tokens?: number | undefined;
|
|
425
|
+
cache_write_tokens?: number | undefined;
|
|
426
|
+
context?: {
|
|
427
|
+
user?: {
|
|
428
|
+
id: string;
|
|
429
|
+
team?: string | undefined;
|
|
430
|
+
name?: string | undefined;
|
|
431
|
+
email?: string | undefined;
|
|
432
|
+
plan?: string | undefined;
|
|
433
|
+
} | undefined;
|
|
434
|
+
task?: {
|
|
435
|
+
id: string;
|
|
436
|
+
type?: string | undefined;
|
|
437
|
+
title?: string | undefined;
|
|
438
|
+
priority?: "low" | "medium" | "high" | "critical" | undefined;
|
|
439
|
+
} | undefined;
|
|
440
|
+
session?: {
|
|
441
|
+
id: string;
|
|
442
|
+
conversationId?: string | undefined;
|
|
443
|
+
parentCallId?: string | undefined;
|
|
444
|
+
} | undefined;
|
|
445
|
+
labels?: Record<string, string> | undefined;
|
|
446
|
+
} | undefined;
|
|
447
|
+
}, {
|
|
448
|
+
input_tokens: number;
|
|
449
|
+
output_tokens: number;
|
|
450
|
+
latency_ms: number;
|
|
451
|
+
model: string;
|
|
452
|
+
provider: string;
|
|
453
|
+
status: "success" | "error";
|
|
454
|
+
error?: string | undefined;
|
|
455
|
+
cost?: number | undefined;
|
|
456
|
+
total_tokens?: number | undefined;
|
|
457
|
+
requested_model?: string | undefined;
|
|
458
|
+
streaming?: boolean | undefined;
|
|
459
|
+
time_to_first_token_ms?: number | undefined;
|
|
460
|
+
cache_read_tokens?: number | undefined;
|
|
461
|
+
cache_write_tokens?: number | undefined;
|
|
462
|
+
context?: {
|
|
463
|
+
user?: {
|
|
464
|
+
id: string;
|
|
465
|
+
team?: string | undefined;
|
|
466
|
+
name?: string | undefined;
|
|
467
|
+
email?: string | undefined;
|
|
468
|
+
plan?: string | undefined;
|
|
469
|
+
} | undefined;
|
|
470
|
+
task?: {
|
|
471
|
+
id: string;
|
|
472
|
+
type?: string | undefined;
|
|
473
|
+
title?: string | undefined;
|
|
474
|
+
priority?: "low" | "medium" | "high" | "critical" | undefined;
|
|
475
|
+
} | undefined;
|
|
476
|
+
session?: {
|
|
477
|
+
id: string;
|
|
478
|
+
conversationId?: string | undefined;
|
|
479
|
+
parentCallId?: string | undefined;
|
|
480
|
+
} | undefined;
|
|
481
|
+
labels?: Record<string, string> | undefined;
|
|
482
|
+
} | undefined;
|
|
483
|
+
}>;
|
|
484
|
+
|
|
485
|
+
declare class BudgetExhaustedError extends Error {
|
|
486
|
+
readonly scope: "user" | "team" | "task";
|
|
487
|
+
readonly scopeId: string;
|
|
488
|
+
readonly spent: number;
|
|
489
|
+
readonly limit: number;
|
|
490
|
+
readonly window: BudgetWindow;
|
|
491
|
+
readonly resetAt?: Date;
|
|
492
|
+
constructor(params: {
|
|
493
|
+
scope: "user" | "team" | "task";
|
|
494
|
+
scopeId: string;
|
|
495
|
+
spent: number;
|
|
496
|
+
limit: number;
|
|
497
|
+
window: BudgetWindow;
|
|
498
|
+
resetAt?: Date;
|
|
499
|
+
});
|
|
500
|
+
}
|
|
501
|
+
|
|
502
|
+
declare class PricingEngine {
|
|
503
|
+
private readonly table;
|
|
504
|
+
private readonly sortedModelKeys;
|
|
505
|
+
constructor(config: PricingConfig);
|
|
506
|
+
static resolve(config: PricingConfig): PricingTable;
|
|
507
|
+
calculateCost(event: UsageEventInput): number;
|
|
508
|
+
isPricingMiss(model: string): boolean;
|
|
509
|
+
private findModel;
|
|
510
|
+
}
|
|
511
|
+
|
|
512
|
+
declare class MemoryBackend implements StorageBackend {
|
|
513
|
+
private events;
|
|
514
|
+
write(events: UsageEvent[]): Promise<void>;
|
|
515
|
+
query(query: UsageQuery): Promise<UsageEvent[]>;
|
|
516
|
+
close(): Promise<void>;
|
|
517
|
+
getAll(): UsageEvent[];
|
|
518
|
+
get size(): number;
|
|
519
|
+
}
|
|
520
|
+
|
|
521
|
+
declare const DEFAULT_BATCH_CONFIG: BatchConfig;
|
|
522
|
+
declare class BatchProcessor {
|
|
523
|
+
private buffer;
|
|
524
|
+
private timer;
|
|
525
|
+
private readonly backend;
|
|
526
|
+
private readonly config;
|
|
527
|
+
private closed;
|
|
528
|
+
constructor(backend: StorageBackend, config?: Partial<BatchConfig>);
|
|
529
|
+
add(event: UsageEvent): Promise<void>;
|
|
530
|
+
flush(): Promise<void>;
|
|
531
|
+
close(): Promise<void>;
|
|
532
|
+
get pending(): number;
|
|
533
|
+
private startTimer;
|
|
534
|
+
private stopTimer;
|
|
535
|
+
}
|
|
536
|
+
|
|
537
|
+
declare const ContextManager: {
|
|
538
|
+
get(): ObservabilityContext | undefined;
|
|
539
|
+
run<T>(context: ObservabilityContext, fn: () => T): T;
|
|
540
|
+
merge(base: ObservabilityContext | undefined, override: ObservabilityContext | undefined): ObservabilityContext;
|
|
541
|
+
};
|
|
542
|
+
|
|
543
|
+
declare function defineAdapter(config: {
|
|
544
|
+
name: string;
|
|
545
|
+
instrumentedMethods: string[];
|
|
546
|
+
extractUsage: (response: unknown) => ExtractedUsage;
|
|
547
|
+
extractStreamUsage?: (stream: AsyncIterable<unknown>) => TrackedStream<unknown>;
|
|
548
|
+
}): ProviderAdapter;
|
|
549
|
+
declare function createTrackedStream<T>(source: AsyncIterable<T>, onComplete: (chunks: T[]) => ExtractedUsage): TrackedStream<T>;
|
|
550
|
+
|
|
551
|
+
declare class CallbackDispatcher {
|
|
552
|
+
private readonly config;
|
|
553
|
+
private readonly errorCounts;
|
|
554
|
+
constructor(config: CallbackConfig);
|
|
555
|
+
dispatch(event: UsageEvent): void;
|
|
556
|
+
private checkErrorSpike;
|
|
557
|
+
}
|
|
558
|
+
|
|
559
|
+
interface BudgetCheckResult {
|
|
560
|
+
exceeded: boolean;
|
|
561
|
+
scope?: 'user' | 'team' | 'task';
|
|
562
|
+
scopeId?: string;
|
|
563
|
+
spent?: number;
|
|
564
|
+
limit?: number;
|
|
565
|
+
window?: BudgetWindow;
|
|
566
|
+
downgrade?: string;
|
|
567
|
+
}
|
|
568
|
+
declare class BudgetEngine {
|
|
569
|
+
private readonly config;
|
|
570
|
+
private readonly accumulators;
|
|
571
|
+
constructor(config: BudgetConfig);
|
|
572
|
+
check(context: ObservabilityContext | undefined, model: string, estimatedCost: number): BudgetCheckResult;
|
|
573
|
+
accumulate(event: UsageEvent): void;
|
|
574
|
+
private checkScope;
|
|
575
|
+
private handleExceeded;
|
|
576
|
+
}
|
|
577
|
+
|
|
578
|
+
declare class Observatory {
|
|
579
|
+
private readonly backend;
|
|
580
|
+
private readonly pricing;
|
|
581
|
+
private readonly batch;
|
|
582
|
+
private readonly defaultContext?;
|
|
583
|
+
private readonly disabled;
|
|
584
|
+
private readonly callbacks?;
|
|
585
|
+
private readonly budgetEngine?;
|
|
586
|
+
constructor(config: ObservatoryConfig);
|
|
587
|
+
record(input: UsageEventInput): Promise<void>;
|
|
588
|
+
track<T>(fn: () => Promise<T>, opts: TrackOptions): Promise<T>;
|
|
589
|
+
instrument<T extends object>(client: T, adapter: ProviderAdapter): T;
|
|
590
|
+
withContext<T>(ctx: ObservabilityContext, fn: () => T | Promise<T>): Promise<T>;
|
|
591
|
+
middleware(opts: MiddlewareOptions): (req: unknown, _res: unknown, next: () => void) => void;
|
|
592
|
+
flush(): Promise<void>;
|
|
593
|
+
close(): Promise<void>;
|
|
594
|
+
}
|
|
595
|
+
|
|
596
|
+
declare class NoopObservatory {
|
|
597
|
+
record(): Promise<void>;
|
|
598
|
+
track<T>(fn: () => Promise<T>): Promise<T>;
|
|
599
|
+
instrument<T extends object>(client: T): T;
|
|
600
|
+
withContext<T>(_ctx: ObservabilityContext, fn: () => T | Promise<T>): Promise<T>;
|
|
601
|
+
middleware(): (_req: unknown, _res: unknown, next: () => void) => void;
|
|
602
|
+
flush(): Promise<void>;
|
|
603
|
+
close(): Promise<void>;
|
|
604
|
+
}
|
|
605
|
+
|
|
606
|
+
export { type AggregateField, type AggregateFunction, type BatchConfig, BatchProcessor, type BudgetCallback, type BudgetCheckResult, type BudgetConfig, BudgetEngine, BudgetExhaustedError, type BudgetLimits, type BudgetWindow, type CallbackConfig, CallbackDispatcher, ContextManager, type CostThresholdCallback, DEFAULT_BATCH_CONFIG, type ErrorSpikeCallback, type ExtractedUsage, type GroupByField, MemoryBackend, type MiddlewareOptions, type ModelPricing, NoopObservatory, type ObservabilityContext, ObservabilityContextSchema, Observatory, type ObservatoryConfig, type PricingConfig, PricingEngine, type PricingTable, type ProviderAdapter, type QueryInterval, type SessionContext, SessionContextSchema, type StorageBackend, type TaskContext, TaskContextSchema, type TrackOptions, type TrackedStream, type UsageEvent, type UsageEventInput, UsageEventInputSchema, type UsageQuery, type UserContext, UserContextSchema, createTrackedStream, defineAdapter };
|