@gojinko/plugin 1.2.1 → 1.3.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": "1.2.1",
+  "version": "1.3.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": "1.2.1",
+  "version": "1.3.0",
   "author": {
     "name": "Jinko",
     "url": "https://gojinko.com"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gojinko/plugin",
-  "version": "1.2.1",
+  "version": "1.3.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/search-hotels/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: search-hotels
-description: Search live hotel inventory and rates by destination, dates, and occupancy using the Jinko Travel API. Use when the user wants to find hotels, compare rates, or book a hotel.
+description: Search live hotel inventory and rates by destination, dates, and occupancy — or look up a specific hotel by name — using the Jinko Travel API. Use when the user wants to find hotels, compare rates, or book a hotel.
 ---
 
 # Hotel Search
@@ -11,14 +11,28 @@ Search live hotel inventory using the `hotel_search` Jinko MCP tool. Returns hot
 
 Live search — returns real-time availability and pricing from hotel suppliers.
 
+`hotel_search` has **two modes**, determined by the `destination` shape:
+
+| Mode | When | Destination shape |
+|---|---|---|
+| **A — Rate Lookup** | User named a specific hotel they want to book | `{ hotel_name }` or `{ hotel_ids }` |
+| **B — Hotel Search** | User is exploring a destination | `{ query }`, `{ city_name + country_code }`, `{ latitude + longitude + radius_km }`, or `{ place_id }` |
+
+In **Mode A**, the server resolves the hotel and returns its rates plus a few **`nearby_alternatives`** (other hotels within ~2km, same dates+occupancy). `filters` are ignored in Mode A — the user already picked the property.
+
+In **Mode B**, `filters` narrow the result set (star rating, facility, chain, etc.).
+
 **Required params:**
 
-- **Destination** (provide exactly one):
-  - `query`: free-text (e.g. `"Paris"`, `"beach resort near Barcelona"`)
-  - `city_name` + optional `country_code`: structured (e.g. `"New York"` + `"us"`)
-  - `latitude` + `longitude` + optional `radius_km`: geo-radius (max 50km)
-  - `place_id`: Google Places ID
-  - `hotel_ids`: re-shop specific hotels by ID
+- **Destination** (provide exactly one shape):
+  - **Mode A:**
+    - `hotel_name`: the user-named hotel (e.g. `"Hotel Calimala"`, `"The St. Regis Rome"`, `"Hôtel Costes"`). **Always pair with `country_code` and `city_name` when known** — name lookup runs against a 1.74M-hotel catalog and precision drops sharply on common names without scope. Server returns 422 `HOTEL_NAME_LOW_CONFIDENCE` if no candidate clears the auto-pick threshold (see error handling below).
+    - `hotel_ids`: re-shop specific hotels by ID (from a prior search).
+  - **Mode B:**
+    - `query`: free-text (e.g. `"Paris"`, `"beach resort near Barcelona"`). Only for unambiguous cities/POIs — returns 0 for islands, regions, countries, archipelagos.
+    - `city_name` + `country_code`: structured (e.g. `"New York"` + `"us"`). Best for ambiguous city names or when the user named a primary city (e.g. `"Mahón"` + `"es"` for Menorca).
+    - `latitude` + `longitude` + optional `radius_km`: geo-radius (max 50km). Best for islands, regions, neighborhoods.
+    - `place_id`: Google Places ID.
 
 - `checkin`: check-in date (YYYY-MM-DD)
 - `checkout`: check-out date (YYYY-MM-DD)
@@ -30,7 +44,7 @@ Live search — returns real-time availability and pricing from hotel suppliers.
 **Optional params:**
 - `currency`: ISO 4217 (default USD)
 - `guest_nationality`: ISO 3166-1 alpha-2 (affects rate availability)
-- `filters`: `{ min_rating, star_rating, min_reviews, hotel_type_ids, chain_ids, facility_ids, max_results }`
+- `filters`: `{ min_rating, star_rating, min_reviews, hotel_type_ids, chain_ids, facility_ids, max_results }` — **Mode B only**. Server ignores filters in Mode A and includes a `warnings` entry on the response; future versions may reject the combination outright.
 
 **Examples:**
 
@@ -68,12 +82,60 @@ Two rooms with kids:
 }
 ```
 
+Look up a specific hotel by name (Mode A):
+```json
+{
+  "destination": {
+    "hotel_name": "Hotel Calimala",
+    "country_code": "it",
+    "city_name": "Florence"
+  },
+  "checkin": "2026-07-15",
+  "checkout": "2026-07-18",
+  "adults": 2,
+  "currency": "EUR"
+}
+```
+
 **Response:** List of hotels with `hotel_id`, `name`, `address`, `star_rating`, `rating`, `review_count`, `main_photo`, and a `rooms[]` list. Each room has `rates[]` — each rate includes:
 - `offer_id`: the `htl_*` token (use as `trip_item_token` for booking)
 - `board_type` / `board_name`: meal plan (RO = Room Only, BB = Bed & Breakfast, etc.)
 - `total_amount` + `currency`: total price for the stay
 - `is_refundable` + `free_cancellation_until`
 
+In **Mode A**, the response also includes:
+- `nearby_alternatives`: list of hotels within ~2km of the matched property, in the same response shape (hotel + rooms + rates) so the user can compare. Empty when none are available for the requested dates.
+- `warnings` (only if you passed `filters` alongside `hotel_name`/`hotel_ids`): explains that filters were dropped because Mode A wins on name match.
+
+### Error handling — `HOTEL_NAME_LOW_CONFIDENCE`
+
+When `hotel_name` is used but no candidate clears the auto-pick threshold (~0.7), the server returns HTTP 422 with this body:
+
+```json
+{
+  "error": {
+    "code": "HOTEL_NAME_LOW_CONFIDENCE",
+    "message": "No high-confidence match for 'Hotel Calimal' in Florence, IT (top score 0.45).",
+    "top_candidates": [
+      { "hotel_id": "lp220fa7", "name": "Hotel Calimala Florence", "city": "Florence", "score": 0.45 },
+      { "hotel_id": "lp657fada9", "name": "Hotel Calimala Milano", "city": "Milan", "score": 0.42 }
+    ],
+    "suggested_retry": {
+      "destination": { "city_name": "Florence", "country_code": "it" },
+      "rationale": "search all Florence hotels instead of name-resolving"
+    }
+  }
+}
+```
+
+This is **actionable**, not fatal. Pick one:
+
+1. **Top candidate is what the user meant** (typo / spelling variant) → confirm with the user, then retry `hotel_search` with `destination: { hotel_ids: ["<top.hotel_id>"] }`.
+2. **None of the candidates fit** → use `suggested_retry.destination` to fall back to a city-level search. Tell the user: _"I couldn't pin down 'Hotel Calimal' — want me to search all Florence hotels instead?"_
+3. **User likely meant a different city** → ask the user to clarify the city/country, then retry with `hotel_name` + the corrected `country_code` / `city_name`.
+
+Don't silently auto-pick a low-confidence candidate — booking the wrong hotel is worse than asking one clarifying question.
+
 ## hotel_details
 
 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.