@gojinko/plugin 2.23.0 → 2.24.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "jinko",
   "description": "Search flights, book trips, and manage bookings with the Jinko Travel API. Connects to the Jinko MCP server for live flight pricing, trip management, and payment.",
-  "version": "2.23.0",
+  "version": "2.24.0",
   "author": {
     "name": "Jinko",
     "url": "https://gojinko.com"

package/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "jinko",
   "description": "Search flights, book trips, and manage bookings with the Jinko Travel API. Connects to the Jinko MCP server for live flight pricing, trip management, and payment.",
-  "version": "2.23.0",
+  "version": "2.24.0",
   "author": {
     "name": "Jinko",
     "url": "https://gojinko.com"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gojinko/plugin",
-  "version": "2.23.0",
+  "version": "2.24.0",
   "description": "Jinko Travel plugin for Claude Code and OpenAI Codex — flight search, booking, and trip management via MCP",
   "private": false,
   "license": "MIT",

package/skills/book-trip/SKILL.md

@@ -28,26 +28,61 @@ Two modes (use exactly one):
     "departure_date": "2026-06-15",
     "return_date": "2026-06-22",
     "cabin_class": "economy",
-    "direct_only": false
+    "max_stops": 1,
+    "checked_bag_included": true
   },
-  "passengers": { "adults": 1, "children": 0, "infants": 0 }
+  "traveler_counts": { "adults": 1, "children": 0, "infants": 0 },
+  "currency": "EUR"
 }
 ```
 
+`search` carries the whole shop filter contract. What to reach for:
+
+- **Stops:** `max_stops` (0-2) — send `max_stops: 0` when the user says "direct", "non-stop", "no layovers". `direct_only` is its deprecated alias: `true` is folded into `max_stops: 0`, the filter report always names `max_stops`, and sending it beside a non-zero `max_stops` is an error.
+- **Time of day:** `departure_time_range` / `arrival_time_range` filter the OUTBOUND leg, `return_departure_time_range` / `return_arrival_time_range` the RETURN leg. Each is `{ "earliest": "08:00", "latest": "12:00" }`, and either bound may be omitted.
+- **Fares:** `refundable_only`, `changeable_only`, `checked_bag_included`.
+- **Routing:** `single_carrier_only`, `include_carriers` / `exclude_carriers`, `via_airports` / `exclude_via_airports`, `aircraft_types`, `connection_time_min_minutes` / `connection_time_max_minutes`, `max_total_duration_minutes`, `same_connection_airport_only`, `same_origin_airport_only`, `same_turnaround_airport_only`.
+- **Widening:** `origin_alternate_airports` / `destination_alternate_airports`, `nearby_airports`, `date_flexibility_days` (0-3, for "give or take a day" — anything wider is a `flight_calendar` query).
+- **Size and shape:** `multi_fare` defaults to true (the branded fare ladder; set it false for one fare per itinerary and a much smaller response), `limit` is the TOTAL number of flights returned (1-300), not a page size.
+- **`cabin_class` is ADVISORY**, not a filter: it is forwarded to the providers as a preference and they may still return other cabins. It never appears in `applied_filters` — read each fare's own `cabin_class`.
+
+**Alternate airports widen an AIRPORT anchor:**
+```json
+{
+  "search": {
+    "origin": "JFK",
+    "origin_alternate_airports": ["EWR", "LGA"],
+    "destination": "CDG",
+    "departure_date": "2026-06-15"
+  }
+}
+```
+The anchor is always searched, and it ranks and truncates the result set — so put the airport that matters most to the user in `origin` / `destination`, not in the list. Against a city anchor (`origin_type: "city"`, or a code that resolves to a city) the search still runs and the list is ignored: it comes back in `unapplied_filters`, which is a warning to relay, not an error. On a round trip the whole side is mirrored onto the return leg.
+
 **Price-check** (user has an `offer_token` — e.g. from a prior `flight_calendar` or legacy `find_flight` result):
 ```json
 {
   "price_check": {
-    "offer_token": "es-abc123..."
+    "offer_token": "es-abc123...",
+    "direct_only": true,
+    "cabin_class": "economy"
   }
 }
 ```
 
-**Response:** Flights with fare options. Each fare includes a `trip_item_token`. If status is `"flight_unavailable"`, show alternatives — do NOT proceed to booking.
+ALWAYS carry forward the filters that were on the call which produced the token — `direct_only`, `cabin_class`, `max_price`, `include_carriers`, `exclude_carriers`. The BFF reshops the closest match, and without them it can return a candidate that violates what the user picked (a stopover after they asked for direct). The wider shop filters (`max_stops`, `refundable_only`, the time ranges, …) belong to `search` only.
+
+**Response:** Flights with fare options. Each fare includes a `trip_item_token` plus `refundable` / `changeable` / `checked_bag_included` booleans you can re-check yourself. If status is `"flight_unavailable"`, show alternatives — do NOT proceed to booking.
+
+The result also carries `applied_filters` (the filters this result set enforces) and `unapplied_filters` (the ones no provider could enforce, each with a `name` and a `reason`), plus a one-sentence `filters_notice` when something went unapplied. **Anything in `unapplied_filters` was NOT enforced** — the flights are not narrowed by it, so apply it yourself or tell the user the constraint could not be met. Both lists name the leg SIDE for the alternate-airport lists: an `origin_alternate_airports` / `destination_alternate_airports` list is reported as `origin` / `destination`, never under the field name you sent.
 
 **Rules:**
+- Exactly one of `search` or `price_check` per call
 - Origin and destination must differ
-- Departure date must be in the future
+- Departure date must be in the future, and `return_date` on or after `departure_date`
+- Single dates only — no arrays, no ranges (bounded flexibility goes in `date_flexibility_days`)
+- `connection_time_min_minutes` must not exceed `connection_time_max_minutes`; `include_carriers` must not overlap `exclude_carriers`, nor `via_airports` overlap `exclude_via_airports`
+- Traveler counts: adults 1-9, children 0-8, infants 0-4
 - Infants cannot exceed adults
 - Total passengers max 9
 
@@ -138,7 +173,9 @@ Categories: `BAGGAGE`, `SEAT`, `MEAL`, etc.
 
 Single synchronous call. The BFF schedules the quote, polls until it completes, schedules fulfillment, and returns a canonical Jinko-hosted checkout URL of the form `https://app.gojinko.com/checkout?sid=<cart_id>`. The user opens this URL in a browser; the Jinko `/checkout` page collects any remaining info and triggers the right Stripe flow (embedded Elements or Hosted Checkout) at Pay-button click. Stripe webhooks finalize the booking automatically — no client-side confirm step is required.
 
