@hanzo/build 0.2.79 → 0.2.81

package/README.md

@@ -100,6 +100,19 @@ nothing behind a More; `useSessions(host)` is the runs — the org's coding runs
 kept live by the org's feed — for a host that draws the rows itself. `administers(token, org)` reads the org-admin bit off a
 hanzo.id token for `Host.admin`. One left column, never two.
 
+## Words
+
+Every word the builder authors is said through @hanzo/i18n, a required peer
+(`>=0.4.0`): the host's `I18nProvider` is the one asked, and without one the
+builder reads in English, unchanged. A component asks `useI18n()`; copy held as
+data is `phrase()` where it is written and drawn through `t`; a helper outside a
+render (`nav()`, `own()`, `tabs()`, `library()`, turn.ts, the plan sentences)
+takes the caller's `t` last and falls back to `say.ts`'s `english`. Names, model
+ids, what a person typed, what the platform said and figures are drawn as given;
+prompts sent to a model stay in English. `src/e2e/language*.spec.ts` and
+`translated.spec.ts` hold the composer, Projects, Skills and the Library in
+French and right to left in Arabic.
+
 ## The model, the composer, the panel
 
 One of each, shared with Chat (@hanzo/rooms imports them):
@@ -226,10 +239,15 @@ are any member's.
 - Plugins: TypeScript connectors built on the platform, from source or from a
   description of an API; a failed build says why. Browse offers building one and
   lists what the deployment mounts.
