agl 40.4.0 → 40.5.1

package/ts_authswitch/authority-spend.ts

@@ -0,0 +1,168 @@
+/**
+ * What an API key spent: the calendar month in UTC a key's spend counts in, the reading the accounts service answers
+ * for a key's login, the spend limit rule, and how an amount reads in US dollars.
+ *
+ * Every amount is a whole number of micro-dollars (a millionth of a US dollar), so sums stay exact. The module imports
+ * nothing, so it bundles for a browser with nothing behind it.
+ */
+
+/** Micro-dollars in one US dollar. */
+export const authSwitchMicroUsdPerUsd = 1_000_000;
+
+/** Micro-dollars in one US cent: a spend limit is a whole number of cents. */
+export const authSwitchMicroUsdPerCent = 10_000;
+
+/** One calendar month in UTC: the period a key's spend counts in and its limit applies to. */
+export interface IAuthSwitchSpendPeriod {
+  /** `YYYY-MM`. */
+  key: string;
+  /** 00:00 UTC on the month's first day, ISO 8601. */
+  start: string;
+  /** 00:00 UTC on the next month's first day, ISO 8601: when the month's spend resets. */
+  end: string;
+}
+
+const twoDigits = (valueArg: number): string => String(valueArg).padStart(2, '0');
+
+/** The calendar month in UTC that `nowArg` (epoch milliseconds) falls in. */
+export const authSwitchSpendPeriod = (nowArg: number): IAuthSwitchSpendPeriod => {
+  const at = new Date(nowArg);
+  const year = at.getUTCFullYear();
+  if (!Number.isFinite(nowArg) || year < 2000 || year > 9999) throw new RangeError('A spend period needs a time from 2000 to 9999.');
+  const month = at.getUTCMonth();
+  return {
+    key: `${year}-${twoDigits(month + 1)}`,
+    start: new Date(Date.UTC(year, month, 1)).toISOString(),
+    end: new Date(Date.UTC(year, month + 1, 1)).toISOString(),
+  };
+};
+
+/** Whether a value is a spend period's key, `YYYY-MM` from 2000-01 to 9999-12. */
+export const isAuthSwitchSpendPeriodKey = (valueArg: unknown): valueArg is string =>
+  typeof valueArg === 'string' && /^(?:[2-9]\d{3})-(?:0[1-9]|1[0-2])$/.test(valueArg);
+
+/**
+ * An API key's spend in one calendar month, as the accounts service holds it from what AGL's inference proxy reported:
+ * the answers the proxy relayed on the key in the month and what each cost by the proxy's price table. It counts AGL's
+ * traffic alone; whatever else used the key is not in it.
+ */
+export interface IAuthSwitchSpendReading {
+  /** The month, `YYYY-MM` (`IAuthSwitchSpendPeriod.key`). */
+  period: string;
+  /** 00:00 UTC on the month's first day, ISO 8601. */
+  periodStart: string;
+  /** 00:00 UTC on the next month's first day, ISO 8601: when the month's spend resets. */
+  resetAt: string;
+  /** What the month's priced answers cost, in micro-dollars. */
+  spentMicroUsd: number;
+  /** The key's monthly spend limit when the reading was answered, in micro-dollars; null for none. */
+  limitMicroUsd: number | null;
+  /** The answers counted in the month, priced or not. */
+  answers: number;
+  /**
+   * The answers of the month the proxy could not price: their cost is unknown, so a key with a limit takes no work
+   * until the month ends or its limit is removed.
+   */
+  unpricedAnswers: number;
+  /** When the month's newest answer ended, ISO 8601; null before the month's first answer. */
+  lastAnswerAt: string | null;
+}
+
+/** A spend limit's range in micro-dollars: one cent to one million dollars. */
+export const authSwitchSpendLimitRange: Readonly<{ min: number; max: number }> = Object.freeze({
+  min: authSwitchMicroUsdPerCent,
+  max: 1_000_000 * authSwitchMicroUsdPerUsd,
+});
+
+/**
+ * The spend limit rule, the one the authority applies to a key's monthly limit: a whole number of cents from
+ * `authSwitchSpendLimitRange.min` to `.max`, in micro-dollars. `null` clears a limit. A consumer validates with this
+ * rather than restating it; the authority answers any other value with the `invalid_input` refusal.
+ */
+export const isAuthSwitchSpendLimitMicroUsd = (valueArg: unknown): valueArg is number => Number.isSafeInteger(valueArg)
+  && (valueArg as number) >= authSwitchSpendLimitRange.min && (valueArg as number) <= authSwitchSpendLimitRange.max
+  && (valueArg as number) % authSwitchMicroUsdPerCent === 0;
+
+/**
+ * A dollar amount as a person types it -- `50`, `12.5`, `$1000.00`, no thousands separator -- in micro-dollars, or
+ * `null` when the text is no such amount. It reads at most two decimals: an amount finer than a cent is no amount.
+ */
+export const authSwitchParseUsd = (textArg: string): number | null => {
+  const match = /^\$?(\d{1,13})(?:\.(\d{1,2}))?$/.exec(textArg.trim());
+  if (!match) return null;
+  const microUsd = Number(match[1]) * authSwitchMicroUsdPerUsd
+    + Number((match[2] ?? '').padEnd(2, '0')) * authSwitchMicroUsdPerCent;
+  return Number.isSafeInteger(microUsd) ? microUsd : null;
+};
+
+/**
+ * An amount in US dollars to the cent, with thousands separators: `$12.40`, `$1,000,000.00`. A part of a cent counts
+ * as a whole one, so a spend never reads lower than it is.
+ */
+export const authSwitchUsdText = (microUsdArg: number): string => {
+  if (!Number.isSafeInteger(microUsdArg) || microUsdArg < 0) throw new RangeError('An amount is a whole number of micro-dollars.');
+  const cents = Math.ceil(microUsdArg / authSwitchMicroUsdPerCent);
+  const dollars = String(Math.floor(cents / 100)).replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+  return `$${dollars}.${twoDigits(cents % 100)}`;
+};
+
+/** The share of its limit a reading's month spent, in percent (above 100 once over it); null without a limit. */
+export const authSwitchSpendPercent = (readingArg: IAuthSwitchSpendReading): number | null =>
+  readingArg.limitMicroUsd === null ? null : readingArg.spentMicroUsd * 100 / readingArg.limitMicroUsd;
+
+/**
+ * Whether a reading's month ended by `nowArg` (epoch milliseconds): its `resetAt` passed. Such a reading says nothing
+ * about the next month, which starts with nothing spent; every rule that judges a reading decides this by it.
+ */
+export const authSwitchSpendMonthEnded = (readingArg: IAuthSwitchSpendReading, nowArg: number): boolean =>
+  Date.parse(readingArg.resetAt) <= nowArg;
+
+/**
+ * An answer AGL's inference proxy relayed on a key whose report the accounts service has not acknowledged yet: when it
+ * ended and what it cost.
+ */
+export interface IAuthSwitchSpendPending {
+  /** When the answer ended, ISO 8601 UTC: its calendar month in UTC is the one it counts in. */
+  endedAt: string;
+  /** What the answer cost, in micro-dollars; null when it could not be priced. */
+  microUsd: number | null;
+}
+
+/**
+ * A key's month as the proxy judges it at `nowArg` (epoch milliseconds): the held reading with the answers added whose
+ * report the accounts service has not acknowledged yet. Only the month `nowArg` falls in counts. When the held
+ * reading's month has ended, that month starts at nothing spent and no answer unpriced, under the reading's limit; of
+ * the pending answers only those that ended in it are added, priced and unpriced alike, so an answer from before
+ * midnight on the 1st counts in the month that ended, never in the new one. The reading's limit is kept: it is the limit
+ * the accounts service answered last.
+ */
+export const authSwitchSpendWithPending = (readingArg: IAuthSwitchSpendReading,
+  pendingArg: readonly IAuthSwitchSpendPending[], nowArg: number): IAuthSwitchSpendReading => {
+  const period = authSwitchSpendPeriod(nowArg);
+  const start = Date.parse(period.start);
+  const end = Date.parse(period.end);
+  const held = readingArg.period === period.key ? readingArg : null;
+  let spentMicroUsd = held?.spentMicroUsd ?? 0;
+  let answers = held?.answers ?? 0;
+  let unpricedAnswers = held?.unpricedAnswers ?? 0;
+  let lastAnswerAt = held?.lastAnswerAt ?? null;
+  for (const answer of pendingArg) {
+    const endedAt = Date.parse(answer.endedAt);
+    if (!(endedAt >= start && endedAt < end)) continue;
+    answers += 1;
+    if (answer.microUsd === null) unpricedAnswers += 1;
+    else spentMicroUsd += answer.microUsd;
+    if (lastAnswerAt === null || endedAt > Date.parse(lastAnswerAt)) lastAnswerAt = new Date(endedAt).toISOString();
+  }
+  return { period: period.key, periodStart: period.start, resetAt: period.end, spentMicroUsd,
+    limitMicroUsd: readingArg.limitMicroUsd, answers, unpricedAnswers, lastAnswerAt };
+};
+
+/**
+ * Whether a key's reading keeps it from taking work at `nowArg` (epoch milliseconds): it has a limit, its month has
+ * not ended, and the month spent the limit or holds an answer that could not be priced. A key without a limit is never
+ * stopped by its spend; once the month ended the reading says nothing about the next one.
+ */
+export const authSwitchSpendExhausted = (readingArg: IAuthSwitchSpendReading, nowArg: number): boolean =>
+  readingArg.limitMicroUsd !== null && !authSwitchSpendMonthEnded(readingArg, nowArg)
+  && (readingArg.spentMicroUsd >= readingArg.limitMicroUsd || readingArg.unpricedAnswers > 0);

