@samva/cli 0.15.0 → 0.17.0

package/AGENTS.md

@@ -21,9 +21,15 @@ response writes its body to stderr and exits `4` for 401 and 403, otherwise `1`.
 is no built-in filter.
 
 `samva api-keys` manages the organization's keys: `list`, `get`, `create`, `update`, `rotate`, and
-`revoke`. `create` takes `--name` and exactly one of `--full-access` or repeatable `--grant
-<resource>=read|write` (neither or both exits `2`), plus optional `--description` and `--expires-at`;
-mailbox and namespace scope go through `samva api`. The API refuses a key with more access than the
+`revoke`. `create` takes `--name` and either `--full-access` or restricted access built from repeatable
+`--grant <resource>=read|write` and mailbox access: repeatable `--mailbox-permission
+read|update|send|quarantine.read`, optionally narrowed to repeatable `--mailbox <id>` (default:
+every mailbox the owner reaches) with `--send-mode approval` (each send waits for a person other
+than the key). `--namespace <id>` confines a restricted key to one namespace. Passing no access, or both
+`--full-access` and restricted access, exits `2`, as does `--mailbox` or `--send-mode` without a
+`--mailbox-permission`. `--description` and `--expires-at` are optional. `update` renames a key,
+sets its description, or changes a mailbox key's `--send-mode` (a person signed in with `samva
+login`); every other part of a key's access is fixed at creation. The API refuses a key with more access than the
 caller holds. `create` and `rotate` return the secret once: `--json` carries `{apiKey, key,
 displayOnce, warning}`, so `samva api-keys create ... --json | jq -r .data.key` yields the key, and
 human mode prints it to stdout with the warning on stderr. `rotate` and `revoke` require
@@ -136,7 +142,10 @@ calls to you, rather than to an installation. Read what exists with `list`, `ver
 `run <id> <run-id>` (adds the handler's log lines); the list commands page with `--limit`,
 `--cursor`, and `--all --jsonl`.
 
-`samva mailboxes` reads and sends as a mailbox: `list` pages with `--limit`, `--cursor`, `--after`,
+`samva mailboxes` reads and sends as a mailbox. Every command except `list` and `create`
+takes the mailbox ID as its first argument and the message, action, or endpoint ID second,
+as in `read <mailbox-id> <message-id>` and `endpoints update <mailbox-id> <endpoint-id>`; `events`
+takes any number of mailbox IDs, or none for every mailbox the credential reads. `list` pages with `--limit`, `--cursor`, `--after`,
 and `--before`. `create --address <address> --name <name>` makes a mailbox with one email endpoint; the
 slug defaults to the address's local part, and a collision asks for `--slug` rather than suffixing.
 `get <id>` inspects a mailbox; `update <id> --data <JSON-or-@file>` changes
@@ -146,12 +155,19 @@ stops sending and receiving, and `resume <id>` resumes without backfilling mail
 paused. These mutations support `--dry-run`. `remove <id>` deletes a mailbox (`--yes` outside a terminal, `--dry-run` to
 preview), `threads` searches, `read` prints a message (human output marks the body as
 untrusted email), and `send` and `reply` take `--idempotency-key` so a retry cannot send twice.
+`create`, `endpoints add`, and `send` take `--channel email|whatsapp|sms` (default `email`); on a
+phone channel the address is a connected number in E.164 form, and `send` takes one `--to` number
+with `--text` or, on WhatsApp, an approved `--template <templateId>` with `--data`. `reply` answers a
+WhatsApp or SMS message on its thread; a bare `--text` reply reads the message first to learn its
+channel. Free-form WhatsApp text outside the customer's 24-hour window fails with
+`WhatsAppServiceWindowClosedError`; send a template. These commands call the API directly because the
+public SDK describes email only.
 Quarantine `list` pages the same way, bounded by `--after` and `--before` on when a message was
 held; `release` and `discard` take the held message's `id` and require a person signed in with
 `samva login`. Discard requires confirmation (`--yes` outside a terminal) and supports `--dry-run`.
-`actions list --mailbox <id>` filters by `--state` and pages with `--limit`, `--cursor`, and
-`--all --jsonl`. `actions approve <action-id> --mailbox <id>` and `actions deny <action-id>
---mailbox <id> [--reason <text>]` require a person different from the proposer, confirmation
+`actions list <mailbox-id>` filters by `--state` and pages with `--limit`, `--cursor`, and
+`--all --jsonl`. `actions approve <mailbox-id> <action-id>` and `actions deny <mailbox-id>
+<action-id> [--reason <text>]` require a person different from the proposer, confirmation
 (`--yes` outside a terminal), and offer `--dry-run`.
 Human mailbox and extension results retain the same facts as JSON: mailbox endpoints (channel, address,
 sender name, default), thread state and activity, message bodies, attachments, authentication and actor,