@argentic/chest-sdk 0.1.1 → 0.2.0

package/README.md

@@ -1,9 +1,11 @@
 # 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 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 — 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 +16,31 @@ 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 and events APIs as the
+namespaces `files`, `members`, `notifications` and `events` (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, read from the `Chest-Member` assertion and verified; `null` without a valid assertion. `memberIdPattern`, `groupIdPattern`: the grammars of the identifiers (`mbr_…`, `grp_…`) |
+| `@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/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): what the SDK throws when the Chest does not give what a tool asks |
+| `@argentic/chest-sdk/testing` | `signAssertion`, `withMember`, `fakeChest`, types `FakeChest`, `FakeChestOptions`, `FakeGroup`, `FakeFile`, `FakeNotification`, `FakeEvent`: for the tool's own tests only |
+| `@argentic/chest-sdk` | all of the above but `testing`; `files`, `members`, `notifications` and `events` as namespaces |
 
 ```ts
 import { member } from "@argentic/chest-sdk/member";
 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 { CapabilityNotGranted } from "@argentic/chest-sdk/errors";
-// or: import { member, databaseUrl, files } from "@argentic/chest-sdk";
+// or: import { member, databaseUrl, files, members, notifications, events } from "@argentic/chest-sdk";
 ```
 
 Types refer to `node:http` (`IncomingMessage`): a TypeScript project needs
@@ -59,8 +70,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 and its notifications), 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`.
@@ -73,16 +86,29 @@ signed-in member. `member(request)` accepts a Node request (`IncomingMessage`)
 or a Web `Request` and returns:
 
 ```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
+  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 with the shape of the claims, so an
+assertion of another shape is refused rather than misread —, `aud` equal to
+`CHEST_TOOL`, `iat` and `exp` within 5 s, the shape of each claim (`sub` an
+`mbr_` identifier, `groups` `grp_` identifiers; 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 +118,227 @@ 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.
+
+## `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`.
 
 ## `databaseUrl()` — database of a server tool
 
@@ -137,32 +380,132 @@ 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: [] };
+const chest = await fakeChest({ members: [camille], capabilities: ["members", "files", "notifications"] });
+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);
+await chest.close();
+```
+
+| Function | Gives |
+|---|---|
+| `signAssertion(member, {token?, tool?, now?})` | A `Chest-Member` header value signed like the Chest's (the token and tool of the environment by default) |
+| `withMember(request, member, options?)` | The request carrying that assertion: a new Web `Request`, or the same Node request |
+| `fakeChest({members?, former?, groups?, capabilities?, receives?, files?})` | An HTTP server on `127.0.0.1` that sets `CHEST_API`, `CHEST_TOKEN`, `CHEST_TOOL` (`tool` unless set) and answers members, groups, files, badges, notifications and erasure acknowledgments with a Chest's bounds, quotas and errors; a capability left out answers 403 (`members`, `files` and `notifications` 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 |
+| `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 +534,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
+seven published modules (`errors`, `member`, `members`, `database`, `files`,
+`notifications`, `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.

package/client/index.ts

@@ -1,9 +1,14 @@
-// The package root: every published module of the SDK (tool contract v2).
-// Each one is also its own subpath (@argentic/chest-sdk/member, /database,
-// /files, /errors), which pulls in nothing else. The files API is a namespace
-// here, as its names (get, put, list, delete, url) are too plain to stand
-// alone.
+// The package root: every published module a tool's code uses (tool contract
+// v2). Each one is also its own subpath (@argentic/chest-sdk/member,
+// /database, /files, /members, /notifications, /events, /errors), which
+// pulls in nothing else. The files, members, notifications and events APIs
+// are namespaces here, as their names (get, list, stat, move, notify,
+// verify…) are too plain to stand alone. @argentic/chest-sdk/testing is for a tool's tests only, and
+// is not here.
 export * from "./src/errors.js";
 export * from "./src/member.js";
 export * from "./src/database.js";
 export * as files from "./src/files.js";
+export * as members from "./src/members.js";
+export * as notifications from "./src/notifications.js";
+export * as events from "./src/events.js";

package/client/src/api.ts

@@ -0,0 +1,81 @@
+import { CapabilityNotGranted, ChestError, QuotaExceeded, RateLimited, TooLarge, Unavailable } from "./errors.js";
+
+// The Chest's API as a server tool reaches it, shared by the modules that
+// call it (files, members): CHEST_API is http://127.0.0.1:<port>, the tool's
+// launcher, which relays each request to the Chest — the container has no
+// network. A call reaches what is the tool's only: its instance is its
+// identity. Not a published module.
+
+const maxAnswer = 4 << 20;
+const deadline = 120000;
+
+// base is the Chest's API as the launcher gives it; without, the version holds
+// none of the capabilities that use it.
+function base(capability: string): string {
+  const value = process.env["CHEST_API"];
+  if (typeof value !== "string" || !/^http:\/\/127\.0\.0\.1:[1-9][0-9]{0,4}$/u.test(value) || Number(value.slice(17)) > 65535) throw new CapabilityNotGranted(capability);
+  return value;
+}
+
+// ask sends one request of a capability to the Chest; a failure to reach it
+// is Unavailable.
+export async function ask(capability: string, method: string, path: string, init: { body?: Uint8Array<ArrayBuffer> | string; type?: string } = {}): Promise<Response> {
+  const headers: Record<string, string> = {};
+  if (init.type !== undefined) headers["Content-Type"] = init.type;
+  const url = base(capability) + path;
+  try {
+    return await fetch(url, { method, headers, ...(init.body !== undefined ? { body: init.body } : {}), redirect: "error", signal: AbortSignal.timeout(deadline) });
+  } catch {
+    throw new Unavailable();
+  }
+}
+
+// read takes a body of limit bytes at most; beyond, or cut, the answer is not
+// the Chest's.
+export async function read(response: Response, limit: number): Promise<Uint8Array> {
+  const declared = Number(response.headers.get("content-length") ?? "0");
+  if (declared > limit) throw new Unavailable();
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  try {
+    for await (const chunk of response.body ?? []) {
+      size += chunk.byteLength;
+      if (size > limit) throw new Unavailable();
+      chunks.push(chunk);
+    }
+  } catch {
+    throw new Unavailable();
+  }
+  const all = new Uint8Array(size);
+  let at = 0;
+  for (const chunk of chunks) {
+    all.set(chunk, at);
+    at += chunk.byteLength;
+  }
+  return all;
+}
+
+// json reads an answer of the Chest as JSON; anything else is Unavailable.
+export async function json(response: Response): Promise<unknown> {
+  try {
+    return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(await read(response, maxAnswer)));
+  } catch {
+    throw new Unavailable();
+  }
+}
+
+// refusal turns an answer that is not a success into what the tool tests.
+export async function refusal(response: Response, capability: string): Promise<ChestError> {
+  let code = "refused";
+  try {
+    const given = ((await json(response)) as { error?: unknown } | null)?.error;
+    if (typeof given === "string" && /^[a-z_]{1,40}$/u.test(given)) code = given;
+  } catch {
+    // The code stays "refused".
+  }
+  if (response.status === 403) return new CapabilityNotGranted(capability);
+  if (response.status === 413) return new TooLarge();
+  if (response.status === 429) return code === "rate_limited" ? new RateLimited() : new QuotaExceeded();
+  if (response.status >= 500) return new Unavailable();
+  return new ChestError(code, response.status, `the Chest refused: ${code}`);
+}

