@agenzo/merchant-cli 0.1.1

package/README.md

@@ -0,0 +1,180 @@
+# @agenzo/merchant-cli
+
+[![npm version](https://img.shields.io/npm/v/@agenzo/merchant-cli)](https://www.npmjs.com/package/@agenzo/merchant-cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
+
+CLI tool for AI Agents to order rides and query merchant services. Ships with a
+structured [SKILL.md](SKILL.md) so AI Agents can run the full ride flow with zero
+extra setup.
+
+[Install](#installation) · [AI Agent Skill](#ai-agent-skill) · [Quick Start](#quick-start) · [Commands](#commands) · [Auth](#authentication)
+
+## Installation
+
+```bash
+npm install -g @agenzo/merchant-cli
+```
+
+**Requirements**: Node.js 18+
+
+The package installs a single binary, `agenzo-merchant-cli`:
+
+```bash
+agenzo-merchant-cli --help
+agenzo-merchant-cli --version
+```
+
+## AI Agent Skill
+
+This CLI ships with a structured [SKILL.md](SKILL.md) that AI Agents can load to
+understand capability discovery, the `quote → book → get → [cancel]` ride flow,
+command parameters, and error recovery. Include `SKILL.md` in the agent's context
+or tool definition.
+
+## Quick Start
+
+```bash
+# 1. (Optional) point at a non-default host
+agenzo-merchant-cli config set-host https://agent.everonet.com
+
+# 2. Discover available services
+agenzo-merchant-cli services list --api-key sk_xxx
+
+# 3. Get fare quotes for a trip
+agenzo-merchant-cli ride quote --api-key sk_xxx \
+  --pickup-lat 1.3 --pickup-lng 103.8 --pickup-name "Changi" \
+  --dropoff-lat 1.29 --dropoff-lng 103.85 --dropoff-name "Marina Bay"
+
+# 4. Book against a returned quote (write op → idempotency key required)
+agenzo-merchant-cli --yes ride book --api-key sk_xxx \
+  --quote-id qt_123 --vehicle-class standard \
+  --passenger-name "Ada" --idempotency-key idem_001
+
+# 5. Poll the order until a terminal status
+agenzo-merchant-cli ride get ord_123 --api-key sk_xxx
+
+# 6. Cancel if needed (write op → idempotency key required)
+agenzo-merchant-cli --yes ride cancel ord_123 --api-key sk_xxx --idempotency-key idem_002
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `config set-host <url>` | Set the API host (persisted locally) |
+| `config reset-host` | Reset the API host to the default |
+| `config show` | Show the current configuration |
+| `services list` | List available merchant services |
+| `services get <service-id>` | Retrieve a single service by id |
+| `ride quote` | Request fare quotes between two points |
+| `ride book` | Book a ride against a returned quote |
+| `ride get <order-id>` | Retrieve a single ride order |
+| `ride cancel <order-id>` | Cancel a ride order (may incur a fee) |
+| `ride list-orders` | List ride orders (paginated, optional status filter) |
+
+### Command Reference
+
+```bash
+# Configuration (local only, no network)
+agenzo-merchant-cli config set-host https://agent.everonet.com
+agenzo-merchant-cli config reset-host
+agenzo-merchant-cli config show
+
+# Services registry
+agenzo-merchant-cli services list --api-key sk_xxx
+agenzo-merchant-cli services get svc_001 --api-key sk_xxx
+
+# Ride flow
+agenzo-merchant-cli ride quote --api-key sk_xxx \
+  --pickup-lat <lat> --pickup-lng <lng> --pickup-name <name> \
+  --dropoff-lat <lat> --dropoff-lng <lng> --dropoff-name <name> [--service-id <id>]
+agenzo-merchant-cli ride book --api-key sk_xxx \
+  --quote-id <id> --vehicle-class <class> --passenger-name <name> \
+  [--passenger-phone <phone>] [--passenger-email <email>] --idempotency-key <key>
+agenzo-merchant-cli ride get <order-id> --api-key sk_xxx
+agenzo-merchant-cli ride cancel <order-id> --api-key sk_xxx --idempotency-key <key>
+agenzo-merchant-cli ride list-orders --api-key sk_xxx [--status <status>] [--page <n>] [--page-size <n>]
+```
+
+## Global Flags
+
+| Flag | Description |
+|------|-------------|
+| `--format <json\|table>` | Output format. Defaults to `json`; pass `--format table` for a human-readable table. |
+| `--api-key <key>` | API key for runtime requests, sent as the `X-API-Key` header. |
+| `--idempotency-key <key>` | Caller-supplied idempotency key for write operations (`ride book`, `ride cancel`). |
+| `--yes` | Skip confirmation/interactive prompts (for automation / AI Agents). |
+
+### Output format
+
+All commands emit JSON by default, which is ideal for scripting and AI Agents.
+Add `--format table` for a readable summary instead:
+
+```bash
+agenzo-merchant-cli ride list-orders --api-key sk_xxx --format table
+```
+
+### Progress feedback
+
+Ride commands make a network call, so while one is in flight the CLI shows a
+spinner (e.g. `⠋ Fetching quotes...`) so you can tell it is working rather than
+hung. This feedback is written to **stderr**, never stdout — so piping or
+redirecting stdout still yields a clean payload:
+
+```bash
+# stdout stays pure JSON; the spinner (on stderr) does not leak in
+agenzo-merchant-cli ride quote --api-key sk_xxx ... | jq '.vehicle_classes'
+```
+
+The spinner animates only when stderr is an interactive terminal (TTY). When
+output is piped, redirected, or run in CI / by an agent, the animation is
+suppressed so no control characters end up in logs. Local commands (`config`,
+`services`) return instantly and show no spinner.
+
+### Idempotency
+
+Write operations (`ride book`, `ride cancel`) require a caller-supplied
+`--idempotency-key`. The CLI **never** auto-generates one:
+
+- Without `--yes`, the CLI prompts for the key interactively.
+- With `--yes`, a missing key is a hard error (`PARAM_IDEMPOTENCY_KEY_REQUIRED`).
+
+The key must be 1–128 characters from `[A-Za-z0-9_-]` and is sent as the
+`Idempotency-Key` header — never in the request body.
+
+## Authentication
+
+Runtime commands (`services`, `ride`) require `--api-key`. The value is sent on
+every request as the `X-API-Key` header. `config` commands are local-only and
+need no API key.
+
+## Host configuration
+
+The default API host is `https://agent.everonet.com`. Override it with
+`config set-host` (persisted at `~/.agenzo-merchant-cli/config.json`) and revert
+with `config reset-host`:
+
+```bash
+agenzo-merchant-cli config set-host http://localhost:8000   # local dev
+agenzo-merchant-cli config reset-host                        # back to https://agent.everonet.com
+agenzo-merchant-cli config show
+```
+
+## Amounts
+
+Monetary amounts are **decimals in the currency's standard unit** (e.g. `12.50`
+USD), not minor units / cents.
+
+## Development
+
+```bash
+npm install
+npm run build      # tsup production build
+npm run dev        # watch build
+npm run lint       # eslint
+```
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,132 @@
+# @agenzo/merchant-cli — AI Agent Skill
+
+CLI for ordering rides and querying merchant services. This skill tells an AI
+Agent how to discover capabilities and drive the full ride lifecycle.
+
+## Setup
+
+- Binary: `agenzo-merchant-cli`
+- Auth: every runtime command needs `--api-key <key>` (sent as `X-API-Key`).
+- Output: JSON by default (machine-readable). Add `--format table` only for
+  human display.
+- Streams: parse **stdout** for results. Progress spinners and status lines go
+  to **stderr** and never contaminate stdout — read only stdout as data. (The
+  spinner is auto-suppressed when stderr is not a TTY, e.g. agent-invoked.)
+- Automation: pass `--yes` to skip interactive prompts. In `--yes` mode every
+  required value must be supplied via flags.
+- Host: defaults to `https://agent.everonet.com`. Change with
+  `config set-host <url>`; reset with `config reset-host`.
+- **Amounts are decimals in the currency's standard unit** (e.g. `12.50` USD),
+  never minor units / cents.
+
+## Capability discovery
+
+Before quoting, discover which services exist and are enabled:
+
+```bash
+agenzo-merchant-cli services list --api-key sk_xxx
+agenzo-merchant-cli services get <service-id> --api-key sk_xxx
+```
+
+- `services list` → `{ services: Service[] }`. Each `Service` has
+  `service_id`, `name`, `enabled`.
+- `services get <service-id>` → a single `Service`. A missing/unknown id raises
+  `SERVICE_NOT_FOUND`.
+- Use a discovered `service_id` as the optional `--service-id` on `ride quote`.
+
+## Ride workflow (closed loop)
+
+The ride lifecycle is `quote → book → get (poll) → [cancel]`.
+
+```
+quote ──► book ──► get (poll until terminal) ──► [cancel if still active]
+```
+
+### 1. quote
+
+Request fare quotes for a trip between two points.
+
+```bash
+agenzo-merchant-cli ride quote --api-key sk_xxx \
+  --pickup-lat <num> --pickup-lng <num> --pickup-name <str> \
+  --dropoff-lat <num> --dropoff-lng <num> --dropoff-name <str> \
+  [--service-id <id>]
+```
+
+Returns `{ vehicle_classes: VehicleClass[] }`. Each class carries
+`vehicle_class`, `passenger_capacity`, `luggage_capacity`, and a `price` with
+`amount`, `currency`, and a `quote_id`. **Carry `quote_id` and the chosen
+`vehicle_class` into `book`.** Quotes expire — book promptly.
+
+### 2. book (write — idempotency key required)
+
+```bash
+agenzo-merchant-cli --yes ride book --api-key sk_xxx \
+  --quote-id <id> --vehicle-class <class> --passenger-name <name> \
+  [--passenger-phone <phone>] [--passenger-email <email>] \
+  --idempotency-key <key>
+```
+
+Returns an `Order` with `order_id` and an initial `status`. Reuse the **same**
+`--idempotency-key` if you retry the same booking, so a network retry never
+creates a duplicate order.
+
+### 3. get (poll)
+
+```bash
+agenzo-merchant-cli ride get <order-id> --api-key sk_xxx
+```
+
+Returns an `Order` with `status`. Poll periodically until a terminal status.
+
+- Active (keep polling): `Pending`, `Accepted`, `On my way`, `Waiting`, `On board`
+- Terminal (stop): `At destination`, `Rejected`, `Cancelled`,
+  `Customer no show`, `Driver no show`
+
+Status strings are case-sensitive — match the server casing exactly.
+
+### 4. cancel (optional, write — idempotency key required)
+
+```bash
+agenzo-merchant-cli --yes ride cancel <order-id> --api-key sk_xxx \
+  --idempotency-key <key>
+```
+
+Only while the order is still active. Returns
+`{ cancellation: { cancellation_fee, reversal_amount, currency } }` — a
+cancellation may incur a fee.
+
+### Listing
+
+```bash
+agenzo-merchant-cli ride list-orders --api-key sk_xxx \
+  [--status <status>] [--page <n>] [--page-size <n>]
+```
+
+Returns `{ orders, total, page, page_size }` (default `page` 1, `page-size` 20).
+
+## Idempotency rule
+
+All write operations (`ride book`, `ride cancel`) require a caller-supplied
+`--idempotency-key`. The CLI never auto-generates one.
+
+- Key format: 1–128 chars from `[A-Za-z0-9_-]`, sent as the `Idempotency-Key`
+  header (not in the body).
+- With `--yes` and no key → hard error `PARAM_IDEMPOTENCY_KEY_REQUIRED`.
+- Without `--yes` → the CLI prompts for the key.
+
+## Error codes & recovery
+
+Errors are emitted with a SCREAMING_SNAKE_CASE `code`. Common ones:
+
+| Code | Meaning | Recovery |
+|------|---------|----------|
+| `QUOTE_EXPIRED` | The `quote_id` is no longer valid | Re-run `ride quote` and book with the fresh `quote_id`. |
+| `VEHICLE_UNAVAILABLE` | The chosen `vehicle_class` is unavailable | Re-quote and pick another `vehicle_class` from `vehicle_classes`. |
+| `BOOKING_FAILED` | Booking could not be completed | Re-quote, then retry `book` with a fresh quote and the same idempotency key. |
+| `CANCELLATION_NOT_ALLOWED` | Order can't be cancelled (terminal/too late) | Re-check status via `ride get`; no action if already terminal. |
+| `SERVICE_NOT_FOUND` | Unknown `service_id` | Re-run `services list` and use a valid, enabled `service_id`. |
+| `PARAM_IDEMPOTENCY_KEY_REQUIRED` | Missing/invalid idempotency key on a write op | Pass a valid `--idempotency-key` (1–128 chars, `[A-Za-z0-9_-]`). |
+
+Other codes you may see: `NETWORK_ERROR` / `TIMEOUT` (retry, check host),
+`CLI_OUTDATED` (upgrade the CLI), `CONFIG_ERROR` (fix/reset local config).

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+
+export {  }