package/ts_authswitch/authority-subscription.ts

@@ -4,7 +4,8 @@
  * The authswitch command line and AGL's Accounts screen both show these, so their words are written here, once. Besides
  * types, the module imports nothing, and therefore bundles for a browser with nothing behind it.
  */
-import type { TAuthSwitchRecheckOutcome, TAuthSwitchUsageReading } from './classes.authorityusage.js';
+import type { IAuthSwitchPaymentProblem, TAuthSwitchRecheckOutcome,
+  TAuthSwitchUsageReading } from './classes.authorityusage.js';
 
 /**
  * What the `subscription_status` values Claude's profile states mean, in plain words, by value. It is empty: no value's
@@ -54,6 +55,14 @@ export const authSwitchSubscriptionFacts = (readingArg: TAuthSwitchUsageReading
       .map((factArg) => ({ label: factArg.label, value: factArg.value }))
     : [];
 
+/**
+ * Whether a payment problem still holds the account at `nowArg` (epoch milliseconds): every one does until it is
+ * cleared, except a `spend_cap`, which holds nothing once its `until` passed. Every reader of a held problem decides by
+ * this, the authority included.
+ */
+export const authSwitchPaymentProblemHeld = (problemArg: IAuthSwitchPaymentProblem, nowArg: number): boolean =>
+  problemArg.cause !== 'spend_cap' || (problemArg.until !== undefined && Date.parse(problemArg.until) > nowArg);
+
 /**
  * What an account's payment problem means, as one sentence (`IAuthSwitchPaymentProblem`); the time it was seen is the
  * caller's to show.
@@ -62,6 +71,22 @@ export const authSwitchPaymentProblemText = 'Anthropic refused a request on this
   + ' (HTTP 402), so AGL routes nothing to it until a usage read shows its subscription changed or a re-check reads it'
   + ' healthy.';
 
+/**
+ * What an API key's payment problem means, as one sentence (`IAuthSwitchPaymentProblem`), by its cause and the key's
+ * provider; when it was seen, and when a spend cap resets, are the caller's to show.
+ */
+export const authSwitchApiKeyPaymentProblemText = (problemArg: IAuthSwitchPaymentProblem, providerIdArg: string): string => {
+  const provider = providerIdArg === 'openai' ? 'OpenAI' : 'Anthropic';
+  switch (problemArg.cause) {
+    case undefined: return `${provider} refused a request on this key with a billing error, so AGL routes nothing to it`
+      + ' until it is re-checked.';
+    case 'spend_cap': return `${provider} stopped this key at its monthly spend cap, so AGL routes nothing to it until the`
+      + ' cap resets, or until it is re-checked.';
+    case 'quota': return `${provider} reports this key's credit or spend limit used up, so AGL routes nothing to it until`
+      + ' it is re-checked.';
+  }
+};
+
 /** How a re-check went, as one sentence. */
 export const authSwitchRecheckOutcomeText = (outcomeArg: TAuthSwitchRecheckOutcome): string => {
   switch (outcomeArg) {
@@ -71,5 +96,7 @@ export const authSwitchRecheckOutcomeText = (outcomeArg: TAuthSwitchRecheckOutco
     case 'profile_missing': return 'Claude did not answer the account\'s profile.';
     case 'mismatch': return 'Claude answered with a different account or organization.';
     case 'read_failed': return 'The account could not be read now; the next read is shown with its usage.';
+    case 'cleared': return 'The key\'s hold is lifted: AGL places requests on it again, and the provider\'s next answer '
+      + 'shows whether it takes them.';
   }
 };

package/ts_authswitch/authority-usagelimit.ts

@@ -2,17 +2,18 @@
  * Whether an account's usage reading still lets it take work: the one rule the inference proxy's placement, Flex's
  * dispatch and resume, the authswitch command line and AGL's Accounts screen all decide by.
  *
- * Besides types, the module imports only the window reader of `authority-usagewindows.ts`, whose own imports carry
- * nothing to a page, so it bundles for a browser with nothing behind it.
+ * Besides types, the module imports only the window reader of `authority-usagewindows.ts` and the spend rule of
+ * `authority-spend.ts`, whose own imports carry nothing to a page, so it bundles for a browser with nothing behind it.
  */
-import type { TAuthSwitchUsageReading } from './classes.authorityusage.js';
+import type { TAuthSwitchProviderUsageReading, TAuthSwitchUsageReading } from './classes.authorityusage.js';
 import { authSwitchUsageWindowName, authSwitchUsageWindowPercent, authSwitchUsageWindows,
   type IAuthSwitchUsageWindow } from './authority-usagewindows.js';
+import { authSwitchSpendExhausted, authSwitchSpendMonthEnded } from './authority-spend.js';
 
 /**
  * `available`: the account takes work. `reserved`: a counted window reached the account's `maxUsagePercent`, so
- * the rest of it is kept for use outside AGL. `exhausted`: a counted window is used up, or the provider refuses
- * requests until a time it names.
+ * the rest of it is kept for use outside AGL. `exhausted`: a counted window is used up, the provider refuses
+ * requests until a time it names, or an API key reached its monthly spend limit.
  */
 export type TAuthSwitchLimitState = 'available' | 'reserved' | 'exhausted';
 
@@ -51,6 +52,82 @@ export const authSwitchReserveLiftActive = (untilArg: string | null | undefined,
 export const authSwitchEffectiveMaxUsage = (maxArg: number | null, untilArg: string | null | undefined,
   nowArg: number): number | null => maxArg !== null && authSwitchReserveLiftActive(untilArg, nowArg) ? 100 : maxArg;
 
+/** The windows' latest reset among those it names, as ISO 8601; null when none names one. */
+const latestReset = (resetsArg: readonly (string | null)[]): string | null => {
+  const resetTimes = resetsArg.flatMap((resetArg) => {
+    const at = resetArg === null ? NaN : Date.parse(resetArg);
+    return Number.isFinite(at) ? [at] : [];
+  });
+  return resetTimes.length ? new Date(Math.max(...resetTimes)).toISOString() : null;
+};
+
+/** A subscription sign-in's limit: see `authSwitchUsageLimit`. */
+const subscriptionLimit = (readingArg: TAuthSwitchProviderUsageReading, maxUsagePercentArg: number | null,
+  nowArg: number, reserveLiftUntilArg: string | null): IAuthSwitchUsageLimit => {
+  const threshold = authSwitchEffectiveMaxUsage(maxUsagePercentArg, reserveLiftUntilArg, nowArg) ?? 100;
+  const windows = authSwitchCountedWindows(readingArg, maxUsagePercentArg);
+  const crossing = windows.filter((windowArg) => authSwitchUsageWindowPercent(windowArg) >= threshold);
+  const resets = crossing.map((windowArg) => windowArg.resetAt);
+  let refused: boolean;
+  switch (readingArg.kind) {
+    case 'openai': {
+      const details = readingArg.rateLimits.rateLimit;
+      const mainWindows = [details?.primaryWindow, details?.secondaryWindow]
+        .filter((windowArg) => windowArg !== undefined);
+      // The refusal is the used-up windows' where the reading states any, else the whole limit's; once each of those
+      // started a new period past the reset the reading stated, so did the refusal.
+      const used = mainWindows.filter((windowArg) => windowArg.usedPercent >= 100);
+      const causes = used.length ? used : mainWindows;
+      const rolled = causes.length > 0 && causes.every((windowArg) => windowArg.estimated === true);
+      refused = details !== undefined && !rolled && (!details.allowed || details.limitReached);
+      // A refusal that names no window is lifted by the latest reset of the windows the limit counts.
+      if (refused && crossing.length === 0) resets.push(...windows.map((windowArg) => windowArg.resetAt));
+      break;
+    }
+    case 'anthropic': {
+      const retryAt = readingArg.status.rateLimit?.retryAt ?? null;
+      refused = retryAt !== null && Date.parse(retryAt) > nowArg;
+      if (refused) resets.push(retryAt);
+      break;
+    }
+    default: {
+      const unhandledReading: never = readingArg;
+      return unhandledReading;
+    }
+  }
+  const state: TAuthSwitchLimitState = refused || crossing.some((windowArg) => authSwitchUsageWindowPercent(windowArg) >= 100)
+    ? 'exhausted' : crossing.length ? 'reserved' : 'available';
+  return {
+    state,
+    threshold,
+    headroom: windows.length
+      ? Math.min(...windows.map((windowArg) => Math.max(0, threshold - authSwitchUsageWindowPercent(windowArg)))) : null,
+    crossing,
+    resetAt: state !== 'available' ? latestReset(resets) : null,
+  };
+};
+
+/**
+ * An API key's limit, from its monthly spend (`authSwitchSpendExhausted`): with a spend limit the key is `exhausted`
+ * once its month spent the limit or holds an answer that could not be priced, until the month ends; without one it is
+ * always `available`. The threshold is always 100, and neither a usage threshold nor a reserve lift applies to a key.
+ */
+const spendLimit = (readingArg: Extract<TAuthSwitchUsageReading, { kind: 'spend' }>, nowArg: number): IAuthSwitchUsageLimit => {
+  const windows = authSwitchUsageWindows(readingArg);
+  const exhausted = authSwitchSpendExhausted(readingArg.spend, nowArg);
+  // A month that ended says nothing about the next one, which starts with nothing spent.
+  const ended = authSwitchSpendMonthEnded(readingArg.spend, nowArg);
+  return {
+    state: exhausted ? 'exhausted' : 'available',
+    threshold: 100,
+    headroom: windows.length
+      ? Math.min(...windows.map((windowArg) => ended ? 100 : Math.max(0, 100 - authSwitchUsageWindowPercent(windowArg))))
+      : null,
+    crossing: exhausted ? windows : [],
+    resetAt: exhausted ? readingArg.spend.resetAt : null,
+  };
+};
+
 /**
  * The limit an account's usage reading states, judged against its `maxUsagePercent` at `nowArg` (epoch
  * milliseconds). An active reserve lift raises only the threshold to 100 until its absolute expiry.
@@ -69,47 +146,25 @@ export const authSwitchEffectiveMaxUsage = (maxArg: number | null, untilArg: str
  * of a Claude reading is the provider refusing inference, as an answer's headers stated it; a refused usage read never
  * sets it.
  *
+ * An API key's spend reading is judged by its spend limit alone (`spendLimit`); `maxUsagePercentArg` and
+ * `reserveLiftUntilArg` do not apply to it.
+ *
  * Whether a reading is recent enough to decide on, and a cooldown after a provider 429, are the caller's: they belong
  * to how it reads usage, not to what a reading says.
  */
 export const authSwitchUsageLimit = (readingArg: TAuthSwitchUsageReading, maxUsagePercentArg: number | null,
   nowArg: number, reserveLiftUntilArg: string | null = null): IAuthSwitchUsageLimit => {
-  const threshold = authSwitchEffectiveMaxUsage(maxUsagePercentArg, reserveLiftUntilArg, nowArg) ?? 100;
-  const windows = authSwitchCountedWindows(readingArg, maxUsagePercentArg);
-  const crossing = windows.filter((windowArg) => authSwitchUsageWindowPercent(windowArg) >= threshold);
-  const resets = crossing.map((windowArg) => windowArg.resetAt);
-  let refused: boolean;
-  if (readingArg.kind === 'openai') {
-    const details = readingArg.rateLimits.rateLimit;
-    const mainWindows = [details?.primaryWindow, details?.secondaryWindow]
-      .filter((windowArg) => windowArg !== undefined);
-    // The refusal is the used-up windows' where the reading states any, else the whole limit's; once each of those
-    // started a new period past the reset the reading stated, so did the refusal.
-    const used = mainWindows.filter((windowArg) => windowArg.usedPercent >= 100);
-    const causes = used.length ? used : mainWindows;
-    const rolled = causes.length > 0 && causes.every((windowArg) => windowArg.estimated === true);
-    refused = details !== undefined && !rolled && (!details.allowed || details.limitReached);
-    // A refusal that names no window is lifted by the latest reset of the windows the limit counts.
-    if (refused && crossing.length === 0) resets.push(...windows.map((windowArg) => windowArg.resetAt));
-  } else {
-    const retryAt = readingArg.status.rateLimit?.retryAt ?? null;
-    refused = retryAt !== null && Date.parse(retryAt) > nowArg;
-    if (refused) resets.push(retryAt);
+  switch (readingArg.kind) {
+    case 'openai':
+    case 'anthropic':
+      return subscriptionLimit(readingArg, maxUsagePercentArg, nowArg, reserveLiftUntilArg);
+    case 'spend':
+      return spendLimit(readingArg, nowArg);
+    default: {
+      const unhandledReading: never = readingArg;
+      return unhandledReading;
+    }
   }
-  const state: TAuthSwitchLimitState = refused || crossing.some((windowArg) => authSwitchUsageWindowPercent(windowArg) >= 100)
-    ? 'exhausted' : crossing.length ? 'reserved' : 'available';
-  const resetTimes = resets.flatMap((resetArg) => {
-    const at = resetArg === null ? NaN : Date.parse(resetArg);
-    return Number.isFinite(at) ? [at] : [];
-  });
-  return {
-    state,
-    threshold,
-    headroom: windows.length
-      ? Math.min(...windows.map((windowArg) => Math.max(0, threshold - authSwitchUsageWindowPercent(windowArg)))) : null,
-    crossing,
-    resetAt: state !== 'available' && resetTimes.length ? new Date(Math.max(...resetTimes)).toISOString() : null,
-  };
 };
 
 const windowNames = (windowsArg: readonly IAuthSwitchUsageWindow[]): string => {

package/ts_authswitch/authority-usagewindows.ts

@@ -54,29 +54,52 @@ const openAiWindows = (limitNameArg: string | null,
     }))
 );
 
+/** The name of an API key's one window, its spend in the calendar month against its limit. */
+export const authSwitchSpendWindowLabel = 'Monthly spend';
+
 /**
  * The windows of a reading: for ChatGPT the main limit's two windows, then each named extra limit's; for Claude the
- * windows as the service reported them. A missing reading has none.
+ * windows as the service reported them; for an API key with a spend limit one account window, the month's spend in
+ * percent of the limit, which resets when the month ends -- a key without a limit has none. A missing reading has none.
  */
 export const authSwitchUsageWindows = (readingArg: TAuthSwitchUsageReading | null): IAuthSwitchUsageWindow[] => {
   if (readingArg === null) return [];
-  if (readingArg.kind === 'openai') {
-    return [
-      ...openAiWindows(null, readingArg.rateLimits.rateLimit),
-      ...readingArg.rateLimits.additionalRateLimits.flatMap((limitArg) => (
-        openAiWindows(limitArg.limitName, limitArg.rateLimit)
-      )),
-    ];
+  switch (readingArg.kind) {
+    case 'openai':
+      return [
+        ...openAiWindows(null, readingArg.rateLimits.rateLimit),
+        ...readingArg.rateLimits.additionalRateLimits.flatMap((limitArg) => (
+          openAiWindows(limitArg.limitName, limitArg.rateLimit)
+        )),
+      ];
+    case 'anthropic':
+      return (readingArg.status.windows ?? []).map((windowArg) => ({
+        label: windowArg.label,
+        limitName: null,
+        scope: windowArg.scope,
+        durationSeconds: windowArg.durationSeconds,
+        usedPercent: windowArg.usedPercent,
+        estimatedUsedPercent: windowArg.estimated ? windowArg.estimatedUsedPercent ?? null : null,
+        resetAt: windowArg.resetAt,
+      }));
+    case 'spend': {
+      const spend = readingArg.spend;
+      if (spend.limitMicroUsd === null) return [];
+      return [{
+        label: authSwitchSpendWindowLabel,
+        limitName: null,
+        scope: 'account',
+        durationSeconds: (Date.parse(spend.resetAt) - Date.parse(spend.periodStart)) / 1000,
+        usedPercent: spend.spentMicroUsd * 100 / spend.limitMicroUsd,
+        estimatedUsedPercent: null,
+        resetAt: spend.resetAt,
+      }];
+    }
+    default: {
+      const unhandledReading: never = readingArg;
+      return unhandledReading;
+    }
   }
-  return (readingArg.status.windows ?? []).map((windowArg) => ({
-    label: windowArg.label,
-    limitName: null,
-    scope: windowArg.scope,
-    durationSeconds: windowArg.durationSeconds,
-    usedPercent: windowArg.usedPercent,
-    estimatedUsedPercent: windowArg.estimated ? windowArg.estimatedUsedPercent ?? null : null,
-    resetAt: windowArg.resetAt,
-  }));
 };
 
 /** The percent a window is used to as far as AGL knows: the estimate between reads, else the reported value. */
@@ -101,5 +124,7 @@ export const authSwitchUsageProblemText = (problemArg: TAuthSwitchUsageProblem):
     case 'expired': return 'The last reading is too old to show.';
     case 'held_in_container': return 'This login is in use in a container, so its usage is not read here.';
     case 'pending': return 'The account\'s usage has not been read yet.';
+    case 'spend_unavailable': return 'The key\'s spend could not be read, so AGL places nothing on it while it has a '
+      + 'spend limit.';
   }
 };