@fortrip/agent-contract 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FortripEngineering
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,39 @@
-# Temporary Holding Version
+# @fortrip/agent-contract
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The contract of Fortrip's agent API, `/api/agent/v1`: the limits, endpoint
+paths, error reasons and field rules that the Fortrip CLI (`fortrip`), the
+hosted MCP server and the store listings all share, so they cannot drift
+apart.
+
+It has one peer dependency, `zod` (`^4.4.0`), and runs anywhere
+ES2023 does. The package version follows the API: `1.x` serves
+`/api/agent/v1`.
+
+```ts
+import { API, LIMITS, containsCardNumber } from "@fortrip/agent-contract";
+
+API.search; // "/api/agent/v1/hotels/search"
+LIMITS.rooms; // 8
+```
+
+It exports:
+
+- `API`, `LIMITS`, `BOARD_CODES`, `CURRENCIES`, `SEARCH_SORTS` and
+  `ERROR_REASONS`: paths, limits and error reasons;
+- `searchHotelsInput`, `getHotelInput`, `getRatesInput` and
+  `createBookingInput`, the zod schemas of the requests, and `bookingResult`,
+  `meResult` and `authConfig`, those of responses;
+- `COMMANDS` and `GLOBAL_FLAGS`, the CLI's commands and flags, and `TOOLS`,
+  the MCP tools;
+- `renderGuide(surface, topic)`, the agent guide as Markdown for `"mcp"`,
+  `"claude-skill"` or `"cli"`;
+- field rules such as `containsCardNumber`, the guest-name rule and the date
+  helpers, and `CONTRACT_VERSION`.
+
+Browser code that only needs the guest-name rule (`GUEST_NAME_PATTERN`,
+`GUEST_NAME_TITLE`, `GUEST_NAME_MESSAGE`, `guestNameRe`, `normalizeGuestName`)
+can import it from `@fortrip/agent-contract/guest-name`. That module imports
+no package, so it does not pull in `zod` or the schemas the root entry builds
+at load. The root entry exports the same names.
+
+MIT licensed. Source: <https://github.com/FortripEngineering/fortrip/tree/main/packages/contract>.

package/dist/chunk-HR6L3RDB.js

@@ -0,0 +1,18 @@
+// src/guest-name.ts
+var CURLY_APOSTROPHES = /[‘’]/g;
+var CORE = "[A-Za-z][A-Za-z '\u2018\u2019.\\-]*";
+var GUEST_NAME_PATTERN = `\\s*|\\s*${CORE}\\s*`;
+var guestNameRe = new RegExp(`^${CORE}$`);
+var GUEST_NAME_TITLE = "Latin letters as in the passport \u2014 start with a letter; spaces, hyphens, apostrophes and periods are fine after that. Transliterate accents (M\xFCller \u2192 Mueller).";
+var GUEST_NAME_MESSAGE = "Guest names must use Latin letters as on the passport (e.g. ZHANG, Wei; M\xFCller \u2192 Mueller).";
+function normalizeGuestName(value) {
+  return value.replace(CURLY_APOSTROPHES, "'").replace(/\s+/g, " ").trim();
+}
+
+export {
+  GUEST_NAME_PATTERN,
+  guestNameRe,
+  GUEST_NAME_TITLE,
+  GUEST_NAME_MESSAGE,
+  normalizeGuestName
+};

package/dist/guest-name.d.ts