-- Agents: Browse is the platform's presets whose tool calls run on the platform,
-  each a Use that opens a new agent written from it; Yours is the org's own —
-  model, instructions, tools, budget — created, edited (only what changed is
-  sent) and deleted.
+- Agents: Browse is every agent to start from — the host's default agents
+  (`cast`) and personas (`personas`), and the platform's presets whose tool
+  calls run on the platform — searched by name and filtered by category. Use
+  makes one agent of the org's own from one template (a name taken becomes
+  `-2`, `-3`), with its face, model and instructions, and opens its profile;
+  nothing is added in bulk. Start from scratch, Clone yourself (the person
+  signed in, with writing pasted or uploaded) and Create from a person make one
+  too. Yours is the org's own — model, instructions, tools, budget — created,
+  edited (only what changed is sent) and deleted.
 
 **New.** "What's up next?", and at the foot the composer: where the run runs
 (Cloud is the platform's sandbox with the codebase's environment; the org's

package/lib/activity.d.ts

@@ -1,8 +1,4 @@
-/**
- * Activity's words: what a run's state is called and drawn as, how long it
- * took, what it cost, and the one line under its title. Pure, so the screen and
- * its tests read the same sentences.
- */
+import type { Say } from '@hanzo/i18n/react';
 import type { SessionStatus } from '@hanzo/ui/chat';
 import type { Job, State } from './api/auto.ts';
 /** A job's state as the rail's dot draws it, and in words. */
@@ -12,8 +8,8 @@ export declare const SAID: Record<State, string>;
 export declare function lasted(started: string, finished: string | null, now?: number): string;
 /** Cents as dollars. */
 export declare const dollars: (cents: number) => string;
-/** One line about a job: when it started, how long, what it cost, what it made. */
-export declare function about(j: Job, now?: number): string;
+/** One line about a job: when it started, how long, what it cost, what it made. Its words in the language of `t`. */
+export declare function about(j: Job, now?: number, t?: Say): string;
 /** The jobs, newest first, with `j` in its place. */
 export declare function merged(list: Job[], j: Job): Job[];
 /** A task's name from what it does: its first line, short. */

package/lib/activity.js

@@ -1,8 +1,21 @@
+/**
+ * Activity's words: what a run's state is called and drawn as, how long it
+ * took, what it cost, and the one line under its title. Pure, so the screen and
+ * its tests read the same sentences.
+ */
+import { phrase } from '@hanzo/i18n';
 import { ago } from './ago.js';
 import { SOURCE } from './api/library.js';
+import { english } from './say.js';
 /** A job's state as the rail's dot draws it, and in words. */
 export const DOTS = { scheduled: 'idle', running: 'running', succeeded: 'done', failed: 'error', cancelled: 'stopped' };
-export const SAID = { scheduled: 'Scheduled', running: 'Running', succeeded: 'Succeeded', failed: 'Failed', cancelled: 'Cancelled' };
+export const SAID = {
+    scheduled: phrase('Scheduled'),
+    running: phrase('Running'),
+    succeeded: phrase('Succeeded'),
+    failed: phrase('Failed'),
+    cancelled: phrase('Cancelled'),
+};
 /** How long a run took, or has taken so far. */
 export function lasted(started, finished, now = Date.now()) {
     const a = Date.parse(started);
@@ -20,10 +33,10 @@ export function lasted(started, finished, now = Date.now()) {
 }
 /** Cents as dollars. */
 export const dollars = (cents) => `$${(cents / 100).toFixed(2)}`;
-/** One line about a job: when it started, how long, what it cost, what it made. */
-export function about(j, now = Date.now()) {
-    const made = j.outputs.length ? `${j.outputs.length} ${j.outputs.length === 1 ? 'output' : 'outputs'}` : '';
-    return [SOURCE[j.product], j.started ? ago(j.started) : '', lasted(j.started, j.finished, now), j.cost !== null ? dollars(j.cost) : '', made].filter(Boolean).join(' · ');
+/** One line about a job: when it started, how long, what it cost, what it made. Its words in the language of `t`. */
+export function about(j, now = Date.now(), t = english) {
+    const made = j.outputs.length ? (j.outputs.length === 1 ? t('{n} output', { n: 1 }) : t('{n} outputs', { n: j.outputs.length })) : '';
+    return [SOURCE[j.product] ? t(SOURCE[j.product]) : '', j.started ? ago(j.started) : '', lasted(j.started, j.finished, now), j.cost !== null ? dollars(j.cost) : '', made].filter(Boolean).join(' · ');
 }
 /** The jobs, newest first, with `j` in its place. */
 export function merged(list, j) {

package/lib/api/agents.d.ts

@@ -1,22 +1,3 @@
-/**
- * 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[];
@@ -35,6 +16,8 @@ export interface Agent {
     task: number;
     spent: number;
     period: Period | '';
+    /** Its picture: an https link or a data URL; '' draws its emoji or initial. */
+    avatar: string;
     emoji: string;
 }
 export interface Preset {
@@ -52,6 +35,8 @@ export interface Draft {
     cap: string;
     task: string;
     period: Period;
+    /** Sent on create only: an https link or a data URL. */
+    avatar: string;
 }
 /** An agent's name, as the handler takes it. */
 export declare const NAME: RegExp;
@@ -65,7 +50,7 @@ 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. */
+/** Why a draft cannot be saved as it stands, or '' when it can: English, marked (`phrase`), so a screen says it through `t`. */
 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>;
@@ -86,29 +71,45 @@ export declare function profile(t: Target, ref: string): Promise<{
     agent: Agent;
     runs: Run[];
 }>;
-/** A default agent a host offers: a name, its line, its model and its instructions. */
+/** An agent to start from: a default agent, a persona or a preset. */
 export interface Cast {
+    /** The name it is made under. */
     name: string;
+    /** What Browse calls it. */
+    title: string;
     description: string;
+    /** What Browse lists it under. */
+    category: string;
     model: string;
     instructions: string;
-    /** Its face, an address of the host, when it has one. */
+    /** Reads the instructions, where they are a file the host serves. */
+    read?: () => Promise<string>;
+    /** Its face, an address of the host. */
     avatar?: string;
+    tools?: string[];
 }
-/** What a default agent may spend until its owner says otherwise, in dollars: each month, and one run. */
+/** What an agent made from a template may spend until its owner says otherwise, in dollars: each month, and one run. */
 export declare const CAST_CAP = "10";
 export declare const CAST_TASK = "1";
-/** The cast members the org has no agent for, by name in any case. */
-export declare const missing: (cast: readonly Cast[], have: readonly {
-    name: string;
-}[]) => Cast[];
-/** Create every cast member the org lacks, one at a time; the names made, and the first refusal, if any. */
-export declare function hire(t: Target, cast: readonly Cast[], have: readonly {
+/**
+ * A name the API takes: accents dropped, any other run of characters a dash,
+ * from a letter or digit, up to 64. "Spärck Jones" is Sparck-Jones.
+ */
+export declare const handle: (name: string) => string;
+/** `name`, or `name-2`, `name-3`… : the first the org has no agent called, in any case. */
+export declare function free(name: string, have: readonly {
     name: string;
-}[]): Promise<{
-    made: string[];
-    error: unknown;
-}>;
+}[]): string;
+/** An address of the page as an https link the API keeps, or '' (a page served over http has none). */
+export declare const link: (at: string | undefined, base: string) => string;
+/**
+ * Make the org's own agent from a template: under the first name the org has
+ * free (read now, so it is never one that exists), with its instructions read
+ * and its face linked. The template is not touched.
+ */
+export declare function use(t: Target, c: Cast, base: string): Promise<Agent>;
+/** Anyone as a template: their name, who they are, and writing of theirs to take the voice from. */
+export declare function person(name: string, about: string, writing: string, avatar?: string): Cast;
 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>;
@@ -116,5 +117,5 @@ 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;
+/** A preset as a template. */
+export declare function fromPreset(p: Preset): Cast;

package/lib/api/agents.js

@@ -1,6 +1,6 @@
 /**
- * Agents: the org's own — a model, instructions, the tools it may call and a
- * budget — and the presets one can start from.
+ * Agents: the org's own — a model, instructions, the tools it may call, a
+ * budget and a face — and the templates one is made from.
  *
  *   GET    /v1/agent                 {agents: [agent]}, without instructions
  *   POST   /v1/agent                 create → 201 agent
@@ -17,6 +17,7 @@
  * (`serverExecuted`) makes a working agent; the others hand their calls back to
  * the client that asked, so they are not offered here.
  */
+import { phrase } from '@hanzo/i18n';
 import { call, seg } from './call.js';
 export const PERIODS = ['day', 'week', 'month'];
 /** An agent's name, as the handler takes it. */
@@ -47,6 +48,7 @@ export function agent(raw) {
         task: num(o.max_task_micro_usd),
         spent: num(o.consumed_micro_usd),
         period: PERIODS.includes(period) ? period : '',
+        avatar: str(o.avatar),
         emoji: str(o.emoji),
     };
 }
@@ -61,23 +63,31 @@ export function draft(a) {
         cap: dollars(a.cap),
         task: dollars(a.task),
         period: a.period || 'month',
+        avatar: a.avatar,
     };
 }
-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 const EMPTY = { name: '', description: '', model: '', instructions: '', tools: [], cap: '', task: '', period: 'month', avatar: '' };
+/** What a budget left unset says, and one run that outspends its period, by the period: whole sentences, so a language says the period its own way. */
+const UNSET = { day: phrase('Set what it may spend each day'), week: phrase('Set what it may spend each week'), month: phrase('Set what it may spend each month') };
+const OVER = {
+    day: phrase('One run cannot spend more than the whole day'),
+    week: phrase('One run cannot spend more than the whole week'),
+    month: phrase('One run cannot spend more than the whole month'),
+};
+/** Why a draft cannot be saved as it stands, or '' when it can: English, marked (`phrase`), so a screen says it through `t`. */
 export function refuse(d) {
     if (!NAME.test(d.name))
-        return 'A name is letters, digits, . _ or -, starting with a letter or digit';
+        return phrase('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';
+        return phrase('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;
+        return UNSET[d.period];
     if (!(task > 0))
-        return 'Set what one run may spend';
+        return phrase('Set what one run may spend');
     if (task > cap)
-        return 'One run cannot spend more than the whole ' + d.period;
+        return OVER[d.period];
     return '';
 }
 export async function agents(t) {
@@ -95,27 +105,52 @@ export async function profile(t, ref) {
     const raw = await call(t, 'GET', `/v1/agent/${seg(ref)}`);
     return { agent: agent(raw), runs: rows(obj(raw).recentRuns).map(run).filter((r) => r.id) };
 }
-/** What a default agent may spend until its owner says otherwise, in dollars: each month, and one run. */
+/** What an agent made from a template may spend until its owner says otherwise, in dollars: each month, and one run. */
 export const CAST_CAP = '10';
 export const CAST_TASK = '1';
-/** The cast members the org has no agent for, by name in any case. */
-export const missing = (cast, have) => {
-    const names = new Set(have.map((a) => a.name.toLowerCase()));
-    return cast.filter((c) => !names.has(c.name.toLowerCase()));
-};
-/** Create every cast member the org lacks, one at a time; the names made, and the first refusal, if any. */
-export async function hire(t, cast, have) {
-    const made = [];
-    for (const c of missing(cast, have)) {
-        try {
-            await create(t, { ...EMPTY, name: c.name, description: c.description, model: c.model, instructions: c.instructions, cap: CAST_CAP, task: CAST_TASK, period: 'month' });
-            made.push(c.name);
-        }
-        catch (error) {
-            return { made, error };
-        }
+/**
+ * A name the API takes: accents dropped, any other run of characters a dash,
+ * from a letter or digit, up to 64. "Spärck Jones" is Sparck-Jones.
+ */
+export const handle = (name) => name
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .replace(/[^A-Za-z0-9._-]+/g, '-')
+    .replace(/^[^A-Za-z0-9]+/, '')
+    .slice(0, 64)
+    .replace(/-+$/, '');
+/** `name`, or `name-2`, `name-3`… : the first the org has no agent called, in any case. */
+export function free(name, have) {
+    const taken = new Set(have.map((a) => a.name.toLowerCase()));
+    if (!taken.has(name.toLowerCase()))
+        return name;
+    for (let i = 2;; i++) {
+        const next = `${name.slice(0, 63 - String(i).length)}-${i}`;
+        if (!taken.has(next.toLowerCase()))
+            return next;
     }
-    return { made, error: null };
+}
+/** An address of the page as an https link the API keeps, or '' (a page served over http has none). */
+export const link = (at, base) => {
+    if (!at)
+        return '';
+    const url = new URL(at, base).href;
+    return url.startsWith('https://') || url.startsWith('data:') ? url : '';
+};
+/**
+ * Make the org's own agent from a template: under the first name the org has
+ * free (read now, so it is never one that exists), with its instructions read
+ * and its face linked. The template is not touched.
+ */
+export async function use(t, c, base) {
+    const [have, instructions] = await Promise.all([agents(t), c.read ? c.read() : c.instructions]);
+    return create(t, { ...EMPTY, name: free(handle(c.name), have), description: c.description, model: c.model, instructions, tools: c.tools ?? [], cap: CAST_CAP, task: CAST_TASK, avatar: link(c.avatar, base) });
+}
+/** Anyone as a template: their name, who they are, and writing of theirs to take the voice from. */
+export function person(name, about, writing, avatar = '') {
+    const who = name.trim();
+    const lines = [`You are ${who}.`, about.trim(), writing.trim() && `Writing by ${who}:\n\n${writing.trim()}`];
+    return { name: who, title: who, description: about.trim(), category: phrase('Person'), model: '', instructions: lines.filter(Boolean).join('\n\n'), avatar };
 }
 export async function create(t, d) {
     const why = refuse(d);
@@ -132,6 +167,8 @@ export async function create(t, d) {
     };
     if (d.model)
         body.model = d.model;
+    if (d.avatar)
+        body.avatar = d.avatar;
     return agent(await call(t, 'POST', '/v1/agent', body));
 }
 /** The fields that differ from `was`, and nothing else: an omitted field keeps its value. */
@@ -173,7 +210,7 @@ export async function presets(t) {
         .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. */
+/** A preset as a template. */
 export function fromPreset(p) {
-    return { ...EMPTY, name: p.id, description: p.title, instructions: p.prompt };
+    return { name: p.id, title: p.title || p.id, description: p.title, category: phrase('Preset'), model: '', instructions: p.prompt };
 }

package/lib/api/auto.d.ts

@@ -1,24 +1,4 @@
-/**
- * Automations: a task that runs itself, on a schedule or when asked.
- *
- *   GET    /v1/auto/automations            {data: [automation]}
- *   POST   /v1/auto/automations            create one: name and instructions
- *   GET    /v1/auto/automations/{id}       one
- *   PATCH  /v1/auto/automations/{id}       change it, or switch it on or off
- *   DELETE /v1/auto/automations/{id}       delete it, its schedule and its runs
- *   POST   /v1/auto/automations/{id}/run   {run: {id, status}}  one run, now
- *   GET    /v1/auto/automations/{id}/runs  {data: [run]}        newest first
- *   POST   /v1/auto/automations/{id}/runs/{run}/review  {post}  post a held post, or discard it
- *   GET    /v1/auto/templates              {data: [starter]}    to start a new one from
- *   POST   /v1/auto/cron                   {schedule, says, next}  a schedule from a person's words
- *   GET    /v1/auto/jobs                   {data: [job]}        what runs without you, across products
- *   GET    /v1/auto/jobs/{id}              one job
- *   GET    /v1/auto/events                 text/event-stream: `job` and `automation`, the reader's own
- *
- * Each run is one Dev run in this organization, started as the person who last
- * saved what it does. A draft is a flow named and not yet told what to do: it
- * runs once its instructions are saved.
- */
+import type { Say } from '@hanzo/i18n/react';
 import { type Target } from './call.ts';
 import { type Source } from './library.ts';
 export type { Source };
@@ -107,8 +87,8 @@ export declare function start(t: Target, id: string): Promise<{
 export declare function runs(t: Target, id: string): Promise<Run[]>;
 /** Post a held post to the automation's accounts, or discard it. */
 export declare function review(t: Target, id: string, runId: string, post: boolean): Promise<Run>;
-/** A schedule the way a person says it. */
-export declare function words(s: Schedule): string;
+/** A schedule the way a person says it, in the words of the `t` handed (English without one). */
+export declare function words(s: Schedule, t?: Say): string;
 /** A ready-made automation to start a new one from. Its schedule names no zone: the page fills in the person's. */
 export interface Starter {
     key: string;

package/lib/api/auto.js

@@ -19,6 +19,8 @@
  * saved what it does. A draft is a flow named and not yet told what to do: it
  * runs once its instructions are saved.
  */
+import { phrase } from '@hanzo/i18n';
+import { english } from '../say.js';
 import { call, headers, query, reason, Refusal, seg } from './call.js';
 import { inApp } from './library.js';
 import { read as stream } from './sse.js';
@@ -78,13 +80,13 @@ export async function automations(t) {
 export async function automation(t, id) {
     const a = read(await call(t, 'GET', `/v1/auto/automations/${seg(id)}`));
     if (!a)
-        throw new Error('The automation came back without an id');
+        throw new Error(phrase('The automation came back without an id'));
     return a;
 }
 export async function create(t, d) {
     const a = read(await call(t, 'POST', '/v1/auto/automations', d));
     if (!a)
-        throw new Error('The automation was created and came back without an id');
+        throw new Error(phrase('The automation was created and came back without an id'));
     return a;
 }
 /** What changed between two drafts, field by field: what a save sends. */
@@ -100,7 +102,7 @@ export function changes(was, now) {
 export async function save(t, id, change) {
     const a = read(await call(t, 'PATCH', `/v1/auto/automations/${seg(id)}`, change));
     if (!a)
-        throw new Error('The automation was saved and came back without an id');
+        throw new Error(phrase('The automation was saved and came back without an id'));
     return a;
 }
 export async function remove(t, id) {
@@ -130,40 +132,55 @@ function run(o) {
 export async function review(t, id, runId, post) {
     return run(obj(await call(t, 'POST', `/v1/auto/automations/${seg(id)}/runs/${seg(runId)}/review`, { post })));
 }
-const DAYS = { mon: 'Mondays', tue: 'Tuesdays', wed: 'Wednesdays', thu: 'Thursdays', fri: 'Fridays', sat: 'Saturdays', sun: 'Sundays' };
-/** A once schedule's local date and time, as a person reads it. */
+/** A weekly schedule's sentence by its day: one sentence each, so a language says the day its own way. */
+const DAYS = {
+    mon: phrase('Mondays at {time} · {zone}'),
+    tue: phrase('Tuesdays at {time} · {zone}'),
+    wed: phrase('Wednesdays at {time} · {zone}'),
+    thu: phrase('Thursdays at {time} · {zone}'),
+    fri: phrase('Fridays at {time} · {zone}'),
+    sat: phrase('Saturdays at {time} · {zone}'),
+    sun: phrase('Sundays at {time} · {zone}'),
+};
+/** A once schedule's local date, as a person reads it, and its time. */
 function once(at) {
     const m = at.match(/^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})$/);
     if (!m)
-        return at;
+        return null;
     const d = new Date(Number(m[1]), Number(m[2]) - 1, Number(m[3]), Number(m[4]), Number(m[5]));
-    return `${d.toLocaleDateString(undefined, { weekday: 'short', month: 'short', day: 'numeric' })} at ${m[4]}:${m[5]}`;
+    return { date: d.toLocaleDateString(undefined, { weekday: 'short', month: 'short', day: 'numeric' }), time: `${m[4]}:${m[5]}` };
 }
-/** A schedule the way a person says it. */
-export function words(s) {
-    const zone = ` · ${s.tz || 'UTC'}`;
+/** A schedule the way a person says it, in the words of the `t` handed (English without one). */
+export function words(s, t = english) {
+    const zone = s.tz || 'UTC';
     switch (s.kind) {
         case 'manual':
-            return 'When you run it';
-        case 'once':
-            return s.at ? `Once, ${once(s.at)}${zone}` : 'Once, now';
+            return t('When you run it');
+        case 'once': {
+            if (!s.at)
+                return t('Once, now');
+            const when = once(s.at);
+            return when ? t('Once, {date} at {time} · {zone}', { ...when, zone }) : t('Once, {at} · {zone}', { at: s.at, zone });
+        }
         case 'hourly':
-            return `Every hour at :${(s.at ?? '00:00').slice(3) || '00'}`;
+            return t('Every hour at :{minute}', { minute: (s.at ?? '00:00').slice(3) || '00' });
         case 'daily':
-            return `Every day at ${s.at}${zone}`;
+            return t('Every day at {time} · {zone}', { time: s.at ?? '', zone });
         case 'weekdays':
-            return `Weekdays at ${s.at}${zone}`;
-        case 'weekly':
-            return `${DAYS[s.day ?? ''] ?? s.day} at ${s.at}${zone}`;
+            return t('Weekdays at {time} · {zone}', { time: s.at ?? '', zone });
+        case 'weekly': {
+            const day = DAYS[s.day ?? ''];
+            return day ? t(day, { time: s.at ?? '', zone }) : t('{day} at {time} · {zone}', { day: s.day ?? '', time: s.at ?? '', zone });
+        }
         case 'cron': {
             // The two a person says most, in their words; any other expression as written.
             const minutes = (s.cron ?? '').match(/^\*\/(\d+) \* \* \* \*$/);
             if (minutes)
-                return `Every ${minutes[1]} minutes${zone}`;
+                return t('Every {n} minutes · {zone}', { n: minutes[1], zone });
             const hours = (s.cron ?? '').match(/^0 \*\/(\d+) \* \* \*$/);
             if (hours)
-                return `Every ${hours[1]} hours${zone}`;
-            return `Cron ${s.cron}${zone}`;
+                return t('Every {n} hours · {zone}', { n: hours[1], zone });
+            return t('Cron {cron} · {zone}', { cron: s.cron ?? '', zone });
         }
     }
 }
@@ -241,7 +258,7 @@ export async function jobs(t, f = {}) {
 export async function one(t, id) {
     const j = job(await call(t, 'GET', `/v1/auto/jobs/${seg(id)}`));
     if (!j)
-        throw new Error('The job came back without an id');
+        throw new Error(phrase('The job came back without an id'));
     return j;
 }
 /** One frame of /v1/auto/events, or null for one this page does not read. */

package/lib/api/billing.d.ts

@@ -1,38 +1,3 @@
-/**
- * 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
- *   GET    /v1/billing/credits                   {grants}: every grant, spent and lapsed included
- *   GET    /v1/billing/tier                      the rung served and its tier class
- *   GET    /v1/billing/recharge                  the auto-reload rule
- *   PUT    /v1/billing/recharge                  arm it (a card on file) or disarm it
- *   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/allowance                         the Free plan's allowance, and the pool it is served from
- *   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;

package/lib/api/billing.js

@@ -33,6 +33,7 @@
  * 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 { phrase } from '@hanzo/i18n';
 import { call, headers, reason, Refusal, seg } from './call.js';
 const str = (v) => (typeof v === 'string' ? v : '');
 const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : 0);
@@ -115,7 +116,7 @@ export async function subscriptions(t) {
 /** Buy a plan. No amount is sent: the catalog prices it, and the platform charges that. */
 export async function subscribe(t, p) {
     if (!p.method)
-        throw new Error('Add a card before choosing a paid plan');
+        throw new Error(phrase('Add a card before choosing a paid plan'));
     const raw = obj(await call(t, 'POST', '/v1/billing/subscribe/card', { planId: p.plan, paymentMethodId: p.method, interval: p.interval }));
     return { subscription: str(raw.subscriptionId), charged: num(raw.amountCents) };
 }
@@ -183,7 +184,7 @@ export function chosen(list) {
 /** Save a card from the single-use token the processor's form returned, optionally with billing info. */
 export async function save(t, token, billingAddress) {
     if (!token)
-        throw new Error('The card form returned no token');
+        throw new Error(phrase('The card form returned no token'));
     const body = { type: 'card', providerRef: token };
     if (billingAddress && Object.values(billingAddress).some(Boolean)) {
         body.billingAddress = billingAddress;
@@ -299,9 +300,9 @@ export async function arm(t, rule) {
 /** Charge a saved card and add the amount to the balance; answers the balance after. */
 export async function topup(t, amount, card) {
     if (!Number.isInteger(amount) || amount <= 0)
-        throw new Error('Enter an amount to add');
+        throw new Error(phrase('Enter an amount to add'));
     if (!card)
-        throw new Error('Add a card before buying more');
+        throw new Error(phrase('Add a card before buying more'));
     const r = obj(await call(t, 'POST', '/v1/billing/topup', { amountCents: amount, paymentMethodId: card }));
     return num(r.balanceCents);
 }
@@ -371,7 +372,7 @@ export function monthly(list) {
 /** Set the org's monthly cap: change the one there is, or open one that refuses spend past it. */
 export async function limit(t, list, threshold) {
     if (!Number.isInteger(threshold) || threshold <= 0)
-        throw new Error('Enter a monthly limit');
+        throw new Error(phrase('Enter a monthly limit'));
     const was = monthly(list);
     if (was)
         return cap(await call(t, 'PATCH', `/v1/billing/alerts/${seg(was.id)}`, { threshold }));