@north-light/api 0.3.550 → 0.3.552

package/dist/api/client.d.ts

@@ -1,4 +1,5 @@
 import { ApiError } from './errors.js';
+import type { ChargeListDTO, SpendLimitListDTO, SpendLimitRemovedDTO, SpendLimitSetRequest, LimitDTO } from './dto/charges.js';
 import type { AppLimitsChangeDTO, LimitsDTO, SetAppLimitsRequest } from './dto/limits.js';
 import type { DaemonAdmitDTO, DaemonRestartDTO, DueDTO, HealthDTO, ReadyDTO, MigrateStateDTO, MigrateStateRequest, StatusDTO } from './dto/health.js';
 import type { BashJobStatusDTO, BashJobStopResultDTO } from './dto/bash-jobs.js';
@@ -230,6 +231,16 @@ export declare class CrtrClient {
     showLimits(): Promise<LimitsDTO>;
     setAppLimits(app: string, req: SetAppLimitsRequest): Promise<AppLimitsChangeDTO>;
     removeAppLimits(app: string, fields: Array<'memory' | 'disk'>): Promise<AppLimitsChangeDTO>;
+    /** One page of this runtime's charge rows for a month, or the rows under a reference, with the month's totals; pass `next` back as `after`. */
+    listCharges(query?: {
+        month?: string;
+        under?: string;
+        after?: string;
+        limit?: number;
+    }): Promise<ChargeListDTO>;
+    listSpendLimits(): Promise<SpendLimitListDTO>;
+    setSpendLimit(id: string, req: SpendLimitSetRequest): Promise<LimitDTO>;
+    removeSpendLimit(id: string): Promise<SpendLimitRemovedDTO>;
     /** Every space on the runtime with its size. */
     listSpaces(): Promise<SpaceListDTO>;
     subscribe(id: string, req: SubscribeRequest): Promise<SubscriptionDTO>;

package/dist/api/client.js

@@ -402,6 +402,19 @@ export class CrtrClient {
     removeAppLimits(app, fields) {
         return this.request('DELETE', withQuery(routes.limitsApp(app), { fields: fields.join(',') }));
     }
+    /** One page of this runtime's charge rows for a month, or the rows under a reference, with the month's totals; pass `next` back as `after`. */
+    listCharges(query = {}) {
+        return this.request('GET', withQuery(routes.charges(), query));
+    }
+    listSpendLimits() {
+        return this.request('GET', routes.spendLimits());
+    }
+    setSpendLimit(id, req) {
+        return this.request('PUT', routes.spendLimit(id), req);
+    }
+    removeSpendLimit(id) {
+        return this.request('DELETE', routes.spendLimit(id));
+    }
     /** Every space on the runtime with its size. */
     listSpaces() {
         return this.request('GET', routes.spaces());

package/dist/api/contract.d.ts

@@ -1,5 +1,5 @@
 /** The contract level this build serves and requires. Written by `scripts/contract.mjs release`; never edit by hand. */
-export declare const CONTRACT_LEVEL = "1.31";
+export declare const CONTRACT_LEVEL = "1.32";
 /** Request header naming the one contract level the caller needs, e.g. `1.3`. Optional: absent means no check. */
 export declare const REQUIRED_CONTRACT_HEADER = "Crouter-Required-Contract";
 /** Response header listing the contract levels the server serves, comma-separated, one per major, e.g. `1.3`. */

package/dist/api/contract.js

@@ -12,7 +12,7 @@
 //
 // PURITY (spec §3.1): Node built-ins + `src/api/*` only.
 /** The contract level this build serves and requires. Written by `scripts/contract.mjs release`; never edit by hand. */
-export const CONTRACT_LEVEL = '1.31';
+export const CONTRACT_LEVEL = '1.32';
 /** Request header naming the one contract level the caller needs, e.g. `1.3`. Optional: absent means no check. */
 export const REQUIRED_CONTRACT_HEADER = 'Crouter-Required-Contract';
 /** Response header listing the contract levels the server serves, comma-separated, one per major, e.g. `1.3`. */

package/dist/api/dto/charges.d.ts

@@ -0,0 +1,122 @@
+export type ChargeKindDTO = 'model' | 'tool' | 'sandbox' | 'job' | 'storage' | 'take';
+export type FundingDTO = 'bill' | 'subscription' | 'key' | 'endpoint' | 'take' | 'legacy';
+export type LimitSourceDTO = 'grant_sync' | 'person' | 'operator';
+/** One charge row. Every field of the ledger's `charges` table. */
+export interface ChargeDTO {
+    /** `receipt:<provider>:<receipt id>` for a tool charge; `legacy:…` for a migrated aggregate; otherwise a fresh id. */
+    id: string;
+    /** The `Request-Id` of the call that spent. Null on legacy rows. */
+    request: string | null;
+    at: string;
+    /** UTC `YYYY-MM`. */
+    month: string;
+    kind: ChargeKindDTO;
+    /** The model that answered, or `<provider id>:<tool path>` for a tool. */
+    what: string;
+    /** `{input, output, cache_read, cache_write}` tokens, or `{units, unit}` from a receipt; null on a legacy tool row. */
+    units: Record<string, unknown> | null;
+    /** List-price dollars; null when the model has no list price; 0 on a refused row. */
+    usd: number | null;
+    /** The principal charged: `user:<id>` or `app:<id>`. */
+    payer: string;
+    funding: FundingDTO;
+    /** The person the work is for. */
+    sub: string | null;
+    /** The app the charge is attributed to. */
+    grantee: string;
+    node: string | null;
+    run: string | null;
+    /** The vendor or provider app the money goes to. */
+    provider: string | null;
+    /** `message:<id>`, `request:<id>`, `cron_run:<id>`, or null for a root. */
+    caused_by: string | null;
+    /** The vendor's request id for a model row; the receipt id for a tool row. */
+    vendor_ref: string | null;
+    /** Set when the check refused this call: the limit id and reason. */
+    refused: {
+        limit: string;
+        reason: string;
+    } | null;
+}
+/** One limit row. A null filter means any. */
+export interface LimitDTO {
+    id: string;
+    payer: string;
+    funding: FundingDTO | null;
+    grantee: string | null;
+    provider: string | null;
+    sub: string | null;
+    /** 0 is an emergency stop. */
+    usd_per_month: number;
+    source: LimitSourceDTO;
+    updated_at: string;
+}
+/** One month's dollars from the rollup, with the limit rows. */
+export interface ChargeTotalsDTO {
+    month: string;
+    by_payer: Array<{
+        payer: string;
+        usd: number;
+    }>;
+    by_funding: Array<{
+        payer: string;
+        funding: string;
+        usd: number;
+    }>;
+    limits: LimitDTO[];
+}
+/** `GET /v1/charges?month=&under=&after=&limit=`: this runtime's rows in `(at, id)` order, newest last. An app sees only rows whose grantee it is. */
+export interface ChargeListDTO {
+    /** The month the rows are filtered to: the requested one, else the current month. Absent when `under` is given without `month`, because the chain spans months. */
+    month?: string;
+    /** At most `limit` rows (default 1,000, at most 10,000). */
+    charges: ChargeDTO[];
+    /** Pass as `after` to read the next page; null when this page is the last. */
+    next: string | null;
+    /** Month totals by payer and funding with the matching limits, over every row of the month rather than this page. Present for the person and a terminal node; absent for an app and when `under` is given. */
+    totals?: ChargeTotalsDTO;
+}
+/** `GET /v1/spend-limits`. */
+export interface SpendLimitListDTO {
+    limits: LimitDTO[];
+}
+/** `PUT /v1/spend-limits/:id`: the id must start `person:`. Writes a limit row with source `person`; an existing row of that id is replaced. */
+export interface SpendLimitSetRequest {
+    /** `user:<id>` (the person) or `app:<id>`. */
+    payer: string;
+    usd_per_month: number;
+    funding?: FundingDTO | null;
+    grantee?: string | null;
+    provider?: string | null;
+    sub?: string | null;
+}
+/** `DELETE /v1/spend-limits/:id`: clears a person-set limit row. */
+export interface SpendLimitRemovedDTO {
+    id: string;
+    removed: true;
+}
+/** The `details` of a `402 cap_exhausted` refusal. */
+export interface CapExhaustedDetails {
+    limit: {
+        id: string;
+        payer: string;
+        filters: {
+            funding: FundingDTO | null;
+            grantee: string | null;
+            provider: string | null;
+            sub: string | null;
+        };
+        usd_per_month: number;
+        source: LimitSourceDTO;
+    };
+    /** The dollars counted against the limit this month. */
+    usd: number;
+    /** When the count starts over. */
+    reset_at: string;
+    /** What the person can do: raise the app's cap, or clear their own limit; absent for an operator limit. */
+    user_action?: 'raise_cap' | 'clear_limit';
+    /** @deprecated Use `limit.usd_per_month`. */
+    spend_cap: number;
+    /** @deprecated Use `usd`. */
+    usd_equivalent: number;
+}

package/dist/api/dto/charges.js

@@ -0,0 +1,3 @@
+// The money ledger's read and limit surfaces: `charges.list`, `spend_limits.list`, `spend_limits.set`, `spend_limits.remove`.
+// (`limits.*` and `/v1/limits` are the per-app memory and disk caps; these are dollar limits.)
+export {};

package/dist/api/dto/usage.d.ts

@@ -6,12 +6,12 @@ export interface SpendUsageModelRowDTO {
     /** List-price cost; null when the served model has no list price (an app-registered endpoint, or an unpriced model). */
     usd_equivalent: number | null;
 }
-/** `usage.get`: the caller's grantee's month-to-date spend (daemon operations, `usage.get`). */
+/** `usage.get` (deprecated in favour of `charges.list`): the caller's grantee's month-to-date spend (daemon operations, `usage.get`). */
 export interface SpendUsageDTO {
     grantee: string;
     /** UTC calendar month, `YYYY-MM`. */
     month: string;
-    /** User-paid spend this month: every model completion and provider receipt. Receipts have no `by_model` row, so this can exceed the sum of `by_model`. */
+    /** User-paid spend this month for this grantee: every model completion and every priced tool call. Tool calls have no `by_model` row, so this can exceed the sum of `by_model`. */
     usd_equivalent: number;
     /** User-paid model completions, one row per served model. */
     by_model: SpendUsageModelRowDTO[];
@@ -20,7 +20,7 @@ export interface SpendUsageDTO {
         usd_equivalent: number;
         by_model: SpendUsageModelRowDTO[];
     };
-    /** The monthly cap on user-paid spend; once `usd_equivalent` reaches it, user-paid model calls answer `cap_exhausted` until `reset_at`. Null when uncapped. */
+    /** The monthly cap on user-paid spend, which now counts priced tool calls as well as model calls; once `usd_equivalent` reaches it, calls billed to the user answer `cap_exhausted` until `reset_at`. Null when no limit row exists. */
     spend_cap: number | null;
     /** 00:00Z on the first day of the next UTC month, when the count starts over. */
     reset_at: string;

package/dist/api/index.d.ts

@@ -17,6 +17,7 @@ export * from './dto/health.js';
 export * from './dto/limits.js';
 export * from './dto/grants.js';
 export * from './dto/usage.js';
+export * from './dto/charges.js';
 export * from './dto/nodes.js';
 export * from './dto/node-outcomes.js';
 export * from './dto/node-events.js';

package/dist/api/index.js

@@ -14,6 +14,7 @@ export * from './dto/health.js';
 export * from './dto/limits.js';
 export * from './dto/grants.js';
 export * from './dto/usage.js';
+export * from './dto/charges.js';
 export * from './dto/nodes.js';
 export * from './dto/node-outcomes.js';
 export * from './dto/node-events.js';

package/dist/api/routes.d.ts

@@ -74,6 +74,9 @@ export declare const routes: {
     readonly spaces: () => string;
     readonly limits: () => string;
     readonly limitsApp: (app: string) => string;
+    readonly charges: () => string;
+    readonly spendLimits: () => string;
+    readonly spendLimit: (id: string) => string;
     readonly nodeAttach: (id: string) => string;
     readonly focuses: () => string;
     readonly focusByNode: () => string;

package/dist/api/routes.js

@@ -92,6 +92,9 @@ export const routes = {
     spaces: () => `${V}/spaces`,
     limits: () => `${V}/limits`,
     limitsApp: (app) => `${V}/limits/apps/${encodeURIComponent(app)}`,
+    charges: () => `${V}/charges`,
+    spendLimits: () => `${V}/spend-limits`,
+    spendLimit: (id) => `${V}/spend-limits/${encodeURIComponent(id)}`,
     nodeAttach: (id) => `${V}/nodes/${id}/attach`,
     // Focuses (viewer registry — the canvas.db `focuses` table)
     focuses: () => `${V}/focuses`,

package/dist/core/config.js

@@ -850,6 +850,10 @@ function mergeConfig(partial) {
     if (paths?.user_files !== undefined && (typeof paths.user_files !== 'string' || !paths.user_files.startsWith('/'))) {
         throw new Error('paths.user_files must be an absolute path');
     }
+    const ledger = partial.ledger;
+    if (ledger?.take_pct !== undefined && (typeof ledger.take_pct !== 'number' || !Number.isFinite(ledger.take_pct) || ledger.take_pct < 0 || ledger.take_pct > 100)) {
+        throw new Error('ledger.take_pct must be a number from 0 to 100');
+    }
     const store = partial.store;
     const runtime = partial.runtime;
     if (runtime?.person_uids !== undefined && (!Array.isArray(runtime.person_uids)
@@ -859,7 +863,7 @@ function mergeConfig(partial) {
     const spawnEnv = mergeSpawnEnv(partial.spawnEnv, defaults.spawnEnv?.allow);
     const bin = normalizeBin(partial.bin);
     const humanActions = normalizeHumanActions(partial.humanActions);
-    return { bin, humanActions, schema_version, marketplaces, plugins, auto_update, max_panes_per_window, auto_open_child_viewers, brokerThresholds, lifecycle, completion_bell, working_gerunds, whip_mode, page_components, page_surface, whip_messages, whip_message_mode, mouse_mode_default, live_cycles, condensed_history, bash_tool_purpose, fold_finished_tools, summarize_tool_calls, detailed_tool_recaps, document_port, consolidate_replies, keybindings, tmux_passthrough, modelLadders, providerOptions, ...(Object.keys(modelRoutes).length > 0 ? { modelRoutes } : {}), ...(Object.keys(routes.legacy).length > 0 ? { legacyModelRoutes: routes.legacy } : {}), ...(modelRouting !== undefined ? { modelRouting } : {}), kinds, remoteCanvas, api, ...(paths ? { paths } : {}), ...(store ? { store } : {}), ...(runtime ? { runtime } : {}), spawnEnv };
+    return { bin, humanActions, schema_version, marketplaces, plugins, auto_update, max_panes_per_window, auto_open_child_viewers, brokerThresholds, lifecycle, completion_bell, working_gerunds, whip_mode, page_components, page_surface, whip_messages, whip_message_mode, mouse_mode_default, live_cycles, condensed_history, bash_tool_purpose, fold_finished_tools, summarize_tool_calls, detailed_tool_recaps, document_port, consolidate_replies, keybindings, tmux_passthrough, modelLadders, providerOptions, ...(Object.keys(modelRoutes).length > 0 ? { modelRoutes } : {}), ...(Object.keys(routes.legacy).length > 0 ? { legacyModelRoutes: routes.legacy } : {}), ...(modelRouting !== undefined ? { modelRouting } : {}), kinds, remoteCanvas, api, ...(paths ? { paths } : {}), ...(ledger ? { ledger } : {}), ...(store ? { store } : {}), ...(runtime ? { runtime } : {}), spawnEnv };
 }
 /** Raw (un-defaulted) partial config for one scope, or null if the scope has
  *  no root or no config.json. Used by `readMergedLaunchConfig` to layer

package/dist/core/user-settings.d.ts

@@ -377,6 +377,10 @@ export declare const CONFIG_SETTINGS_COVERAGE: {
         surface: "specialized";
         owner: string;
     };
+    ledger: {
+        surface: "specialized";
+        owner: string;
+    };
     store: {
         surface: "specialized";
         owner: string;

package/dist/core/user-settings.js

@@ -469,6 +469,7 @@ export const CONFIG_SETTINGS_COVERAGE = {
     remoteCanvas: { surface: 'specialized', owner: 'canvas config commands' },
     api: { surface: 'specialized', owner: 'sys connect' },
     paths: { surface: 'specialized', owner: 'runtime layout' },
+    ledger: { surface: 'specialized', owner: 'money ledger (take_pct)' },
     store: { surface: 'specialized', owner: 'daemon conversation store' },
     runtime: { surface: 'specialized', owner: 'app-facing listener' },
     spawnEnv: { surface: 'specialized', owner: 'spawn environment allow-list' },

package/dist/types.d.ts

@@ -402,6 +402,10 @@ export interface ScopeConfig {
     paths?: {
         user_files?: string;
     };
+    /** The money ledger. `take_pct` (0-100, default 0) is Northlight's take on each priced model or tool charge; at 0 no take rows are written. */
+    ledger?: {
+        take_pct?: number;
+    };
     /** Conversation store configuration for the daemon. */
     store?: {
         root?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/api",
-  "version": "0.3.550",
+  "version": "0.3.552",
   "description": "Typed crtrd /v1 API contract — DTOs, route builders, the error contract, the CrtrClient, and the command-plugin manifest format. Zero runtime dependencies.",
   "type": "module",
   "main": "./dist/api/index.js",