@@ -0,0 +1,71 @@
+/**
+ * What a guest name may contain.
+ *
+ * The old rule was `[A-Za-z\s-]+`, carrying the comment "the supplier only
+ * accepts Latin guest names". The supplier's booking endpoint actually types
+ * `firstName` / `lastName` as bare strings with NO character constraint —
+ * Latin is a convention its examples follow, not a documented rule. Evidence
+ * the old rule was never verified: `contactName`, which travels the same
+ * request, has never been pattern-checked at all.
+ *
+ * So the apostrophe and the period are back: `O'Brien`, `D'Angelo`,
+ * `St. John`, `Jr.` are ordinary passport spellings that we were rejecting
+ * before the supplier ever saw them. Curly apostrophes come in from phone
+ * keyboards and normalize to straight ones rather than being refused.
+ *
+ * Still refused: CJK, other non-Latin scripts, and accented Latin (José,
+ * Müller). Be clear about whose rule this is — **ours**. The supplier accepts
+ * CJK names outright: `伟`/`张` booked successfully against its sandbox on
+ * 2026-08-07. The old comment here claimed "the supplier only accepts Latin
+ * guest names" and that was simply false, in whole, not just in the
+ * apostrophe it also got wrong.
+ *
+ * We keep the restriction for a reason the supplier API can't speak to: the
+ * property reads these names at check-in, most of them can't render CJK, and
+ * passports carry an ASCII transliteration in the machine-readable zone (JOSE,
+ * MUELLER) — that is the spelling a front desk matches. So the model
+ * transliterates and the form asks the user to. If that trade is ever
+ * revisited, revisit it as a product decision about hotels, not as "restoring
+ * supplier parity" — parity already permits CJK.
+ */
+/**
+ * HTML `pattern` body — implicitly anchored by the browser, and applied to the
+ * RAW field value, which is why it is looser than `guestNameRe` rather than
+ * identical to it.
+ *
+ * Two things force the slack. Browsers skip `pattern` only when a value is the
+ * empty string, so `"   "` is validated — and a `CORE`-only pattern would
+ * refuse it. That breaks the reveal affordance outright: a user who opens a
+ * row, types a name, then deletes it leaving one stray space has no Remove
+ * button and no way forward, stranded on the payment screen by the very
+ * mechanism that was supposed to be the undo. Allowing an all-blank value
+ * hands that row to `collectGuestsFromForm`, which drops it — the undo works.
+ * Surrounding whitespace is allowed for the same reason a pasted `" Wei"`
+ * should not be rejected in the browser when `normalizeGuestName` would trim it
+ * server-side anyway (the old `[A-Za-z\s\-]+` accepted it; refusing it here
+ * would be a regression).
+ *
+ * The cost is deliberate: a required lead row holding only spaces passes the
+ * browser and is caught server-side ("Room 1 needs at least one guest name.").
+ * That trade favours the common case — stray whitespace while erasing — over
+ * the rare one, someone typing nothing but spaces into a required field.
+ */
+declare const GUEST_NAME_PATTERN = "\\s*|\\s*[A-Za-z][A-Za-z '\u2018\u2019.\\-]*\\s*";
+/** Server-side check, applied AFTER `normalizeGuestName`, so it sees no
+ *  surrounding whitespace and can be strict. Deliberately not derived from
+ *  `GUEST_NAME_PATTERN` — they validate different values at different stages.
+ *  `guest-name.test.ts` pins the relationship that actually matters: anything
+ *  the browser accepts is, once normalized, either empty or accepted here. */
+declare const guestNameRe: RegExp;
+/** Shown as the `title` on every guest-name input, so a rejected value
+ *  explains itself. Names the first-character rule because the pattern enforces
+ *  it and a Dutch `'t Hooft` would otherwise be refused with no explanation. */
+declare const GUEST_NAME_TITLE = "Latin letters as in the passport \u2014 start with a letter; spaces, hyphens, apostrophes and periods are fine after that. Transliterate accents (M\u00FCller \u2192 Mueller).";
+/** The server's answer to a name `guestNameRe` refuses: what to type
+ *  instead, for a caller that can't see the form's `title`. */
+declare const GUEST_NAME_MESSAGE = "Guest names must use Latin letters as on the passport (e.g. ZHANG, Wei; M\u00FCller \u2192 Mueller).";
+/** Collapse whitespace and straighten curly apostrophes. Applied server-side so
+ *  both booking surfaces store one spelling of the same name. */
+declare function normalizeGuestName(value: string): string;
+
+export { GUEST_NAME_MESSAGE, GUEST_NAME_PATTERN, GUEST_NAME_TITLE, guestNameRe, normalizeGuestName };

package/dist/guest-name.js

@@ -0,0 +1,14 @@
+import {
+  GUEST_NAME_MESSAGE,
+  GUEST_NAME_PATTERN,
+  GUEST_NAME_TITLE,
+  guestNameRe,
+  normalizeGuestName
+} from "./chunk-HR6L3RDB.js";
+export {
+  GUEST_NAME_MESSAGE,
+  GUEST_NAME_PATTERN,
+  GUEST_NAME_TITLE,
+  guestNameRe,
+  normalizeGuestName
+};

