@samva/cli 0.9.0 → 0.10.0

package/AGENTS.md

@@ -27,6 +27,13 @@ a template written in a format the compiler rejects. Templates live in `template
 `emails/`; a template is a `.tsx` file that default-exports `defineTemplate`, and the compiler reads
 it without running it.
 
+`samva email send --attach <path>` (repeatable) attaches local files; the filename is the basename and
+the content type comes from the extension (`application/octet-stream` when unknown). The CLI reads
+and budget-checks every file before any request (at most 10 files, 25 MiB each and in total) and
+exits `2` naming the path or limit. Past the 4 MiB inline limit, the largest files upload through
+`/v1/media` first and travel by `mediaId`; the send's retries reuse them, and rerunning the command
+uploads again. `--dry-run` lists each attachment and uploads nothing.
+
 `--publication-id` and `--input-contract-id` on `email send`, `scheduled-messages create`, and
 `campaigns create`/`update` choose which publication a template send renders: one exact publication,
 or the newest publication that still validates input identically. They are mutually exclusive and
@@ -90,18 +97,35 @@ Standalone callers supply their own resolver. The README owns resolution order a
 `dev` handles mailbox events locally, `publish` records an immutable version, and `install` grants
 that version scoped mailbox permissions. Hosted extensions run on Samva; webhook extensions use
 the installation credentials returned once at install. Publishing and installation management
-require a person signed in with `samva login`. Local development with that login attributes tool
+require a person signed in with `samva login`. `upgrade <installation-id>` selects the latest
+published version, or `--version <version-or-id>` selects one. `--dry-run` asks the API for the
+from/to versions and added/removed grants without changing the installation; the installation
+shown in a preview is its current state. Applying requires confirmation (`--yes` outside a
+terminal) and an exact, repeatable `--accept-permissions` acknowledgement for each added grant,
+such as `permission:send` or `event:mailbox.message.sent`. Local development with that login attributes tool
 calls to you, rather than to an installation. Read what exists with `list`, `versions <name>`,
 `version <name> <version>`, `installations`, `installation <id>`, `runs <id>` (outcomes only), and
 `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`,
-and `--before`, `threads` searches, `read` prints a message (human output marks the body as
+and `--before`. `get <id>` inspects a mailbox; `update <id> --data <JSON-or-@file>` changes
+`displayName`, `defaultFrom`, or `metadata` (merges by key, `null` deletes a key). `pause <id>`
+stops sending and receiving, and `resume <id>` resumes without backfilling mail received while
+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.
 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`. `samva mailboxes events` reads the SDK event stream with reconnects off and prints
+`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
+(`--yes` outside a terminal), and offer `--dry-run`.
+Human mailbox and extension results retain the same facts as JSON: mailbox addresses and sending
+identity, thread state and activity, message bodies, attachments, authentication and actor,
+receipt waits and skipped recipients, held-mail results, and installation/run details.
+`samva mailboxes events` reads the SDK event stream with reconnects off and prints
 one record per event, `{cursor, id, event}` (`--jsonl` wraps each in a result envelope, `--quiet`
 prints none, `--json` is refused). A drop or refusal ends the command with the server's `_tag` as
 the error `reason`, its `status` and `details`, and a `Try:` line; the last handled cursor, which