package/client/src/errors.ts

@@ -20,15 +20,26 @@ export class CapabilityNotGranted extends ChestError {
   }
 }
 
-// What the tool keeps would go beyond what its Chest gives it: its total
-// (1 GiB of files) or its count (10,000 objects).
+// The call would take the tool beyond what its Chest gives it: for files,
+// their total (1 GiB unless its manifest asks more) or their count (10,000
+// objects); for notifications, 1,000 recipients an hour, 100 items per member
+// a day or 600 badge writes a minute. A refused call changes nothing.
 export class QuotaExceeded extends ChestError {
   constructor() {
     super("quota_exceeded", 429, "the Chest refused: the tool's quota would be exceeded");
   }
 }
 
-// One object is beyond the bound of one (32 MiB for a file).
+// The tool called the Chest's API more often than its bound (600 calls a
+// minute for its members): it waits before calling again.
+export class RateLimited extends ChestError {
+  constructor() {
+    super("rate_limited", 429, "the Chest refused: too many calls, wait a minute");
+  }
+}
+
+// One object is beyond the bound of one (for a file, the tool's largest
+// object: 32 MiB unless its manifest asks more, 512 MiB at most).
 export class TooLarge extends ChestError {
   constructor() {
     super("too_large", 413, "the Chest refused: the object is too large");