fortrip 4.3.0 → 5.0.0-rc.1

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.
@@ -5,6 +5,51 @@ var __export = (target, all) => {
5
5
  __defProp(target, name, { get: all[name], enumerable: true });
6
6
  };
7
7
 
8
+ // ../contract/src/limits.ts
9
+ var LIMITS = {
10
+ rooms: 8,
11
+ adultsPerRoom: 8,
12
+ childrenPerRoom: 4,
13
+ childAgeMax: 17,
14
+ nightsFortrip: 30,
15
+ nightsSupplier: 15,
16
+ offersHotels: 15,
17
+ offersPerHotelDefault: 10,
18
+ offersPerHotelMax: 20,
19
+ pageSizeDefault: 20,
20
+ pageSizeMax: 50,
21
+ textLength: 128,
22
+ radiusMetersMax: 8e4,
23
+ radiusMetersDefault: 8e3,
24
+ amenityFilters: 9,
25
+ guestName: 60,
26
+ contactFirstName: 59,
27
+ contactLastName: 59,
28
+ contactPhoneMin: 3,
29
+ contactPhoneMax: 40,
30
+ specialRequests: 500,
31
+ poolLimit: 3e3,
32
+ candidatesShown: 8,
33
+ candidatesCounted: 200,
34
+ localitiesShown: 8,
35
+ tokenPaymentMaxUsd: 500,
36
+ /** Minutes that must be left before the order's payment window closes
37
+ * (`payment.expiresAt`) for the order to offer a token or wallet payment
38
+ * (an entry of `payment.methods`). */
39
+ payMinMinutesLeft: 15,
40
+ /** `pay_order` refuses (`order_not_payable`), by token or wallet, when the
41
+ * order's payment window (`payment.expiresAt`) closes within this many
42
+ * minutes. */
43
+ payCutoffMinutes: 2,
44
+ tokensPerOrder: 5,
45
+ wechatCodeMinutes: 120,
46
+ /** Orders one account can make for one stay (the same room, rate, dates
47
+ * and party); past it, ordering the stay answers `order_exists`. */
48
+ ordersPerStay: 20
49
+ };
50
+ var CURRENCIES = ["USD", "CNY"];
51
+ var SUPPORT_EMAIL = "info@fortrip.ai";
52
+
8
53
  // ../../node_modules/.pnpm/zod@4.4.3/node_modules/zod/v4/classic/external.js
9
54
  var external_exports = {};
10
55
  __export(external_exports, {
@@ -14604,15 +14649,26 @@ var money = external_exports.looseObject({
14604
14649
  error: currencyError
14605
14650
  })
14606
14651
  });
14607
- var usdMoney = external_exports.strictObject(
14608
- {
14609
- amount: external_exports.string({ error: amountError }).regex(/^\d+(\.\d+)?$/, { error: amountError }).describe("Decimal string such as 132.40, never a number."),
14610
- currency: external_exports.literal("USD", { error: "currency must be USD" }).describe("Always USD in a request.")
14611
- },
14612
- {
14613
- error: (issue2) => issue2.code === "unrecognized_keys" ? `Unknown field(s): ${issue2.keys.join(", ")}` : "Expected a Money object"
14614
- }
14615
- );
14652
+ function requestMoney(name) {
14653
+ return external_exports.strictObject(
14654
+ {
14655
+ amount: external_exports.string({ error: amountError }).regex(/^\d+(\.\d+)?$/, { error: amountError }).describe("Decimal string such as 132.40, never a number."),
14656
+ currency: external_exports.enum(CURRENCIES, { error: "currency must be USD or CNY" }).describe("USD or CNY.")
14657
+ },
14658
+ {
14659
+ error: (issue2) => issue2.code === "unrecognized_keys" ? `Unknown field(s): ${issue2.keys.join(", ")}` : `${name} must be Money: { amount: "132.40", currency: "USD" or "CNY" }`
14660
+ }
14661
+ );
14662
+ }
14663
+ function echoedMoney(name) {
14664
+ return external_exports.looseObject(
14665
+ {
14666
+ amount: external_exports.string({ error: amountError }).regex(/^\d+(\.\d+)?$/, { error: amountError }).describe("Decimal string such as 132.40, never a number."),
14667
+ currency: external_exports.string({ error: currencyError }).regex(/^[A-Z]{3}$/, { error: currencyError }).describe("3-letter uppercase ISO 4217 code, as returned.")
14668
+ },
14669
+ { error: `${name} must be Money as returned: { amount: "132.40", currency: "USD" }` }
14670
+ );
14671
+ }
14616
14672
 
14617
14673
  // ../contract/src/conventions/time.ts
