@gojinko/cli 2.22.1 → 2.24.0

package/dist/commands/price-monitoring.js

@@ -1,4 +1,4 @@
-import { withClient, output, resolveDeprecatedFlag } from './shared.js';
+import { withClient, output, resolveDeprecatedFlag, userIntentOption } from './shared.js';
 // price_monitoring — cache-only flight price snapshot for a fixed OD +
 // dates pair. JIN-256. Intended to be wired into a cron / scheduled job
 // so partners can track a route over time. On cache miss the surface returns
@@ -25,6 +25,7 @@ export function registerPriceMonitoringCommand(program) {
         .option('--max-price <amount>', 'upper bound on total fare. JSON: `max_price`.')
         .option('--include-carriers <codes...>', 'whitelist IATA 2-letter carrier codes (e.g. AF KL). JSON: `include_carriers`.')
         .option('--exclude-carriers <codes...>', 'blacklist IATA 2-letter carrier codes (e.g. FR U2). JSON: `exclude_carriers`.')
+        .addOption(userIntentOption())
         // Deprecated aliases — Phase 1 transition (JIN-665), remove in next major.
         .option('--from <origin>', 'DEPRECATED: use --origin.')
         .option('--to <destination>', 'DEPRECATED: use --destination.')

package/dist/commands/price-monitoring.js.map

@@ -1 +1 @@
-{"version":3,"file":"price-monitoring.js","sourceRoot":"","sources":["../../src/commands/price-monitoring.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAExE,uEAAuE;AACvE,wEAAwE;AACxE,6EAA6E;AAC7E,0EAA0E;AAC1E,6DAA6D;AAC7D,EAAE;AACF,8EAA8E;AAC9E,2DAA2D;AAC3D,MAAM,UAAU,8BAA8B,CAAC,OAAgB;IAC7D,OAAO;SACJ,OAAO,CAAC,kBAAkB,CAAC;SAC3B,OAAO,CAAC,kEAAkE,CAAC;SAC3E,WAAW,CACV,sWAAsW,CACvW;QACD,4EAA4E;SAC3E,MAAM,CAAC,iBAAiB,EAAE,mFAAmF,CAAC;SAC9G,MAAM,CAAC,sBAAsB,EAAE,6FAA6F,CAAC;SAC7H,MAAM,CACL,sBAAsB,EACtB,yEAAyE,EACzE,MAAM,CACP;SACA,MAAM,CACL,2BAA2B,EAC3B,mFAAmF,EACnF,MAAM,CACP;SACA,MAAM,CAAC,yBAAyB,EAAE,iEAAiE,CAAC;SACpG,MAAM,CAAC,sBAAsB,EAAE,+DAA+D,CAAC;SAC/F,MAAM,CAAC,cAAc,EAAE,0DAA0D,CAAC;SAClF,MAAM,CAAC,uBAAuB,EAAE,8EAA8E,CAAC;SAC/G,MAAM,CAAC,eAAe,EAAE,oDAAoD,CAAC;SAC7E,MAAM,CAAC,sBAAsB,EAAE,+CAA+C,CAAC;SAC/E,MAAM,CACL,+BAA+B,EAC/B,+EAA+E,CAChF;SACA,MAAM,CACL,+BAA+B,EAC/B,+EAA+E,CAChF;QACD,2EAA2E;SAC1E,MAAM,CAAC,iBAAiB,EAAE,2BAA2B,CAAC;SACtD,MAAM,CAAC,oBAAoB,EAAE,gCAAgC,CAAC;SAC9D,MAAM,CAAC,eAAe,EAAE,mCAAmC,CAAC;SAC5D,MAAM,CAAC,iBAAiB,EAAE,gCAAgC,CAAC;SAC3D,MAAM,CAAC,iBAAiB,EAAE,gCAAgC,CAAC;SAC3D,MAAM,CAAC,kBAAkB,EAAE,2BAA2B,CAAC;SACvD,MAAM,CACL,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE;QACzC,mDAAmD;QACnD,MAAM,MAAM,GAAG,qBAAqB,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;QACnF,MAAM,WAAW,GAAG,qBAAqB,CAAC,IAAI,CAAC,WAAW,EAAE,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,eAAe,CAAC,CAAC;QAC9F,MAAM,aAAa,GAAG,qBAAqB,CAAC,IAAI,CAAC,aAAa,EAAE,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,kBAAkB,CAAC,CAAC;QACzG,MAAM,UAAU,GAAG,qBAAqB,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,MAAM,EAAE,UAAU,EAAE,eAAe,CAAC,CAAC;QACpG,MAAM,UAAU,GAAG,qBAAqB,CAAC,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,KAAK,EAAE,SAAS,EAAE,eAAe,CAAC,CAAC;QAClG,MAAM,MAAM,GAAG,qBAAqB,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,cAAc,EAAE,UAAU,CAAC,CAAC;QAE/F,IAAI,CAAC,MAAM,IAAI,CAAC,WAAW,IAAI,CAAC,aAAa,EAAE,CAAC;YAC9C,OAAO,CAAC,KAAK,CAAC,oEAAoE,CAAC,CAAC;YACpF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;QAED,0EAA0E;QAC1E,MAAM,OAAO,GAA2B;YACtC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE;YACpC,WAAW,EAAE,IAAI,CAAC,UAAU,IAAI,MAAM;YACtC,WAAW,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC,WAAW,EAAE;YAC9C,gBAAgB,EAAE,IAAI,CAAC,eAAe,IAAI,MAAM;YAChD,cAAc,EAAE,aAAa;YAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC;YAC3B,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAClD,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAClD,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACjD,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9D,GAAG,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,gBAAgB,EAAE,IAAI,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC3E,GAAG,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,gBAAgB,EAAE,IAAI,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC5E,CAAC;QAEF,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;QAEvD,MAAM,CAAC,QAAQ,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC/C,CAAC,CAAC,CACH,CAAC;AACN,CAAC"}
+{"version":3,"file":"price-monitoring.js","sourceRoot":"","sources":["../../src/commands/price-monitoring.ts"],"names":[],"mappings":"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"}

package/dist/commands/refund.d.ts

@@ -1,40 +1,20 @@
 import { Command } from 'commander';
 /**
- * Validate the refund auth-mode inputs locally so partial-pair invocations
- * never propagate to the BFF as opaque 400s.
+ * Build a refund/exchange request body from CLI options.
  *
- * Two mutually exclusive modes:
- *   - Authenticated: --order-id
- *   - Guest:         --booking-ref + --last-name  (both required together)
- *
- * Throws a Commander-friendly string error (matches Commander's `.error()` /
- * thrown-string conventions) on invalid input.
- */
-export declare function validateAuthFields(opts: {
-    bookingRef?: string;
-    lastName?: string;
-    orderId?: string;
-}): void;
-/**
- * Build a refund request body from CLI options, picking the right auth mode.
- *
- * Guest auth: --booking-ref + --last-name (public; validated by BFF).
- * Authenticated: --order-id (DevPlatform OAuth / jnk_* keys).
- *
- * Exactly one mode must be provided — the BFF rejects mixed combinations.
+ * Auth is always `booking_ref` + `last_name` (required by the public spec —
+ * Commander enforces both via `requiredOption`, so they are guaranteed here).
  */
 export declare function buildAuthFields(opts: {
-    bookingRef?: string;
-    lastName?: string;
-    orderId?: string;
+    bookingRef: string;
+    lastName: string;
     provider?: string;
     ticketNumbers?: string[];
 }): {
     ticket_numbers?: string[] | undefined;
     provider?: string | undefined;
-    last_name?: string | undefined;
-    booking_ref?: string | undefined;
-    order_id?: string | undefined;
+    booking_ref: string;
+    last_name: string;
 };
 export declare function registerRefundCommand(program: Command): void;
 //# sourceMappingURL=refund.d.ts.map

package/dist/commands/refund.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"refund.d.ts","sourceRoot":"","sources":["../../src/commands/refund.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAMpC;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IACvC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,IAAI,CAiBP;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;;;;;;EASA;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CA2D5D"}
+{"version":3,"file":"refund.d.ts","sourceRoot":"","sources":["../../src/commands/refund.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGpC;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;;;;;EAOA;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAyD5D"}

package/dist/commands/refund.js

@@ -1,47 +1,14 @@
-import { withClient, output } from './shared.js';
-const AUTH_MODE_ERROR = 'Provide either --order-id OR both --booking-ref and --last-name (guest mode). Exactly one auth mode is required.';
+import { withClient, output, userIntentOption } from './shared.js';
 /**
- * Validate the refund auth-mode inputs locally so partial-pair invocations
- * never propagate to the BFF as opaque 400s.
+ * Build a refund/exchange request body from CLI options.
  *
- * Two mutually exclusive modes:
- *   - Authenticated: --order-id
- *   - Guest:         --booking-ref + --last-name  (both required together)
- *
- * Throws a Commander-friendly string error (matches Commander's `.error()` /
- * thrown-string conventions) on invalid input.
- */
-export function validateAuthFields(opts) {
-    const hasOrderId = Boolean(opts.orderId);
-    const hasBookingRef = Boolean(opts.bookingRef);
-    const hasLastName = Boolean(opts.lastName);
-    const hasGuestPair = hasBookingRef && hasLastName;
-    const hasPartialGuest = (hasBookingRef || hasLastName) && !hasGuestPair;
-    if (hasOrderId && (hasBookingRef || hasLastName)) {
-        throw new Error(AUTH_MODE_ERROR);
-    }
-    if (!hasOrderId && !hasGuestPair) {
-        throw new Error(AUTH_MODE_ERROR);
-    }
-    if (hasPartialGuest) {
-        // Unreachable given the two checks above, but kept explicit for readability.
-        throw new Error(AUTH_MODE_ERROR);
-    }
-}
-/**
- * Build a refund request body from CLI options, picking the right auth mode.
- *
- * Guest auth: --booking-ref + --last-name (public; validated by BFF).
- * Authenticated: --order-id (DevPlatform OAuth / jnk_* keys).
- *
- * Exactly one mode must be provided — the BFF rejects mixed combinations.
+ * Auth is always `booking_ref` + `last_name` (required by the public spec —
+ * Commander enforces both via `requiredOption`, so they are guaranteed here).
  */
 export function buildAuthFields(opts) {
-    validateAuthFields(opts);
     return {
-        ...(opts.orderId && { order_id: opts.orderId }),
-        ...(opts.bookingRef && { booking_ref: opts.bookingRef }),
-        ...(opts.lastName && { last_name: opts.lastName }),
+        booking_ref: opts.bookingRef,
+        last_name: opts.lastName,
         ...(opts.provider && { provider: opts.provider }),
         ...(opts.ticketNumbers && opts.ticketNumbers.length > 0 && { ticket_numbers: opts.ticketNumbers }),
     };
@@ -54,11 +21,11 @@ export function registerRefundCommand(program) {
         .command('check')
         .summary('Check refund eligibility and estimated amount')
         .description('Check refund eligibility and estimated amount.')
-        .option('--booking-ref <ref>', 'Jinko booking reference (guest auth, requires --last-name) [required: guest mode]')
-        .option('--last-name <name>', 'Last name of the primary traveler (guest auth) [required: guest mode]')
-        .option('--order-id <id>', 'DevPlatform order ID (authenticated auth) [required: authenticated mode]')
+        .requiredOption('--booking-ref <ref>', 'Jinko booking reference [required]')
+        .requiredOption('--last-name <name>', 'Last name of the primary traveler [required]')
         .option('--provider <provider>', 'override provider hint')
         .option('--ticket-numbers <numbers...>', 'one or more ticket numbers')
+        .addOption(userIntentOption())
         .action(withClient(async (client, globals, opts) => {
         const response = await client.refundCheck(buildAuthFields(opts));
         output(response, { format: globals.format });
@@ -67,11 +34,11 @@ export function registerRefundCommand(program) {
         .command('commit')
         .summary('Initiate a refund for a booked flight')
         .description('Initiate a refund for a booked flight.')
-        .option('--booking-ref <ref>', 'Jinko booking reference (guest auth, requires --last-name) [required: guest mode]')
-        .option('--last-name <name>', 'Last name of the primary traveler (guest auth) [required: guest mode]')
-        .option('--order-id <id>', 'DevPlatform order ID (authenticated auth) [required: authenticated mode]')
+        .requiredOption('--booking-ref <ref>', 'Jinko booking reference [required]')
+        .requiredOption('--last-name <name>', 'Last name of the primary traveler [required]')
         .option('--provider <provider>', 'override provider hint')
         .option('--ticket-numbers <numbers...>', 'one or more ticket numbers')
+        .addOption(userIntentOption())
         .action(withClient(async (client, globals, opts) => {
         const response = await client.refundCommit(buildAuthFields(opts));
         output(response, { format: globals.format });
@@ -80,17 +47,15 @@ export function registerRefundCommand(program) {
         .command('status')
         .summary('Check the status of a refund')
         .description('Poll the current status of a previously committed refund.')
-        .option('--booking-ref <ref>', 'Jinko booking reference (guest auth, requires --last-name) [required: guest mode]')
-        .option('--last-name <name>', 'Last name of the primary traveler (guest auth) [required: guest mode]')
-        .option('--order-id <id>', 'DevPlatform order ID (authenticated auth) [required: authenticated mode]')
+        .requiredOption('--booking-ref <ref>', 'Jinko booking reference [required]')
+        .requiredOption('--last-name <name>', 'Last name of the primary traveler [required]')
         .option('--refund-reference <ref>', 'refund reference returned by `refund commit`')
         .option('--provider <provider>', 'override provider hint')
+        .addOption(userIntentOption())
         .action(withClient(async (client, globals, opts) => {
-        validateAuthFields(opts);
         const response = await client.refundStatus({
-            ...(opts.orderId && { order_id: opts.orderId }),
-            ...(opts.bookingRef && { booking_ref: opts.bookingRef }),
-            ...(opts.lastName && { last_name: opts.lastName }),
+            booking_ref: opts.bookingRef,
+            last_name: opts.lastName,
             ...(opts.refundReference && { refund_reference: opts.refundReference }),
             ...(opts.provider && { provider: opts.provider }),
         });

package/dist/commands/refund.js.map

@@ -1 +1 @@
-{"version":3,"file":"refund.js","sourceRoot":"","sources":["../../src/commands/refund.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"refund.js","sourceRoot":"","sources":["../../src/commands/refund.ts"],"names":[],"mappings":"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"}

package/dist/commands/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/commands/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgMpC,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAmC5D"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/commands/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA6RpC,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAmC5D"}

package/dist/commands/schema.js

@@ -2,10 +2,26 @@ import { output } from "./shared.js";
 import { getGlobalOptions } from "../config/config.js";
 /**
  * Schema definitions for CLI commands. Names match MCP tools 1:1.
+ *
+ * HAND-MAINTAINED. This table is prose about the contract, not generated from
+ * `public-api.yaml` or `generated.ts`, so a spec sync does NOT update it —
+ * update it here when the contract moves. Last aligned to contract 0.3.0.
  */
+/**
+ * The identity a submitted offer echoes back on every item and booking (C11,
+ * as narrowed by D29). Optional throughout, and per kind: flights carry
+ * `offer_id` + `trip_item_token`, hotels carry `offer_id` + `hotel_id`.
+ */
+const IDENTITY_FIELDS = "offer_id?, trip_item_token? (flights), hotel_id? (hotels — the same id hotel_search publishes)";
+/** Terms captured for a quoted hotel item (C12). */
+const HOTEL_TERMS = '{ terms_as_of: "search" | "quote", is_refundable?, free_cancellation_until?, board_type?, board_name?, room_name?, room_capacity?, payment_types?, taxes_breakdown: [{ name, amount, currency, included }], cancellation_schedule: [{ cancel_time, amount, currency }] }? — hotels only. terms_as_of "search" means the terms were captured at search and NOT re-confirmed at quote. Cancellation timestamps are RFC 3339 with the supplier offset; a deadline the supplier gave no timezone for is omitted rather than published without one, so an absent free_cancellation_until does not mean non-refundable and a cancellation_schedule can be shorter than the supplier\'s own.';
+/** The closed public error enum (C15) — `error.code` is one of these twenty. */
+const ERROR_CODES = "error.code is a closed enum: AUTH_REQUIRED, PAYMENT_REQUIRED, RATE_LIMITED, BAD_REQUEST, FORBIDDEN, NOT_FOUND, CONFLICT, GONE (410, the generic 410 beneath QUOTE_EXPIRED and OFFER_EXPIRED — what the request named is gone for good, so repeating it cannot succeed), QUOTE_EXPIRED (410, carries expires_at and a numeric quoted_cart_id naming which quote lapsed), TRIP_EXPIRED (409, carries status), TRIP_STATE_CONFLICT (409, carries status), OFFER_EXPIRED, OFFER_UNAVAILABLE, MISSING_CUSTOMER_DETAILS, CURRENCY_UNSUPPORTED, UPSTREAM_REJECTED, UPSTREAM_UNAVAILABLE, UPSTREAM_TIMEOUT, UPSTREAM_ERROR, INTERNAL. Carried keys are SIBLINGS of error, never nested inside it.";
+/** Every lifecycle state a trip can report (C13). */
+const TRIP_STATUS = "draft | quoting | quoted | fulfillment_prepared | fulfilling | fulfilled | partially_fulfilled | failed | cancelled | expired";
 const SCHEMAS = {
     "find-destination": {
-        description: "Discover destinations from origin airports (POST /flights/destination-search).",
+        description: "Discover destinations from origin airports (POST /v1/find_destination).",
         request: {
             passengers: "{ adt: number }",
             filters: {
@@ -23,34 +39,74 @@ const SCHEMAS = {
             pagination: "{ next_page_token }",
             total: "number",
         },
+        money_format: "Money objects here are INTEGER MINOR UNITS: divide value by 10 ** decimal_places to display ({ value: 15977, decimal_places: 2 } is 159.77). See docs.gojinko.com/concepts/money.",
     },
     "flight-search": {
-        description: "Live flight search or price-check a specific offer (POST /flights/shop).",
+        description: "Live flight search or price-check a specific offer (POST /v1/flight_search).",
         request: {
             mode_a_search: {
-                origin: "string (IATA code)",
-                destination: "string (IATA code)",
+                origin: "string (IATA city or airport code)",
+                destination: "string (IATA city or airport code)",
+                origin_type: "city | airport? (omit to let the platform classify the code)",
+                destination_type: "city | airport?",
                 departure_date: "string (YYYY-MM-DD)",
                 return_date: "string? (YYYY-MM-DD)",
                 trip_type: "oneway | roundtrip",
-                cabin_class: "economy | premium_economy | business | first",
-                direct_only: "boolean?",
-                max_price: "number?",
-                passengers: "{ adults?: number, children?: number, infants?: number }",
+                cabin_class: "economy | premium_economy | business | first (advisory — never appears in applied_filters)",
+                adults: "number (default 1)",
+                children: "number?",
+                infants: "number?",
+                max_stops: "number? (0 non-stop, 1, 2 — per leg)",
+                direct_only: "boolean? (DEPRECATED alias of max_stops: 0)",
+                multi_fare: "boolean? (branded fare ladder; default true)",
+                max_price: "number? (total for all passengers, in currency, major units)",
+                include_carriers: "string[]? (IATA 2-letter)",
+                exclude_carriers: "string[]? (IATA 2-letter, must not overlap include_carriers)",
+                departure_time_range: '{ earliest?: "HH:MM", latest?: "HH:MM" }? (outbound leg)',
+                arrival_time_range: "{ earliest?, latest? }? (outbound leg)",
+                return_departure_time_range: "{ earliest?, latest? }? (return leg)",
+                return_arrival_time_range: "{ earliest?, latest? }? (return leg)",
+                connection_time_min_minutes: "number? (must not exceed the max)",
+                connection_time_max_minutes: "number?",
+                max_total_duration_minutes: "number? (per leg, door to door)",
+                refundable_only: "boolean? (conservative — fares whose rules cannot be verified are dropped)",
+                changeable_only: "boolean? (conservative in the same way)",
+                checked_bag_included: "boolean?",
+                single_carrier_only: "boolean?",
+                via_airports: "string[]? (at least one connection must be one of them)",
+                exclude_via_airports: "string[]? (must not overlap via_airports)",
+                aircraft_types: "string[]? (IATA equipment codes, every segment)",
+                origin_alternate_airports: "string[]? (ADDITIONAL departure airports beside origin; airport anchor only — against a city anchor it comes back under `origin` in unapplied_filters)",
+                destination_alternate_airports: "string[]? (same rules, reported as `destination`)",
+                nearby_airports: "boolean? (widening)",
+                same_connection_airport_only: "boolean?",
+                same_origin_airport_only: "boolean?",
+                same_turnaround_airport_only: "boolean?",
+                limit: "number? (1-300 TOTAL flights, not a page size; search mode only)",
+                currency: "string? (ISO 4217)",
+                locale: "string?",
             },
             mode_b_price_check: {
                 offer_token: "string (from flight-search or flight-calendar results)",
-                passengers: "{ adults?: number, children?: number, infants?: number }",
+                adults: "number (default 1)",
+                children: "number?",
+                infants: "number?",
+                currency: "string?",
+                locale: "string?",
+                note: "search-mode fields are rejected beside offer_token",
             },
         },
         response: {
-            mode: "search | price_check",
-            flights: "[{ offer_token, origin, destination, total_price, currency, outbound_*, inbound_*, fares? }]",
-            fares: "(price_check only) [{ trip_item_token, brand_name, cabin_class, total_price, is_refundable, ... }]",
+            offers: "[{ offer_id, provider, origin, destination, is_round_trip, total_duration_minutes, outbound, inbound, additional_legs, fares }]",
+            fares: "offers[].fares: [{ trip_item_token, brand_name, cabin_class, total_price, price_per_person, included_baggage, is_refundable, is_changeable, checked_bag_included }]",
+            exact_match_found: "boolean?",
+            applied_filters: "string[] — requested filters these results DO honor (alternate-airport lists reported per side as `origin` / `destination`)",
+            unapplied_filters: "[{ name, reason }] — requested filters these results do NOT honor; post-filter yourself or tell the user the constraint could not be met",
         },
+        money_format: "Money objects here are INTEGER MINOR UNITS: divide value by 10 ** decimal_places to display ({ value: 15977, decimal_places: 2 } is 159.77). See docs.gojinko.com/concepts/money.",
     },
     "flight-calendar": {
-        description: "Cheapest prices across a date range (POST /flights/search with date range).",
+        description: "Cheapest prices across a date range (POST /v1/flight_calendar).",
         request: {
             from: "string (IATA code, origin)",
             to: "string (IATA code, destination)",
@@ -61,27 +117,30 @@ const SCHEMAS = {
         response: {
             itineraries: "[{ id, slices, total_amount, ... }]",
         },
+        money_format: "Money objects here are INTEGER MINOR UNITS: divide value by 10 ** decimal_places to display ({ value: 15977, decimal_places: 2 } is 159.77). See docs.gojinko.com/concepts/money.",
     },
     trip: {
-        description: "Manage a trip: create, add/remove flight items, set travelers (POST /shop/sync).",
+        description: "Manage a trip: create, add/remove flight items, set travelers (POST /v1/trip).",
         request: {
             trip_id: "string? (omit to create new)",
             add_item: "{ trip_item_token: string }? (from flight-search)",
             remove_item: "{ item_id: string }? (item_id from prior trip response items[].item_id; requires trip_id; can be combined with add_item to swap in one call)",
-            upsert_travelers: "{ travelers: [{ first_name, last_name, passenger_type, date_of_birth?, gender?, frequent_flyer?: { airline, number }, ... }], contact?: { email, phone } }? (travelers + contact email/phone required to book; date_of_birth + gender required for flights, optional for hotel-only; contact name taken from first traveler)",
+            upsert_travelers: "{ travelers: [{ first_name, last_name, passenger_type, date_of_birth?, gender?, frequent_flyer?: { airline, number }, known_traveler_number?, known_traveler_issuing_country?, redress_number?, redress_issuing_country?, ... }], contact?: { email, phone } }? (travelers + contact email/phone required to book; date_of_birth + gender required for flights, optional for hotel-only; KTN/redress issuing countries default to US; contact name taken from first traveler)",
         },
         response: {
             trip_id: "string",
-            status: "string",
-            items: "[{ item_id, type, description, price, currency }]",
+            status: TRIP_STATUS,
+            items: `[{ item_id, type, description, price, currency, ${IDENTITY_FIELDS} }]`,
             travelers: "[...]",
             contact: "{ email, phone }",
             totals: "{ total, currency }",
             actions_performed: "string[]",
         },
+        error_codes: ERROR_CODES,
+        money_format: "Amounts here are already MAJOR units (plain decimals, no decimal_places) — display as-is, do not divide. See docs.gojinko.com/concepts/money.",
     },
     checkout: {
-        description: "Checkout a trip — returns the web checkout_url a human opens to pay, the agent_spt_params an agent uses to pay programmatically, plus cart items and ancillaries (POST /shop/sync/checkout). `book` is a deprecated alias.",
+        description: "Checkout a trip — returns the web checkout_url a human opens to pay, the agent_spt_params an agent uses to pay programmatically, plus cart items and ancillaries (POST /v1/checkout). `book` is a deprecated alias.",
         request: {
             trip_id: "string (from trip command)",
         },
@@ -90,29 +149,35 @@ const SCHEMAS = {
             checkout_url: "string (human payment URL)",
             expires_at: "string? (ISO datetime)",
             status: "ready | pending | failed",
-            total_amount: "{ amount: number, currency: string }?",
-            agent_spt_params: "{ max_amount: number, currency: string, stripe_profile?: string, expires_at?: string }? (mint an SPT scoped to these, then call agent-pay submit)",
-            items: "[{ item_id, kind, price, pax_count, available_ancillaries: [...], selected_ancillaries: [...] }]",
+            total_amount: "{ amount: number, currency: string }? (amount is MAJOR units — display as-is)",
+            agent_spt_params: "{ max_amount: number, currency: string, stripe_profile?: string, expires_at?: string }? (mint an SPT scoped to these, then call agent-pay submit; max_amount is an INTEGER in MINOR units per Stripe convention — the one exception to the no-decimal_places-means-major rule)",
+            items: `[{ item_id, kind, price, pax_count, ${IDENTITY_FIELDS}, hotel_terms?, available_ancillaries: [...], selected_ancillaries: [...] }]`,
+            "items[].hotel_terms": HOTEL_TERMS,
         },
+        error_codes: ERROR_CODES,
     },
     "trip-status": {
-        description: "Full lifecycle state for a trip: cart, quote, fulfillment, bookings (GET /shop/sync/:id).",
+        description: "Full lifecycle state for a trip: cart, quote, fulfillment, bookings (GET /v1/trip/:trip_id).",
         request: {
             trip_id: "string",
         },
         response: {
             trip_id: "string",
-            status: "draft | quoting | quoted | fulfillment_prepared | fulfilling | fulfilled | partially_fulfilled | failed | cancelled",
+            status: TRIP_STATUS,
             travelers: "[...]",
             contact: "{ email?, phone? }?",
-            items: "[{ item_id, kind, price, pax_count, available_ancillaries, selected_ancillaries }]",
+            items: `[{ item_id, kind, price, pax_count, ${IDENTITY_FIELDS}, hotel_terms?, available_ancillaries, selected_ancillaries }]`,
+            "items[].hotel_terms": HOTEL_TERMS,
             total_amount: "{ amount, currency }?",
             quote: "{ quoted_cart_id, status, expires_at? }?",
             fulfillment: "{ fulfillment_cart_id, status, phase?, scheduled_at? }?",
-            bookings: "[{ item_id, kind, booking_reference, pnr?, provider_status? }]?",
+            booking_ref: "string? (the Jinko booking reference, JNK-XXXXXX — the value get-booking, hotel-cancel, refund and exchange take as --booking-ref, and the booking_ref every webhook event carries. Present as soon as a fulfillment cart exists for the trip — i.e. once fulfillment has been scheduled, which can be before payment completes (a hosted checkout still in progress, or an agent-pay submit that fell back to checkout_url, leaves the cart awaiting_payment). Presence does not mean paid: read fulfillment.status. The value never changes afterwards. One per trip.)",
+            bookings: `[{ item_id, kind, booking_reference (the SUPPLIER confirmation — airline record locator / hotel confirmation number, NOT the get-booking handle), pnr?, provider_status?, ${IDENTITY_FIELDS} }]?`,
             created_at: "string (ISO)",
             updated_at: "string (ISO)",
         },
+        error_codes: ERROR_CODES,
+        money_format: "price and price_per_unit are { amount, currency } in MAJOR units — display as-is. See docs.gojinko.com/concepts/money.",
     },
     "get-ancillaries": {
         description: "List the purchasable ancillaries for a trip (bags, seats, meals) without generating a checkout URL. Runs a quote transparently and polls until ready (GET /v1/trip/:id/ancillaries).",
@@ -125,11 +190,13 @@ const SCHEMAS = {
             quoted_cart_id: "number?",
             expires_at: "string (ISO)?",
             retry_after_seconds: "number? (present when status=pricing)",
-            items: "[{ item_id, kind, price, pax_count, available_ancillaries: [{ offer_id, type, label, display_label, price_per_unit, per_pax, max_quantity }], selected_ancillaries }]",
+            items: `[{ item_id, kind, price, pax_count, ${IDENTITY_FIELDS}, hotel_terms?, available_ancillaries: [{ offer_id, type, label, display_label, price_per_unit, per_pax, max_quantity }], selected_ancillaries }]`,
+            "items[].hotel_terms": HOTEL_TERMS,
         },
+        error_codes: ERROR_CODES,
     },
     "select-ancillaries": {
-        description: "Select bags / seats / meals for a trip item (POST /shop/sync/ancillaries).",
+        description: "Select bags / seats / meals for a trip item (POST /v1/select_ancillaries).",
         request: {
             trip_id: "string",
             item_id: "string",
@@ -139,6 +206,7 @@ const SCHEMAS = {
             trip_id: "string",
             items: "[...]",
         },
+        money_format: "total_with_ancillaries is { amount: INTEGER MINOR units, currency, decimal_places } — divide amount by 10 ** decimal_places to display. See docs.gojinko.com/concepts/money.",
     },
     "agent-pay": {
         description: "One-call programmatic payment with a Shared Payment Token — the alternative to opening `checkout`'s checkout URL. Get `agent_spt_params` from `checkout`, mint an SPT scoped to them, then `agent-pay submit` presents trip_id + the SPT: the BFF schedules the agent fulfillment and redeems the token (POST /v1/agent_payment/submit).",
@@ -154,10 +222,12 @@ const SCHEMAS = {
                 status: "string",
                 payment_verified: "boolean",
                 message: "string?",
+                booking_ref: "string? (the Jinko booking reference, JNK-XXXXXX, for the trip just paid — hand it to get-booking, hotel-cancel, refund or exchange as --booking-ref. Present when the token was authorized; absent when the payment could not be authorized and checkout_url is returned instead.)",
                 checkout_url: "string? (hosted-checkout fallback, present only on a 3DS step-up / decline)",
                 recap_token: "string?",
             },
         },
+        error_codes: ERROR_CODES,
     },
 };
 export function registerSchemaCommand(program) {

package/dist/commands/schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/commands/schema.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/commands/schema.ts"],"names":[],"mappings":"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"}

package/dist/commands/select-ancillaries.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"select-ancillaries.d.ts","sourceRoot":"","sources":["../../src/commands/select-ancillaries.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGpC,wBAAgB,gCAAgC,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAkCvE"}
+{"version":3,"file":"select-ancillaries.d.ts","sourceRoot":"","sources":["../../src/commands/select-ancillaries.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGpC,wBAAgB,gCAAgC,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAmCvE"}

package/dist/commands/select-ancillaries.js

@@ -1,4 +1,4 @@
-import { withClient, output } from './shared.js';
+import { withClient, output, userIntentOption } from './shared.js';
 export function registerSelectAncillariesCommand(program) {
     program
         .command('select-ancillaries')
@@ -9,6 +9,7 @@ export function registerSelectAncillariesCommand(program) {
         .requiredOption('--select <ids>', 'comma-separated ancillary offer IDs [required]')
         .option('--pax <ref>', 'passenger reference (for per-pax ancillaries)')
         .option('--quantity <n>', 'quantity (default: 1)', '1')
+        .addOption(userIntentOption())
         .action(withClient(async (client, globals, opts) => {
         const parsedQuantity = parseInt(opts.quantity, 10);
         if (Number.isNaN(parsedQuantity)) {

package/dist/commands/select-ancillaries.js.map

@@ -1 +1 @@
-{"version":3,"file":"select-ancillaries.js","sourceRoot":"","sources":["../../src/commands/select-ancillaries.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAEjD,MAAM,UAAU,gCAAgC,CAAC,OAAgB;IAC/D,OAAO;SACJ,OAAO,CAAC,oBAAoB,CAAC;SAC7B,OAAO,CAAC,4DAA4D,CAAC;SACrE,WAAW,CACV,yWAAyW,CAC1W;SACA,cAAc,CAAC,gBAAgB,EAAE,oBAAoB,CAAC;SACtD,cAAc,CAAC,gBAAgB,EAAE,yBAAyB,CAAC;SAC3D,cAAc,CAAC,gBAAgB,EAAE,gDAAgD,CAAC;SAClF,MAAM,CAAC,aAAa,EAAE,+CAA+C,CAAC;SACtE,MAAM,CAAC,gBAAgB,EAAE,uBAAuB,EAAE,GAAG,CAAC;SACtD,MAAM,CAAC,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE;QACjD,MAAM,cAAc,GAAG,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;QACnD,IAAI,MAAM,CAAC,KAAK,CAAC,cAAc,CAAC,EAAE,CAAC;YACjC,OAAO,CAAC,KAAK,CAAC,2CAA2C,CAAC,CAAC;YAC3D,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;YACrB,OAAO;QACT,CAAC;QAED,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,OAAe,EAAE,EAAE,CAAC,CAAC;YAClE,QAAQ,EAAE,OAAO,CAAC,IAAI,EAAE;YACxB,GAAG,CAAC,IAAI,CAAC,GAAG,IAAI,EAAE,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC;YACzC,GAAG,CAAC,cAAc,KAAK,CAAC,IAAI,EAAE,QAAQ,EAAE,cAAc,EAAE,CAAC;SAC1D,CAAC,CAAC,CAAC;QAEJ,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,iBAAiB,CAAC;YAC9C,OAAO,EAAE,IAAI,CAAC,MAAM;YACpB,OAAO,EAAE,IAAI,CAAC,MAAM;YACpB,UAAU;SACX,CAAC,CAAC;QAEH,MAAM,CAAC,QAAQ,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC/C,CAAC,CAAC,CAAC,CAAC;AACR,CAAC"}
+{"version":3,"file":"select-ancillaries.js","sourceRoot":"","sources":["../../src/commands/select-ancillaries.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEnE,MAAM,UAAU,gCAAgC,CAAC,OAAgB;IAC/D,OAAO;SACJ,OAAO,CAAC,oBAAoB,CAAC;SAC7B,OAAO,CAAC,4DAA4D,CAAC;SACrE,WAAW,CACV,yWAAyW,CAC1W;SACA,cAAc,CAAC,gBAAgB,EAAE,oBAAoB,CAAC;SACtD,cAAc,CAAC,gBAAgB,EAAE,yBAAyB,CAAC;SAC3D,cAAc,CAAC,gBAAgB,EAAE,gDAAgD,CAAC;SAClF,MAAM,CAAC,aAAa,EAAE,+CAA+C,CAAC;SACtE,MAAM,CAAC,gBAAgB,EAAE,uBAAuB,EAAE,GAAG,CAAC;SACtD,SAAS,CAAC,gBAAgB,EAAE,CAAC;SAC7B,MAAM,CAAC,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE;QACjD,MAAM,cAAc,GAAG,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;QACnD,IAAI,MAAM,CAAC,KAAK,CAAC,cAAc,CAAC,EAAE,CAAC;YACjC,OAAO,CAAC,KAAK,CAAC,2CAA2C,CAAC,CAAC;YAC3D,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;YACrB,OAAO;QACT,CAAC;QAED,MAAM,UAAU,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,OAAe,EAAE,EAAE,CAAC,CAAC;YAClE,QAAQ,EAAE,OAAO,CAAC,IAAI,EAAE;YACxB,GAAG,CAAC,IAAI,CAAC,GAAG,IAAI,EAAE,UAAU,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC;YACzC,GAAG,CAAC,cAAc,KAAK,CAAC,IAAI,EAAE,QAAQ,EAAE,cAAc,EAAE,CAAC;SAC1D,CAAC,CAAC,CAAC;QAEJ,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,iBAAiB,CAAC;YAC9C,OAAO,EAAE,IAAI,CAAC,MAAM;YACpB,OAAO,EAAE,IAAI,CAAC,MAAM;YACpB,UAAU;SACX,CAAC,CAAC;QAEH,MAAM,CAAC,QAAQ,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAC/C,CAAC,CAAC,CAAC,CAAC;AACR,CAAC"}

package/dist/commands/shared.d.ts

@@ -1,4 +1,4 @@
-import type { Command } from 'commander';
+import { Option, type Command } from 'commander';
 import { type JinkoClient } from '@gojinko/api-client';
 import { type GlobalOptions } from '../config/config.js';
 import { output, outputError } from '../output/formatter.js';
@@ -30,6 +30,19 @@ export declare function exitWithError(err: unknown, globals: GlobalOptions): nev
  * Returns the resolved canonical value so callers can use it inline.
  */
 export declare function resolveDeprecatedFlag<T>(canonical: T | undefined, deprecated: T | undefined, oldFlag: string, newFlag: string): T | undefined;
+/**
+ * Fresh `--user-intent` option for the intent-eligible commands — the CLI
+ * commands whose underlying API call is one of the 21 public POST operations
+ * that accept the optional `intent: { user_intent }` request-body envelope
+ * (IntentInput). Each eligible leaf registers its own instance via
+ * `.addOption(userIntentOption())`: Commander Options must not be shared
+ * across commands, and the docs generator only documents leaf options, so a
+ * root/global option would be invisible on the generated pages. withClient
+ * threads the parsed value into the api-client, which merges it into the
+ * POST body. Falls back to the JINKO_USER_INTENT env var when the flag is
+ * not given (Commander `.env()`).
+ */
+export declare function userIntentOption(): Option;
 /**
  * Build the source-native action string for the `X-Origin-Action` header: the
  * invoked CLI command path (e.g. `flight-search`, `book`, `auth login`),

package/dist/commands/shared.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/commands/shared.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAA0C,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAC/F,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAC3E,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAE7D,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;AAC/B,YAAY,EAAE,aAAa,EAAE,CAAC;AAE9B,iEAAiE;AACjE,qBAAa,UAAW,SAAQ,KAAK;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBACV,OAAO,EAAE,MAAM,EAAE,IAAI,SAAkB;CAKpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,aAAa,GAAG,KAAK,CAezE;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EACrC,SAAS,EAAE,CAAC,GAAG,SAAS,EACxB,UAAU,EAAE,CAAC,GAAG,SAAS,EACzB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GACd,CAAC,GAAG,SAAS,CAMf;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAY/E;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,CACP,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,aAAa,EAEtB,OAAO,CAAC,EAAE,GAAG,EACb,GAAG,CAAC,EAAE,OAAO,KACV,OAAO,CAAC,IAAI,CAAC,IAGK,MAAM,OAAO,EAAE,GAAG,MAAM,GAAG,EAAE,mBA8BrD"}
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/commands/shared.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,KAAK,OAAO,EAAE,MAAM,WAAW,CAAC;AACjD,OAAO,EAA0C,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAC/F,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAC3E,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAE7D,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;AAC/B,YAAY,EAAE,aAAa,EAAE,CAAC;AAE9B,iEAAiE;AACjE,qBAAa,UAAW,SAAQ,KAAK;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBACV,OAAO,EAAE,MAAM,EAAE,IAAI,SAAkB;CAKpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,EAAE,aAAa,GAAG,KAAK,CAkBzE;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EACrC,SAAS,EAAE,CAAC,GAAG,SAAS,EACxB,UAAU,EAAE,CAAC,GAAG,SAAS,EACzB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GACd,CAAC,GAAG,SAAS,CAMf;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,CAKzC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAY/E;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACxB,OAAO,EAAE,CACP,MAAM,EAAE,WAAW,EACnB,OAAO,EAAE,aAAa,EAEtB,OAAO,CAAC,EAAE,GAAG,EACb,GAAG,CAAC,EAAE,OAAO,KACV,OAAO,CAAC,IAAI,CAAC,IAGK,MAAM,OAAO,EAAE,GAAG,MAAM,GAAG,EAAE,mBAuCrD"}

package/dist/commands/shared.js

@@ -1,3 +1,4 @@
+import { Option } from 'commander';
 import { createJinkoClient, ApiError, AuthError } from '@gojinko/api-client';
 import { getGlobalOptions } from '../config/config.js';
 import { output, outputError } from '../output/formatter.js';
@@ -30,7 +31,7 @@ export function exitWithError(err, globals) {
         process.exit(2);
     }
     if (err instanceof ApiError) {
-        outputError({ code: err.code, message: err.message, doc_url: err.docUrl }, globals);
+        outputError({ code: err.code, message: err.message, doc_url: err.docUrl, details: err.details }, globals);
         process.exit(1);
     }
     outputError({ message: err instanceof Error ? err.message : String(err) }, globals);
@@ -53,6 +54,21 @@ export function resolveDeprecatedFlag(canonical, deprecated, oldFlag, newFlag) {
     }
     return canonical;
 }
+/**
+ * Fresh `--user-intent` option for the intent-eligible commands — the CLI
+ * commands whose underlying API call is one of the 21 public POST operations
+ * that accept the optional `intent: { user_intent }` request-body envelope
+ * (IntentInput). Each eligible leaf registers its own instance via
+ * `.addOption(userIntentOption())`: Commander Options must not be shared
+ * across commands, and the docs generator only documents leaf options, so a
+ * root/global option would be invisible on the generated pages. withClient
+ * threads the parsed value into the api-client, which merges it into the
+ * POST body. Falls back to the JINKO_USER_INTENT env var when the flag is
+ * not given (Commander `.env()`).
+ */
+export function userIntentOption() {
+    return new Option('--user-intent <text>', "the end user's request in their own words, forwarded to Jinko for observability and relevance (avoid PII). Env fallback: JINKO_USER_INTENT. JSON: `intent.user_intent`.").env('JINKO_USER_INTENT');
+}
 /**
  * Build the source-native action string for the `X-Origin-Action` header: the
  * invoked CLI command path (e.g. `flight-search`, `book`, `auth login`),
@@ -98,6 +114,9 @@ export function withClient(handler) {
                 environment: globals.environment,
                 originSource: 'cli',
                 originAction: resolveCommandPath(cmd),
+                // Only intent-eligible commands register the flag (userIntentOption),
+                // so this stays undefined — and the body untouched — everywhere else.
+                userIntent: typeof cmdOpts?.userIntent === 'string' ? cmdOpts.userIntent : undefined,
             });
             await handler(client, globals, cmdOpts, cmd);
         }
@@ -107,7 +126,10 @@ export function withClient(handler) {
                 process.exit(2);
             }
             if (error instanceof ApiError) {
-                outputError({ code: error.code, message: error.message, doc_url: error.docUrl }, globals);
+                // `details` carries the envelope keys that sit beside `error` (D27) —
+                // expires_at, status, items — which is what tells the caller what to do
+                // next about the code they just got.
+                outputError({ code: error.code, message: error.message, doc_url: error.docUrl, details: error.details }, globals);
                 process.exit(1);
             }
             if (error instanceof Error) {