fortrip 4.0.0-rc.1 → 4.1.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
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
# fortrip
|
|
2
2
|
|
|
3
|
-
Search hotels,
|
|
4
|
-
terminal or an AI agent. Hotels only for now. The npm package and the command
|
|
3
|
+
Search hotels, compare live rates, book and pay securely, and cancel
|
|
4
|
+
bookings, from the terminal or an AI agent. Hotels only for now. The npm package and the command
|
|
5
5
|
are both `fortrip`; they talk to Fortrip API v1, `https://api.fortrip.ai/v1`.
|
|
6
6
|
|
|
7
7
|
```bash
|
|
@@ -83,11 +83,11 @@ other command that needs to save a sign-in exits 1 too. The error says to set
|
|
|
83
83
|
| `orders get <orderId>` | Show an order and its status |
|
|
84
84
|
| `orders list` | List your orders, newest first |
|
|
85
85
|
| `orders cancel <orderId>` | Cancel an order under its terms, for the penalty the user agreed to |
|
|
86
|
-
| `orders pay <orderId>` | Pay an order
|
|
87
|
-
| `login` | Sign in through the browser
|
|
86
|
+
| `orders pay <orderId>` | Pay an order from the user's Link wallet (US and Canada) instead of its payment link |
|
|
87
|
+
| `login` | Sign in through the browser |
|
|
88
88
|
| `logout` | Revoke and forget the saved token |
|
|
89
89
|
| `whoami` | Show the signed-in account |
|
|
90
|
-
| `guide [topic]` | Print the guide for AI agents (Markdown) |
|
|
90
|
+
| `guide [topic]` | Print the guide for AI agents (Markdown); `fortrip guide planning` prints the planning guide |
|
|
91
91
|
| `mcp` | Run an MCP server over stdio for local clients, bridged to Fortrip's hosted server |
|
|
92
92
|
|
|
93
93
|
```bash
|
|
@@ -138,9 +138,9 @@ npx skills add FortripEngineering/fortrip --skill fortrip-cli
|
|
|
138
138
|
|
|
139
139
|
## MCP server
|
|
140
140
|
|
|
141
|
-
Fortrip's hosted MCP server is `https://mcp.fortrip.ai/`. It has
|
|
141
|
+
Fortrip's hosted MCP server is `https://mcp.fortrip.ai/`. It has nine tools:
|
|
142
142
|
`get_planning_guide`, `search_hotels`, `get_hotel`, `get_hotel_offers`,
|
|
143
|
-
`book_hotel`, `get_order`, `list_orders` and `
|
|
143
|
+
`book_hotel`, `get_order`, `list_orders`, `cancel_order` and `pay_order`.
|
|
144
144
|
|
|
145
145
|
Clients that support remote MCP servers with OAuth don't need the CLI: add
|
|
146
146
|
`https://mcp.fortrip.ai/` as a remote server and sign in to Fortrip in the
|
|
@@ -224,8 +224,10 @@ that starts with `local_`.
|
|
|
224
224
|
|
|
225
225
|
## Support
|
|
226
226
|
|
|
227
|
-
|
|
228
|
-
|
|
227
|
+
A cancellation the CLI can make goes through `fortrip orders cancel`. For
|
|
228
|
+
changes, other cancellations, refunds or other help with a booking, email
|
|
229
|
+
[info@fortrip.ai](mailto:info@fortrip.ai) with the order's reference. Never
|
|
230
|
+
send the payment link.
|
|
229
231
|
|
|
230
232
|
## Releasing
|
|
231
233
|
|
|
@@ -14750,7 +14750,7 @@ var stay = strictInput({
|
|
|
14750
14750
|
"Check-in date in the hotel's calendar, yyyy-MM-dd."
|
|
14751
14751
|
),
|
|
14752
14752
|
checkOut: localDate.describe(
|
|
14753
|
-
`Check-out date in the hotel's calendar, yyyy-MM-dd. Stays are 1 to ${LIMITS.nightsFortrip} nights.`
|
|
14753
|
+
`Check-out date in the hotel's calendar, yyyy-MM-dd. Stays are 1 to ${LIMITS.nightsSupplier} nights; a longer one answers stay_unsupported (max_nights), and past ${LIMITS.nightsFortrip} nights invalid_request: ask the user whether to split it into consecutive stays.`
|
|
14754
14754
|
),
|
|
14755
14755
|
rooms: external_exports.array(
|
|
14756
14756
|
strictInput({
|
|
@@ -14769,7 +14769,7 @@ var stay = strictInput({
|
|
|
14769
14769
|
).min(1, { error: `rooms must list 1 to ${LIMITS.rooms} rooms` }).max(LIMITS.rooms, {
|
|
14770
14770
|
error: `rooms must list 1 to ${LIMITS.rooms} rooms`
|
|
14771
14771
|
}).describe(
|
|
14772
|
-
`The rooms wanted, 1 to ${LIMITS.rooms}, each with its
|
|
14772
|
+
`The rooms wanted, 1 to ${LIMITS.rooms}, each with its party; offers and orders need every room the same.`
|
|
14773
14773
|
)
|
|
14774
14774
|
}).superRefine((value, ctx) => {
|
|
14775
14775
|
if (!isIsoDate(value.checkIn) || !isIsoDate(value.checkOut)) return;
|
|
@@ -15053,10 +15053,10 @@ var createOrderInput = strictInput({
|
|
|
15053
15053
|
}).describe("What the hotel needs to know.")
|
|
15054
15054
|
}),
|
|
15055
15055
|
{ error: "items must list exactly one offer" }
|
|
15056
|
-
).min(1, { error: "items must list exactly one offer" }).max(1, { error: "items must list exactly one offer" }).describe("The offer to book
|
|
15056
|
+
).min(1, { error: "items must list exactly one offer" }).max(1, { error: "items must list exactly one offer" }).describe("The offer to book: exactly one.")
|
|
15057
15057
|
});
|
|
15058
15058
|
var getOrderInput = strictInput({
|
|
15059
|
-
orderId: orderId.describe("
|
|
15059
|
+
orderId: orderId.describe("The order's orderId."),
|
|
15060
15060
|
locale: locale.optional()
|
|
15061
15061
|
});
|
|
15062
15062
|
var listLimitError = `limit must be a whole number from 1 to ${LIMITS.pageSizeMax}`;
|
|
@@ -15069,9 +15069,9 @@ var listOrdersInput = strictInput({
|
|
|
15069
15069
|
});
|
|
15070
15070
|
var maximumPenaltyError = "maximumPenalty must be a number of 0 or more: the order's cancel.penalty.amount, such as 12.5 for 12.50";
|
|
15071
15071
|
var cancelOrderInput = strictInput({
|
|
15072
|
-
orderId: orderId.describe("orderId of the order to cancel
|
|
15072
|
+
orderId: orderId.describe("The orderId of the order to cancel."),
|
|
15073
15073
|
maximumPenalty: external_exports.number({ error: maximumPenaltyError }).min(0, { error: maximumPenaltyError }).describe(
|
|
15074
|
-
|
|
15074
|
+
`The penalty the user agreed to, in the order's currency. Pass maximumPenalty as the number in cancel.penalty.amount ("120.00" \u2192 120).`
|
|
15075
15075
|
)
|
|
15076
15076
|
});
|
|
15077
15077
|
var sharedPaymentTokenRe = /^spt_[A-Za-z0-9]{1,250}$/;
|
|
@@ -15085,7 +15085,9 @@ var ucpInstrument = external_exports.looseObject(
|
|
|
15085
15085
|
handler_id: nonEmpty("handler_id").describe(
|
|
15086
15086
|
"The id of the handler the instrument pays through: the order's stripe_payments for the selected one."
|
|
15087
15087
|
),
|
|
15088
|
-
type: nonEmpty("type").describe(
|
|
15088
|
+
type: nonEmpty("type").describe(
|
|
15089
|
+
"The instrument type: card for the selected one. A Link token is presented as a card instrument, whatever Link funds it with."
|
|
15090
|
+
),
|
|
15089
15091
|
selected: flag("selected").optional().describe(
|
|
15090
15092
|
"Whether this is the instrument to pay with. Exactly one is selected; a lone instrument without it is the one."
|
|
15091
15093
|
),
|
|
@@ -15128,7 +15130,7 @@ function selectedOf(instruments) {
|
|
|
15128
15130
|
return chosen;
|
|
15129
15131
|
}
|
|
15130
15132
|
var payOrderInput = strictInput({
|
|
15131
|
-
orderId: orderId.describe("orderId of the order to pay
|
|
15133
|
+
orderId: orderId.describe("The orderId of the order to pay."),
|
|
15132
15134
|
sharedPaymentToken: external_exports.string({ error: sharedPaymentTokenError }).regex(sharedPaymentTokenRe, { error: sharedPaymentTokenError }).optional().describe(
|
|
15133
15135
|
"The shared payment token (spt_\u2026) the user approved for this order, requested with the order's payment.credentialLimits. Exactly one of sharedPaymentToken and payment."
|
|
15134
15136
|
),
|
|
@@ -15207,10 +15209,11 @@ function fieldDescription(json2, field, sets = {}) {
|
|
|
15207
15209
|
}
|
|
15208
15210
|
function flagsOf(input, defs) {
|
|
15209
15211
|
const json2 = external_exports.toJSONSchema(input, { io: "input" });
|
|
15210
|
-
return defs.map((def) =>
|
|
15211
|
-
|
|
15212
|
-
|
|
15213
|
-
|
|
15212
|
+
return defs.map(({ required: required2, ...def }) => {
|
|
15213
|
+
const description = def.description ?? fieldDescription(json2, def.field, def.sets);
|
|
15214
|
+
const prefix = required2 === "always" ? "Required. " : required2 === "unless-body" ? "Required unless --body gives it. " : "";
|
|
15215
|
+
return { ...def, description: `${prefix}${description}` };
|
|
15216
|
+
});
|
|
15214
15217
|
}
|
|
15215
15218
|
function positional(input, name, description) {
|
|
15216
15219
|
const json2 = external_exports.toJSONSchema(input, { io: "input" });
|
|
@@ -15405,10 +15408,10 @@ var bookFlags = flagsOf(createOrderInput, [
|
|
|
15405
15408
|
placeholder: "<room>:<first>:<last>",
|
|
15406
15409
|
description: "A guest, as `room:first:last`, e.g. `1:John:Smith` for room 1. Repeat for each guest: at least one per room of the offer, no more than the room sleeps. Names in Latin letters as on the passport; transliterate accents (M\xFCller \u2192 Mueller)."
|
|
15407
15410
|
},
|
|
15408
|
-
{ flag: "first-name", field: "contact.firstName", type: "string", placeholder: "<name>" },
|
|
15409
|
-
{ flag: "last-name", field: "contact.lastName", type: "string", placeholder: "<name>" },
|
|
15410
|
-
{ flag: "email", field: "contact.email", type: "string", placeholder: "<email>" },
|
|
15411
|
-
{ flag: "phone", field: "contact.phone", type: "string", placeholder: "<phone>" },
|
|
15411
|
+
{ flag: "first-name", field: "contact.firstName", type: "string", placeholder: "<name>", required: "unless-body" },
|
|
15412
|
+
{ flag: "last-name", field: "contact.lastName", type: "string", placeholder: "<name>", required: "unless-body" },
|
|
15413
|
+
{ flag: "email", field: "contact.email", type: "string", placeholder: "<email>", required: "unless-body" },
|
|
15414
|
+
{ flag: "phone", field: "contact.phone", type: "string", placeholder: "<phone>", required: "unless-body" },
|
|
15412
15415
|
{
|
|
15413
15416
|
flag: "special-requests",
|
|
15414
15417
|
field: "items.hotel.specialRequests",
|
|
@@ -15437,13 +15440,15 @@ var payFlags = flagsOf(payOrderInput, [
|
|
|
15437
15440
|
field: "sharedPaymentToken",
|
|
15438
15441
|
type: "string",
|
|
15439
15442
|
placeholder: "<spt_\u2026>",
|
|
15440
|
-
|
|
15443
|
+
required: "always",
|
|
15444
|
+
description: "The spt_\u2026 token the user's Link wallet issued for this order."
|
|
15441
15445
|
},
|
|
15442
15446
|
{
|
|
15443
15447
|
flag: "total",
|
|
15444
15448
|
field: "total",
|
|
15445
15449
|
type: "string",
|
|
15446
15450
|
placeholder: "<USD decimal>",
|
|
15451
|
+
required: "always",
|
|
15447
15452
|
description: "The total the user approved, exactly as `orders get` shows it, in USD, e.g. `125.00`."
|
|
15448
15453
|
}
|
|
15449
15454
|
]);
|
|
@@ -15516,7 +15521,7 @@ var COMMANDS = [
|
|
|
15516
15521
|
{
|
|
15517
15522
|
group: "orders",
|
|
15518
15523
|
name: "pay",
|
|
15519
|
-
summary: "Pay an order
|
|
15524
|
+
summary: "Pay an order from the user's Link wallet (US and Canada) instead of its payment link",
|
|
15520
15525
|
tool: "pay_order",
|
|
15521
15526
|
flags: payFlags,
|
|
15522
15527
|
positionals: [positional(payOrderInput, "orderId")]
|
|
@@ -15524,7 +15529,7 @@ var COMMANDS = [
|
|
|
15524
15529
|
{
|
|
15525
15530
|
group: null,
|
|
15526
15531
|
name: "login",
|
|
15527
|
-
summary: "Sign in through the browser
|
|
15532
|
+
summary: "Sign in through the browser",
|
|
15528
15533
|
tool: null,
|
|
15529
15534
|
flags: [],
|
|
15530
15535
|
options: [
|
|
@@ -15552,7 +15557,7 @@ var COMMANDS = [
|
|
|
15552
15557
|
{
|
|
15553
15558
|
group: null,
|
|
15554
15559
|
name: "guide",
|
|
15555
|
-
summary: "Print the guide for AI agents (Markdown)",
|
|
15560
|
+
summary: "Print the guide for AI agents (Markdown); `fortrip guide planning` prints the planning guide",
|
|
15556
15561
|
tool: "get_planning_guide",
|
|
15557
15562
|
flags: [],
|
|
15558
15563
|
positionals: [
|
|
@@ -15602,10 +15607,10 @@ var FRAGMENTS = {
|
|
|
15602
15607
|
"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',
|
|
15603
15608
|
"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{{/if}}\n- Offers and orders take one party per call, every room the same: for different parties, order once per party.{{#if claude-skill cli}} `{{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`.{{/if}}\n{{#if claude-skill cli}}\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",
|
|
15604
15609
|
"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 the `hub` it belongs to: search the hub, 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- Typos return nothing: "Shangahi" finds no hotel.\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 USD; 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. A typo finds nothing.\n{{/if}}\n',
|
|
15605
|
-
"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 payment on Stripe. 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: don't shorten, rebuild or re-encode it.\n\n{{/if}}\n{{#if mcp}}\n-
|
|
15610
|
+
"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 payment on Stripe. 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: don't shorten, rebuild or re-encode it.\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.\n- An order `awaiting_payment` whose `payment.url` is null had its link unreadable this time: read it again with `{{tool:orders get}}`.\n{{/if}}\n- Never ask for, accept or pass on payment card details; payment happens only through Stripe.{{#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.handlers` isn't empty (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 $500, so `payment.handlers` is empty for a larger order. Otherwise give `payment.url`, and never ask the user to create, type or paste a token.\n\n1. Show the user the order's total and currency, the stay (hotel, room, dates, rooms and guests per room) and every term: meals, cancellation and fees payable at the property. End that reply by asking the user to confirm, and wait for 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 the handler's `config.business_profile` and `payment.credentialLimits`: `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. Pay one way only: either give `payment.url` or {{#if claude-skill}}call{{/if}}{{#if cli}}run{{/if}} `{{tool:orders pay}}`. 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 the order's `payment.credentialLimits`. `service_unavailable`: call `{{tool:orders pay}}` again with the same token, never a new one. A token pays one order only.\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",
|
|
15606
15611
|
"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}}SKILL.md{{/if}}{{#if cli}}`{{tool:guide}}`{{/if}} still apply (call order, destinations, one party per offer and order, confirming the order `{{tool:hotels book}}` returns before giving the payment link); 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\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\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 children come along, ask each child's age; `{{tool:hotels offers}}` needs it. Don't ask for trip type or style: infer it from the conversation or leave it general. When a place name is ambiguous, ask which place the user means.\n\n## Evidence\n\n- 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 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- A hotel is available only once `{{tool:hotels offers}}` returned an offer for it.\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 other than `approx`, 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 USD.\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. Show at most three plans, 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",
|
|
15607
15612
|
"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 USD, 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",
|
|
15608
|
-
"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 mcp}}\n- Search prices are indicative, not bookable: quote `{{tool:hotels offers}}` prices.\n{{/if}}\n- {{#if claude-skill cli}}In an offer or order, {{/if}}`price.total` is the whole stay for all rooms and is what is charged, in USD for offers and the orders made from them.{{#if claude-skill cli}} `perNightAllRooms` is the total per night; to compare with a per-room budget, also divide by the rooms.{{/if}} Stripe's page may let the user pay in their card's local currency at Stripe's rate
|
|
15613
|
+
"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 mcp}}\n- Search prices are indicative, not bookable: quote `{{tool:hotels offers}}` prices.\n{{/if}}\n- {{#if claude-skill cli}}In an offer or order, {{/if}}`price.total` is the whole stay for all rooms and is what is charged, in USD for offers and the orders made from them.{{#if claude-skill cli}} `perNightAllRooms` is the total per night; to compare with a per-room budget, also divide by the rooms.{{/if}} 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 USD total is the price{{/if}}. `approx`{{#if claude-skill cli}}, in `{{arg:displayCurrency}}`, with its `rateDate`,{{/if}} is an estimate, never the charge.\n{{#if claude-skill cli}}\n- `{{arg:displayCurrency}}`{{#if cli}} (or `FORTRIP_DISPLAY_CURRENCY`){{/if}} is `USD` or `CNY`: `CNY` adds `approx` in yuan to suit a user who thinks in it. It never changes the charge.\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",
|
|
15609
15614
|
"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 them; `{{tool:orders cancel}}` cancels one, `{{tool:orders pay}}` pays by token. `{{tool:guide}}` returns Fortrip's guidance for flexible dates, budgets or several destinations.\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 in USD, 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 |\n| `{{tool:orders pay}}` | Pays an order without its link, with a shared payment token from the user's wallet |\n\nFor flexible dates, a budget, split stays, several destinations or \"find me the best\", {{#if claude-skill}}read [references/planning.md](references/planning.md){{/if}}{{#if cli}}also run `{{tool:guide}} planning`{{/if}} before searching.\n{{/if}}\n",
|
|
15610
15615
|
"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\nWhen the user first asks about hotels, run `{{tool:whoami}}` before asking follow-up questions, so the sign-in can happen while they answer.\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 CI or a sandbox 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",
|
|
15611
15616
|
"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`), and then the penalty under its terms (`cancel.penalty`) and the refund, what was paid less the penalty (`cancel.refund`), both in the charge currency; 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.amount` as shown. 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`.{{#if cli}} Without `--max-penalty`, `{{tool:orders cancel}}` cancels nothing: it prints the penalty and the refund 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"
|
|
@@ -15877,7 +15882,7 @@ var hotelSummary = openObject({
|
|
|
15877
15882
|
distanceMeters: external_exports.number().nullable(),
|
|
15878
15883
|
price: indicativePrice.nullable(),
|
|
15879
15884
|
/** The cover photo; `null` without one. */
|
|
15880
|
-
photo: photo.nullable()
|
|
15885
|
+
photo: photo.nullable().describe("The cover photo; null when there is none.")
|
|
15881
15886
|
});
|
|
15882
15887
|
var localities = openObject({
|
|
15883
15888
|
items: external_exports.array(
|
|
@@ -15952,7 +15957,7 @@ var searchResult = openObject({
|
|
|
15952
15957
|
nameAsText: count.nullable()
|
|
15953
15958
|
}),
|
|
15954
15959
|
data: external_exports.array(hotelSummary),
|
|
15955
|
-
nextCursor: external_exports.string().nullable(),
|
|
15960
|
+
nextCursor: external_exports.string().nullable().describe("Pass it back as cursor for the next page; null on the last page."),
|
|
15956
15961
|
notes: external_exports.array(
|
|
15957
15962
|
openObject({ code: openEnum(SEARCH_NOTE_CODES), message: external_exports.string() })
|
|
15958
15963
|
)
|
|
@@ -15998,7 +16003,7 @@ var hotel = openObject({
|
|
|
15998
16003
|
description: knownLocaleText.nullable(),
|
|
15999
16004
|
/** Up to 8 hotel photos, the cover first; `null` when the catalogue lists
|
|
16000
16005
|
* none (unknown is not no). */
|
|
16001
|
-
photos: external_exports.array(photo).nullable(),
|
|
16006
|
+
photos: external_exports.array(photo).nullable().describe("Up to 8 hotel photos, the cover first; null when the catalogue lists none."),
|
|
16002
16007
|
checkInTimes: timeRange,
|
|
16003
16008
|
checkOutTimes: timeRange,
|
|
16004
16009
|
policies: openObject({
|
|
@@ -16213,7 +16218,9 @@ var order = openObject({
|
|
|
16213
16218
|
price: openObject({ total: money }),
|
|
16214
16219
|
payment: openObject({
|
|
16215
16220
|
status: openEnum(PAYMENT_STATUSES),
|
|
16216
|
-
url: external_exports.string().nullable()
|
|
16221
|
+
url: external_exports.string().nullable().describe(
|
|
16222
|
+
"The payment page, on fortrip.ai. With requiresSignIn false it continues to Stripe Checkout, and 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 when the order isn't awaiting payment, or, while it is, when the link couldn't be read this time: read the order again."
|
|
16223
|
+
),
|
|
16217
16224
|
requiresSignIn: external_exports.boolean(),
|
|
16218
16225
|
expiresAt: instant.nullable(),
|
|
16219
16226
|
chargeCurrency: external_exports.string(),
|
|
@@ -16222,31 +16229,44 @@ var order = openObject({
|
|
|
16222
16229
|
/** The ways to pay other than `url`, while the order can be paid that
|
|
16223
16230
|
* way: a `com.stripe.payments` handler takes a shared payment token
|
|
16224
16231
|
* through `pay_order`. Empty when there is none. */
|
|
16225
|
-
handlers: external_exports.array(paymentHandler)
|
|
16232
|
+
handlers: external_exports.array(paymentHandler).describe(
|
|
16233
|
+
"The ways to pay other than url: a com.stripe.payments handler takes a Stripe shared payment token through pay_order. [] when a token can't pay the order: over $500, not charged in USD, an order started on the Fortrip website, a negotiated price, under 15 minutes left, 5 tokens tried, a token payment is under way, or token payment isn't offered for this order."
|
|
16234
|
+
),
|
|
16226
16235
|
/** What a payment credential for `pay_order` must allow, with
|
|
16227
|
-
* `handlers`: `maxAmount
|
|
16228
|
-
* lowercase as Stripe takes it, and
|
|
16229
|
-
* can't be paid. `null` when
|
|
16236
|
+
* `handlers`: at least `maxAmount`, in minor units (cents) of
|
|
16237
|
+
* `currency`, lowercase as Stripe takes it, and valid until at least
|
|
16238
|
+
* `expiresAt`, past which the order can't be paid. `null` when
|
|
16239
|
+
* `handlers` is empty. */
|
|
16230
16240
|
credentialLimits: openObject({
|
|
16231
|
-
maxAmount: external_exports.number().int(),
|
|
16232
|
-
currency: external_exports.string(),
|
|
16233
|
-
expiresAt: instant
|
|
16234
|
-
|
|
16241
|
+
maxAmount: external_exports.number().int().describe("Request the token for at least this amount, in cents; a token that allows less can't pay."),
|
|
16242
|
+
currency: external_exports.string().describe("The token's currency, lowercase as Stripe takes it: usd."),
|
|
16243
|
+
expiresAt: instant.describe(
|
|
16244
|
+
"Request the token valid until at least this time; the order can't be paid after it."
|
|
16245
|
+
)
|
|
16246
|
+
}).nullable().describe(
|
|
16247
|
+
"What the shared payment token for pay_order must allow. null exactly when handlers is []."
|
|
16248
|
+
)
|
|
16235
16249
|
}),
|
|
16236
16250
|
/** Whether the user can cancel the order now and, when they can, its
|
|
16237
16251
|
* penalty under the accepted terms (read a minute ahead) and the refund,
|
|
16238
16252
|
* what was paid less the penalty, both in the charge currency. */
|
|
16239
16253
|
cancel: openObject({
|
|
16240
|
-
available: external_exports.boolean(),
|
|
16241
|
-
reason: openEnum(CANCEL_REASONS)
|
|
16242
|
-
|
|
16243
|
-
|
|
16244
|
-
|
|
16254
|
+
available: external_exports.boolean().describe("Whether the user can cancel the order now."),
|
|
16255
|
+
reason: openEnum(CANCEL_REASONS).describe(
|
|
16256
|
+
"cancellable when it can be cancelled now; otherwise why not."
|
|
16257
|
+
),
|
|
16258
|
+
penalty: money.nullable().describe(
|
|
16259
|
+
"The penalty if cancelled now, under the accepted terms, in the charge currency; null when not stated."
|
|
16260
|
+
),
|
|
16261
|
+
refund: money.nullable().describe(
|
|
16262
|
+
"What a cancellation now refunds: what was paid less the penalty, in the charge currency; null when not stated."
|
|
16263
|
+
)
|
|
16264
|
+
}).describe("Whether the order can be cancelled now, and for what penalty and refund."),
|
|
16245
16265
|
manageUrl: external_exports.string()
|
|
16246
16266
|
});
|
|
16247
16267
|
var orderList = openObject({
|
|
16248
16268
|
data: external_exports.array(order),
|
|
16249
|
-
nextCursor: external_exports.string().nullable()
|
|
16269
|
+
nextCursor: external_exports.string().nullable().describe("Pass it back as cursor for the next page; null on the last page.")
|
|
16250
16270
|
});
|
|
16251
16271
|
function change(field, value) {
|
|
16252
16272
|
return openObject({
|
|
@@ -16266,8 +16286,32 @@ var offerChange = openUnion("field", [
|
|
|
16266
16286
|
|
|
16267
16287
|
// ../contract/src/tools.ts
|
|
16268
16288
|
var ORDER_NEXT_STEP = "Before you give the user an order's payment.url, show them its total and currency, the stay (hotel, room, dates, rooms and guests per room) and every term (meals, cancellation, fees payable at the property), then end your reply by asking them to confirm, and wait for a clear yes. Only after they say yes, give them payment.url exactly as returned.";
|
|
16269
|
-
var
|
|
16270
|
-
|
|
16289
|
+
var CALLS = {
|
|
16290
|
+
mcp: {
|
|
16291
|
+
cancel: "call cancel_order",
|
|
16292
|
+
penalty: 'Pass maximumPenalty as the number in cancel.penalty.amount ("120.00" \u2192 120).',
|
|
16293
|
+
pay: "call pay_order",
|
|
16294
|
+
payWith: "call pay_order with it and the order's price.total",
|
|
16295
|
+
paid: "pay_order"
|
|
16296
|
+
},
|
|
16297
|
+
cli: {
|
|
16298
|
+
cancel: "run `fortrip orders cancel <orderId> --max-penalty <n>`",
|
|
16299
|
+
penalty: "Pass the penalty's amount as --max-penalty (120.00 for a penalty of USD 120.00).",
|
|
16300
|
+
pay: "run `fortrip orders pay`",
|
|
16301
|
+
payWith: "run `fortrip orders pay <orderId> --token <spt_\u2026> --total <total>` with the token and the order's total",
|
|
16302
|
+
paid: "`fortrip orders pay`"
|
|
16303
|
+
}
|
|
16304
|
+
};
|
|
16305
|
+
function cancelNextStep(surface) {
|
|
16306
|
+
const c = CALLS[surface];
|
|
16307
|
+
return `Before you ${c.cancel}, show the user the order's stay (hotel, dates), cancel.penalty and cancel.refund (amount and currency), then end your reply by asking them to confirm the cancellation, and wait for a clear yes. ${c.penalty} Never state a refund the order did not return.`;
|
|
16308
|
+
}
|
|
16309
|
+
var CANCEL_NEXT_STEP = cancelNextStep("mcp");
|
|
16310
|
+
function payNextStep(surface) {
|
|
16311
|
+
const c = CALLS[surface];
|
|
16312
|
+
return `To pay without the link: only if you have a tool that can request a Stripe shared payment token from the user's Link wallet (US and Canadian Link accounts), and the order's payment.handlers isn't empty. Otherwise give payment.url, and never ask the user to create, type or paste a token. Before you ${c.pay}, show the user the order's total and currency, the stay (hotel, room, dates, rooms and guests per room) and every term (meals, cancellation, fees payable at the property), then end your reply by asking them to confirm, and wait for a clear yes. Then request the token for this order from the user's Link wallet with the handler's config.business_profile and payment.credentialLimits (maxAmount in cents, currency, expiresAt), and ${c.payWith}. The charge is in USD: a card in another currency may add a foreign transaction fee. Pay one way only: either give payment.url or ${c.pay}. Once ${c.paid} succeeds, payment.url stops working; a failed payment leaves it open.`;
|
|
16313
|
+
}
|
|
16314
|
+
var PAY_NEXT_STEP = payNextStep("mcp");
|
|
16271
16315
|
var nextStep = external_exports.string().optional().describe(
|
|
16272
16316
|
"What to show and ask before giving a payment.url. Present when the answer holds a non-null payment.url, and only then."
|
|
16273
16317
|
);
|
|
@@ -16321,7 +16365,7 @@ var TOOLS = [
|
|
|
16321
16365
|
{
|
|
16322
16366
|
name: "book_hotel",
|
|
16323
16367
|
title: "Create hotel order and payment link",
|
|
16324
|
-
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 where the user pays. Nothing is charged until the
|
|
16368
|
+
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 where the user pays. 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.`,
|
|
16325
16369
|
annotations: {
|
|
16326
16370
|
readOnlyHint: false,
|
|
16327
16371
|
idempotentHint: false,
|
|
@@ -16363,7 +16407,7 @@ var TOOLS = [
|
|
|
16363
16407
|
{
|
|
16364
16408
|
name: "pay_order",
|
|
16365
16409
|
title: "Pay order with a shared payment token",
|
|
16366
|
-
description: "Pay an order
|
|
16410
|
+
description: "Pay an order with a Stripe shared payment token, not its link, when payment.handlers isn't empty. Only if you have a tool to request the token from the user's Link wallet (US and Canadian Link accounts); otherwise give payment.url, and never ask the user to create, type or paste a token. First show the user the USD total, the stay and every term (meals, cancellation, fees payable at the property), ask them to confirm, and wait for a clear yes. Then request the token with the handler's config.business_profile and payment.credentialLimits, and pass it with price.total. Pay one way only: payment.url or pay_order. Once this succeeds, payment.url stops working; a failure leaves it open. Then poll get_order. payment_total_changed: confirm details.total with the user, then retry with it. payment_declined: another wallet method or the link. payment_action_required: give the user payment.url. payment_credential_invalid: a new token. service_unavailable: retry with the same token. A token pays one order only.",
|
|
16367
16411
|
annotations: {
|
|
16368
16412
|
readOnlyHint: false,
|
|
16369
16413
|
idempotentHint: true,
|
|
@@ -16706,9 +16750,10 @@ var OMITTED = {
|
|
|
16706
16750
|
dominated: "beaten by or the same as another offer for the same room",
|
|
16707
16751
|
unreadable: "unreadable"
|
|
16708
16752
|
};
|
|
16709
|
-
function limitText(o) {
|
|
16753
|
+
function limitText(o, surface) {
|
|
16710
16754
|
const n = o.byLimit;
|
|
16711
|
-
|
|
16755
|
+
const [limit, filters] = surface === "cli" ? ["--limit-per-hotel", "--require-breakfast / --require-free-cancellation"] : ["limitPerHotel", "requireBreakfast / requireFreeCancellation"];
|
|
16756
|
+
return typeof n === "number" && n > 0 ? `${plural(n, "more offer")} not shown (${limit}); a filtered request (${filters}) or a higher ${limit} may show them \u2014 don't conclude they don't exist` : "";
|
|
16712
16757
|
}
|
|
16713
16758
|
function omittedText(o) {
|
|
16714
16759
|
return Object.entries(OMITTED).filter(([key]) => typeof o[key] === "number" && o[key] > 0).map(([key, words]) => `${o[key]} ${words}`).join(", ");
|
|
@@ -16722,7 +16767,7 @@ var UNAVAILABLE = {
|
|
|
16722
16767
|
supplier_unavailable: "offers could not be fetched this time",
|
|
16723
16768
|
stay_in_past: "check-in is already past"
|
|
16724
16769
|
};
|
|
16725
|
-
function renderOffers(r) {
|
|
16770
|
+
function renderOffers(r, surface = "mcp") {
|
|
16726
16771
|
const lines = [
|
|
16727
16772
|
`Live offers \xB7 ${stayLine(r.stay.checkIn, r.stay.checkOut)} \xB7 ${party(r.stay.rooms)}`,
|
|
16728
16773
|
"total = the whole stay and every room, the amount charged. Fees not in the total are in the property's currency, not converted. Times are UTC, then the hotel's time zone."
|
|
@@ -16733,13 +16778,13 @@ function renderOffers(r) {
|
|
|
16733
16778
|
h.offers.forEach((o, i) => lines.push(`${i + 1}. ${offerLine(o)}`));
|
|
16734
16779
|
const omitted2 = omittedText(h.omitted);
|
|
16735
16780
|
if (omitted2) lines.push(`Not shown: ${omitted2}.`);
|
|
16736
|
-
const limited = limitText(h.omitted);
|
|
16781
|
+
const limited = limitText(h.omitted, surface);
|
|
16737
16782
|
if (limited) lines.push(`${limited}.`);
|
|
16738
16783
|
}
|
|
16739
16784
|
if (r.unavailable.length > 0) {
|
|
16740
16785
|
lines.push("", "Unavailable:");
|
|
16741
16786
|
for (const u of r.unavailable) {
|
|
16742
|
-
const omitted2 = u.omitted ? [omittedText(u.omitted), limitText(u.omitted)].filter(Boolean).join("; ") : "";
|
|
16787
|
+
const omitted2 = u.omitted ? [omittedText(u.omitted), limitText(u.omitted, surface)].filter(Boolean).join("; ") : "";
|
|
16743
16788
|
lines.push(`- ${u.hotelId}: ${label(UNAVAILABLE, u.reason)}${omitted2 ? ` (${omitted2})` : ""}`);
|
|
16744
16789
|
}
|
|
16745
16790
|
}
|
|
@@ -16795,7 +16840,7 @@ function itemLines(item) {
|
|
|
16795
16840
|
`Hotel confirmation number: ${h.confirmationNumber ?? "none yet"}`
|
|
16796
16841
|
];
|
|
16797
16842
|
}
|
|
16798
|
-
function paymentLines(o) {
|
|
16843
|
+
function paymentLines(o, surface) {
|
|
16799
16844
|
const p = o.payment;
|
|
16800
16845
|
const lines = [
|
|
16801
16846
|
[
|
|
@@ -16814,43 +16859,54 @@ function paymentLines(o) {
|
|
|
16814
16859
|
} else if (o.status === "awaiting_payment") {
|
|
16815
16860
|
lines.push("Payment link: could not be read this time; read this order again for it.");
|
|
16816
16861
|
}
|
|
16817
|
-
if (p.handlers.length > 0) lines.push(handlersLine(
|
|
16818
|
-
lines.push(cancelLine(o
|
|
16862
|
+
if (p.handlers.length > 0) lines.push(handlersLine(o, surface));
|
|
16863
|
+
lines.push(cancelLine(o));
|
|
16819
16864
|
lines.push(`Manage: ${o.manageUrl}`);
|
|
16820
16865
|
return lines;
|
|
16821
16866
|
}
|
|
16822
|
-
function handlersLine(
|
|
16867
|
+
function handlersLine(o, surface) {
|
|
16868
|
+
const { handlers, credentialLimits: limits } = o.payment;
|
|
16869
|
+
const pay = surface === "cli" ? `\`fortrip orders pay ${o.orderId} --token <spt_\u2026> --total ${o.price.total.amount}\`` : "pay_order";
|
|
16823
16870
|
const shown = handlers.map(
|
|
16824
16871
|
(h) => `${h.type} (handler ${h.id}, business_profile ${h.config.business_profile})`
|
|
16825
16872
|
);
|
|
16826
16873
|
const limit = limits ? `; token limits: maxAmount ${limits.maxAmount} (cents), currency ${limits.currency}, expiresAt ${limits.expiresAt}` : "";
|
|
16827
|
-
return
|
|
16874
|
+
return [
|
|
16875
|
+
`Pay without the link: ${pay} with a shared payment token via ${shown.join(", ")}${limit}.`,
|
|
16876
|
+
"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.",
|
|
16877
|
+
`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"}.`
|
|
16878
|
+
].join(" ");
|
|
16828
16879
|
}
|
|
16829
|
-
function cancelLine(
|
|
16880
|
+
function cancelLine(o) {
|
|
16881
|
+
const c = o.cancel;
|
|
16882
|
+
if (o.status === "awaiting_payment" && !c.available && c.reason === "not_confirmed") {
|
|
16883
|
+
const at = o.payment.expiresAt === null ? "" : ` at ${when(o.payment.expiresAt, null)}`;
|
|
16884
|
+
return `Cancel: not needed: an unpaid order expires unpaid${at}`;
|
|
16885
|
+
}
|
|
16830
16886
|
const figure = (name, m) => `${name} ${m ? money2(m) : "not stated"}`;
|
|
16831
16887
|
const figures = `${figure("penalty", c.penalty)}, ${figure("refund", c.refund)}`;
|
|
16832
16888
|
if (c.available) return `Cancel: can cancel now: ${figures}`;
|
|
16833
16889
|
const why = `Cancel: not available: ${label(CANCEL_REASON_WORDS, c.reason)}`;
|
|
16834
16890
|
return c.penalty || c.refund ? `${why} \xB7 ${figures}` : why;
|
|
16835
16891
|
}
|
|
16836
|
-
function orderLines(o) {
|
|
16892
|
+
function orderLines(o, surface = "mcp") {
|
|
16837
16893
|
return [
|
|
16838
16894
|
`Order ${o.orderId} \xB7 reference ${o.reference} \xB7 ${label(ORDER_STATUS_WORDS, o.status)} \xB7 created ${when(o.createdAt, null)} \xB7 updated ${when(o.updatedAt, null)}`,
|
|
16839
16895
|
...o.items.flatMap(itemLines),
|
|
16840
|
-
...paymentLines(o)
|
|
16896
|
+
...paymentLines(o, surface)
|
|
16841
16897
|
];
|
|
16842
16898
|
}
|
|
16843
|
-
function renderOrder(o) {
|
|
16844
|
-
return orderLines(o).join("\n");
|
|
16899
|
+
function renderOrder(o, surface = "mcp") {
|
|
16900
|
+
return orderLines(o, surface).join("\n");
|
|
16845
16901
|
}
|
|
16846
|
-
function renderOrderList(list) {
|
|
16902
|
+
function renderOrderList(list, surface = "mcp") {
|
|
16847
16903
|
const lines = [
|
|
16848
16904
|
list.data.length === 0 ? "No orders on this page." : `Orders, newest first: ${list.data.length} on this page.`
|
|
16849
16905
|
];
|
|
16850
|
-
for (const o of list.data) lines.push("", ...orderLines(o));
|
|
16906
|
+
for (const o of list.data) lines.push("", ...orderLines(o, surface));
|
|
16851
16907
|
lines.push(
|
|
16852
16908
|
"",
|
|
16853
|
-
list.nextCursor === null ? "Last page." : `Next page: call again with { cursor: "${list.nextCursor}" }.`
|
|
16909
|
+
list.nextCursor === null ? "Last page." : surface === "cli" ? `Next page: run again with --cursor ${list.nextCursor}.` : `Next page: call again with { cursor: "${list.nextCursor}" }.`
|
|
16854
16910
|
);
|
|
16855
16911
|
return lines.join("\n");
|
|
16856
16912
|
}
|
|
@@ -16941,9 +16997,10 @@ function countsLine(r) {
|
|
|
16941
16997
|
if (c.nameAsText !== null) parts.push(`${num(c.nameAsText)} have the name as text`);
|
|
16942
16998
|
return `Counts: ${parts.join(", ")}.`;
|
|
16943
16999
|
}
|
|
16944
|
-
function localitiesLines(loc, areaName) {
|
|
17000
|
+
function localitiesLines(loc, areaName, surface = "mcp") {
|
|
17001
|
+
const back = surface === "cli" ? "--locality <placeId>" : 'destination { kind: "locality", placeId }';
|
|
16945
17002
|
const lines = [
|
|
16946
|
-
|
|
17003
|
+
`Localities: pass one back as ${back}, never the name. The number is its matching hotels; "incl." lists places inside it, with all their hotels regardless of filters ("hotels overall").`
|
|
16947
17004
|
];
|
|
16948
17005
|
for (const item of loc.items) {
|
|
16949
17006
|
let line = `- ${item.place.name} ${item.place.placeId} ${num(item.count)}`;
|
|
@@ -16964,7 +17021,9 @@ function localitiesLines(loc, areaName) {
|
|
|
16964
17021
|
lines.push(`${plural(loc.unassigned, "hotel")} in this search belong to no locality.`);
|
|
16965
17022
|
}
|
|
16966
17023
|
if (loc.more > 0) {
|
|
16967
|
-
lines.push(
|
|
17024
|
+
lines.push(
|
|
17025
|
+
`${num(loc.more)} more localities; name one with ${surface === "cli" ? "--place-name and --country" : "place_name"}.`
|
|
17026
|
+
);
|
|
16968
17027
|
}
|
|
16969
17028
|
return lines;
|
|
16970
17029
|
}
|
|
@@ -16995,7 +17054,7 @@ function hotelLine(h, i, r) {
|
|
|
16995
17054
|
h.hotelId
|
|
16996
17055
|
].filter(Boolean).join(" \xB7 ");
|
|
16997
17056
|
}
|
|
16998
|
-
function renderSearch(r) {
|
|
17057
|
+
function renderSearch(r, surface = "mcp") {
|
|
16999
17058
|
const lines = [header(r)];
|
|
17000
17059
|
lines.push(
|
|
17001
17060
|
[
|
|
@@ -17019,7 +17078,7 @@ function renderSearch(r) {
|
|
|
17019
17078
|
}
|
|
17020
17079
|
if (r.coverage.localities) {
|
|
17021
17080
|
const areaName = r.destination?.kind === "place" ? r.destination.place.name : null;
|
|
17022
|
-
lines.push("", ...localitiesLines(r.coverage.localities, areaName));
|
|
17081
|
+
lines.push("", ...localitiesLines(r.coverage.localities, areaName, surface));
|
|
17023
17082
|
}
|
|
17024
17083
|
lines.push("");
|
|
17025
17084
|
if (r.data.length === 0) lines.push("No hotels on this page.");
|
|
@@ -17029,7 +17088,7 @@ function renderSearch(r) {
|
|
|
17029
17088
|
}
|
|
17030
17089
|
lines.push(
|
|
17031
17090
|
"",
|
|
17032
|
-
r.nextCursor === null ? "Last page." : `Next page: call again with only the cursor and, optionally, limit: { cursor: "${r.nextCursor}" }.`
|
|
17091
|
+
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}" }.`
|
|
17033
17092
|
);
|
|
17034
17093
|
return lines.join("\n");
|
|
17035
17094
|
}
|
|
@@ -17063,23 +17122,24 @@ function changeLine(c) {
|
|
|
17063
17122
|
return `- ${c.field}: ${raw(c.previous)} \u2192 ${raw(c.current)}${worse}`;
|
|
17064
17123
|
}
|
|
17065
17124
|
}
|
|
17066
|
-
function tooBroad(d) {
|
|
17125
|
+
function tooBroad(d, surface) {
|
|
17126
|
+
const locality = surface === "cli" ? "--locality <id>" : 'destination { kind: "locality", placeId: "<id>" }';
|
|
17067
17127
|
const lines = [
|
|
17068
|
-
|
|
17069
|
-
...localitiesLines(d.localities, null)
|
|
17128
|
+
`Next: show the user these localities and ask which they prefer, unless their request already names one of them; then search again with ${locality} and the same text, filters, stay and sort.`,
|
|
17129
|
+
...localitiesLines(d.localities, null, surface)
|
|
17070
17130
|
];
|
|
17071
17131
|
const top = d.localities.items[0];
|
|
17072
17132
|
if (top && top.total > d.poolLimit && d.center?.place?.placeId === top.place.placeId) {
|
|
17073
17133
|
lines.push(
|
|
17074
|
-
`Or: ${top.place.name}, the area's center, alone has ${num(top.total)} matching hotels: the same destination with radiusMeters (up to ${LIMITS.radiusMetersMax}) prices nearly the same hotels (the nearest ${num(d.poolLimit)} around ${top.place.name}).`
|
|
17134
|
+
`Or: ${top.place.name}, the area's center, alone has ${num(top.total)} matching hotels: the same destination with ${surface === "cli" ? "--radius-meters" : "radiusMeters"} (up to ${LIMITS.radiusMetersMax}) prices nearly the same hotels (the nearest ${num(d.poolLimit)} around ${top.place.name}).`
|
|
17075
17135
|
);
|
|
17076
17136
|
}
|
|
17077
17137
|
return lines;
|
|
17078
17138
|
}
|
|
17079
|
-
function ambiguous(d) {
|
|
17139
|
+
function ambiguous(d, surface) {
|
|
17080
17140
|
const shown = d.candidatesTotal > d.candidates.length ? `${d.candidates.length} of ${d.candidatesTotal} shown` : `${d.candidatesTotal}`;
|
|
17081
17141
|
const lines = [
|
|
17082
|
-
`Places named "${d.name}" in ${d.countryCode} (${shown}). Ask the user which one, then search with destination { kind: "place", placeId: "<id>" }:`
|
|
17142
|
+
`Places named "${d.name}" in ${d.countryCode} (${shown}). Ask the user which one, then search with ${surface === "cli" ? "--place <id>" : 'destination { kind: "place", placeId: "<id>" }'}:`
|
|
17083
17143
|
];
|
|
17084
17144
|
for (const c of d.candidates) {
|
|
17085
17145
|
const other = [c.names.en, c.names.zh].find((n) => n && n !== c.name);
|
|
@@ -17099,7 +17159,7 @@ function ambiguous(d) {
|
|
|
17099
17159
|
}
|
|
17100
17160
|
return lines;
|
|
17101
17161
|
}
|
|
17102
|
-
function notFound(d) {
|
|
17162
|
+
function notFound(d, surface) {
|
|
17103
17163
|
switch (d.reason) {
|
|
17104
17164
|
case "no_match": {
|
|
17105
17165
|
const m = d;
|
|
@@ -17110,22 +17170,23 @@ function notFound(d) {
|
|
|
17110
17170
|
return [`Unknown placeId ${d.placeId}.`];
|
|
17111
17171
|
case "not_a_locality": {
|
|
17112
17172
|
const n = d;
|
|
17113
|
-
const town = `{ kind: "place", placeId: "${n.placeId}" }`;
|
|
17173
|
+
const town = surface === "cli" ? `--place ${n.placeId}` : `{ kind: "place", placeId: "${n.placeId}" }`;
|
|
17114
17174
|
if (n.hub === null) {
|
|
17115
17175
|
return [`${n.placeId} belongs to no locality: search ${town} for an 8 km circle around it.`];
|
|
17116
17176
|
}
|
|
17117
17177
|
const total = n.hubTotal === null ? "" : ` (${plural(n.hubTotal, "matching hotel")})`;
|
|
17118
17178
|
return [
|
|
17119
17179
|
`${n.placeId} is not a locality. Its hotels belong to the locality ${n.hub.name} ${n.hub.placeId}${total}.`,
|
|
17120
|
-
`Search { kind: "locality", placeId: "${n.hub.placeId}" } for those, or ${town} for an 8 km circle around the town itself.`
|
|
17180
|
+
`Search ${surface === "cli" ? `--locality ${n.hub.placeId}` : `{ kind: "locality", placeId: "${n.hub.placeId}" }`} for those, or ${town} for an 8 km circle around the town itself.`
|
|
17121
17181
|
];
|
|
17122
17182
|
}
|
|
17123
17183
|
default:
|
|
17124
17184
|
return [`Details: ${raw(d)}`];
|
|
17125
17185
|
}
|
|
17126
17186
|
}
|
|
17127
|
-
function detailLines(e) {
|
|
17187
|
+
function detailLines(e, surface) {
|
|
17128
17188
|
if (!("details" in e)) return [];
|
|
17189
|
+
const getOrder = (id) => surface === "cli" ? `\`fortrip orders get ${id}\`` : "get_order";
|
|
17129
17190
|
switch (e.code) {
|
|
17130
17191
|
case "invalid_request": {
|
|
17131
17192
|
const d = e.details;
|
|
@@ -17162,13 +17223,13 @@ function detailLines(e) {
|
|
|
17162
17223
|
return [`Not cancellable: ${label(CANCEL_REASON_WORDS, e.details.reason)}.`];
|
|
17163
17224
|
case "order_not_payable":
|
|
17164
17225
|
return [
|
|
17165
|
-
`Order ${e.details.orderId}, ${label(ORDER_STATUS_WORDS, e.details.status)}: read it with
|
|
17226
|
+
`Order ${e.details.orderId}, ${label(ORDER_STATUS_WORDS, e.details.status)}: read it with ${getOrder(e.details.orderId)}; this call charged nothing.`
|
|
17166
17227
|
];
|
|
17167
17228
|
case "payment_in_progress":
|
|
17168
|
-
return [`Order ${e.details.orderId}: read it with
|
|
17229
|
+
return [`Order ${e.details.orderId}: read it with ${getOrder(e.details.orderId)} in a few seconds.`];
|
|
17169
17230
|
case "payment_total_changed":
|
|
17170
17231
|
return [
|
|
17171
|
-
`Order ${e.details.orderId}
|
|
17232
|
+
`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} --token <spt_\u2026> --total ${e.details.total.amount}\` again with the same token` : "call pay_order again with it and the same token"}. Nothing was charged.`
|
|
17172
17233
|
];
|
|
17173
17234
|
case "payment_credential_invalid":
|
|
17174
17235
|
return [
|
|
@@ -17176,16 +17237,18 @@ function detailLines(e) {
|
|
|
17176
17237
|
];
|
|
17177
17238
|
case "payment_declined":
|
|
17178
17239
|
return [
|
|
17179
|
-
`Declined${e.details.declineCode ? ` (${e.details.declineCode})` : ""}: the user picks another payment method in their wallet for a new token, or pays by link
|
|
17240
|
+
`Declined${e.details.declineCode ? ` (${e.details.declineCode})` : ""}: the user picks another payment method in their wallet for a new token, or pays by link: read the order with ${getOrder("<orderId>")} and give its payment.url.`
|
|
17180
17241
|
];
|
|
17181
17242
|
case "destination_ambiguous":
|
|
17182
|
-
return ambiguous(e.details);
|
|
17243
|
+
return ambiguous(e.details, surface);
|
|
17183
17244
|
case "destination_not_found":
|
|
17184
|
-
return notFound(e.details);
|
|
17245
|
+
return notFound(e.details, surface);
|
|
17185
17246
|
case "search_too_broad":
|
|
17186
|
-
return tooBroad(e.details);
|
|
17247
|
+
return tooBroad(e.details, surface);
|
|
17187
17248
|
case "stay_unsupported":
|
|
17188
|
-
return e.details.reason === "mixed_occupancy" ? ["Every room must have the same party: ask once per party."] : e.details.reason === "max_nights" ? [
|
|
17249
|
+
return e.details.reason === "mixed_occupancy" ? ["Every room must have the same party: ask once per party."] : e.details.reason === "max_nights" ? [
|
|
17250
|
+
`At most ${plural(e.details.max, "night")} per stay: ask the user whether to split it into consecutive stays, each its own order.`
|
|
17251
|
+
] : [`Details: ${raw(e.details)}`];
|
|
17189
17252
|
case "stay_in_past":
|
|
17190
17253
|
return [`Check-in ${e.details.checkIn} is already past${e.details.timeZone ? ` in ${e.details.timeZone}` : ""}.`];
|
|
17191
17254
|
case "offer_unavailable":
|
|
@@ -17214,7 +17277,7 @@ function retryLine(retryable, after) {
|
|
|
17214
17277
|
}
|
|
17215
17278
|
return retryable === false ? "Not retryable." : "Retryable: unknown.";
|
|
17216
17279
|
}
|
|
17217
|
-
function renderError(envelope, status) {
|
|
17280
|
+
function renderError(envelope, status, surface = "mcp") {
|
|
17218
17281
|
const http = status === void 0 ? "" : ` (HTTP ${status})`;
|
|
17219
17282
|
let known = null;
|
|
17220
17283
|
let body = null;
|
|
@@ -17235,7 +17298,7 @@ Retryable: unknown.`;
|
|
|
17235
17298
|
retryLine(body.retryable, body.retryAfterSeconds)
|
|
17236
17299
|
];
|
|
17237
17300
|
if (typeof body.param === "string") lines.push(`Field: ${body.param}`);
|
|
17238
|
-
if (known) lines.push(...detailLines(known));
|
|
17301
|
+
if (known) lines.push(...detailLines(known, surface));
|
|
17239
17302
|
else if (body.details !== void 0) lines.push(`Details: ${raw(body.details)}`);
|
|
17240
17303
|
if (typeof body.requestId === "string") lines.push(`Request id: ${body.requestId}`);
|
|
17241
17304
|
return lines.join("\n");
|
|
@@ -17310,41 +17373,43 @@ function renderHotel(h) {
|
|
|
17310
17373
|
}
|
|
17311
17374
|
|
|
17312
17375
|
// ../contract/src/render/index.ts
|
|
17313
|
-
function renderToolResult(tool, data) {
|
|
17376
|
+
function renderToolResult(tool, data, surface = "mcp") {
|
|
17314
17377
|
const schema = TOOLS.find((t) => t.name === tool)?.output;
|
|
17315
17378
|
let parsed;
|
|
17316
17379
|
try {
|
|
17317
17380
|
if (!schema) throw new Error(`no output schema for ${tool}`);
|
|
17318
17381
|
parsed = parseOpen(schema, data);
|
|
17319
17382
|
} catch {
|
|
17320
|
-
const
|
|
17383
|
+
const spec = COMMANDS.find((command) => command.tool === tool);
|
|
17384
|
+
const name = surface === "cli" && spec ? commandInvocation(spec) : tool;
|
|
17385
|
+
const text2 = `This ${name} result is not in the expected shape; as JSON:
|
|
17321
17386
|
${raw(data)}`;
|
|
17322
17387
|
return [
|
|
17323
17388
|
text2,
|
|
17324
17389
|
ORDER_TOOLS.has(tool) && holdsPaymentUrl(data) ? ORDER_NEXT_STEP : "",
|
|
17325
|
-
ORDER_TOOLS.has(tool) && holdsHandlers(data) ?
|
|
17326
|
-
CANCEL_TOOLS.has(tool) && holdsCancellable(data) ?
|
|
17390
|
+
ORDER_TOOLS.has(tool) && holdsHandlers(data) ? payNextStep(surface) : "",
|
|
17391
|
+
CANCEL_TOOLS.has(tool) && holdsCancellable(data) ? cancelNextStep(surface) : ""
|
|
17327
17392
|
].filter(Boolean).join("\n\n");
|
|
17328
17393
|
}
|
|
17329
17394
|
switch (tool) {
|
|
17330
17395
|
case "search_hotels":
|
|
17331
|
-
return renderSearch(parsed);
|
|
17396
|
+
return renderSearch(parsed, surface);
|
|
17332
17397
|
case "get_hotel":
|
|
17333
17398
|
return renderHotel(parsed);
|
|
17334
17399
|
case "get_hotel_offers":
|
|
17335
|
-
return renderOffers(parsed);
|
|
17400
|
+
return renderOffers(parsed, surface);
|
|
17336
17401
|
case "book_hotel":
|
|
17337
17402
|
case "get_order": {
|
|
17338
17403
|
const order2 = parsed;
|
|
17339
|
-
return withConsent(tool, renderOrder(order2), [order2]);
|
|
17404
|
+
return withConsent(tool, surface, renderOrder(order2, surface), [order2]);
|
|
17340
17405
|
}
|
|
17341
17406
|
case "list_orders": {
|
|
17342
17407
|
const list = parsed;
|
|
17343
|
-
return withConsent(tool, renderOrderList(list), list.data);
|
|
17408
|
+
return withConsent(tool, surface, renderOrderList(list, surface), list.data);
|
|
17344
17409
|
}
|
|
17345
17410
|
case "cancel_order":
|
|
17346
17411
|
case "pay_order":
|
|
17347
|
-
return renderOrder(parsed);
|
|
17412
|
+
return renderOrder(parsed, surface);
|
|
17348
17413
|
}
|
|
17349
17414
|
}
|
|
17350
17415
|
var ORDER_TOOLS = /* @__PURE__ */ new Set(["book_hotel", "get_order", "list_orders"]);
|
|
@@ -17376,19 +17441,19 @@ function holdsCancellable(value, seen = /* @__PURE__ */ new Set()) {
|
|
|
17376
17441
|
}
|
|
17377
17442
|
return Object.values(value).some((v) => holdsCancellable(v, seen));
|
|
17378
17443
|
}
|
|
17379
|
-
function withConsent(tool, text2, orders) {
|
|
17444
|
+
function withConsent(tool, surface, text2, orders) {
|
|
17380
17445
|
return [
|
|
17381
17446
|
text2,
|
|
17382
17447
|
orders.some((o) => o.payment.url !== null) ? ORDER_NEXT_STEP : "",
|
|
17383
|
-
orders.some((o) => o.payment.handlers.length > 0) ?
|
|
17384
|
-
CANCEL_TOOLS.has(tool) && orders.some((o) => o.cancel.available) ?
|
|
17448
|
+
orders.some((o) => o.payment.handlers.length > 0) ? payNextStep(surface) : "",
|
|
17449
|
+
CANCEL_TOOLS.has(tool) && orders.some((o) => o.cancel.available) ? cancelNextStep(surface) : ""
|
|
17385
17450
|
].filter(Boolean).join("\n\n");
|
|
17386
17451
|
}
|
|
17387
17452
|
|
|
17388
17453
|
// ../contract/package.json
|
|
17389
17454
|
var package_default = {
|
|
17390
17455
|
name: "@fortrip/agent-contract",
|
|
17391
|
-
version: "4.
|
|
17456
|
+
version: "4.1.0",
|
|
17392
17457
|
license: "Apache-2.0",
|
|
17393
17458
|
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.",
|
|
17394
17459
|
type: "module",
|
|
@@ -17547,7 +17612,7 @@ function formatError2(failure, json2) {
|
|
|
17547
17612
|
if (fromApi) {
|
|
17548
17613
|
const status = failure.details.status;
|
|
17549
17614
|
const known = Object.hasOwn(ERROR_CODES, fromApi.code);
|
|
17550
|
-
lines.push(renderError(failure.envelope, known || typeof status !== "number" ? void 0 : status));
|
|
17615
|
+
lines.push(renderError(failure.envelope, known || typeof status !== "number" ? void 0 : status, "cli"));
|
|
17551
17616
|
if (failure.message !== fromApi.message) lines.push(failure.message);
|
|
17552
17617
|
lines.push(...fieldLines(Object.fromEntries(own.filter(([n]) => !inError(n) && n !== "status"))));
|
|
17553
17618
|
} else {
|
|
@@ -18351,7 +18416,7 @@ async function login({
|
|
|
18351
18416
|
throw new CliError("Login was denied in the browser.", EXIT.error);
|
|
18352
18417
|
case "invalid_client":
|
|
18353
18418
|
throw new CliError(
|
|
18354
|
-
`The sign-in server
|
|
18419
|
+
`The sign-in server at ${apiUrl} doesn't recognise this CLI (invalid_client). Check FORTRIP_API_URL, or email ${SUPPORT_EMAIL}.`,
|
|
18355
18420
|
EXIT.error
|
|
18356
18421
|
);
|
|
18357
18422
|
case "expired_token":
|
package/dist/cli.js
CHANGED
|
@@ -26,7 +26,7 @@ import {
|
|
|
26
26
|
unwrap,
|
|
27
27
|
usageError,
|
|
28
28
|
whoami
|
|
29
|
-
} from "./chunk-
|
|
29
|
+
} from "./chunk-CCFEWDCU.js";
|
|
30
30
|
|
|
31
31
|
// src/commands.ts
|
|
32
32
|
import { readFileSync } from "fs";
|
|
@@ -129,7 +129,8 @@ ${optionList(GLOBAL_FLAGS)}
|
|
|
129
129
|
Output is compact text on stdout; --json prints it as one line of JSON.
|
|
130
130
|
Errors go to stderr, as text or, with --json, as JSON.
|
|
131
131
|
Exit codes: 0 ok, 1 error (retry once when the error says it is retryable),
|
|
132
|
-
2 invalid arguments,
|
|
132
|
+
2 invalid arguments, or orders cancel without --max-penalty (nothing is
|
|
133
|
+
cancelled), 3 not signed in or sign-in not accepted, 4 rate limited.
|
|
133
134
|
|
|
134
135
|
Environment:
|
|
135
136
|
FORTRIP_TOKEN Use this token instead of the saved login (CI, sandboxes)
|
|
@@ -242,7 +243,8 @@ function cancelPreview(spec, argv) {
|
|
|
242
243
|
if (positionals2.length !== 1) throw usageError(`Usage: ${usageLine(spec)}`);
|
|
243
244
|
const input = { orderId: positionals2[0] };
|
|
244
245
|
check({ ...spec, tool: "get_order" }, input, true, /* @__PURE__ */ new Map());
|
|
245
|
-
|
|
246
|
+
const orderId = input.orderId;
|
|
247
|
+
return { method: "GET", path: API.order(orderId), flag: `--${flag.flag}`, orderId };
|
|
246
248
|
}
|
|
247
249
|
function check(spec, input, isGet, fromEnv) {
|
|
248
250
|
const schema = TOOLS.find((tool) => tool.name === spec.tool)?.input;
|
|
@@ -528,7 +530,7 @@ async function run(argv) {
|
|
|
528
530
|
case "mcp": {
|
|
529
531
|
parseOptions(spec, rest);
|
|
530
532
|
const mcpUrl = resolveMcpUrl(apiUrl);
|
|
531
|
-
const { runMcpBridge } = await import("./mcp-bridge-
|
|
533
|
+
const { runMcpBridge } = await import("./mcp-bridge-5F5O5LVT.js");
|
|
532
534
|
await runMcpBridge(mcpUrl, apiUrl);
|
|
533
535
|
return void 0;
|
|
534
536
|
}
|
|
@@ -537,21 +539,20 @@ async function run(argv) {
|
|
|
537
539
|
const preview = cancelPreview(spec, rest);
|
|
538
540
|
if (preview) {
|
|
539
541
|
const order2 = unwrap(await authorizedRequest(apiUrl, preview.path, { method: preview.method }));
|
|
540
|
-
throw usageError(notCancelled(spec, preview.flag, order2));
|
|
542
|
+
throw usageError(notCancelled(spec, preview.flag, preview.orderId, order2));
|
|
541
543
|
}
|
|
542
544
|
const { method, path, body } = parseCommand(spec, rest, process.env);
|
|
543
545
|
const data = unwrap(await authorizedRequest(apiUrl, path, { method, body }));
|
|
544
|
-
return { data, text: renderToolResult(spec.tool, data) };
|
|
546
|
+
return { data, text: renderToolResult(spec.tool, data, "cli") };
|
|
545
547
|
}
|
|
546
|
-
function notCancelled(spec, flag, order2) {
|
|
547
|
-
const
|
|
548
|
+
function notCancelled(spec, flag, orderId, order2) {
|
|
549
|
+
const lines = renderToolResult("get_order", order2, "cli").split("\n").filter((text) => text.startsWith("Hotel: ") || text.startsWith("Cancel: "));
|
|
548
550
|
const parsed = order.safeParse(order2);
|
|
549
551
|
const cancel = parsed.success ? parsed.data.cancel : void 0;
|
|
550
|
-
|
|
551
|
-
`
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
].join("\n");
|
|
552
|
+
const next = cancel?.available && cancel.penalty ? [
|
|
553
|
+
`Show the user the stay, this penalty and this refund, and ask them to confirm. Only after a clear yes, run \`${commandInvocation(spec)} ${orderId} ${flag} ${cancel.penalty.amount}\`.`
|
|
554
|
+
] : cancel ? [] : [`${commandInvocation(spec)} needs ${flag}, the penalty the user agreed to.`];
|
|
555
|
+
return ["Not cancelled: nothing was sent.", ...lines, ...next].join("\n");
|
|
555
556
|
}
|
|
556
557
|
function account(data) {
|
|
557
558
|
const { apiUrl, userId, email, name } = data;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "fortrip",
|
|
3
|
-
"version": "4.
|
|
3
|
+
"version": "4.1.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",
|
|
@@ -32,7 +32,7 @@
|
|
|
32
32
|
"tsx": "^4.20.0",
|
|
33
33
|
"typescript": "^5.9.0",
|
|
34
34
|
"zod": "4.4.3",
|
|
35
|
-
"@fortrip/agent-contract": "4.
|
|
35
|
+
"@fortrip/agent-contract": "4.1.0"
|
|
36
36
|
},
|
|
37
37
|
"scripts": {
|
|
38
38
|
"build": "tsup",
|