@agenzo/merchant-cli 0.7.0 → 0.8.0

package/README.md

@@ -3,7 +3,7 @@
 [![npm](https://img.shields.io/npm/v/@agenzo/merchant-cli.svg)](https://www.npmjs.com/package/@agenzo/merchant-cli) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](../../LICENSE) ![node](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)
 
 > **Merchant-fulfillment CLI** for the Agenzo platform — binary `agenzo-merchant-cli`.
-> Agents fulfill commerce services here. Each capability is a noun and the set grows over time — use `services` to discover what's available; today's capabilities are ride-hailing (`ride-elife`) and hotel booking (`hotel-redaug`).
+> Agents fulfill commerce services here. Each capability is a noun and the set grows over time — use `services` to discover what's available; today's capabilities are ride-hailing (`ride-elife`), hotel booking (`hotel-redaug`), and flight booking (`flight-flink`).
 
 **[Overview](#overview)** · **[Features](#features)** · **[Quick Start](#quick-start)** · **[Global flags](#global-flags)** · **[Errors](#output-and-error-contract)** · **[Idempotency-Key](#idempotency-key)**
 
@@ -16,6 +16,7 @@
 - **`services`** (capability discovery): list what's currently available and how to call it — run this first to learn the current capability set.
 - **`ride-elife`** (ride-hailing): the full loop of quote → book → query/poll → cancel → list-orders.
 - **`hotel-redaug`** (hotel booking): search, find-destination, hotel-filters, list-cities, hotel-detail, quote, create-order, pay-order, get (status/poll), cancel, checkout, get-checkout, list-orders. Supports both **monthly_settlement** (on-account deduction) and **pay_per_call** (user pays via EVO using the order_id as the merchantTransID).
+- **`flight-flink`** (flight booking): search, verify, create-order, pay-order, get-order, cancel, list-orders, and refund operations, including `upi_agent` payment-token passthrough.
 
 More fulfillment capabilities are added as new nouns over time; `services list` always reflects the current set.
 
@@ -104,10 +105,14 @@ agenzo-merchant-cli ride-elife cancel --api-key "$API_KEY" --yes \
 ### Hotel booking end-to-end example
 
 The core Agent loop is `search → quote → create-order → pay-order → get`. Amounts are decimal currency
-units (e.g. `320.00` = 320.00 yuan). `pay-order` takes only `--order-id`; the billing path is chosen
-server-side by the developer's `billing_mode`:
-- **monthly_settlement**: deducted from the monthly-settlement account.
-- **pay_per_call**: the user pays via shared EVO parameters using the `order_id` as the EVO merchantTransID; the platform verifies that payment for the same `order_id` before confirming.
+units (e.g. `320.00` = 320.00 yuan). **`create-order` settles payment AND locks the room** — the funds
+path is chosen server-side by the developer's `billing_mode`:
+
+- **monthly_settlement**: the total is deducted from the developer's monthly-settlement account balance.
+- **pay_per_call**: the total is authorized + captured on the developer's bound card via the platform's own EVO integration (server-side; no EVO parameters pass through this CLI).
+
+`pay-order` takes only `--order-id` and triggers supplier confirmation / ticket issuance — funds were
+already settled in `create-order`, so both billing modes use the same `pay-order` call.
 
 ```bash
 # 1. Search hotels by coordinates + stay dates (or use --destination-id from find-destination).
@@ -123,7 +128,7 @@ agenzo-merchant-cli hotel-redaug quote --api-key "$API_KEY" \
   --check-in 2026-02-10 --check-out 2026-02-12 \
   --adults 2 --room-num 1 --nationality CN
 
-# 3. Create Order (write op: locks rate, no charge; returns order_id + payable amount).
+# 3. Create Order (write op: settles payment + locks the room; returns order_id + fc_order_code).
 agenzo-merchant-cli hotel-redaug create-order --api-key "$API_KEY" --yes \
   --product-token "$PRODUCT_TOKEN" \
   --total-amount 640.00 --currency CNY \
@@ -138,8 +143,8 @@ agenzo-merchant-cli hotel-redaug pay-order --api-key "$API_KEY" --yes \
   --order-id "$ORDER_ID" \
   --idempotency-key "hotel-pay-$(date +%s)"
 
-# 4b. Pay Order — pay_per_call path (user already paid via EVO using order_id
-#     as the EVO merchantTransID). Same command, no other flag.
+# 4b. Pay Order — pay_per_call path (funds already captured on the bound card in
+#     create-order; pay-order just triggers supplier confirmation). Same command.
 agenzo-merchant-cli hotel-redaug pay-order --api-key "$API_KEY" --yes \
   --order-id "$ORDER_ID" \
   --idempotency-key "hotel-pay-$(date +%s)"
@@ -182,6 +187,72 @@ agenzo-merchant-cli hotel-redaug get-checkout --api-key "$API_KEY" \
   --task-order-code "$TASK_ORDER_CODE" --watch --watch-interval 10 --watch-timeout 600
 ```
 
+### Flight booking end-to-end example (flight-flink)
+
+The flow is `find-airport → search → verify → create-order → pay-order → get-order (poll until TICKETED)`.
+Amounts are decimal currency units (e.g. `1200.00` = 1200.00 yuan). `create-order` locks the fare without
+charging; `pay-order` settles + triggers ticketing (asynchronous — poll `get-order` until status=TICKETED).
+
+```bash
+# 1. Resolve a city/airport keyword to IATA codes.
+agenzo-merchant-cli flight-flink find-airport --api-key "$API_KEY" --keyword "beijing"
+
+# 2. Search one-way flights (trip-type 1=OW, 2=RT, 3=multi-city).
+#    journeys always carries ALL legs; for multi-city, relay --journey-id from each result.
+agenzo-merchant-cli flight-flink search --api-key "$API_KEY" \
+  --trip-type 1 \
+  --journeys '[{"date":"2026-08-01","origin":"PEK","originType":"2","destination":"SHA","destinationType":"2"}]'
+
+# 3. Verify price (returns authoritative product_token; if price_changed, re-confirm with user).
+agenzo-merchant-cli flight-flink verify --api-key "$API_KEY" \
+  --product-token "$PRODUCT_TOKEN"
+
+# 4. Create Order (write op: locks fare, NO charge; status → AWAITING_PAYMENT).
+agenzo-merchant-cli flight-flink create-order --api-key "$API_KEY" --yes \
+  --product-token "$VERIFIED_TOKEN" \
+  --total-amount 1200.00 --currency CNY \
+  --contact-name "ZHANG SAN" --contact-region 86 \
+  --contact-phone "13800138000" --contact-email "a@example.com" \
+  --passengers '[{"firstName":"SAN","lastName":"ZHANG","gender":"1","birthday":"1990-01-01","id_type":"1","id_number":"E12345678","nationality":"CN","type":"adult","expiration":"2032-01-01"}]' \
+  --idempotency-key "flight-create-$(date +%s)"
+
+# 5. Pay Order (settles + triggers ticketing; status → PAID).
+agenzo-merchant-cli flight-flink pay-order --api-key "$API_KEY" --yes \
+  --order-no "$ORDER_NO" \
+  --idempotency-key "flight-pay-$(date +%s)"
+
+# 6. Poll status until TICKETED (ticket_infos populated). Single-pax ~100s, multi-pax ~150s+.
+agenzo-merchant-cli flight-flink get-order --api-key "$API_KEY" --order-no "$ORDER_NO" \
+  --watch --watch-interval 10 --watch-timeout 300
+
+# 7. List flight orders (local read, pagination + optional status filter).
+agenzo-merchant-cli flight-flink list-orders --api-key "$API_KEY" --page 1 --page-size 20
+
+# 8. Cancel an un-ticketed order (ticketed orders → use refund-apply instead).
+agenzo-merchant-cli flight-flink cancel-order --api-key "$API_KEY" --yes \
+  --order-no "$ORDER_NO" \
+  --idempotency-key "flight-cancel-$(date +%s)"
+
+# 9. Change (rebooking): search → apply → detail; confirm via pay-order or cancel via change-cancel.
+agenzo-merchant-cli flight-flink change-search --api-key "$API_KEY" \
+  --order-no "$ORDER_NO" --date 2026-08-05 --passenger P1 --segment-id S1
+agenzo-merchant-cli flight-flink change-apply --api-key "$API_KEY" --yes \
+  --order-no "$ORDER_NO" --passenger P1 --segment-id S1 \
+  --product-token "$CHANGE_TOKEN" \
+  --contact-name "ZHANG SAN" --contact-region 86 --contact-phone 138 --contact-email a@b.com \
+  --idempotency-key "flight-change-$(date +%s)"
+
+# 10. Refund: apply → detail → confirm (--confirm 1 to proceed, 2 to cancel).
+agenzo-merchant-cli flight-flink refund-apply --api-key "$API_KEY" --yes \
+  --order-no "$ORDER_NO" --passenger P1 --segment-id S1 \
+  --reason-type 1 \
+  --contact-name "ZHANG SAN" --contact-region 86 --contact-phone 138 --contact-email a@b.com \
+  --idempotency-key "flight-refund-$(date +%s)"
+agenzo-merchant-cli flight-flink refund-confirm --api-key "$API_KEY" --yes \
+  --refund-order-no "$REFUND_ORDER_NO" --confirm 1 \
+  --idempotency-key "flight-refund-confirm-$(date +%s)"
+```
+
 ## Global flags
 
 | Flag | Default | Description |
@@ -257,13 +328,15 @@ merchant-cli **has no host / config commands** and does not govern environments.
 
 ## Machine-readable verb schema
 
-Every `ride-elife` and `hotel-redaug` verb supports `--help --format json`, emitting that verb's machine-readable schema (`cli` / `noun` / `verb` / `description` / `flags` / `response` / `example`, some with `error_recovery` / `polling`):
+Every `ride-elife`, `hotel-redaug`, and `flight-flink` verb supports `--help --format json`, emitting that verb's machine-readable schema (`cli` / `noun` / `verb` / `description` / `flags` / `response` / `example`, some with `error_recovery` / `polling`):
 
 ```bash
 agenzo-merchant-cli ride-elife quote --help --format json
 agenzo-merchant-cli ride-elife book --help --format json
 agenzo-merchant-cli hotel-redaug quote --help --format json
 agenzo-merchant-cli hotel-redaug create-order --help --format json   # write verb: error_recovery
+agenzo-merchant-cli flight-flink search --help --format json
+agenzo-merchant-cli flight-flink create-order --help --format json
 agenzo-merchant-cli hotel-redaug pay-order --help --format json      # write verb: error_recovery
 agenzo-merchant-cli hotel-redaug get --help --format json             # long-running: polling block
 ```