14618
14674
  var instant = external_exports.string({ error: "must be an RFC 3339 UTC instant such as 2026-10-23T08:00:00Z" }).regex(/^\d{4}-\d{2}-\d{2}T(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?Z$/, {
@@ -14670,51 +14726,6 @@ function normalizeGuestName(value) {
14670
14726
  return value.replace(CURLY_APOSTROPHES, "'").replace(/\s+/g, " ").trim();
14671
14727
  }
14672
14728
 
14673
- // ../contract/src/limits.ts
14674
- var LIMITS = {
14675
- rooms: 8,
14676
- adultsPerRoom: 8,
14677
- childrenPerRoom: 4,
14678
- childAgeMax: 17,
14679
- nightsFortrip: 30,
14680
- nightsSupplier: 15,
14681
- offersHotels: 15,
14682
- offersPerHotelDefault: 10,
14683
- offersPerHotelMax: 20,
14684
- pageSizeDefault: 20,
14685
- pageSizeMax: 50,
14686
- textLength: 128,
14687
- radiusMetersMax: 8e4,
14688
- radiusMetersDefault: 8e3,
14689
- amenityFilters: 9,
14690
- guestName: 60,
14691
- contactFirstName: 59,
14692
- contactLastName: 59,
14693
- contactPhoneMin: 3,
14694
- contactPhoneMax: 40,
14695
- specialRequests: 500,
14696
- poolLimit: 3e3,
14697
- candidatesShown: 8,
14698
- candidatesCounted: 200,
14699
- localitiesShown: 8,
14700
- tokenPaymentMaxUsd: 500,
14701
- /** Minutes that must be left before the order's payment window closes
14702
- * (`payment.expiresAt`) for the order to offer a token or wallet payment
14703
- * (`payment.handlers`, `payment.wallets`). */
14704
- payMinMinutesLeft: 15,
14705
- /** `pay_order` refuses (`order_not_payable`), by token or wallet, when the
14706
- * order's payment window (`payment.expiresAt`) closes within this many
14707
- * minutes. */
14708
- payCutoffMinutes: 2,
14709
- tokensPerOrder: 5,
14710
- wechatCodeMinutes: 120,
14711
- /** Orders one account can make for one stay (the same room, rate, dates
14712
- * and party); past it, ordering the stay answers `order_exists`. */
14713
- ordersPerStay: 20
14714
- };
14715
- var DISPLAY_CURRENCIES = ["USD", "CNY"];
14716
- var SUPPORT_EMAIL = "info@fortrip.ai";
14717
-
14718
14729
  // ../contract/src/vocabulary.ts
14719
14730
  var FILTERABLE_AMENITIES = [
14720
14731
  "parking",
@@ -14751,12 +14762,7 @@ var SEARCH_SORTS = [
14751
14762
  var locale = oneOf("locale", ["en", "zh"]).describe(
14752
14763
  "Language for names and text in the response: en or zh."
14753
14764
  );
14754
- var displayCurrency = oneOf("displayCurrency", [
14755
- "USD",
14756
- "CNY"
14757
- ]).describe(
14758
- "Currency to show prices in, USD or CNY. It never changes what is charged: payment is in USD."
14759
- );
14765
+ var currencyDescription = "The currency to price and charge in: USD (default) or CNY, where available (otherwise the answer is currency_unavailable).";
14760
14766
  var cursor = nonEmpty("cursor");
14761
14767
  var nightsError = (name) => `${name} must be after the check-in date and at most ${LIMITS.nightsFortrip} nights later`;
14762
14768
  var stay = strictInput({
@@ -14838,7 +14844,7 @@ var destination = external_exports.discriminatedUnion(
14838
14844
  countryCode: countryCode.describe("ISO 3166-1 alpha-2 country, e.g. JP.")
14839
14845
  }),
14840
14846
  strictInput({
14841
- kind: external_exports.literal("locality", { error: "kind must be locality" }).describe("A locality (hub) listed in an earlier search response."),
14847
+ kind: external_exports.literal("locality", { error: "kind must be locality" }).describe("A locality listed in an earlier search response."),
14842
14848
  placeId: placeId.describe("placeId of the locality."),
14843
14849
  radiusMeters
14844
14850
  })
@@ -14880,8 +14886,8 @@ var searchFilters = strictInput({
14880
14886
  "Amenities every hotel must list. Only some codes can filter; asking for one that cannot is answered with the list that can."
14881
14887
  ),
14882
14888
  price: strictInput({
14883
- maxPerRoomNight: usdMoney.describe(
14884
- "Highest price per room per night, in USD."
14889
+ maxPerRoomNight: requestMoney("filters.price.maxPerRoomNight").describe(
14890
+ "Highest price per room per night, in the search's currency."
14885
14891
  )
14886
14892
  }).optional().describe("Price limit. Needs indicative pricing, so a stay.")
14887
14893
  }).optional().describe("Filters every hotel in the answer must pass.");
@@ -14909,7 +14915,7 @@ function createSearchHotelsInput(now = Date.now) {
14909
14915
  "`nextCursor` from the previous response. A next page is the cursor and, optionally, `limit`; nothing else."
14910
14916
  ),
14911
14917
  locale: locale.optional(),
14912
- displayCurrency: displayCurrency.optional()
14918
+ currency: oneOf("currency", CURRENCIES).optional().describe(currencyDescription)
14913
14919
  }).superRefine((input, ctx) => {
14914
14920
  const issue2 = (path, message) => ctx.addIssue({ code: "custom", path, message });
14915
14921
  if (input.cursor !== void 0) {
@@ -14951,6 +14957,14 @@ function createSearchHotelsInput(now = Date.now) {
14951
14957
  );
14952
14958
  }
14953
14959
  }
14960
+ const bound = input.filters?.price?.maxPerRoomNight;
14961
+ const searchCurrency = input.currency ?? "USD";
14962
+ if (bound !== void 0 && bound.currency !== searchCurrency) {
14963
+ issue2(
14964
+ ["filters", "price", "maxPerRoomNight", "currency"],
14965
+ `filters.price.maxPerRoomNight.currency is ${bound.currency}, but the search is in ${searchCurrency}${input.currency === void 0 ? " (the default)" : ""}: send the price in ${searchCurrency}`
14966
+ );
14967
+ }
14954
14968
  const checkIn = input.stay?.checkIn;
14955
14969
  if (checkIn !== void 0 && isIsoDate(checkIn)) {
14956
14970
  const earliest = new Date(now() - 12 * 36e5).toISOString().slice(0, 10);
@@ -14982,7 +14996,7 @@ var hotelOffersInput = strictInput({
14982
14996
  `Offers per hotel, 1 to ${LIMITS.offersPerHotelMax}. Default ${LIMITS.offersPerHotelDefault}.`
14983
14997
  ),
14984
14998
  locale: locale.optional(),
14985
- displayCurrency: displayCurrency.optional()
14999
+ currency: oneOf("currency", CURRENCIES).optional().describe(`${currencyDescription} An order made from these offers is charged in this currency.`)
14986
15000
  });
14987
15001
  function cardFreeText(name, min, max, minDigits) {
14988
15002
  return text(name, min, max).refine(
@@ -15081,11 +15095,10 @@ var listOrdersInput = strictInput({
15081
15095
  ),
15082
15096
  locale: locale.optional()
15083
15097
  });
15084
- var maximumPenaltyError = "maximumPenalty must be a number of 0 or more: the order's cancel.penalty.amount, such as 12.5 for 12.50";
15085
15098
  var cancelOrderInput = strictInput({
15086
15099
  orderId: orderId.describe("The orderId of the order to cancel."),
15087
- maximumPenalty: external_exports.number({ error: maximumPenaltyError }).min(0, { error: maximumPenaltyError }).describe(
15088
- `The penalty the user agreed to, in the order's currency. Pass maximumPenalty as the number in cancel.penalty.amount ("120.00" \u2192 120).`
15100
+ maximumPenalty: echoedMoney("maximumPenalty").optional().describe(
15101
+ "The penalty the user agreed to: the order's cancel.penalty, exactly as returned. Ignored when closing an unpaid order."
15089
15102
  )
15090
15103
  });
15091
15104
  var sharedPaymentTokenRe = /^spt_[A-Za-z0-9]{1,250}$/;
@@ -15111,7 +15124,7 @@ var ucpInstrument = external_exports.looseObject(
15111
15124
  "The credential type: stripe_payment_token for the selected one."
15112
15125
  ),
15113
15126
  token: external_exports.string({ error: instrumentTokenError }).optional().describe(
15114
- "The shared payment token (spt_\u2026) the user approved for this order, requested with the order's payment.credentialLimits."
15127
+ "The shared payment token (spt_\u2026) the user approved for this order, requested with the limits of the order's stripe_shared_payment_token method."
15115
15128
  )
15116
15129
  },
15117
15130
  { error: "credential must be a JSON object" }
@@ -15146,7 +15159,7 @@ function selectedOf(instruments) {
15146
15159
  var payOrderInput = strictInput({
15147
15160
  orderId: orderId.describe("The orderId of the order to pay."),
15148
15161
  sharedPaymentToken: external_exports.string({ error: sharedPaymentTokenError }).regex(sharedPaymentTokenRe, { error: sharedPaymentTokenError }).optional().describe(
15149
- "The shared payment token (spt_\u2026) the user approved for this order, requested with the order's payment.credentialLimits. Exactly one of sharedPaymentToken, payment and method."
15162
+ "The shared payment token (spt_\u2026) the user approved for this order, requested with the limits of the order's stripe_shared_payment_token method. Exactly one of sharedPaymentToken, payment and method."
15150
15163
  ),
15151
15164
  payment: strictInput({
15152
15165
  instruments: external_exports.array(ucpInstrument, { error: instrumentsError }).min(1, { error: instrumentsError }).max(8, { error: instrumentsError }).describe("The instruments, exactly one of them selected.")
@@ -15184,11 +15197,11 @@ var payOrderInput = strictInput({
15184
15197
  }).optional().describe(
15185
15198
  "UCP's Complete Checkout payment, in place of sharedPaymentToken: the token as the stripe_payment_token credential of the one selected stripe_payments card instrument. Exactly one of sharedPaymentToken, payment and method."
15186
15199
  ),
15187
- method: oneOf("method", ["alipay_wechat_pay"]).optional().describe(
15188
- "Pay with Alipay or WeChat Pay instead of a token: opens the payment and returns payment.wallets. Exactly one of sharedPaymentToken, payment and method."
15200
+ method: oneOf("method", ["stripe_alipay_wechat_pay"]).optional().describe(
15201
+ "Pay by a method in payment.methods other than the token, which is paid with sharedPaymentToken or payment. Exactly one of sharedPaymentToken, payment and method."
15189
15202
  ),
15190
- total: usdMoney.describe(
15191
- "The total the user approved: the order's price.total, exactly as returned."
15203
+ total: requestMoney("total").describe(
15204
+ "The total the user approved: the order's price.total, in its currency, exactly as returned."
15192
15205
  )
15193
15206
  }).superRefine((input, ctx) => {
15194
15207
  const given = [
@@ -15257,11 +15270,11 @@ var localeFlag = {
15257
15270
  type: "string",
15258
15271
  placeholder: LOCALES
15259
15272
  };
15260
- var displayCurrencyFlag = {
15261
- flag: "display-currency",
15262
- field: "displayCurrency",
15273
+ var currencyFlag = {
15274
+ flag: "currency",
15275
+ field: "currency",
15263
15276
  type: "string",
15264
- placeholder: DISPLAY_CURRENCIES.join("|")
15277
+ placeholder: CURRENCIES.join("|")
15265
15278
  };
15266
15279
  function stayFlags(roomDescription) {
15267
15280
  return [
@@ -15363,8 +15376,8 @@ var searchFlags = flagsOf(searchHotelsInput, [
15363
15376
  flag: "price-max-per-room-night",
15364
15377
  field: "filters.price.maxPerRoomNight",
15365
15378
  type: "string",
15366
- placeholder: "<USD decimal>",
15367
- description: "Highest indicative price per room per night, in USD, e.g. `150` or `149.50`. Needs a stay."
15379
+ placeholder: "<decimal>",
15380
+ description: "Highest indicative price per room per night, in the search's currency (`--currency`, else USD), e.g. `150` or `149.50`. Needs a stay."
15368
15381
  },
15369
15382
  {
15370
15383
  flag: "sort",
@@ -15381,7 +15394,7 @@ var searchFlags = flagsOf(searchHotelsInput, [
15381
15394
  description: "`nextCursor` from the previous page. A next page takes only `--cursor` and `--limit`."
15382
15395
  },
15383
15396
  localeFlag,
15384
- displayCurrencyFlag
15397
+ currencyFlag
15385
15398
  ]);
15386
15399
  var hotelFlags = flagsOf(getHotelInput, [
15387
15400
  {
@@ -15413,7 +15426,7 @@ var offersFlags = flagsOf(hotelOffersInput, [
15413
15426
  },
15414
15427
  { flag: "limit-per-hotel", field: "limitPerHotel", type: "number", placeholder: COUNT },
15415
15428
  localeFlag,
15416
- displayCurrencyFlag
15429
+ currencyFlag
15417
15430
  ]);
15418
15431
  var bookFlags = flagsOf(createOrderInput, [
15419
15432
  {
@@ -15452,9 +15465,9 @@ var cancelFlags = flagsOf(cancelOrderInput, [
15452
15465
  {
15453
15466
  flag: "max-penalty",
15454
15467
  field: "maximumPenalty",
15455
- type: "number",
15468
+ type: "string",
15456
15469
  placeholder: "<amount>",
15457
- 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."
15470
+ description: "To cancel a paid order: the penalty the user agreed to, exactly as `orders get` shows it, in the order's currency, e.g. `12.50`. Without it or --close, the command changes nothing: it shows the penalty and the refund, or that the order can be closed."
15458
15471
  }
15459
15472
  ]);
15460
15473
  var payFlags = flagsOf(payOrderInput, [
@@ -15463,22 +15476,22 @@ var payFlags = flagsOf(payOrderInput, [
15463
15476
  field: "sharedPaymentToken",
15464
15477
  type: "string",
15465
15478
  placeholder: "<spt_\u2026>",
15466
- description: "Required unless --wallet. The spt_\u2026 token the user's Link wallet issued for this order."
15479
+ description: "Required unless --method. The spt_\u2026 token the user's Link wallet issued for this order. For agents that can request a token from the user's Link wallet; people pay by the order's link or --method."
15467
15480
  },
15468
15481
  {
15469
- flag: "wallet",
15482
+ flag: "method",
15470
15483
  field: "method",
15471
- type: "boolean",
15472
- value: "alipay_wechat_pay",
15473
- description: "Pay with Alipay or WeChat Pay instead of a token: prints the WeChat Pay code and both links."
15484
+ type: "string",
15485
+ placeholder: "stripe_alipay_wechat_pay",
15486
+ description: "Pay by a method in the order's payment.methods instead of a token: stripe_alipay_wechat_pay is Alipay or WeChat Pay, and prints the WeChat Pay code and both links."
15474
15487
  },
15475
15488
  {
15476
15489
  flag: "total",
15477
15490
  field: "total",
15478
15491
  type: "string",
15479
- placeholder: "<USD decimal>",
15492
+ placeholder: "<decimal>",
15480
15493
  required: "always",
15481
- description: "The total the user approved, exactly as `orders get` shows it, in USD, e.g. `125.00`."
15494
+ description: "The total the user approved, exactly as `orders get` shows it, in the order's currency, e.g. `125.00`."
15482
15495
  }
15483
15496
  ]);
15484
15497
  var BODY_OPTION = {
@@ -15542,15 +15555,22 @@ var COMMANDS = [
15542
15555
  {
15543
15556
  group: "orders",
15544
15557
  name: "cancel",
15545
- summary: "Cancel an order under its terms, for the penalty the user agreed to",
15558
+ summary: "With the penalty the user agreed to (--max-penalty) it cancels a paid order under its terms, and --close closes an unpaid one; with neither it changes nothing and shows what the order allows",
15546
15559
  tool: "cancel_order",
15547
15560
  flags: cancelFlags,
15548
- positionals: [positional(cancelOrderInput, "orderId")]
15561
+ positionals: [positional(cancelOrderInput, "orderId")],
15562
+ options: [
15563
+ {
15564
+ flag: "close",
15565
+ type: "boolean",
15566
+ description: "Close an unpaid order (cancel.reason unpaid), only once the user says they no longer want it: nothing is charged, and it becomes expired. Nothing is sent for an order that can't be closed."
15567
+ }
15568
+ ]
15549
15569
  },
15550
15570
  {
15551
15571
  group: "orders",
15552
15572
  name: "pay",
15553
- summary: "Pay an order with a Link wallet token (US and Canada) or with Alipay or WeChat Pay, instead of its payment link",
15573
+ summary: "Pay an order with a Link token (US and Canada) or with Alipay or WeChat Pay, instead of its payment link",
15554
15574
  tool: "pay_order",
15555
15575
  flags: payFlags,
15556
15576
  positionals: [positional(payOrderInput, "orderId")]
@@ -15583,21 +15603,6 @@ var COMMANDS = [
15583
15603
  tool: null,
15584
15604
  flags: []
15585
15605
  },
15586
- {
15587
- group: null,
15588
- name: "guide",
15589
- summary: "Print the guide for AI agents (Markdown); `fortrip guide planning` prints the planning guide",
15590
- tool: "get_planning_guide",
15591
- flags: [],
15592
- positionals: [
15593
- {
15594
- name: "topic",
15595
- field: null,
15596
- optional: true,
15597
- description: "`planning` for the planning guide; left out, the main guide."
15598
- }
15599
- ]
15600
- },
15601
15606
  {
15602
15607
  group: null,
15603
15608
  name: "mcp",
@@ -15632,17 +15637,17 @@ var GLOBAL_FLAGS = [
15632
15637
  // ../contract/src/guide-data.generated.ts
15633
15638
  var FRAGMENTS = {
15634
15639
  "booking": "{{#if claude-skill cli}}\n## Ordering\n\n{{/if}}\n- Call `{{tool:hotels book}}` only for the offer the user picked, with at least one guest per room{{#if claude-skill cli}}, named as the user gave them{{/if}}; never invent guests.{{#if claude-skill cli}} Room 1 is the offer's first room, and a room takes no more guests than it sleeps.{{/if}}\n- Guest names: Latin letters as on the passport (M\xFCller \u2192 Mueller), first and last name 1\u2013{{limit:guestName}} characters each{{#if cli}}, as `--guest 1:John:Smith` (room 1, first name, last name){{/if}}.\n{{#if claude-skill cli}}\n- The contact's first and last name (up to {{limit:contactFirstName}} characters each), email and phone (with its country code) are all required. Special requests must be in English and aren't guaranteed.\n{{/if}}\n- `{{tool:hotels book}}` can take about two minutes{{#if cli}}: allow the command at least 3 minutes{{/if}}. If it times out, {{#if cli}}run it again with identical flags{{/if}}{{#if mcp claude-skill}}call it again with the same details{{/if}}: it returns the same order.\n{{#if mcp}}\n- On `offer_changed`, show the user every change and ask again before ordering the new offer.\n{{/if}}\n{{#if cli}}\n- `{{tool:hotels book}}` takes only these fields: a `--body` with any other field (such as `nationality`) is rejected with exit 2.\n{{/if}}\n",
15635
- "errors": "{{#if claude-skill cli}}\n## Errors\n\n{{#if claude-skill}}A tool error{{/if}}{{#if cli}}An error on stderr{{/if}} carries `code`, `message` and `retryable`, and `retryAfterSeconds` when waiting helps; many carry `details`. Search errors are under Search. Ordering errors:\n\n| `code` | Do this |\n|---|---|\n| `offer_changed` (409) | The price or terms changed since the offer: `changes` lists every change (`worse` says which are worse for the user) and `offer` is the new offer. Show the user every change and ask again; if they still want it, order the new offer, and confirm the new order before giving its link |\n| `offer_expired` (409) | Get offers again and let the user choose again |\n| `offer_unavailable` (422) | The offer is sold out or was refused: get offers again and let the user choose again |\n| `order_in_progress` (409) | The same order is still being created: wait `retryAfterSeconds`, then {{#if claude-skill}}call again with the same details{{/if}}{{#if cli}}run the command again with identical flags{{/if}} |\n| `offer_already_ordered` (409) | This offer was already ordered with other details: show that order (`orderId`) instead. An offer is ordered once |\n| `order_exists` (409) | This stay already has an open order for one of these guests (`orderId`, `status`): show it instead of ordering again. A party with none of its guests can order the stay from a new offer (get offers again), and so can the user once the stay's order is confirmed, cancelled or refused by the hotel. It also answers when the stay's earlier order failed at the hotel with its outcome unknown, or the stay has had {{limit:ordersPerStay}} orders; for those, the user emails {{support}} |\n| `order_attempts_exhausted` (409) | This order can't be tried again: the user emails {{support}} with its `reference` |\n| `order_removed` (410) | The order was never completed and no payment is held: get offers again and order the new offer (the order keeps its `orderId`) |\n| `stay_unsupported` (422) | `mixed_occupancy`: order once per party; `max_nights`: at most `max` nights per order |\n| `stay_in_past` (422) | Check-in has passed in the hotel's time zone: ask for new dates |\n| `ordering_paused` (503) | Ordering is paused on Fortrip's side: tell the user, and try again only after `retryAfterSeconds` (10 minutes or more) |\n\nAny code:\n\n- `invalid_request` (400): `details.issues` lists each bad field; fix them. For amenities, `details.filterable` lists those that can filter.\n- `cursor_invalid` (400): the page is gone; search again from the first page.\n- `not_found` (404): no such hotel, or no such order for this user.\n- `rate_limited` (429): wait `retryAfterSeconds`, then retry once.\n- `service_unavailable` (503) and `supplier_unavailable` (503 or 504): wait `retryAfterSeconds`, then retry once with the same details; if it fails again, tell the user.\n- Any other code: read `message`. If `retryable` is true, wait `retryAfterSeconds` and retry once; otherwise tell the user instead of guessing.\n{{/if}}\n",
15640
+ "errors": "{{#if claude-skill cli}}\n## Errors\n\n{{#if claude-skill}}A tool error{{/if}}{{#if cli}}An error on stderr{{/if}} carries `code`, `message` and `retryable`, and `retryAfterSeconds` when waiting helps; many carry `details`. Search errors are under Search. Ordering errors:\n\n| `code` | Do this |\n|---|---|\n| `offer_changed` (409) | The price or terms changed since the offer: `changes` lists every change (`worse` says which are worse for the user) and `offer` is the new offer. Show the user every change and ask again; if they still want it, order the new offer, and confirm the new order before giving its link |\n| `offer_expired` (409) | Get offers again and let the user choose again |\n| `offer_unavailable` (422) | The offer is sold out or was refused: get offers again and let the user choose again |\n| `order_in_progress` (409) | The same order is still being created: wait `retryAfterSeconds`, then {{#if claude-skill}}call again with the same details{{/if}}{{#if cli}}run the command again with identical flags{{/if}} |\n| `offer_already_ordered` (409) | This offer was already ordered with other details: show that order (`orderId`) instead. An offer is ordered once |\n| `order_exists` (409) | This stay already has an open order for one of these guests (`orderId`, `status`): show it instead of ordering again. A party with none of its guests can order the stay from a new offer (get offers again), and so can the user once the stay's order is confirmed, cancelled or refused by the hotel. It also answers when the stay's earlier order failed at the hotel with its outcome unknown, or the stay has had {{limit:ordersPerStay}} orders; for those, the user emails {{support}} |\n| `order_attempts_exhausted` (409) | This order can't be tried again: the user emails {{support}} with its `reference` |\n| `order_removed` (410) | The order was never completed and no payment is held: get offers again and order the new offer (the order keeps its `orderId`) |\n| `stay_unsupported` (422) | `mixed_occupancy`: order once per party; `max_nights`: at most `max` nights per order |\n| `currency_unavailable` (422) | Prices in `details.currency` aren't available yet: tell the user, and ask whether to see USD prices |\n| `stay_in_past` (422) | Check-in has passed in the hotel's time zone: ask for new dates |\n| `ordering_paused` (503) | Ordering is paused on Fortrip's side: tell the user, and try again only after `retryAfterSeconds` |\n\nAny code:\n\n- `invalid_request` (400): `details.issues` lists each bad field; fix them. For amenities, `details.filterable` lists those that can filter.\n- `cursor_invalid` (400): the page is gone; search again from the first page.\n- `not_found` (404): no such hotel, or no such order for this user.\n- `rate_limited` (429): wait `retryAfterSeconds`, then retry once.\n- `service_unavailable` (503) and `supplier_unavailable` (503 or 504): wait `retryAfterSeconds`, then retry once with the same details; if it fails again, tell the user.\n- Any other code: read `message`. If `retryable` is true, wait `retryAfterSeconds` and retry once; otherwise tell the user instead of guessing.\n{{/if}}\n",
15636
15641
  "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',
15637
15642
  "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",
15638
- "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.\n{{/if}}\n',
15639
- "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 ${{limit:tokenPaymentMaxUsd}}, 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## Paying with Alipay or WeChat Pay\n\nAn order whose result text has the line \"Pay with Alipay or WeChat Pay\" can be paid in the user's Alipay or WeChat wallet, with no token: it is for users who have a mainland-China wallet. {{#if claude-skill}}Call{{/if}}{{#if cli}}Run{{/if}} `{{tool:orders pay}}` {{#if claude-skill}}with `method` `alipay_wechat_pay`{{/if}}{{#if cli}}the way that line shows{{/if}} and the order's `price.total`, only after the user has confirmed.\n\n1. Show the user the order's total in USD, 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. Pay one way only: `payment.url` or this.\n2. Then show `payment.wallets`: the WeChat Pay code as an image if you can, and both links (WeChat Pay and Alipay). The user pays once, by either. Alipay and WeChat Pay charge at once; if the hotel can't confirm, the payment is refunded in full. The total is in US dollars, and the wallets show it in yuan at their rate.\n3. Check the order with `{{tool:orders get}}` until it isn't `awaiting_payment`.\n\nA WeChat Pay code expires {{limit:wechatCodeMinutes}} minutes after it is made, and goes dead earlier if the user opens the Alipay link instead. Then `payment.wallets.wechatPay.qrData` is null: tell the user to open the WeChat link again, or {{#if claude-skill}}call{{/if}}{{#if cli}}run{{/if}} `{{tool:orders pay}}` again for a new code.\n\nWeChat can't scan a code shown on the same phone's screen. Offer both ways, since you can't tell which device the user is on: save the image and scan it from the album (WeChat, then Scan, then Album), or open the WeChat link on another screen; on a phone, the Alipay link opens the Alipay app.\n\n## After payment\n\nCheck the order with `{{tool:orders get}}`:\n\n- `confirming` while the hotel confirms, then `confirmed` with the hotel's `confirmationNumber`.\n- `failed`: no stay was booked; `payment.status` says whether the payment was released or refunded.\n- `needs_attention`: Fortrip is looking into it; the user can email {{support}} with the `reference`.\n- `manageUrl` is the user's own page for the order.\n{{/if}}\n",
15640
- "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",
15641
- "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",
15642
- "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",
15643
- "scope": "{{#if claude-skill cli}}\n# Fortrip hotel stays\n\n{{/if}}\nFortrip: hotel search, live offers and orders with a payment link.{{#if claude-skill cli}} Not for flights, activities, or changing an existing order.{{/if}}\n\n{{#if mcp}}\nCall order: `{{tool:hotels search}}` \u2192 (optional) `{{tool:hotels get}}` \u2192 `{{tool:hotels offers}}` \u2192 `{{tool:hotels book}}`; after the user pays, `{{tool:orders get}}`; `{{tool:orders list}}` lists, `{{tool:orders cancel}}` cancels, `{{tool:orders pay}}` pays by token or Alipay/WeChat Pay. `{{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, by a shared payment token from the user's wallet, or with Alipay or WeChat Pay |\n\nFor flexible dates, a budget, split stays, several destinations or \"find me the best\", {{#if claude-skill}}read [references/planning.md](references/planning.md){{/if}}{{#if cli}}also run `{{tool:guide}} planning`{{/if}} before searching.\n{{/if}}\n",
15644
- "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",
15645
- "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"
15643
+ "order": '{{#if claude-skill cli}}\n## Workflow\n\n1. **Search** with `{{tool:hotels search}}` for candidate hotels: a destination, `{{arg:text}}` or both, and the stay\'s dates and rooms for indicative prices.\n{{#if cli}}\n\n ```bash\n {{tool:hotels search}} --place-name Bangkok --country TH --check-in 2026-11-10 \\\n --check-out 2026-11-12 --room 2 --stars-min 4 --sort price_asc --limit 10\n ```\n\n{{/if}}\n2. **Details** (optional) with `{{tool:hotels get}}`, when the user asks about a hotel or a stated preference needs evidence (a pool, a policy, room size). For a details-only question, call it directly when you know the hotel\'s `hotelId`; otherwise find the hotel with `{{tool:hotels search}}`.\n{{#if cli}}\n\n ```bash\n {{tool:hotels get}} <hotelId> [--rooms]\n ```\n\n{{/if}}\n3. **Offers** with `{{tool:hotels offers}}` for a few shortlisted hotels, with the dates and rooms the user will order. It takes about 15 seconds. A hotel is available only once this returns an offer for it.\n{{#if cli}}\n\n ```bash\n {{tool:hotels offers}} --hotel <hotelId> --hotel <hotelId> --check-in 2026-11-10 \\\n --check-out 2026-11-12 --room 2 --room 2 [--require-free-cancellation]\n ```\n\n{{/if}}\n4. **Order** with `{{tool:hotels book}}`, once the user has picked one offer and given the guests and the contact (see Ordering).\n{{#if cli}}\n\n ```bash\n {{tool:hotels book}} --offer <offerId> --guest 1:John:Smith --guest 2:Mary:Smith \\\n --first-name John --last-name Smith --email john@example.com \\\n --phone "+8613800000000"\n ```\n\n{{/if}}\n5. **Confirm, then give the payment link**, as in "Before giving the payment link" below.\n6. **After payment**, check the order with `{{tool:orders get}}` (see After payment).\n\n## Search\n\n### Where\n\n- **A place by name:** {{#if mcp claude-skill}}`{ kind: "place_name", name, countryCode }`{{/if}}{{#if cli}}`--place-name <name> --country <CC>`{{/if}}, in any language (Kyoto or \u4EAC\u90FD). The country is required: ask the user when it isn\'t clear. Names match exactly, ignoring only case and spacing: accents, hyphens, apostrophes and periods count ("K\xF6ln" or "Cologne", not "Koln"; "St. Moritz", not "St Moritz").\n- If several places bear the name, the answer is `destination_ambiguous` with up to {{limit:candidatesShown}} candidates and their hotel counts: ask the user which one they mean, then search it by its `placeId`; never pick one yourself.\n- `destination_not_found` with `no_match` means no place of that name in that country: check the spelling and accents, or try another name for the place. Its `nameAsText` counts the hotels that a `{{arg:text}}` search for the name would find.\n- **A place from an earlier answer:** {{#if mcp claude-skill}}`{ kind: "place", placeId }`{{/if}}{{#if cli}}`--place <placeId>`{{/if}}.\n- **Near a point:** {{#if mcp claude-skill}}`{ kind: "point", location: { lat, lng } }`{{/if}}{{#if cli}}`--point <lat,lng>`{{/if}}, for "near X" when you know where X is.\n- **A whole country:** {{#if mcp claude-skill}}`{ kind: "country", countryCode }`{{/if}}{{#if cli}}`--country-only <CC>`{{/if}}, as for the Maldives.\n- Countries, regions (states, provinces), prefecture-level cities in China and main islands cover their whole area. Towns, neighbourhoods, districts, small islands and points cover a circle of {{limit:radiusMetersDefault}} meters; `{{arg:destination.radiusMeters}}` sets another, up to {{limit:radiusMetersMax}} meters, and narrows an area to a circle around its center.\n- **Localities:** an area search lists its `localities`, the towns its hotels belong to, each with a `placeId`, its hotel `count` and the places it `includes` (Patong is part of Phuket). To search one, pass it as {{#if mcp claude-skill}}`{ kind: "locality", placeId }`{{/if}}{{#if cli}}`--locality <placeId>`{{/if}}. A town that isn\'t a locality answers `destination_not_found` with `not_a_locality` and, in `hub`, the locality it belongs to: search that locality, or the town itself with {{#if mcp claude-skill}}`kind: "place"`{{/if}}{{#if cli}}`--place`{{/if}} for a circle around it.\n- A price sort or price filter over more than {{limit:poolLimit}} hotels (in an area, or for text alone) answers `search_too_broad` with `matched` and the top `localities`: show them and ask the user which they prefer, unless the request already names one of them; search that one by its `placeId` as a locality, never by its name.\n\n### Text\n\n`{{arg:text}}` matches exact words in hotel names and addresses, in Chinese or English:\n\n- Every word must match as written: plurals, accents, spacing and abbreviations count ("hostel" and "hostels", "St Regis" and "Saint Regis" find different hotels). Hyphens and apostrophes don\'t (Ritz-Carlton finds Ritz Carlton).\n- In Chinese, matching follows word segmentation, so part of a name can match unrelated hotels (\u5E0C\u5C14 is not \u5E0C\u5C14\u987F).\n- Use only distinctive words: a hotel or brand name, a district or a landmark. Not "hotel", "near", "cheap" or "best".\n- 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 the search\'s currency; hotels without one are left out and counted.\n\n### Results\n\n- `notes` explain the answer (a limited pool, a circle around an island, more hotels just outside it): pass on what matters to the user.\n- `coverage` has the counts: `matched` hotels, how many were priced and how many have a price.\n- A next page is {{#if mcp claude-skill}}`cursor` set to `nextCursor` and, optionally, `limit`{{/if}}{{#if cli}}`--cursor <nextCursor>` and, optionally, `--limit`{{/if}}; nothing else.\n{{/if}}\n{{#if mcp}}\n- A place name needs its `countryCode` (ask the user if unclear) and matches exactly (accents and periods count). On `destination_ambiguous`, ask the user which they mean, then search its `placeId`; never pick one yourself.\n- On `search_too_broad`, show its `localities` and ask the user which, unless they already named one; search it as `{ kind: "locality", placeId }`, never by name.\n- `text` matches whole words of hotel names and addresses: use a distinctive name, brand or landmark.\n{{/if}}\n',
15644
+ "payment-link": "{{#if claude-skill cli}}\n## Before giving the payment link\n\n`{{tool:hotels book}}` answers with an unpaid order: `status` `awaiting_payment`, its `reference` (the support number), `price.total`, the stay and its terms, and `payment.url`, a Fortrip page that recaps the order and continues to the payment provider. Nothing is charged until the user pays.\n\n1. Show the order's total and currency, the stay (hotel, room, dates, rooms and guests per room) and every term: meals, cancellation (status, deadline, penalties) and fees payable at the property, unknowns included.\n2. End that reply by asking the user to confirm, and wait for a clear yes. Urgency is not consent.\n3. Then give `payment.url` exactly as returned: 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, or can be closed now with `{{tool:orders cancel}}`{{#if cli}} and `--close`{{/if}} once the user says they no longer want it.\n- An order `awaiting_payment` with `payment.status` `unpaid` whose `payment.url` is null 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.methods` has the `stripe_shared_payment_token` entry (in {{#if claude-skill}}a result's text{{/if}}{{#if cli}}the text output{{/if}}, the line \"Pay without the link\") can also be paid through `{{tool:orders pay}}` with a Stripe shared payment token that the user's Link wallet grants for it. Use it only if you have a tool that can request such a token from the user's Link wallet: Link is for US and Canadian accounts, and caps a spend request at ${{limit:tokenPaymentMaxUsd}}, so only a USD order up to that has such an entry. Otherwise give `payment.url`, and never ask the user to create, type or paste a token.\n\n1. 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 that entry's `handler.config.business_profile` and its `limits`: `maxAmount` (in cents), `currency` and `expiresAt`.\n3. {{#if claude-skill}}Call{{/if}}{{#if cli}}Run{{/if}} `{{tool:orders pay}}` with the token and the order's `price.total`{{#if cli}} (`--token`, `--total`){{/if}}{{#if claude-skill}}, the token as `sharedPaymentToken` or in UCP's `payment.instruments`{{/if}}. The order is then `confirming`, its payment `authorized`: check it as after payment.\n\nThe charge is in USD: a card in another currency may add a foreign transaction fee. 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 that entry's `limits`. `service_unavailable`: call `{{tool:orders pay}}` again with the same token, never a new one. A token pays one order only.\n\n## Paying with Alipay or WeChat Pay\n\nAn order whose result text has the line \"Pay with Alipay or WeChat Pay\" can be paid in the user's Alipay or WeChat wallet, with no token: it is for users who have a mainland-China wallet. {{#if claude-skill}}Call{{/if}}{{#if cli}}Run{{/if}} `{{tool:orders pay}}` {{#if claude-skill}}with `method` `stripe_alipay_wechat_pay`{{/if}}{{#if cli}}the way that line shows{{/if}} and the order's `price.total`, only after the user has confirmed.\n\n1. 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. Pay one way only: `payment.url` or this.\n2. Then show the `stripe_alipay_wechat_pay` entry of `payment.methods`: the WeChat Pay code as an image if you can, and both links (WeChat Pay and Alipay). The user pays once, by either. Alipay and WeChat Pay charge at once; if the hotel can't confirm, the payment is refunded in full. The total is in the order's currency, and the wallets show it in yuan at their rate.\n3. Check the order with `{{tool:orders get}}` until it isn't `awaiting_payment`.\n\nA WeChat Pay code expires {{limit:wechatCodeMinutes}} minutes after it is made, and goes dead earlier if the user opens the Alipay link instead. Then that entry's `wechatPay.qrData` is null: tell the user to open the WeChat link again, or {{#if claude-skill}}call{{/if}}{{#if cli}}run{{/if}} `{{tool:orders pay}}` again for a new code.\n\nWeChat can't scan a code shown on the same phone's screen. Offer both ways, since you can't tell which device the user is on: save the image and scan it from the album (WeChat, then Scan, then Album), or open the WeChat link on another screen; on a phone, the Alipay link opens the Alipay app.\n\n## After payment\n\nCheck the order with `{{tool:orders get}}`:\n\n- `confirming` while the hotel confirms, then `confirmed` with the hotel's `confirmationNumber`.\n- `failed`: no stay was booked; `payment.status` says whether the payment was released or refunded.\n- `needs_attention`: Fortrip is looking into it; the user can email {{support}} with the `reference`.\n- `manageUrl` is the user's own page for the order.\n{{/if}}\n",
15645
+ "planning": "# Planning a hotel stay\n\nRead this when the request is more than one hotel for fixed dates: flexible dates, a budget, split stays, several destinations, or \"find me the best\". The rules in {{#if mcp}}the server instructions{{/if}}{{#if claude-skill cli}}SKILL.md{{/if}} still apply (call order, destinations, 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, is unknown. Say so instead of filling it in.\n\n## Ranking\n\n1. Drop options that break a hard constraint (dates, guests, budget cap, required facility). Compare a budget in the unit the user gave it: per night, per room or for the whole stay. An offer's `price.total` covers the whole stay and every room, in the offer's currency.\n2. Keep only options with a live offer.\n3. Order by the user's stated main goal. Goals they didn't state don't count.\n4. Use other preferences only to break ties.\n\nUse the cheapest comparable offer as the baseline unless the user fixed the room type. 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",
15646
+ "presentation": "{{#if claude-skill}}\n## Presenting hotels\n\nIf your interface can show rich elements, show each hotel as a card with only what Fortrip's tools returned for it in this conversation: photo, name, stars, region and price, and once you have offers every term that changes the choice (meals and who they cover, cancellation, fees payable at the property, confirmation), an unknown one as unknown. Label a search's `price.fromPerRoomNight` as an estimate per room-night and an offer's `price.total` as the whole stay for all rooms, in its currency, and draw a map only from returned `location` coordinates. Offer the choices you need to ask anyway (dates, a locality, which offer) as options to pick. Otherwise use a short list. Keep hotel names as returned, and never invent photos, ratings, reviews, prices, terms or coordinates.\n{{/if}}\n",
15647
+ "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 the request's `{{arg:currency}}` (`USD` by default); an order is in the currency of the offer it was made from.{{#if claude-skill cli}} `perNightAllRooms` is the total per night; to compare with a per-room budget, also divide by the rooms.{{/if}} On a USD order, Stripe's page may let the user pay in their card's local currency at Stripe's rate{{#if claude-skill cli}} (Adaptive Pricing): say so plainly, and that the total in that currency is the price{{/if}}.\n{{#if claude-skill cli}}\n- Every price of a response is in that one currency; don't convert it. `{{arg:currency}}`{{#if cli}} (or `FORTRIP_CURRENCY`){{/if}} is `USD` (the default) or `CNY`, where available; otherwise the answer is `currency_unavailable`.\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",
15648
+ "scope": "{{#if claude-skill cli}}\n# Fortrip hotel stays\n\n{{/if}}\nFortrip: hotel search, live offers and orders with a payment link.{{#if claude-skill cli}} Not for flights, activities, or changing an existing order.{{/if}}\n\n{{#if mcp}}\nCall order: `{{tool:hotels search}}` \u2192 (optional) `{{tool:hotels get}}` \u2192 `{{tool:hotels offers}}` \u2192 `{{tool:hotels book}}`; after the user pays, `{{tool:orders get}}`; `{{tool:orders list}}` lists, `{{tool:orders cancel}}` cancels or closes an unpaid one, `{{tool:orders pay}}` pays by token or Alipay/WeChat Pay.\n{{/if}}\n{{#if claude-skill}}\nThe tools are on Fortrip's MCP server, named `fortrip` in this plugin (a Fortrip connector added on claude.ai can show under its own name). They're written `fortrip:<tool>` below:\n{{/if}}\n{{#if cli}}\nThe `fortrip` CLI (npm package `fortrip`) calls Fortrip as the signed-in user and prints each answer as compact text (`--json` prints its JSON):\n{{/if}}\n{{#if claude-skill cli}}\n\n| {{#if claude-skill}}Tool{{/if}}{{#if cli}}Command{{/if}} | Returns |\n|---|---|\n| `{{tool:hotels search}}` | Hotels in a place, near a point or matching a name (`{{arg:text}}`), with indicative prices |\n| `{{tool:hotels get}}` | One hotel's address, check-in and check-out times, description, policies, amenities and rooms; no prices |\n| `{{tool:hotels offers}}` | Live offers (room, meals, total and currency, cancellation terms) for up to {{limit:offersHotels}} hotels |\n| `{{tool:hotels book}}` | An unpaid order for one offer, with its terms and a payment link |\n| `{{tool:orders get}}` | One order and its status, including whether the hotel confirmed it |\n| `{{tool:orders list}}` | The user's orders, newest first, including those made on the Fortrip website |\n| `{{tool:orders cancel}}` | Cancels an order under its terms, for the penalty the user agreed to, and refunds the rest; closes an unpaid one |\n| `{{tool:orders pay}}` | Pays an order without its link, by a shared payment token from the user's wallet, or with Alipay or WeChat Pay |\n\nFor flexible dates, a budget, split stays, several destinations or \"find me the best\", read [references/planning.md](references/planning.md) before searching.\n{{/if}}\n",
15649
+ "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 a remote agent environment or a CI run without a browser, the user can set `FORTRIP_TOKEN` instead. Exit 3 with `tokenSource: \"FORTRIP_TOKEN\"` means Fortrip didn't accept that token: tell the user to replace or unset it.\n\n## Exit codes\n\n| Code | Meaning | What to do |\n|---|---|---|\n| 0 | Success; the answer on stdout | Continue |\n| 1 | Any other error: an error from Fortrip (see Errors), a network error or a timeout | Read the error on stderr. If `retryable` is true, wait `retryAfterSeconds` (or a few seconds) and retry once |\n| 2 | Invalid arguments, or `invalid_request` from Fortrip | Fix the flags; the error lists each bad field with a message |\n| 3 | Not signed in | Show `loginUrl` to the user, then rerun (above) |\n| 4 | Rate limited | Wait `retryAfterSeconds`, then retry once |\n\nOutput on stdout or stderr can carry `warning` (with `recoveryFile` when a sign-in couldn't be saved): pass it on to the user.\n{{/if}}\n",
15650
+ "support": "{{#if claude-skill cli}}\n## Cancelling an order\n\n`{{tool:orders get}}` and `{{tool:orders list}}` say of each order whether the user can cancel it now (`cancel.available`). A paid order (`cancel.reason` `cancellable`) then has the penalty under its terms (`cancel.penalty`) and the refund, what was paid less the penalty (`cancel.refund`), both in the charge currency; an unpaid one (`unpaid`) can be closed instead. Otherwise `cancel.reason` says why not.\n\n1. Show the user the stay (hotel, dates), `cancel.penalty` and `cancel.refund` (amount and currency). A refund of 0 means nothing is paid back: say so plainly.\n2. End that reply by asking the user to confirm the cancellation, and wait for a clear yes.\n3. Then {{#if claude-skill}}call{{/if}}{{#if cli}}run{{/if}} `{{tool:orders cancel}}` with `{{arg:maximumPenalty}}` set to `cancel.penalty` as shown{{#if cli}}, its amount: the CLI takes the currency from the order{{/if}}. Never state a refund the order didn't return, and never choose or work out an amount yourself.\n\nThe order is then `cancelling`, and `cancelled` once the hotel has cancelled and the refund is issued: check it with `{{tool:orders get}}`. If the hotel refuses, the order is `confirmed` again with `cancel.reason` `refused`. `cancellation_changed` (409) means the penalty is now higher than the one the user agreed to: read the order again and ask the user again. `order_not_cancellable` (409) says why in `reason`.\n\nClose an unpaid order only once the user says they no longer want it: {{#if claude-skill}}call{{/if}}{{#if cli}}run{{/if}} `{{tool:orders cancel}}` {{#if claude-skill}}without `maximumPenalty`{{/if}}{{#if cli}}with `--close`{{/if}}. It becomes `expired`, and nothing is charged. `payment_in_progress` (409) means a payment of it is under way: read it again shortly.{{#if cli}} Without `--max-penalty` or `--close`, `{{tool:orders cancel}}` changes nothing: it prints the penalty and the refund, or that the order can be closed, and exits 2.{{/if}}\n\n## Changes and support\n\n{{/if}}\n{{#if mcp}}For changes{{/if}}{{#if claude-skill}}These tools can't change an order: for changes{{/if}}{{#if cli}}The CLI can't change an order: for changes{{/if}}, a cancellation that `{{tool:orders cancel}}` can't make, or other problems, the user emails {{support}} with the order's `reference` (never `payment.url`).\n"
15646
15651
  };
15647
15652
 
15648
15653
  // ../contract/src/guide.ts
@@ -15750,7 +15755,7 @@ function resolve(token, surface, shown) {
15750
15755
  }
15751
15756
  function toolName(spec, surface, token) {
15752
15757
  if (surface === "cli") return commandInvocation(spec);
15753
- if (spec.tool === null || surface === "claude-skill" && spec.tool === "get_planning_guide") {
15758
+ if (spec.tool === null) {
15754
15759
  throw new Error(`Guide token ${token} has no tool on ${surface}`);
15755
15760
  }
15756
15761
  return surface === "mcp" ? spec.tool : `fortrip:${spec.tool}`;
@@ -15889,12 +15894,7 @@ var indicativePrice = openObject({
15889
15894
  kind: openEnum(["indicative"]),
15890
15895
  basis: openEnum(["lowest_unit"]),
15891
15896
  fromPerRoomNight: money,
15892
- fromPerRoomStay: money,
15893
- approx: openObject({
15894
- fromPerRoomNight: money,
15895
- fromPerRoomStay: money,
15896
- rateDate: localDate
15897
- }).nullable()
15897
+ fromPerRoomStay: money
15898
15898
  });
15899
15899
  var hotelSummary = openObject({
15900
15900
  hotelId,
@@ -15954,6 +15954,7 @@ var destination2 = openUnion("kind", [
15954
15954
  })
15955
15955
  ]);
15956
15956
  var count = external_exports.number().int();
15957
+ var hotels = (what) => count.nullable().describe(what);
15957
15958
  var searchResult = openObject({
15958
15959
  destination: destination2.nullable(),
15959
15960
  text: openObject({
@@ -15974,17 +15975,31 @@ var searchResult = openObject({
15974
15975
  "price_desc"
15975
15976
  ]),
15976
15977
  coverage: openObject({
15977
- matched: count,
15978
- priced: count.nullable(),
15979
- withPrice: count.nullable(),
15980
- poolRadiusMeters: external_exports.number().nullable(),
15981
- excludedNoPrice: count.nullable(),
15982
- excludedNoFacilityData: count.nullable(),
15983
- withinMaxRadius: count.nullable(),
15984
- textAnywhere: count.nullable(),
15985
- localities: localities.nullable(),
15986
- nameAsText: count.nullable()
15987
- }),
15978
+ matched: count.describe(
15979
+ "Hotels that match the destination, the text and every filter but the price filter."
15980
+ ),
15981
+ priced: hotels(
15982
+ "Hotels priced: those on this page, or with a price sort or price filter the whole priced set (pricing.scope); null without prices."
15983
+ ),
15984
+ withPrice: hotels("Of those priced, how many have an indicative price; null when prices weren't asked for or are unavailable."),
15985
+ poolRadiusMeters: external_exports.number().nullable().describe(
15986
+ `When a price sort or price filter priced only the nearest ${LIMITS.poolLimit.toLocaleString("en-US")}: how far the farthest of them is from the center, in meters; otherwise null.`
15987
+ ),
15988
+ excludedNoPrice: hotels("With a price filter: priced hotels left out for having no indicative price; otherwise null."),
15989
+ excludedNoFacilityData: hotels(
15990
+ "With an amenity filter: hotels left out for listing no facilities at all, though they may have the amenity; otherwise null."
15991
+ ),
15992
+ withinMaxRadius: hotels(
15993
+ `For a radius under ${LIMITS.radiusMetersMax.toLocaleString("en-US")} m: how many would match within ${LIMITS.radiusMetersMax.toLocaleString("en-US")} m of the center; otherwise null.`
15994
+ ),
15995
+ textAnywhere: hotels(
15996
+ "With text and a place: the hotels that match the text anywhere in the place's country; otherwise null."
15997
+ ),
15998
+ localities: localities.nullable().describe("For an area: its top localities, the towns its matching hotels belong to; otherwise null."),
15999
+ nameAsText: hotels(
16000
+ "When a place_name search matched few hotels: how many in its country match the name as text; otherwise null."
16001
+ )
16002
+ }).describe("What the search covered: counts of hotels, each null when it doesn't apply."),
15988
16003
  data: external_exports.array(hotelSummary),
15989
16004
  nextCursor: external_exports.string().nullable().describe("Pass it back as cursor for the next page; null on the last page."),
15990
16005
  notes: external_exports.array(
@@ -16070,11 +16085,17 @@ var hotel = openObject({
16070
16085
  var meals = openObject({
16071
16086
  known: external_exports.boolean(),
16072
16087
  included: external_exports.array(openEnum(["breakfast", "lunch", "dinner"])).nullable(),
16073
- unspecifiedMainMeals: external_exports.number().int().nullable(),
16088
+ unspecifiedMainMeals: external_exports.number().int().nullable().describe(
16089
+ "Main meals a day beyond included that the rate doesn't name (e.g. 1 when a half-board rate doesn't say lunch or dinner); null when known is false."
16090
+ ),
16074
16091
  allInclusive: external_exports.boolean().nullable(),
16075
- guestsCoveredPerRoom: external_exports.number().int().nullable(),
16092
+ guestsCoveredPerRoom: external_exports.number().int().nullable().describe(
16093
+ "How many guests in each room the meals are for; fewer than the guests in the room means not everyone gets them. null when not stated."
16094
+ ),
16076
16095
  label: localizedText.nullable()
16077
- });
16096
+ }).describe(
16097
+ "What the rate includes to eat. known false: the meals are unknown, not none, and included, unspecifiedMainMeals and allInclusive are null."
16098
+ );
16078
16099
  var payAtProperty = openObject({
16079
16100
  disclosure: openEnum(["complete", "incomplete"]),
16080
16101
  items: external_exports.array(
@@ -16092,20 +16113,24 @@ var payAtProperty = openObject({
16092
16113
  collectedAt: openEnum(["property", "unknown"])
16093
16114
  })
16094
16115
  )
16095
- });
16116
+ }).describe(
16117
+ "Fees paid at the property, on top of price.total, in the property's currency, not converted. disclosure incomplete: there may be fees not listed."
16118
+ );
16096
16119
  var cancellation = openObject({
16097
16120
  status: openEnum(["free", "partial_penalty", "non_refundable", "unknown"]),
16098
- asOf: instant,
16121
+ asOf: instant.describe("When these terms were read: status and penalties are as of this time."),
16099
16122
  freeCancellationEndsAt: instant.nullable(),
16100
16123
  penalties: external_exports.array(
16101
16124
  openObject({ startsAt: instant.nullable(), amount: money })
16102
16125
  ),
16103
16126
  timeZone: external_exports.string().nullable()
16104
- });
16127
+ }).describe("The cancellation terms, read at asOf.");
16105
16128
  var confirmation = openObject({
16106
- mode: openEnum(["instant", "on_request", "unknown"]),
16107
- withinMinutes: external_exports.number().int().nullable()
16108
- });
16129
+ mode: openEnum(["instant", "on_request", "unknown"]).describe(
16130
+ "instant: the hotel confirms the booking as soon as it is made. on_request: the hotel confirms or refuses it later, within withinMinutes when stated. unknown: not stated."
16131
+ ),
16132
+ withinMinutes: external_exports.number().int().nullable().describe("For on_request, the minutes the hotel takes to confirm; null when instant or not stated.")
16133
+ }).describe("How the hotel confirms a booking of this offer.");
16109
16134
  var offer = openObject({
16110
16135
  offerId,
16111
16136
  type: openEnum(["hotel"]),
@@ -16118,24 +16143,26 @@ var offer = openObject({
16118
16143
  }),
16119
16144
  price: openObject({
16120
16145
  total: money,
16121
- perNightAllRooms: money,
16122
- approx: openObject({
16123
- total: money,
16124
- perNightAllRooms: money,
16125
- rateDate: localDate
16126
- }).nullable(),
16146
+ perNightAllRooms: money.describe(
16147
+ "price.total divided by the nights: all rooms, one night. A search's fromPerRoomNight is for one room; divide by roomCount to compare."
16148
+ ),
16127
16149
  payAtProperty
16128
16150
  }),
16129
16151
  cancellation,
16130
16152
  confirmation
16131
16153
  });
16154
+ var removed = (step) => external_exports.number().int().describe(`Offers left out ${step}.`);
16132
16155
  var omitted = openObject({
16133
- byNationality: external_exports.number().int(),
16134
- byFilters: external_exports.number().int(),
16135
- dominated: external_exports.number().int(),
16136
- unreadable: external_exports.number().int(),
16137
- byLimit: external_exports.number().int()
16138
- });
16156
+ byNationality: removed(
16157
+ "because the hotel sells them only to guests of some nationalities; Fortrip can't book them"
16158
+ ),
16159
+ byFilters: removed("by filters"),
16160
+ dominated: removed(
16161
+ "because another offer of the same room is as good on price and every term, or can't be told apart from one kept"
16162
+ ),
16163
+ unreadable: removed("because their details came back incomplete or inconsistent"),
16164
+ byLimit: removed("by limitPerHotel")
16165
+ }).describe("How many offers each selection step left out.");
16139
16166
  var UNAVAILABLE_REASONS = [
16140
16167
  "sold_out",
16141
16168
  "no_matching_offers",
@@ -16157,7 +16184,9 @@ var hotelOffersResult = openObject({
16157
16184
  unavailable: external_exports.array(
16158
16185
  openObject({
16159
16186
  hotelId,
16160
- reason: openEnum(UNAVAILABLE_REASONS),
16187
+ reason: openEnum(UNAVAILABLE_REASONS).describe(
16188
+ "Why the hotel has no offers: sold_out (nothing left for the stay), no_matching_offers (the filters left none), nationality_restricted (the hotel sells this stay only to guests of some nationalities; Fortrip can't book it), offers_unreadable (its offers came back incomplete or inconsistent), not_found (Fortrip has no bookable hotel with this hotelId), supplier_unavailable (offers couldn't be fetched this time; try again), stay_in_past (check-in has passed in the hotel's time zone)."
16189
+ ),
16161
16190
  omitted: omitted.nullable()
16162
16191
  })
16163
16192
  )
@@ -16184,6 +16213,7 @@ var PAYMENT_STATUSES = [
16184
16213
  ];
16185
16214
  var CANCEL_REASONS = [
16186
16215
  "cancellable",
16216
+ "unpaid",
16187
16217
  "already_cancelled",
16188
16218
  "in_progress",
16189
16219
  "not_confirmed",
@@ -16216,6 +16246,38 @@ var paymentHandler = openObject({
16216
16246
  business_profile: external_exports.string()
16217
16247
  })
16218
16248
  });
16249
+ var paymentMethod = openUnion("id", [
16250
+ openObject({
16251
+ id: external_exports.literal("stripe_shared_payment_token"),
16252
+ handler: paymentHandler.describe("The com.stripe.payments handler, which takes the token."),
16253
+ limits: openObject({
16254
+ maxAmount: external_exports.number().int().describe("Request the token for at least this amount, in cents; a token that allows less can't pay."),
16255
+ currency: external_exports.string().describe("The token's currency, lowercase as Stripe takes it: usd."),
16256
+ expiresAt: instant.describe(
16257
+ "Request the token valid until at least this time; the order can't be paid after it."
16258
+ )
16259
+ }).describe("What the shared payment token for pay_order must allow.")
16260
+ }).describe(
16261
+ `A Stripe shared payment token, through pay_order's sharedPaymentToken or payment. The entry is absent when a token can't pay the order: over $${LIMITS.tokenPaymentMaxUsd}, not charged in USD, an order started on the Fortrip website, a negotiated price, under ${LIMITS.payMinMinutesLeft} minutes left, ${LIMITS.tokensPerOrder} tokens tried, a token payment is under way, an Alipay or WeChat Pay payment is open, or token payment isn't offered for this order.`
16262
+ ),
16263
+ openObject({
16264
+ id: external_exports.literal("stripe_alipay_wechat_pay"),
16265
+ open: external_exports.boolean().describe("Whether pay_order has opened an Alipay or WeChat Pay payment on this order."),
16266
+ current: openEnum(["wechat_pay", "alipay"]).nullable().describe("Which of the two the payment is on now; null until it is open."),
16267
+ wechatPay: openObject({
16268
+ qrData: external_exports.string().nullable().describe(
16269
+ "The WeChat Pay code's content, to draw as a QR code; null when there is no live code (open wechatPay.url for one)."
16270
+ ),
16271
+ qrImageUrl: external_exports.string().nullable().describe("A 480 px PNG of the same code."),
16272
+ url: external_exports.string().describe("A link, on fortrip.ai, for the user to pay with WeChat Pay; anyone holding it can pay.")
16273
+ }).nullable().describe("The WeChat Pay code and link; null until the payment is open."),
16274
+ alipay: openObject({
16275
+ url: external_exports.string().describe("A link, on fortrip.ai, for the user to pay with Alipay; anyone holding it can pay.")
16276
+ }).nullable().describe("The Alipay link; null until the payment is open.")
16277
+ }).describe(
16278
+ "Paying with Alipay or WeChat Pay: pass method stripe_alipay_wechat_pay to pay_order to open it. The entry is absent when the order can't be paid this way and none is open."
16279
+ )
16280
+ ]);
16219
16281
  var orderReference = external_exports.string().regex(/^FT-[2-9A-HJ-NP-Z]{6}$/);
16220
16282
  var hotelItem = openObject({
16221
16283
  type: external_exports.literal("hotel"),
@@ -16232,7 +16294,9 @@ var hotelItem = openObject({
16232
16294
  beds: localizedText.nullable()
16233
16295
  }),
16234
16296
  meals,
16235
- cancellation,
16297
+ cancellation: cancellation.describe(
16298
+ "The terms the order was made on, read at asOf; cancel says whether it can be cancelled now."
16299
+ ),
16236
16300
  payAtProperty,
16237
16301
  confirmationNumber: external_exports.string().nullable()
16238
16302
  })
@@ -16240,70 +16304,46 @@ var hotelItem = openObject({
16240
16304
  var order = openObject({
16241
16305
  orderId,
16242
16306
  reference: orderReference,
16243
- status: openEnum(ORDER_STATUSES),
16307
+ status: openEnum(ORDER_STATUSES).describe(
16308
+ "awaiting_payment: unpaid, nothing charged; payable until payment.expiresAt. expired: not paid; the time ran out or the order was closed. Nothing charged. confirming: paid or held, the booking is with the hotel. confirmed: the hotel confirmed and the payment is charged. failed: no stay was booked; payment.status says what became of the money. cancelling, then cancelled: a cancellation under the terms. needs_attention: a person at Fortrip has to resolve it."
16309
+ ),
16244
16310
  createdAt: instant,
16245
16311
  updatedAt: instant,
16246
16312
  items: external_exports.array(openUnion("type", [hotelItem])).min(1),
16247
- price: openObject({ total: money }),
16313
+ price: openObject({
16314
+ total: money.describe(
16315
+ "The whole stay for all rooms, in payment.chargeCurrency: what paying charges, or once paid what was charged. Fees payable at the property are not in it."
16316
+ )
16317
+ }),
16248
16318
  payment: openObject({
16249
16319
  status: openEnum(PAYMENT_STATUSES),
16250
16320
  url: external_exports.string().nullable().describe(
16251
- "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."
16321
+ "The payment page, on fortrip.ai; it continues to the payment provider. With requiresSignIn false anyone holding it can pay; with requiresSignIn true (an order started on the Fortrip website) it continues to the Fortrip booking page, where only the signed-in owner can pay. null while a payment is held (authorized) or when the order isn't awaiting payment, or, while it is and its payment is unpaid, when the link couldn't be read this time: read the order again."
16252
16322
  ),
16253
16323
  requiresSignIn: external_exports.boolean(),
16254
- expiresAt: instant.nullable(),
16255
- chargeCurrency: external_exports.string(),
16256
- localCurrencyAtCheckout: external_exports.boolean(),
16257
- localCharge: money.nullable(),
16258
- /** The ways to pay other than `url`, while the order can be paid that
16259
- * way: a `com.stripe.payments` handler takes a shared payment token
16260
- * through `pay_order`. Empty when there is none. */
16261
- handlers: external_exports.array(paymentHandler).describe(
16262
- "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."
16324
+ expiresAt: instant.nullable().describe(
16325
+ "When the time to pay ends: an order unpaid by then expires, with nothing charged. null unless status is awaiting_payment."
16263
16326
  ),
16264
- /** What a payment credential for `pay_order` must allow, with
16265
- * `handlers`: at least `maxAmount`, in minor units (cents) of
16266
- * `currency`, lowercase as Stripe takes it, and valid until at least
16267
- * `expiresAt`, past which the order can't be paid. `null` when
16268
- * `handlers` is empty. */
16269
- credentialLimits: openObject({
16270
- maxAmount: external_exports.number().int().describe("Request the token for at least this amount, in cents; a token that allows less can't pay."),
16271
- currency: external_exports.string().describe("The token's currency, lowercase as Stripe takes it: usd."),
16272
- expiresAt: instant.describe(
16273
- "Request the token valid until at least this time; the order can't be paid after it."
16274
- )
16275
- }).nullable().describe(
16276
- "What the shared payment token for pay_order must allow. null exactly when handlers is []."
16327
+ chargeCurrency: external_exports.string().describe(
16328
+ "USD or CNY: the currency of the offer the order was made from. An order made on the Fortrip website may be in another currency."
16277
16329
  ),
16278
- /** Paying with Alipay or WeChat Pay through `pay_order`'s `method`.
16279
- * `null` when it is neither offered for the order nor open on it. */
16280
- wallets: openObject({
16281
- open: external_exports.boolean().describe("Whether pay_order has opened a wallet payment on this order."),
16282
- current: openEnum(["wechat_pay", "alipay"]).nullable().describe("The wallet the payment is on now; null until it is open."),
16283
- wechatPay: openObject({
16284
- qrData: external_exports.string().nullable().describe(
16285
- "The WeChat Pay code's content, to draw as a QR code; null when there is no live code (open wechatPay.url for one)."
16286
- ),
16287
- qrImageUrl: external_exports.string().nullable().describe("A 480 px PNG of the same code."),
16288
- url: external_exports.string().describe("A link, on fortrip.ai, for the user to pay with WeChat Pay; anyone holding it can pay.")
16289
- }).nullable().describe("The WeChat Pay code and link; null until the payment is open."),
16290
- alipay: openObject({
16291
- url: external_exports.string().describe("A link, on fortrip.ai, for the user to pay with Alipay; anyone holding it can pay.")
16292
- }).nullable().describe("The Alipay link; null until the payment is open.")
16293
- }).nullable().describe(
16294
- "Paying with Alipay or WeChat Pay: pass method alipay_wechat_pay to pay_order to open it. null when the order can't be paid this way and none is open."
16330
+ localCurrencyAtCheckout: external_exports.boolean().describe(
16331
+ "Whether paying by url may charge the card in its own currency, converted by Stripe; false once paid by token, Alipay or WeChat Pay; always false on a CNY order."
16332
+ ),
16333
+ localCharge: money.nullable().describe(
16334
+ "What the card was charged in its own currency, when Stripe converted the total; otherwise null. Always null on a CNY order."
16335
+ ),
16336
+ methods: external_exports.array(paymentMethod).describe(
16337
+ "What pay_order accepts for this order now, by id. [] means: give the user payment.url, when it isn't null."
16295
16338
  )
16296
16339
  }),
16297
- /** Whether the user can cancel the order now and, when they can, its
16298
- * penalty under the accepted terms (read a minute ahead) and the refund,
16299
- * what was paid less the penalty, both in the charge currency. */
16300
16340
  cancel: openObject({
16301
- available: external_exports.boolean().describe("Whether the user can cancel the order now."),
16341
+ available: external_exports.boolean().describe("Whether the user can cancel the order now, or, unpaid (reason unpaid), close it."),
16302
16342
  reason: openEnum(CANCEL_REASONS).describe(
16303
- "cancellable when it can be cancelled now; otherwise why not."
16343
+ "cancellable: a paid order can be cancelled now; unpaid: an unpaid order can be closed; otherwise why not."
16304
16344
  ),
16305
16345
  penalty: money.nullable().describe(
16306
- "The penalty if cancelled now, under the accepted terms, in the charge currency; null when not stated."
16346
+ "The penalty if cancelled now, under the accepted terms, in the charge currency; null when not stated, except on an unpaid order (reason unpaid), where null means closing it charges nothing."
16307
16347
  ),
16308
16348
  refund: money.nullable().describe(
16309
16349
  "What a cancellation now refunds: what was paid less the penalty, in the charge currency; null when not stated."
@@ -16331,24 +16371,90 @@ var offerChange = openUnion("field", [
16331
16371
  change("pay_at_property", payAtProperty)
16332
16372
  ]);
16333
16373
 
16374
+ // ../contract/src/paths.ts
16375
+ var PUBLIC_ORIGINS = {
16376
+ api: "https://api.fortrip.ai",
16377
+ mcp: "https://mcp.fortrip.ai"
16378
+ };
16379
+ var API = {
16380
+ me: "/v1/me",
16381
+ authConfig: "/v1/auth/config",
16382
+ hotelSearch: "/v1/hotels/search",
16383
+ hotelOffers: "/v1/hotels/offers",
16384
+ orders: "/v1/orders",
16385
+ hotel(id, opts) {
16386
+ const query = [];
16387
+ if (opts?.rooms) query.push("include=rooms");
16388
+ if (opts?.locale) query.push(`locale=${opts.locale}`);
16389
+ return `/v1/hotels/${encodeURIComponent(id)}${query.length ? `?${query.join("&")}` : ""}`;
16390
+ },
16391
+ order(id, opts) {
16392
+ return `/v1/orders/${encodeURIComponent(id)}${opts?.locale ? `?locale=${opts.locale}` : ""}`;
16393
+ },
16394
+ orderCancel(id) {
16395
+ return `/v1/orders/${encodeURIComponent(id)}/cancel`;
16396
+ },
16397
+ orderPay(id) {
16398
+ return `/v1/orders/${encodeURIComponent(id)}/pay`;
16399
+ }
16400
+ };
16401
+ var MCP_PATH = "/";
16402
+ var MCP_SERVER_URL = `${PUBLIC_ORIGINS.mcp}${MCP_PATH}`;
16403
+
16404
+ // ../contract/src/routes.ts
16405
+ var route = (method, path, queryFields = []) => ({
16406
+ method,
16407
+ path,
16408
+ pathFields: [...path.matchAll(/\{(\w+)\}/g)].map((match) => match[1]),
16409
+ queryFields
16410
+ });
16411
+ var HTTP_ROUTES = {
16412
+ search_hotels: route("POST", "/v1/hotels/search"),
16413
+ get_hotel: route("GET", "/v1/hotels/{hotelId}", ["include", "locale"]),
16414
+ get_hotel_offers: route("POST", "/v1/hotels/offers"),
16415
+ book_hotel: route("POST", "/v1/orders"),
16416
+ get_order: route("GET", "/v1/orders/{orderId}", ["locale"]),
16417
+ list_orders: route("GET", "/v1/orders", ["cursor", "limit", "locale"]),
16418
+ cancel_order: route("POST", "/v1/orders/{orderId}/cancel"),
16419
+ pay_order: route("POST", "/v1/orders/{orderId}/pay")
16420
+ };
16421
+ var ACCOUNT_ROUTES = {
16422
+ me: route("GET", "/v1/me"),
16423
+ authConfig: route("GET", "/v1/auth/config")
16424
+ };
16425
+ function routePath(route2, input) {
16426
+ const path = route2.path.replace(
16427
+ /\{(\w+)\}/g,
16428
+ (_, field) => encodeURIComponent(String(input[field]))
16429
+ );
16430
+ const query = new URLSearchParams();
16431
+ for (const field of route2.queryFields) {
16432
+ if (input[field] !== void 0) query.set(field, String(input[field]));
16433
+ }
16434
+ const text2 = query.toString();
16435
+ return text2 ? `${path}?${text2}` : path;
16436
+ }
16437
+
16334
16438
  // ../contract/src/tools.ts
16335
16439
  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.";
16336
16440
  var CALLS = {
16337
16441
  mcp: {
16338
16442
  cancel: "call cancel_order",
16339
- penalty: 'Pass maximumPenalty as the number in cancel.penalty.amount ("120.00" \u2192 120).',
16443
+ penalty: "Pass maximumPenalty as cancel.penalty, exactly as returned.",
16444
+ close: "call cancel_order",
16340
16445
  pay: "call pay_order",
16341
- payWallet: " with method alipay_wechat_pay",
16446
+ payWallet: " with method stripe_alipay_wechat_pay",
16342
16447
  get: "call get_order",
16343
16448
  poll: "poll get_order",
16344
16449
  payWith: "call pay_order with it and the order's price.total",
16345
16450
  paid: "pay_order"
16346
16451
  },
16347
16452
  cli: {
16348
- cancel: "run `fortrip orders cancel <orderId> --max-penalty <n>`",
16453
+ cancel: "run `fortrip orders cancel <orderId> --max-penalty <amount>`",
16454
+ close: "run `fortrip orders cancel <orderId> --close`",
16349
16455
  penalty: "Pass the penalty's amount as --max-penalty (120.00 for a penalty of USD 120.00).",
16350
16456
  pay: "run `fortrip orders pay`",
16351
- payWallet: " with --wallet",
16457
+ payWallet: " with --method stripe_alipay_wechat_pay",
16352
16458
  get: "run `fortrip orders get <orderId>`",
16353
16459
  poll: "poll it with `fortrip orders get <orderId>`",
16354
16460
  payWith: "run `fortrip orders pay <orderId> --token <spt_\u2026> --total <total>` with the token and the order's total",
@@ -16362,12 +16468,12 @@ function cancelNextStep(surface) {
16362
16468
  var CANCEL_NEXT_STEP = cancelNextStep("mcp");
16363
16469
  function payNextStep(surface) {
16364
16470
  const c = CALLS[surface];
16365
- 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.`;
16471
+ 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.methods has the stripe_shared_payment_token entry. 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 that entry's handler config.business_profile and its limits (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.`;
16366
16472
  }
16367
16473
  var PAY_NEXT_STEP = payNextStep("mcp");
16368
16474
  function walletNextStep(surface) {
16369
16475
  const c = CALLS[surface];
16370
- return `Before you ${c.pay}${c.payWallet}, show the user the order's total in USD, the stay (hotel, room, dates, rooms and guests per room) and every term (meals, cancellation, fees payable at the property), then ask them to confirm, and wait for a clear yes. Then show payment.wallets: the WeChat code as an image if you can, and both links. The user pays once, by one of them. Alipay and WeChat Pay charge at once; if the hotel can't confirm, the payment is refunded in full. Then ${c.poll}.`;
16476
+ return `Before you ${c.pay}${c.payWallet}, 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 ask them to confirm, and wait for a clear yes. Then show the stripe_alipay_wechat_pay entry of payment.methods: the WeChat code as an image if you can, and both links. The user pays once, by one of them. Alipay and WeChat Pay charge at once; if the hotel can't confirm, the payment is refunded in full. Then ${c.poll}.`;
16371
16477
  }
16372
16478
  var WALLET_NEXT_STEP = walletNextStep("mcp");
16373
16479
  var nextStep = external_exports.string().optional().describe(
@@ -16388,14 +16494,6 @@ var READ = {
16388
16494
  };
16389
16495
  var READ_OWN = { ...READ, openWorldHint: false };
16390
16496
  var TOOLS = [
16391
- {
16392
- name: "get_planning_guide",
16393
- title: "Get hotel planning guide",
16394
- description: `Returns Fortrip's planning guide for a request that is more than one hotel for fixed dates (flexible dates, a budget, split stays, several destinations, "find me the best"): what to ask the user, which results count as evidence, how to rank and how to present options.`,
16395
- annotations: READ_OWN,
16396
- input: null,
16397
- output: null
16398
- },
16399
16497
  {
16400
16498
  name: "search_hotels",
16401
16499
  title: "Search hotels",
@@ -16406,7 +16504,7 @@ var TOOLS = [
16406
16504
  },
16407
16505
  {
16408
16506
  name: "get_hotel",
16409
- title: "Get hotel details",
16507
+ title: "Hotel details",
16410
16508
  description: `One hotel's catalogue facts: names, address, location, time zone, check-in and check-out times, the full description, every policy and the amenities, and its rooms with include: "rooms". "Not listed" is not "no". No prices or availability: get_hotel_offers has those.`,
16411
16509
  annotations: READ,
16412
16510
  input: getHotelInput,
@@ -16414,15 +16512,15 @@ var TOOLS = [
16414
16512
  },
16415
16513
  {
16416
16514
  name: "get_hotel_offers",
16417
- title: "Get live hotel offers",
16418
- description: `Live, bookable offers for up to ${LIMITS.offersHotels} hotels and one stay. Every room in stay.rooms must have the same party: for different parties, call once per party. Each offer has the room, the meals included, price.total in USD for the whole stay and every room (what is charged), fees payable at the property, the cancellation terms with times in UTC and the hotel's time zone, the confirmation mode, and an offerId for book_hotel that expires at expiresAt. Hotels with nothing to offer are listed under unavailable with the reason. Up to limitPerHotel offers per hotel, default ${LIMITS.offersPerHotelDefault}, chosen for a spread of choices in this order while room remains: the cheapest offer, the cheapest that can be cancelled free, the cheapest with breakfast, the cheapest of each other room, then the rest by price; listed cheapest first.`,
16515
+ title: "Live offers",
16516
+ description: `Live, bookable offers for up to ${LIMITS.offersHotels} hotels and one stay. Every room in stay.rooms must have the same party: for different parties, call once per party. Each offer has the room, the meals included, price.total, in the request's currency, for the whole stay and every room (what is charged), fees payable at the property, the cancellation terms with times in UTC and the hotel's time zone, the confirmation mode, and an offerId for book_hotel that expires at expiresAt. Hotels with nothing to offer are listed under unavailable with the reason. Up to limitPerHotel offers per hotel, default ${LIMITS.offersPerHotelDefault}, chosen for a spread of choices in this order while room remains: the cheapest offer, the cheapest that can be cancelled free, the cheapest with breakfast, the cheapest of each other room, then the rest by price; listed cheapest first.`,
16419
16517
  annotations: READ,
16420
16518
  input: hotelOffersInput,
16421
16519
  output: hotelOffersResult
16422
16520
  },
16423
16521
  {
16424
16522
  name: "book_hotel",
16425
- title: "Create hotel order and payment link",
16523
+ title: "Create order",
16426
16524
  description: `Order one offer from get_hotel_offers. The answer is an unpaid order with a payment link: status awaiting_payment, the total, the stay and its terms, and payment.url, a Fortrip page to pay on. Nothing is charged until the order is paid, on that page or with pay_order (or Alipay/WeChat Pay); 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.`,
16427
16525
  annotations: {
16428
16526
  readOnlyHint: false,
@@ -16452,7 +16550,7 @@ var TOOLS = [
16452
16550
  {
16453
16551
  name: "cancel_order",
16454
16552
  title: "Cancel order",
16455
- 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.`,
16553
+ description: `Cancel a paid order under its terms, or close an unpaid one. Paid (cancel.reason cancellable): the hotel booking is cancelled and cancel.refund is refunded. ${CANCEL_NEXT_STEP} Penalty now above maximumPenalty: cancellation_changed, nothing changed; ask again. Then poll get_order: cancelling, then cancelled. Hotel refused: confirmed, reason refused. Unpaid (cancel.reason unpaid): close it only once the user says they no longer want it, without maximumPenalty; nothing is charged; it becomes expired. Paid meanwhile: the answer is the paid order or invalid_request; then cancel only under cancel.penalty, with the user's yes. payment_in_progress: read it again shortly. Repeat calls answer the order as it is.`,
16456
16554
  annotations: {
16457
16555
  readOnlyHint: false,
16458
16556
  idempotentHint: true,
@@ -16464,8 +16562,8 @@ var TOOLS = [
16464
16562
  },
16465
16563
  {
16466
16564
  name: "pay_order",
16467
- title: "Pay order by token or Alipay/WeChat Pay",
16468
- description: `Pay an order without its link, by shared payment token or Alipay/WeChat Pay (method alipay_wechat_pay). Token: only if payment.handlers isn't empty and you can request one from the user's Link wallet (US and Canadian accounts); never ask the user for one. 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. Token: request it with config.business_profile and payment.credentialLimits; pass it with price.total. Wallet: pass method, price.total; show payment.wallets (WeChat code as an image if you can, both links); they pay once by either; a code lasts ${LIMITS.wechatCodeMinutes} minutes; then the WeChat link opens a new one, or call again. Pay one way only: payment.url or pay_order. On success payment.url stops working; on failure it stays open. Then poll get_order. payment_total_changed: confirm details.total, retry. payment_credential_invalid: new token. service_unavailable: retry. Else payment.url. A token pays one order only.`,
16565
+ title: "Pay order",
16566
+ description: `Pay an order without its link, by one of its payment.methods: a shared payment token, or Alipay/WeChat Pay (method stripe_alipay_wechat_pay). Token: only if you can request one from the user's Link wallet (US and Canadian accounts); never ask the user for one. First show the user the total and currency, the stay and every term (meals, cancellation, fees payable at the property), ask them to confirm and wait for a clear yes. Token: request it with the entry's handler config.business_profile and limits; pass it with price.total. Wallet: pass method, price.total; show the wallet entry (WeChat code as an image if you can, both links); they pay once by either; a code lasts ${LIMITS.wechatCodeMinutes} minutes; then the WeChat link opens a new one, or call again. Pay one way only: payment.url or pay_order. Success closes payment.url; failure leaves it open. Then poll get_order. payment_total_changed: confirm details.total, retry. payment_credential_invalid: new token. service_unavailable: retry. Else payment.url. A token pays one order.`,
16469
16567
  annotations: {
16470
16568
  readOnlyHint: false,
16471
16569
  idempotentHint: true,
@@ -16507,6 +16605,7 @@ var ERROR_CODES = {
16507
16605
  stay_unsupported: { status: [422], retryable: false },
16508
16606
  stay_in_past: { status: [422], retryable: false },
16509
16607
  offer_unavailable: { status: [422], retryable: false },
16608
+ currency_unavailable: { status: [422], retryable: false },
16510
16609
  rate_limited: { status: [429], retryable: true },
16511
16610
  ordering_paused: { status: [503], retryable: true },
16512
16611
  service_unavailable: { status: [503], retryable: true },
@@ -16600,6 +16699,7 @@ var ERROR_DETAILS = {
16600
16699
  offerId,
16601
16700
  reason: openEnum(["sold_out", "refused"])
16602
16701
  }),
16702
+ currency_unavailable: openObject({ currency: external_exports.string() }),
16603
16703
  rate_limited: openObject({
16604
16704
  scope: openEnum([
16605
16705
  "search",
@@ -16789,10 +16889,7 @@ function roomText(r) {
16789
16889
  }
16790
16890
  function offerLine(o) {
16791
16891
  const p = o.price;
16792
- let price = `${money2(p.total)} total (${money2(p.perNightAllRooms)} per night, all rooms)`;
16793
- if (p.approx) {
16794
- price += ` \u2248 ${money2(p.approx.total)} (${money2(p.approx.perNightAllRooms)} per night), exchange rate of ${p.approx.rateDate}`;
16795
- }
16892
+ const price = `${money2(p.total)} total (${money2(p.perNightAllRooms)} per night, all rooms)`;
16796
16893
  return [
16797
16894
  `${o.offerId}${o.type === "hotel" ? "" : ` (${o.type})`}`,
16798
16895
  `${plural(o.hotel.roomCount, "room")}: ${roomText(o.hotel.room)}`,
@@ -16852,9 +16949,12 @@ function renderOffers(r, surface = "mcp") {
16852
16949
  }
16853
16950
 
16854
16951
  // ../contract/src/render/order.ts
16952
+ function methodOf(o, id) {
16953
+ return o.payment.methods.find((m) => m.id === id);
16954
+ }
16855
16955
  var ORDER_STATUS_WORDS = {
16856
16956
  awaiting_payment: "awaiting payment",
16857
- expired: "expired (not paid in time)",
16957
+ expired: "not paid: the time ran out or it was closed",
16858
16958
  confirming: "confirming with the hotel",
16859
16959
  confirmed: "confirmed",
16860
16960
  failed: "failed",
@@ -16873,6 +16973,7 @@ var PAYMENT_WORDS = {
16873
16973
  var SUPPORT = `for help, the user emails ${SUPPORT_EMAIL} with the order's reference`;
16874
16974
  var CANCEL_REASON_WORDS = {
16875
16975
  cancellable: "it can be cancelled",
16976
+ unpaid: "it isn't paid: it can be closed if the user no longer wants it",
16876
16977
  already_cancelled: "it is already cancelled",
16877
16978
  in_progress: "a cancellation is in progress",
16878
16979
  not_confirmed: "only a confirmed order that is paid can be cancelled",
@@ -16916,24 +17017,22 @@ function paymentLines(o, surface) {
16916
17017
  p.requiresSignIn ? "the user signs in to Fortrip to pay" : "no sign-in needed"
16917
17018
  ].filter(Boolean);
16918
17019
  lines.push(`Payment link (${about.join("; ")}): ${p.url}`);
16919
- } else if (o.status === "awaiting_payment") {
17020
+ } else if (o.status === "awaiting_payment" && p.status === "unpaid") {
16920
17021
  lines.push("Payment link: could not be read this time; read this order again for it.");
16921
17022
  }
16922
- if (p.handlers.length > 0) lines.push(handlersLine(o, surface));
16923
- if (p.wallets) lines.push(...walletLines(p.wallets, surface));
16924
- lines.push(cancelLine(o));
17023
+ const token = methodOf(o, "stripe_shared_payment_token");
17024
+ if (token) lines.push(tokenLine(o, token, surface));
17025
+ const wallet = methodOf(o, "stripe_alipay_wechat_pay");
17026
+ if (wallet) lines.push(...walletLines(wallet, surface));
17027
+ lines.push(cancelLine(o, surface));
16925
17028
  lines.push(`Manage: ${o.manageUrl}`);
16926
17029
  return lines;
16927
17030
  }
16928
- function handlersLine(o, surface) {
16929
- const { handlers, credentialLimits: limits } = o.payment;
17031
+ function tokenLine(o, token, surface) {
17032
+ const { handler: h, limits } = token;
16930
17033
  const pay = surface === "cli" ? `\`fortrip orders pay ${o.orderId} --token <spt_\u2026> --total ${o.price.total.amount}\`` : "pay_order";
16931
- const shown = handlers.map(
16932
- (h) => `${h.type} (handler ${h.id}, business_profile ${h.config.business_profile})`
16933
- );
16934
- const limit = limits ? `; token limits: maxAmount ${limits.maxAmount} (cents), currency ${limits.currency}, expiresAt ${limits.expiresAt}` : "";
16935
17034
  return [
16936
- `Pay without the link: ${pay} with a shared payment token via ${shown.join(", ")}${limit}.`,
17035
+ `Pay without the link: ${pay} with a shared payment token via ${h.type} (handler ${h.id}, business_profile ${h.config.business_profile}); token limits: maxAmount ${limits.maxAmount} (cents), currency ${limits.currency}, expiresAt ${limits.expiresAt}.`,
16937
17036
  "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.",
16938
17037
  `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"}.`
16939
17038
  ].join(" ");
@@ -16941,7 +17040,7 @@ function handlersLine(o, surface) {
16941
17040
  function walletLines(w, surface) {
16942
17041
  const c = CALLS[surface];
16943
17042
  if (!w.open) {
16944
- const pay = surface === "cli" ? "run `fortrip orders pay <orderId> --wallet --total <total>`" : "call pay_order with method alipay_wechat_pay and the order's price.total";
17043
+ const pay = surface === "cli" ? "run `fortrip orders pay <orderId> --method stripe_alipay_wechat_pay --total <total>`" : "call pay_order with method stripe_alipay_wechat_pay and the order's price.total";
16945
17044
  return [`Pay with Alipay or WeChat Pay: ${pay}.`];
16946
17045
  }
16947
17046
  const lines = [];
@@ -16958,9 +17057,13 @@ function walletLines(w, surface) {
16958
17057
  );
16959
17058
  return lines;
16960
17059
  }
16961
- function cancelLine(o) {
17060
+ function cancelLine(o, surface) {
16962
17061
  const c = o.cancel;
17062
+ if (c.available && c.reason === "unpaid") {
17063
+ return `Cancel: can be closed now, nothing is charged; close it only if the user says they no longer want it (${CALLS[surface].close})`;
17064
+ }
16963
17065
  if (o.status === "awaiting_payment" && !c.available && c.reason === "not_confirmed") {
17066
+ if (!o.payment.requiresSignIn) return "Cancel: not now: a payment is under way; read the order again shortly";
16964
17067
  const at = o.payment.expiresAt === null ? "" : ` at ${when(o.payment.expiresAt, null)}`;
16965
17068
  return `Cancel: not needed: an unpaid order expires unpaid${at}`;
16966
17069
  }
@@ -17004,7 +17107,7 @@ var CENTER_BASES2 = {
17004
17107
  seat: "the seat",
17005
17108
  capital: "the capital",
17006
17109
  busiest_settlement: "the settlement with the most hotels",
17007
- hub: "the locality's hub",
17110
+ hub: "the locality",
17008
17111
  point: "its location"
17009
17112
  };
17010
17113
  function radiusWords(meters, source) {
@@ -17071,7 +17174,7 @@ function countsLine(r) {
17071
17174
  if (c.excludedNoFacilityData !== null) {
17072
17175
  parts.push(`${num(c.excludedNoFacilityData)} left out for listing no facilities`);
17073
17176
  }
17074
- if (c.withinMaxRadius !== null) parts.push(`${num(c.withinMaxRadius)} within 80 km`);
17177
+ if (c.withinMaxRadius !== null) parts.push(`${num(c.withinMaxRadius)} within ${LIMITS.radiusMetersMax / 1e3} km`);
17075
17178
  if (c.textAnywhere !== null) {
17076
17179
  parts.push(`${num(c.textAnywhere)} match the text anywhere in ${country}`);
17077
17180
  }
@@ -17114,9 +17217,6 @@ function priceWords(h, status) {
17114
17217
  return status === "ok" ? "no indicative price" : "price unavailable this time";
17115
17218
  }
17116
17219
  let text2 = `from ${money2(p.fromPerRoomNight)}/room-night (${money2(p.fromPerRoomStay)} per room for the stay)`;
17117
- if (p.approx) {
17118
- text2 += ` \u2248 ${money2(p.approx.fromPerRoomNight)}/room-night (${money2(p.approx.fromPerRoomStay)}), exchange rate of ${p.approx.rateDate}`;
17119
- }
17120
17220
  if (p.kind !== "indicative" || p.basis !== "lowest_unit") {
17121
17221
  text2 += ` [${p.kind}, ${p.basis}]`;
17122
17222
  }
@@ -17225,13 +17325,13 @@ function ambiguous(d, surface) {
17225
17325
  for (const c of d.candidates) {
17226
17326
  const other = [c.names.en, c.names.zh].find((n) => n && n !== c.name);
17227
17327
  const where = [c.region && `${c.region.name} ${c.region.placeId}`, c.countryCode].filter(Boolean).join(", ");
17228
- const hotels = c.hotels.scope === "area" ? `${plural(c.hotels.count, "hotel")} in the area` : c.hotels.radiusMeters === null ? plural(c.hotels.count, "hotel") : `${plural(c.hotels.count, "hotel")} within ${km(c.hotels.radiusMeters)}`;
17328
+ const hotels2 = c.hotels.scope === "area" ? `${plural(c.hotels.count, "hotel")} in the area` : c.hotels.radiusMeters === null ? plural(c.hotels.count, "hotel") : `${plural(c.hotels.count, "hotel")} within ${km(c.hotels.radiusMeters)}`;
17229
17329
  lines.push(
17230
17330
  [
17231
17331
  `- ${c.name}${other ? ` (${other})` : ""} ${c.placeId}`,
17232
17332
  `${c.kind} in ${where}`,
17233
17333
  c.population === null ? "population not recorded" : `population ${num(c.population)}`,
17234
- hotels
17334
+ hotels2
17235
17335
  ].join(" \xB7 ")
17236
17336
  );
17237
17337
  }
@@ -17314,7 +17414,7 @@ function detailLines(e, surface) {
17314
17414
  ];
17315
17415
  case "payment_credential_invalid":
17316
17416
  return [
17317
- `The token ${label(CREDENTIAL_INVALID_WORDS, e.details.reason)}: request a new one with the order's payment.credentialLimits. Nothing was charged.`
17417
+ `The token ${label(CREDENTIAL_INVALID_WORDS, e.details.reason)}: request a new one with the limits of the order's stripe_shared_payment_token method. Nothing was charged.`
17318
17418
  ];
17319
17419
  case "payment_declined":
17320
17420
  return [
@@ -17336,6 +17436,8 @@ function detailLines(e, surface) {
17336
17436
  return [
17337
17437
  `Offer ${e.details.offerId}: ${label({ sold_out: "sold out", refused: "can no longer be booked" }, e.details.reason)}. Get fresh offers.`
17338
17438
  ];
17439
+ case "currency_unavailable":
17440
+ return [`Prices in ${e.details.currency} aren't available yet. Tell the user, and ask whether to see USD prices.`];
17339
17441
  case "rate_limited":
17340
17442
  return [`Limit reached for: ${e.details.scope}.`];
17341
17443
  case "supplier_unavailable":
@@ -17468,8 +17570,8 @@ ${raw(data)}`;
17468
17570
  return [
17469
17571
  text2,
17470
17572
  ORDER_TOOLS.has(tool) && holdsPaymentUrl(data) ? ORDER_NEXT_STEP : "",
17471
- ORDER_TOOLS.has(tool) && holdsHandlers(data) ? payNextStep(surface) : "",
17472
- ORDER_TOOLS.has(tool) && holdsWalletOffer(data) ? walletNextStep(surface) : "",
17573
+ ORDER_TOOLS.has(tool) && holdsMethod(data, isTokenMethod) ? payNextStep(surface) : "",
17574
+ ORDER_TOOLS.has(tool) && holdsMethod(data, isWalletOffer) ? walletNextStep(surface) : "",
17473
17575
  CANCEL_TOOLS.has(tool) && holdsCancellable(data) ? cancelNextStep(surface) : ""
17474
17576
  ].filter(Boolean).join("\n\n");
17475
17577
  }
@@ -17505,32 +17607,23 @@ function holdsPaymentUrl(value, seen = /* @__PURE__ */ new Set()) {
17505
17607
  }
17506
17608
  return Object.values(value).some((v) => holdsPaymentUrl(v, seen));
17507
17609
  }
17508
- function holdsHandlers(value, seen = /* @__PURE__ */ new Set()) {
17610
+ var isTokenMethod = (m) => m.id === "stripe_shared_payment_token";
17611
+ var isWalletOffer = (m) => m.id === "stripe_alipay_wechat_pay" && m.open === false;
17612
+ function holdsMethod(value, match, seen = /* @__PURE__ */ new Set()) {
17509
17613
  if (typeof value !== "object" || value === null || seen.has(value)) return false;
17510
17614
  seen.add(value);
17511
17615
  const payment = value.payment;
17512
- if (typeof payment === "object" && payment !== null && Array.isArray(payment.handlers) && payment.handlers.length > 0) {
17616
+ const methods = typeof payment === "object" && payment !== null ? payment.methods : void 0;
17617
+ if (Array.isArray(methods) && methods.some((m) => typeof m === "object" && m !== null && match(m))) {
17513
17618
  return true;
17514
17619
  }
17515
- return Object.values(value).some((v) => holdsHandlers(v, seen));
17516
- }
17517
- function holdsWalletOffer(value, seen = /* @__PURE__ */ new Set()) {
17518
- if (typeof value !== "object" || value === null || seen.has(value)) return false;
17519
- seen.add(value);
17520
- const payment = value.payment;
17521
- if (typeof payment === "object" && payment !== null) {
17522
- const wallets = payment.wallets;
17523
- if (typeof wallets === "object" && wallets !== null && wallets.open === false) {
17524
- return true;
17525
- }
17526
- }
17527
- return Object.values(value).some((v) => holdsWalletOffer(v, seen));
17620
+ return Object.values(value).some((v) => holdsMethod(v, match, seen));
17528
17621
  }
17529
17622
  function holdsCancellable(value, seen = /* @__PURE__ */ new Set()) {
17530
17623
  if (typeof value !== "object" || value === null || seen.has(value)) return false;
17531
17624
  seen.add(value);
17532
17625
  const cancel = value.cancel;
17533
- if (typeof cancel === "object" && cancel !== null && cancel.available === true) {
17626
+ if (typeof cancel === "object" && cancel !== null && cancel.available === true && cancel.reason !== "unpaid") {
17534
17627
  return true;
17535
17628
  }
17536
17629
  return Object.values(value).some((v) => holdsCancellable(v, seen));
@@ -17539,16 +17632,16 @@ function withConsent(tool, surface, text2, orders) {
17539
17632
  return [
17540
17633
  text2,
17541
17634
  orders.some((o) => o.payment.url !== null) ? ORDER_NEXT_STEP : "",
17542
- orders.some((o) => o.payment.handlers.length > 0) ? payNextStep(surface) : "",
17543
- orders.some((o) => o.payment.wallets?.open === false) ? walletNextStep(surface) : "",
17544
- CANCEL_TOOLS.has(tool) && orders.some((o) => o.cancel.available) ? cancelNextStep(surface) : ""
17635
+ orders.some((o) => methodOf(o, "stripe_shared_payment_token")) ? payNextStep(surface) : "",
17636
+ orders.some((o) => methodOf(o, "stripe_alipay_wechat_pay")?.open === false) ? walletNextStep(surface) : "",
17637
+ CANCEL_TOOLS.has(tool) && orders.some((o) => o.cancel.available && o.cancel.reason !== "unpaid") ? cancelNextStep(surface) : ""
17545
17638
  ].filter(Boolean).join("\n\n");
17546
17639
  }
17547
17640
 
17548
17641
  // ../contract/package.json
17549
17642
  var package_default = {
17550
17643
  name: "@fortrip/agent-contract",
17551
- version: "4.3.0",
17644
+ version: "5.0.0-rc.1",
17552
17645
  license: "Apache-2.0",
17553
17646
  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.",
17554
17647
  type: "module",
@@ -17571,7 +17664,10 @@ var package_default = {
17571
17664
  import: "./dist/regions.js"
17572
17665
  }
17573
17666
  },
17574
- files: ["dist", "NOTICE"],
17667
+ files: [
17668
+ "dist",
17669
+ "NOTICE"
17670
+ ],
17575
17671
  sideEffects: false,
17576
17672
  engines: {
17577
17673
  node: ">=22"
@@ -17616,70 +17712,6 @@ var authConfig = openObject({
17616
17712
  revocationEndpoint: external_exports.string()
17617
17713
  });
17618
17714
 
17619
- // ../contract/src/paths.ts
17620
- var PUBLIC_ORIGINS = {
17621
- api: "https://api.fortrip.ai",
17622
- mcp: "https://mcp.fortrip.ai"
17623
- };
17624
- var API = {
17625
- me: "/v1/me",
17626
- authConfig: "/v1/auth/config",
17627
- hotelSearch: "/v1/hotels/search",
17628
- hotelOffers: "/v1/hotels/offers",
17629
- orders: "/v1/orders",
17630
- hotel(id, opts) {
17631
- const query = [];
17632
- if (opts?.rooms) query.push("include=rooms");
17633
- if (opts?.locale) query.push(`locale=${opts.locale}`);
17634
- return `/v1/hotels/${encodeURIComponent(id)}${query.length ? `?${query.join("&")}` : ""}`;
17635
- },
17636
- order(id, opts) {
17637
- return `/v1/orders/${encodeURIComponent(id)}${opts?.locale ? `?locale=${opts.locale}` : ""}`;
17638
- },
17639
- orderCancel(id) {
17640
- return `/v1/orders/${encodeURIComponent(id)}/cancel`;
17641
- },
17642
- orderPay(id) {
17643
- return `/v1/orders/${encodeURIComponent(id)}/pay`;
17644
- }
17645
- };
17646
- var MCP_PATH = "/";
17647
- var MCP_SERVER_URL = `${PUBLIC_ORIGINS.mcp}${MCP_PATH}`;
17648
-
17649
- // ../contract/src/routes.ts
17650
- var route = (method, path, queryFields = []) => ({
17651
- method,
17652
- path,
17653
- pathFields: [...path.matchAll(/\{(\w+)\}/g)].map((match) => match[1]),
17654
- queryFields
17655
- });
17656
- var HTTP_ROUTES = {
17657
- search_hotels: route("POST", "/v1/hotels/search"),
17658
- get_hotel: route("GET", "/v1/hotels/{hotelId}", ["include", "locale"]),
17659
- get_hotel_offers: route("POST", "/v1/hotels/offers"),
17660
- book_hotel: route("POST", "/v1/orders"),
17661
- get_order: route("GET", "/v1/orders/{orderId}", ["locale"]),
17662
- list_orders: route("GET", "/v1/orders", ["cursor", "limit", "locale"]),
17663
- cancel_order: route("POST", "/v1/orders/{orderId}/cancel"),
17664
- pay_order: route("POST", "/v1/orders/{orderId}/pay")
17665
- };
17666
- var ACCOUNT_ROUTES = {
17667
- me: route("GET", "/v1/me"),
17668
- authConfig: route("GET", "/v1/auth/config")
17669
- };
17670
- function routePath(route2, input) {
17671
- const path = route2.path.replace(
17672
- /\{(\w+)\}/g,
17673
- (_, field) => encodeURIComponent(String(input[field]))
17674
- );
17675
- const query = new URLSearchParams();
17676
- for (const field of route2.queryFields) {
17677
- if (input[field] !== void 0) query.set(field, String(input[field]));
17678
- }
17679
- const text2 = query.toString();
17680
- return text2 ? `${path}?${text2}` : path;
17681
- }
17682
-
17683
17715
  // src/exit-codes.ts
17684
17716
  var EXIT = {
17685
17717
  ok: 0,
@@ -18697,13 +18729,16 @@ async function whoami(apiUrl, token) {
18697
18729
 
18698
18730
  export {
18699
18731
  LIMITS,
18732
+ CURRENCIES,
18700
18733
  COMMAND_GROUPS,
18701
18734
  COMMANDS,
18702
18735
  commandInvocation,
18703
18736
  GLOBAL_FLAGS,
18704
18737
  renderGuide,
18705
18738
  order,
18739
+ PUBLIC_ORIGINS,
18706
18740
  API,
18741
+ MCP_SERVER_URL,
18707
18742
  HTTP_ROUTES,
18708
18743
  routePath,
18709
18744
  TOOLS,
@@ -18720,8 +18755,6 @@ export {
18720
18755
  VERSION,
18721
18756
  isEnvelope,
18722
18757
  unwrap,
18723
- DEFAULT_API_URL,
18724
- DEFAULT_MCP_URL,
18725
18758
  resolveApiUrl,
18726
18759
  resolveMcpUrl,
18727
18760
  loadSession,