@capxul/cli 4.20.0-beta.17 → 4.20.0-beta.19

package/README.md

@@ -53,6 +53,29 @@ one final version 1 result on stdout. Account setup reports public signer states
 Activity shows that the CLI is waiting. It does not prove settlement or a healthy
 connection. A deadline stops observation; it does not cancel a submitted operation.
 
+## Status overview
+
+```sh
+capxul status
+capxul status --email EMAIL --json
+capxul status --org ORGANIZATION_ID
+```
+
+`status` reads the current personal Account unless one explicit Organization
+is selected with `--org`. It shows the saved session identity, selected actor
+profile and readiness, separate asset balances, received and issued requests,
+pending or active Payments, and five recent Activity rows. It gives scoped
+commands to inspect requests and Activity. A saved Organization default does
+not change the overview's personal scope.
+
+Each source read retains its own state. An unavailable balance or Inbox is
+not an empty balance or Inbox. Indexed Activity fallback is marked incomplete.
+JSON returns `state: "partial"` when a read fails or Activity is incomplete.
+Document counts include known references from available request and Payment
+reads. Activity detail can have additional documents. The overview does not
+render or download PDFs and does not prepare or submit Payments. Showing an
+existing scheduled or streaming Payment does not add recurring billing.
+
 ## Personal Payments
 
 ```sh
@@ -121,6 +144,129 @@ refuses a missing or unavailable reference. Annotation accepts only `reference`,
 writes require preview and confirmation. Scripted writes require `--confirm`.
 In a terminal, omit required fields for guided flags and annotation input.
 
+## Issued requests and received Inbox
+
+```sh
+capxul request list
+capxul request issue --input invoice.json --confirm
+capxul request get --request-id REQUEST_ID
+capxul request cancel --request-id REQUEST_ID --confirm
+capxul inbox list
+capxul inbox get --request-id REQUEST_ID
+capxul inbox pay --request-id REQUEST_ID --confirm
+capxul inbox decline --request-id REQUEST_ID --confirm
+capxul org request list --org ORGANIZATION_ID
+capxul org request issue --org ORGANIZATION_ID --input invoice.json --confirm
+capxul org request get --org ORGANIZATION_ID --request-id REQUEST_ID
+capxul org request cancel --org ORGANIZATION_ID --request-id REQUEST_ID --confirm
+capxul org inbox list --org ORGANIZATION_ID
+capxul org inbox get --org ORGANIZATION_ID --request-id REQUEST_ID
+capxul org inbox pay --org ORGANIZATION_ID --request-id REQUEST_ID --permission-id PERMISSION_ID --confirm
+capxul org inbox decline --org ORGANIZATION_ID --request-id REQUEST_ID --confirm
+```
+
+`request` reads the selected actor's issued Invoice and payment requests.
+`inbox` reads payment requests addressed to that actor. Organization reads
+require one explicit Organization ID. Add `--email EMAIL` to select a saved
+session. No signer is required for these reads.
+
+For human reads, start with `capxul request --help` or `capxul inbox --help`.
+Run `request list` for requests you issued. Run `inbox list` for requests you
+received. Copy the full request ID from the list into the matching `get` command.
+In a terminal, omit required fields to start guided input. Ctrl+C or Ctrl+D
+cancels with exit 130. The wizard can ask about optional email selection before
+required fields. Provide `--email EMAIL` when you need one saved session.
+
+For agent reads, supply all required flags and add `--json`. Capture stdout,
+stderr, and the process exit code separately. A refusal is still a version 1
+result on stdout. Inspect `outcome` and `error.code`; do not infer success from
+valid JSON. Missing required input exits 2. A missing authenticated session exits 3. Noninteractive human refusals use stderr. These runs do not prompt.
+
+A missing `--org` refuses an Organization request or Inbox read before session
+restoration. Supply that selector on every Organization command. Do not assume
+that `org use` selects request or Inbox scope.
+
+The [installed beta18 audit](../../docs/planning/checkout-cli/request-read-contract.md#installed-beta18-local-audit-c06)
+records local help, refusal, and cancellation checks. Authenticated request
+reads, document output, issuance, and payment remain separate journey checks.
+
+Human output shows request ID, reference, amount, status, counterparty
+reference, and document references. An unpaid Invoice can have a document
+before any Payment exists. The document guidance preserves the selected
+session. Run that explicit command to save a PDF. Request and Inbox reads do
+not render or download PDFs. JSON output preserves scope, direction, and the
+SDK item or list. Unavailable reads remain failures, not empty lists.
+
+Cancel changes an issued request. Decline changes a received request. Both
+commands read the exact request in the selected scope before the write.
+Terminal writes show a preview and ask for confirmation. Scripted writes
+require `--confirm` before session restoration. A lost write reply gives an
+exact readback command in the same scope and session. It never repeats the
+write. These commands start no signer and move no funds.
+
+Issue accepts an Invoice request JSON object from `--input FILE` or `--input -`.
+It saves the issued Invoice PDF in the common document directory by default.
+Human and JSON output include `checkoutUrl` for an Invoice instruction with a link token.
+Memo requests do not receive an Invoice checkout URL.
+The PDF includes the checkout link from the authorized backend render context.
+For a custom deployment, set `CAPXUL_CHECKOUT_FRONTEND_ORIGIN` in both the CLI
+and backend environments. Use the same frontend origin for both.
+Offer create, get, list, revise, and deactivate output also include `checkoutUrl`.
+The checkout page reads current terms and status when the link opens.
+Use `--output-dir DIRECTORY` to change that location. A PDF failure retains the
+issued request and its document references. Do not issue it again to retry PDF
+output; use the printed document render command.
+
+```json
+{
+  "payer": { "kind": "email", "email": "bob@example.com" },
+  "amount": { "asset": "<admitted asset ID>", "value": "9" },
+  "invoice": {
+    "kind": "invoice",
+    "invoiceNumber": "INV-002",
+    "payerRef": "Bob",
+    "payeeRef": "Alice",
+    "dueAt": 1900000000000,
+    "note": "Thank you",
+    "discountMinor": "1000000",
+    "lineItems": [{ "description": "Consulting", "quantity": 1, "unitMinor": "10000000" }]
+  }
+}
+```
+
+Supply your Invoice number. The request reference defaults to that number;
+optional `reference` changes the request reference only. `dueAt` uses epoch
+milliseconds, as the shared Invoice document and frontend do. Set it to zero
+for no due date. Optional `expiresAt` also uses epoch milliseconds. `discountMinor` and
+`unitMinor` use the asset's exact minor units. The example is 10 USDC less
+1 USDC for a six-decimal USDC asset. The backend checks the Invoice total,
+registered payer, and issuer authority before creation. Optional `memo` is a
+request memo; `invoice.note` is the document note. Unknown fields refuse.
+
+Earlier CLI guidance incorrectly named Unix seconds for `dueAt`. Convert those
+values to milliseconds for new drafts. Rendering does not change the dates in
+an issued document. Inspect an incorrect Invoice before cancelling it and
+issuing a corrected request.
+
+A lost issuance reply provides issued-list readback in the same scope and
+session. Issuance has no automatic resend.
+
+Inbox pay reads and confirms exact backend-owned request terms. It uses the existing
+CLI signer and the SDK fulfillment API. Organization payment requires the
+selected Permission; the backend checks Budget and spending authority. The
+command publishes prepared Payment IDs before signing. A submitted Payment
+is not a settled Payment. Use the printed get/wait commands to inspect its state.
+Returned documents use the same default PDF directory.
+
+A lost reply or timeout gives exact readback in the same session and scope.
+Pay refuses an already prepared Invoice unless you explicitly use `--resume`
+after readback. Resumption must retain its linked Payment ID and original
+Invoice terms. It does not create another request or Payment. Use
+`--timeout-seconds N` to change the bounded signing wait (default 120).
+An Invoice retains its issued instruction. A generic request uses a deterministic
+Memo instruction. Reading terms creates no Payment or document. Fulfillment
+checks those terms again and stores the Memo with the original request birth.
+
 ## Payment documents
 
 ```sh
