@samva/cli 0.7.1 → 0.9.0

package/AGENTS.md

@@ -2,13 +2,19 @@
 
 Use `samva --help` and `samva <command> --help` as the command contract. For automation, prefer
 `SAMVA_API_KEY`, `--json` for one bounded result, and `--jsonl` with `--all` for streamed lists.
-Machine-readable results go to stdout; warnings and typed errors go to stderr.
+Machine-readable results go to stdout; warnings and typed errors go to stderr. Error envelopes carry
+`schemaVersion`, `type`, `command`, `reason`, `message`, and optional `next`. For API failures,
+`reason` is the API `_tag`, `status` is the HTTP status, and `details` preserves the public error
+fields. Follow `next` and fix `details.fields` before retrying. API 401 and 403 exit with code `4`;
+other operational failures exit with code `1`. Human mode prints the same message and recovery step.
 
 `samva templates export --out <dir>` renders every local template's fixtures to HTML
 and text with the asset manifest, needing a Samva credential only to resolve a live `samva:brand`; `--asset-base <origin>` is for an
 export that will be delivered, which cannot carry a relative reference.
 `samva templates check --watch` is the continuous authoring gate. Human mode prints observations;
 machine watch output uses `--jsonl`. `--json` remains one-shot.
+`samva mailboxes events` is a stream: human mode prints one raw record per line, `--jsonl` one result
+envelope per event, `--quiet` nothing, and `--json` is refused (exit 2) with a pointer to `--jsonl`.
 
 The developer loop for a template project is `samva templates dev` (the local visual editor, no
 `vite.config.ts`), `check` (type-check, compile, and render every fixture), `render <template>
@@ -79,3 +85,26 @@ artifact directly.
 Keep Samva brand resolution in the CLI and pass `samvaBrandPlugin` to the project's authoring
 toolchain, so standalone `@samva/vite` stays independent of Samva authentication and storage.
 Standalone callers supply their own resolver. The README owns resolution order and configuration.
+
+`samva extensions` is the mailbox extension developer loop: `init` scaffolds an authoring project,
+`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
+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
+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
+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.

package/README.md

@@ -360,12 +360,14 @@ samva --quiet profile use acme
 `--json` writes one bounded, versioned result envelope to stdout:
 `{schemaVersion:1,type:"result",command,data}`. For resource lists, `--jsonl` writes one flat,
 independently parseable outer result envelope per resource. Errors use the corresponding
-`{schemaVersion:1,type:"error",command,reason,message,next?}` envelope on stderr and exit
-non-zero. `--json`, `--jsonl`, and `--quiet` are mutually exclusive; assignment forms such as
+`{schemaVersion:1,type:"error",command,reason,message,status?,details?,next?}` envelope on stderr and exit
+non-zero. API errors use their `_tag` as `reason`, their HTTP status as `status`, and their
+public fields as `details`. Fix `details.fields` and follow `next` before retrying. API 401 and 403
+exit with code `4`. Human mode prints the same message and a `Try:` line. `--json`, `--jsonl`, and `--quiet` are mutually exclusive; assignment forms such as
 `--json=true` are usage errors. `--quiet` suppresses successful output only. In machine modes,
 stdout contains only result data; warnings and errors go to stderr.
 
-Lists are paginated by default. Use `--page` and `--limit` for a bounded page. `--all` requires
+Lists are paginated by default. Use `--limit` for a bounded page and `--cursor` with the printed `nextCursor` for the next one. `--all` requires
 `--jsonl`, so an automated traversal stays streamable rather than producing an unbounded JSON
 document. `--all` changes traversal only: bounded and unbounded JSONL records have the same outer
 envelope, with the resource itself in `data`. Empty lists emit no records.
@@ -418,13 +420,20 @@ review decision, sendable domain and verified sender counts, and domain-verifica
 `readyToSend` is true when a production send would be admitted and at least one domain or sender can
 carry it. It is read-only and does not inspect receiving configuration, check DNS itself, send an
 email, or replay fixtures.
-Use `samva email receiving status <domain-id>` to read a domain's receiving prerequisite status.
-`samva email receiving enable <domain-id> ...` acts by default; its `--dry-run` is offline and does
-not require credentials or call the API. Each check is `passed`, `failed`, or
+Each check is `passed`, `failed`, or
 `unavailable`. A `failed` check carries the underlying error detail; `unavailable`, such as no
 sending domain yet or a review in progress, is informational; a rejected review fails. The command always prints the full report, then
 exits `1` if any check failed and `0` otherwise. The `--json` result's `data` adds an aggregate
 `ok` boolean, and human output marks checks with `✓`, `!`, and `✗` respectively.
 
+Use `samva email receiving status <domain-id>` to read a domain's receiving prerequisites in
+order: sending verified, a destination, receiving enabled, and the inbound MX, which it looks up
+live and names when mail is routed elsewhere.
+`samva email receiving enable <domain-id> --domain <name> --catch-all [--endpoint <webhook-id>]`
+routes every address on a verified domain. A catch-all needs a destination, either `--endpoint` or
+an active forwarding rule that covers the domain; mail that matches neither is rejected. Pass
+`--address` for exact recipients instead. The command acts by default; its `--dry-run` is offline
+and does not require credentials or call the API.
+
 A command that needs a subcommand, such as a bare `samva` or a group like `samva email`, prints its
 help to stdout and exits `2`, so a script never mistakes a missing subcommand for success.