@hanzo/build 0.2.9 → 0.2.11

package/README.md

@@ -42,9 +42,10 @@ import { Builder, type Host } from '@hanzo/build'
 `Host` is everything that differs between hosts: where the platform is
 (`api`), the bearer (`token()`, read at call time), the org (`org`), who is
 signed in (`person`), whether they administer the org (`admin`), the address
-under the mount (`path`) and how to move (`go`), and where to link out
-(`links`, `open`). Peers: `@hanzo/ui`, `@hanzo/gui`, `@hanzogui/lucide-icons-2`,
-`react`.
+under the mount (`path`) and how to move (`go`), where to link out
+(`links`, `open`), and — for a host that can repaint itself — the theme
+(`theme`, `chooseTheme`), which follows the person's saved choice. Peers:
+`@hanzo/ui`, `@hanzo/gui`, `@hanzogui/lucide-icons-2`, `react`.
 
 ### In a host that has its own rail
 
@@ -72,13 +73,16 @@ hanzo.id token for `Host.admin`. One left column, never two.
 | `''` | New — the empty state and the composer |
 | `sess_<32 hex>` | one run, live |
 | `-/automations` | repeating work, read from `/v1/auto/flows` |
-| `-/mcp` | the fleet's native MCP servers, from `POST /v1/mcp` `tools/list` |
+| `-/customize` · `-/customize/connectors` · `/plugins` · `/agents` | Customize: skills, connectors, plugins, agents |
+| `-/mcp` | Connectors → Discover, where the fleet's native MCP servers now live |
 | `-/codebases` | the forge's repositories |
 | `-/sync` | bring granted repositories onto the forge |
 | `-/projects` | the forge's boards |
 | `-/issues` | the forge's issues |
 | `-/artifacts` | what the org has built |
 | `-/templates` | the public starters |
+| `-/plans` | the plans this brand sells, and the move to another |
+| `-/settings/<section>` | Billing, Usage, Members, Integrations, Notifications, … |
 | `<slug>` | a project's workspace |
 
 A project slug holds no `_` and never starts with `-`, so the forms cannot
@@ -88,25 +92,86 @@ collide.
 
 **The rail** (hanzo.build). At the top, the mark. Signed in to an organization,
 that spot is the organization switcher: the org, and the projects under it.
-New, then Automations, then the forge — Codebase, Projects, Issues — then MCP,
-Artifacts, More (Templates, Machines, Docs), then the org's coding runs newest
-first with a live status dot. The account stays at the foot. Settings opens
-that account on this page. Collapse is an explicit toggle kept in this browser.
-A host with its own rail draws `DevSection` there instead.
+New, Projects, Artifacts, Customize, Automations, then More (Codebase, Issues,
+Templates, Machines, Docs), then the org's coding runs newest first with a live
+status dot. At the foot, a card offering Hanzo in Slack (dismissed once, gone in
+this browser) and the account, whose menu holds the email, Settings, Usage, View
+all plans, Get help (the docs, in a new tab) and Log out. Collapse is an explicit
+toggle kept in this browser. A host with its own rail draws `DevSection` there
+instead.
 
-**MCP.** The native servers `POST /v1/mcp` lists, each with the operations it
-names. A run starts a server when it calls it, and the server stays up afterwards.
+**Artifacts.** A few starters to make something new from, each copied into a
+project as Templates does, then every project under the month it was last
+edited, public or private, with rename, visibility and delete. A project belongs
+to the org and names no author, so there is no Yours or Shared with you.
+
+**Settings, Code.** Environments: every codebase that has one, opened in the
+same editor a run shows, forgotten by an org admin. Machines: `hanzo login` and
+`hanzo link` to link one, registering one by hand, and each machine's rename,
+drain, claim key (shown once) and removal. API keys: your secret and publishable
+key, a new one shown once, rotated or revoked.
+
+**Customize.** What the agent brings to a run, a tab each — Skills, Connectors,
+Plugins, Agents — and in each, Yours (what the org has) and Discover (what it
+can add), one search and one Add. Any member of the org may change any of it;
+the platform gates none of it to admins.
+
+- Skills: the org's own SKILL.md skills, written, revised and deleted here, and
+  the brand's catalogue (`/.well-known/agent-skills/`) to read and add. Adding is
+  switching `skill_<name>` on, and a switch per skill turns it off again.
+- Connectors: the MCP servers the org added — by URL or off the shelf, a secret
+  sealed in KMS — each with a switch per tool. Adding one switches its tools on.
+  Discover is the shelf (featured first; a listing that ships only a package has
+  no plus) and the fleet's native servers `POST /v1/mcp` lists, which every run
+  can call and nothing adds.
+- Plugins: TypeScript connectors built on the platform, from source or from a
+  description of an API; a failed build says why. Discover lists what the
+  deployment mounts.
+- Agents: the org's own — model, instructions, tools, budget — created, edited
+  (only what changed is sent) and deleted; Discover is the platform's presets
+  whose tool calls run on the platform.
 
 **New.** "What's up next?", and at the foot the composer: where the run runs
