fortrip 0.3.0 → 0.3.1

package/AGENT_GUIDE.md

@@ -1,4 +1,4 @@
-# Fortrip hotels
+# Fortrip
 
 Fortrip sells hotel rooms at supplier net prices. The
 `fortrip` CLI (npm package `fortrip`) calls the Fortrip API as the
@@ -13,6 +13,9 @@ signed-in user and prints JSON.
   the user pays in their browser).
 
 Not for flights, activities, or changing/cancelling an existing booking.
+For changes, cancellations, refunds or any other problem with a booking, the
+user emails info@fortrip.ai with the booking's `orderUrl` (never
+`paymentUrl` or `statusUrl`).
 
 For flexible dates, a budget, split stays, several destinations or "find me
 the best", also run `npx -y fortrip@latest skill planning` before searching.
@@ -20,7 +23,8 @@ the best", also run `npx -y fortrip@latest skill planning` before searching.
 ## Setup
 
 Run every command as `npx -y fortrip@latest <command>`, the same version that
-printed this guide. The examples below shorten that to `fortrip`.
+printed this guide. The examples below shorten that to `fortrip`;
+`fortrip <command> --help` lists a command's flags.
 
 When the user first asks about hotels, run `fortrip whoami` before asking
 follow-up questions, so a login can happen while they answer.
@@ -29,25 +33,35 @@ If 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 BCDF-GHJK) and tell me when you're done." When they confirm, rerun the
 same command; it finishes the login itself. Don't run `fortrip login` — it
-waits for up to 10 minutes. If the rerun gives a new `loginUrl`, the old one
-expired or was denied; show the new one.
-
-If exit 3 has no `loginUrl`, the saved token was revoked: run `fortrip logout`,
-then rerun the command to get a link.
-
-In CI, the user can set `FORTRIP_TOKEN` instead. Never ask the user to paste a
-token into the chat.
+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.
+
+When Fortrip doesn't accept the saved sign-in (it was revoked or has
+expired, or Fortrip had a passing problem), 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, so after a passing problem the next command
+works without signing in again. Exit 3 with `tokenSource: "FORTRIP_TOKEN"` means Fortrip
+didn't accept the token the user set in `FORTRIP_TOKEN`: retry once a
+little later, and if it keeps happening, tell the user to replace or unset
+it.
+
+Sign-in happens only in the browser. In CI, the user can set `FORTRIP_TOKEN`
+instead. Never ask the user to paste a token into the chat.
 
 ## Exit codes
 
 | Code | Meaning | What to do |
 |---|---|---|
 | 0 | Success; JSON on stdout | Continue |
-| 1 | Other error (supplier error, rate no longer bookable, network) | Read `error` on stderr; re-run `rates` if a rate went stale |
-| 2 | Invalid arguments | Fix the flags; stderr `issues` lists the bad fields |
+| 1 | Other error (supplier error, rate no longer bookable, network error or timeout) | Read `error` on stderr; if `retryable` is true (supplier unreachable or timed out, Fortrip briefly unavailable, or no response from Fortrip), wait `retryAfterSeconds` (or a few seconds) and retry once; re-run `rates` if a rate went stale. `book` errors carry a `reason` (below) |
+| 2 | Invalid arguments | Fix the flags; stderr `issues` lists each bad field with a message |
 | 3 | Not logged in | Show `loginUrl` to the user, then rerun (above) |
 | 4 | Rate limited | Wait `retryAfterSeconds`, then retry once |
 
+Output on stdout or stderr can carry `warning` (with `recoveryFile` when a
+sign-in couldn't be saved): pass it on to the user.
+
 ## Recommended order
 
 1. **Search** — find candidates and indicative prices:
@@ -63,7 +77,9 @@ token into the chat.
    `--price-min` / `--price-max` are in that currency.
    `--facility` names must match the catalogue exactly (e.g. `Swimming pool`,
    `Parking`), otherwise nothing matches. Prices here (`price.nightlyFrom`,
-   `totalFrom`) are **indicative floors**, not quotes — say so.
+   `totalFrom`) are **indicative floors**, not quotes — say so. A search
+   that matches too many hotels fails with `matched` and `maxMatches`: narrow
+   it (a city, an area, stars or a price range).
 
 2. **Hotel detail** (optional) — description, policies, facilities, photos:
 
