@argentic/chest-sdk 0.1.1 → 0.3.0

package/README.md

@@ -1,9 +1,13 @@
 # Chest SDK
 
 `@argentic/chest-sdk` is what a server tool (tool contract v2) embeds to talk
-with its Chest: the member the Chest asserts on a request, the address of the
-tool's own database and its private files. The SDK has no dependency: it only
-imports `node:*`.
+with its Chest: the member the Chest asserts on a request, the Chest itself
+(its organization, time zone and language), the other members
+who have the tool, the address of the tool's own database, its private
+files, the badges and notifications it shows members inside the Chest, the
+events of its members' lifecycle, AI models through the Chest — and, for the
+tool's tests, a fake Chest. The SDK has no dependency: it
+only imports `node:*`.
 
 ```sh
 npm install @argentic/chest-sdk
@@ -14,22 +18,35 @@ Node 22 or later. ESM only, compiled JavaScript with its type declarations.
 ## Imports
 
 Each module is its own subpath and pulls in nothing else; the root gives them
-all, with the files API as the namespace `files`.
+all, with the files, members, notifications, events and ai APIs as the
+namespaces `files`, `members`, `notifications`, `events` and `ai` (the
+testing module is not in the root).
 
 | Import | Gives |
 |---|---|
-| `@argentic/chest-sdk/member` | `member(request)`, type `Member`: the member of a request on the team host of a server tool, read from the `Chest-Member` assertion and verified; `null` without a valid assertion |
+| `@argentic/chest-sdk/member` | `member(request)`, type `Member`: the member of a request on the team host of a server tool, with the language the Chest speaks to them and the zone they work in, read from the `Chest-Member` assertion and verified; `null` without a valid assertion. `memberIdPattern`, `groupIdPattern`, `languagePattern`, `timeZonePattern`: the grammars of the identifiers (`mbr_…`, `grp_…`), of a language and of a zone |
+| `@argentic/chest-sdk/chest` | `chest`, type `Chest`: the Chest the tool runs in — `chest.organization.name`, `chest.timeZone`, `chest.language`, `chest.today()` —, the same for every member, on a request or outside one |
+| `@argentic/chest-sdk/members` | `list`, `get`, `lookup`, `groups.list`, `forget`, types `MemberPage`, `Lookup`, `FormerMember`, `Group`: the members who have the tool (capability `members`, their addresses with `members.email`) |
+| `@argentic/chest-sdk/notifications` | `notify`, `withdraw`, `badge.set`, `badge.setMany`, types `Notice`, `Delivery`, `BadgeCount`, `BadgeWrite`: counters on the tool's tile and items in members' inboxes, inside the Chest (capability `notifications`) |
+| `@argentic/chest-sdk/events` | `handle`, `verify`, `acknowledgeErasure`, `memorySeen`, `erasureIdPattern`, types `ChestEvent`, `MemberUpdated`, `AccessRevoked`, `MemberRemoved`, `MemberErased`, `MemberChange`, `Handlers`, `Seen`: the events of the members' lifecycle the Chest posts to the tool's `/chest-events` (`"receives": ["member.*"]`), verified, deduplicated by id, and the acknowledgment of an erasure |
+| `@argentic/chest-sdk/ai` | `chat`, `embed`, `models`, `usage`, types `Alias`, `Provider`, `ChatMessage`, `ChatTool`, `ToolChoice`, `ResponseFormat`, `ChatOptions`, `ChatResult`, `ChatChunk`, `ToolCall`, `ToolCallDelta`, `Usage`, `EmbedOptions`, `Embeddings`, `AiModel`, `AiUsage`: AI models through the Chest, on the owner's connectors, metered against the tool's monthly cap (capability `ai`) |
 | `@argentic/chest-sdk/database` | `databaseUrl()`: the address of the tool's own PostgreSQL database (capability `database`) |
-| `@argentic/chest-sdk/files` | `put`, `get`, `list`, `delete`, `url`, types `FileObject`, `FileData`, `FilePage`: the tool's private files (capability `files`), kept by the Chest, and a 15-minute signed link to one |
-| `@argentic/chest-sdk/errors` | `ChestError` (`code`, `status`), `CapabilityNotGranted` (403), `TooLarge` (413), `QuotaExceeded` (429), `Unavailable` (503): what the SDK throws when the Chest does not give what a tool asks |
-| `@argentic/chest-sdk` | all of the above; `files` as a namespace |
+| `@argentic/chest-sdk/files` | `put`, `get`, `stat`, `list`, `move`, `delete`, `url`, `uploadUrl`, types `FileObject`, `FileData`, `FilePage`: the tool's private files (capability `files`), kept by the Chest, a 15-minute signed link to one (or to its thumbnail), and uploads straight from a member's browser |
+| `@argentic/chest-sdk/errors` | `ChestError` (`code`, `status`), `CapabilityNotGranted` (403), `TooLarge` (413), `QuotaExceeded` (429), `RateLimited` (429), `Unavailable` (503), and for AI `AiCapReached` (402), `AiModelNotAllowed` (403), `AiRefused` (422), `AiUnavailable` (502, 503), type `AiUnavailableReason`: what the SDK throws when the Chest does not give what a tool asks |
+| `@argentic/chest-sdk/testing` | `signAssertion`, `withMember`, `fakeChest`, types `AssertionOptions`, `FakeChest`, `FakeChestOptions`, `FakeGroup`, `FakeFile`, `FakeNotification`, `FakeEvent`, `FakeAi`, `FakeAiModel`, `FakeAiReply`, `FakeAiCall`: for the tool's own tests only |
+| `@argentic/chest-sdk` | all of the above but `testing`; `files`, `members`, `notifications`, `events` and `ai` as namespaces |
 
 ```ts
 import { member } from "@argentic/chest-sdk/member";