-(Default is the platform's sandbox; the org's machines follow), the codebase
-and the branch — the forge's repositories, filtered as you type — then the
-ask. Under it: attach (files ride the prompt as text), dictate, Build or Plan,
-and the model and effort. A codebase can be added to a project. Opening a
-codebase or an issue from its own screen lands here with that choice already
-made.
+(Cloud is the platform's sandbox with the codebase's environment; the org's
+machines follow under remote control, each linked with `hanzo link`), the
+codebase and the branch — the forge's repositories, filtered as you type, read
+again with Refresh list, and a way to Sync for a GitHub repository that is not
+there yet — then the ask. Under it: attach (files ride the prompt as text),
+dictate, Build or Plan, and the model and effort. A codebase can be added to a
+project. Opening a codebase or an issue from its own screen lands here with
+that choice already made.
+
+**A run.** The transcript as it streams, drawn by what each part is: what the
+agent says as markdown, each command it runs as a card that opens onto its
+output, the files it edits with their diff, the files it reads as chips, and the
+run's own steps. Steering while it works; Pause, Resume and Stop; the pull
+request once it pushes one. Once it has finished, a follow-up starts a new run
+from the branch it pushed — the same codebase, place and mode — and opens it; a
+paused sandbox run goes on the same way. A plan run ends with its plan and
+Approve and build. Rename it, share a project run's story publicly, and find any
+run by status in Find. Beside it:
+
+- Environment: the codebase's environment, and the run's facts.
+- Git: what it pushed, read from the forge — Diff, Review, Commits.
+- Desktop: its sandbox's screen, framed from the sandbox's own noVNC page. A
+  sandbox run asks for a desktop.
+- Terminal: a shell in the same working tree (a tmux session named for the run,
+  so it reattaches), and the agent's own log.
+- Files: the working tree live from the sandbox, or the run's branch; and
+  Artifacts, what it produced.
+- Subscriptions.
+
+The desktop and the shell are the sandbox's, so they close when the run stops.
+The setup bar says how long setup runs here have taken, once there are three.
 
-**A run.** The transcript as it streams, steering while it works, Stop, and
-the pull request once it pushes one.
+**An environment.** What a sandbox run does to its codebase's checkout before
+the agent starts: the install script, the start command, and the secrets it
+exports. New offers to set one up when the chosen codebase has none. Start the
+agent, and a run in mode `setup`, titled by the prompt's first line and working
+through its steps, explores, installs and checks the codebase. Its answer is kept
+as a proposal the Environment tab shows in its editors until an org admin saves
+it. Or an org admin skips and saves it empty, and writes the scripts beside the
+next run. Secret values are sealed in KMS and never shown again.
 
 **A project.** The v2 workspace in the same window: its runs as a
 conversation with suggestions and a Build/Plan composer on the left; Preview,
@@ -120,19 +185,46 @@ picker and open-in-tab; Share and Publish; the console dock under it.
 | `POST /v1/agent/coding` | start a run → 202 `{sessionId, …}` |
 | `GET /v1/agent/sessions?kind=coding` | Recents, and a project's runs |
 | `GET /v1/agent/sessions/{id}` · `GET /v1/agent/sessions/stream?root=` | a run, and its live feed (SSE over fetch) |