-**Response includes:** `checkout_url`, `session_id`, `total_amount`, `items`.
+**Response includes:** `checkout_url`, `session_id`, `total_amount`, `items`, and on any item the provider re-priced between search and quote, `price_change`.
+
+`price_change` carries `original` (the price shown at search), `current` (the price about to be charged) and `delta` (`current` minus `original`, signed); it is absent when the two prices are the same. Checkout proceeds at `current` — tell the user the new price before they open the checkout URL.
 
 ## Optional: Check trip status — `get_trip`
 
@@ -150,6 +187,8 @@ Single synchronous call. The BFF schedules the quote, polls until it completes,
 
 Returns the full trip lifecycle state: cart contents, travelers, quote status, fulfillment status, booking references. Use after booking to verify confirmation or anytime to inspect the trip.
 
+Once fulfillment has been scheduled the response carries a top-level `booking_ref` (`JNK-…`): the Jinko booking reference, which is the `booking_ref` that `get_booking`, hotel cancel, refund and exchange take. It can be present before payment completes (a hosted checkout still in progress, or an agent submit that fell back to `checkout_url`, leaves the cart `awaiting_payment`), so presence does not mean paid — read `fulfillment.status`. `bookings[].booking_reference` is the supplier's own confirmation (airline record locator, hotel confirmation number), not that handle. An agent paying with a Shared Payment Token never sees the checkout page, so `submit_agent_payment` returns the same `booking_ref` once the token is authorized.
+
 ## Important rules
 
 - **Never skip steps** — each depends on the previous

package/skills/cli/SKILL.md

@@ -45,14 +45,14 @@ Prod and sandbox keys are stored separately in `~/.jinko/config.yaml`. Precedenc
 | `auth login / logout / status` | Credentials |
 | `find-destination` | Discover destinations from origin(s) — inspiration |
 | `flight-calendar` | Cheapest prices across a date range for a specific route |
-| `flight-search` | Live pricing — direct search by route + dates, or `--offer-token` price-check (returns bookable `trip_item_token`) |
+| `flight-search` | Live pricing — direct search by route + dates, or `--offer-token` price-check (returns bookable `trip_item_token`). Full shop filter set: `--max-stops`, `--departure-time-range`, `--connection-time-*-minutes`, `--refundable-only`, `--checked-bag-included`, `--via-airports`, `--origin-alternate-airports`, … |
 | `hotel-search` | Live hotel search by city/query/geo/hotel-ids |
 | `hotel-details` | Rich metadata (gallery, facilities, policies, per-room details) for a single hotel |
 | `trip` | Create / update a trip: add items, remove items, set travelers + contact |
 | `select-ancillaries` | Add baggage / seats / meals to a trip item |
 | `checkout` | Finalize a trip → returns `checkout_url` (human pays in browser) + `agent_spt_params` (agent pays programmatically). `book` is a deprecated alias. |
