dsh-token-usage-ledger 0.0.0-stage → 0.0.36
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/CHANGELOG.md +1067 -0
- package/LICENSE +21 -0
- package/README.md +237 -2
- package/cordis.patch.yml +30 -0
- package/lib/client.js +4469 -0
- package/lib/host/aggregate.d.ts +132 -0
- package/lib/host/aggregate.js +840 -0
- package/lib/host/api.d.ts +118 -0
- package/lib/host/api.js +346 -0
- package/lib/host/backfill.d.ts +54 -0
- package/lib/host/backfill.js +265 -0
- package/lib/host/collector.d.ts +139 -0
- package/lib/host/collector.js +441 -0
- package/lib/host/ledger-io.d.ts +125 -0
- package/lib/host/ledger-io.js +211 -0
- package/lib/host/operation-error.d.ts +22 -0
- package/lib/host/operation-error.js +28 -0
- package/lib/host/paths.d.ts +35 -0
- package/lib/host/paths.js +63 -0
- package/lib/host/pricing-module.d.ts +112 -0
- package/lib/host/pricing-module.js +63 -0
- package/lib/host/pricing-modules/deepseek-2026-09-10.d.ts +31 -0
- package/lib/host/pricing-modules/deepseek-2026-09-10.js +67 -0
- package/lib/host/pricing-modules/index.d.ts +27 -0
- package/lib/host/pricing-modules/index.js +30 -0
- package/lib/host/pricing.d.ts +192 -0
- package/lib/host/pricing.js +287 -0
- package/lib/host/records.d.ts +47 -0
- package/lib/host/records.js +116 -0
- package/lib/host/runtime-marker.d.ts +67 -0
- package/lib/host/runtime-marker.js +71 -0
- package/lib/host/schema.d.ts +77 -0
- package/lib/host/schema.js +158 -0
- package/lib/host/store.d.ts +171 -0
- package/lib/host/store.js +337 -0
- package/lib/host/workspace-titles.d.ts +38 -0
- package/lib/host/workspace-titles.js +136 -0
- package/lib/host/zstd.d.ts +41 -0
- package/lib/host/zstd.js +134 -0
- package/lib/index.d.ts +82 -0
- package/lib/index.js +512 -0
- package/lib/shared/format.d.ts +415 -0
- package/lib/shared/format.js +714 -0
- package/lib/shared/protocol.d.ts +646 -0
- package/lib/shared/protocol.js +129 -0
- package/package.json +85 -4
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Pure aggregation from ledger records to the dashboard's summary payload.
|
|
3
|
+
*
|
|
4
|
+
* Kept free of I/O and of the clock so it can be tested directly: the caller
|
|
5
|
+
* supplies `now`, the records, and the active filters.
|
|
6
|
+
*
|
|
7
|
+
* Two attribution rules matter and are applied consistently here:
|
|
8
|
+
*
|
|
9
|
+
* - A **workspace filter** selects whole records (a Turn belongs to exactly one
|
|
10
|
+
* workspace). It accepts either the merged display key (the project's basename,
|
|
11
|
+
* what the dashboard sends after the WSL→Windows path change) or the exact raw
|
|
12
|
+
* path (one physical checkout), so both views stay possible.
|
|
13
|
+
* - A **model filter** selects individual ATTEMPTS, because one Turn can be
|
|
14
|
+
* billed across several routes after a retry or a model switch. Summing only
|
|
15
|
+
* the matching attempts keeps a filtered figure exact instead of apportioning
|
|
16
|
+
* a whole-turn number.
|
|
17
|
+
*
|
|
18
|
+
* The workspace BREAKDOWN additionally merges by display label so a project whose
|
|
19
|
+
* root moved between platforms reads as one row, while each original path stays
|
|
20
|
+
* available under `paths`. The model breakdown ignores attempts that have neither
|
|
21
|
+
* a route nor any usage: they are administrative (an errored turn settled without
|
|
22
|
+
* an assistant/message), not a model's turn.
|
|
23
|
+
*
|
|
24
|
+
* @module dsh-token-usage-ledger/host/aggregate
|
|
25
|
+
*/
|
|
26
|
+
import type { Currency, HealthReport, PricingProvenance, SummaryResponse, TokenBuckets, UsageAttempt, UsageRecord, WorkspacePathUsage } from '../shared/protocol.js';
|
|
27
|
+
/** Zeroed buckets; a fresh object every call so callers cannot alias one. */
|
|
28
|
+
export declare function zeroBuckets(): TokenBuckets;
|
|
29
|
+
/** Scale-invariant route identity used as the model filter key. */
|
|
30
|
+
export declare function routeKeyOf(provider: string, model: string): string;
|
|
31
|
+
/**
|
|
32
|
+
* Label the path shape for the workspace breakdown.
|
|
33
|
+
*
|
|
34
|
+
* Only a display hint: a `unix` shape can be a native Linux path or a WSL path
|
|
35
|
+
* (the UI therefore says "Linux/WSL", not "WSL"). Keeping this out of the merge
|
|
36
|
+
* key means the merge never depends on a guess about the platform.
|
|
37
|
+
*
|
|
38
|
+
* @param workspace - original workspace root, possibly empty.
|
|
39
|
+
* @returns the display platform.
|
|
40
|
+
*/
|
|
41
|
+
export declare function platformOfWorkspacePath(workspace: string): WorkspacePathUsage['platform'];
|
|
42
|
+
/**
|
|
43
|
+
* Resolve the current display title for one raw workspace path.
|
|
44
|
+
*
|
|
45
|
+
* Supplied by the Host's summary builder when the Workspace registry is
|
|
46
|
+
* available; absent in unit tests and in compositions without that service, in
|
|
47
|
+
* which case the stored `workspaceLabel` remains the group identity.
|
|
48
|
+
*/
|
|
49
|
+
export type WorkspaceTitleOf = (workspace: string) => string | undefined;
|
|
50
|
+
/**
|
|
51
|
+
* Identity the workspace breakdown aggregates by.
|
|
52
|
+
*
|
|
53
|
+
* A current Workspace title, when one is available, is the user-facing project
|
|
54
|
+
* identity: it follows a Workspace rename while the directory path stays the
|
|
55
|
+
* same, so old and new labels never become two rows. Without a registry match
|
|
56
|
+
* the stored display label (basename) is used, preserving the pre-registry
|
|
57
|
+
* behavior. A project whose path changed (WSL → Windows) still merges when the
|
|
58
|
+
* current titles match. Records written without a label (hand-written lines,
|
|
59
|
+
* very old formats) fall back to their raw path so they are never merged with
|
|
60
|
+
* an unrelated group; a record with neither is the single unattributed group.
|
|
61
|
+
*
|
|
62
|
+
* @param record - record carrying a workspace and its stored display label.
|
|
63
|
+
* @param titleOf - current-title resolver, or undefined when unavailable.
|
|
64
|
+
* @returns a non-empty group key.
|
|
65
|
+
*/
|
|
66
|
+
export declare function workspaceGroupKeyOf(record: Pick<UsageRecord, 'workspace' | 'workspaceLabel'>, titleOf?: WorkspaceTitleOf): string;
|
|
67
|
+
/**
|
|
68
|
+
* Local calendar day of one instant, as `YYYY-MM-DD`.
|
|
69
|
+
*
|
|
70
|
+
* Days are the machine's local days — "每日消耗" means the user's day, not UTC's
|
|
71
|
+
* — and the Host is the only place a day key is ever produced, so the client
|
|
72
|
+
* never re-derives one and cannot disagree.
|
|
73
|
+
*
|
|
74
|
+
* @param epochMs - instant to label.
|
|
75
|
+
* @returns the local day key.
|
|
76
|
+
*/
|
|
77
|
+
export declare function localDayKey(epochMs: number): string;
|
|
78
|
+
/**
|
|
79
|
+
* Shift a local day key by whole days, honouring DST transitions.
|
|
80
|
+
* @param key - source `YYYY-MM-DD`.
|
|
81
|
+
* @param delta - days to add (may be negative).
|
|
82
|
+
* @returns the shifted key.
|
|
83
|
+
*/
|
|
84
|
+
export declare function addLocalDays(key: string, delta: number): string;
|
|
85
|
+
/** Everything the summary needs; mirrors the query parameters plus context. */
|
|
86
|
+
export interface SummaryInput {
|
|
87
|
+
/** Accepted ledger records, oldest first. */
|
|
88
|
+
records: readonly UsageRecord[];
|
|
89
|
+
/** Active workspace filter key, or `null`. */
|
|
90
|
+
workspace: string | null;
|
|
91
|
+
/** Active model filter key, or `null`. */
|
|
92
|
+
model: string | null;
|
|
93
|
+
/** Active provider filter id, or `null`. */
|
|
94
|
+
provider: string | null;
|
|
95
|
+
/** Width of the daily window in days. */
|
|
96
|
+
days: number;
|
|
97
|
+
/** Current instant, supplied so the function stays pure. */
|
|
98
|
+
now: number;
|
|
99
|
+
/** Currency every amount is expressed in. */
|
|
100
|
+
currency: Currency;
|
|
101
|
+
/** Plugin version reported in the payload. */
|
|
102
|
+
pluginVersion: string;
|
|
103
|
+
/** Pricing provenance reported in the payload. */
|
|
104
|
+
pricing: PricingProvenance;
|
|
105
|
+
/** Degradation counters reported in the payload. */
|
|
106
|
+
health: HealthReport;
|
|
107
|
+
/**
|
|
108
|
+
* Resolve a record's raw workspace path to its current Workspace title.
|
|
109
|
+
*
|
|
110
|
+
* Optional: unit tests and compositions without the Workspace registry omit
|
|
111
|
+
* it and keep the stored `workspaceLabel` behavior.
|
|
112
|
+
*/
|
|
113
|
+
workspaceTitleOf?: WorkspaceTitleOf | undefined;
|
|
114
|
+
}
|
|
115
|
+
/**
|
|
116
|
+
* Build the dashboard payload.
|
|
117
|
+
* @param input - records, filters, clock, and reporting context.
|
|
118
|
+
* @returns the serializable summary.
|
|
119
|
+
*/
|
|
120
|
+
export declare function buildSummary(input: SummaryInput): SummaryResponse;
|
|
121
|
+
/**
|
|
122
|
+
* Local start-of-day epoch milliseconds for a day key.
|
|
123
|
+
* @param key - `YYYY-MM-DD`.
|
|
124
|
+
* @returns the instant local midnight began.
|
|
125
|
+
*/
|
|
126
|
+
export declare function startOfLocalDay(key: string): number;
|
|
127
|
+
/**
|
|
128
|
+
* Total priced amount across one attempt list.
|
|
129
|
+
* @param attempts - attempts of one record.
|
|
130
|
+
* @returns the summed amount.
|
|
131
|
+
*/
|
|
132
|
+
export declare function sumAttemptCost(attempts: readonly UsageAttempt[]): number;
|