-| `POST /v1/agent/sessions/{id}/message` · `/stop` | steer, stop |
-| `GET /v1/agent/targets` | the org's machines |
+| `POST /v1/agent/sessions/{id}/message` · `/pause` · `/resume` · `/stop` | steer, pause, resume a machine's run, stop |
+| `PATCH /v1/agent/sessions/{id}` `{title}` · `{published}` | rename a run, share its story at `GET /v1/agent/builds/{org}/{project}` |
+| `GET /v1/agent/sessions?kind=coding&status=&after=` | Find, by status, paged |
+| `GET`/`POST /v1/agent/targets` · `PATCH`/`DELETE …/{id}` · `POST …/{id}/key` | the org's machines, and a machine's claim key |
+| `GET`/`POST`/`DELETE /v1/account/keys` | your API keys |
 | `GET /v1/auto/flows` · `POST /v1/auto/flows` · `POST /v1/auto/flows/{id}/enable` | automations |
+| `GET /v1/environment` · `GET`/`PUT`/`DELETE /v1/environment/{repo}` · `PUT`/`DELETE …/secrets/{name}` | a codebase's environment |
+| `GET /v1/agent/coding/{session}/changes` · `/tree` · `/blob` | what a run pushed, and its branch's files, from the forge |
+| `POST /v1/sandbox/{id}/screen/ticket` · `…/terminal/ticket` | the run's desktop and shell, framed with a single-use ticket |
+| `POST /v1/sandbox/read` | the run's working tree, live |
 | `GET /v1/provider/github/repos` · `POST /v1/provider/github/repos/import` | granted repositories, and bringing them onto the forge |
 | `GET /v1/git/repos` · `GET /v1/git/repos/{name}` | the codebase chip, and its branches |
 | `GET /v1/task/projects` · `GET /v1/task/board` · `GET /v1/task/projects/{key}/issues` | boards and issues, read from the forge |
 | `GET /v1/provider/github/repos` · `…/{owner}/{repo}/branches` | kept for a host that still asks GitHub |
 | `POST /v1/provider/github/user/connect` | connect a person's GitHub |
-| `GET /v1/projects` · `POST /v1/projects/fork` · `GET /v1/templates` | artifacts, templates |
+| `GET /v1/projects` · `PATCH`/`DELETE /v1/projects/{slug}` · `POST /v1/projects/fork` · `GET /v1/templates` | artifacts, templates |
 | `GET /v1/git/repos/{name}/tree` · `/blob` | Files and Code |
 | `POST /v1/platform/apps` · `GET /v1/platform/builds` | Add to project, Publish |
 | `POST /v1/mcp` | the native MCP servers, `tools/list` |
+| `GET /v1/tool?source=` · `GET`/`PUT /v1/tool/activation` | the org's tools, and which are on |
+| `GET /v1/tool/skills?activated=true` · `GET /v1/tool/skills/authored` · `POST /v1/tool/skills` · `DELETE /v1/tool/skills/{id}` | skills |
+| `GET /.well-known/agent-skills/index.json` · `…/{skill}/SKILL.md` | the brand's skills catalogue, public |
+| `GET`/`POST /v1/tool/mcp/servers` · `DELETE …/{id}` · `GET /v1/tool/catalog` · `…/{id}` | connectors, and the shelf |
+| `GET /v1/tool/plugins/authored` · `POST /v1/tool/plugins/build` · `DELETE …/authored/{id}` · `GET /v1/tool/plugins` | plugins, and what is mounted |
+| `GET`/`POST /v1/agent` · `GET`/`PATCH`/`DELETE /v1/agent/{ref}` · `GET /v1/agent/chat/presets` | agents, and presets |
 | `GET /v1/models` · `POST /v1/event` | the model list, a verdict |
