@samva/cli 0.9.0 → 0.11.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,21 +97,43 @@ 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
 `--cursor` resumes from, goes to stderr in human mode and into `details.lastCursor` otherwise.
 `samva extensions dev` follows the same output modes. 401 and 403 exit 4. An expired
 cursor exits 1 and the next step is to start without `--cursor`. Ctrl+C exits cleanly.
+
+`samva subscriptions subscribe` requests one email confirmation with `--email`,
+`--contact-group-id`, and `--from`. Optional flags record signup context, select a template, or
+name the unsubscribe group whose opt-out confirmation clears. A successful receipt means the
+request was accepted; group membership waits for recipient confirmation on the hosted page.

package/README.md

@@ -339,6 +339,25 @@ samva campaigns runs recipients <campaign-id> <run-id> --status failed
 scheduled message. Campaign definitions freeze after their first run. Cancelling a scheduled
 message or campaign run requires confirmation, and dispatch already in progress may still finish.
 
+## Contacts
+
+```sh
+samva contacts list --search ada --limit 25
+samva contacts list --fields plan,score --json
+samva contacts list --custom-field plan --custom-field-value '"pro"' --json
+samva contacts list --all --jsonl
+samva contacts get contact_7q2xk9mvt4znw8rh --json
+```
+
+`list` returns a bounded page with a `nextCursor`; pass it as `--cursor` to resume. `--fields`
+selects the custom-field keys included in each summary. Exact custom-field filtering requires
+both `--custom-field` and `--custom-field-value`, with the value encoded as a JSON scalar
+(for example `'"pro"'`, `42`, `true`, or `null`). `--search`, `--status`, `--after`, and `--before`
+combine with that filter. `get` returns the contact's identities, profile, custom fields, and metadata.
+If a list page fails, machine-readable stderr includes `details.cursor`. Retry with that
+`--cursor` and the same filters to resume after the contacts already printed; a null cursor means
+the first page failed, so retry without `--cursor`.
+
 ## Automation contract
 
 Use `--dry-run` on supported mutations to validate input and preview the intended request. `email
@@ -402,7 +421,7 @@ samva email send --help
 ```
 
 Released top-level commands are `login`, `logout`, `org`, `email`, `messages`, `campaigns`,
-`scheduled-messages`, `templates`, `brands`, `webhooks`, `profile`, and `help`. Use `samva <command> --help`
+`contacts`, `scheduled-messages`, `templates`, `brands`, `webhooks`, `profile`, and `help`. Use `samva <command> --help`
 for flags and runnable examples.
 
 Test a configured webhook against its real endpoint with an optional JSON payload. `--data` accepts