+import { chest } from "@argentic/chest-sdk/chest";
 import { databaseUrl } from "@argentic/chest-sdk/database";
 import * as files from "@argentic/chest-sdk/files";
+import * as members from "@argentic/chest-sdk/members";
+import * as notifications from "@argentic/chest-sdk/notifications";
+import * as events from "@argentic/chest-sdk/events";
+import * as ai from "@argentic/chest-sdk/ai";
 import { CapabilityNotGranted } from "@argentic/chest-sdk/errors";
-// or: import { member, databaseUrl, files } from "@argentic/chest-sdk";
+// or: import { member, chest, databaseUrl, files, members, notifications, events, ai } from "@argentic/chest-sdk";
 ```
 
 Types refer to `node:http` (`IncomingMessage`): a TypeScript project needs
@@ -39,7 +56,7 @@ Types refer to `node:http` (`IncomingMessage`): a TypeScript project needs
 ### Next.js
 
 The SDK runs on the server only — it reads the tool's environment
-(`CHEST_TOKEN`, `DATABASE_URL`, `CHEST_API`) and uses Node built-ins. Import it
+(`CHEST_TOKEN`, `DATABASE_URL`, `CHEST_API`, `CHEST_TIME_ZONE`…) and uses Node built-ins. Import it
 in route handlers, server components or server actions, never in a
 `"use client"` module. Webpack and Turbopack resolve the
 compiled package with no configuration (no `transpilePackages`):
@@ -59,8 +76,10 @@ export function GET(request: Request) {
 A v2 tool is an ordinary web server in a container without network, run by
 its Chest. The Chest's front is the only one to reach it; the tool reaches only
 what its launcher gives it on `127.0.0.1` (its database, the Chest's API for
-its files). Rights come from the Chest — the signed member, the capabilities
-approved for the version — and the Chest enforces them even outside the SDK:
+its files, its members, its notifications and AI), and the Chest posts it the
+events it receives on `/chest-events`, through the same launcher. Rights come
+from the Chest — the signed member, the capabilities approved for the
+version — and the Chest enforces them even outside the SDK:
 the SDK makes the calls easier, it is not a security boundary. The full
 contract (manifest `chest.json`, capabilities, build from source, catalogue)
 is described in the Chest repository, `docs/architecture.md`.
@@ -70,19 +89,38 @@ is described in the Chest repository, `docs/architecture.md`.
 A v2 tool is an ordinary web server; on its team host, the Chest relays
 `/chest` and everything below it with the `Chest-Member` header of the
 signed-in member. `member(request)` accepts a Node request (`IncomingMessage`)
-or a Web `Request` and returns:
+or a Web `Request` and returns a `Member`, the type the `members` API
+answers too:
 
 ```ts
-type Member = { id: string; firstName: string; lastName: string; name: string; email: string; photo?: string; role?: string; isAdmin: boolean; isBuilder: boolean };
+type Member = {
+  id: string;            // "mbr_…": the member in this Chest, the same in all its tools
+  firstName: string;
+  lastName: string;
+  name: string;          // "Camille Martin", or the local part of the address without names
+  photo: string | null;  // /_chest/members/{id}/photo?v=<rev> on the tool's team host
+  role: string | null;   // one of the roles chest.json declares; null if it declares none
+  isAdmin: boolean;      // owner or admin of the Chest
+  isBuilder: boolean;    // builder of this tool
+  groups: string[];      // "grp_…": the groups that give the member this tool
+  language: string;      // "en", "fr"…: the language the Chest speaks to this member
+  timeZone: string;      // "America/New_York": the zone the member works in
+  email?: string;        // only with the capability "members.email"
+};
 ```
 
 or `null`: without the header, on the public host (the Chest never sends an
 assertion there and strips a client's), or for any assertion that is not
 exactly its own. Checks: compact JWS, header exactly
 `{"alg":"HS256","typ":"JWT"}`, HMAC-SHA256 signature compared in constant time
-under the key HMAC-SHA256("Chest-Member v1") of the text of `CHEST_TOKEN` —
-the Chest's derivation —, `aud` equal to `CHEST_TOOL`, `iat` and `exp` within
-5 s, the shape of each claim (an unknown claim is ignored). Without
+under the key HMAC-SHA256("Chest-Member v2") of the text of `CHEST_TOKEN` —
+the Chest's derivation; the label changes when a claim changes meaning or
+goes, so an assertion of another shape is refused rather than misread, and
+stays when a claim is added —, `aud` equal to
+`CHEST_TOOL`, `iat` and `exp` within 5 s, the shape of each claim (`sub` an
+`mbr_` identifier, `groups` `grp_` identifiers, `language` a primary tag of
+2 or 3 lowercase letters, `time_zone` a zone of `timeZonePattern`; an
+unknown claim is ignored). Without
 `CHEST_TOKEN` or `CHEST_TOOL`, nobody is a member. The function never throws
 for what a request carries.
 
@@ -92,10 +130,402 @@ const who = member(request);
 if (!who) { response.writeHead(401).end(); return; }
 ```
 
