@gojinko/plugin 1.1.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/.claude-plugin/plugin.json +1 -1
  2. package/.codex-plugin/plugin.json +1 -1
  3. package/package.json +1 -1
  4. package/skills/book-trip/SKILL.md +2 -2
  5. package/skills/cli/SKILL.md +8 -4
  6. package/skills/search-flights/SKILL.md +33 -20
  7. package/skills/search-hotels/SKILL.md +21 -0
package/.claude-plugin/plugin.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "jinko",
3
3
  "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.",
4
- "version": "1.1.0",
4
+ "version": "1.2.0",
5
5
  "author": {
6
6
  "name": "Jinko",
7
7
  "url": "https://gojinko.com"
package/.codex-plugin/plugin.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "jinko",
3
3
  "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.",
4
- "version": "1.1.0",
4
+ "version": "1.2.0",
5
5
  "author": {
6
6
  "name": "Jinko",
7
7
  "url": "https://gojinko.com"
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gojinko/plugin",
3
- "version": "1.1.0",
3
+ "version": "1.2.0",
4
4
  "description": "Jinko Travel plugin for Claude Code and OpenAI Codex — flight search, booking, and trip management via MCP",
5
5
  "private": false,
6
6
  "license": "MIT",
package/skills/book-trip/SKILL.md CHANGED
@@ -34,7 +34,7 @@ Two modes (use exactly one):
34
34
  }
35
35
  ```
36
36
 
37
- **Price-check** (user has an `offer_token` from find_flight):
37
+ **Price-check** (user has an `offer_token` — e.g. from a prior `flight_calendar` or legacy `find_flight` result):
38
38
  ```json
39
39
  {
40
40
  "price_check": {
@@ -136,7 +136,7 @@ Categories: `BAGGAGE`, `SEAT`, `MEAL`, etc.
136
136
  }
137
137
  ```
138
138
 
139
- Single synchronous call. The BFF schedules the quote, polls until it completes, schedules fulfillment, and returns a Stripe checkout URL. The user opens this URL in a browser to complete payment. Stripe webhooks finalize the booking automatically — no client-side confirm step is required.
139
+ 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.
140
140
 
141
141
  **Response includes:** `checkout_url`, `session_id`, `total_amount`, `items`.
142
142
 
package/skills/cli/SKILL.md CHANGED
@@ -32,9 +32,10 @@ Auth alternatives:
32
32
  | `auth login / logout / status` | Credentials |
33
33
  | `find-destination` | Discover destinations from origin(s) — inspiration |
34
34
  | `flight-calendar` | Cheapest prices across a date range for a specific route |
35
- | `find-flight` | Cached-flight search by route + dates (returns `offer_token`) |
36
- | `flight-search` | Live pricing — by route or `--offer-token` price-check |
35
+ | `flight-search` | Live pricing — direct search by route + dates, or `--offer-token` price-check (returns bookable `trip_item_token`) |
36
+ | `find-flight` | **Legacy.** Cached route + dates search. Kept for backwards compat; prefer `flight-search` for new work. |
37
37
  | `hotel-search` | Live hotel search by city/query/geo/hotel-ids |
38
+ | `hotel-details` | Rich metadata (gallery, facilities, policies, per-room details) for a single hotel |
38
39
  | `trip` | Create / update a trip: add items, remove items, set travelers + contact |
39
40
  | `select-ancillaries` | Add baggage / seats / meals to a trip item |
40
41
  | `book` | Schedule checkout → returns Stripe payment URL |
@@ -61,9 +62,12 @@ jinko trip --trip-id tr_ABC \
61
62
  --travelers '[{"type":"ADT","first_name":"John","last_name":"Doe","date_of_birth":"1990-01-15"}]' \
62
63
  --contact '{"email":"john@example.com","phone":"+33612345678"}'
63
64
 
64
- # 4. Schedule checkout — returns Stripe URL
65
+ # 4. Schedule checkout — returns canonical Jinko-hosted URL
65
66
  jinko book --trip-id tr_ABC
66
- # → { checkout_url: "https://checkout.stripe.com/..." }
67
+ # → { checkout_url: "https://app.gojinko.com/checkout?sid=12345" }
68
+ # The /checkout page renders the cart, collects any remaining info,
69
+ # and triggers the right Stripe flow (embedded Elements or Hosted
70
+ # Checkout) on Pay-button click.
67
71
 
68
72
  # 5. User pays in browser (or open the URL programmatically)
69
73
  # 6. Poll status
package/skills/search-flights/SKILL.md CHANGED
@@ -1,19 +1,22 @@
1
1
  ---
2
2
  name: search-flights
3
- description: Search for flights, explore destinations, and compare prices across dates using the Jinko Travel API. Use when the user wants to find flights, discover where they can fly, or compare prices.
3
+ description: Search for flights, explore destinations, compare prices across dates, and monitor a fixed route over time using the Jinko Travel API. Use when the user wants to find flights, discover where they can fly, compare prices, or track price changes on a specific route.
4
4
  ---
5
5
 
6
6
  # Flight Search
7
7
 
8
- You have access to three Jinko MCP tools for flight discovery. Pick the right one based on what the user knows:
8
+ You have access to Jinko MCP tools for flight discovery. Pick the right one based on what the user knows AND what they want to do:
9
9
 
10
10
  ## Tool Selection
11
11
 
12
- | User knows | Tool to use |
12
+ | User intent | Tool to use |
13
13
  |-----------|-------------|
14
- | Nothing — wants inspiration | `find_destination` |
15
- | Route but flexible on dates | `flight_calendar` |
16
- | Route + dates | `find_flight` |
14
+ | Nothing in mind — wants inspiration | `find_destination` |
15
+ | Route known, flexible on dates | `flight_calendar` |
16
+ | Route + exact dates, wants live pricing + bookable token | `flight_search` (see the `book-trip` skill) |
17
+ | Route + exact dates, **wants to track price over time** | `price_monitoring` |
18
+
19
+ > `find_flight` (cached search by route + dates) still exists for backwards compatibility but is no longer recommended — `flight_search` returns live prices and a `trip_item_token` in a single step.
17
20
 
18
21
  ## find_destination
19
22
 
@@ -53,27 +56,37 @@ Show cheapest prices across a date range for a specific route. Great for "what's
53
56
 
54
57
  **Response:** List of dates with `price`, `offer_token`, `airline`, `stops`. Includes `cheapest` entry.
55
58
 
56
- ## find_flight
59
+ ## find_flight (legacy — prefer flight_search)
60
+
61
+ Cached flight search by route + dates. Still callable for backwards compatibility with older ChatGPT App versions, but not recommended for new integrations. Use `flight_search` (in the `book-trip` skill) for the same inputs plus live pricing + a bookable `trip_item_token` in one step.
62
+
63
+ ## price_monitoring
57
64
 
58
- Search cached flights by route and dates. Fast results with offer tokens.
65
+ Track the price of a specific route + exact dates over time. **Cache-only** — never triggers a live call. Designed for scheduled polling (cron / scheduled job) so you can act on a price drop.
59
66
 
60
67
  **Required params:**
61
- - `origin`: IATA code (e.g. `"CDG"`)
62
- - `destination`: IATA code (e.g. `"JFK"`)
63
- - `trip_type`: `"oneway"` or `"roundtrip"`
68
+ - `origin`: IATA code (e.g. `"PAR"`)
69
+ - `destination`: IATA code (e.g. `"NYC"`)
70
+ - `departure_date`: YYYY-MM-DD
71
+ - `return_date`: YYYY-MM-DD (omit for one-way)
64
72
 
65
- **Optional params:**
66
- - `departure_dates` or `departure_date_ranges`: when to depart
67
- - `return_dates` or `return_date_ranges`: when to return (roundtrip)
68
- - `stay_days` or `stay_days_range`: trip duration
69
- - `direct_only`, `cabin_class`, `max_price`, `sort_by`, `currency`
73
+ **Optional filters** (use the SAME set between polls — switching filters mid-poll means you're monitoring a different route, not the same one cheaper):
74
+ - `direct_only`, `cabin_class`, `max_price`
75
+ - `include_carriers` / `exclude_carriers` (IATA 2-letter codes)
76
+ - `currency`, `locale`
77
+
78
+ **Response:**
79
+ - `status: "ok"` with a `flight` block (cheapest cached itinerary matching the filters), OR
80
+ - `status: "stale"` when the cache had no matching itinerary — retry later. **Do NOT silently fall back to `flight_search`** on stale; that's a different intent. Only call `flight_search` if the user is ready to book RIGHT NOW.
81
+
82
+ **`offer_token`** in the response is re-shoppable via `flight_search` (price_check mode) when the user decides to act.
70
83
 
71
- **Response:** Flights with `offer_token`, `airline`, `price`, `departure`, `arrival`, `duration_minutes`, `stops`.
84
+ **Cadence:** poll no faster than the cache refresh interval (typically a few hours). Polling faster is wasted work.
72
85
 
73
86
  ## Important notes
74
87
 
75
88
  - **Airport codes**: Use 3-letter IATA codes (PAR, NYC, JFK, CDG)
76
89
  - **Dates**: YYYY-MM-DD format
77
- - **Cached vs Live**: These tools use cached data (fast). For live pricing, use the `book-trip` skill's `flight_search` tool
78
- - **offer_token**: Every result includes an `offer_token` — save it for live pricing via `flight_search`
79
- - All three tools support `format: "json"` for structured output or `format: "text"` for readable summaries
90
+ - **Cached vs Live**: `find_destination`, `flight_calendar`, and `price_monitoring` use cached data — great for exploration and tracking. For live pricing + a bookable token, use `flight_search` (see the `book-trip` skill).
91
+ - **`price_monitoring` is cache-only** — unlike the others, it never falls back to live data. `status: "stale"` is the correct response when the cache is cold; surface it to the user instead of retrying immediately or switching to `flight_search`.
92
+ - The tools support `format: "json"` for structured output or `format: "text"` for readable summaries
package/skills/search-hotels/SKILL.md CHANGED
@@ -74,6 +74,27 @@ Two rooms with kids:
74
74
  - `total_amount` + `currency`: total price for the stay
75
75
  - `is_refundable` + `free_cancellation_until`
76
76
 
77
+ ## hotel_details
78
+
79
+ Optional follow-up to `hotel_search`. Returns rich metadata for a single hotel — gallery, full facilities list, policies, per-room metadata (bed types, size, amenities, views). Use when the user wants more info on a specific result before booking.
80
+
81
+ **Required params:**
82
+ - `hotel_id`: the hotel ID from a prior `hotel_search` result
83
+
84
+ **Optional params:**
85
+ - `checkin` / `checkout`: YYYY-MM-DD. Accepted for future cache-key alignment; currently ignored by the BFF but callers are encouraged to pass them when known.
86
+
87
+ **Example:**
88
+ ```json
89
+ {
90
+ "hotel_id": "HID_12345",
91
+ "checkin": "2026-07-15",
92
+ "checkout": "2026-07-18"
93
+ }
94
+ ```
95
+
96
+ **Response:** `{ hotel: { id, name, description, star_rating, address, coords, images[], facilities[], policies[], checkin_time, checkout_time }, rooms?: [{ id, name, description, amenities[], bed_types[], max_occupancy, size_sqm, views[], images[] }] }`
97
+
77
98
  ## Booking flow
78
99
 
79
100
  Hotels use the same cart as flights — multi-domain trips supported: