@agenzo/merchant-cli 0.9.0 → 0.9.1

package/dist/index.js

@@ -1197,6 +1197,22 @@ var ridePayOrderSchema = {
       default: false,
       description: "[\u65B9\u6848 B/R16] Explicit opt-in to settle this pay_per_call ride via the EVO bound-card fallback rail. Set true ONLY when the user explicitly chose EVO; forwarded to the pay body as evo_explicit=true. Without it, a pay_per_call settlement lacking --payment-token-id is hard-gated server-side. Ignored for monthly_settlement and on the payment-token-id direct-charge path."
     },
+    authenticate: {
+      type: "bool",
+      required: false,
+      default: false,
+      description: "Opt-in to require cardholder 3DS on the network-token direct charge (payment-token-id, EVO/Mastercard). On step-up the response is AUTHENTICATION_REQUIRED with three_ds_url + charge_no; resume via authorized-charge-no. Default off = frictionless. Ignored on the EVO preauth path and for UnionPay/Visa."
+    },
+    "return-url": {
+      type: "string",
+      required: false,
+      description: "Optional 3DS/passkey return URL for the network-token authenticate path; falls back to the platform EVO_3DS_RETURN_URL."
+    },
+    "authorized-charge-no": {
+      type: "string",
+      required: false,
+      description: "Resume a network-token 3DS challenge: charge_no from a prior AUTHENTICATION_REQUIRED response (settled via resume_token). Relaxes the exactly-one-credential rule (continuation, not a fresh charge)."
+    },
     "idempotency-key": {
       type: "string",
       required: true,
@@ -1662,6 +1678,22 @@ var hotelPayOrderSchema = {
       default: false,
       description: "[\u65B9\u6848 B/R16] Explicit opt-in to settle this pay_per_call order via the EVO bound-card fallback rail. Set true ONLY when the user explicitly chose EVO; forwarded to the pay body as evo_explicit=true. Without it, a pay_per_call settlement lacking --payment-token-id is hard-gated server-side. Ignored for monthly_settlement and on the payment-token-id direct-charge path."
     },
+    authenticate: {
+      type: "bool",
+      required: false,
+      default: false,
+      description: "Opt-in to require cardholder 3DS on the network-token direct charge (payment-token-id, EVO/Mastercard). On step-up the response is AUTHENTICATION_REQUIRED with three_ds_url + charge_no; resume via authorized-charge-no. Default off = frictionless. Ignored on the EVO preauth path and for UnionPay/Visa."
+    },
+    "return-url": {
+      type: "string",
+      required: false,
+      description: "Optional 3DS/passkey return URL for the network-token authenticate path; falls back to the platform EVO_3DS_RETURN_URL."
+    },
+    "authorized-charge-no": {
+      type: "string",
+      required: false,
+      description: "Resume a network-token 3DS challenge: charge_no from a prior AUTHENTICATION_REQUIRED response (settled via resume_token), then triggers upstream payOrder on success (pay_per_call only)."
+    },
     "idempotency-key": {
       type: "string",
       required: true,
@@ -2363,30 +2395,38 @@ var flightListNationalitiesSchema = flightSchema(
 );
 var flightSearchSchema = flightSchema(
   "search",
-  "Search flights (one-way/round-trip/multi-city). journeys always carries all legs; journey-id accumulates progress and only the final search returns a real priceKey (product_token).",
+  "Search flights (one-way/round-trip/multi-city). journeys always carries all legs; for round-trip/multi-city relay the CHOSEN candidate's next_journey_ids into --journey-id until is_final_leg is true \u2014 only then do offers carry a real priceKey (product_token).",
   {
     "trip-type": { type: "int", required: true, description: "1=one-way, 2=round-trip, 3=multi-city." },
-    journeys: { type: "json", required: true, description: "JSON array of {date, origin, destination, origin_type?, destination_type?}. origin/destination are IATA 3-letter codes; *_type 1=city, 2=airport." },
+    journeys: { type: "json", required: true, description: "JSON array of {date, origin, destination, origin_type?, destination_type?}. origin/destination are IATA 3-letter codes; *_type 1=city, 2=airport. Carries ALL legs on every call, including relay calls." },
     "cabin-class": { type: "string", required: false, default: "economy", description: "economy | premium_economy | business | first." },
     "adult-num": { type: "int", required: false, default: 1, description: "Adults (1-9)." },
     "child-num": { type: "int", required: false, default: 0, description: "Children (0-9)." },
     "infant-num": { type: "int", required: false, default: 0, description: "Infants (0-9)." },
     airline: { type: "string", required: false, description: "Airline 2-letter code filter." },
     "transfer-number": { type: "int", required: false, default: 0, description: "0=any,1=direct,2=1 stop,3=2 stops." },
-    "journey-id": { type: "json", required: false, description: "JSON array of already-selected journey ids (relay for round-trip/multi-city)." }
+    "journey-id": { type: "json", required: false, description: "Relay key: copy offers[].next_journey_ids VERBATIM from the candidate the user chose in the previous search. Omit on the first search. Do not build it from the top-level journey_ids, and never send more ids than there are legs (rejected)." }
   },
   {
-    offers: { type: "array", description: "Offers; each has product_token (when price_key_ready), total_sale_price, currency." },
+    offers: { type: "array", description: "Candidates for the current leg. Each has next_journey_ids (relay key), journey_id, segment_ids, paired_segment_ids, total_sale_price (WHOLE-TRIP total), currency, cabin_class, baggage/refund/change_rules, and product_token when price_key_ready." },
     price_key_ready: { type: "bool", description: "True only when all legs are selected (final search)." },
-    journey_ids: { type: "array", description: "journeyId values to relay into the next search." }
+    current_leg: { type: "int", description: "Which leg this result is choosing (1-based)." },
+    total_legs: { type: "int", description: "Total legs in the trip." },
+    is_final_leg: { type: "bool", description: "True when these offers can be bookable. False means relay another round with the chosen candidate's next_journey_ids." },
+    journey_ids: { type: "array", description: "DEPRECATED for relay: flattened across all candidates, so it cannot tell you which id belongs to which. Relay offers[].next_journey_ids instead." }
   },
-  { command: `agenzo-merchant-cli flight-flink search --trip-type 1 --journeys '[{"date":"2026-08-01","origin":"PEK","destination":"SHA"}]'`, output_summary: "Returns offers[]; use a product_token where price_key_ready is true, then verify." }
+  { command: `agenzo-merchant-cli flight-flink search --trip-type 1 --journeys '[{"date":"2026-08-01","origin":"PEK","destination":"SHA"}]'`, output_summary: "Returns offers[]; use a product_token where price_key_ready is true, then verify. Round-trip: the first search has is_final_leg=false and no product_token \u2014 relay the chosen candidate's next_journey_ids to get bookable offers." }
 );
 var flightMoreOffersSchema = flightSchema(
   "more-offers",
   "More fare offers for a priceKey (carried by product_token).",
   { "product-token": { type: "string", required: true, description: "Opaque token from search." } },
-  { offers: { type: "array", description: "Additional fare candidates." } },
+  {
+    offers: { type: "array", description: "Additional fare candidates for the same flight (same shape as search offers[]); all are bookable." },
+    current_leg: { type: "int", description: "Always 1 \u2014 alternative fares for one chosen flight, not a relay round." },
+    total_legs: { type: "int", description: "Always 1." },
+    is_final_leg: { type: "bool", description: "Always true." }
+  },
   { command: "agenzo-merchant-cli flight-flink more-offers --product-token pt_...", output_summary: "Additional fare offers." }
 );
 var flightVerifySchema = flightSchema(
@@ -2397,7 +2437,8 @@ var flightVerifySchema = flightSchema(
     product_token: { type: "string", description: "Authoritative token to pass to create-order." },
     total_price: { type: "int", description: "Verified total price (integer)." },
     currency: { type: "string", description: "Currency code." },
-    price_changed: { type: "bool", description: "True if the price changed since search; re-confirm with the user." }
+    price_changed: { type: "bool", description: "True if the price changed since search; re-confirm with the user." },
+    journeys: { type: "array", description: "The COMPLETE itinerary being priced \u2014 every leg, not just the last one relayed. Use it to show the full trip on a confirmation screen." }
   },
   { command: "agenzo-merchant-cli flight-flink verify --product-token pt_...", output_summary: "Returns the authoritative product_token + price_changed." }
 );
@@ -2440,7 +2481,10 @@ var flightPayOrderSchema = flightSchema(
     "order-no": { type: "string", required: true, description: "Our order reference from create-order." },
     "payment-method-id": { type: "string", required: false, description: "Optional bound-card id to charge (pay_per_call only; omit to use the default card)." },
     "payment-token-id": { type: "string", required: false, description: "Optional network-token id; settles via direct charge instead of EVO preauth." },
-    "authorized-merchant-trans-id": { type: "string", required: false, description: "Resume a 3DS challenge with an already-authorised preauth trans id." },
+    "authorized-merchant-trans-id": { type: "string", required: false, description: "Resume an EVO-card 3DS challenge with an already-authorised preauth trans id." },
+    authenticate: { type: "bool", required: false, default: false, description: "Opt-in to require cardholder 3DS on the network-token direct charge (payment-token-id, EVO/Mastercard). On step-up the response is AUTHENTICATION_REQUIRED with three_ds_url + charge_no; resume via authorized-charge-no. Default off = frictionless." },
+    "return-url": { type: "string", required: false, description: "Optional 3DS/passkey return URL for the network-token authenticate path; falls back to the platform EVO_3DS_RETURN_URL." },
+    "authorized-charge-no": { type: "string", required: false, description: "Resume a network-token 3DS challenge: charge_no from a prior AUTHENTICATION_REQUIRED response (settled via resume_token), then triggers ticketing on success." },
     "evo-explicit": { type: "bool", required: false, default: false, description: "[\u65B9\u6848 B/R16] Explicit opt-in to settle this pay_per_call order via the EVO bound-card fallback rail. Set true ONLY when the user explicitly chose EVO; forwarded to the pay body as evo_explicit=true. Without it, a pay_per_call settlement lacking --payment-token-id is hard-gated server-side." },
     "idempotency-key": { type: "string", required: true, description: "Forwarded verbatim as the Idempotency-Key header." }
   },
@@ -3103,6 +3147,17 @@ function formatPayOrder(data) {
     lines.push(["Amount", `${data.price.amount} ${data.price.currency}`]);
     if (data.price.quote_id) lines.push(["Quote ID", String(data.price.quote_id)]);
   }
+  if (data.charge_no) lines.push(["Charge no", String(data.charge_no)]);
+  if (data.three_ds_url) lines.push(["3DS URL", String(data.three_ds_url)]);
+  if (String(data.status) === "AUTHENTICATION_REQUIRED") {
+    return [
+      Formatter.keyValue(lines),
+      Formatter.status(
+        "warning",
+        `Order ${orderRef} needs cardholder 3DS \u2014 open the 3DS URL, then resume pay-order with --authorized-charge-no ${data.charge_no ?? ""}.`
+      )
+    ].join("\n\n");
+  }
   return [
     Formatter.keyValue(lines),
     Formatter.status(
@@ -3120,7 +3175,16 @@ function registerRidePayOrderCommand(parent, deps) {
     "Bound-card id to charge via EVO preauth+capture (fallback path). Exactly one of --payment-token-id / --payment-method-id is required."
   ).option(
     "--authorized-merchant-trans-id <id>",
-    "Resume a 3DS challenge: merchant trans id of an already-authorised preauth"
+    "Resume an EVO-card 3DS challenge: merchant trans id of an already-authorised preauth"
+  ).option(
+    "--authenticate",
+    "Opt-in to require cardholder 3DS on the network-token direct charge (--payment-token-id, EVO/Mastercard). When a step-up is needed the response is AUTHENTICATION_REQUIRED with three_ds_url + charge_no; resume with --authorized-charge-no. Default off = frictionless."
+  ).option(
+    "--return-url <url>",
+    "Optional 3DS/passkey return URL for the network-token authenticate path (falls back to the platform EVO_3DS_RETURN_URL)"
+  ).option(
+    "--authorized-charge-no <no>",
+    "Resume a network-token 3DS challenge: charge_no returned by a prior AUTHENTICATION_REQUIRED response (settled via ChargeService.resume_token). When set, the exactly-one-credential rule is relaxed (this is a continuation, not a fresh charge)."
   ).option(
     "--evo-explicit",
     "[\u65B9\u6848 B/R16] Explicit opt-in to settle this pay_per_call ride via the EVO bound-card fallback rail. Set ONLY when the user explicitly chose EVO; forwarded to the pay body as evo_explicit=true. Without it, a pay_per_call settlement lacking --payment-token-id is hard-gated server-side."
@@ -3136,7 +3200,10 @@ function registerRidePayOrderCommand(parent, deps) {
     const orderId = need4(opts.orderId, "order-id");
     const paymentTokenId = opts.paymentTokenId;
     const paymentMethodId = opts.paymentMethodId;
-    assertExactlyOneCredential(paymentTokenId, paymentMethodId);
+    const authorizedChargeNo = opts.authorizedChargeNo;
+    if (authorizedChargeNo === void 0) {
+      assertExactlyOneCredential(paymentTokenId, paymentMethodId);
+    }
     const apiKey = await PromptEngine.resolveInput(opts.apiKey, {
       message: "API Key:",
       type: "password"
@@ -3147,6 +3214,9 @@ function registerRidePayOrderCommand(parent, deps) {
     if (opts.authorizedMerchantTransId !== void 0) {
       body.authorized_merchant_trans_id = opts.authorizedMerchantTransId;
     }
+    if (opts.authenticate) body.authenticate = true;
+    if (opts.returnUrl !== void 0) body.return_url = opts.returnUrl;
+    if (authorizedChargeNo !== void 0) body.authorized_charge_no = authorizedChargeNo;
     if (opts.evoExplicit) body.evo_explicit = true;
     if (!isYes) {
       const confirmed = await confirm3({
@@ -4864,11 +4934,14 @@ function formatPayOrder2(data) {
   ];
   if (data.settlement_path) lines.push(["Settlement path", String(data.settlement_path)]);
   if (data.pay_status) lines.push(["Pay status", String(data.pay_status)]);
+  if (data.status) lines.push(["Status", String(data.status)]);
   if (data.total_amount != null && data.currency) {
     lines.push(["Amount", `${data.total_amount} ${data.currency}`]);
   }
   if (data.billing_entry_id) lines.push(["Billing entry", String(data.billing_entry_id)]);
   if (data.merchant_trans_id) lines.push(["Merchant trans ID", String(data.merchant_trans_id)]);
+  if (data.charge_no) lines.push(["Charge no", String(data.charge_no)]);
+  if (data.three_ds_url) lines.push(["3DS URL", String(data.three_ds_url)]);
   return Formatter.keyValue(lines);
 }
 function isPaymentTerminal(record) {
@@ -4878,7 +4951,16 @@ function isPaymentTerminal(record) {
 function registerHotelPayOrderCommand(parent, deps) {
   const cmd = parent.command("pay-order").description("Settle an existing hotel order (path decided by billing_mode: monthly_settlement or pay_per_call)").option("--api-key <key>", "API Key for authentication (X-Api-Key)").option("--order-id <id>", "Order ID to pay (from create-order response)").option("--payment-method-id <id>", "Optional bound-card id to charge (pay_per_call / EVO preauth)").option("--payment-token-id <id>", "Optional network-token id (unionpay/visa charge path)").option(
     "--authorized-merchant-trans-id <id>",
-    "Resume a 3DS challenge: merchant trans id of an already-authorised preauth"
+    "Resume an EVO-card 3DS challenge: merchant trans id of an already-authorised preauth"
+  ).option(
+    "--authenticate",
+    "Opt-in to require cardholder 3DS on the network-token direct charge (--payment-token-id, EVO/Mastercard). When a step-up is needed the response is AUTHENTICATION_REQUIRED with three_ds_url + charge_no; resume with --authorized-charge-no. Default off = frictionless."
+  ).option(
+    "--return-url <url>",
+    "Optional 3DS/passkey return URL for the network-token authenticate path (falls back to the platform EVO_3DS_RETURN_URL)"
+  ).option(
+    "--authorized-charge-no <no>",
+    "Resume a network-token 3DS challenge: charge_no returned by a prior AUTHENTICATION_REQUIRED response (settled via ChargeService.resume_token)"
   ).option(
     "--evo-explicit",
     "[\u65B9\u6848 B/R16] Explicit opt-in to settle this pay_per_call order via the EVO bound-card fallback rail. Set ONLY when the user explicitly chose EVO; forwarded to the pay body as evo_explicit=true. Without it, a pay_per_call settlement lacking --payment-token-id is hard-gated server-side."
@@ -4920,6 +5002,11 @@ function registerHotelPayOrderCommand(parent, deps) {
     if (opts.authorizedMerchantTransId !== void 0) {
       body.authorized_merchant_trans_id = opts.authorizedMerchantTransId;
     }
+    if (opts.authenticate) body.authenticate = true;
+    if (opts.returnUrl !== void 0) body.return_url = opts.returnUrl;
+    if (opts.authorizedChargeNo !== void 0) {
+      body.authorized_charge_no = opts.authorizedChargeNo;
+    }
     if (opts.evoExplicit) body.evo_explicit = true;
     if (!isYes) {
       const confirmed = await confirm8({
@@ -6151,7 +6238,7 @@ function registerListNationalitiesCommand(parent, deps) {
 
 // src/flight-flink/search.ts
 function registerSearchCommand(parent, deps) {
-  const cmd = parent.command("search").description("Search flights (one-way/round-trip/multi-city, journeyId relay)").option("--api-key <key>", "API Key for authentication (X-Api-Key)").option("--trip-type <n>", "1=one-way, 2=round-trip, 3=multi-city").option("--journeys <json>", "JSON array of {date, origin, destination, origin_type?, destination_type?}").option("--cabin-class <c>", "economy | premium_economy | business | first", "economy").option("--adult-num <n>", "Adults (1-9)", "1").option("--child-num <n>", "Children (0-9)", "0").option("--infant-num <n>", "Infants (0-9)", "0").option("--airline <code>", "Airline 2-letter code filter").option("--transfer-number <n>", "0=any,1=direct,2=1 stop,3=2 stops", "0").option("--journey-id <json>", "JSON array of already-selected journey ids (relay)");
+  const cmd = parent.command("search").description("Search flights (one-way/round-trip/multi-city, journeyId relay)").option("--api-key <key>", "API Key for authentication (X-Api-Key)").option("--trip-type <n>", "1=one-way, 2=round-trip, 3=multi-city").option("--journeys <json>", "JSON array of {date, origin, destination, origin_type?, destination_type?}").option("--cabin-class <c>", "economy | premium_economy | business | first", "economy").option("--adult-num <n>", "Adults (1-9)", "1").option("--child-num <n>", "Children (0-9)", "0").option("--infant-num <n>", "Infants (0-9)", "0").option("--airline <code>", "Airline 2-letter code filter").option("--transfer-number <n>", "0=any,1=direct,2=1 stop,3=2 stops", "0").option("--journey-id <json>", "Relay: the chosen offer's next_journey_ids, verbatim (round-trip/multi-city)");
   attachSchemaHelp(cmd, flightSearchSchema);
   cmd.action(async () => {
     const opts = cmd.optsWithGlobals();
@@ -6310,7 +6397,16 @@ import { confirm as confirm11 } from "@inquirer/prompts";
 function registerPayOrderCommand(parent, deps) {
   const cmd = parent.command("pay-order").description("Settle a created order by --order-no (triggers ticketing)").option("--api-key <key>", "API Key for authentication (X-Api-Key)").option("--order-no <id>", "Our order reference from create-order").option("--payment-method-id <id>", "Optional bound-card id to charge (pay_per_call only)").option("--payment-token-id <id>", "Optional network-token id (unionpay/visa charge path)").option(
     "--authorized-merchant-trans-id <id>",
-    "Resume a 3DS challenge: merchant trans id of an already-authorised preauth"
+    "Resume an EVO-card 3DS challenge: merchant trans id of an already-authorised preauth"
+  ).option(
+    "--authenticate",
+    "Opt-in to require cardholder 3DS on the network-token direct charge (--payment-token-id, EVO/Mastercard). When a step-up is needed the response is AUTHENTICATION_REQUIRED with three_ds_url + charge_no; resume with --authorized-charge-no. Default off = frictionless."
+  ).option(
+    "--return-url <url>",
+    "Optional 3DS/passkey return URL for the network-token authenticate path (falls back to the platform EVO_3DS_RETURN_URL)"
+  ).option(
+    "--authorized-charge-no <no>",
+    "Resume a network-token 3DS challenge: charge_no returned by a prior AUTHENTICATION_REQUIRED response (settled via ChargeService.resume_token)"
   ).option(
     "--evo-explicit",
     "[\u65B9\u6848 B/R16] Explicit opt-in to settle this pay_per_call order via the EVO bound-card fallback rail. Set ONLY when the user explicitly chose EVO; forwarded to the pay body as evo_explicit=true. Without it, a pay_per_call settlement lacking --payment-token-id is hard-gated server-side."
@@ -6340,6 +6436,11 @@ function registerPayOrderCommand(parent, deps) {
     if (opts.authorizedMerchantTransId !== void 0) {
       body.authorized_merchant_trans_id = opts.authorizedMerchantTransId;
     }
+    if (opts.authenticate) body.authenticate = true;
+    if (opts.returnUrl !== void 0) body.return_url = opts.returnUrl;
+    if (opts.authorizedChargeNo !== void 0) {
+      body.authorized_charge_no = opts.authorizedChargeNo;
+    }
     if (opts.evoExplicit) body.evo_explicit = true;
     const result = await deps.apiClient.post(
       `/flight/${encodeURIComponent(orderNo)}/pay`,
@@ -6349,15 +6450,16 @@ function registerPayOrderCommand(parent, deps) {
     );
     spinner?.stop();
     if (!result.success) throw CliError.fromApi(result, { auth: "api-key" });
-    await render2(
-      result.data,
-      opts.format,
-      (d) => Formatter.keyValue([
+    await render2(result.data, opts.format, (d) => {
+      const rows = [
         ["Order no", String(d.order_no ?? "-")],
         ["Status", String(d.status ?? "-")],
         ["Amount", `${d.amount ?? "-"} ${d.currency ?? ""}`.trim()]
-      ])
-    );
+      ];
+      if (d.charge_no) rows.push(["Charge no", String(d.charge_no)]);
+      if (d.three_ds_url) rows.push(["3DS URL", String(d.three_ds_url)]);
+      return Formatter.keyValue(rows);
+    });
   });
 }
 
@@ -6810,10 +6912,18 @@ verbs and pass data between them. For exact flags and field types, read the sche
 ## Workflow (book)
 1. find-airport --keyword "<place>"    \u2192 resolve to IATA city/airport codes
 2. search --trip-type <1|2|3> --journeys '<json>'
-   - journeys ALWAYS carries ALL legs. For round-trip/multi-city, relay journey-id
-     from the previous search into the next until price_key_ready is true.
-   - Only offers where price_key_ready is true carry a real product_token; earlier-leg
-     offers carry only an identifier (product_token null).
+   - journeys ALWAYS carries ALL legs, on every call including relay calls.
+   - Round-trip/multi-city: keep searching until is_final_leg is true. Each round, present the
+     candidates, let the USER pick one, and pass THAT candidate's next_journey_ids verbatim as
+     --journey-id on the next search. Never assemble the list yourself (the top-level journey_ids
+     is flattened across all candidates) and never send more ids than there are legs \u2014 it is
+     rejected, because upstream would otherwise silently answer with the FIRST leg's candidates.
+   - Only offers where price_key_ready is true carry a real product_token. Earlier-leg candidates
+     are NOT bare flight rows: total_sale_price is already the WHOLE-TRIP total and
+     paired_segment_ids names the legs upstream paired with it, so you can show the full
+     itinerary and real total from the first round \u2014 they just are not bookable yet.
+   - A relay search returning ZERO offers means the journey ids went stale OR that leg sold out
+     (upstream reports both as an empty list). Restart from leg 1 for fresh ids.
    - Code<->type consistency: tag each code with its matching type \u2014 an AIRPORT code (e.g. NRT)
      uses type 2, a CITY code (e.g. TYO) uses type 1. Mislabeling (e.g. NRT with type 1, since NRT
      is an airport whose city is TYO) is rejected with code 400 "destination not exist".
@@ -6849,7 +6959,7 @@ verbs and pass data between them. For exact flags and field types, read the sche
 ## Data passing
 - product_token : search \u2192 verify \u2192 create-order (opaque; never fabricate or edit; verify's token wins)
 - order_no      : create-order \u2192 pay-order / get-order / cancel-order
-- journey_id    : search \u2192 next search (relay for round-trip/multi-city)
+- next_journey_ids : chosen offer \u2192 next search's --journey-id (relay for round-trip/multi-city)
 - change_order_no / refund_order_no : *-apply \u2192 *-detail / *-confirm / pay-order (change)
 
 ## Invariants
@@ -7002,7 +7112,8 @@ Key notes:
 Workflow (typical order):
   1. find-airport      Resolve a place name \u2192 IATA city/airport codes
   2. search            Search flights (one-way/round-trip/multi-city). journeys carries ALL legs;
-                       relay --journey-id for round-trip/multi-city until price_key_ready is true
+                       round-trip/multi-city: relay the chosen offer's next_journey_ids into
+                       --journey-id until is_final_leg is true
   3. verify            Verify the fare \u2192 authoritative product_token + price_changed flag
   4. create-order      Create the order using verify's product_token (locks the fare, no charge)
   5. pay-order         Settle by --order-no (triggers ticketing); order \u2192 PAID