@@ -79,13 +95,30 @@ token into the chat.
      [--nationality CN] [--board BB] [--free-cancellation] [--currency USD]
    ```
 
+   `--adults` and `--child-age` are **per room**, and every room has the same
+   occupancy: 2 rooms for 4 adults is `--rooms 2 --adults 2`. If the party
+   doesn't divide evenly (3 adults in 2 rooms), ask the user whether to price
+   every room for the larger number or book the rooms separately. Limits:
+   1–8 rooms, 1–8 adults and 0–8 children (aged 0–17) per room, 1–15
+   nights, up to 15 hotels per call.
+
    This call takes about 15 seconds. Prices are in the response's `currency`,
    converted at Stripe's exchange rate (refreshed hourly), or a fixed fallback
    rate when Stripe is unavailable; `fx` says which, and is `null` when
-   nothing needed converting. Present each option with meal plan (`boardCode`: RO room only,
-   BB breakfast, HB half board, FB full board, AI all inclusive),
-   `freeCancelUntil` / `refundable`, `isInstantConfirm`, and any `fees`
-   (taxes paid at the hotel, in their own currency).
+   nothing needed converting. Present each option with:
+
+   - meal plan: `boardCode` (RO room only, BB breakfast, HB breakfast +
+     dinner, FB breakfast + lunch + dinner, BL lunch, BD dinner, HBBL
+     breakfast + lunch, HBLD lunch + dinner, AI all inclusive) together with
+     `boardCount`, how many guests per room the meal plan covers; fewer than
+     the adults per room means not everyone gets the meals (BB with
+     `boardCount` 1 for 2 adults is breakfast for 1 of 2), so say who is
+     covered;
+   - `freeCancelUntil` / `refundable`, `isInstantConfirm`, and any `fees`
+     (taxes paid at the hotel, in their own currency).
+
+   `--nationality` isn't sent with the booking: a rate restricted to that
+   nationality may change or be refused when booked.
 
 4. **Book** — only after the user picks one rate and gives guest details:
 
@@ -97,37 +130,71 @@ token into the chat.
    ```
 
    `--hotel`, `--room-id`, `--rate-plan`, dates, `--rooms`, `--adults` and
-   `--child-age` must be exactly the values used in `rates`. Guest names must
-   be in Latin letters as on the passport ("First Last"; last word is the last
-   name; `"First Last:2"` puts the guest in room 2). Each room needs at least
-   one guest. `--special-requests` must be in English and isn't guaranteed.
+   `--child-age` must be exactly the values used in `rates`; `book` requires
+   `--rooms` and `--adults`. Guest names must be in Latin letters as on the
+   passport ("First Last"; last word is the last name; `"First Last:2"` puts
+   the guest in room 2; 1–60 characters each). Each room needs at least one
+   guest. The contact name takes up to 120 characters, the phone 3–40.
+   `--special-requests` must be in English and isn't guaranteed. `book`
+   accepts only these fields: a `--body` with any other field (such as
+   `nationality`) is rejected with exit 2.
+
+   One booking covers at most 15 nights; book a longer stay as separate
+   bookings. `book` checks the rate with the supplier again and can take up
+   to about 2 minutes: allow the command at least 3 minutes, and if it times
+   out, run it again with identical flags. That is always safe: it returns
+   the same order, with the same or a refreshed payment link.
 
 ## Before giving the payment link
 
-`book` returns `paymentUrl`, `amount`, `currency`, `terms`, `statusUrl` and
-`orderUrl`. Before you hand over `paymentUrl`:
-
-1. **Show the `terms`** and get the user's confirmation: meal plan
-   (`boardCode`, `boardCount`), cancellation (`refundable`, `freeCancelUntil`,
-   the `cancellation` ladder), confirmation (`isInstantConfirm`,
-   `confirmByMins`) and `payAtHotelFees`.
+`book` returns `paymentUrl`, `amount`, `currency`, `terms`, `stay`,
+`statusUrl` and `orderUrl`. Before you hand over `paymentUrl`:
+
+1. **Show what will be booked and ask the user to confirm.** From `stay`:
+   hotel (`hotelName`), room (`roomName`), dates, nights, rooms and guests per
+   room (`adultsPerRoom`, `childrenAgesPerRoom`); if `stay` is missing, use
+   the values you passed. From `terms`: meal plan (`boardCode` with
+   `boardCount`), cancellation (`refundable`, `freeCancelUntil`, the
+   `cancellation` ladder), confirmation (`isInstantConfirm`, `confirmByMins`)
+   and `payAtHotelFees`. Then the `amount` and `currency`, and end your reply
+   by asking them to confirm. If `amount` or `terms` is `null`, say it
+   couldn't be read rather than guess; the payment page shows the amount.
 2. **Explain the amount.** `rates` showed a converted figure, but the charge
    is `amount` in `currency` (usually USD), and the Stripe page may display
    the user's local currency at Stripe's rate. The `rates` figure used a
    Stripe rate too, so it is usually close, but the amount on the payment page
    is what will be charged; the `rates` figure was a reference.
-3. The link is for **this user only**: whoever has it can pay. Don't post it
+3. **Only after they confirm, give `paymentUrl` exactly as returned**: don't
+   shorten, rebuild or re-encode it. It opens a Fortrip page that recaps the
+   booking and continues to payment.
+4. The link is for **this user only**: whoever has it can pay. Don't post it
    in shared channels, logs or tickets. It expires after about 3 hours 45
    minutes; call `book` again with the same details for a fresh one.
 