@@ -561,14 +707,15 @@ Ctrl-C stops local work at exit 130. Neither stop writes a backend failure.
 
 ## Configuration
 
-| Variable                       | Use                                                                                                          |
-| ------------------------------ | ------------------------------------------------------------------------------------------------------------ |
-| `CAPXUL_CLI_HOME`              | Directory for global CLI settings. Defaults to `$XDG_CONFIG_HOME/capxul/cli`, or `$HOME/.config/capxul/cli`. |
-| `CAPXUL_PUBLISHABLE_KEY`       | Optional developer override for the bundled first-party staging key.                                         |
-| `CAPXUL_BOOTSTRAP_URL`         | Bootstrap origin. Defaults to `https://api.staging.capxul.com`. Convex Cloud origins are rejected.           |
-| `CAPXUL_POSTHOG_HOST`          | Optional development override for the built-in public PostHog ingestion origin.                              |
-| `CAPXUL_POSTHOG_PROJECT_TOKEN` | Optional development override for the built-in public project ingestion token.                               |
-| `CAPXUL_TELEMETRY_DISABLED`    | Set to `true` to disable remote observation regardless of the saved preference.                              |
+| Variable                          | Use                                                                                                                                                                                   |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `CAPXUL_CLI_HOME`                 | Directory for global CLI settings. Defaults to `$XDG_CONFIG_HOME/capxul/cli`, or `$HOME/.config/capxul/cli`.                                                                          |
+| `CAPXUL_PUBLISHABLE_KEY`          | Optional developer override for the bundled first-party staging key.                                                                                                                  |
+| `CAPXUL_BOOTSTRAP_URL`            | Bootstrap origin. Defaults to `https://api.staging.capxul.com`. Convex Cloud origins are rejected.                                                                                    |
+| `CAPXUL_CHECKOUT_FRONTEND_ORIGIN` | Checkout frontend origin. Staging uses `https://app.staging.capxul.com`. Devnet at `http://127.0.0.1:3211` uses `http://127.0.0.1:3002`. Custom bootstrap origins require this value. |
+| `CAPXUL_POSTHOG_HOST`             | Optional development override for the built-in public PostHog ingestion origin.                                                                                                       |
+| `CAPXUL_POSTHOG_PROJECT_TOKEN`    | Optional development override for the built-in public project ingestion token.                                                                                                        |
+| `CAPXUL_TELEMETRY_DISABLED`       | Set to `true` to disable remote observation regardless of the saved preference.                                                                                                       |
 
 The published CLI includes the verified first-party staging application key and
 Capxul-owned public ingestion configuration. You do not need key or PostHog