package/dist/index.d.ts

@@ -0,0 +1,422 @@
+import { z } from 'zod';
+export { GUEST_NAME_MESSAGE, GUEST_NAME_PATTERN, GUEST_NAME_TITLE, guestNameRe, normalizeGuestName } from './guest-name.js';
+
+/** Shown on a booking field that seems to hold a payment card number. */
+declare const CARD_NUMBER_MESSAGE = "This looks like a payment card number. Payment happens only on the payment page; if it isn't a card number, rewrite it.";
+/**
+ * Whether `text` holds a payment card number in one of the two ways people
+ * type one: 13–19 digits in a single run, or groups of four digits (the last
+ * 1–4) split by one space or one hyphen. It must start like a card (Mir
+ * 2200–2204, Mastercard 2221–2720, 3, 4, 5, 6, RuPay 81/82) and pass the
+ * Luhn check. Full-width digits count (NFKC).
+ *
+ * Deliberately narrow, because every looser rule flagged ordinary text: no
+ * joining across `/`, `.`, `_`, line breaks or double spaces (two phone
+ * numbers, a list of room numbers, one number per line), and no Amex-style
+ * 4-6-5 grouping (missed; a 15-digit Amex in one run is still caught). A
+ * card may start at any digit group, so a room number or date in front of it
+ * can't hide it. Right after `+` come a phone number's country code and
+ * number, so digits there count only from 16 on, too many for a phone.
+ *
+ * `minDigits` is the shortest card looked for. A phone field passes 16, so a
+ * phone isn't mistaken for a card there, at the cost of missing cards of
+ * 13–15 digits (Amex).
+ */
+declare function containsCardNumber(text: string, minDigits?: number): boolean;
+
+type ToolName = "get_planning_guide" | "search_hotels" | "get_hotel" | "get_rates" | "create_booking";
+interface ToolSpec {
+    name: ToolName;
+    title: string;
+    description: string;
+    annotations: {
+        readOnlyHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+        destructiveHint: boolean;
+    };
+    /** What the tool takes; `null` for a tool without arguments. */
+    input: z.ZodType | null;
+    /** What it answers with, when that is a schema; `null` otherwise. */
+    output: z.ZodType | null;
+}
+/** `getRatesInput` as the MCP tool takes it: the same, with its own default
+ *  for `maxRoomsPerHotel`. */
+declare const MCP_RATES_INPUT: z.ZodObject<{
+    hotelIds: z.ZodArray<z.ZodNumber>;
+    checkIn: z.ZodString;
+    checkOut: z.ZodString;
+    rooms: z.ZodNumber;
+    adults: z.ZodNumber;
+    childrenAges: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+    nationality: z.ZodOptional<z.ZodString>;
+    currency: z.ZodDefault<z.ZodEnum<{
+        CNY: "CNY";
+        USD: "USD";
+    }>>;
+    bookableOnly: z.ZodDefault<z.ZodBoolean>;
+    boardCodes: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        RO: "RO";
+        BB: "BB";
+        HB: "HB";
+        FB: "FB";
+        BL: "BL";
+        BD: "BD";
+        HBBL: "HBBL";
+        HBLD: "HBLD";
+        AI: "AI";
+    }>>>;
+    freeCancellation: z.ZodOptional<z.ZodBoolean>;
+    maxRoomsPerHotel: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+/** Rides on every create_booking answer: some clients never show the model
+ *  the server instructions. */
+declare const BOOKING_NEXT_STEP = "Show the user amount, currency, the stay (hotel, room, dates, rooms, guests per room) and every item in terms (meals, cancellation, confirmation, pay-at-hotel fees), then end your reply by asking them to confirm. Only after they say yes, give them paymentUrl exactly as returned.";
+/** create_booking's answer over MCP: the booking result plus `nextStep`. */
+declare const MCP_BOOKING_RESULT: z.ZodObject<{
+    agentOrderId: z.ZodString;
+    paymentUrl: z.ZodString;
+    amount: z.ZodNullable<z.ZodNumber>;
+    currency: z.ZodString;
+    orderUrl: z.ZodString;
+    statusUrl: z.ZodOptional<z.ZodString>;
+    stay: z.ZodObject<{
+        hotelId: z.ZodNumber;
+        hotelName: z.ZodNullable<z.ZodString>;
+        roomName: z.ZodNullable<z.ZodString>;
+        checkIn: z.ZodString;
+        checkOut: z.ZodString;
+        nights: z.ZodNumber;
+        rooms: z.ZodNumber;
+        adultsPerRoom: z.ZodNumber;
+        childrenAgesPerRoom: z.ZodArray<z.ZodNumber>;
+    }, z.core.$strip>;
+    terms: z.ZodNullable<z.ZodObject<{
+        boardCode: z.ZodString;
+        boardCount: z.ZodNumber;
+        refundable: z.ZodBoolean;
+        freeCancelUntil: z.ZodNullable<z.ZodString>;
+        cancellation: z.ZodArray<z.ZodObject<{
+            amount: z.ZodNumber;
+            from: z.ZodString;
+        }, z.core.$strip>>;
+        isInstantConfirm: z.ZodBoolean;
+        confirmByMins: z.ZodNullable<z.ZodNumber>;
+        payAtHotelFees: z.ZodArray<z.ZodObject<{
+            type: z.ZodString;
+            isMandatory: z.ZodBoolean;
+            amount: z.ZodNumber;
+            currency: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    nextStep: z.ZodString;
+}, z.core.$strip>;
+declare const TOOLS: readonly ToolSpec[];
+
+/** A flag that sets one field of a tool's input. */
+interface FlagSpec {
+    /** The long name without dashes: `check-in` for `--check-in`. */
+    flag: string;
+    /** The one-letter name without its dash: `q` for `-q`. */
+    short?: string;
+    /** The input field it sets; dots step into an object (`near.lat`). */
+    field: string;
+    /**
+     * How the CLI reads the value. `id` is digits only, a positive whole
+     * number. A `boolean` flag sets its field to true, except where the field
+     * defaults to true (`bookableOnly`): `--include-unbookable` sets it to
+     * false. A `string` flag whose field is an object (`near`, read as
+     * `lat,lng,radiusKm`) or a list of objects (`guests`, read as
+     * `First Last[:roomNo]`) is one value the CLI parses into that shape.
+     */
+    type: "string" | "number" | "boolean" | "id";
+    /** Given once per item; its field is a list. */
+    multiple?: boolean;
+    /**
+     * What the value looks like in help, as it follows the flag name: `<n>`,
+     * `YYYY-MM-DD`, `CNY|USD` (an enum's values), `"First Last[:roomNo]"`.
+     * Every flag that takes a value has one.
+     */
+    placeholder?: string;
+    description: string;
+}
+/** An option of the CLI itself that no tool takes: not a field of any input. */
+interface OptionSpec {
+    /** The long name without dashes. */
+    flag: string;
+    /** The one-letter name without its dash. */
+    short?: string;
+    type: "string" | "boolean";
+    /** As on `FlagSpec`; every option that takes a value has one. */
+    placeholder?: string;
+    description: string;
+}
+interface CommandSpec {
+    name: "search" | "hotel" | "rates" | "book" | "login" | "logout" | "whoami" | "guide" | "mcp";
+    summary: string;
+    /** The MCP tool the command mirrors; `null` for one that is the CLI's own. */
+    tool: ToolName | null;
+    /** The tool's input fields the command sets. */
+    flags: readonly FlagSpec[];
+    /** Named after the input field they set, except `guide`'s `topic`. */
+    positionals?: readonly string[];
+    /** Options that are not input fields, such as `--body`. */
+    options?: readonly OptionSpec[];
+}
+declare const COMMANDS: readonly CommandSpec[];
+/** Options of the CLI itself: `--help` after any command, `--version` on its own. */
+declare const GLOBAL_FLAGS: readonly OptionSpec[];
+
+/** True only for a real Gregorian calendar date in canonical yyyy-MM-dd form. */
+declare function isIsoDate(value: string): boolean;
+/** Signed number of UTC calendar days in the half-open range [start, end). */
+declare function countIsoDateDays(start: string, end: string): number;
+declare function addIsoDateDays(date: string, days: number): string;
+
+/** An object that names the keys it doesn't know instead of dropping them. */
+declare function strictInput<T extends z.core.$ZodLooseShape>(shape: T): z.ZodObject<{ -readonly [P in keyof T]: T[P]; }, z.core.$strict>;
+declare function wholeNumber(name: string, min: number, max: number): z.ZodNumber;
+declare function positiveId(name: string): z.ZodNumber;
+declare function isoDate(name: string): z.ZodString;
+declare function nonEmpty(name: string): z.ZodString;
+declare function text(name: string, min: number, max: number): z.ZodString;
+declare function oneOf<const T extends readonly [string, ...string[]]>(name: string, values: T): z.ZodEnum<{ [k_1 in T[number]]: k_1; } extends infer T_1 ? { [k in keyof T_1]: T_1[k]; } : never>;
+declare function flag(name: string): z.ZodBoolean;
+/** Each child's age in one room, up to `max` children. */
+declare function childrenAges(max: number): z.ZodArray<z.ZodNumber>;
+
+type GuideSurface = "mcp" | "claude-skill" | "cli";
+type GuideTopic = "main" | "planning";
+/** The guide on `topic` as `surface` states it, in Markdown. */
+declare function renderGuide(surface: GuideSurface, topic: GuideTopic): string;
+
+/** `POST /api/agent/v1/hotels/search` and the MCP `search_hotels` arguments. */
+declare const searchHotelsInput: z.ZodObject<{
+    query: z.ZodOptional<z.ZodString>;
+    cityCode: z.ZodOptional<z.ZodNumber>;
+    near: z.ZodOptional<z.ZodObject<{
+        lat: z.ZodNumber;
+        lng: z.ZodNumber;
+        radiusKm: z.ZodNumber;
+    }, z.core.$strict>>;
+    starMin: z.ZodOptional<z.ZodNumber>;
+    starMax: z.ZodOptional<z.ZodNumber>;
+    facilities: z.ZodOptional<z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string[], string[]>>>;
+    checkIn: z.ZodString;
+    checkOut: z.ZodString;
+    currency: z.ZodDefault<z.ZodEnum<{
+        CNY: "CNY";
+        USD: "USD";
+    }>>;
+    priceMin: z.ZodOptional<z.ZodNumber>;
+    priceMax: z.ZodOptional<z.ZodNumber>;
+    sortBy: z.ZodDefault<z.ZodEnum<{
+        recommended: "recommended";
+        "price-asc": "price-asc";
+        "price-desc": "price-desc";
+        "star-desc": "star-desc";
+        distance: "distance";
+    }>>;
+    page: z.ZodDefault<z.ZodNumber>;
+    pageSize: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+/**
+ * `GET /api/agent/v1/hotels/{id}` and the MCP `get_hotel` arguments. Not
+ * strict: it has always dropped a key it doesn't know. `hotelId` is coerced,
+ * so the numeric string a URL path gives parses as the number.
+ */
+declare const getHotelInput: z.ZodObject<{
+    hotelId: z.ZodCoercedNumber<unknown>;
+    includeRooms: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+/** `POST /api/agent/v1/hotels/rates` and the MCP `get_rates` arguments. */
+declare const getRatesInput: z.ZodObject<{
+    hotelIds: z.ZodArray<z.ZodNumber>;
+    checkIn: z.ZodString;
+    checkOut: z.ZodString;
+    rooms: z.ZodNumber;
+    adults: z.ZodNumber;
+    childrenAges: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+    nationality: z.ZodOptional<z.ZodString>;
+    currency: z.ZodDefault<z.ZodEnum<{
+        CNY: "CNY";
+        USD: "USD";
+    }>>;
+    bookableOnly: z.ZodDefault<z.ZodBoolean>;
+    boardCodes: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        RO: "RO";
+        BB: "BB";
+        HB: "HB";
+        FB: "FB";
+        BL: "BL";
+        BD: "BD";
+        HBBL: "HBBL";
+        HBLD: "HBLD";
+        AI: "AI";
+    }>>>;
+    freeCancellation: z.ZodOptional<z.ZodBoolean>;
+    maxRoomsPerHotel: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+/**
+ * `POST /api/agent/v1/hotels/bookings` and the MCP `create_booking`
+ * arguments. The booking action validates guest names (Latin letters) and
+ * the room assignment again. Occupancy is per room, every room the same.
+ * Unknown keys are refused, not dropped: a misspelled `children` would
+ * otherwise book the default `childrenAges: []`, a different party.
+ */
+declare const createBookingInput: z.ZodObject<{
+    hotelId: z.ZodNumber;
+    roomId: z.ZodString;
+    ratePlanCode: z.ZodString;
+    checkIn: z.ZodString;
+    checkOut: z.ZodString;
+    rooms: z.ZodNumber;
+    adults: z.ZodNumber;
+    childrenAges: z.ZodDefault<z.ZodArray<z.ZodNumber>>;
+    guests: z.ZodArray<z.ZodObject<{
+        firstName: z.ZodString;
+        lastName: z.ZodString;
+        roomNo: z.ZodCoercedNumber<unknown>;
+    }, z.core.$strict>>;
+    contactName: z.ZodString;
+    contactPhone: z.ZodString;
+    contactEmail: z.ZodOptional<z.ZodString>;
+    specialRequests: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** What a caller sends (defaults optional), and what a handler gets once parsed. */
+type SearchHotelsInput = z.input<typeof searchHotelsInput>;
+type SearchHotelsParsed = z.output<typeof searchHotelsInput>;
+type GetHotelInput = z.input<typeof getHotelInput>;
+type GetHotelParsed = z.output<typeof getHotelInput>;
+type GetRatesInput = z.input<typeof getRatesInput>;
+type GetRatesParsed = z.output<typeof getRatesInput>;
+type CreateBookingInput = z.input<typeof createBookingInput>;
+type CreateBookingParsed = z.output<typeof createBookingInput>;
+
+/** The ceilings and floors every agent surface enforces and documents. */
+declare const LIMITS: {
+    readonly rooms: 8;
+    readonly adultsPerRoom: 8;
+    readonly childrenPerRoom: 8;
+    readonly childAgeMax: 17;
+    readonly nights: 15;
+    readonly ratesHotels: 15;
+    readonly facilities: 10;
+    readonly queryLength: 128;
+    readonly nearRadiusKm: 200;
+    readonly page: 100;
+    readonly pageSize: 50;
+    readonly guestName: 60;
+    readonly contactName: 120;
+    readonly contactPhoneMin: 3;
+    readonly contactPhoneMax: 40;
+    readonly specialRequests: 500;
+    readonly maxRoomsPerHotel: 200;
+};
+/** Board (meal plan) codes a rate can carry and a search can ask for. */
+declare const BOARD_CODES: readonly ["RO", "BB", "HB", "FB", "BL", "BD", "HBBL", "HBLD", "AI"];
+/** Currencies prices can be shown and paid in. */
+declare const CURRENCIES: readonly ["CNY", "USD"];
+/** Orders a hotel search can be sorted in. */
+declare const SEARCH_SORTS: readonly ["recommended", "price-asc", "price-desc", "star-desc", "distance"];
+/** Where a person goes when an agent gets stuck. */
+declare const SUPPORT_EMAIL = "info@fortrip.ai";
+
+/**
+ * What `create_booking` / `POST /api/agent/v1/hotels/bookings` answers with.
+ * Its JSON Schema allows no other keys, so a caller that parses its answer
+ * through this schema drops a field the server adds until it is added here,
+ * rather than failing a strict client's validation. The MCP tool adds a
+ * `nextStep` to it; the HTTP answer has none.
+ */
+declare const bookingResult: z.ZodObject<{
+    agentOrderId: z.ZodString;
+    paymentUrl: z.ZodString;
+    amount: z.ZodNullable<z.ZodNumber>;
+    currency: z.ZodString;
+    orderUrl: z.ZodString;
+    statusUrl: z.ZodOptional<z.ZodString>;
+    stay: z.ZodObject<{
+        hotelId: z.ZodNumber;
+        hotelName: z.ZodNullable<z.ZodString>;
+        roomName: z.ZodNullable<z.ZodString>;
+        checkIn: z.ZodString;
+        checkOut: z.ZodString;
+        nights: z.ZodNumber;
+        rooms: z.ZodNumber;
+        adultsPerRoom: z.ZodNumber;
+        childrenAgesPerRoom: z.ZodArray<z.ZodNumber>;
+    }, z.core.$strip>;
+    terms: z.ZodNullable<z.ZodObject<{
+        boardCode: z.ZodString;
+        boardCount: z.ZodNumber;
+        refundable: z.ZodBoolean;
+        freeCancelUntil: z.ZodNullable<z.ZodString>;
+        cancellation: z.ZodArray<z.ZodObject<{
+            amount: z.ZodNumber;
+            from: z.ZodString;
+        }, z.core.$strip>>;
+        isInstantConfirm: z.ZodBoolean;
+        confirmByMins: z.ZodNullable<z.ZodNumber>;
+        payAtHotelFees: z.ZodArray<z.ZodObject<{
+            type: z.ZodString;
+            isMandatory: z.ZodBoolean;
+            amount: z.ZodNumber;
+            currency: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type BookingResult = z.infer<typeof bookingResult>;
+/** `GET /api/agent/v1/me`: the signed-in user. */
+declare const meResult: z.ZodObject<{
+    userId: z.ZodString;
+    email: z.ZodNullable<z.ZodString>;
+    name: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+type MeResult = z.infer<typeof meResult>;
+/**
+ * `GET /api/agent/v1/auth/config` (public): where and how the CLI signs in
+ * with the device flow. `scopes` is one space-separated string.
+ */
+declare const authConfig: z.ZodObject<{
+    issuer: z.ZodString;
+    clientId: z.ZodString;
+    scopes: z.ZodString;
+    deviceAuthorizationEndpoint: z.ZodString;
+    tokenEndpoint: z.ZodString;
+    revocationEndpoint: z.ZodString;
+}, z.core.$strip>;
+type AuthConfig = z.infer<typeof authConfig>;
+
+/** Where the agent API lives. Paths only: the origin is the caller's to choose. */
+declare const API: {
+    readonly me: "/api/agent/v1/me";
+    readonly authConfig: "/api/agent/v1/auth/config";
+    readonly search: "/api/agent/v1/hotels/search";
+    readonly rates: "/api/agent/v1/hotels/rates";
+    readonly bookings: "/api/agent/v1/hotels/bookings";
+    readonly mcp: "/api/mcp";
+    readonly hotel: (id: number, includeRooms?: boolean) => string;
+};
+
+declare const reasonStatuses: {
+    readonly already_booked: readonly [409];
+    readonly price_or_terms_changed: readonly [409];
+    readonly rate_unavailable: readonly [422];
+    readonly refused: readonly [422];
+    readonly supplier_unavailable: readonly [503, 504];
+};
+type ErrorReason = keyof typeof reasonStatuses;
+/**
+ * The `reason` an agent error can carry, each with the HTTP statuses it is
+ * sent with. Typed as plain number lists so `ERROR_REASONS[reason].includes(status)`
+ * type-checks for a status read off a response.
+ */
+declare const ERROR_REASONS: {
+    readonly [R in ErrorReason]: readonly number[];
+};
+
+/** The contract's version, from package.json, the one place a release bumps it. */
+declare const CONTRACT_VERSION: string;
+
+export { API, type AuthConfig, BOARD_CODES, BOOKING_NEXT_STEP, type BookingResult, CARD_NUMBER_MESSAGE, COMMANDS, CONTRACT_VERSION, CURRENCIES, type CommandSpec, type CreateBookingInput, type CreateBookingParsed, ERROR_REASONS, type ErrorReason, type FlagSpec, GLOBAL_FLAGS, type GetHotelInput, type GetHotelParsed, type GetRatesInput, type GetRatesParsed, type GuideSurface, type GuideTopic, LIMITS, MCP_BOOKING_RESULT, MCP_RATES_INPUT, type MeResult, type OptionSpec, SEARCH_SORTS, SUPPORT_EMAIL, type SearchHotelsInput, type SearchHotelsParsed, TOOLS, type ToolName, type ToolSpec, addIsoDateDays, authConfig, bookingResult, childrenAges, containsCardNumber, countIsoDateDays, createBookingInput, flag, getHotelInput, getRatesInput, isIsoDate, isoDate, meResult, nonEmpty, oneOf, positiveId, renderGuide, searchHotelsInput, strictInput, text, wholeNumber };