fortrip 5.0.1 → 5.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.
package/README.md
CHANGED
|
@@ -82,7 +82,7 @@ other command that needs to save a sign-in exits 1 too. The error says to set
|
|
|
82
82
|
| `hotels book` | Order an offer: an unpaid order with a payment link |
|
|
83
83
|
| `orders get <orderId>` | Show an order and its status |
|
|
84
84
|
| `orders list` | List your orders, newest first |
|
|
85
|
-
| `orders cancel <orderId>` |
|
|
85
|
+
| `orders cancel <orderId>` | Cancel a paid order under its terms (--max-penalty), or close an unpaid one (--close) |
|
|
86
86
|
| `orders pay <orderId>` | Pay an order with a Link token (US and Canada) or with Alipay or WeChat Pay, instead of its payment link |
|
|
87
87
|
| `login` | Sign in through the browser |
|
|
88
88
|
| `logout` | Revoke and forget the saved token |
|
|
@@ -193,7 +193,7 @@ args = ["-y", "fortrip", "mcp"]
|
|
|
193
193
|
| `FORTRIP_TOKEN` | An access token, used instead of the saved sign-in. It is short-lived, so it suits a remote agent environment or a CI run; for longer, sign in. It isn't tied to a server: it is sent to whatever `FORTRIP_API_URL` points at. If Fortrip doesn't accept it, or it contains a line break or another character that can't be sent in a header, commands exit 3 with `tokenSource: "FORTRIP_TOKEN"` and no `loginUrl`; the error never repeats the token. |
|
|
194
194
|
| `FORTRIP_API_URL` | The API's base URL (default `https://api.fortrip.ai`). It must be `https`, except for `localhost`, `127.0.0.1` and `[::1]`, which may use plain `http`. It may end in a path prefix (`http://localhost:3000/api/public`), which every request path follows; a query or fragment is dropped. |
|
|
195
195
|
| `FORTRIP_MCP_URL` | The MCP server `fortrip mcp` bridges to (default `https://mcp.fortrip.ai/`), under the same URL rule. Your sign-in is sent to it, so it must be the MCP server of the API you use: on the origin of `FORTRIP_API_URL`, except that the default API goes with the default MCP server, `api.fortrip.ai` and `mcp.fortrip.ai`. When you set `FORTRIP_API_URL` to a local or preview API, set `FORTRIP_MCP_URL` too; `fortrip mcp` exits 2 and says so when you don't. |
|
|
196
|
-
| `FORTRIP_CURRENCY` | The default `--currency` for `hotels search` and `hotels offers` (`USD` or `CNY
|
|
196
|
+
| `FORTRIP_CURRENCY` | The default `--currency` for `hotels search` and `hotels offers` (`USD` or `CNY`). Prices are in this currency, and an order made from the offers is paid in it. |
|
|
197
197
|
|
|
198
198
|
## Output and exit codes
|
|
199
199
|
|
|
@@ -14,8 +14,8 @@ var LIMITS = {
|
|
|
14
14
|
nightsFortrip: 30,
|
|
15
15
|
nightsSupplier: 15,
|
|
16
16
|
offersHotels: 15,
|
|
17
|
-
offersPerHotelDefault:
|
|
18
|
-
offersPerHotelMax:
|
|
17
|
+
offersPerHotelDefault: 15,
|
|
18
|
+
offersPerHotelMax: 30,
|
|
19
19
|
pageSizeDefault: 20,
|
|
20
20
|
pageSizeMax: 50,
|
|
21
21
|
textLength: 128,
|
|
@@ -14759,7 +14759,7 @@ var SEARCH_SORTS = [
|
|
|
14759
14759
|
var locale = oneOf("locale", ["en", "zh"]).describe(
|
|
14760
14760
|
"Language for names and text in the response: en or zh."
|
|
14761
14761
|
);
|
|
14762
|
-
var currencyDescription = "The currency
|
|
14762
|
+
var currencyDescription = "The currency of every price: USD (default) or CNY. Each currency is paid through its own channel, with its own payment methods; the order's payment page shows them. CNY is paid through payment channels in mainland China and suits a user who pays that way.";
|
|
14763
14763
|
var cursor = nonEmpty("cursor");
|
|
14764
14764
|
var nightsError = (name) => `${name} must be after the check-in date and at most ${LIMITS.nightsFortrip} nights later`;
|
|
14765
14765
|
var stay = strictInput({
|
|
@@ -14899,7 +14899,7 @@ function createSearchHotelsInput(now = Date.now) {
|
|
|
14899
14899
|
"Dates and party. Needed for indicative prices. Search uses only the dates when the rooms differ."
|
|
14900
14900
|
),
|
|
14901
14901
|
pricing: oneOf("pricing", ["indicative", "none"]).optional().describe(
|
|
14902
|
-
"`indicative` adds an
|
|
14902
|
+
"`indicative` adds an indicative price per hotel and needs a stay; `none` skips prices. Default: indicative with a stay, otherwise none."
|
|
14903
14903
|
),
|
|
14904
14904
|
filters: searchFilters,
|
|
14905
14905
|
sort: oneOf("sort", SEARCH_SORTS).optional().describe(
|
|
@@ -15552,7 +15552,7 @@ var COMMANDS = [
|
|
|
15552
15552
|
{
|
|
15553
15553
|
group: "orders",
|
|
15554
15554
|
name: "cancel",
|
|
15555
|
-
summary: "
|
|
15555
|
+
summary: "Cancel a paid order under its terms (--max-penalty), or close an unpaid one (--close)",
|
|
15556
15556
|
tool: "cancel_order",
|
|
15557
15557
|
flags: cancelFlags,
|
|
15558
15558
|
positionals: [positional(cancelOrderInput, "orderId")],
|
|
@@ -15633,17 +15633,17 @@ var GLOBAL_FLAGS = [
|
|
|
15633
15633
|
|
|
15634
15634
|
// ../contract/src/guide-data.generated.ts
|
|
15635
15635
|
var FRAGMENTS = {
|
|
15636
|
-
"booking": "{{#if claude-skill cli}}\n## Ordering\n\n{{/if}}\n- Call `{{tool:hotels book}}` only for the offer the user picked, with at least one guest per room{{#if claude-skill cli}}, named as the user gave them{{/if}}; never invent guests.{{#if claude-skill cli}} Room 1 is the offer's first room, and a room takes no more guests than it sleeps.{{/if}}\n- Guest names: Latin letters as on the passport (M\xFCller \u2192 Mueller), first and last name 1\u2013{{limit:guestName}} characters each{{#if cli}}, as `--guest 1:John:Smith` (room 1, first name, last name){{/if}}.\n
|
|
15637
|
-
"errors": "{{#if claude-skill cli}}\n## Errors\n\n{{#if claude-skill}}A tool error{{/if}}{{#if cli}}An error on stderr{{/if}} carries `code`, `message` and `retryable`, and `retryAfterSeconds` when waiting helps; many carry `details`. Search errors are under Search. Ordering errors:\n\n| `code` | Do this |\n|---|---|\n| `offer_changed` (409) | The price or terms changed since the offer: `changes` lists every change (`worse` says which are worse for the user) and `offer` is the new offer. Show the user every change and ask again; if they still want it, order the new offer
|
|
15636
|
+
"booking": "{{#if claude-skill cli}}\n## Ordering\n\n{{/if}}\n- Call `{{tool:hotels book}}` only for the offer the user picked, with at least one guest per room{{#if claude-skill cli}}, named as the user gave them{{/if}}; never invent guests.{{#if claude-skill cli}} Room 1 is the offer's first room, and a room takes no more guests than it sleeps.{{/if}}\n{{#if claude-skill cli}}\n- Guest names: Latin letters as on the passport (M\xFCller \u2192 Mueller), first and last name 1\u2013{{limit:guestName}} characters each{{#if cli}}, as `--guest 1:John:Smith` (room 1, first name, last name){{/if}}.\n- The contact's first and last name (up to {{limit:contactFirstName}} characters each), email and phone (with its country code) are all required. Special requests must be in English and aren't guaranteed.\n{{/if}}\n- `{{tool:hotels book}}` can take about two minutes{{#if cli}}: allow the command at least 3 minutes{{/if}}. If it times out, {{#if cli}}run it again with identical flags{{/if}}{{#if mcp claude-skill}}call it again with the same details{{/if}}: it returns the same order.\n{{#if cli}}\n- `{{tool:hotels book}}` takes only these fields: a `--body` with any other field (such as `nationality`) is rejected with exit 2.\n{{/if}}\n",
|
|
15637
|
+
"errors": "{{#if claude-skill cli}}\n## Errors\n\n{{#if claude-skill}}A tool error{{/if}}{{#if cli}}An error on stderr{{/if}} carries `code`, `message` and `retryable`, and `retryAfterSeconds` when waiting helps; many carry `details`. Search errors are under Search. Ordering errors:\n\n| `code` | Do this |\n|---|---|\n| `offer_changed` (409) | The price or terms changed since the offer: `changes` lists every change (`worse` says which are worse for the user) and `offer` is the new offer. Show the user every change and ask again; if they still want it, order the new offer |\n| `offer_expired` (409) | Get offers again and let the user choose again |\n| `offer_unavailable` (422) | The offer is sold out or was refused: get offers again and let the user choose again |\n| `order_in_progress` (409) | The order is still being created, or still being confirmed when cancelling it: wait `retryAfterSeconds`, then {{#if claude-skill}}call again with the same details{{/if}}{{#if cli}}run the command again with identical flags{{/if}} |\n| `offer_already_ordered` (409) | This offer was already ordered with other details: show that order (`orderId`) instead. An offer is ordered once, even when its order failed or expired: to order with other details, get offers again |\n| `stay_unsupported` (422) | `mixed_occupancy`: order once per party; `max_nights`: at most `max` nights per order |\n| `currency_unavailable` (422) | Prices in `details.currency` aren't available yet: tell the user, and ask whether to see USD prices |\n| `stay_in_past` (422) | Check-in has passed in the hotel's time zone: ask for new dates |\n| `ordering_paused` (503) | Ordering is paused on Fortrip's side: tell the user, and try again only after `retryAfterSeconds` |\n\nAny code:\n\n- `invalid_request` (400): `details.issues` lists each bad field; fix them. For amenities, `details.filterable` lists those that can filter.\n- `cursor_invalid` (400): the page is gone; search again from the first page.\n- `not_found` (404): no such hotel, or no such order for this user.\n- `rate_limited` (429): wait `retryAfterSeconds`, then retry once.\n- `service_unavailable` (503) and `supplier_unavailable` (503 or 504): wait `retryAfterSeconds`, then retry once with the same details; if it fails again, tell the user.\n- Any other code: read `message`. If `retryable` is true, wait `retryAfterSeconds` and retry once; otherwise tell the user instead of guessing.\n{{/if}}\n",
|
|
15638
15638
|
"meals": '{{#if claude-skill cli}}\n## Presenting an offer\n\nGive the user, for each offer:\n\n- the room (`room.name`, beds, size) and the total, as above;\n- the meals: `meals.included` (breakfast, lunch, dinner) or `allInclusive`, with `guestsCoveredPerRoom`. Fewer than the guests per room means not everyone gets the meals (breakfast for 1 with 2 adults in the room): say who is covered. `unspecifiedMainMeals` counts main meals the hotel didn\'t name. With `known: false`, the meals are unknown: say so, and don\'t call it room only;\n- cancellation: `status` (`free`, `partial_penalty`, `non_refundable` or `unknown`), `freeCancellationEndsAt` (null with `free`: free until check-in) and the `penalties`. Times are in UTC: also give them in the hotel\'s `timeZone`;\n- confirmation: `mode` `instant` or `on_request` (within `withinMinutes`);\n- fees payable at the property (`payAtProperty.items`), in the property\'s currency. `disclosure: "incomplete"` means there can be fees not listed: say so.\n\nAn offer expires at `expiresAt`, about 30 minutes after it was made; after that, get offers again.\n\n"Not listed" is not "no": `listed: false` (amenities, policies, rooms), `null` and `unknown` mean the source didn\'t say. Tell the user it\'s unknown instead of turning it into "no".\n{{/if}}\n{{#if mcp}}\n- "Not listed" or "unknown" is not "no".\n{{/if}}\n',
|
|
15639
|
-
"occupancy": "{{#if claude-skill cli}}\n## Rooms and guests\n\n- {{#if mcp claude-skill}}`stay.rooms` lists each room's party as `{ adults, childrenAges }`: two rooms of 2 adults, one with a child of 6, is `[{ adults: 2, childrenAges: [6] }, { adults: 2, childrenAges: [] }]`{{/if}}{{#if cli}}`--room <adults[:age,\u2026]>`, once per room, gives each room's party: two rooms of 2 adults, one with a child of 6, is `--room 2:6 --room 2`{{/if}}.\n- Ask each child's age; offers need it.\n- If the party doesn't split evenly across the rooms (3 adults in 2 rooms), ask the user how it splits.\n
|
|
15640
|
-
"order": '{{#if claude-skill cli}}\n## Workflow\n\n1. **Search** with `{{tool:hotels search}}` for candidate hotels: a destination, `{{arg:text}}` or both, and the stay\'s dates and rooms for indicative prices.\n{{#if cli}}\n\n ```bash\n {{tool:hotels search}} --place-name Bangkok --country TH --check-in 2026-11-10 \\\n --check-out 2026-11-12 --room 2 --stars-min 4 --sort price_asc --limit 10\n ```\n\n{{/if}}\n2. **Details** (optional) with `{{tool:hotels get}}`, when the user asks about a hotel or a stated preference needs evidence (a pool, a policy, room size). For a details-only question, call it directly when you know the hotel\'s `hotelId`; otherwise find the hotel with `{{tool:hotels search}}`.\n{{#if cli}}\n\n ```bash\n {{tool:hotels get}} <hotelId> [--rooms]\n ```\n\n{{/if}}\n3. **Offers** with `{{tool:hotels offers}}` for a few shortlisted hotels, with the dates and rooms the user will order. It takes about 15 seconds. A hotel is available only once this returns an offer for it.\n{{#if cli}}\n\n ```bash\n {{tool:hotels offers}} --hotel <hotelId> --hotel <hotelId> --check-in 2026-11-10 \\\n --check-out 2026-11-12 --room 2 --room 2 [--require-free-cancellation]\n ```\n\n{{/if}}\n4. **Order** with `{{tool:hotels book}}`, once the user has picked one offer and given the guests and the contact (see Ordering).\n{{#if cli}}\n\n ```bash\n {{tool:hotels book}} --offer <offerId> --guest 1:John:Smith --guest 2:Mary:Smith \\\n --first-name John --last-name Smith --email john@example.com \\\n --phone "+8613800000000"\n ```\n\n{{/if}}\n5. **Confirm, then give the payment link**, as in "Before giving the payment link" below.\n6. **After payment**, check the order with `{{tool:orders get}}` (see After payment).\n\n## Search\n\n### Where\n\n- **A place by name:** {{#if mcp claude-skill}}`{ kind: "place_name", name, countryCode }`{{/if}}{{#if cli}}`--place-name <name> --country <CC>`{{/if}}, in any language (Kyoto or \u4EAC\u90FD). The country is required: ask the user when it isn\'t clear. Names match exactly, ignoring only case and spacing: accents, hyphens, apostrophes and periods count ("K\xF6ln" or "Cologne", not "Koln"; "St. Moritz", not "St Moritz").\n- If several places bear the name, the answer is `destination_ambiguous` with up to {{limit:candidatesShown}} candidates and their hotel counts: ask the user which one they mean, then search it by its `placeId`; never pick one yourself.\n- `destination_not_found` with `no_match` means no place of that name in that country: check the spelling and accents, or try another name for the place. Its `nameAsText` counts the hotels that a `{{arg:text}}` search for the name would find.\n- **A place from an earlier answer:** {{#if mcp claude-skill}}`{ kind: "place", placeId }`{{/if}}{{#if cli}}`--place <placeId>`{{/if}}.\n- **Near a point:** {{#if mcp claude-skill}}`{ kind: "point", location: { lat, lng } }`{{/if}}{{#if cli}}`--point <lat,lng>`{{/if}}, for "near X" when you know where X is.\n- **A whole country:** {{#if mcp claude-skill}}`{ kind: "country", countryCode }`{{/if}}{{#if cli}}`--country-only <CC>`{{/if}}, as for the Maldives.\n- Countries, regions (states, provinces), prefecture-level cities in China and main islands cover their whole area. Towns, neighbourhoods, districts, small islands and points cover a circle of {{limit:radiusMetersDefault}} meters; `{{arg:destination.radiusMeters}}` sets another, up to {{limit:radiusMetersMax}} meters, and narrows an area to a circle around its center.\n- **Localities:** an area search lists its `localities`, the towns its hotels belong to, each with a `placeId`, its hotel `count` and the places it `includes` (Patong is part of Phuket). To search one, pass it as {{#if mcp claude-skill}}`{ kind: "locality", placeId }`{{/if}}{{#if cli}}`--locality <placeId>`{{/if}}. A town that isn\'t a locality answers `destination_not_found` with `not_a_locality` and, in `hub`, the locality it belongs to: search that locality, or the town itself with {{#if mcp claude-skill}}`kind: "place"`{{/if}}{{#if cli}}`--place`{{/if}} for a circle around it.\n- A price sort or price filter over more than {{limit:poolLimit}} hotels (in an area, or for text alone) answers `search_too_broad` with `matched` and the top `localities`: show them and ask the user which they prefer, unless the request already names one of them; search that one by its `placeId` as a locality, never by its name.\n\n### Text\n\n`{{arg:text}}` matches exact words in hotel names and addresses, in Chinese or English:\n\n- Every word must match as written: plurals, accents, spacing and abbreviations count ("hostel" and "hostels", "St Regis" and "Saint Regis" find different hotels). Hyphens and apostrophes don\'t (Ritz-Carlton finds Ritz Carlton).\n- In Chinese, matching follows word segmentation, so part of a name can match unrelated hotels (\u5E0C\u5C14 is not \u5E0C\u5C14\u987F).\n- Use only distinctive words: a hotel or brand name, a district or a landmark. Not "hotel", "near", "cheap" or "best".\n-
|
|
15641
|
-
"payment-link": "{{#if claude-skill cli}}\n## Before giving the payment link\n\n`{{tool:hotels book}}` answers with an unpaid order: `status` `awaiting_payment`, its `reference` (the support number), `price.total`, the stay and its terms, and `payment.url`, a Fortrip page that recaps the order and continues to the payment provider. Nothing is charged until the user pays.\n\n1. Show the order's total and currency, the stay (hotel, room, dates, rooms and guests per room) and every term: meals, cancellation (status, deadline, penalties) and fees payable at the property, unknowns included.\n2. End that reply by asking the user to confirm, and wait for a clear yes. Urgency is not consent.\n3. Then give `payment.url` exactly as returned
|
|
15642
|
-
"planning": "# Planning a hotel stay\n\nRead this when the request is more than one hotel for fixed dates: flexible dates, a budget, split stays, several destinations, or \"find me the best\". The rules in {{#if mcp}}the server instructions{{/if}}{{#if claude-skill cli}}SKILL.md{{/if}} still apply (call order, destinations,
|
|
15639
|
+
"occupancy": "{{#if claude-skill cli}}\n## Rooms and guests\n\n- {{#if mcp claude-skill}}`stay.rooms` lists each room's party as `{ adults, childrenAges }`: two rooms of 2 adults, one with a child of 6, is `[{ adults: 2, childrenAges: [6] }, { adults: 2, childrenAges: [] }]`{{/if}}{{#if cli}}`--room <adults[:age,\u2026]>`, once per room, gives each room's party: two rooms of 2 adults, one with a child of 6, is `--room 2:6 --room 2`{{/if}}.\n- Ask each child's age; offers need it.\n- If the party doesn't split evenly across the rooms (3 adults in 2 rooms), ask the user how it splits.\n- Offers and orders take one party per call, every room the same: for different parties, order once per party. `{{tool:hotels offers}}` answers `stay_unsupported` (`mixed_occupancy`) for mixed rooms; `{{tool:hotels search}}` accepts them but prices only from the dates, with the note `party_split_required`.\n- Limits: 1\u2013{{limit:rooms}} rooms, 1\u2013{{limit:adultsPerRoom}} adults and 0\u2013{{limit:childrenPerRoom}} children (aged 0\u2013{{limit:childAgeMax}}) per room, 1\u2013{{limit:nightsSupplier}} nights, up to {{limit:offersHotels}} hotels per `{{tool:hotels offers}}` call. A longer stay answers `stay_unsupported` (`max_nights`): ask the user whether to split it into consecutive stays, each its own order.\n{{/if}}\n",
|
|
15640
|
+
"order": '{{#if claude-skill cli}}\n## Workflow\n\n1. **Search** with `{{tool:hotels search}}` for candidate hotels: a destination, `{{arg:text}}` or both, and the stay\'s dates and rooms for indicative prices.\n{{#if cli}}\n\n ```bash\n {{tool:hotels search}} --place-name Bangkok --country TH --check-in 2026-11-10 \\\n --check-out 2026-11-12 --room 2 --stars-min 4 --sort price_asc --limit 10\n ```\n\n{{/if}}\n2. **Details** (optional) with `{{tool:hotels get}}`, when the user asks about a hotel or a stated preference needs evidence (a pool, a policy, room size). For a details-only question, call it directly when you know the hotel\'s `hotelId`; otherwise find the hotel with `{{tool:hotels search}}`.\n{{#if cli}}\n\n ```bash\n {{tool:hotels get}} <hotelId> [--rooms]\n ```\n\n{{/if}}\n3. **Offers** with `{{tool:hotels offers}}` for a few shortlisted hotels, with the dates and rooms the user will order. It takes about 15 seconds. A hotel is available only once this returns an offer for it.\n{{#if cli}}\n\n ```bash\n {{tool:hotels offers}} --hotel <hotelId> --hotel <hotelId> --check-in 2026-11-10 \\\n --check-out 2026-11-12 --room 2 --room 2 [--require-free-cancellation]\n ```\n\n{{/if}}\n4. **Order** with `{{tool:hotels book}}`, once the user has picked one offer and given the guests and the contact (see Ordering).\n{{#if cli}}\n\n ```bash\n {{tool:hotels book}} --offer <offerId> --guest 1:John:Smith --guest 2:Mary:Smith \\\n --first-name John --last-name Smith --email john@example.com \\\n --phone "+8613800000000"\n ```\n\n{{/if}}\n5. **Confirm, then give the payment link**, as in "Before giving the payment link" below.\n6. **After payment**, check the order with `{{tool:orders get}}` (see After payment).\n\n## Search\n\n### Where\n\n- **A place by name:** {{#if mcp claude-skill}}`{ kind: "place_name", name, countryCode }`{{/if}}{{#if cli}}`--place-name <name> --country <CC>`{{/if}}, in any language (Kyoto or \u4EAC\u90FD). The country is required: ask the user when it isn\'t clear. Names match exactly, ignoring only case and spacing: accents, hyphens, apostrophes and periods count ("K\xF6ln" or "Cologne", not "Koln"; "St. Moritz", not "St Moritz").\n- If several places bear the name, the answer is `destination_ambiguous` with up to {{limit:candidatesShown}} candidates and their hotel counts: ask the user which one they mean, then search it by its `placeId`; never pick one yourself.\n- `destination_not_found` with `no_match` means no place of that name in that country: check the spelling and accents, or try another name for the place. Its `nameAsText` counts the hotels that a `{{arg:text}}` search for the name would find.\n- **A place from an earlier answer:** {{#if mcp claude-skill}}`{ kind: "place", placeId }`{{/if}}{{#if cli}}`--place <placeId>`{{/if}}.\n- **Near a point:** {{#if mcp claude-skill}}`{ kind: "point", location: { lat, lng } }`{{/if}}{{#if cli}}`--point <lat,lng>`{{/if}}, for "near X" when you know where X is.\n- **A whole country:** {{#if mcp claude-skill}}`{ kind: "country", countryCode }`{{/if}}{{#if cli}}`--country-only <CC>`{{/if}}, as for the Maldives.\n- Countries, regions (states, provinces), prefecture-level cities in China and main islands cover their whole area. Towns, neighbourhoods, districts, small islands and points cover a circle of {{limit:radiusMetersDefault}} meters; `{{arg:destination.radiusMeters}}` sets another, up to {{limit:radiusMetersMax}} meters, and narrows an area to a circle around its center.\n- **Localities:** an area search lists its `localities`, the towns its hotels belong to, each with a `placeId`, its hotel `count` and the places it `includes` (Patong is part of Phuket). To search one, pass it as {{#if mcp claude-skill}}`{ kind: "locality", placeId }`{{/if}}{{#if cli}}`--locality <placeId>`{{/if}}. A town that isn\'t a locality answers `destination_not_found` with `not_a_locality` and, in `hub`, the locality it belongs to: search that locality, or the town itself with {{#if mcp claude-skill}}`kind: "place"`{{/if}}{{#if cli}}`--place`{{/if}} for a circle around it.\n- A price sort or price filter over more than {{limit:poolLimit}} hotels (in an area, or for text alone) answers `search_too_broad` with `matched` and the top `localities`: show them and ask the user which they prefer, unless the request already names one of them; search that one by its `placeId` as a locality, never by its name.\n\n### Text\n\n`{{arg:text}}` matches exact words in hotel names and addresses, in Chinese or English:\n\n- Every word must match as written (a typo such as "Shangahi" finds nothing): plurals, accents, spacing and abbreviations count ("hostel" and "hostels", "St Regis" and "Saint Regis" find different hotels). Hyphens and apostrophes don\'t (Ritz-Carlton finds Ritz Carlton).\n- In Chinese, matching follows word segmentation, so part of a name can match unrelated hotels (\u5E0C\u5C14 is not \u5E0C\u5C14\u987F).\n- Use only distinctive words: a hotel or brand name, a district or a landmark. Not "hotel", "near", "cheap" or "best".\n- Place names belong in the destination: "Maldives" as text finds a hotel named Maldives in China.\n\n### Filters\n\n- Stars run from 1 to 5 in half steps{{#if mcp claude-skill}} (`filters.stars`){{/if}}. "4 stars" as {{#if mcp claude-skill}}`{ min: 4, max: 4 }`{{/if}}{{#if cli}}`--stars-min 4 --stars-max 4`{{/if}} leaves out 4.5: unless the user means exactly 4, use {{#if mcp claude-skill}}`{ min: 4 }`{{/if}}{{#if cli}}`--stars-min 4`{{/if}} or ask. Unrated hotels are left out whenever stars are filtered.\n- `{{arg:filters.amenities}}` takes only the amenities that can filter (such as pool, parking, wifi); others, such as gym or spa, show in `{{tool:hotels get}}` but can\'t filter. A hotel matches only when it lists the amenity, and about half the hotels list no amenities at all (`coverage.excludedNoFacilityData` counts those left out): "not listed" is not "absent".\n- `{{arg:filters.price.maxPerRoomNight}}` bounds the indicative price per room per night, in the search\'s currency; hotels without one are left out and counted.\n\n### Results\n\n- `notes` explain the answer (a limited pool, a circle around an island, more hotels just outside it): pass on what matters to the user.\n- `coverage` has the counts: `matched` hotels, how many were priced and how many have a price.\n- A next page is {{#if mcp claude-skill}}`cursor` set to `nextCursor` and, optionally, `limit`{{/if}}{{#if cli}}`--cursor <nextCursor>` and, optionally, `--limit`{{/if}}; nothing else.\n{{/if}}\n{{#if mcp}}\n- A place name needs its `countryCode` (ask the user if unclear) and matches exactly (accents and periods count). On `destination_ambiguous`, ask the user which they mean, then search its `placeId`; never pick one yourself.\n- On `search_too_broad`, show its `localities` and ask the user which, unless they already named one; search it as `{ kind: "locality", placeId }`, never by name.\n- `text` matches whole words of hotel names and addresses: use a distinctive name, brand or landmark.\n{{/if}}\n',
|
|
15641
|
+
"payment-link": "{{#if claude-skill cli}}\n## Before giving the payment link\n\n`{{tool:hotels book}}` answers with an unpaid order: `status` `awaiting_payment`, its `reference` (the support number), `price.total`, the stay and its terms, and `payment.url`, a Fortrip page that recaps the order and continues to the payment provider. Nothing is charged until the user pays.\n\n1. Show the order's total and currency, the stay (hotel, room, dates, rooms and guests per room) and every term: meals, cancellation (status, deadline, penalties) and fees payable at the property, unknowns included.\n2. End that reply by asking the user to confirm, and wait for a clear yes. Urgency is not consent.\n3. Then pay one way only: give `payment.url` exactly as returned (don't shorten, rebuild or re-encode it), or use one of the ways below.\n\n{{/if}}\n{{#if mcp}}\n- Pay one way only: give `payment.url` or call `{{tool:orders pay}}`. First show the order's total and currency, the stay and every term, end that reply by asking the user to confirm, and wait for a clear yes. Then give `payment.url` exactly as returned, to this user only: anyone holding it can pay.\n{{/if}}\n{{#if claude-skill cli}}\n- `payment.url` works like a payment credential: anyone holding it can pay. Give it to this user only, never in shared channels, documents, logs or tickets. With `requiresSignIn: true` (an order started on the Fortrip website), the user signs in to pay.\n- The link expires at `payment.expiresAt`; the order is then `expired`. To order the stay again, get offers again, and confirm the new order with the user before giving its link.\n- Another order of the stay (another party, or a corrected guest name) needs a new offer: get offers again. When it replaces an unpaid order, tell the user to pay only the new link; the earlier one expires unpaid, or can be closed now with `{{tool:orders cancel}}`{{#if cli}} and `--close`{{/if}} once the user says they no longer want it.\n- An order `awaiting_payment` with `payment.status` `unpaid` whose `payment.url` is null has a payment being processed: read it again shortly with `{{tool:orders get}}`, and don't give an earlier link.\n{{/if}}\n- Never ask for, accept or pass on payment card details; payment happens only on `payment.url` or by a way in the order's `payment.methods`.{{#if claude-skill cli}} A card number in a guest name, the contact or the special requests is rejected{{#if cli}} with exit 2{{/if}}.{{/if}}\n{{#if claude-skill cli}}\n\n## Paying without the link\n\nAn order whose `payment.methods` has the `stripe_shared_payment_token` entry (in {{#if claude-skill}}a result's text{{/if}}{{#if cli}}the text output{{/if}}, the line \"Pay without the link\") can also be paid through `{{tool:orders pay}}` with a Stripe shared payment token that the user's Link wallet grants for it. Use it only if you have a tool that can request such a token from the user's Link wallet: Link is for US and Canadian accounts, and caps a spend request at ${{limit:tokenPaymentMaxUsd}}, so only a USD order up to that has such an entry. Otherwise give `payment.url`, and never ask the user to create, type or paste a token.\n\n1. Confirm the order with the user as before giving the payment link: its total and currency, the stay and every term, and a clear yes. The token comes from the user's wallet, never from card details.\n2. Request the token from the user's Link wallet with that entry's `handler.config.business_profile` and its `limits`: `maxAmount` (in cents), `currency` and `expiresAt`.\n3. {{#if claude-skill}}Call{{/if}}{{#if cli}}Run{{/if}} `{{tool:orders pay}}` with the token and the order's `price.total`{{#if cli}} (`--token`, `--total`){{/if}}{{#if claude-skill}}, the token as `sharedPaymentToken` or in UCP's `payment.instruments`{{/if}}. The order is then `confirming`, its payment `authorized`: check it as after payment.\n\nThe charge is in USD: a card in another currency may add a foreign transaction fee. Once `{{tool:orders pay}}` succeeds, `payment.url` stops working; a payment that fails leaves the link open. `payment_total_changed` means the total sent isn't the order's (`details.total`); the order's total hasn't changed: confirm it with the user, then {{#if claude-skill}}call{{/if}}{{#if cli}}run{{/if}} `{{tool:orders pay}}` again with it and the same token. `payment_declined`: the user picks another payment method in their wallet, or pays by link. `payment_action_required`: the card needs a verification this can't give: pay by link. `payment_credential_invalid`: request a new token with that entry's `limits`. `service_unavailable`: call `{{tool:orders pay}}` again with the same token, never a new one. A token pays one order only.\n\n## Paying with Alipay or WeChat Pay\n\nAn order whose result text has the line \"Pay with Alipay or WeChat Pay\" can be paid in the user's Alipay or WeChat wallet, with no token. {{#if claude-skill}}Call{{/if}}{{#if cli}}Run{{/if}} `{{tool:orders pay}}` {{#if claude-skill}}with `method` `stripe_alipay_wechat_pay`{{/if}}{{#if cli}}the way that line shows{{/if}} and the order's `price.total`, only after the user has confirmed.\n\n1. Confirm the order with the user as before giving the payment link: its total and currency, the stay and every term, and a clear yes.\n2. Then show the `stripe_alipay_wechat_pay` entry of `payment.methods`: the WeChat Pay code as an image if you can, and both links (WeChat Pay and Alipay). The user pays once, by either. Alipay and WeChat Pay charge at once; if the hotel can't confirm, the payment is refunded in full. The total is in the order's currency, and the wallets show it in yuan at their rate.\n3. Check the order with `{{tool:orders get}}` until it isn't `awaiting_payment`.\n\nA WeChat Pay code expires {{limit:wechatCodeMinutes}} minutes after it is made, and goes dead earlier if the user opens the Alipay link instead. Then that entry's `wechatPay.qrData` is null: tell the user to open the WeChat link again, or {{#if claude-skill}}call{{/if}}{{#if cli}}run{{/if}} `{{tool:orders pay}}` again for a new code.\n\nWeChat can't scan a code shown on the same phone's screen. Offer both ways, since you can't tell which device the user is on: save the image and scan it from the album (WeChat, then Scan, then Album), or open the WeChat link on another screen; on a phone, the Alipay link opens the Alipay app.\n\n## After payment\n\nCheck the order with `{{tool:orders get}}`:\n\n- `confirming` while the hotel confirms, then `confirmed` with the hotel's `confirmationNumber`.\n- `failed`: no stay was booked; `payment.status` says whether the payment was released or refunded.\n- `needs_attention`: Fortrip is looking into it; the user can email {{support}} with the `reference`.\n- `manageUrl` is the user's own page for the order.\n{{/if}}\n",
|
|
15642
|
+
"planning": "# Planning a hotel stay\n\nRead this when the request is more than one hotel for fixed dates: flexible dates, a budget, split stays, several destinations, or \"find me the best\". The rules in {{#if mcp}}the server instructions{{/if}}{{#if claude-skill cli}}SKILL.md{{/if}} still apply{{#if mcp}} (call order, destinations, confirming the order `{{tool:hotels book}}` returns before giving the payment link){{/if}}; this covers what to ask, how to compare and how to present.{{#if cli}} As there, `fortrip` is short for `npx -y fortrip@latest`.{{/if}}\n\n## What to collect\n\nKeep track of: dates (or the flexible window), nights, destination(s) with their country, rooms and the guests in each room, room constraints (beds, connecting rooms, accessibility), budget, and what the user said matters most (cheapest, most flexible, closest to X).\n\n{{#if mcp}}\nOffers and orders take one party per call, every room the same, so if the party doesn't split evenly across the rooms, ask how it splits. Rooms for different parties are priced and ordered separately, each order with its own payment link.\n\n{{/if}}\nAsk only for what changes which hotels qualify or how they rank. \"4 stars\" as {{#if mcp claude-skill}}`{ min: 4, max: 4 }`{{/if}}{{#if cli}}`--stars-min 4 --stars-max 4`{{/if}} leaves out 4.5: unless the user means exactly 4, use {{#if mcp claude-skill}}`{ min: 4 }`{{/if}}{{#if cli}}`--stars-min 4`{{/if}} or ask.{{#if mcp}} If children come along, ask each child's age; `{{tool:hotels offers}}` needs it. When a place name is ambiguous, ask which place the user means.{{/if}} Don't ask for trip type or style: infer it from the conversation or leave it general.\n\n## Evidence\n\n- {{#if mcp}}A `{{tool:hotels search}}` price is an indicative estimate per room per night, not a quote. Never call a search result available or bookable, and once{{/if}}{{#if claude-skill cli}}Once{{/if}} you have offers, compare offers only. A hotel without a search price can still have offers.\n- Use `{{tool:hotels get}}` only when a stated preference needs evidence (a pool, a policy, room size). An amenity or policy it doesn't list is unknown, not absent.\n{{#if mcp}}\n- A hotel is available only once `{{tool:hotels offers}}` returned an offer for it.\n{{/if}}\n- Anything {{#if mcp claude-skill}}the tools{{/if}}{{#if cli}}the CLI{{/if}} didn't return, such as reviews, style, price trends or exchange rates, is unknown. Say so instead of filling it in.\n\n## Ranking\n\n1. Drop options that break a hard constraint (dates, guests, budget cap, required facility). Compare a budget in the unit the user gave it: per night, per room or for the whole stay. An offer's `price.total` covers the whole stay and every room, in the offer's currency.\n2. Keep only options with a live offer.\n3. Order by the user's stated main goal. Goals they didn't state don't count.\n4. Use other preferences only to break ties.\n\nUse the cheapest comparable offer as the baseline unless the user fixed the room type. Two or three plans usually suffice, each with its price difference from the baseline and what it trades off (meals, cancellation, location, confirmation). Keep hotel names as returned and dates in the user's notation.\n\nFor a split stay or several destinations, price each leg with its own `{{tool:hotels offers}}` call and add up the legs. Each leg is a separate `{{tool:hotels book}}` call, with its own confirmation and its own payment link.\n\n## Stop and say so\n\n- `{{tool:hotels offers}}` covers up to {{limit:offersHotels}} hotels per call and takes about 15 seconds, and its offers expire after about 30 minutes. If the request needs more hotels or date combinations than a few calls can cover, narrow it with the user, or present the result as a comparison of the hotels you priced, not the best overall.\n- When a search is too broad to price, show its localities and ask the user which they prefer, unless the request already names one of them; never pick one yourself.\n- Urgency is not consent. Call `{{tool:hotels book}}` only for the offer the user picked, and give its payment link only after the user confirms the total, currency, stay and terms of the order `{{tool:hotels book}}` returned.\n",
|
|
15643
15643
|
"presentation": "{{#if claude-skill}}\n## Presenting hotels\n\nIf your interface can show rich elements, show each hotel as a card with only what Fortrip's tools returned for it in this conversation: photo, name, stars, region and price, and once you have offers every term that changes the choice (meals and who they cover, cancellation, fees payable at the property, confirmation), an unknown one as unknown. Label a search's `price.fromPerRoomNight` as an estimate per room-night and an offer's `price.total` as the whole stay for all rooms, in its currency, and draw a map only from returned `location` coordinates. Offer the choices you need to ask anyway (dates, a locality, which offer) as options to pick. Otherwise use a short list. Keep hotel names as returned, and never invent photos, ratings, reviews, prices, terms or coordinates.\n{{/if}}\n",
|
|
15644
|
-
"prices": "{{#if claude-skill cli}}\n## Prices and currency\n\n- A search price (`price.fromPerRoomNight`) is indicative and not bookable: the lowest price of one unit (a room or, at a hostel, possibly a bed) per night, for any party and often any date, and it can be well above or below the offers. Call it an estimate, quote `{{tool:hotels offers}}` prices, and never call a search result available or bookable. `price: null` means there is no indicative price, not that the hotel is full; about half the hotels have none for given dates.\n{{/if}}\n
|
|
15644
|
+
"prices": "{{#if claude-skill cli}}\n## Prices and currency\n\n- A search price (`price.fromPerRoomNight`) is indicative and not bookable: the lowest price of one unit (a room or, at a hostel, possibly a bed) per night, for any party and often any date, and it can be well above or below the offers. Call it an estimate, quote `{{tool:hotels offers}}` prices, and never call a search result available or bookable. `price: null` means there is no indicative price, not that the hotel is full; about half the hotels have none for given dates.\n{{/if}}\n- {{#if claude-skill cli}}In an offer or order, `price.total` is the whole stay for all rooms and is what is charged, in the request's `{{arg:currency}}` (`USD` by default); an{{/if}}{{#if mcp}}An{{/if}} order is in the currency of the offer it was made from.{{#if claude-skill cli}} `perNightAllRooms` is the total per night; to compare with a per-room budget, also divide by the rooms.{{/if}} On a USD order, Stripe's page may let the user pay in their card's local currency at Stripe's rate{{#if claude-skill cli}} (Adaptive Pricing): say so plainly, and that the total in that currency is the price{{/if}}.\n{{#if claude-skill cli}}\n- Every price of a response is in that one currency; don't convert it. `{{arg:currency}}`{{#if cli}} (or `FORTRIP_CURRENCY`){{/if}} is `USD` (the default) or `CNY`.\n- Each currency is paid through its own channel, with its own payment methods; the order's payment page shows them. CNY is paid through payment channels in mainland China and suits a user who pays that way.\n- A search not in CNY may carry `currencyHint` (CNY) when the request or the user's latest sign-in comes from mainland China: offer CNY prices if the user may pay that way, and then use CNY for both the search and the offers.\n- Fees payable at the property (`payAtProperty`) are separate, in the property's own currency, not converted.\n- After payment, `payment.localCharge` is what the card paid in its own currency. Orders made on the Fortrip website can be charged in another currency: `payment.chargeCurrency` says which.\n{{/if}}\n",
|
|
15645
15645
|
"scope": "{{#if claude-skill cli}}\n# Fortrip hotel stays\n\n{{/if}}\nFortrip: hotel search, live offers and orders with a payment link.{{#if claude-skill cli}} Not for flights, activities, or changing an existing order.{{/if}}\n\n{{#if mcp}}\nCall order: `{{tool:hotels search}}` \u2192 (optional) `{{tool:hotels get}}` \u2192 `{{tool:hotels offers}}` \u2192 `{{tool:hotels book}}`; after the user pays, `{{tool:orders get}}`; `{{tool:orders list}}` lists, `{{tool:orders cancel}}` cancels or closes an unpaid one, `{{tool:orders pay}}` pays by token or Alipay/WeChat Pay.\n{{/if}}\n{{#if claude-skill}}\nThe tools are on Fortrip's MCP server, named `fortrip` in this plugin (a Fortrip connector added on claude.ai can show under its own name). They're written `fortrip:<tool>` below:\n{{/if}}\n{{#if cli}}\nThe `fortrip` CLI (npm package `fortrip`) calls Fortrip as the signed-in user and prints each answer as compact text (`--json` prints its JSON):\n{{/if}}\n{{#if claude-skill cli}}\n\n| {{#if claude-skill}}Tool{{/if}}{{#if cli}}Command{{/if}} | Returns |\n|---|---|\n| `{{tool:hotels search}}` | Hotels in a place, near a point or matching a name (`{{arg:text}}`), with indicative prices |\n| `{{tool:hotels get}}` | One hotel's address, check-in and check-out times, description, policies, amenities and rooms; no prices |\n| `{{tool:hotels offers}}` | Live offers (room, meals, total and currency, cancellation terms) for up to {{limit:offersHotels}} hotels |\n| `{{tool:hotels book}}` | An unpaid order for one offer, with its terms and a payment link |\n| `{{tool:orders get}}` | One order and its status, including whether the hotel confirmed it |\n| `{{tool:orders list}}` | The user's orders, newest first, including those made on the Fortrip website |\n| `{{tool:orders cancel}}` | Cancels an order under its terms, for the penalty the user agreed to, and refunds the rest; closes an unpaid one |\n| `{{tool:orders pay}}` | Pays an order without its link, by a shared payment token from the user's wallet, or with Alipay or WeChat Pay |\n\nFor flexible dates, a budget, split stays, several destinations or \"find me the best\", read [references/planning.md](references/planning.md) before searching.\n{{/if}}\n",
|
|
15646
|
-
"setup": "{{#if cli}}\n## Setup\n\nRun every command as `npx -y fortrip@latest <command>` (Node.js 22 or newer). The examples below shorten that to `fortrip`; `fortrip <command> --help` lists a command's flags. `{{tool:hotels search}}`, `{{tool:hotels offers}}` and `{{tool:hotels book}}` also take `--body '<json>'` (or `--body @file.json`), the raw request body; flags override its fields. Add `--json` to any command that calls Fortrip to get its answer as one line of JSON instead of text.\n\
|
|
15646
|
+
"setup": "{{#if cli}}\n## Setup\n\nRun every command as `npx -y fortrip@latest <command>` (Node.js 22 or newer). The examples below shorten that to `fortrip`; `fortrip <command> --help` lists a command's flags. `{{tool:hotels search}}`, `{{tool:hotels offers}}` and `{{tool:hotels book}}` also take `--body '<json>'` (or `--body @file.json`), the raw request body; flags override its fields. Add `--json` to any command that calls Fortrip to get its answer as one line of JSON instead of text.\n\nRunning `{{tool:whoami}}` when the user first asks about hotels lets the sign-in happen while they answer your follow-up questions.\n\n{{/if}}\n{{#if claude-skill cli}}\n## Sign-in\n\n{{/if}}\nSign-in happens only in the browser. Never ask the user to paste a token.\n{{#if claude-skill}}\n\nIf none of these tools are available, Fortrip isn't connected: tell the user to add the Fortrip connector or plugin and sign in.\n{{/if}}\n{{#if mcp claude-skill}}\nIf a tool says the user isn't signed in, ask them to reconnect.\n{{/if}}\n{{#if cli}}\n\nIf a command exits with code **3** and stderr has `loginUrl`, show it to the user as a link together with `userCode`, e.g. \"Sign in to Fortrip: <loginUrl> (code <userCode>), then tell me when you're done.\" When they confirm, rerun the same command; it finishes the sign-in itself. Don't run `{{tool:login}}`: it waits for up to 10 minutes. Commands that exit 3 together share one `loginUrl`; show it once. If the rerun gives a different `loginUrl`, show that one.\n\nWhen Fortrip no longer accepts the saved sign-in (it was revoked, or it expired and couldn't be renewed), the command also exits 3 with a `loginUrl`; handle it the same way. The saved sign-in is kept until the user approves the new link.\n\nIn a remote agent environment or a CI run without a browser, the user can set `FORTRIP_TOKEN` instead. Exit 3 with `tokenSource: \"FORTRIP_TOKEN\"` means Fortrip didn't accept that token: tell the user to replace or unset it.\n\n## Exit codes\n\n| Code | Meaning | What to do |\n|---|---|---|\n| 0 | Success; the answer on stdout | Continue |\n| 1 | Any other error: an error from Fortrip (see Errors), a network error or a timeout | Read the error on stderr. If `retryable` is true, wait `retryAfterSeconds` (or a few seconds) and retry once |\n| 2 | Invalid arguments, or `invalid_request` from Fortrip | Fix the flags; the error lists each bad field with a message |\n| 3 | Not signed in | Show `loginUrl` to the user, then rerun (above) |\n| 4 | Rate limited | Wait `retryAfterSeconds`, then retry once |\n\nOutput on stdout or stderr can carry `warning` (with `recoveryFile` when a sign-in couldn't be saved): pass it on to the user.\n{{/if}}\n",
|
|
15647
15647
|
"support": "{{#if claude-skill cli}}\n## Cancelling an order\n\n`{{tool:orders get}}` and `{{tool:orders list}}` say of each order whether the user can cancel it now (`cancel.available`). A paid order (`cancel.reason` `cancellable`) then has the penalty under its terms (`cancel.penalty`) and the refund, what was paid less the penalty (`cancel.refund`), both in the charge currency; an unpaid one (`unpaid`) can be closed instead. Otherwise `cancel.reason` says why not.\n\n1. Show the user the stay (hotel, dates), `cancel.penalty` and `cancel.refund` (amount and currency). A refund of 0 means nothing is paid back: say so plainly.\n2. End that reply by asking the user to confirm the cancellation, and wait for a clear yes.\n3. Then {{#if claude-skill}}call{{/if}}{{#if cli}}run{{/if}} `{{tool:orders cancel}}` with `{{arg:maximumPenalty}}` set to `cancel.penalty` as shown{{#if cli}}, its amount: the CLI takes the currency from the order{{/if}}. Never state a refund the order didn't return, and never choose or work out an amount yourself.\n\nThe order is then `cancelling`, and `cancelled` once the hotel has cancelled and the refund is issued: check it with `{{tool:orders get}}`. If the hotel refuses, the order is `confirmed` again with `cancel.reason` `refused`. `cancellation_changed` (409) means the penalty is now higher than the one the user agreed to: read the order again and ask the user again. `order_not_cancellable` (409) says why in `reason`.\n\nClose an unpaid order only once the user says they no longer want it: {{#if claude-skill}}call{{/if}}{{#if cli}}run{{/if}} `{{tool:orders cancel}}` {{#if claude-skill}}without `maximumPenalty`{{/if}}{{#if cli}}with `--close`{{/if}}. It becomes `expired`, and nothing is charged. `payment_in_progress` (409) means a payment of it is under way: read it again shortly.{{#if cli}} Without `--max-penalty` or `--close`, `{{tool:orders cancel}}` changes nothing: it prints the penalty and the refund, or that the order can be closed, and exits 2.{{/if}}\n\n## Changes and support\n\n{{/if}}\n{{#if mcp}}For changes{{/if}}{{#if claude-skill}}These tools can't change an order: for changes{{/if}}{{#if cli}}The CLI can't change an order: for changes{{/if}}, a cancellation that `{{tool:orders cancel}}` can't make, or other problems, the user emails {{support}} with the order's `reference` (never `payment.url`).\n"
|
|
15648
15648
|
};
|
|
15649
15649
|
|
|
@@ -15997,6 +15997,12 @@ var searchResult = openObject({
|
|
|
15997
15997
|
"When a place_name search matched few hotels: how many in its country match the name as text; otherwise null."
|
|
15998
15998
|
)
|
|
15999
15999
|
}).describe("What the search covered: counts of hotels, each null when it doesn't apply."),
|
|
16000
|
+
currencyHint: openObject({
|
|
16001
|
+
currency: openEnum(["CNY"]),
|
|
16002
|
+
reason: openEnum(["request_location", "sign_in_location"])
|
|
16003
|
+
}).optional().describe(
|
|
16004
|
+
"Present only when the search is not in that currency and the user may pay through its channel: this request comes from mainland China (request_location), or the user's latest sign-in to Fortrip was there (sign_in_location). Prices are also available in that currency; a suggestion, not a requirement."
|
|
16005
|
+
),
|
|
16000
16006
|
data: external_exports.array(hotelSummary),
|
|
16001
16007
|
nextCursor: external_exports.string().nullable().describe("Pass it back as cursor for the next page; null on the last page."),
|
|
16002
16008
|
notes: external_exports.array(
|
|
@@ -16255,7 +16261,7 @@ var paymentMethod = openUnion("id", [
|
|
|
16255
16261
|
)
|
|
16256
16262
|
}).describe("What the shared payment token for pay_order must allow.")
|
|
16257
16263
|
}).describe(
|
|
16258
|
-
`A Stripe shared payment token, through pay_order's sharedPaymentToken or payment. The entry is absent when a token can't pay
|
|
16264
|
+
`A Stripe shared payment token, through pay_order's sharedPaymentToken or payment. The entry is absent when a token can't pay this order (for example over $${LIMITS.tokenPaymentMaxUsd}, not charged in USD, or started on the Fortrip website); then give payment.url or use another entry.`
|
|
16259
16265
|
),
|
|
16260
16266
|
openObject({
|
|
16261
16267
|
id: external_exports.literal("stripe_alipay_wechat_pay"),
|
|
@@ -16302,7 +16308,7 @@ var order = openObject({
|
|
|
16302
16308
|
orderId,
|
|
16303
16309
|
reference: orderReference,
|
|
16304
16310
|
status: openEnum(ORDER_STATUSES).describe(
|
|
16305
|
-
"awaiting_payment:
|
|
16311
|
+
"awaiting_payment: not paid yet (a payment just made may still be settling); payable until payment.expiresAt. expired: not paid; the time ran out or the order was closed. Nothing charged. confirming: paid or held, the booking is with the hotel. confirmed: the hotel confirmed and the payment is charged. failed: no stay was booked; payment.status says what became of the money. cancelling, then cancelled: a cancellation under the terms. needs_attention: a person at Fortrip has to resolve it."
|
|
16306
16312
|
),
|
|
16307
16313
|
createdAt: instant,
|
|
16308
16314
|
updatedAt: instant,
|
|
@@ -16315,7 +16321,7 @@ var order = openObject({
|
|
|
16315
16321
|
payment: openObject({
|
|
16316
16322
|
status: openEnum(PAYMENT_STATUSES),
|
|
16317
16323
|
url: external_exports.string().nullable().describe(
|
|
16318
|
-
"The payment page, on fortrip.ai; it continues to the payment provider. With requiresSignIn false anyone holding it can pay; with requiresSignIn true (an order started on the Fortrip website) it continues to the Fortrip booking page, where only the signed-in owner can pay. null while a payment is held (authorized) or when the order isn't awaiting payment, or, while it is and its payment is unpaid,
|
|
16324
|
+
"The payment page, on fortrip.ai; it continues to the payment provider. With requiresSignIn false anyone holding it can pay; with requiresSignIn true (an order started on the Fortrip website) it continues to the Fortrip booking page, where only the signed-in owner can pay. null while a payment is held (authorized) or when the order isn't awaiting payment, or, while it is and its payment is unpaid, while a payment is being processed: read the order again shortly, and don't give an earlier link."
|
|
16319
16325
|
),
|
|
16320
16326
|
requiresSignIn: external_exports.boolean(),
|
|
16321
16327
|
expiresAt: instant.nullable().describe(
|
|
@@ -16325,7 +16331,7 @@ var order = openObject({
|
|
|
16325
16331
|
"USD or CNY: the currency of the offer the order was made from. An order made on the Fortrip website may be in another currency."
|
|
16326
16332
|
),
|
|
16327
16333
|
localCurrencyAtCheckout: external_exports.boolean().describe(
|
|
16328
|
-
"Whether paying by url may charge the card in its own currency, converted by Stripe; false once paid by token, Alipay or WeChat Pay; always false on a CNY order."
|
|
16334
|
+
"Whether paying by url may charge the card in its own currency, converted by Stripe; false once paid by token, or by Alipay or WeChat Pay through pay_order or the Fortrip page; always false on a CNY order."
|
|
16329
16335
|
),
|
|
16330
16336
|
localCharge: money.nullable().describe(
|
|
16331
16337
|
"What the card was charged in its own currency, when Stripe converted the total; otherwise null. Always null on a CNY order."
|
|
@@ -16440,7 +16446,7 @@ var CALLS = {
|
|
|
16440
16446
|
penalty: "Pass maximumPenalty as cancel.penalty, exactly as returned.",
|
|
16441
16447
|
close: "call cancel_order",
|
|
16442
16448
|
pay: "call pay_order",
|
|
16443
|
-
payWallet: " with method stripe_alipay_wechat_pay",
|
|
16449
|
+
payWallet: " with method stripe_alipay_wechat_pay and the order's price.total",
|
|
16444
16450
|
get: "call get_order",
|
|
16445
16451
|
poll: "poll get_order",
|
|
16446
16452
|
payWith: "call pay_order with it and the order's price.total",
|
|
@@ -16451,7 +16457,7 @@ var CALLS = {
|
|
|
16451
16457
|
close: "run `fortrip orders cancel <orderId> --close`",
|
|
16452
16458
|
penalty: "Pass the penalty's amount as --max-penalty (120.00 for a penalty of USD 120.00).",
|
|
16453
16459
|
pay: "run `fortrip orders pay`",
|
|
16454
|
-
payWallet: " with --method stripe_alipay_wechat_pay",
|
|
16460
|
+
payWallet: " with --method stripe_alipay_wechat_pay --total <total>",
|
|
16455
16461
|
get: "run `fortrip orders get <orderId>`",
|
|
16456
16462
|
poll: "poll it with `fortrip orders get <orderId>`",
|
|
16457
16463
|
payWith: "run `fortrip orders pay <orderId> --token <spt_\u2026> --total <total>` with the token and the order's total",
|
|
@@ -16494,7 +16500,7 @@ var TOOLS = [
|
|
|
16494
16500
|
{
|
|
16495
16501
|
name: "search_hotels",
|
|
16496
16502
|
title: "Search hotels",
|
|
16497
|
-
description:
|
|
16503
|
+
description: "Find hotels by destination and/or text, with an indicative per-room-night price when a stay is given. destination is a place_name with its countryCode, a place or locality by placeId from an earlier answer, a point, or a country. text matches hotel names, brands and areas word for word. Indicative prices are estimates and not bookable: get_hotel_offers returns what the user pays. A name several places bear answers destination_ambiguous, and a search too broad to answer search_too_broad with its localities; each error says what to do next. The answer states the scope, the counts and notes; a next page is the cursor and, optionally, limit.",
|
|
16498
16504
|
annotations: READ,
|
|
16499
16505
|
input: searchHotelsInput,
|
|
16500
16506
|
output: searchResult
|
|
@@ -16510,7 +16516,7 @@ var TOOLS = [
|
|
|
16510
16516
|
{
|
|
16511
16517
|
name: "get_hotel_offers",
|
|
16512
16518
|
title: "Live offers",
|
|
16513
|
-
description: `Live, bookable offers for up to ${LIMITS.offersHotels} hotels and one stay. Every room in stay.rooms must have the same party: for different parties, call once per party. Each offer has the room, the meals included, price.total, in the request's currency, for the whole stay and every room (what is charged), fees payable at the property, the cancellation terms with times in UTC and the hotel's time zone, the confirmation mode, and an offerId for book_hotel that expires at expiresAt. Hotels with nothing to offer are listed under unavailable with the reason. Up to limitPerHotel offers per hotel
|
|
16519
|
+
description: `Live, bookable offers for up to ${LIMITS.offersHotels} hotels and one stay. Every room in stay.rooms must have the same party: for different parties, call once per party. Each offer has the room, the meals included, price.total, in the request's currency, for the whole stay and every room (what is charged), fees payable at the property, the cancellation terms with times in UTC and the hotel's time zone, the confirmation mode, and an offerId for book_hotel that expires at expiresAt. Hotels with nothing to offer are listed under unavailable with the reason. Up to limitPerHotel offers per hotel (default ${LIMITS.offersPerHotelDefault}), picked to span price, free cancellation, breakfast and rooms, listed cheapest first; the answer counts those not shown.`,
|
|
16514
16520
|
annotations: READ,
|
|
16515
16521
|
input: hotelOffersInput,
|
|
16516
16522
|
output: hotelOffersResult
|
|
@@ -16518,7 +16524,7 @@ var TOOLS = [
|
|
|
16518
16524
|
{
|
|
16519
16525
|
name: "book_hotel",
|
|
16520
16526
|
title: "Create order",
|
|
16521
|
-
description: `Order one offer from get_hotel_offers. The answer is an unpaid order with a payment link: status awaiting_payment, the total, the stay and its terms, and payment.url, a Fortrip page to pay on. Nothing is charged until the order is paid, on that page or with pay_order
|
|
16527
|
+
description: `Order one offer from get_hotel_offers. The answer is an unpaid order with a payment link: status awaiting_payment, the total, the stay and its terms, and payment.url, a Fortrip page to pay on. Nothing is charged until the order is paid, on that page or with pay_order; anyone holding the link can pay. Send the contact and, for each room of the offer, at least one guest. If the price or terms changed since the offer, the answer is offer_changed with every change and a new offer: show the changes and ask the user again before ordering it. Sending the same details again returns the same order. An offer is ordered once: for another order of the stay (another party, or a corrected guest name), get offers again and order the new offer; when it replaces an unpaid order, tell the user to pay only the new link, as the earlier one expires unpaid. To cancel an order, use cancel_order; for changes, or a cancellation cancel_order can't make, the user emails ${SUPPORT_EMAIL} with the order's reference.`,
|
|
16522
16528
|
annotations: {
|
|
16523
16529
|
readOnlyHint: false,
|
|
16524
16530
|
idempotentHint: false,
|
|
@@ -16531,7 +16537,7 @@ var TOOLS = [
|
|
|
16531
16537
|
{
|
|
16532
16538
|
name: "get_order",
|
|
16533
16539
|
title: "Get order",
|
|
16534
|
-
description: "One of the user's orders by orderId: its status, the payment status and, while it awaits payment, payment.url; the stay and its terms; and the hotel's confirmation number once there is one. Check it after the user pays.
|
|
16540
|
+
description: "One of the user's orders by orderId: its status, the payment status and, while it awaits payment, payment.url; the stay and its terms; and the hotel's confirmation number once there is one. Check it after the user pays.",
|
|
16535
16541
|
annotations: READ_OWN,
|
|
16536
16542
|
input: getOrderInput,
|
|
16537
16543
|
output: MCP_OUTPUT.get_order
|
|
@@ -16547,7 +16553,7 @@ var TOOLS = [
|
|
|
16547
16553
|
{
|
|
16548
16554
|
name: "cancel_order",
|
|
16549
16555
|
title: "Cancel order",
|
|
16550
|
-
description: `Cancel a paid order under its terms, or close an unpaid one. Paid (cancel.reason cancellable): the
|
|
16556
|
+
description: `Cancel a paid order under its terms, or close an unpaid one. Paid (cancel.reason cancellable): only after the user confirmed the order's cancel.penalty and cancel.refund with a clear yes, pass maximumPenalty, that cancel.penalty exactly as returned. The order becomes cancelling, then cancelled with cancel.refund refunded, or confirmed with reason refused if the hotel refuses: poll get_order. cancellation_changed: the penalty rose above maximumPenalty and nothing changed; ask the user again. Never state a refund the order did not return. Unpaid (cancel.reason unpaid): close it, without maximumPenalty, only once the user says they no longer want it; nothing is charged and it becomes expired. If it was paid meanwhile, the answer is the paid order, invalid_request, order_not_cancellable or order_in_progress: cancel it only under its cancel.penalty, with the user's yes. payment_in_progress: read it again shortly. Repeat calls answer the order as it is.`,
|
|
16551
16557
|
annotations: {
|
|
16552
16558
|
readOnlyHint: false,
|
|
16553
16559
|
idempotentHint: true,
|
|
@@ -16560,7 +16566,7 @@ var TOOLS = [
|
|
|
16560
16566
|
{
|
|
16561
16567
|
name: "pay_order",
|
|
16562
16568
|
title: "Pay order",
|
|
16563
|
-
description: `Pay
|
|
16569
|
+
description: `Pay a USD order without its link, by one of its payment.methods: a Stripe shared payment token, only if you can request one from the user's Link wallet (US and Canadian accounts; never ask the user for one), or Alipay/WeChat Pay (method stripe_alipay_wechat_pay). Call it only after the user confirmed the order's total and currency, the stay and every term with a clear yes. Token: request it with the entry's handler config.business_profile and limits, and pass it with price.total; a token pays one order. Wallet: pass method and price.total, then show the entry it returns: the WeChat code as an image if you can, and both links; the user pays once, by either. A code lasts ${LIMITS.wechatCodeMinutes} minutes; then the WeChat link opens a new one, or call again. Pay one way only: success closes payment.url, a failure leaves it open, and each error says how to recover. Then poll get_order.`,
|
|
16564
16570
|
annotations: {
|
|
16565
16571
|
readOnlyHint: false,
|
|
16566
16572
|
idempotentHint: true,
|
|
@@ -16966,7 +16972,7 @@ var CANCEL_REASON_WORDS = {
|
|
|
16966
16972
|
cancellable: "it can be cancelled",
|
|
16967
16973
|
unpaid: "it isn't paid: it can be closed if the user no longer wants it",
|
|
16968
16974
|
already_cancelled: "it is already cancelled",
|
|
16969
|
-
in_progress: "a cancellation is
|
|
16975
|
+
in_progress: "the booking is still being confirmed, or a cancellation is under way; read the order again later",
|
|
16970
16976
|
not_confirmed: "only a confirmed order that is paid can be cancelled",
|
|
16971
16977
|
stay_started: `the stay has started; ${SUPPORT}`,
|
|
16972
16978
|
non_refundable: "this rate can't be cancelled",
|
|
@@ -17009,7 +17015,7 @@ function paymentLines(o, surface) {
|
|
|
17009
17015
|
].filter(Boolean);
|
|
17010
17016
|
lines.push(`Payment link (${about.join("; ")}): ${p.url}`);
|
|
17011
17017
|
} else if (o.status === "awaiting_payment" && p.status === "unpaid") {
|
|
17012
|
-
lines.push("Payment link:
|
|
17018
|
+
lines.push("Payment link: none while a payment is being processed; read this order again shortly.");
|
|
17013
17019
|
}
|
|
17014
17020
|
const token = methodOf(o, "stripe_shared_payment_token");
|
|
17015
17021
|
if (token) lines.push(tokenLine(o, token, surface));
|
|
@@ -17022,11 +17028,7 @@ function paymentLines(o, surface) {
|
|
|
17022
17028
|
function tokenLine(o, token, surface) {
|
|
17023
17029
|
const { handler: h, limits } = token;
|
|
17024
17030
|
const pay = surface === "cli" ? `\`fortrip orders pay ${o.orderId} --token <spt_\u2026> --total ${o.price.total.amount}\`` : "pay_order";
|
|
17025
|
-
return
|
|
17026
|
-
`Pay without the link: ${pay} with a shared payment token via ${h.type} (handler ${h.id}, business_profile ${h.config.business_profile}); token limits: maxAmount ${limits.maxAmount} (cents), currency ${limits.currency}, expiresAt ${limits.expiresAt}.`,
|
|
17027
|
-
"Only if you have a tool that can request the token from the user's Link wallet (US and Canadian Link accounts); otherwise give the payment link, and never ask the user to create, type or paste a token.",
|
|
17028
|
-
`First show the user the total and currency, the stay and every term, and wait for a clear yes. Pay one way only: the link or ${surface === "cli" ? "`fortrip orders pay`" : "pay_order"}.`
|
|
17029
|
-
].join(" ");
|
|
17031
|
+
return `Pay without the link: ${pay} with a shared payment token via ${h.type} (handler ${h.id}, business_profile ${h.config.business_profile}); token limits: maxAmount ${limits.maxAmount} (cents), currency ${limits.currency}, expiresAt ${limits.expiresAt}.`;
|
|
17030
17032
|
}
|
|
17031
17033
|
function walletLines(w, surface) {
|
|
17032
17034
|
const c = CALLS[surface];
|
|
@@ -17226,6 +17228,15 @@ function hotelLine(h, i, r) {
|
|
|
17226
17228
|
h.hotelId
|
|
17227
17229
|
].filter(Boolean).join(" \xB7 ");
|
|
17228
17230
|
}
|
|
17231
|
+
var HINT_REASONS = {
|
|
17232
|
+
request_location: "this request comes from mainland China",
|
|
17233
|
+
sign_in_location: "the user's latest sign-in to Fortrip was from mainland China"
|
|
17234
|
+
};
|
|
17235
|
+
function currencyHintLine(hint, surface) {
|
|
17236
|
+
const reason = HINT_REASONS[hint.reason];
|
|
17237
|
+
const again = surface === "cli" ? "search and get offers with --currency CNY" : "search and get offers with currency CNY";
|
|
17238
|
+
return `Currency: ${reason ? `${reason}. ` : ""}Prices are also available in CNY, paid through payment channels in mainland China; if the user may pay that way, offer them CNY prices: ${again}.`;
|
|
17239
|
+
}
|
|
17229
17240
|
function renderSearch(r, surface = "mcp") {
|
|
17230
17241
|
const lines = [header(r)];
|
|
17231
17242
|
lines.push(
|
|
@@ -17262,6 +17273,7 @@ function renderSearch(r, surface = "mcp") {
|
|
|
17262
17273
|
"",
|
|
17263
17274
|
r.nextCursor === null ? "Last page." : surface === "cli" ? `Next page: run again with only --cursor ${r.nextCursor} and, optionally, --limit.` : `Next page: call again with only the cursor and, optionally, limit: { cursor: "${r.nextCursor}" }.`
|
|
17264
17275
|
);
|
|
17276
|
+
if (r.currencyHint?.currency === "CNY") lines.push("", currencyHintLine(r.currencyHint, surface));
|
|
17265
17277
|
return lines.join("\n");
|
|
17266
17278
|
}
|
|
17267
17279
|
|
|
@@ -17396,7 +17408,7 @@ function detailLines(e, surface) {
|
|
|
17396
17408
|
return [`Order ${e.details.orderId}: read it with ${getOrder(e.details.orderId)} in a few seconds.`];
|
|
17397
17409
|
case "payment_total_changed":
|
|
17398
17410
|
return [
|
|
17399
|
-
`Order ${e.details.orderId} totals ${money2(e.details.total)}, not the total sent: confirm this total with the user, then ${surface === "cli" ? `run \`fortrip orders pay ${e.details.orderId}
|
|
17411
|
+
`Order ${e.details.orderId} totals ${money2(e.details.total)}, not the total sent: confirm this total with the user, then ${surface === "cli" ? `run the same \`fortrip orders pay ${e.details.orderId}\` command again with \`--total ${e.details.total.amount}\`` : "call pay_order again with it, the same way (the same token, or method stripe_alipay_wechat_pay)"}. Nothing was charged.`
|
|
17400
17412
|
];
|
|
17401
17413
|
case "payment_credential_invalid":
|
|
17402
17414
|
return [
|
|
@@ -17627,7 +17639,7 @@ function withConsent(tool, surface, text2, orders) {
|
|
|
17627
17639
|
// ../contract/package.json
|
|
17628
17640
|
var package_default = {
|
|
17629
17641
|
name: "@fortrip/agent-contract",
|
|
17630
|
-
version: "5.0
|
|
17642
|
+
version: "5.2.0",
|
|
17631
17643
|
license: "Apache-2.0",
|
|
17632
17644
|
description: "The contract of Fortrip's agent API (https://api.fortrip.ai/v1) and its MCP server: limits, paths, request and response schemas, error codes and field rules.",
|
|
17633
17645
|
type: "module",
|
package/dist/cli.js
CHANGED
|
@@ -28,7 +28,7 @@ import {
|
|
|
28
28
|
unwrap,
|
|
29
29
|
usageError,
|
|
30
30
|
whoami
|
|
31
|
-
} from "./chunk-
|
|
31
|
+
} from "./chunk-V7P6JGK6.js";
|
|
32
32
|
|
|
33
33
|
// src/commands.ts
|
|
34
34
|
import { readFileSync } from "fs";
|
|
@@ -1207,7 +1207,7 @@ async function run(argv) {
|
|
|
1207
1207
|
case "mcp": {
|
|
1208
1208
|
parseOptions(spec, rest);
|
|
1209
1209
|
const mcpUrl = resolveMcpUrl(apiUrl);
|
|
1210
|
-
const { runMcpBridge } = await import("./mcp-bridge-
|
|
1210
|
+
const { runMcpBridge } = await import("./mcp-bridge-P3IRTNHZ.js");
|
|
1211
1211
|
await runMcpBridge(mcpUrl, apiUrl);
|
|
1212
1212
|
return void 0;
|
|
1213
1213
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "fortrip",
|
|
3
|
-
"version": "5.0
|
|
3
|
+
"version": "5.2.0",
|
|
4
4
|
"license": "Apache-2.0",
|
|
5
5
|
"description": "Search, price and book Fortrip hotels from the terminal or an AI agent.",
|
|
6
6
|
"mcpName": "io.github.FortripEngineering/fortrip",
|
|
@@ -33,7 +33,7 @@
|
|
|
33
33
|
"typescript": "^5.9.0",
|
|
34
34
|
"uqr": "0.1.3",
|
|
35
35
|
"zod": "4.4.3",
|
|
36
|
-
"@fortrip/agent-contract": "5.0
|
|
36
|
+
"@fortrip/agent-contract": "5.2.0"
|
|
37
37
|
},
|
|
38
38
|
"scripts": {
|
|
39
39
|
"build": "tsup",
|