+| `GET`/`PATCH /v1/pref` | the person's own settings: theme, text size, motion, dictation language, what to call them, their instructions, the coding defaults |
+| `PUT /v1/iam/account` · `POST /v1/account/avatar` | the person's name and photo |
+| `GET`/`PUT /v1/iam/consent` | whether Hanzo may train on their data, and usage insights |
+| `GET /v1/tool` · `PUT /v1/tool/activation` | what the agent may use, per kind of tool |
+| `GET /v1/ai/memory/list` · `POST /v1/ai/memory/remember` · `…/delete` | what Hanzo remembers |
+| `PATCH /v1/projects/{slug}` | a project public or private |
+| `GET /v1/billing/plans` · `…/subscriptions` · `POST …/subscribe/card` · `…/subscriptions/{id}/cancel`·`/reactivate` | Plans, and the plan in Billing |
+| `GET`/`POST`/`DELETE /v1/billing/methods` · `GET /v1/billing/settings` | saved cards; a card is added from the processor's own field |
+| `GET /v1/billing/invoices` · `…/invoices/{id}/pdf` | invoices |
+| `GET /v1/billing/balance` · `…/credit-balance` · `…/usage/rollup` · `POST …/topup` · `GET /v1/usage/summary` | Usage |
+| `GET`/`POST`/`PATCH`/`DELETE /v1/billing/alerts` | the monthly limit (org admin) |
+| `GET /v1/iam/memberships?org=` · `GET`/`POST`/`DELETE /v1/iam/invitations` | Members |
+| `GET /v1/provider/{slack,github}` · `POST …/connect`·`/disconnect` · `GET /v1/provider/slack/channels` · `GET /v1/provider/github/installations` | Integrations |
+| `GET`/`POST /v1/webhook` · `DELETE /v1/webhook/{id}` · `POST …/test` · `GET …/deliveries` | Notifications |
 
 `mode`, `model` and `effort` are sent with a run as asked; the platform
 honours them where it does and nothing here simulates them.
@@ -146,10 +238,21 @@ src/
   landing.tsx   New
   forge.tsx     Codebase, Automations, Projects, Issues
   run.tsx       one run
+  transcript.tsx  a run's transcript, as cards
+  prose.tsx     markdown, drawn as text (markdown.ts reads it)
+  desk.tsx      the pane beside a run
+  door.tsx      a run's desktop or shell, framed
+  git.tsx       what a run pushed
+  files.tsx     a run's files and artifacts
+  environment.tsx a codebase's environment
   project.tsx   a project's workspace
   shelf.tsx     Artifacts and Templates
+  customize/    Customize: the shell, then one file per tab
   publish.tsx   Add to project / Publish
-  account.tsx   the account and find-a-run dialogs
+  find.tsx      finding a run, by status, paged
+  foot.tsx      the rail's foot: the Slack card and the account menu
+  ask.tsx       confirming an act, or naming something, in a dialog
+  settings/     Settings, one file per section
   data.ts       reads as hooks
   host.tsx      what a host provides
   route.ts      the address grammar