+Never ask for, accept or pass on payment card details; payment happens only
+on the payment page. A card number in a guest name, the contact name or the
+special requests is rejected with exit 2.
+
 After paying, the user lands on `statusUrl`, which shows confirmation progress
 without signing in. `orderUrl` is the signed-in order page.
 
 ## Errors from `book`
 
-- `409` with `agentOrderId`: this exact stay is already paid or completed —
-  show `orderUrl`, don't book again.
-- `409` with `changes`: price or terms changed — re-run `rates` and confirm
-  again with the user.
-- `422`: the booking was refused (guest names, too many attempts, bookings
-  paused, or a preview deployment). Read `error`.
+Act on `reason` in stderr:
+
+- `already_booked` (409, with `agentOrderId`): this exact stay is already paid
+  or completed — show `orderUrl`, don't book again.
+- `price_or_terms_changed` (409, with `changes`): show what changed, re-run
+  `rates` and confirm again with the user.
+- `rate_unavailable` (422): the rate can no longer be booked — re-run `rates`
+  and offer what is left.
+- `supplier_unavailable` (503 or 504, `retryable: true`): wait
+  `retryAfterSeconds` and retry once with identical flags. A 503 with
+  `retryable: true` and no `reason` (a passing outage) is handled the same
+  way.
+- `refused` (any other 422): the booking was refused (guest names, too many
+  attempts, bookings paused, or a preview deployment). Read `error`.
+
+Older servers send no `reason`: there a 409 with `agentOrderId` is
+`already_booked`, a 409 with `changes` is `price_or_terms_changed`, any other
+409 is `rate_unavailable`, and a 422 is `refused`.

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,8 +1,12 @@
 # fortrip-cli
 
-Search, price and book Fortrip hotels from the terminal or an AI agent. The
+Search, price and book Fortrip hotels from the terminal or an AI agent.
 The npm package and the command are both `fortrip`.
 