-| `agent-pay submit` | Pay programmatically with a Shared Payment Token (`--trip-id` + `--token`); 3DS step-up falls back to `checkout_url` |
-| `trip-status` | Full status: cart, quote, fulfillment, bookings |
+| `agent-pay submit` | Pay programmatically with a Shared Payment Token (`--trip-id` + `--token`); returns the Jinko `booking_ref` once authorized; 3DS step-up falls back to `checkout_url` |
+| `trip-status` | Full status: cart, quote, fulfillment, bookings, and the Jinko `booking_ref` once fulfillment has been scheduled — it can be present before payment completes, so read `fulfillment.status` for paid (the `--booking-ref` for `get-booking` / `hotel-cancel` / `refund`) |
 | `get-booking` | Retrieve a booking by `JNK-*` ref + last name (guest access). |
 | `refund check / commit / status` | Voluntary refund flow |
 | `schema <command>` | Print request/response schema for a command |
@@ -64,7 +64,8 @@ Run `jinko <command> --help` for flags on any command.
 
 ```bash
 # 1. Find a flight (live pricing, gives trip_item_token)
-jinko flight-search --from PAR --to NYC --date 2026-06-15 --return 2026-06-22 --passengers 2
+jinko flight-search --origin PAR --destination NYC \
+  --departure-date 2026-06-15 --return-date 2026-06-22 --adults 2
 
 # 2. Create a trip with that item
 jinko trip --trip-item-token "offer_xxx:fare_yyy"
@@ -87,11 +88,14 @@ jinko checkout --trip-id tr_ABC
 # 5b. Agent path: mint a Shared Payment Token scoped to agent_spt_params,
 #     then pay programmatically (no browser):
 jinko agent-pay submit --trip-id tr_ABC --token spt_xxx
-# → { status: "processing", payment_verified: true }
-#   On a 3DS step-up / decline, the response carries a checkout_url fallback.
+# → { status: "processing", payment_verified: true, booking_ref: "JNK-XEVGW5" }
+#   On a 3DS step-up / decline, the response carries a checkout_url fallback (no booking_ref).
 
 # 6. Poll status
 jinko trip-status --trip-id tr_ABC
+# → booking_ref (JNK-…) is the Jinko reference — pass it as --booking-ref to
+#   get-booking / hotel-cancel / refund. bookings[].booking_reference is the
+#   supplier's confirmation, not that handle.
 ```
 
 ## Hotel flow
@@ -147,7 +151,9 @@ jinko refund status --ref JNK-A7B3X9 --last-name Doe
 ## Common pitfalls
 
 - **Use an API key everywhere.** A tenant API key (`jnk_*`) works across the CLI, the SDK, and MCP Bearer headers — it's the one credential to carry. (OAuth sign-in is deprecated; any legacy WorkOS CLI token in `~/.jinko/config.yaml` is NOT interchangeable with an MCP OAuth token and will fail with an issuer mismatch if pasted into an MCP Bearer header.)
-- **IATA codes**: `--from PAR` uses a CITY code (matches CDG + ORY + BVA); `--from CDG` uses an airport. `flight-search` has `--origin-type city|airport` to disambiguate.
+- **IATA codes**: `--origin PAR` uses a CITY code (matches CDG + ORY + BVA); `--origin CDG` uses an airport. `flight-search` has `--origin-type city|airport` to disambiguate — omit it and the platform classifies the code itself, which is the safest choice.
+- **Filters are requests, not guarantees**: `flight-search` answers with `applied_filters` and `unapplied_filters` (name + reason). An unapplied filter still returns 200 with offers — post-filter them yourself or tell the user the constraint could not be met. `--format table` prints the report under the results.
+- **Alternate airports widen an AIRPORT anchor**: `--origin-alternate-airports EWR LGA` adds airports beside `--origin`, never removes results, and the anchor decides ranking — so put the airport that matters most in `--origin`. Against a city anchor the list is ignored and comes back in `unapplied_filters` as `origin` / `destination`.
 - **trip_item_token format**: `offer_xxx:fare_yyy` (flight) or `htl_xxx:rate_yyy` (hotel). Always the offer ID + fare/rate ID joined by colon.
 - **Token expiry**: offers cached ~30 min. If `checkout` returns a quote failure, re-run `flight-search`/`hotel-search` to get a fresh token.
 - **Script use**: set `JINKO_API_KEY` env var and use `--format json` so output parses cleanly.

package/skills/manage-booking/SKILL.md

@@ -18,6 +18,8 @@ Use `get_booking` to retrieve a booking by its Jinko reference and the traveler'
 }
 ```
 
+`booking_ref` is the top-level `booking_ref` that `get_trip` returns once fulfillment has been scheduled (it can precede payment — read `fulfillment.status` for paid), and that `submit_agent_payment` returns once the token is authorized — not the per-item `booking_reference` (the supplier's PNR / confirmation number).
+
 **Response includes:**
 - `booking_reference`: the Jinko booking reference
 - `status`: current booking status (completed, processing, etc.)