package/lib/api/agents.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Agents: the org's own — a model, instructions, the tools it may call and a
+ * budget — and the presets one can start from.
+ *
+ *   GET    /v1/agent                 {agents: [agent]}, without instructions
+ *   POST   /v1/agent                 create → 201 agent
+ *   GET    /v1/agent/{ref}           one, with its instructions
+ *   PATCH  /v1/agent/{ref}           the fields sent change, the rest stay → agent
+ *   DELETE /v1/agent/{ref}           removes it and every run recorded against it → 204
+ *   GET    /v1/agent/chat/presets    {presets: [{id, title, systemPrompt, serverExecuted}]}
+ *
+ * A ref is the agent's id or its name. A budget is required: the most it may
+ * spend in a period and in one run, in micro-USD, and the period — day, week or
+ * month. Tools are names from the tool plane; none grants none, and `*` is
+ * whatever the fleet's MCP server serves when it runs. An omitted model is the
+ * deployment's default. A preset whose tool calls run on the platform
+ * (`serverExecuted`) makes a working agent; the others hand their calls back to
+ * the client that asked, so they are not offered here.
+ */
+import { type Target } from './call.ts';
+export type Period = 'day' | 'week' | 'month';
+export declare const PERIODS: readonly Period[];
+export interface Agent {
+    id: string;
+    name: string;
+    model: string;
+    description: string;
+    /** Only a single agent's read carries it; the list withholds it. */
+    instructions: string;
+    tools: string[];
+    status: string;
+    runs: number;
+    /** Micro-USD per period, per run, and spent this period. */
+    cap: number;
+    task: number;
+    spent: number;
+    period: Period | '';
+    emoji: string;
+}
+export interface Preset {
+    id: string;
+    title: string;
+    prompt: string;
+}
+/** The fields a person edits. Money is in dollars here and micro-USD on the wire. */
+export interface Draft {
+    name: string;
+    description: string;
+    model: string;
+    instructions: string;
+    tools: string[];
+    cap: string;
+    task: string;
+    period: Period;
+}
+/** An agent's name, as the handler takes it. */
+export declare const NAME: RegExp;
+/** The most instructions the handler keeps. */
+export declare const MAX: number;
+/** Every tool the fleet's MCP server serves. */
+export declare const ALL = "*";
+export declare const micros: (dollars: string) => number;
+export declare const dollars: (m: number) => string;
+export declare function agent(raw: unknown): Agent;
+/** A draft of an agent as it stands, to edit. */
+export declare function draft(a: Agent): Draft;
+export declare const EMPTY: Draft;
+/** Why a draft cannot be saved as it stands, or '' when it can. */
+export declare function refuse(d: Draft): string;
+export declare function agents(t: Target): Promise<Agent[]>;
+export declare function one(t: Target, ref: string): Promise<Agent>;
+export declare function create(t: Target, d: Draft): Promise<Agent>;
+/** The fields that differ from `was`, and nothing else: an omitted field keeps its value. */
+export declare function changes(was: Agent, d: Draft): Record<string, unknown>;
+export declare function update(t: Target, was: Agent, d: Draft): Promise<Agent>;
+export declare function remove(t: Target, ref: string): Promise<void>;
+/** The presets that make a working agent. */
+export declare function presets(t: Target): Promise<Preset[]>;
+/** A new agent's draft from a preset. */
+export declare function fromPreset(p: Preset): Draft;

package/lib/api/agents.js