-`photo` is the address of the photo on the team host, `role` the role the
-Chest gives the member among those the manifest declares. Only the Chest's
-front reaches the container: the signature is a second defence; business rules
-(who writes what) remain the tool's.
+`id` is the member's identifier in the Chest: random, never an address nor
+an account of the sign-in provider, stable when the member changes their name
+or address, never given to anyone else. Store it in your data; resolve names
+when rendering (`members.lookup`). `photo` is served by the Chest on the team
+host to members who have the tool; `role` is the one the Chest gives the
+member among those the manifest declares. Only the Chest's front reaches the
+container: the signature is a second defence; business rules (who writes
+what) remain the tool's.
+
+`language` is the member's own language in the Chest, else the Chest's
+default: a BCP 47 primary tag among those the product speaks (`en`, `fr`
+today; the SDK accepts any, so a language added to the Chest needs no new
+SDK). The tool's private part (`/chest`) speaks it — to this member, on every
+request — and offers no language switch of its own; only its public parts,
+where nobody is signed in, keep their own switch. The members API answers
+it too: a notification or an email to another member is written in *their*
+language (`members.get(id).language`), not in the sender's. A tool that does not
+speak that language uses its own default. `timeZone` is the zone the member
+works in: the one they chose in their profile, else the one their browser
+is in, else the Chest's. The members API answers it too, so a tool reminds
+each member at their own hour. What is the same for every member — the
+organization, the company's time zone — is not the member's: it is the
+Chest's (below).
+
+### Times: store in UTC, decide in the Chest's zone, show in the member's
+
+| What | Zone |
+|---|---|
+| An instant (created, due at, sent at) | stored as UTC: `timestamptz` in PostgreSQL, `Date` in code |
+| “Today”, “this week”, a deadline's day, business hours, working days | the company's: `chest.timeZone`, `chest.today()` (the database's `current_date` is the same) |
+| A time or a date shown to a member, a personal reminder's hour | theirs: `member(request).timeZone`, or `members.get(id).timeZone` outside their request |
+
+```ts
+const who = member(request)!;
+const due = await sql`select * from tasks where due_on = ${chest.today()}`; // the company's day
+const shown = new Intl.DateTimeFormat(who.language, { timeZone: who.timeZone, dateStyle: "medium", timeStyle: "short" }).format(task.remindAt);
+```
+
+## `chest` — the Chest the tool runs in
+
+```ts
+import { chest } from "@argentic/chest-sdk/chest";
+
+chest.organization.name; // "Acme SAS": the organization the Chest is of, as its owner wrote it
+chest.timeZone;          // "Europe/Paris": an IANA zone, "UTC" until the owner sets one
+chest.language;          // "fr": the Chest's own language (a member's is member(request).language)
+chest.today();           // "2026-09-30": the date now in the Chest's zone (or chest.today(at))
+```
+
+The Chest gives these to every tool in its environment at each start
+(`CHEST_ORGANIZATION`, `CHEST_TIME_ZONE`, `CHEST_LANGUAGE`), and starts every
+tool again when its owner changes one in Settings → General — the tool never
+asks its own admin for the company's name or zone. They are there outside a
+request too: a scheduled job, a start-up task, an export. No capability is
+needed: nothing here is more than what the Chest's pages show its members.
+
+- `organization.name` is plain text of 2 to 80 characters: show it in a
+  header, a document or an email, never as HTML.
+- `timeZone` is the day of “due today” and the hour of a reminder. The Chest
+  also makes it the `TimeZone` of the tool's database sessions: there,
+  `current_date`, `now()::date` and a `timestamptz` shown as text are in the
+  Chest's zone. A session may set its own (`SET TIME ZONE`), for itself.
+- `language` is the language of what the tool writes for no one in
+  particular: a public page before the visitor chooses, an export's default.
+  A page of `/chest` speaks `member(request).language` instead.
+- `today(at?)` is `YYYY-MM-DD` in the Chest's zone, for now or for an instant
+  (`Date` or milliseconds): compare it with dates your database keeps as
+  `date`, never with `new Date().toISOString().slice(0, 10)`, which is UTC's.
+
+Each value is read from the environment at each access, and checked: outside a
+Chest (a development server without the variables), or for a value the Chest
+never gives, reading it throws a `ChestError` with the code `not_in_chest` —
+a wrong zone read silently is exactly what this module exists to prevent. In
+tests, `fakeChest({chest: {organization, timeZone, language}})` sets them.
+
+## `members` — who has the tool
+
+A v2 tool that declares `"capabilities": ["members"]` (approved like a
+permission: “Sees the name, photo, role and groups of the members who have
+access to it.”) reads the members who have it, through the Chest's API
+(`CHEST_API`, as for files). `"members.email"`, a permission of its own that
+requires `members`, adds their addresses — to these answers and to
+`member(request)`.
+
+```ts
+import * as members from "@argentic/chest-sdk/members";
+const { members: page, next } = await members.list({ q: "cam", limit: 50 }); // by name, then id
+const camille = await members.get("mbr_k2qhx4mzc7v3b6nfp5r2t7w4ya");        // Member, or null
+const { members: found, former, unknown } = await members.lookup(ids);      // any number of ids
+const teams = await members.groups.list();                                  // [{id, name, members}]
+```
+
+- **Who**: exactly the members who have the tool now — by a grant, a group,
+  open to all, or because they run it (owner, admins, its builders);
+  recomputed at every call. A member without access answers as an identifier
+  that does not exist (`get` → `null`, `lookup` → `unknown`).
+- **`list({after, limit, q, role, group})`**: ordered by name (accents aside)
+  then identifier; `limit` 100 by default, 500 at most; `next` is an opaque
+  cursor for `after`, `null` after the last page. `q` finds the start of a
+  first name, a last name or a name — and of an address with `members.email`
+  —, whatever its case and accents; `role` and `group` keep the members of that
+  role or group.
+- **`lookup(ids)`**: each identifier once, in the order given: `members`,
+  `former` (`{id, name, status: "former"}`: someone who left the Chest after
+  having the tool, so a record still reads “Camille Martin (former member)”;
+  `{id, name: null, status: "erased"}` once the owner had their data erased,
+  rendered “Former member”) and `unknown`. The SDK asks 200 at a time and
+  keeps each answer a minute in the process (5,000 at most); `forget()`
+  empties it, and so does every event of the members' lifecycle
+  (`events.handle`).
+- **`groups.list()`**: the groups that give the tool, with their members'
+  identifiers; never the others.
+- Errors: `CapabilityNotGranted` (403), `RateLimited` (429: 600 calls a minute
+  per instance), `Unavailable` (503), `ChestError` for the rest (`invalid_id`,
+  `invalid_query`).
+
+Store identifiers, resolve names when rendering, never copy them: a copied
+name or address goes stale and makes the tool a second directory to erase.
+
+```sql
+create table tasks (
+  id bigint generated always as identity primary key,
+  title text not null,
+  assignee text,                                     -- a member id, "mbr_…"
+  created_by text not null,
+  constraint assignee_is_member check (assignee ~ '^mbr_[a-z2-7]{26}$')
+);
+```
+
+```ts
+const rows = await sql`select * from tasks order by id desc limit 50`;
+const people = await members.lookup(rows.flatMap(r => [r.assignee, r.created_by]).filter(Boolean));
+```
+
+To search tasks by assignee name: `members.list({ q })` first, then
+`where assignee = any($ids)`.
+
+## `notifications` — badges and inbox items
+
+A v2 tool that declares `"capabilities": ["notifications"]` (approved like a
+permission: “Shows counters and sends notifications, inside the Chest, to the
+members who have access to it.”) tells its members what needs their
+attention, inside the Chest only — no email, no push to a phone. Two
+primitives:
+
+- a **badge** is a count on the tool's tile in the Chest home and on its row
+  in the tools list, for one member (“99+” beyond 99): a state, set again as
+  often as it changes;
+- a **notification** is an item in a member's inbox (the bell of the Chest):
+  the tool's icon and name, a title, a body, and a link that opens a page of
+  the tool on its team host.
+
+```ts
+import * as notifications from "@argentic/chest-sdk/notifications";
+
+const { delivered, skipped } = await notifications.notify([assignee], {
+  title: "New task: fix the door",       // 1 to 80 characters
+  body: "Before Friday.\nKeys at the desk.", // 280 characters at most; optional
+  path: "/chest/tasks/42",               // under /chest; /chest when not said
+  key: "task:42",                        // optional: replace, then withdraw
+});
+await notifications.withdraw("task:42");             // done: its items go, for everyone
+await notifications.withdraw("task:42", [assignee]); // only for those
+const shown = await notifications.badge.set(assignee, 3);            // false: no access
+const { set, skipped: noAccess } = await notifications.badge.setMany([
+  { memberId: assignee, count: 3 },
+  { memberId: reviewer, count: 0 },    // 0 clears it
+]);
+```
+
+- **Who**: only members who have access to the tool now receive either.
+  `notify` answers `{delivered, skipped}`, each identifier once in the order
+  given; `skipped` holds identifiers the Chest does not know and members
+  without access (as for `members`, the two are indistinguishable). `badge.set`
+  answers `false` for such a member, `setMany` puts them in `skipped`.
+- **`notify(memberIds, {title, body?, path?, key?})`**: 1 to 500 identifiers
+  (a duplicate counts once), one inbox item per recipient. `title` is 1 to 80
+  characters (Unicode code points), `body` 280 at most (an empty body is
+  none). `path` is a page of the tool's private part: `/chest`, or `/chest`
+  followed by `/`, `?` or `#`; printable ASCII without spaces or `\`, 512
+  characters at most, never `//`, no `.` or `..` segment; the Chest builds the
+  link on the tool's team host, so it cannot point anywhere else. `key` is
+  1 to 64 of `a-z 0-9 . _ : -`.
+- **Replace and withdraw.** A notification with the key of an earlier one, for
+  the same member, replaces it: new text, new time, first in the inbox and
+  unread again — never a duplicate. `withdraw(key, memberIds?)` removes the
+  items of that key, from every member or from those named (1 to 500), once
+  the thing they were about is done. It never says what existed.
+- **Plain text.** The Chest removes control characters (a tab or a line break
+  in a title becomes a space; `body` keeps its line breaks) and the characters
+  that reorder text, trims both, and interprets neither Markdown nor HTML.
+  Every item shows the tool's icon and name beside it: a tool cannot pass for
+  the Chest or another tool. A title that is empty once cleaned is refused.
+- **Muting is invisible.** A member may mute the tool in their profile: their
+  new items are then dropped, but they still count as `delivered`, and their
+  badges stay. The tool never learns who muted it.
+- **Badges** go from 0 to 9,999, 0 clears one. `setMany` takes 1 to 500, a
+  member at most once.
+- **Quotas**, per tool: 1,000 recipients an hour (those with access, muted or
+  not), 100 items per member a day (a replacement counts; one recipient at 100
+  refuses the whole call), 600 badge writes a minute (each badge of `setMany`
+  counts). Beyond, `QuotaExceeded` (429, the Chest answers `Retry-After`); a
+  refused call changes nothing.
+- **Lifecycle**: a member who loses access loses the tool's items and badge;
+  removing the tool removes them all. A member's inbox keeps 500 items for 90
+  days.
+- Errors: `CapabilityNotGranted` (403), `QuotaExceeded` (429), `Unavailable`
+  (503, the Chest not reached, or an answer that is not its own: the call may
+  or may not have happened), `ChestError` for the rest (`invalid_id`,
+  `invalid_title`, `invalid_text`, `invalid_path`, `invalid_key`,
+  `invalid_count`, `invalid_body`) — the SDK refuses these before sending
+  anything.
+
+A badge suits a count that goes up and down (tasks assigned, messages
+unread); a notification, an event worth a look — with a key, so that it goes
+away by itself once handled.
+
+## `events` — the members' lifecycle
+
+A v2 tool that holds `members` and declares `"receives": ["member.*"]` in its
+`chest.json` (approved like a permission: “Is told when the members who have
+access to it change or leave.”) is told, on its own `POST /chest-events`:
+
+| Event | `data` | When |
+|---|---|---|
+| `member.updated` | `{id, changed: ("name" \| "photo" \| "role" \| "groups" \| "email")[]}` | Something the tool sees of a member who has it changed (`email` only with `members.email`) |
+| `access.revoked` | `{id}` | The member lost access to the tool but stays in the Chest |
+| `member.removed` | `{id}` | The member left the Chest: `lookup` now reads them `former` |
+| `member.erased` | `{id, erasure, deadline}` | The owner asked for this person's data to be erased: delete or anonymise what the tool keeps of them before `deadline` (30 days), then `acknowledgeErasure(erasure)` |
+
+A member who gets the tool is no event: the next `list` has them.
+
+```jsonc
+// chest.json
+{ "capabilities": ["members"], "receives": ["member.*"] }
+```
+
+```ts
+// app/chest-events/route.ts — at the root, outside /chest: the Chest calls it
+// through the tool's launcher, never from a browser (its front answers 404 there).
+import * as events from "@argentic/chest-sdk/events";
+
+const seen = {
+  has: async (id: string) => (await sql`select 1 from chest_events where id = ${id}`).length > 0,
+  add: async (id: string) => { await sql`insert into chest_events (id) values (${id}) on conflict do nothing`; },
+};
+
+export async function POST(request: Request) {
+  return new Response(null, { status: await events.handle(request, {
+    "member.updated": e => refreshCache(e.data.id, e.data.changed),
+    "access.revoked": e => sql`update tasks set assignee = null where assignee = ${e.data.id}`,
+    "member.erased": async e => {
+      await sql`update tasks set created_by = 'erased' where created_by = ${e.data.id}`;
+      await events.acknowledgeErasure(e.data.erasure);
+    },
+  }, { seen }) });
+}
+```
+
+- **Delivery**: at least once, in no guaranteed order. An event is an
+  envelope `{id: "evt_…", type, occurredAt, data}`, signed for this tool
+  (`Chest-Event` header, HS256 under a key derived from `CHEST_TOKEN` with
+  the label `Chest-Event v1`, naming the event and the SHA-256 of the body,
+  60 seconds). Any answer but a 2xx is delivered again, the same event with
+  the same id, after 5 s, 15 s, 30 s, 1 min, 2 min, 5 min, 10 min, 30 min, then
+  every hour, for 72 hours — a restart of the node included. Given up, the
+  tool is marked “out of sync” on its page until its next start.
+- **`members.list` is the truth.** Reconcile by listing at start (and so after
+  being out of sync): events keep a tool current between starts, they do not
+  replace reading who has it.
+- **`handle(request, handlers, {seen?})`** answers the status to give the
+  Chest: 401 for what is not a delivery of the Chest for this tool, 204 for an
+  event handled, one already in `seen`, a type without a handler, or one of a
+  later Chest (signed, ignored). It reads the body (64 KiB at most): mount it
+  before any body parser. A handler that throws leaves the event unseen and
+  `handle` throws: answer 500, it comes again. `seen` is the store of the
+  handled ids — `memorySeen()` (the default: 10,000 ids in the process, lost
+  at a restart) or a table of the tool's own, as above. Make handlers
+  idempotent anyway: an event handled but not yet added to `seen` when the
+  tool stops comes again.
+- **`verify(request)`** is the event of a delivery, typed, or `null`; for a
+  tool that routes events itself.
+- **`acknowledgeErasure(erasure)`**: `POST /erasures/{erasure}/done` on the
+  Chest's API; the owner then sees the tool's part done (“Erased on 3 Oct.”),
+  “Overdue” past the deadline otherwise. Again is harmless. Errors:
+  `ChestError` `erasure_not_found` (404: an erasure this tool was not told of)
+  or `invalid_id` (400), `CapabilityNotGranted` (403), `Unavailable`.
+
+## `ai` — AI models through the Chest
+
+A v2 tool that declares the `ai` capability calls AI models through its
+Chest. The Chest's owner connects OpenRouter with the company's own key;
+the tool calls models by four **aliases**: `default`, `fast`, `smart`,
+`embedding`, each led by the Chest to a model it chose (the owner may choose
+another for `default`). The tool names an alias, never a provider's model:
+the model changes for the whole Chest without touching code. The tool never
+holds a key; the Chest meters every call against the tool's monthly cap.
+
+```jsonc
+// chest.json
+{
+  "capabilities": ["ai"],
+  "ai": { "monthly": 20, "models": ["default", "embedding"], "purpose": "Summarises support tickets" }
+}
+```
+
+| Key | Default | |
+|---|---|---|
+| `monthly` | 5 | Whole euros a month, 1 to 1,000: what the tool asks; the owner's cap replaces it and may be changed at any time |
+| `models` | `["default"]` | 1 to 4 of `default`, `fast`, `smart`, `embedding`: the only aliases the tool may call |
+| `purpose` | required | 1 to 120 characters, shown at approval: “Uses AI models through the Chest, up to €20 a month” |
+
+```ts
+import * as ai from "@argentic/chest-sdk/ai";
+
+const r = await ai.chat({
+  model: "default",
+  messages: [{ role: "system", content: "Summarise in two sentences." }, { role: "user", content: ticket.text }],
+  maxTokens: 300,                 // 1 to 128,000; 4,096 when not said
+  member: who.id,                 // optional: attribution in the Chest's usage log
+});
+r.text;                           // "" when the model only called tools
+r.usage;                          // { input, output, cached, cost } — cost in estimated euros
+
+// Streamed: pieces as they come; breaking out of the loop ends the call.
+for await (const chunk of ai.chat({ model: "fast", messages, stream: true, signal })) {
+  write(chunk.text);              // chunk.toolCalls, chunk.finishReason, then chunk.usage last
+}
+
+// Tools: the model asks, the tool runs them and answers.
+const step = await ai.chat({ model: "smart", messages, tools: [{ type: "function", function: { name: "lookup", parameters: schema } }] });
+messages.push(step.message);
+for (const call of step.toolCalls) messages.push({ role: "tool", tool_call_id: call.id, content: JSON.stringify(await run(call.name, JSON.parse(call.arguments))) });
+
+const { embeddings } = await ai.embed({ model: "embedding", input: ["first text", "second text"] }); // 1 to 256 texts
+const mapped = await ai.models();  // [{ alias, model, provider, input, output }] — USD per million tokens
+const month = await ai.usage();    // { month: "2026-09", spent, cap, resetsAt }
+```
+
+- **`chat(options)`** takes the OpenAI Chat Completions request in camelCase:
+  `model`, `messages`, `maxTokens`, `temperature`, `topP`, `stop`, `tools`,
+  `toolChoice`, `responseFormat`, `parallelToolCalls`, `seed`,
+  `reasoningEffort`, plus `member`, `stream` and `signal`. Messages, tools and
+  response formats keep the OpenAI shape (images in `content` parts too); the
+  Chest translates them for each provider and never runs a tool. Without
+  `stream` it returns `Promise<ChatResult>` `{text, message, toolCalls,
+  finishReason, model, usage}` — `message` is the assistant's message to add
+  to the conversation, `toolCalls` are `{id, name, arguments}` with the
+  arguments as JSON text, `model` is the provider's model. With
+  `stream: true` it returns an `AsyncIterable<ChatChunk>` `{text, toolCalls?,
+  finishReason?, usage?}`: tool calls come in pieces (`{index, id?, name?,
+  arguments?}`: join the `arguments` of the same `index`), the usage in the
+  last chunk.
+- **Bounds**: a request body of 10 MiB (images included), 16 MiB of answer, a
+  call ends after 10 minutes (streamed or not); 60 requests a minute and 8
+  streams at once per tool (`RateLimited`). An aborted `signal` throws its
+  reason.
+- **The cap never overshoots**: before a call the Chest reserves its worst
+  case (input and `maxTokens`) against the tool's cap and the Chest's; a call
+  that does not fit is refused before anything is spent. Keep `maxTokens` to
+  what the answer needs.
+- **`embed({model, input, dimensions?, member?})`** gives one vector per text,
+  in the order given, and the input tokens and cost.
+- **`models()`** gives the aliases the tool declared that the owner mapped,
+  with their model, provider and prices; **`usage()`** the tool's month:
+  estimated euros spent, the cap in force, and when the month resets.
+
+**AI can stop at any time** — the month's budget spent, no connector, the
+provider down. Keep the tool usable without it:
+
+```ts
+import { AiCapReached, AiUnavailable } from "@argentic/chest-sdk/errors";
+
+let summary: string | null = null;
+try {
+  summary = (await ai.chat({ model: "default", messages, maxTokens: 300 })).text;
+} catch (error) {
+  if (!(error instanceof AiCapReached || error instanceof AiUnavailable)) throw error;
+  // summary stays null: show "AI features are paused" and keep the page working
+}
+```
+
+| Error | Code, status | When |
+|---|---|---|
+| `AiCapReached` | `cap_reached` 402 | The tool's (`scope: "tool"`) or the Chest's (`scope: "chest"`) monthly cap is spent, until `resetsAt` |
+| `AiUnavailable` | `no_connector` 503, `provider_key_invalid` 502, `provider_unavailable` 503 | No connector behind the alias, the provider refused the connector's key, or failed (`reason`) |
+| `AiModelNotAllowed` | `model_not_allowed` 403 | An alias the tool did not declare in `models` (the SDK refuses any other name before sending) |
+| `CapabilityNotGranted` | `capability_not_granted` 403 | The version does not hold `ai`, or it was not approved |
+| `AiRefused` | `content_refused` 422 | The provider's moderation refused the content |
+| `RateLimited` | `rate_limited` 429 | 60 requests a minute or 8 streams at once |
+| `TooLarge` | `too_large` 413 | A body beyond 10 MiB, or a context beyond the model's |
+| `ChestError` | `invalid_body`, `invalid_request` 400 | A malformed request (the SDK refuses most before sending), or parameters the provider rejected (its message in the error's) |
+| `Unavailable` | `unavailable` 503 | The Chest not reached, or an answer that is not its own; in a stream, the stream cut |
+
+An error in the middle of a stream is thrown where it comes, after the chunks
+before it.
 
 ## `databaseUrl()` — database of a server tool
 
@@ -137,32 +567,135 @@ previous version working — going back to the previous version undoes nothing.
 
 A v2 tool that declares `"capabilities": ["files"]` (approved like a permission)
 keeps private files **through its Chest**, never on its disk (the container's
-root is read-only): 1 GiB and 10,000 objects per tool, 32 MiB per object. The
-launcher gives the tool `CHEST_API=http://127.0.0.1:<port>` — its own port,
-relayed to the Chest; the container has no network — and the instance is the
-identity: the tool reaches its own files only.
+root is read-only). The launcher gives the tool
+`CHEST_API=http://127.0.0.1:<port>` — its own port, relayed to the Chest; the
+container has no network — and the instance is the identity: the tool reaches
+its own files only.
 
 ```ts
 import * as files from "@argentic/chest-sdk/files";
 await files.put("photos/cat.png", bytes, "image/png");       // Uint8Array or text
 const file = await files.get("photos/cat.png");              // {data, type, size} or null
+const info = await files.stat("photos/cat.png");             // {name, type, size, updated, width?, height?} or null
 const { files: page, next } = await files.list({ prefix: "photos/" }); // 1000 per page
-await files.delete("photos/cat.png");                        // true, or false if it did not exist
-const { url, expiresIn } = await files.url("photos/cat.png");
+await files.move("photos/cat.png", "archive/cat.png");       // atomic; replaces archive/cat.png
+await files.delete("archive/cat.png");                       // true, or false if it did not exist
+const { url, expiresIn } = await files.url("photos/dog.png", { thumbnail: 256 });
 ```
 
 A name: up to 8 segments of 1 to 100 letters, digits, `.`, `_` or `-`,
 separated by `/`, none starting with `.` or `-`; refused before anything is
-sent otherwise (`ChestError`, `invalid_name`). `url` signs a link to the file
-as it is, on the tool's **team host** (`/_chest/files/…`): whoever has it opens
-it without signing in for 15 minutes, or until the file changes or goes; the
-Chest serves it in a sandbox, displayed for an image, a PDF or plain text,
-downloaded otherwise. Give it to a member's browser, never to a public page.
+sent otherwise (`ChestError`, `invalid_name`).
+
+### Limits
+
+Per tool: 1 GiB, 10,000 objects and 32 MiB per object, unless its manifest
+asks otherwise — approved by the owner like any permission, and a later
+version that asks more is approved again:
+
+```jsonc
+// chest.json
+{ "capabilities": ["files"], "files": { "quota": "5 GiB", "maxObject": "100 MiB" } }
+```
+
+`quota` goes from 100 MiB to 100 GiB (10 GiB and more allow 100,000 objects),
+`maxObject` from 1 to 512 MiB; the owner or an admin may also set the quota
+by hand. The SDK refuses beyond 512 MiB before sending anything; the Chest
+holds the tool to its own bounds (`TooLarge`, `QuotaExceeded`). `put` and
+`get` carry the bytes through the tool's server: for large files, let the
+browser upload them itself.
+
+### Uploads from a member's browser
+
+The bytes go from the browser to the Chest directly, never through the tool.
+The tool authorises one upload, in a `/chest` route, once `member()` said who
+asks:
+
+```ts
+// Server side: app/chest/api/invoices/upload/route.ts
+const up = await files.uploadUrl("invoices/2026/0042.pdf", {
+  maxSize: 10 << 20,                // bytes; the tool's largest object when not said
+  types: ["application/pdf"],       // up to 8, "image/*" for a family; any when not said
+  expiresIn: 300,                   // 1 to 900 seconds; 900 when not said
+});
+// → { url, method: "PUT", expiresIn }: hand it to the member's browser
+```
+
+```ts
+// Browser side, on a page under /chest: the member's session goes with it
+const response = await fetch(up.url, { method: "PUT", body: file, headers: { "Content-Type": file.type } });
+// 201 {name, type, size}; 403 invalid_token (used, expired), 415 type_refused,
+// 400 type_mismatch, 413 too_large, 429 quota_exceeded, 401 without a session
+```
+
+```ts
+// Server side, when the browser says it is done
+const info = await files.stat("invoices/2026/0042.pdf"); // null if nothing came
+```
+
+`url` is `https://<tool's team host>/_chest/files/upload/<token>`: the same
+origin as the tool's `/chest` pages, so no CORS. The token is signed by the
+Chest and binds the name, the size, the types and the expiry; it serves once.
+A name ending in `/` is a folder: the Chest then names the object (20 hex
+characters and an extension from its type) and answers its name. The Chest
+checks the declared size before reading, drops the body at the first byte too
+many, and for images, PDFs and archives checks that the first bytes are of the
+type sent; nothing of a refused upload remains. There is no antivirus scan.
+`uploadUrl` answers `Unavailable` while the Chest does not know the tool's
+team host yet.
+
+### Links and thumbnails
+
+`url(name, {thumbnail?, download?})` signs a link to the file as it is, on the
+tool's **team host** (`/_chest/files/…`): whoever has it opens it without
+signing in for 15 minutes, or until the file changes or goes; the Chest serves
+it in a sandbox, displayed for an image, a PDF or plain text, downloaded
+otherwise, or always downloaded with `download: true`. `thumbnail: 256` or
+`1024` links to the image reduced to that many pixels (JPEG, PNG, GIF — its
+first frame — and WebP up to 40 megapixels; `ChestError` `no_thumbnail`
+otherwise); thumbnails are made once, not counted in the quota. `stat` gives
+`width` and `height` for these images. Give a link to a member's browser,
+never to a public page.
+
 Errors: `CapabilityNotGranted` (a version without the capability, or no
 `CHEST_API`), `TooLarge` (413), `QuotaExceeded` (429), `Unavailable` (the
 Chest not reached, or an answer that is not its own: a write may or may not
-have happened), `ChestError` for the rest (`invalid_type`, `not_found` for
-`url`…). Removing the tool removes its files; a new version keeps them.
+have happened), `ChestError` for the rest (`invalid_type`, `no_thumbnail`,
+`not_found` for `url` and `move`…). Removing the tool removes its files; a new
+version keeps them.
+
+## `testing` — a tool's own tests
+
+`@argentic/chest-sdk/testing` is for tests, never imported by production code.
+
+```ts
+import { fakeChest, signAssertion, withMember } from "@argentic/chest-sdk/testing";
+
+const camille = { id: "mbr_k2qhx4mzc7v3b6nfp5r2t7w4ya", firstName: "Camille", lastName: "Martin", name: "Camille Martin", photo: null, role: "editor", isAdmin: false, isBuilder: false, groups: [], language: "fr", timeZone: "Europe/Paris" };
+const chest = await fakeChest({ members: [camille], capabilities: ["members", "files", "notifications", "ai"], ai: { reply: () => "Summary." } });
+const response = await handler(withMember(new Request("http://tool.test/chest/tasks"), camille));
+assert.equal(await chest.emit({ type: "member.erased", data: { id: camille.id, erasure: "era_k2qhx4mzc7v3b6nfp5r2t7w4ya", deadline: "2026-10-28T10:00:00Z" } }, request => handler(request)), 204);
+assert.deepEqual(chest.acknowledged, ["era_k2qhx4mzc7v3b6nfp5r2t7w4ya"]);
+assert.deepEqual((await members.list()).members.map(m => m.id), [camille.id]);
+assert.ok(chest.files.has("reports/2026.pdf"));
+assert.deepEqual(chest.notifications, [{ member: camille.id, title: "New task", path: "/chest/tasks/42", key: "task:42" }]);
+assert.equal(chest.badges.get(camille.id), 1);
+assert.equal(chest.ai[0]?.path, "/ai/chat");
+await chest.close();
+```
+
+| Function | Gives |
+|---|---|
+| `signAssertion(member, {token?, tool?, now?})` | A `Chest-Member` header value signed like the Chest's for that `Member` (the token and tool of the environment by default), signed as given, so a language or a zone the Chest never sends makes `member()` refuse it |
+| `withMember(request, member, options?)` | The request carrying that assertion (the options of `signAssertion`): a new Web `Request`, or the same Node request |
+| `fakeChest({members?, former?, groups?, capabilities?, receives?, files?, ai?, chest?})` | An HTTP server on `127.0.0.1` that sets `CHEST_API`, `CHEST_TOKEN`, `CHEST_TOOL` (`tool` unless set), the Chest's `CHEST_ORGANIZATION`, `CHEST_TIME_ZONE`, `CHEST_LANGUAGE` (`chest: {organization, timeZone, language}`: `"Test organization"`, `"UTC"`, `"en"` by default) and answers members, groups, files, badges, notifications, AI and erasure acknowledgments with a Chest's bounds, quotas and errors; a capability left out answers 403 (`members`, `files`, `notifications` and `ai` by default; `members.email` adds the addresses; `receives` is `["member.*"]` by default, `[]` refuses acknowledgments). A former member `{id, name?, erased?}` looks up as `former`, or `erased` |
+| `chest.emit(event, to)` | Delivers an event (`{type, data, id?, occurredAt?}`: a new id and now by default; name an id to deliver the same event twice) signed as the Chest signs it, to `to` — the tool's address (`POST <to>/chest-events`) or a function of a Web `Request` — and says the status it answered. A `member.erased` makes its erasure one the tool may acknowledge |
+| `ai: {models?, reply?, cap?, unavailable?}` | The fake Chest's AI, deterministic and without any provider. `models`: the aliases the tool declared, `{alias, model, provider?, input?, output?}` (all four by default, `fake-default`…`fake-embedding`, provider `openrouter`, 1 and 2 USD per million tokens); another alias answers `model_not_allowed`. `reply(request)`: what a chat answers, given the wire request — a string, or `{text?, toolCalls?: {name, arguments, id?}[]}` (by default the last user message, echoed); streamed, it comes word by word, each tool call's arguments in two pieces, then the finish reason and the usage. Embeddings are unit vectors from a hash of each text (8 dimensions unless `dimensions`). Tokens count one per 4 characters; once the spending reaches `cap` (euros, 5 by default; 0 refuses at once) a call answers `cap_reached`. `unavailable` (`no_connector`, `provider_key_invalid`, `provider_unavailable`) makes chat and embeddings answer it. 60 requests a minute |
+| `chest.ai` | The tool's calls to AI, `{path, body}` in order (`body` null for a `GET`) |
+| `chest.acknowledged` | The erasures the tool acknowledged, each once |
+| `chest.members`, `chest.groups`, `chest.files` | What the fake Chest holds, to change or assert on; its `members` are those who have the tool |
+| `chest.notifications`, `chest.badges` | What the tool sent: the items kept, `{member, title, body?, path, key?}` cleaned as the Chest cleans them, in the order sent (a replaced item removed, the new one last; `withdraw` removes), and each member's badge (`Map` member → count; 0 removes it) |
+| `chest.close()` | Stops it and restores the environment |
 
 ## Version
 
@@ -191,9 +724,12 @@ npm run check:package  # npm pack, install into a temp project, import every sub
 ```
 
 `client/src` holds the modules, `client/index.ts` the package root,
-`client/test` the tests. `npm run build` compiles `client/index.ts` and the
-four published modules (`errors`, `member`, `database`, `files`; TypeScript
-strict, ES2022, NodeNext) into `dist/`: ESM `.js`, `.d.ts` and their maps.
+`client/test` the tests. `npm run build` compiles `client/index.ts`, the
+nine published modules (`errors`, `member`, `members`, `database`, `files`,
+`notifications`, `events`, `ai`, `testing`) and the one they share (`api`, the Chest's API) —
+TypeScript strict, ES2022, NodeNext — into `dist/`: ESM `.js`, `.d.ts` and
+their maps. `member.ts` imports nothing but `node:*`, so that a tool may copy
+it alone.
 The package stays dependency-free (`node:*` only) and reaches nothing but the
 Chest's API on `127.0.0.1`. `AGENTS.md` is a usage guide for AI agents
 building a tool with this package.