fortrip 0.1.1 → 0.1.2

package/AGENT_GUIDE.md

@@ -0,0 +1,124 @@
+# Fortrip hotels
+
+Fortrip sells hotel rooms at supplier net prices. The
+`fortrip` CLI (npm package `fortrip`) calls the Fortrip API as the
+signed-in user and prints JSON.
+
+## When to use
+
+- The user wants hotels in a city, near a point, or by name, for given dates.
+- The user wants live rooms, meal plans, cancellation terms or prices for
+  specific hotels.
+- The user has picked a rate and wants to book it (you return a payment link;
+  the user pays in their browser).
+
+Not for flights, activities, or changing/cancelling an existing booking.
+
+## Setup
+
+Run every command as `npx -y fortrip@latest <command>`, the same version that
+printed this guide. The examples below shorten that to `fortrip`.
+
+When the user first asks about hotels, run `fortrip whoami` before asking
+follow-up questions, so a login can happen while they answer.
+
+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.
+
+## 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 |
+| 3 | Not logged in | Show `loginUrl` to the user, then rerun (above) |
+| 4 | Rate limited | Wait `retryAfterSeconds`, then retry once |
+
+## Recommended order
+
+1. **Search** — find candidates and indicative prices:
+
+   ```bash
+   fortrip search --query "Bangkok" --check-in 2026-11-10 --check-out 2026-11-12 \
+     --star-min 4 --sort price-asc --page-size 10
+   ```
+
+   Use `--near lat,lng,radiusKm` for "near X", `--city-code` when known.
+   `--facility` names must match the catalogue exactly (e.g. `Swimming pool`,
+   `Parking`), otherwise nothing matches. Prices here (`price.nightlyFrom`,
+   `totalFrom`, CNY) are **indicative floors**, not quotes — say so.
+
+2. **Hotel detail** (optional) — description, policies, facilities, photos:
+
+   ```bash
+   fortrip hotel 266000 [--with-rooms]
+   ```
+
+3. **Rates** — live rooms and prices for up to 15 hotels:
+
+   ```bash
+   fortrip rates --hotel 266000 --hotel 266001 --check-in 2026-11-10 \
+     --check-out 2026-11-12 --rooms 1 --adults 2 [--child-age 6] \
+     [--nationality CN] [--board BB] [--free-cancellation]
+   ```
+
+   This call takes about 15 seconds. `totalPrice` is CNY at a fixed exchange
+   rate. 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).
+
+4. **Book** — only after the user picks one rate and gives guest details:
+
+   ```bash
+   fortrip book --hotel 266000 --room-id 9191658 --rate-plan "<ratePlanCode>" \
+     --check-in 2026-11-10 --check-out 2026-11-12 --rooms 1 --adults 2 \
+     --guest "John Smith" --contact-name "John Smith" \
+     --contact-phone "+8613800000000" [--contact-email john@example.com]
+   ```
+
+   `--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.
+
+## 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`.
+2. **Explain the amount.** `rates` showed CNY, 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 amount on the payment page is what will be
+   charged; the CNY figure was a reference.
+3. 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.
+
+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`.

package/README.md

@@ -53,9 +53,16 @@ Tokens don't expire; `logout` revokes them.
 
 ## Agent skill
 
-[`skills/fortrip-hotels/SKILL.md`](skills/fortrip-hotels/SKILL.md) tells an AI
-agent when to use the CLI, the call order, and what to show the user before
-handing over a payment link.
+```bash
+npx skills add FortripEngineering/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
+[`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`.
 
 ## Development
 

package/dist/cli.js

@@ -22,7 +22,10 @@ function usageError(message) {
 }
 
 // src/version.ts
-var VERSION = "0.1.0";
+import { readFileSync } from "fs";
+var VERSION = JSON.parse(
+  readFileSync(new URL("../package.json", import.meta.url), "utf8")
+).version;
 
 // src/api.ts
 var LOGIN_HINT = "Run `npx fortrip login` first.";
@@ -96,7 +99,7 @@ function unwrap(response) {
 }
 
 // src/args.ts
-import { readFileSync } from "fs";
+import { readFileSync as readFileSync2 } from "fs";
 import { parseArgs } from "util";
 var BODY_OPTION = { body: { type: "string" } };
 function parse(argv, options) {
@@ -112,7 +115,7 @@ function baseBody(values) {
   let text = raw;
   if (raw.startsWith("@")) {
     try {
-      text = readFileSync(raw.slice(1), "utf8");
+      text = readFileSync2(raw.slice(1), "utf8");
     } catch (error) {
       throw usageError(`Cannot read --body file: ${error.message}`);
     }
@@ -513,6 +516,12 @@ function deviceLabel() {
   return hostname().replace(/[^\w .@-]/g, "").slice(0, 64);
 }
 
+// src/guide.ts
+import { readFile as readFile2 } from "fs/promises";
+function readGuide() {
+  return readFile2(new URL("../AGENT_GUIDE.md", import.meta.url), "utf8");
+}
+
 // src/cli.ts
 var HELP = `fortrip ${VERSION} \u2014 search, price and book Fortrip hotels
 
@@ -526,6 +535,7 @@ Commands:
   hotel <hotelId>             Static hotel detail [--with-rooms]
   rates                       Live rooms and rates (CNY) for up to 15 hotels
   book                        Create an order and get a payment link
+  skill                       Print the guide for AI agents (Markdown)
 
 search:  --query <text> | --city-code <n> | --near <lat,lng,km>
          --check-in YYYY-MM-DD --check-out YYYY-MM-DD
@@ -562,6 +572,11 @@ async function run(argv) {
 `);
     return void 0;
   }
+  if (command === "skill") {
+    parse(rest, {});
+    process.stdout.write(await readGuide());
+    return void 0;
+  }
   const apiUrl = resolveApiUrl();
   const log = (line) => process.stderr.write(`${line}
 `);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fortrip",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Search, price and book Fortrip hotels from the terminal or an AI agent.",
   "type": "module",
   "bin": {
@@ -9,6 +9,7 @@
   "files": [
     "dist",
     "skills",
+    "AGENT_GUIDE.md",
     "README.md"
   ],
   "engines": {

package/skills/fortrip-hotels/SKILL.md

@@ -5,125 +5,16 @@ description: Search hotels, compare live room rates and create a hotel booking w
 
 # Fortrip hotels
 
-Fortrip sells hotel rooms at supplier net prices. The
-`fortrip` CLI (npm package `fortrip`) calls the Fortrip API as the
-signed-in user and prints JSON.
+Before anything else, run:
 
-## When to use
+```bash
+npx -y fortrip@latest skill
+```
 
-- The user wants hotels in a city, near a point, or by name, for given dates.
-- The user wants live rooms, meal plans, cancellation terms or prices for
-  specific hotels.
-- The user has picked a rate and wants to book it (you return a payment link;
-  the user pays in their browser).
+It prints the current instructions for the Fortrip CLI: commands, call order,
+login, and what to show the user before giving a payment link. Follow them.
+They ship with each CLI release, so this file stays short and doesn't go out
+of date.
 
-Not for flights, activities, or changing/cancelling an existing booking.
-
-## Setup
-
-Run commands with `npx -y fortrip <command>` (or `fortrip <command>`
-if installed globally).
-
-When the user first asks about hotels, run `fortrip whoami` before asking
-follow-up questions, so a login can happen while they answer.
-
-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.
-
-## 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 |
-| 3 | Not logged in | Show `loginUrl` to the user, then rerun (above) |
-| 4 | Rate limited | Wait `retryAfterSeconds`, then retry once |
-
-## Recommended order
-
-1. **Search** — find candidates and indicative prices:
-
-   ```bash
-   fortrip search --query "Bangkok" --check-in 2026-11-10 --check-out 2026-11-12 \
-     --star-min 4 --sort price-asc --page-size 10
-   ```
-
-   Use `--near lat,lng,radiusKm` for "near X", `--city-code` when known.
-   `--facility` names must match the catalogue exactly (e.g. `Swimming pool`,
-   `Parking`), otherwise nothing matches. Prices here (`price.nightlyFrom`,
-   `totalFrom`, CNY) are **indicative floors**, not quotes — say so.
-
-2. **Hotel detail** (optional) — description, policies, facilities, photos:
-
-   ```bash
-   fortrip hotel 266000 [--with-rooms]
-   ```
-
-3. **Rates** — live rooms and prices for up to 15 hotels:
-
-   ```bash
-   fortrip rates --hotel 266000 --hotel 266001 --check-in 2026-11-10 \
-     --check-out 2026-11-12 --rooms 1 --adults 2 [--child-age 6] \
-     [--nationality CN] [--board BB] [--free-cancellation]
-   ```
-
-   This call takes about 15 seconds. `totalPrice` is CNY at a fixed exchange
-   rate. 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).
-
-4. **Book** — only after the user picks one rate and gives guest details:
-
-   ```bash
-   fortrip book --hotel 266000 --room-id 9191658 --rate-plan "<ratePlanCode>" \
-     --check-in 2026-11-10 --check-out 2026-11-12 --rooms 1 --adults 2 \
-     --guest "John Smith" --contact-name "John Smith" \
-     --contact-phone "+8613800000000" [--contact-email john@example.com]
-   ```
-
-   `--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.
-
-## 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`.
-2. **Explain the amount.** `rates` showed CNY, 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 amount on the payment page is what will be
-   charged; the CNY figure was a reference.
-3. 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.
-
-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`.
+Needs Node.js 22 or newer. If the command fails, tell the user why instead of
+guessing the CLI's flags.