@@ -0,0 +1,148 @@
+/**
+ * Agents: the org's own — a model, instructions, the tools it may call and a
+ * budget — and the presets one can start from.
+ *
+ *   GET    /v1/agent                 {agents: [agent]}, without instructions
+ *   POST   /v1/agent                 create → 201 agent
+ *   GET    /v1/agent/{ref}           one, with its instructions
+ *   PATCH  /v1/agent/{ref}           the fields sent change, the rest stay → agent
+ *   DELETE /v1/agent/{ref}           removes it and every run recorded against it → 204
+ *   GET    /v1/agent/chat/presets    {presets: [{id, title, systemPrompt, serverExecuted}]}
+ *
+ * A ref is the agent's id or its name. A budget is required: the most it may
+ * spend in a period and in one run, in micro-USD, and the period — day, week or
+ * month. Tools are names from the tool plane; none grants none, and `*` is
+ * whatever the fleet's MCP server serves when it runs. An omitted model is the
+ * deployment's default. A preset whose tool calls run on the platform
+ * (`serverExecuted`) makes a working agent; the others hand their calls back to
+ * the client that asked, so they are not offered here.
+ */
+import { call, seg } from './call.js';
+export const PERIODS = ['day', 'week', 'month'];
+/** An agent's name, as the handler takes it. */
+export const NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+/** The most instructions the handler keeps. */
+export const MAX = 32 << 10;
+/** Every tool the fleet's MCP server serves. */
+export const ALL = '*';
+const str = (v) => (typeof v === 'string' ? v : '');
+const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : 0);
+const obj = (v) => (v && typeof v === 'object' ? v : {});
+const rows = (v) => (Array.isArray(v) ? v : []);
+export const micros = (dollars) => Math.round(Number(dollars) * 1_000_000);
+export const dollars = (m) => (m ? String(m / 1_000_000) : '');
+export function agent(raw) {
+    const o = obj(raw);
+    const period = str(o.period);
+    return {
+        id: str(o.id),
+        name: str(o.name),
+        model: str(o.model),
+        description: str(o.description),
+        instructions: str(o.instructions),
+        tools: rows(o.tools).map(str).filter(Boolean),
+        status: str(o.status),
+        runs: num(o.runs),
+        cap: num(o.cap_micro_usd),
+        task: num(o.max_task_micro_usd),
+        spent: num(o.consumed_micro_usd),
+        period: PERIODS.includes(period) ? period : '',
+        emoji: str(o.emoji),
+    };
+}
+/** A draft of an agent as it stands, to edit. */
+export function draft(a) {
+    return {
+        name: a.name,
+        description: a.description,
+        model: a.model,
+        instructions: a.instructions,
+        tools: a.tools,
+        cap: dollars(a.cap),
+        task: dollars(a.task),
+        period: a.period || 'month',
+    };
+}
+export const EMPTY = { name: '', description: '', model: '', instructions: '', tools: [], cap: '', task: '', period: 'month' };
+/** Why a draft cannot be saved as it stands, or '' when it can. */
+export function refuse(d) {
+    if (!NAME.test(d.name))
+        return 'A name is letters, digits, . _ or -, starting with a letter or digit';
+    if (new TextEncoder().encode(d.instructions).length > MAX)
+        return 'Instructions are at most 32 KB';
+    const cap = micros(d.cap);
+    const task = micros(d.task);
+    if (!(cap > 0))
+        return 'Set what it may spend each ' + d.period;
+    if (!(task > 0))
+        return 'Set what one run may spend';
+    if (task > cap)
+        return 'One run cannot spend more than the whole ' + d.period;
+    return '';
+}
+export async function agents(t) {
+    return rows(obj(await call(t, 'GET', '/v1/agent')).agents).map(agent).filter((a) => a.name);
+}
+export async function one(t, ref) {
+    return agent(await call(t, 'GET', `/v1/agent/${seg(ref)}`));
+}
+export async function create(t, d) {
+    const why = refuse(d);
+    if (why)
+        throw new Error(why);
+    const body = {
+        name: d.name.trim(),
+        description: d.description.trim(),
+        instructions: d.instructions,
+        tools: d.tools,
+        cap_micro_usd: micros(d.cap),
+        max_task_micro_usd: micros(d.task),
+        period: d.period,
+    };
+    if (d.model)
+        body.model = d.model;
+    return agent(await call(t, 'POST', '/v1/agent', body));
+}
+/** The fields that differ from `was`, and nothing else: an omitted field keeps its value. */
+export function changes(was, d) {
+    const out = {};
+    if (d.model && d.model !== was.model)
+        out.model = d.model;
+    if (d.description.trim() !== was.description)
+        out.description = d.description.trim();
+    if (d.instructions !== was.instructions)
+        out.instructions = d.instructions;
+    if (d.tools.join('\n') !== was.tools.join('\n'))
+        out.tools = d.tools;
+    if (micros(d.cap) !== was.cap)
+        out.cap_micro_usd = micros(d.cap);
+    if (micros(d.task) !== was.task)
+        out.max_task_micro_usd = micros(d.task);
+    if (d.period !== was.period)
+        out.period = d.period;
+    return out;
+}
+export async function update(t, was, d) {
+    const why = refuse({ ...d, name: was.name });
+    if (why)
+        throw new Error(why);
+    const body = changes(was, d);
+    if (!Object.keys(body).length)
+        return was;
+    return agent(await call(t, 'PATCH', `/v1/agent/${seg(was.id || was.name)}`, body));
+}
+export async function remove(t, ref) {
+    await call(t, 'DELETE', `/v1/agent/${seg(ref)}`);
+}
+/** The presets that make a working agent. */
+export async function presets(t) {
+    return rows(obj(await call(t, 'GET', '/v1/agent/chat/presets')).presets)
+        .map(obj)
+        .filter((p) => p.serverExecuted === true)
+        .map((p) => ({ id: str(p.id), title: str(p.title), prompt: str(p.systemPrompt) }))
+        .filter((p) => p.id);
+}
+/** A new agent's draft from a preset. */
+export function fromPreset(p) {
+    return { ...EMPTY, name: p.id, description: p.title, instructions: p.prompt };
+}

