@agenzo/merchant-cli 0.5.0 → 0.5.2

package/dist/index.js

@@ -41,15 +41,6 @@ var CODE_NUM = {
   QUOTE_EXPIRED: 4202,
   BOOKING_FAILED: 4203,
   CANCELLATION_NOT_ALLOWED: 4204,
-  PRICE_MISMATCH: 4205,
-  VEHICLE_CLASS_MISMATCH: 4206,
-  PAYMENT_METHOD_REQUIRED: 4207,
-  QUOTE_CACHE_UNAVAILABLE: 4208,
-  ARREARS_OUTSTANDING: 4209,
-  CONTACT_REQUIRED: 4210,
-  INVALID_PHONE: 4211,
-  SEAT_LIMIT_EXCEEDED: 4213,
-  RIDE_NOT_FOUND: 4212,
   NO_AVAILABILITY: 4301,
   PRICE_CHANGED: 4302,
   NAME_FORMAT_INVALID: 4303,
@@ -219,15 +210,6 @@ var STABLE_MESSAGE = {
   VEHICLE_UNAVAILABLE: "No vehicle is available for the requested trip. Please try a different time or class.",
   QUOTE_EXPIRED: "The quote has expired. Please request a new quote and retry.",
   BOOKING_FAILED: "The booking could not be completed. Please retry.",
-  PRICE_MISMATCH: "The price does not match the quote. Re-quote and use the exact amount from the quote response.",
-  VEHICLE_CLASS_MISMATCH: "The vehicle class does not match the quote. Use the vehicle class from the quote response.",
-  PAYMENT_METHOD_REQUIRED: "Pay-per-call billing requires an active payment method. Please add a card first.",
-  QUOTE_CACHE_UNAVAILABLE: "Quote cache is temporarily unavailable. Please request a new quote and retry.",
-  ARREARS_OUTSTANDING: "You have outstanding arrears. Please settle your balance before booking a new ride.",
-  CONTACT_REQUIRED: "Passenger contact information is required. Please provide a passenger name and phone number.",
-  INVALID_PHONE: "The passenger phone number is not valid. Please provide a valid international number.",
-  SEAT_LIMIT_EXCEEDED: "The number of child/infant/toddler seats exceeds the vehicle capacity. Reduce seats or choose a larger vehicle.",
-  RIDE_NOT_FOUND: "The ride order was not found or does not belong to you.",
   CANCELLATION_NOT_ALLOWED: "This order cannot be cancelled in its current state.",
   NO_AVAILABILITY: "No rooms available for the selected hotel and dates.",
   PRICE_CHANGED: "The price changed since the quote. Re-quote and confirm.",
@@ -914,7 +896,9 @@ var quoteSchema = {
     "passenger-count": { type: "int", required: false, description: "Number of passengers" },
     "luggage-count": { type: "int", required: false, description: "Number of luggage items" },
     "passenger-email": { type: "string", required: false, description: "Passenger email address" },
-    "children-count": { type: "int", required: false, description: "Number of children" }
+    "children-count": { type: "int", required: false, description: "Number of children" },
+    "infant-count": { type: "int", required: false, description: "Number of infants (passenger breakdown; affects seat pricing)" },
+    "toddler-count": { type: "int", required: false, description: "Number of toddlers (passenger breakdown; affects seat pricing)" }
   },
   response: {
     vehicle_classes: {
@@ -1308,7 +1292,7 @@ var hotelPayOrderSchema = {
   cli: CLI_NAME,
   noun: HOTEL_NOUN,
   verb: "pay-order",
-  description: 'Settle an existing AWAITING_PAYMENT order created by create-order. Takes only --order-id; the billing path is decided server-side by the order billing_mode. monthly_settlement deducts from the developer credit account then confirms with the supplier; pay_per_call verifies the user EVO payment \u2014 the EVO merchantTransID IS the order_id (the user pays via EVO under the order_id), so the platform queries EVO for that order_id and requires an exact amount/currency match before confirming (the response settlement_path is then "active_payment"). On success the order becomes PAID. Supports --watch to poll on PAYMENT_NOT_COMPLETED until PAID',
+  description: 'Settle an existing AWAITING_PAYMENT order created by create-order. Takes only --order-id; the billing path is decided server-side by the order billing_mode. monthly_settlement deducts from the developer credit account then confirms with the supplier; pay_per_call verifies the user EVO payment \u2014 the EVO merchantTransID IS the order_id (the user pays via EVO under the order_id), so the platform queries EVO for that order_id and requires an exact amount/currency match before confirming (the response settlement_path is then "pay_per_call"). On success the order becomes PAID. Supports --watch to poll on PAYMENT_NOT_COMPLETED until PAID',
   flags: {
     "order-id": { type: "string", required: true, description: "Order to settle (create-order.response.order_id). For pay_per_call this is also the EVO merchantTransID the user paid under." },
     "idempotency-key": {
@@ -1323,7 +1307,7 @@ var hotelPayOrderSchema = {
   },
   response: {
     order_id: { type: "string", description: "Order reference." },
-    settlement_path: { type: "string", description: "Which billing path was used: 'monthly_settlement' or 'active_payment'." },
+    settlement_path: { type: "string", description: "Which billing path was used: 'monthly_settlement' or 'pay_per_call' (same tokens as billing_mode)." },
     amount: { type: "float", description: "Settled amount in DECIMAL units." },
     currency: { type: "string", description: "ISO 4217 currency code of the settlement." },
     pay_status: { type: "int", description: "Upstream pay status (1 = paid). The order internal status is now PAID." },
@@ -1331,7 +1315,7 @@ var hotelPayOrderSchema = {
   },
   example: {
     command: "agenzo-merchant-cli hotel-redaug pay-order --order-id hho_01KWC63Z5CD6CKBM33Q7SC2ZDT --idempotency-key pay-h1n2",
-    output_summary: 'Settlement path is chosen server-side by billing_mode. monthly_settlement: deducts from the credit account, confirms with the supplier. Returns {order_id, settlement_path:"monthly_settlement", amount, currency, pay_status:1, settled_at}. Order becomes PAID. For pay_per_call the user must have already paid via EVO using the order_id as the merchantTransID; the same command settles it (settlement_path:"active_payment").'
+    output_summary: 'Settlement path is chosen server-side by billing_mode. monthly_settlement: deducts from the credit account, confirms with the supplier. Returns {order_id, settlement_path:"monthly_settlement", amount, currency, pay_status:1, settled_at}. Order becomes PAID. For pay_per_call the user must have already paid via EVO using the order_id as the merchantTransID; the same command settles it (settlement_path:"pay_per_call").'
   },
   error_recovery: {
     PAYMENT_NOT_COMPLETED: "pay_per_call only: EVO has not yet confirmed the payment for this order_id. Retry with the SAME idempotency-key after a delay, or use --watch to poll automatically until PAID.",
@@ -2351,7 +2335,10 @@ function registerListOrdersCommand(parent, deps) {
 // src/services/registry.ts
 var SERVICE_REGISTRY = [
   {
-    service_id: "ride-elife",
+    // service_id 是平台级不透明内部引用（svc_ 前缀 + ULID），不进 Agent 日常拼的命令
+    // ——Agent 拼命令用的是 cli_noun="ride-elife"。与后端
+    // services/merchant_service/discovery/catalog.py 的 RIDE_ELIFE_SERVICE_ID 保持一致。
+    service_id: "svc_01KWTPBWDH5YZ52H717BFVWZA8",
     name: "Ride hailing (eLife)",
     description: "On-demand ride ordering: quote a fare, book it, poll status, and cancel.",
     category: "ride",
@@ -2368,7 +2355,9 @@ var SERVICE_REGISTRY = [
     },
     workflow: ["quote", "book", "get (poll for status)", "cancel (optional)"],
     since: "2026-06-01",
-    discovery: { help_command: "agenzo-merchant-cli ride-elife --help" }
+    discovery: {
+      help_command: "agenzo-merchant-cli ride-elife --help"
+    }
   },
   {
     service_id: "svc_01J0HT5REDAUG0001",
@@ -2420,7 +2409,9 @@ var SERVICE_REGISTRY = [
       "cancel / checkout (optional)"
     ],
     since: "2026-06-25",
-    discovery: { help_command: "agenzo-merchant-cli hotel-redaug --help" }
+    discovery: {
+      help_command: "agenzo-merchant-cli hotel-redaug --help"
+    }
   }
 ];
 function findService(serviceId) {
@@ -3362,10 +3353,29 @@ function formatGetOrder2(data) {
   if (data.check_in) lines.push(["Check-in", String(data.check_in)]);
   if (data.check_out) lines.push(["Check-out", String(data.check_out)]);
   if (data.total_amount !== void 0 && data.total_amount !== null) {
-    lines.push(["Total amount", String(data.total_amount)]);
+    const currency = data.currency ? ` ${data.currency}` : "";
+    lines.push(["Total amount", `${String(data.total_amount)}${currency}`]);
+  }
+  if (data.settlement_path) lines.push(["Settlement path", String(data.settlement_path)]);
+  if (data.rooms && data.rooms.length > 0) {
+    lines.push([
+      "Rooms",
+      data.rooms.map((r) => `${r.room_index}:${r.guest_name}`).join(", ")
+    ]);
+  }
+  if (data.room_num !== void 0 && data.room_num !== null) {
+    lines.push(["Rooms booked", String(data.room_num)]);
   }
+  if (data.guest?.name) lines.push(["Guest", String(data.guest.name)]);
+  if (data.contact?.name) {
+    const phone2 = data.contact.phone ? ` (+${data.contact.country_code ?? ""} ${data.contact.phone})` : "";
+    lines.push(["Contact", `${data.contact.name}${phone2}`]);
+  }
+  if (data.arrive_time) lines.push(["Arrive time", String(data.arrive_time)]);
+  if (data.special_requests) lines.push(["Special requests", String(data.special_requests)]);
   if (data.channel_state) lines.push(["Channel state", String(data.channel_state)]);
-  if (data.source) lines.push(["Source", String(data.source)]);
+  if (data.created_at) lines.push(["Created at", String(data.created_at)]);
+  if (data.updated_at) lines.push(["Updated at", String(data.updated_at)]);
   return Formatter.keyValue(lines);
 }
 function registerHotelGetCommand(parent, deps) {
@@ -4134,7 +4144,7 @@ run \`hotel-redaug <verb> --help\`.
 - API key with merchant scope
 - Two billing modes supported (set on the developer, not chosen per-call):
   - **monthly_settlement**: developer has a settlement account with sufficient balance
-  - **pay_per_call**: developer collects payment from their end-user via EVO; the user pays using the create-order \`order_id\` as the EVO merchantTransID, and the platform verifies by querying EVO for that order_id (the pay-order response reports settlement_path "active_payment")
+  - **pay_per_call**: developer collects payment from their end-user via EVO; the user pays using the create-order \`order_id\` as the EVO merchantTransID, and the platform verifies by querying EVO for that order_id (the pay-order response reports settlement_path "pay_per_call")
 - BILLING_MODE_MISMATCH means the order billing_mode is not one of the two modes above
 - Pass --api-key <key> --format json on every call; add --yes on writes
 
@@ -4179,32 +4189,40 @@ run \`hotel-redaug <verb> --help\`.
    - Generate a unique idempotency-key
    - Response \u2192 save order_id + fc_order_code + total_amount + currency
    - Order status: AWAITING_PAYMENT (no money charged yet)
-   - FOR pay_per_call: tell the user to pay total_amount+currency via EVO
-     USING THIS order_id as the EVO merchantTransID. The verification in step 6 works by
-     querying EVO for exactly this order_id, so paying under any other id will not settle.
 
-6. Pay order (settle the locked order) \u2014 MUST confirm with the user before calling this
+6. BRANCH ON BILLING_MODE \u2014 decide THIS before calling pay-order, not inside it
+   - You (the developer/Agent) know your own billing_mode; the order does not expose it.
+   a) monthly_settlement \u2192 skip straight to step 7 (pay-order). Nothing to do here.
+   b) pay_per_call \u2192 STOP. Do NOT call pay-order yet.
+      - Drive YOUR OWN EVO payment integration now, using the order_id from step 5 AS THE
+        EVO merchantTransID (this is the id you pass to your EVO payment call \u2014 not a new
+        or random id).
+      - Wait for the end-user to actually complete that EVO payment for total_amount+currency.
+      - Only once EVO shows the payment as complete, proceed to step 7 \u2014 pay-order is what
+        tells the platform "go verify and settle this", it does NOT itself collect payment.
+
+7. Pay order (settle the locked order) \u2014 MUST confirm with the user before calling this
    - Before calling: show the user total_amount + currency from create-order and which
      billing path applies, and get explicit go-ahead \u2014 pay-order is the step that actually
-     moves money
+     moves money (for pay_per_call, confirm the EVO payment from step 6 was completed first)
    - pay-order --order-id <order_id from create-order>   (that's the only identifier needed)
    - Billing path determined server-side by developer's billing_mode:
      a) monthly_settlement:
         - Platform deducts from settlement account \u2192 calls upstream payOrder
      b) pay_per_call:
-        - The user must have ALREADY paid via EVO using the order_id as the EVO
-          merchantTransID (see create-order step 5). Just call pay-order --order-id <id>;
-          the platform queries EVO for that order_id and verifies exact amount/currency.
+        - Requires step 6 to have already happened (user paid via EVO under this order_id).
+          Calling pay-order now just makes the platform query EVO for that order_id and
+          verify exact amount/currency \u2014 it does NOT initiate the EVO payment itself.
           There is no merchant-transaction-id flag: the EVO key IS the order_id, so a
           foreign already-paid EVO transaction cannot be substituted.
         - If EVO not yet confirmed \u2192 PAYMENT_NOT_COMPLETED; use --watch to poll
    - On success \u2192 order status becomes PAID
 
-7. Confirm (upstream confirmation is async)
+8. Confirm (upstream confirmation is async)
    - Poll get --order-id until CONFIRMED (success) or CANCELLED (failed)
    - Do not report success before CONFIRMED
 
-8. Post-booking (only when the user asks)
+9. Post-booking (only when the user asks)
    - cancel: order_id + fc_order_code + reason
    - checkout: partial leave-early \u2192 then poll get-checkout with task_order_code
    - list-orders: view all orders
@@ -4215,8 +4233,9 @@ run \`hotel-redaug <verb> --help\`.
 - price_items     : quote \u2192 create-order  (JSON array; copy exactly)
 - order_id        : create-order \u2192 pay-order / get / cancel
 - fc_order_code   : create-order \u2192 cancel / checkout
-- order_id (again): for pay_per_call it IS the EVO merchantTransID \u2014 the user pays via
-  EVO under the order_id; pay-order takes no separate merchant-transaction-id
+- order_id (again): for pay_per_call it IS the EVO merchantTransID \u2014 YOU (the developer/Agent)
+  use it to drive your own EVO payment call BEFORE pay-order (see step 6); pay-order itself
+  takes no separate merchant-transaction-id, it only verifies the payment already made
 - task_order_code : checkout \u2192 get-checkout
 
 ## Billing modes (chosen server-side by billing_mode)
@@ -4227,15 +4246,18 @@ routes purely by the order's billing_mode:
 | Developer billing_mode | Behavior |
 |------------------------|----------|
 | monthly_settlement     | Deducts settlement balance \u2192 payOrder |
-| pay_per_call           | Platform queries EVO for the order_id \u2192 verify exact amount/currency \u2192 payOrder (response settlement_path is "active_payment") |
+| pay_per_call           | Platform queries EVO for the order_id \u2192 verify exact amount/currency \u2192 payOrder (response settlement_path is "pay_per_call") |
 | anything else          | ERROR: BILLING_MODE_MISMATCH (only the two modes above are valid) |
 
 ## pay_per_call flow \u2014 the EVO merchantTransID IS the order_id
 
 1. create-order returns order_id + total_amount + currency (no EVO credentials in response)
-2. User pays total_amount+currency via EVO, USING the order_id as the EVO merchantTransID
-   (the shared EVO parameters are onboarded separately, out of band)
-3. Agent calls pay-order --order-id <order_id>   (no other identifier)
+2. YOU drive your own EVO payment integration now, passing the order_id as the EVO
+   merchantTransID, and get the user to pay total_amount+currency
+   (the shared EVO parameters are onboarded separately, out of band \u2014 pay-order does not do
+   this step for you)
+3. ONLY once that EVO payment is complete, call pay-order --order-id <order_id>
+   (no other identifier)
 4. Platform queries EVO for that order_id: paid + exact amount/currency match \u2192 payOrder \u2192 PAID
 5. If not yet paid \u2192 PAYMENT_NOT_COMPLETED; use --watch to auto-poll
 6. Why order_id (not an arbitrary id): it binds the payment to this exact order, so a caller
@@ -4252,7 +4274,7 @@ routes purely by the order's billing_mode:
 - IMPORTANT: --yes only skips this CLI's own interactive TTY prompt (needed because the Agent
   runs non-interactively). It is NOT a substitute for showing the user the hotel/rate/price and
   getting their decision in the chat UI. Passing --yes does not remove the confirmation steps in
-  step 3/4 (choose hotel + rate) or step 6 (confirm before pay-order) above.
+  step 3/4 (choose hotel + rate) or step 7 (confirm before pay-order) above.
 - After a cancel call returns successfully (including the cancel_status='cancel_pending' shape),
   do NOT call cancel again for the same order \u2014 poll get instead. A pending acknowledgement is
   success, not failure.
@@ -4304,7 +4326,31 @@ async function main() {
     const flag = thisCommand.opts().format;
     process.env.AGENZO_FORMAT = resolveFormat(flag);
   });
-  const rideCmd = program.command("ride-elife").description("Ride ordering (eLife)");
+  const rideCmd = program.command("ride-elife").description(
+    `Ride ordering (eLife) \u2014 quote a fare, book it, poll status, and cancel.
+
+Workflow (typical order):
+  1. quote        Get fare quotes between two points \u2192 vehicle_classes[] each with a quote_id
+  2. book         Book one vehicle_class using its quote_id \u2192 ride_id (write; needs --idempotency-key)
+  3. get          Poll ride status by --order-id=<ride_id> until terminal (or use --watch for NDJSON)
+  4. cancel       (optional) Cancel a ride by --order-id (write; may incur a fee)
+     list-orders  (standalone) List the developer's previous ride orders
+
+Key notes:
+  \u2022 Coordinates are NOT geocoded by the backend \u2014 supply --pickup-lat/lng and --dropoff-lat/lng.
+    book must repeat the SAME pickup/dropoff coordinates+names and pickup-time used in quote;
+    the quote_id does NOT carry them forward.
+  \u2022 quote_id from quote is opaque and provider-specific \u2014 pass it unchanged to book, never reuse
+    it across services.
+  \u2022 vehicle_class values are case-sensitive literals (Sedan / SUV / MPV-5 / MPV-7 / Van / Luxury /
+    Train) \u2014 pass back to book verbatim.
+  \u2022 --pickup-time is UTC epoch seconds or the literal "now"; convert the user's local time to UTC.
+  \u2022 All amounts are DECIMAL currency units (e.g. 42.50 = $42.50), never minor units (cents).
+  \u2022 Billing mode is decided server-side: pay_per_call needs a PAID --payment-order-id (from
+    payment-cli); monthly_settlement forbids it (settled against the developer's account).
+  \u2022 Write verbs (book / cancel) require --idempotency-key; reuse the SAME key when retrying the
+    same intent.`
+  );
   registerQuoteCommand(rideCmd, deps);
   registerBookCommand(rideCmd, deps);
   registerRideGetCommand(rideCmd, deps);