agl 40.4.0 → 40.5.0

package/dist_ts_authswitch/classes.authorityregistry.js

@@ -1,5 +1,5 @@
 import * as plugins from './plugins.js';
-import { AuthSwitchAuthorityAccountModel, AuthSwitchAuthorityBindingModel, AuthSwitchAuthorityClaudeContainerHomeModel, AuthSwitchAuthorityClaudeHandoffModel, AuthSwitchAuthorityClaudeHomeModel, AuthSwitchAuthorityCodexHandoffModel, AuthSwitchAuthorityCodexHomeModel, AuthSwitchAuthorityCodexHostHomeModel, AuthSwitchAuthorityEnrollmentModel, AuthSwitchAuthorityEventModel, AuthSwitchAuthorityGrantModel, AuthSwitchAuthorityHandoffModel, AuthSwitchAuthorityMetaModel, AuthSwitchAuthorityMigrationLedgerModel, AuthSwitchAuthorityOperationModel, AuthSwitchAuthorityUsageEstimateModel, AuthSwitchAuthorityUsageModel, } from './classes.authoritymodels.js';
+import { AuthSwitchAuthorityAccountModel, AuthSwitchAuthorityBindingModel, AuthSwitchAuthorityClaudeContainerHomeModel, AuthSwitchAuthorityClaudeHandoffModel, AuthSwitchAuthorityClaudeHomeModel, AuthSwitchAuthorityCodexHandoffModel, AuthSwitchAuthorityCodexHomeModel, AuthSwitchAuthorityCodexHostHomeModel, AuthSwitchAuthorityEnrollmentModel, AuthSwitchAuthorityEventModel, AuthSwitchAuthorityGrantModel, AuthSwitchAuthorityHandoffModel, AuthSwitchAuthorityMetaModel, AuthSwitchAuthorityMigrationLedgerModel, AuthSwitchAuthorityOperationModel, AuthSwitchAuthoritySpendEntryModel, AuthSwitchAuthoritySpendPeriodModel, AuthSwitchAuthorityUsageEstimateModel, AuthSwitchAuthorityUsageModel, } from './classes.authoritymodels.js';
 const define = (name, model) => Object.freeze({
     name,
     initialize: async (db) => {
@@ -25,6 +25,8 @@ export const authorityModelRegistry = Object.freeze([
     define('authswitch_authority_meta', AuthSwitchAuthorityMetaModel),
     define('authswitch_authority_migration_ledger', AuthSwitchAuthorityMigrationLedgerModel),
     define('authswitch_authority_operations', AuthSwitchAuthorityOperationModel),
+    define('authswitch_authority_spend_entries', AuthSwitchAuthoritySpendEntryModel),
+    define('authswitch_authority_spend_periods', AuthSwitchAuthoritySpendPeriodModel),
     define('authswitch_authority_usage', AuthSwitchAuthorityUsageModel),
     define('authswitch_authority_usage_estimates', AuthSwitchAuthorityUsageEstimateModel),
 ]);
@@ -33,4 +35,4 @@ for (let index = 1; index < authorityModelRegistry.length; index++) {
         throw new Error('Authority model registry must be unique and sorted.');
     }
 }
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhc3Nlcy5hdXRob3JpdHlyZWdpc3RyeS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzX2F1dGhzd2l0Y2gvY2xhc3Nlcy5hdXRob3JpdHlyZWdpc3RyeS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLGNBQWMsQ0FBQztBQUN4QyxPQUFPLEVBQ0wsK0JBQStCLEVBQUUsK0JBQStCLEVBQUUsMkNBQTJDLEVBQzdHLHFDQUFxQyxFQUNyQyxrQ0FBa0MsRUFBRSxvQ0FBb0MsRUFBRSxpQ0FBaUMsRUFDM0cscUNBQXFDLEVBQUUsa0NBQWtDLEVBQ3pFLDZCQUE2QixFQUFFLDZCQUE2QixFQUFFLCtCQUErQixFQUM3Riw0QkFBNEIsRUFBRSx1Q0FBdUMsRUFBRSxpQ0FBaUMsRUFDeEcscUNBQXFDLEVBQUUsNkJBQTZCLEdBQ3JFLE1BQU0sOEJBQThCLENBQUM7QUFRdEMsTUFBTSxNQUFNLEdBQUcsQ0FBQyxJQUFZLEVBQUUsS0FBcUUsRUFBd0IsRUFBRSxDQUMzSCxNQUFNLENBQUMsTUFBTSxDQUFDO0lBQ1osSUFBSTtJQUNKLFVBQVUsRUFBRSxLQUFLLEVBQUUsRUFBK0IsRUFBRSxFQUFFO1FBQ3BELE9BQU8sQ0FBQyxPQUFPLENBQUMsdUJBQXVCLENBQUMsRUFBRSxFQUFFLEVBQUUsRUFBRSxLQUFLLENBQUMsQ0FBQztRQUN2RCxNQUFNLEtBQUssQ0FBQyxJQUFJLEVBQUUsQ0FBQztJQUNyQixDQUFDO0lBQ0QsT0FBTyxFQUFFLEdBQUcsRUFBRSxDQUFDLEtBQUssQ0FBQyxLQUFLLENBQUMsT0FBTyxFQUFFO0NBQ3JDLENBQUMsQ0FBQztBQUVMLCtHQUErRztBQUMvRyxNQUFNLENBQUMsTUFBTSxzQkFBc0IsR0FBb0MsTUFBTSxDQUFDLE1BQU0sQ0FBQztJQUNuRixNQUFNLENBQUMsK0JBQStCLEVBQUUsK0JBQStCLENBQUM7SUFDeEUsTUFBTSxDQUFDLCtCQUErQixFQUFFLCtCQUErQixDQUFDO0lBQ3hFLE1BQU0sQ0FBQyw2Q0FBNkMsRUFBRSwyQ0FBMkMsQ0FBQztJQUNsRyxNQUFNLENBQUMsc0NBQXNDLEVBQUUscUNBQXFDLENBQUM7SUFDckYsTUFBTSxDQUFDLG1DQUFtQyxFQUFFLGtDQUFrQyxDQUFDO0lBQy9FLE1BQU0sQ0FBQyxxQ0FBcUMsRUFBRSxvQ0FBb0MsQ0FBQztJQUNuRixNQUFNLENBQUMsa0NBQWtDLEVBQUUsaUNBQWlDLENBQUM7SUFDN0UsTUFBTSxDQUFDLHVDQUF1QyxFQUFFLHFDQUFxQyxDQUFDO0lBQ3RGLE1BQU0sQ0FBQyxrQ0FBa0MsRUFBRSxrQ0FBa0MsQ0FBQztJQUM5RSxNQUFNLENBQUMsNkJBQTZCLEVBQUUsNkJBQTZCLENBQUM7SUFDcEUsTUFBTSxDQUFDLDZCQUE2QixFQUFFLDZCQUE2QixDQUFDO0lBQ3BFLE1BQU0sQ0FBQywrQkFBK0IsRUFBRSwrQkFBK0IsQ0FBQztJQUN4RSxNQUFNLENBQUMsMkJBQTJCLEVBQUUsNEJBQTRCLENBQUM7SUFDakUsTUFBTSxDQUFDLHVDQUF1QyxFQUFFLHVDQUF1QyxDQUFDO0lBQ3hGLE1BQU0sQ0FBQyxpQ0FBaUMsRUFBRSxpQ0FBaUMsQ0FBQztJQUM1RSxNQUFNLENBQUMsNEJBQTRCLEVBQUUsNkJBQTZCLENBQUM7SUFDbkUsTUFBTSxDQUFDLHNDQUFzQyxFQUFFLHFDQUFxQyxDQUFDO0NBQ3RGLENBQUMsQ0FBQztBQUVILEtBQUssSUFBSSxLQUFLLEdBQUcsQ0FBQyxFQUFFLEtBQUssR0FBRyxzQkFBc0IsQ0FBQyxNQUFNLEVBQUUsS0FBSyxFQUFFLEVBQUUsQ0FBQztJQUNuRSxJQUFJLHNCQUFzQixDQUFDLEtBQUssR0FBRyxDQUFDLENBQUMsQ0FBQyxJQUFJLElBQUksc0JBQXNCLENBQUMsS0FBSyxDQUFDLENBQUMsSUFBSSxFQUFFLENBQUM7UUFDakYsTUFBTSxJQUFJLEtBQUssQ0FBQyxxREFBcUQsQ0FBQyxDQUFDO0lBQ3pFLENBQUM7QUFDSCxDQUFDIn0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhc3Nlcy5hdXRob3JpdHlyZWdpc3RyeS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzX2F1dGhzd2l0Y2gvY2xhc3Nlcy5hdXRob3JpdHlyZWdpc3RyeS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLGNBQWMsQ0FBQztBQUN4QyxPQUFPLEVBQ0wsK0JBQStCLEVBQUUsK0JBQStCLEVBQUUsMkNBQTJDLEVBQzdHLHFDQUFxQyxFQUNyQyxrQ0FBa0MsRUFBRSxvQ0FBb0MsRUFBRSxpQ0FBaUMsRUFDM0cscUNBQXFDLEVBQUUsa0NBQWtDLEVBQ3pFLDZCQUE2QixFQUFFLDZCQUE2QixFQUFFLCtCQUErQixFQUM3Riw0QkFBNEIsRUFBRSx1Q0FBdUMsRUFBRSxpQ0FBaUMsRUFDeEcsa0NBQWtDLEVBQUUsbUNBQW1DLEVBQ3ZFLHFDQUFxQyxFQUFFLDZCQUE2QixHQUNyRSxNQUFNLDhCQUE4QixDQUFDO0FBUXRDLE1BQU0sTUFBTSxHQUFHLENBQUMsSUFBWSxFQUFFLEtBQXFFLEVBQXdCLEVBQUUsQ0FDM0gsTUFBTSxDQUFDLE1BQU0sQ0FBQztJQUNaLElBQUk7SUFDSixVQUFVLEVBQUUsS0FBSyxFQUFFLEVBQStCLEVBQUUsRUFBRTtRQUNwRCxPQUFPLENBQUMsT0FBTyxDQUFDLHVCQUF1QixDQUFDLEVBQUUsRUFBRSxFQUFFLEVBQUUsS0FBSyxDQUFDLENBQUM7UUFDdkQsTUFBTSxLQUFLLENBQUMsSUFBSSxFQUFFLENBQUM7SUFDckIsQ0FBQztJQUNELE9BQU8sRUFBRSxHQUFHLEVBQUUsQ0FBQyxLQUFLLENBQUMsS0FBSyxDQUFDLE9BQU8sRUFBRTtDQUNyQyxDQUFDLENBQUM7QUFFTCwrR0FBK0c7QUFDL0csTUFBTSxDQUFDLE1BQU0sc0JBQXNCLEdBQW9DLE1BQU0sQ0FBQyxNQUFNLENBQUM7SUFDbkYsTUFBTSxDQUFDLCtCQUErQixFQUFFLCtCQUErQixDQUFDO0lBQ3hFLE1BQU0sQ0FBQywrQkFBK0IsRUFBRSwrQkFBK0IsQ0FBQztJQUN4RSxNQUFNLENBQUMsNkNBQTZDLEVBQUUsMkNBQTJDLENBQUM7SUFDbEcsTUFBTSxDQUFDLHNDQUFzQyxFQUFFLHFDQUFxQyxDQUFDO0lBQ3JGLE1BQU0sQ0FBQyxtQ0FBbUMsRUFBRSxrQ0FBa0MsQ0FBQztJQUMvRSxNQUFNLENBQUMscUNBQXFDLEVBQUUsb0NBQW9DLENBQUM7SUFDbkYsTUFBTSxDQUFDLGtDQUFrQyxFQUFFLGlDQUFpQyxDQUFDO0lBQzdFLE1BQU0sQ0FBQyx1Q0FBdUMsRUFBRSxxQ0FBcUMsQ0FBQztJQUN0RixNQUFNLENBQUMsa0NBQWtDLEVBQUUsa0NBQWtDLENBQUM7SUFDOUUsTUFBTSxDQUFDLDZCQUE2QixFQUFFLDZCQUE2QixDQUFDO0lBQ3BFLE1BQU0sQ0FBQyw2QkFBNkIsRUFBRSw2QkFBNkIsQ0FBQztJQUNwRSxNQUFNLENBQUMsK0JBQStCLEVBQUUsK0JBQStCLENBQUM7SUFDeEUsTUFBTSxDQUFDLDJCQUEyQixFQUFFLDRCQUE0QixDQUFDO0lBQ2pFLE1BQU0sQ0FBQyx1Q0FBdUMsRUFBRSx1Q0FBdUMsQ0FBQztJQUN4RixNQUFNLENBQUMsaUNBQWlDLEVBQUUsaUNBQWlDLENBQUM7SUFDNUUsTUFBTSxDQUFDLG9DQUFvQyxFQUFFLGtDQUFrQyxDQUFDO0lBQ2hGLE1BQU0sQ0FBQyxvQ0FBb0MsRUFBRSxtQ0FBbUMsQ0FBQztJQUNqRixNQUFNLENBQUMsNEJBQTRCLEVBQUUsNkJBQTZCLENBQUM7SUFDbkUsTUFBTSxDQUFDLHNDQUFzQyxFQUFFLHFDQUFxQyxDQUFDO0NBQ3RGLENBQUMsQ0FBQztBQUVILEtBQUssSUFBSSxLQUFLLEdBQUcsQ0FBQyxFQUFFLEtBQUssR0FBRyxzQkFBc0IsQ0FBQyxNQUFNLEVBQUUsS0FBSyxFQUFFLEVBQUUsQ0FBQztJQUNuRSxJQUFJLHNCQUFzQixDQUFDLEtBQUssR0FBRyxDQUFDLENBQUMsQ0FBQyxJQUFJLElBQUksc0JBQXNCLENBQUMsS0FBSyxDQUFDLENBQUMsSUFBSSxFQUFFLENBQUM7UUFDakYsTUFBTSxJQUFJLEtBQUssQ0FBQyxxREFBcUQsQ0FBQyxDQUFDO0lBQ3pFLENBQUM7QUFDSCxDQUFDIn0=

package/dist_ts_authswitch/classes.authorityusage.d.ts

@@ -3,14 +3,16 @@ import type { IOpenAiAccountRateLimits } from './interfaces.openai.js';
 import type { IClaudeLogin, IClaudeStatusRead, IClaudeSubscription } from './classes.claudestatus.js';
 import { type TAuthSwitchUsageObservation } from './authority-usageheaders.js';
 import type { IAuthSwitchTokenUsage } from './authority-usagetokens.js';
+import { type IAuthSwitchSpendReading } from './authority-spend.js';
+import type { IAuthSwitchSpendAnswer, TAuthSwitchPaymentProblemCause as TCause } from './authority-contract.js';
 import { type IAuthSwitchUsageEstimateState, type IAuthSwitchUsageEstimatorOptions, type TAuthSwitchEstimateBasis } from './classes.authorityusageestimate.js';
 type TRateLimits = IOpenAiAccountRateLimits;
 /**
  * Why a usage reading is missing or incomplete. `held_in_container`: the Claude login runs in a registered container
  * home, whose files are the container's; the authority reads its usage again once the login is moved out. `pending`:
- * the account's first read has not finished yet.
+ * the account's first read has not finished yet. `spend_unavailable`: an API key's spend ledger could not be read.
  */
-export type TAuthSwitchUsageProblem = 'none' | 'unsupported' | 'access_unavailable' | 'provider_unavailable' | 'provider_rejected' | 'profile_unavailable' | 'usage_unavailable' | 'context_changed' | 'expired' | 'held_in_container' | 'pending';
+export type TAuthSwitchUsageProblem = 'none' | 'unsupported' | 'access_unavailable' | 'provider_unavailable' | 'provider_rejected' | 'profile_unavailable' | 'usage_unavailable' | 'context_changed' | 'expired' | 'held_in_container' | 'pending' | 'spend_unavailable';
 export interface IAuthSwitchNativeUsageSource {
     homeId: string;
     credentialDigest: string;
@@ -72,13 +74,22 @@ export interface IAuthSwitchClaudeStatus {
         retryAt: string | null;
     } | null;
 }
-export type TAuthSwitchUsageReading = {
+/** A usage reading the authority reads from a provider for a subscription sign-in, and stores between its runs. */
+export type TAuthSwitchProviderUsageReading = {
     kind: 'openai';
     rateLimits: TRateLimits;
 } | {
     kind: 'anthropic';
     status: IAuthSwitchClaudeStatus;
 };
+/**
+ * A login's usage reading: a subscription sign-in's, as its provider stated it, or an API key's monthly spend
+ * (`spend`), which the authority answers from what AGL's inference proxy reported and never reads from a provider.
+ */
+export type TAuthSwitchUsageReading = TAuthSwitchProviderUsageReading | {
+    kind: 'spend';
+    spend: IAuthSwitchSpendReading;
+};
 export interface IAuthSwitchUsageAccess {
     accessToken: string;
     accountId: string;
@@ -101,9 +112,31 @@ export interface IAuthSwitchUsageAccess {
 export interface IAuthSwitchPaymentProblem {
     at: string;
     subscription: IClaudeSubscription | null;
+    /**
+     * What the provider refused for (`TAuthSwitchPaymentProblemCause`), present only for `spend_cap` and `quota`, which
+     * only an API key's login is held with; absent, the cause is `billing`, on a Claude login and an API key alike. A
+     * problem with a cause has no subscription.
+     */
+    cause?: Exclude<TAuthSwitchPaymentProblemCause, 'billing'>;
+    /**
+     * When a `spend_cap` lifts by itself: the end of the month in UTC `at` falls in (`authSwitchSpendPeriod(at).end`),
+     * present exactly for that cause; once it passed the problem holds nothing (`authSwitchPaymentProblemHeld`). Every
+     * other problem holds until it is cleared: a Claude login's by a read, an API key's by a re-check (`usage.recheck`).
+     */
+    until?: string;
 }
 /**
- * How a re-check's read went (`AuthSwitchAuthorityUsage.recheck`): `healthy` -- the profile was found, the sign-in
+ * Why a provider refused inference on an API key for money, as AGL's inference proxy read the refusal: `billing`, the
+ * organization's billing (Anthropic HTTP 402 `billing_error`, and every Claude sign-in's payment problem); `spend_cap`,
+ * the monthly spend cap of the key's usage tier, which lifts at 00:00 UTC on the first of the next month (Anthropic 429
+ * `enforced_spend_limit_reached`); `quota`, the organization's or project's credit or spend limit (OpenAI 429
+ * `insufficient_quota`).
+ */
+export type TAuthSwitchPaymentProblemCause = 'billing' | 'spend_cap' | 'quota';
+/**
+ * How a re-check went (`AuthSwitchAuthorityUsage.recheck`). `cleared`: the login is an API key, whose hold a re-check
+ * lifts without asking the provider, which states no billing or quota on a model list; the next request shows whether the
+ * provider takes the key again. Every other outcome is a Claude login's read: `healthy` -- the profile was found, the sign-in
  * accepted and the identity matched -- clears a payment problem; every other outcome clears nothing. `credential_rejected`:
  * Anthropic rejected the sign-in, renewed too. `token_unusable`: no access token usable for a profile read (it could not
  * be resolved, is not fresh enough, or lacks the `user:profile` scope). `profile_missing`: the profile read failed or its
@@ -111,7 +144,7 @@ export interface IAuthSwitchPaymentProblem {
  * run or publish -- the login changed or is not read, its record could not be written, or the usage service's retry time
  * lies ahead.
  */
-export type TAuthSwitchRecheckOutcome = 'healthy' | 'credential_rejected' | 'token_unusable' | 'profile_missing' | 'mismatch' | 'read_failed';
+export type TAuthSwitchRecheckOutcome = 'healthy' | 'credential_rejected' | 'token_unusable' | 'profile_missing' | 'mismatch' | 'read_failed' | 'cleared';
 /** A re-check's answer: the usage the authority holds once its read finished, and how that read went. */
 export interface IAuthSwitchUsageRecheck {
     usage: IAuthSwitchUsageSnapshot;
@@ -121,7 +154,7 @@ export interface IAuthSwitchUsageRecheck {
 export interface IAuthSwitchStoredUsage {
     context: IAuthSwitchUsageContext;
     updateId: string;
-    reading: TAuthSwitchUsageReading | null;
+    reading: TAuthSwitchProviderUsageReading | null;
     observedAt: string | null;
     currentUntil: string | null;
     staleUntil: string | null;
@@ -265,6 +298,14 @@ export interface IAuthSwitchAuthorityUsageOptions {
     estimate?: IAuthSwitchUsageEstimatorOptions;
     /** Where the reader's notes go, one line each: standard error, the service's journal, unless set. */
     log?: (lineArg: string) => void;
+    /**
+     * An API key's spend ledger: its month's reading at `nowArg`, and a spend report recorded in one transaction
+     * (`AuthSwitchAuthorityDatabase.readSpend`, `.recordSpend`). Without it the authority answers no key's usage.
+     */
+    spend?: {
+        read(accountId: string, loginId: string, nowArg: number): Promise<IAuthSwitchSpendReading>;
+        record(accountId: string, loginId: string, answers: readonly IAuthSwitchSpendAnswer[], nowArg: number): Promise<IAuthSwitchSpendReading>;
+    };
 }
 /** What a client that served requests on a login reports about the account: see `report`. */
 export interface IAuthSwitchUsageReport {
@@ -358,7 +399,7 @@ export declare class AuthSwitchAuthorityUsage {
      * carries it. Refused for any login but a Claude login the authority renews, and for one with no usage record of its
      * sign-in yet, which the proxy never routed to. The provider is not asked.
      */
-    reportPaymentProblem(accountId: string, loginId: string, observedAt: string): Promise<IAuthSwitchUsageSnapshot>;
+    reportPaymentProblem(accountId: string, loginId: string, observedAt: string, cause?: TCause): Promise<IAuthSwitchUsageSnapshot>;
     /**
      * Reads the login at once, as `requestRead` does, and answers how that read went with the usage held once it finished
      * (`IAuthSwitchUsageRecheck`). It is a re-check: a read that finds the profile, its sign-in accepted and its identity
@@ -367,6 +408,27 @@ export declare class AuthSwitchAuthorityUsage {
      * than `recheckWaitMs` is not waited for: the answer is then `read_failed`, and the next read is no re-check.
      */
     recheck(accountId: string, loginId: string): Promise<IAuthSwitchUsageRecheck>;
+    /**
+     * Records what answers relayed on an API key's login cost (`authswitch.authority.usage.spend`) and answers the key's
+     * usage once the report committed. A removed key's spend is recorded too; its usage then answers unavailable.
+     */
+    recordSpend(accountId: string, loginId: string, answers: readonly IAuthSwitchSpendAnswer[]): Promise<IAuthSwitchUsageSnapshot>;
+    /**
+     * An API key's usage: its month's spend from the ledger, current as of now, which stays current until the month ends
+     * or a report or a limit change moves it, and the payment problem it is held with, while it holds.
+     */
+    private spendAnswer;
+    /**
+     * Holds an API key with a payment problem on its usage record, which holds nothing else: when it was seen -- a time
+     * ahead of the authority's clock counts as now -- and its cause; `billing` is written as no cause, and a `spend_cap`
+     * lifts at the end of the month it was seen in. False when another write of the record landed first.
+     */
+    private holdApiKey;
+    /**
+     * A re-check of an API key: lifts the payment problem it is held with, without asking the provider, whose model list
+     * states no billing or quota; the next request shows whether the provider takes the key again.
+     */
+    private clearApiKey;
     /** Logs a Claude subscription status the first time this run reads it, up to `maximumLoggedSubscriptionStatuses`. */
     private noteSubscriptionStatus;
     /**