@@ -852,3 +999,43 @@ the same Party, session and scope. The contact's history remains available.
 `contact unhide` uses the same scoped selector, including hidden contacts, when
 a terminal omits `--entry-id`. It confirms the change and shows the visible
 contact. Scripts provide the exact Party ID and `--confirm`.
+
+## Fixed offers
+
+Manage fixed service offers in your personal Account or an explicit Organization.
+These commands do not sign payments or create checkout purchases.
+
+```sh
+capxul offer create --input offer.json --request-key consulting-001 --confirm
+capxul offer list
+capxul offer get --offer-id OFFER_ID
+capxul offer revise --offer-id OFFER_ID --expected-revision 1 --input offer.json --confirm
+capxul offer deactivate --offer-id OFFER_ID --expected-revision 2 --confirm
+capxul org offer list --org ORG_ID
+```
+
+Use `org offer` and `--org ORG_ID` for each Organization command. Use `--email`
+to select a saved session. Scripts must supply `--confirm` for each write.
+A terminal shows the proposed change and asks for confirmation. Use `--json`
+for structured output. Lists and reads create no PDF.
+
+The input file contains the complete offer terms. Use `--input -` to read stdin.
+The input limit is 64 KiB. Supply an admitted Base Sepolia asset ID from the
+existing asset catalog. Amounts use exact decimal strings. Quantity limits use
+positive whole numbers.
+
+```json
+{
+  "title": "Consulting",
+  "description": "One hour of consulting",
+  "unitLabel": "hour",
+  "unitAmount": { "asset": "ASSET_ID", "value": "12" },
+  "quantity": { "min": 1, "max": 8 }
+}
+```
+
+Creation requires an explicit replay key. Keep the key and identical terms when
+recovering an uncertain result. Read the offer list before another write. Revision
+and deactivation require the revision you observed. A conflict requires a fresh
+read. The CLI does not retry a write automatically. Checkout links are not emitted
+until the checkout route works.