The best way to control Claude Code, Codex and more from any computer or phone

main
ts 174 lines 6.53 KB
Raw
1 import * as Schema from "effect/Schema";
2
3 import { ForwardCompatibleArray, NonNegativeInt, TrimmedNonEmptyString } from "./baseSchemas.ts";
4
5 /** Bump for incompatible UsageSummary changes; skipped unknown array variants need no bump. */
6 export const USAGE_CONTRACT_VERSION = 6 as const;
7
8 export const USAGE_MERGE_COMPATIBLE_SINCE = 4 as const;
9
10 export const UsageProviderKind = Schema.Literals([
11 "claude",
12 "codex",
13 "grok",
14 "cursor",
15 "opencode",
16 "antigravity",
17 "pi",
18 "muse",
19 ]);
20 export type UsageProviderKind = typeof UsageProviderKind.Type;
21
22 const USAGE_DAY_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
23
24 export const UsageDay = TrimmedNonEmptyString.check(Schema.isPattern(USAGE_DAY_PATTERN)).pipe(
25 Schema.brand("UsageDay"),
26 );
27 export type UsageDay = typeof UsageDay.Type;
28
29 export const UsageResolution = Schema.Literals(["day", "hour"]);
30 export type UsageResolution = typeof UsageResolution.Type;
31
32 export const UsageCostSource = Schema.Literals(["providerReported", "modelPriced", "unpriced"]);
33 export type UsageCostSource = typeof UsageCostSource.Type;
34
35 /** Sum uncached input, cache reads, and cache writes for input totals; reasoning is already included in output. */
36 export const UsageTokenTotals = Schema.Struct({
37 uncachedInputTokens: NonNegativeInt,
38 cachedInputTokens: NonNegativeInt,
39 cacheCreationTokens: NonNegativeInt,
40 outputTokens: NonNegativeInt,
41 reasoningTokens: NonNegativeInt,
42 });
43 export type UsageTokenTotals = typeof UsageTokenTotals.Type;
44
45 export const UsageCategoryCost = Schema.Struct({
46 input: Schema.Number,
47 cacheRead: Schema.Number,
48 cacheWrite: Schema.Number,
49 output: Schema.Number,
50 });
51 export type UsageCategoryCost = typeof UsageCategoryCost.Type;
52
53 export const UsageBucket = Schema.Struct({
54 day: UsageDay,
55 hourStart: Schema.optional(TrimmedNonEmptyString),
56 provider: UsageProviderKind,
57 model: TrimmedNonEmptyString,
58 sourcePath: Schema.optional(TrimmedNonEmptyString),
59 totals: UsageTokenTotals,
60 costUsd: Schema.Number,
61 cacheSavingsUsd: Schema.Number,
62 categoryCostUsd: Schema.optional(UsageCategoryCost),
63 fastCostUsd: Schema.optional(Schema.Number),
64 ultrafastCostUsd: Schema.optional(Schema.Number),
65 speedPremiumUsd: Schema.optional(Schema.Number),
66 costSource: UsageCostSource,
67 records: NonNegativeInt,
68 unpricedRecords: NonNegativeInt,
69 /** Absent from older servers; merges then estimate it from the unpriced record share. */
70 unpricedTokens: Schema.optional(NonNegativeInt),
71 sessions: NonNegativeInt,
72 });
73 export type UsageBucket = typeof UsageBucket.Type;
74
75 export const UsageSourceFingerprint = Schema.Struct({
76 hostId: TrimmedNonEmptyString,
77 provider: UsageProviderKind,
78 resolvedHomePath: TrimmedNonEmptyString,
79 /** Transcript directory device:inode distinguishes machines sharing a hostname and home path. */
80 volumeId: Schema.String,
81 /**
82 * Opaque identity of a directory that the Windows server of a desktop install
83 * reads natively and its managed WSL server reads through a drvfs mount. Path
84 * and `volumeId` differ between the two sides, so clients treat sources with
85 * an equal value as one directory in addition to the fields above.
86 */
87 physicalSourceId: Schema.optionalKey(TrimmedNonEmptyString),
88 });
89 export type UsageSourceFingerprint = typeof UsageSourceFingerprint.Type;
90
91 export const UsageSourceStatus = Schema.Literals(["ok", "missing", "partial", "failed"]);
92 export type UsageSourceStatus = typeof UsageSourceStatus.Type;
93
94 export const UsageSource = Schema.Struct({
95 fingerprint: UsageSourceFingerprint,
96 status: UsageSourceStatus,
97 scannedFiles: NonNegativeInt,
98 skippedFiles: NonNegativeInt,
99 malformedRecords: NonNegativeInt,
100 /** Total this count; bucket counts double-count sessions spanning days or models. */
101 distinctSessions: NonNegativeInt,
102 message: Schema.NullOr(TrimmedNonEmptyString),
103 /** Cached response during refresh; repeat with awaitRefresh for fresh data. */
104 refreshing: Schema.optionalKey(Schema.Literal(true)),
105 });
106 export type UsageSource = typeof UsageSource.Type;
107
108 export const UsagePricingStatus = Schema.Literals(["fresh", "cached", "unavailable"]);
109 export type UsagePricingStatus = typeof UsagePricingStatus.Type;
110
111 export const UsagePricing = Schema.Struct({
112 status: UsagePricingStatus,
113 source: TrimmedNonEmptyString,
114 fetchedAt: Schema.NullOr(Schema.String),
115 knownModels: NonNegativeInt,
116 });
117 export type UsagePricing = typeof UsagePricing.Type;
118
119 /**
120 * Matches a provider's original model ID, before usage model aliases apply. Omit provider to
121 * match any; a string provider lets older clients carry selectors for providers they lack.
122 */
123 export const UsageModelSelector = Schema.Struct({
124 provider: Schema.optional(TrimmedNonEmptyString),
125 model: TrimmedNonEmptyString,
126 });
127 export type UsageModelSelector = typeof UsageModelSelector.Type;
128
129 /** Keeps records matching `include` (all when omitted) and not matching `exclude`. */
130 export const UsageModelFilter = Schema.Struct({
131 include: Schema.optional(Schema.Array(UsageModelSelector)),
132 exclude: Schema.optional(Schema.Array(UsageModelSelector)),
133 });
134 export type UsageModelFilter = typeof UsageModelFilter.Type;
135
136 export const UsageSummaryInput = Schema.Struct({
137 sinceDay: UsageDay,
138 untilDay: UsageDay,
139 /** IANA bucketing zone; offsets fail across DST boundaries. */
140 timeZone: TrimmedNonEmptyString,
141 resolution: Schema.optional(UsageResolution),
142 sinceTime: Schema.optional(TrimmedNonEmptyString),
143 untilTime: Schema.optional(TrimmedNonEmptyString),
144 awaitRefresh: Schema.optional(Schema.Boolean),
145 /** Accept an immediate answer from the last scan; its sources are marked refreshing. */
146 provisional: Schema.optional(Schema.Boolean),
147 modelFilter: Schema.optional(UsageModelFilter),
148 });
149 export type UsageSummaryInput = typeof UsageSummaryInput.Type;
150
151 export const UsageSummary = Schema.Struct({
152 contractVersion: Schema.Number,
153 readAt: Schema.String,
154 timeZone: TrimmedNonEmptyString,
155 sinceDay: UsageDay,
156 untilDay: UsageDay,
157 buckets: ForwardCompatibleArray(UsageBucket),
158 sources: ForwardCompatibleArray(UsageSource),
159 pricing: UsagePricing,
160 scanDurationMs: NonNegativeInt,
161 /** The filter the server applied; absent means unfiltered, including servers that predate filters. */
162 modelFilter: Schema.optional(UsageModelFilter),
163 });
164 export type UsageSummary = typeof UsageSummary.Type;
165
166 export class UsageReadError extends Schema.TaggedError<UsageReadError>()("UsageReadError", {
167 reason: Schema.Literals(["scanFailed", "invalidWindow"]),
168 detail: TrimmedNonEmptyString,
169 cause: Schema.optional(Schema.Defect()),
170 }) {
171 override get message(): string {
172 return `Usage read failed (${this.reason}): ${this.detail}`;
173 }
174 }