+For MCP clients, see the separately maintained
+[Fortrip MCP](https://github.com/FortripEngineering/fortrip-mcp)
+repository for local and hosted connection instructions.
+
 ```bash
 npx fortrip login          # sign in through the browser
 npx fortrip search --query Bangkok --check-in 2026-11-10 --check-out 2026-11-12
@@ -20,52 +24,77 @@ Requires Node.js 22 or newer. No runtime dependencies.
 | `search` | Hotels with indicative prices |
 | `hotel <hotelId> [--with-rooms]` | Static hotel detail |
 | `rates` | Live rooms and rates |
-| `book` | Order + Stripe payment link |
+| `book` | Order + payment link (a Fortrip page that continues to Stripe) |
+
+Run `fortrip --help` for every flag, or `fortrip <command> --help` for one
+command's. `search`, `rates` and `book` also accept `--body '<json>'` or
+`--body @file.json` with the raw request body; flags override its fields.
 
-Run `fortrip --help` for every flag. `search`, `rates` and `book` also accept
-`--body '<json>'` or `--body @file.json` with the raw request body; flags
-override its fields.
+`--adults` and `--child-age` are per room, and every room has the same
+occupancy: 2 rooms for 4 adults is `--rooms 2 --adults 2`. `rates` defaults
+to 1 room for 2 adults; `book` requires `--rooms` and `--adults`.
 
 Output is JSON on stdout. Errors are JSON on stderr, with fixed exit codes:
 
 | Code | Meaning |
 |---|---|
 | 0 | Success |
-| 1 | Other error |
+| 1 | Other error (`retryable: true` on stderr: worth one retry) |
 | 2 | Invalid arguments (local or HTTP 400) |
-| 3 | Not logged in / token revoked (HTTP 401) |
+| 3 | Not logged in, or the sign-in wasn't accepted (HTTP 401) |
 | 4 | Rate limited (HTTP 429; `retryAfterSeconds` on stderr) |
 
 ## Credentials
 
 - `login` saves the token to `~/.config/fortrip/credentials.json`
-  (`$XDG_CONFIG_HOME` is honoured), mode `0600`. Tokens are stored per API URL,
-  so a token is only ever sent to the server that issued it.
+  (`$XDG_CONFIG_HOME` is honoured), mode `0600`. Saved tokens are stored per
+  API URL, so a saved token is only sent to the server that issued it.
 - Without a token, any other command starts a device login and exits 3 with
   `loginUrl` on stderr instead of waiting. Once that link is approved in the
   browser, rerunning the command saves the token and carries on. This is how
-  AI agents sign in, since they can't sit in `login`.
-- `FORTRIP_TOKEN` overrides the saved login (CI, remote sandboxes).
+  AI agents sign in, since they can't sit in `login`. Commands run in
+  parallel share one login link. If the server doesn't accept the saved
+  token, the command keeps it and starts a new login the same way; once that
+  link is approved, the new token replaces the saved one.
+- `FORTRIP_TOKEN` overrides the saved login (CI, remote sandboxes). It is not
+  tied to a server: it is sent to whatever `FORTRIP_API_URL` points at. If the
+  server doesn't accept it, commands exit 3 with `tokenSource: "FORTRIP_TOKEN"`
+  and no `loginUrl`.
 - `FORTRIP_API_URL` overrides the base URL (default `https://fortrip.ai`).
   Plain `http` is only accepted for `localhost`.
 - `FORTRIP_CURRENCY` sets the default `--currency` for `search` and `rates`
   (`CNY` or `USD`; the API defaults to `CNY`). Display only: `book`
   charges the currency it returns.
 
-Tokens don't expire; `logout` revokes them.
+`logout` revokes the saved token. With the Fortrip server update released
+alongside CLI 0.3.1, sign-ins that go unused for 90 days stop working, and
+signed-in users can list and revoke their CLI sign-ins in their Fortrip
+account (account menu → **Fortrip CLI**).
+
+If a new sign-in can't be saved (the file is busy or damaged), it is kept
+in a `credentials.recovered-*.json` file next to `credentials.json` (mode
+`0600`), and the command's JSON output names it in `warning` and
+`recoveryFile`. The next successful save merges it back and removes the
+file; `logout` revokes and removes these too.
+
+Sharing `credentials.json` with 0.3.0 works on a best-effort basis: 0.3.0
+finds the newest pending login where it expects it, but it writes the file
+without a lock, so don't sign in with 0.3.0 and 0.3.1 at the same moment.
 
 ## Agent skill
 
 ```bash
-npx skills add FortripEngineering/fortrip-cli
+npx skills add FortripEngineering/fortrip-plugins --skill fortrip-cli
 ```
 
-[`skills/fortrip-hotels/SKILL.md`](skills/fortrip-hotels/SKILL.md) only tells
-the agent to run `npx -y fortrip@latest skill`, which prints
+The skill lives in
+[fortrip-plugins](https://github.com/FortripEngineering/fortrip-plugins); the
+Claude directory plugin there uses the hosted MCP instead of the CLI. The
+skill only tells the agent to run `npx -y fortrip@latest skill`, which prints
 [`AGENT_GUIDE.md`](AGENT_GUIDE.md): when to use the CLI, the call order, login,
 and what to show the user before handing over a payment link. The guide ships
 with the package, so a CLI release updates every installed skill. Edit
-`AGENT_GUIDE.md`, not `SKILL.md`.
+`AGENT_GUIDE.md`, not the skill.
 
 `fortrip skill planning` prints [`guides/planning.md`](guides/planning.md):
 what to ask, how to rank and how to present options for flexible dates,
@@ -73,6 +102,12 @@ budgets, split stays and several destinations. Both guides are printed with
 `fortrip@latest` replaced by the running version, so an agent keeps using the
 same CLI for the whole conversation.
 
+## Support
+
+For changes, cancellations, refunds or other help with a booking, email
+[info@fortrip.ai](mailto:info@fortrip.ai) with the booking's order link
+(`orderUrl`).
+
 ## Development
 
 ```bash
@@ -89,7 +124,9 @@ Point at a local Fortrip app with `FORTRIP_API_URL=http://localhost:3000`.
 
 Pushing a `v*` tag publishes to npm through
 [`.github/workflows/publish.yml`](.github/workflows/publish.yml), which signs
-in with npm trusted publishing (no npm token in GitHub).
+in with npm trusted publishing (no npm token in GitHub). Pull requests and
+pushes to `main` run typecheck, tests and the build through
+[`.github/workflows/ci.yml`](.github/workflows/ci.yml).
 
 1. Bump the version in a PR and merge it into `main`:
    `npm version minor --no-git-tag-version` (or `patch`).
@@ -101,5 +138,13 @@ in with npm trusted publishing (no npm token in GitHub).
    ```
 
 The workflow refuses a tag that doesn't match `package.json` or isn't on
-`main`, then runs typecheck, tests and the build before publishing. Every
-installed skill picks up the new guide on its next `npx fortrip@latest skill`.
+`main`. A `build` job runs typecheck, tests and the build and packs the
+tarball; a `publish` job in the `npm-publish` environment publishes that
+tarball, with no install or build of its own. Every installed skill picks up
+the new guide on its next `npx fortrip@latest skill`.
+
+## License
+
+The code and documentation in this repository are licensed under the
+[MIT License](LICENSE). This license does not grant access to the hosted
+Fortrip service, hotel inventory, or third-party data.