fortrip 3.2.0 → 3.3.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
|
@@ -141,6 +141,7 @@ other command that needs to save a sign-in exits 1 too. The error says to set
|
|
|
141
141
|
| `hotels book` | Order an offer: an unpaid order with a payment link |
|
|
142
142
|
| `orders get <orderId>` | Show an order and its status |
|
|
143
143
|
| `orders list` | List your orders, newest first |
|
|
144
|
+
| `orders cancel <orderId>` | Cancel an order under its terms, for the penalty the user agreed to |
|
|
144
145
|
| `login` | Sign in through the browser (device code) |
|
|
145
146
|
| `logout` | Revoke and forget the saved token |
|
|
146
147
|
| `whoami` | Show the signed-in account |
|
|
@@ -165,6 +166,14 @@ same.
|
|
|
165
166
|
Nothing is charged until the person pays on the page the link opens. Orders
|
|
166
167
|
are paid in USD whatever `--display-currency` shows.
|
|
167
168
|
|
|
169
|
+
`orders get` and `orders list` say of each order whether it can be cancelled
|
|
170
|
+
now and, if so, the penalty under its terms and the refund.
|
|
171
|
+
`orders cancel <orderId> --max-penalty <amount>` cancels it, with the penalty
|
|
172
|
+
the person agreed to exactly as shown; if the penalty has gone up since,
|
|
173
|
+
nothing changes and the command exits 1 with `cancellation_changed`. Without
|
|
174
|
+
`--max-penalty` it cancels nothing: it prints the order's penalty and refund
|
|
175
|
+
and exits 2.
|
|
176
|
+
|
|
168
177
|
## For AI agents
|
|
169
178
|
|
|
170
179
|
```bash
|
|
@@ -186,9 +195,9 @@ npx skills add FortripEngineering/fortrip --skill fortrip-cli
|
|
|
186
195
|
|
|
187
196
|
## MCP server
|
|
188
197
|
|
|
189
|
-
Fortrip's hosted MCP server is `https://mcp.fortrip.ai/`. It has
|
|
198
|
+
Fortrip's hosted MCP server is `https://mcp.fortrip.ai/`. It has eight tools:
|
|
190
199
|
`get_planning_guide`, `search_hotels`, `get_hotel`, `get_hotel_offers`,
|
|
191
|
-
`book_hotel`, `get_order` and `
|
|
200
|
+
`book_hotel`, `get_order`, `list_orders` and `cancel_order`.
|
|
192
201
|
|
|
193
202
|
Clients that support remote MCP servers with OAuth don't need the CLI: add
|
|
194
203
|
`https://mcp.fortrip.ai/` as a remote server and sign in to Fortrip in the
|
|
@@ -15067,6 +15067,13 @@ var listOrdersInput = strictInput({
|
|
|
15067
15067
|
),
|
|
15068
15068
|
locale: locale.optional()
|
|
15069
15069
|
});
|
|
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
|
+
var cancelOrderInput = strictInput({
|
|
15072
|
+
orderId: orderId.describe("orderId of the order to cancel, from get order or list orders."),
|
|
15073
|
+
maximumPenalty: external_exports.number({ error: maximumPenaltyError }).min(0, { error: maximumPenaltyError }).describe(
|
|
15074
|
+
"The penalty the user agreed to: cancel.penalty.amount of the order, in its currency."
|
|
15075
|
+
)
|
|
15076
|
+
});
|
|
15070
15077
|
|
|
15071
15078
|
// ../contract/src/commands.ts
|
|
15072
15079
|
function fieldDescription(json2, field, sets = {}) {
|
|
@@ -15303,6 +15310,15 @@ var ordersListFlags = flagsOf(listOrdersInput, [
|
|
|
15303
15310
|
{ flag: "limit", field: "limit", type: "number", placeholder: COUNT },
|
|
15304
15311
|
localeFlag
|
|
15305
15312
|
]);
|
|
15313
|
+
var cancelFlags = flagsOf(cancelOrderInput, [
|
|
15314
|
+
{
|
|
15315
|
+
flag: "max-penalty",
|
|
15316
|
+
field: "maximumPenalty",
|
|
15317
|
+
type: "number",
|
|
15318
|
+
placeholder: "<amount>",
|
|
15319
|
+
description: "The penalty the user agreed to, exactly as `orders get` shows it, in the order's currency, e.g. `12.50`. Without it, the command cancels nothing: it shows the penalty and the refund."
|
|
15320
|
+
}
|
|
15321
|
+
]);
|
|
15306
15322
|
var BODY_OPTION = {
|
|
15307
15323
|
flag: "body",
|
|
15308
15324
|
type: "string",
|
|
@@ -15311,7 +15327,7 @@ var BODY_OPTION = {
|
|
|
15311
15327
|
};
|
|
15312
15328
|
var COMMAND_GROUPS = [
|
|
15313
15329
|
{ name: "hotels", summary: "Search hotels, get offers and order one" },
|
|
15314
|
-
{ name: "orders", summary: "Your orders and
|
|
15330
|
+
{ name: "orders", summary: "Your orders, their status, and cancelling one" }
|
|
15315
15331
|
];
|
|
15316
15332
|
var COMMANDS = [
|
|
15317
15333
|
{
|
|
@@ -15361,6 +15377,14 @@ var COMMANDS = [
|
|
|
15361
15377
|
tool: "list_orders",
|
|
15362
15378
|
flags: ordersListFlags
|
|
15363
15379
|
},
|
|
15380
|
+
{
|
|
15381
|
+
group: "orders",
|
|
15382
|
+
name: "cancel",
|
|
15383
|
+
summary: "Cancel an order under its terms, for the penalty the user agreed to",
|
|
15384
|
+
tool: "cancel_order",
|
|
15385
|
+
flags: cancelFlags,
|
|
15386
|
+
positionals: [positional(cancelOrderInput, "orderId")]
|
|
15387
|
+
},
|
|
15364
15388
|
{
|
|
15365
15389
|
group: null,
|
|
15366
15390
|
name: "login",
|
|
@@ -15446,9 +15470,9 @@ var FRAGMENTS = {
|
|
|
15446
15470
|
"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",
|
|
15447
15471
|
"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",
|
|
15448
15472
|
"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 (Adaptive Pricing){{#if claude-skill cli}}: 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",
|
|
15449
|
-
"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
|
|
15473
|
+
"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 their orders; `{{tool:orders cancel}}` cancels one. `{{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\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",
|
|
15450
15474
|
"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 Fortrip.\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",
|
|
15451
|
-
"support": "{{#if claude-skill cli}}\n## Changes and support\n\n{{/if}}\n{{#if mcp claude-skill}}These tools{{/if}}{{#if cli}}The CLI
|
|
15475
|
+
"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"
|
|
15452
15476
|
};
|
|
15453
15477
|
|
|
15454
15478
|
// ../contract/src/guide.ts
|
|
@@ -15983,6 +16007,17 @@ var PAYMENT_STATUSES = [
|
|
|
15983
16007
|
"refund_pending",
|
|
15984
16008
|
"refunded"
|
|
15985
16009
|
];
|
|
16010
|
+
var CANCEL_REASONS = [
|
|
16011
|
+
"cancellable",
|
|
16012
|
+
"already_cancelled",
|
|
16013
|
+
"in_progress",
|
|
16014
|
+
"not_confirmed",
|
|
16015
|
+
"stay_started",
|
|
16016
|
+
"non_refundable",
|
|
16017
|
+
"refused",
|
|
16018
|
+
"terms_unknown",
|
|
16019
|
+
"needs_attention"
|
|
16020
|
+
];
|
|
15986
16021
|
var orderReference = external_exports.string().regex(/^FT-[2-9A-HJ-NP-Z]{6}$/);
|
|
15987
16022
|
var hotelItem = openObject({
|
|
15988
16023
|
type: external_exports.literal("hotel"),
|
|
@@ -16021,6 +16056,16 @@ var order = openObject({
|
|
|
16021
16056
|
localCurrencyAtCheckout: external_exports.boolean(),
|
|
16022
16057
|
localCharge: money.nullable()
|
|
16023
16058
|
}),
|
|
16059
|
+
/** Whether the user can cancel the order now and, when they can, its
|
|
16060
|
+
* penalty under the accepted terms (read a minute ahead) and the refund,
|
|
16061
|
+
* what was paid less the penalty, both in the charge currency. Absent
|
|
16062
|
+
* from servers before 3.3. */
|
|
16063
|
+
cancel: openObject({
|
|
16064
|
+
available: external_exports.boolean(),
|
|
16065
|
+
reason: openEnum(CANCEL_REASONS),
|
|
16066
|
+
penalty: money.nullable(),
|
|
16067
|
+
refund: money.nullable()
|
|
16068
|
+
}).optional(),
|
|
16024
16069
|
manageUrl: external_exports.string()
|
|
16025
16070
|
});
|
|
16026
16071
|
var orderList = openObject({
|
|
@@ -16045,13 +16090,15 @@ var offerChange = openUnion("field", [
|
|
|
16045
16090
|
|
|
16046
16091
|
// ../contract/src/tools.ts
|
|
16047
16092
|
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.";
|
|
16093
|
+
var CANCEL_NEXT_STEP = "Before you call cancel_order, 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. Pass maximumPenalty exactly as cancel.penalty.amount. Never state a refund the order did not return.";
|
|
16048
16094
|
var nextStep = external_exports.string().optional().describe(
|
|
16049
16095
|
"What to show and ask before giving a payment.url. Present when the answer holds a non-null payment.url, and only then."
|
|
16050
16096
|
);
|
|
16051
16097
|
var MCP_OUTPUT = {
|
|
16052
16098
|
book_hotel: order.extend({ nextStep }),
|
|
16053
16099
|
get_order: order.extend({ nextStep }),
|
|
16054
|
-
list_orders: orderList.extend({ nextStep })
|
|
16100
|
+
list_orders: orderList.extend({ nextStep }),
|
|
16101
|
+
cancel_order: order
|
|
16055
16102
|
};
|
|
16056
16103
|
var READ = {
|
|
16057
16104
|
readOnlyHint: true,
|
|
@@ -16096,7 +16143,7 @@ var TOOLS = [
|
|
|
16096
16143
|
{
|
|
16097
16144
|
name: "book_hotel",
|
|
16098
16145
|
title: "Create hotel order and payment link",
|
|
16099
|
-
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 user pays there; 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.
|
|
16146
|
+
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 user pays there; 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. 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.`,
|
|
16100
16147
|
annotations: {
|
|
16101
16148
|
readOnlyHint: false,
|
|
16102
16149
|
idempotentHint: false,
|
|
@@ -16121,6 +16168,19 @@ var TOOLS = [
|
|
|
16121
16168
|
annotations: READ_OWN,
|
|
16122
16169
|
input: listOrdersInput,
|
|
16123
16170
|
output: MCP_OUTPUT.list_orders
|
|
16171
|
+
},
|
|
16172
|
+
{
|
|
16173
|
+
name: "cancel_order",
|
|
16174
|
+
title: "Cancel order",
|
|
16175
|
+
description: `Cancel one of the user's orders by orderId under its cancellation terms, when its cancel.available is true: the hotel booking is cancelled and cancel.refund, what was paid less cancel.penalty, is refunded. ${CANCEL_NEXT_STEP} If the penalty is now higher than maximumPenalty, the answer is cancellation_changed and nothing changes: read the order again and ask the user again. Answers the order: status cancelling, then cancelled once the hotel cancels and the refund is issued; poll get_order. If the hotel refuses, the order goes back to confirmed with cancel.reason refused. Calling it again for the same order answers the order as it is.`,
|
|
16176
|
+
annotations: {
|
|
16177
|
+
readOnlyHint: false,
|
|
16178
|
+
idempotentHint: true,
|
|
16179
|
+
openWorldHint: true,
|
|
16180
|
+
destructiveHint: true
|
|
16181
|
+
},
|
|
16182
|
+
input: cancelOrderInput,
|
|
16183
|
+
output: MCP_OUTPUT.cancel_order
|
|
16124
16184
|
}
|
|
16125
16185
|
];
|
|
16126
16186
|
|
|
@@ -16138,6 +16198,8 @@ var ERROR_CODES = {
|
|
|
16138
16198
|
order_exists: { status: [409], retryable: false },
|
|
16139
16199
|
order_in_progress: { status: [409], retryable: true },
|
|
16140
16200
|
order_attempts_exhausted: { status: [409], retryable: false },
|
|
16201
|
+
cancellation_changed: { status: [409], retryable: false },
|
|
16202
|
+
order_not_cancellable: { status: [409], retryable: false },
|
|
16141
16203
|
destination_ambiguous: { status: [422], retryable: false },
|
|
16142
16204
|
destination_not_found: { status: [422], retryable: false },
|
|
16143
16205
|
search_too_broad: { status: [422], retryable: false },
|
|
@@ -16175,6 +16237,8 @@ var ERROR_DETAILS = {
|
|
|
16175
16237
|
order_exists: openObject({ orderId, status: openEnum(ORDER_STATUSES) }),
|
|
16176
16238
|
order_in_progress: openObject({ orderId }),
|
|
16177
16239
|
order_attempts_exhausted: openObject({ orderId }),
|
|
16240
|
+
cancellation_changed: null,
|
|
16241
|
+
order_not_cancellable: openObject({ reason: openEnum(CANCEL_REASONS) }),
|
|
16178
16242
|
destination_ambiguous: openObject({
|
|
16179
16243
|
name: external_exports.string(),
|
|
16180
16244
|
countryCode: external_exports.string(),
|
|
@@ -16227,7 +16291,14 @@ var ERROR_DETAILS = {
|
|
|
16227
16291
|
reason: openEnum(["sold_out", "refused"])
|
|
16228
16292
|
}),
|
|
16229
16293
|
rate_limited: openObject({
|
|
16230
|
-
scope: openEnum([
|
|
16294
|
+
scope: openEnum([
|
|
16295
|
+
"search",
|
|
16296
|
+
"offers",
|
|
16297
|
+
"hotel",
|
|
16298
|
+
"orders_read",
|
|
16299
|
+
"orders_create",
|
|
16300
|
+
"orders_cancel"
|
|
16301
|
+
])
|
|
16231
16302
|
}),
|
|
16232
16303
|
ordering_paused: null,
|
|
16233
16304
|
service_unavailable: null,
|
|
@@ -16493,6 +16564,18 @@ var PAYMENT_WORDS = {
|
|
|
16493
16564
|
refund_pending: "refund pending",
|
|
16494
16565
|
refunded: "refunded"
|
|
16495
16566
|
};
|
|
16567
|
+
var SUPPORT = `for help, the user emails ${SUPPORT_EMAIL} with the order's reference`;
|
|
16568
|
+
var CANCEL_REASON_WORDS = {
|
|
16569
|
+
cancellable: "it can be cancelled",
|
|
16570
|
+
already_cancelled: "it is already cancelled",
|
|
16571
|
+
in_progress: "a cancellation is in progress",
|
|
16572
|
+
not_confirmed: "only a confirmed order that is paid can be cancelled",
|
|
16573
|
+
stay_started: `the stay has started; ${SUPPORT}`,
|
|
16574
|
+
non_refundable: "this rate can't be cancelled",
|
|
16575
|
+
refused: "the hotel refused the cancellation; the booking stands",
|
|
16576
|
+
terms_unknown: `its cancellation terms are not on record; ${SUPPORT}`,
|
|
16577
|
+
needs_attention: `Fortrip is looking into this order; ${SUPPORT}`
|
|
16578
|
+
};
|
|
16496
16579
|
function itemLines(item) {
|
|
16497
16580
|
if (item.type !== "hotel") {
|
|
16498
16581
|
return [`Item of type ${item.type}: not shown in this text. ${raw(item)}`];
|
|
@@ -16530,9 +16613,17 @@ function paymentLines(o) {
|
|
|
16530
16613
|
} else if (o.status === "awaiting_payment") {
|
|
16531
16614
|
lines.push("Payment link: could not be read this time; read this order again for it.");
|
|
16532
16615
|
}
|
|
16616
|
+
if (o.cancel) lines.push(cancelLine(o.cancel));
|
|
16533
16617
|
lines.push(`Manage: ${o.manageUrl}`);
|
|
16534
16618
|
return lines;
|
|
16535
16619
|
}
|
|
16620
|
+
function cancelLine(c) {
|
|
16621
|
+
const figure = (name, m) => `${name} ${m ? money2(m) : "not stated"}`;
|
|
16622
|
+
const figures = `${figure("penalty", c.penalty)}, ${figure("refund", c.refund)}`;
|
|
16623
|
+
if (c.available) return `Cancel: can cancel now: ${figures}`;
|
|
16624
|
+
const why = `Cancel: not available: ${label(CANCEL_REASON_WORDS, c.reason)}`;
|
|
16625
|
+
return c.penalty || c.refund ? `${why} \xB7 ${figures}` : why;
|
|
16626
|
+
}
|
|
16536
16627
|
function orderLines(o) {
|
|
16537
16628
|
return [
|
|
16538
16629
|
`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)}`,
|
|
@@ -16849,6 +16940,8 @@ function detailLines(e) {
|
|
|
16849
16940
|
return [`Order ${e.details.orderId}.`];
|
|
16850
16941
|
case "order_exists":
|
|
16851
16942
|
return [`Order ${e.details.orderId}, ${label(ORDER_STATUS_WORDS, e.details.status)}.`];
|
|
16943
|
+
case "order_not_cancellable":
|
|
16944
|
+
return [`Not cancellable: ${label(CANCEL_REASON_WORDS, e.details.reason)}.`];
|
|
16852
16945
|
case "destination_ambiguous":
|
|
16853
16946
|
return ambiguous(e.details);
|
|
16854
16947
|
case "destination_not_found":
|
|
@@ -16990,9 +17083,11 @@ function renderToolResult(tool, data) {
|
|
|
16990
17083
|
} catch {
|
|
16991
17084
|
const text2 = `This ${tool} result is not in the expected shape; as JSON:
|
|
16992
17085
|
${raw(data)}`;
|
|
16993
|
-
return
|
|
16994
|
-
|
|
16995
|
-
|
|
17086
|
+
return [
|
|
17087
|
+
text2,
|
|
17088
|
+
ORDER_TOOLS.has(tool) && holdsPaymentUrl(data) ? ORDER_NEXT_STEP : "",
|
|
17089
|
+
CANCEL_TOOLS.has(tool) && holdsCancellable(data) ? CANCEL_NEXT_STEP : ""
|
|
17090
|
+
].filter(Boolean).join("\n\n");
|
|
16996
17091
|
}
|
|
16997
17092
|
switch (tool) {
|
|
16998
17093
|
case "search_hotels":
|
|
@@ -17004,15 +17099,18 @@ ${ORDER_NEXT_STEP}` : text2;
|
|
|
17004
17099
|
case "book_hotel":
|
|
17005
17100
|
case "get_order": {
|
|
17006
17101
|
const order2 = parsed;
|
|
17007
|
-
return withConsent(renderOrder(order2), [order2]);
|
|
17102
|
+
return withConsent(tool, renderOrder(order2), [order2]);
|
|
17008
17103
|
}
|
|
17009
17104
|
case "list_orders": {
|
|
17010
17105
|
const list = parsed;
|
|
17011
|
-
return withConsent(renderOrderList(list), list.data);
|
|
17106
|
+
return withConsent(tool, renderOrderList(list), list.data);
|
|
17012
17107
|
}
|
|
17108
|
+
case "cancel_order":
|
|
17109
|
+
return renderOrder(parsed);
|
|
17013
17110
|
}
|
|
17014
17111
|
}
|
|
17015
17112
|
var ORDER_TOOLS = /* @__PURE__ */ new Set(["book_hotel", "get_order", "list_orders"]);
|
|
17113
|
+
var CANCEL_TOOLS = /* @__PURE__ */ new Set(["get_order", "list_orders"]);
|
|
17016
17114
|
function holdsPaymentUrl(value, seen = /* @__PURE__ */ new Set()) {
|
|
17017
17115
|
if (typeof value !== "object" || value === null || seen.has(value)) return false;
|
|
17018
17116
|
seen.add(value);
|
|
@@ -17022,16 +17120,27 @@ function holdsPaymentUrl(value, seen = /* @__PURE__ */ new Set()) {
|
|
|
17022
17120
|
}
|
|
17023
17121
|
return Object.values(value).some((v) => holdsPaymentUrl(v, seen));
|
|
17024
17122
|
}
|
|
17025
|
-
function
|
|
17026
|
-
|
|
17027
|
-
|
|
17028
|
-
|
|
17123
|
+
function holdsCancellable(value, seen = /* @__PURE__ */ new Set()) {
|
|
17124
|
+
if (typeof value !== "object" || value === null || seen.has(value)) return false;
|
|
17125
|
+
seen.add(value);
|
|
17126
|
+
const cancel = value.cancel;
|
|
17127
|
+
if (typeof cancel === "object" && cancel !== null && cancel.available === true) {
|
|
17128
|
+
return true;
|
|
17129
|
+
}
|
|
17130
|
+
return Object.values(value).some((v) => holdsCancellable(v, seen));
|
|
17131
|
+
}
|
|
17132
|
+
function withConsent(tool, text2, orders) {
|
|
17133
|
+
return [
|
|
17134
|
+
text2,
|
|
17135
|
+
orders.some((o) => o.payment.url !== null) ? ORDER_NEXT_STEP : "",
|
|
17136
|
+
CANCEL_TOOLS.has(tool) && orders.some((o) => o.cancel?.available === true) ? CANCEL_NEXT_STEP : ""
|
|
17137
|
+
].filter(Boolean).join("\n\n");
|
|
17029
17138
|
}
|
|
17030
17139
|
|
|
17031
17140
|
// ../contract/package.json
|
|
17032
17141
|
var package_default = {
|
|
17033
17142
|
name: "@fortrip/agent-contract",
|
|
17034
|
-
version: "3.
|
|
17143
|
+
version: "3.3.0",
|
|
17035
17144
|
license: "Apache-2.0",
|
|
17036
17145
|
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.",
|
|
17037
17146
|
type: "module",
|
|
@@ -17114,6 +17223,9 @@ var API = {
|
|
|
17114
17223
|
},
|
|
17115
17224
|
order(id, opts) {
|
|
17116
17225
|
return `/v1/orders/${encodeURIComponent(id)}${opts?.locale ? `?locale=${opts.locale}` : ""}`;
|
|
17226
|
+
},
|
|
17227
|
+
orderCancel(id) {
|
|
17228
|
+
return `/v1/orders/${encodeURIComponent(id)}/cancel`;
|
|
17117
17229
|
}
|
|
17118
17230
|
};
|
|
17119
17231
|
var MCP_PATH = "/";
|
package/dist/cli.js
CHANGED
|
@@ -25,7 +25,7 @@ import {
|
|
|
25
25
|
unwrap,
|
|
26
26
|
usageError,
|
|
27
27
|
whoami
|
|
28
|
-
} from "./chunk-
|
|
28
|
+
} from "./chunk-UZAPSE5N.js";
|
|
29
29
|
|
|
30
30
|
// src/commands.ts
|
|
31
31
|
import { readFileSync } from "fs";
|
|
@@ -167,7 +167,8 @@ var ROUTES = {
|
|
|
167
167
|
const text = query.toString();
|
|
168
168
|
return text ? `${API.orders}?${text}` : API.orders;
|
|
169
169
|
}
|
|
170
|
-
}
|
|
170
|
+
},
|
|
171
|
+
cancel_order: { method: "POST", path: (input) => API.orderCancel(input.orderId) }
|
|
171
172
|
};
|
|
172
173
|
var PATH_FIELDS = /* @__PURE__ */ new Set(["hotelId", "orderId"]);
|
|
173
174
|
function parseOptions(spec, argv) {
|
|
@@ -227,7 +228,19 @@ function parseCommand(spec, argv, env) {
|
|
|
227
228
|
}
|
|
228
229
|
check(spec, input, route.method === "GET", fromEnv);
|
|
229
230
|
const path = route.path(input);
|
|
230
|
-
|
|
231
|
+
if (route.method === "GET") return { method: "GET", path };
|
|
232
|
+
const body = Object.fromEntries(Object.entries(input).filter(([field]) => !PATH_FIELDS.has(field)));
|
|
233
|
+
return { method: "POST", path, body };
|
|
234
|
+
}
|
|
235
|
+
function cancelPreview(spec, argv) {
|
|
236
|
+
const flag = spec.tool === "cancel_order" ? spec.flags.find((f) => f.field === "maximumPenalty") : void 0;
|
|
237
|
+
if (!flag) return null;
|
|
238
|
+
const { values, positionals: positionals2 } = parseOptions(spec, argv);
|
|
239
|
+
if (values[flag.flag] !== void 0) return null;
|
|
240
|
+
if (positionals2.length !== 1) throw usageError(`Usage: ${usageLine(spec)}`);
|
|
241
|
+
const input = { orderId: positionals2[0] };
|
|
242
|
+
check({ ...spec, tool: "get_order" }, input, true, /* @__PURE__ */ new Map());
|
|
243
|
+
return { method: "GET", path: API.order(input.orderId), flag: `--${flag.flag}` };
|
|
231
244
|
}
|
|
232
245
|
function check(spec, input, isGet, fromEnv) {
|
|
233
246
|
const schema = TOOLS.find((tool) => tool.name === spec.tool)?.input;
|
|
@@ -235,7 +248,7 @@ function check(spec, input, isGet, fromEnv) {
|
|
|
235
248
|
if (!result || result.success) return;
|
|
236
249
|
const pointer = (path) => {
|
|
237
250
|
const keys = path.map((key) => String(key).replaceAll("~", "~0").replaceAll("/", "~1"));
|
|
238
|
-
const where =
|
|
251
|
+
const where = keys[0] === void 0 ? [] : PATH_FIELDS.has(keys[0]) ? ["path"] : isGet ? ["query"] : [];
|
|
239
252
|
return [...where, ...keys].map((key) => `/${key}`).join("");
|
|
240
253
|
};
|
|
241
254
|
const issues = result.error.issues.flatMap(
|
|
@@ -520,16 +533,31 @@ async function run(argv) {
|
|
|
520
533
|
case "mcp": {
|
|
521
534
|
parseOptions(spec, rest);
|
|
522
535
|
const mcpUrl = resolveMcpUrl(apiUrl);
|
|
523
|
-
const { runMcpBridge } = await import("./mcp-bridge-
|
|
536
|
+
const { runMcpBridge } = await import("./mcp-bridge-EZICPRCO.js");
|
|
524
537
|
await runMcpBridge(mcpUrl, apiUrl);
|
|
525
538
|
return void 0;
|
|
526
539
|
}
|
|
527
540
|
}
|
|
528
541
|
}
|
|
542
|
+
const preview = cancelPreview(spec, rest);
|
|
543
|
+
if (preview) {
|
|
544
|
+
const order = unwrap(await authorizedRequest(apiUrl, preview.path, { method: preview.method }));
|
|
545
|
+
throw usageError(notCancelled(spec, preview.flag, order));
|
|
546
|
+
}
|
|
529
547
|
const { method, path, body } = parseCommand(spec, rest, process.env);
|
|
530
548
|
const data = unwrap(await authorizedRequest(apiUrl, path, { method, body }));
|
|
531
549
|
return { data, text: renderToolResult(spec.tool, data) };
|
|
532
550
|
}
|
|
551
|
+
function notCancelled(spec, flag, order) {
|
|
552
|
+
const line = renderToolResult("get_order", order).split("\n").find((text) => text.startsWith("Cancel: "));
|
|
553
|
+
const cancel = order?.cancel;
|
|
554
|
+
const amount = cancel?.available === true ? cancel.penalty?.amount : void 0;
|
|
555
|
+
return [
|
|
556
|
+
`Not cancelled: ${commandInvocation(spec)} needs ${flag}, the penalty the user agreed to.`,
|
|
557
|
+
line ?? "Cancel: not stated for this order.",
|
|
558
|
+
...typeof amount === "string" ? [`Pass ${flag} ${amount} to cancel.`] : []
|
|
559
|
+
].join("\n");
|
|
560
|
+
}
|
|
533
561
|
function account(data) {
|
|
534
562
|
const { apiUrl, userId, email, name } = data;
|
|
535
563
|
const given = (value) => value ?? "not given";
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "fortrip",
|
|
3
|
-
"version": "3.
|
|
3
|
+
"version": "3.3.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": "3.
|
|
35
|
+
"@fortrip/agent-contract": "3.3.0"
|
|
36
36
|
},
|
|
37
37
|
"scripts": {
|
|
38
38
|
"build": "tsup",
|