package/lib/api/billing.d.ts

@@ -0,0 +1,205 @@
+/**
+ * The organization's money: its plan, the cards it pays with, its invoices, its
+ * balance and credits, what it has spent this month, and the caps on that spend.
+ *
+ *   GET    /v1/billing/plans                     the catalog the serving brand sells (public)
+ *   GET    /v1/billing/subscriptions             {count, subscriptions}
+ *   POST   /v1/billing/subscribe/card            buy a plan with a saved card; one paid plan at a time (409)
+ *   POST   /v1/billing/subscriptions/{id}/cancel     at the end of the paid period
+ *   POST   /v1/billing/subscriptions/{id}/reactivate
+ *   GET    /v1/billing/methods                   saved cards, newest first
+ *   POST   /v1/billing/methods                   save a card from the processor's single-use token
+ *   DELETE /v1/billing/methods/{id}
+ *   GET    /v1/billing/settings                  the processor a browser tokenizes a card against
+ *   GET    /v1/billing/invoices                  {count, cursor, invoices}
+ *   GET    /v1/billing/invoices/{id}/pdf         the invoice as a PDF
+ *   GET    /v1/billing/balance                   prepaid balance, whole cents
+ *   GET    /v1/billing/credit-balance            granted credit, per currency
+ *   POST   /v1/billing/topup                     charge a saved card into the balance
+ *   GET    /v1/billing/usage/rollup              the plan's month: included spend and request windows
+ *   GET    /v1/usage/summary?range=month         this month's spend, by category
+ *   GET    /v1/billing/alerts                    spend caps (bare array)
+ *   POST   /v1/billing/alerts                    open a cap (org admin)
+ *   PATCH  /v1/billing/alerts/{id}               change one (org admin)
+ *   DELETE /v1/billing/alerts/{id}               lift one (org admin)
+ *
+ * Every figure is whole cents. The wallet, the caps and the cards are the
+ * caller's own, resolved by the platform from the credential; nothing here names
+ * an org or a subject. No card number passes through this file: a card is saved
+ * from the token the processor's own form returns.
+ */
+import { type Target } from './call.ts';
+/** `$1,234.56` from whole cents; whole dollars drop the cents. */
+export declare function money(cents: number, currency?: string): string;
+/** Whole cents from what a person typed as dollars — `25`, `$25.50` — or null. */
+export declare function cents(typed: string): number | null;
+export interface Plan {
+    id: string;
+    name: string;
+    description: string;
+    /** personal, team, enterprise, … */
+    category: string;
+    /** Per month, billed monthly. 0 is free. */
+    monthly: number;
+    /** Per month, billed yearly; 0 when the plan has no yearly price. */
+    yearly: number;
+    currency: string;
+    perSeat: boolean;
+    /** Priced by talking to sales; nothing to buy here. */
+    sales: boolean;
+    popular: boolean;
+    features: string[];
+}
+export declare function plan(raw: unknown): Plan;
+export declare function plans(t: Target): Promise<Plan[]>;
+export interface Subscription {
+    id: string;
+    plan: string;
+    name: string;
+    /** Per period, per seat. */
+    price: number;
+    interval: string;
+    currency: string;
+    seats: number;
+    /** trialing, active, past_due, canceled, unpaid. */
+    status: string;
+    /** RFC 3339: paid through, and renews or ends then. */
+    ends: string;
+    /** Ends at `ends` rather than renewing. */
+    ending: boolean;
+    /** The saved card a renewal charges, or ''. */
+    method: string;
+}
+export declare function subscription(raw: unknown): Subscription;
+/** The plan the org is on, or null for none (the free tier). */
+export declare function current(list: Subscription[]): Subscription | null;
+export declare function subscriptions(t: Target): Promise<Subscription[]>;
+export interface Purchase {
+    plan: string;
+    /** month | year */
+    interval: 'month' | 'year';
+    /** The saved card that pays. */
+    method: string;
+}
+/** Buy a plan. No amount is sent: the catalog prices it, and the platform charges that. */
+export declare function subscribe(t: Target, p: Purchase): Promise<{
+    subscription: string;
+    charged: number;
+}>;
+/** End a plan when its paid period does, not before. */
+export declare function cancel(t: Target, id: string): Promise<Subscription>;
+export declare function reactivate(t: Target, id: string): Promise<Subscription>;
+export interface Method {
+    id: string;
+    type: string;
+    brand: string;
+    last4: string;
+    /** `MM/YY`, or ''. */
+    expires: string;
+    default: boolean;
+    /** What the platform calls it when it is not a card. */
+    name: string;
+}
+export declare function method(raw: unknown): Method;
+/** How a saved method reads in a row: `Visa •••• 4242`. */
+export declare function label(m: Method): string;
+export declare function methods(t: Target): Promise<Method[]>;
+/** The card a charge uses: the default, or the newest. */
+export declare function chosen(list: Method[]): Method | null;
+/** Save a card from the single-use token the processor's form returned. */
+export declare function save(t: Target, token: string): Promise<Method>;
+export declare function detach(t: Target, id: string): Promise<void>;
+export interface Processor {
+    /** `square`, or '' where none is configured. */
+    provider: string;
+    application: string;
+    location: string;
+    /** `production` charges real cards; anything else is the sandbox. */
+    environment: string;
+    live: boolean;
+}
+export declare function processor(t: Target): Promise<Processor>;
+export interface Line {
+    description: string;
+    amount: number;
+}
+export interface Invoice {
+    id: string;
+    /** `INV-0042`, or '' for a draft. */
+    number: string;
+    date: string;
+    status: string;
+    currency: string;
+    subtotal: number;
+    tax: number;
+    discount: number;
+    credit: number;
+    paid: number;
+    due: number;
+    /** What the invoice comes to before credit is applied. */
+    total: number;
+    start: string;
+    end: string;
+    lines: Line[];
+}
+export declare function invoice(raw: unknown): Invoice;
+export declare function invoices(t: Target): Promise<Invoice[]>;
+/** The invoice as a PDF, read with the caller's bearer. */
+export declare function pdf(t: Target, id: string): Promise<Blob>;
+/** What the org can still spend from its prepaid balance, in cents. */
+export declare function balance(t: Target): Promise<number>;
+/** Granted credit the org can spend, in US cents. */
+export declare function credit(t: Target): Promise<number>;
+/** Charge a saved card and add the amount to the balance; answers the balance after. */
+export declare function topup(t: Target, amount: number, card: string): Promise<number>;
+export interface Window {
+    /** hour, day, week or month. */
+    span: string;
+    /** Requests the plan includes in this span; 0 is no bound. */
+    limit: number;
+    used: number;
+    /** RFC 3339. */
+    resets: string;
+}
+export interface Month {
+    plan: string;
+    /** `2026-09`. */
+    period: string;
+    /** Spend the plan includes this month, and how much of it is used. */
+    included: number;
+    used: number;
+    overage: number;
+    windows: Window[];
+}
+export declare function month(t: Target): Promise<Month>;
+export interface Spend {
+    /** Whether the ledger answered; false means the zeros are not measurements. */
+    known: boolean;
+    /** Month to date. */
+    total: number;
+    categories: {
+        name: string;
+        cents: number;
+    }[];
+}
+export declare function spend(t: Target): Promise<Spend>;
+export interface Cap {
+    id: string;
+    title: string;
+    /** The ceiling for the calendar month, in cents; 0 bounds no spend. */
+    threshold: number;
+    /** Refuses spend past the ceiling, rather than only warning. */
+    enforce: boolean;
+    project: string;
+    service: string;
+    /** Spent this month against it, or null when the platform could not read it. */
+    spent: number | null;
+    resets: string;
+}
+export declare function cap(raw: unknown): Cap;
+export declare function caps(t: Target): Promise<Cap[]>;
+/** The org-wide monthly cap: no project, no service, a ceiling. */
+export declare function monthly(list: Cap[]): Cap | null;
+/** Set the org's monthly cap: change the one there is, or open one that refuses spend past it. */
+export declare function limit(t: Target, list: Cap[], threshold: number): Promise<Cap>;
+export declare function lift(t: Target, id: string): Promise<void>;