usage-dollars

1import type { Engine, Register } from 'claude-code'
2
3import type { Booked, Days } from '../types'
4import { book, dayKey, line, prune, summarize } from './ledger'
5
6const DAYS = 'days'
7const BOOKED = 'booked'
8const WARNED = 'warned'
9
10// Books this session's new spend into the shared day ledger and returns the summary.
11// `seed` records the session's current total as already booked: a resumed session
12// arrives with its past cost, which belongs to the days it was spent on.
13async function sync($: Engine, seed: boolean, budget: number) {
14  const usage = await $.session.usage()
15  const now = await $.clock.now()
16  if (usage.cost === undefined) return undefined
17
18  const session = String(usage.startedAt)
19  const days = ((await $.store.get(DAYS)) ?? {}) as Days
20  const booked = ((await $.store.get(BOOKED)) ?? {}) as Booked
21  const next =
22    seed && !(session in booked)
23      ? { days, booked: { ...booked, [session]: usage.cost.usd } }
24      : book(days, booked, session, usage.cost.usd, dayKey(now))
25  const pruned = prune(next.days, next.booked, now)
26  await $.store.set(DAYS, pruned.days)
27  await $.store.set(BOOKED, pruned.booked)
28
29  return summarize(pruned.days, now, budget)
30}
31
32export const register: Register = (on, options) => {
33  const budget = Number(options.monthlyBudgetUsd ?? 0)
34
35  on('session.start', async ($, e, next) => {
36    await $.command.register({ name: 'spend', description: 'Spend today and month to date against the budget' })
37    const s = await sync($, true, budget)
38    if (s) $.ui.status(line(s))
39
40    return next(e)
41  })
42
43  on('turn.complete', async ($, e, next) => {
44    const s = await sync($, false, budget)
45    if (s) {
46      $.ui.status(line(s))
47      if (s.budget > 0) {
48        const month = dayKey(await $.clock.now()).slice(0, 7)
49        const level = s.month >= s.budget ? 100 : s.month >= s.budget * 0.8 ? 80 : 0
50        const warned = ((await $.store.get(WARNED)) ?? {}) as { month?: string; level?: number }
51        const last = warned.month === month ? (warned.level ?? 0) : 0
52        if (level > last) {
53          await $.store.set(WARNED, { month, level })
54          $.ui.toast(`Budget ${level}% reached: ${line(s)}`)
55        }
56      }
57    }
58
59    return next(e)
60  })
61
62  on('command.run', { command: 'spend' }, async $ => {
63    const s = await sync($, false, budget)
64    if (!s) return { text: 'No cost ledger in this host.' }
65    const rest = s.budget > 0 ? `\nRemaining this month: ${Math.max(0, s.budget - s.month).toFixed(2)} USD` : ''
66
67    return { text: `${line(s)}${rest}` }
68  })
69}
70

1import type { Booked, Days, Summary } from '../types'
2
3const pad = (n: number) => String(n).padStart(2, '0')
4
5/** Local calendar day of an epoch-millisecond time, "YYYY-MM-DD". */
6export const dayKey = (ms: number): string => {
7  const d = new Date(ms)
8
9  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`
10}
11
12/**
13 * Books the part of a session's cumulative `usd` not yet booked onto `day`.
14 * A cumulative figure that went down (a /clear, a reset ledger) books nothing
15 * and becomes the new baseline.
16 */
17export const book = (
18  days: Days,
19  booked: Booked,
20  session: string,
21  usd: number,
22  day: string,
23): { days: Days; booked: Booked } => {
24  const delta = Math.max(0, usd - (booked[session] ?? 0))
25
26  return {
27    days: delta > 0 ? { ...days, [day]: (days[day] ?? 0) + delta } : days,
28    booked: { ...booked, [session]: usd },
29  }
30}
31
32/** Drops days from before the current month and sessions older than 40 days. */
33export const prune = (days: Days, booked: Booked, now: number): { days: Days; booked: Booked } => {
34  const month = dayKey(now).slice(0, 7)
35  const cutoff = now - 40 * 86_400_000
36
37  return {
38    days: Object.fromEntries(Object.entries(days).filter(([k]) => k.startsWith(month))),
39    booked: Object.fromEntries(Object.entries(booked).filter(([k]) => Number(k) >= cutoff)),
40  }
41}
42
43export const summarize = (days: Days, now: number, budget: number): Summary => {
44  const day = dayKey(now)
45  const month = day.slice(0, 7)
46  const sum = Object.entries(days).reduce((s, [k, v]) => (k.startsWith(month) ? s + v : s), 0)
47
48  return { today: days[day] ?? 0, month: sum, budget }
49}
50
51export const usd = (n: number): string => `$${n.toFixed(2)}`
52
53export const line = (s: Summary): string =>
54  s.budget > 0
55    ? `${usd(s.today)} today · ${usd(s.month)}/${usd(s.budget)} month (${Math.round((s.month / s.budget) * 100)}%)`
56    : `${usd(s.today)} today · ${usd(s.month)} month`
57

1/** Dollars spent per local calendar day ("YYYY-MM-DD"), summed over every session. */
2export type Days = Record<string, number>
3
4/** Cumulative dollars already booked per session, keyed by the session's start time. */
5export type Booked = Record<string, number>
6
7export type Summary = { today: number; month: number; budget: number }
8