fortrip 0.1.0 → 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

@@ -41,6 +41,10 @@ Output is JSON on stdout. Errors are JSON on stderr, with fixed exit codes:
 - `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.
+- 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).
 - `FORTRIP_API_URL` overrides the base URL (default `https://fortrip.ai`).
   Plain `http` is only accepted for `localhost`.
@@ -49,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}`);
     }
@@ -331,11 +334,21 @@ function resolveApiUrl(env = process.env) {
 async function readCredentials(path) {
   try {
     const parsed = JSON.parse(await readFile(path, "utf8"));
-    return { tokens: parsed?.tokens ?? {} };
+    return { tokens: parsed?.tokens ?? {}, pending: parsed?.pending ?? {} };
   } catch {
-    return { tokens: {} };
+    return { tokens: {}, pending: {} };
   }
 }
+async function writeCredentials(path, file) {
+  if (Object.keys(file.tokens).length === 0 && Object.keys(file.pending).length === 0) {
+    await rm(path, { force: true });
+    return;
+  }
+  await mkdir(dirname(path), { recursive: true, mode: 448 });
+  await writeFile(path, `${JSON.stringify(file, null, 2)}
+`, { mode: 384 });
+  await chmod(path, 384);
+}
 async function loadStoredToken(apiUrl, env = process.env) {
   const file = await readCredentials(credentialsPath(env));
   return file.tokens[apiUrl]?.accessToken ?? null;
@@ -350,31 +363,51 @@ async function saveToken(apiUrl, accessToken, env = process.env) {
   const path = credentialsPath(env);
   const file = await readCredentials(path);
   file.tokens[apiUrl] = { accessToken, createdAt: (/* @__PURE__ */ new Date()).toISOString() };
-  await mkdir(dirname(path), { recursive: true, mode: 448 });
-  await writeFile(path, `${JSON.stringify(file, null, 2)}
-`, { mode: 384 });
-  await chmod(path, 384);
+  delete file.pending[apiUrl];
+  await writeCredentials(path, file);
 }
 async function deleteToken(apiUrl, env = process.env) {
   const path = credentialsPath(env);
   const file = await readCredentials(path);
   delete file.tokens[apiUrl];
-  if (Object.keys(file.tokens).length === 0) {
-    await rm(path, { force: true });
-    return;
-  }
-  await writeFile(path, `${JSON.stringify(file, null, 2)}
-`, { mode: 384 });
-  await chmod(path, 384);
+  await writeCredentials(path, file);
+}
+async function loadPendingLogin(apiUrl, env = process.env) {
+  const pending = (await readCredentials(credentialsPath(env))).pending[apiUrl];
+  return pending && Date.parse(pending.expiresAt) > Date.now() ? pending : null;
+}
+async function savePendingLogin(apiUrl, pending, env = process.env) {
+  const path = credentialsPath(env);
+  const file = await readCredentials(path);
+  if (pending) file.pending[apiUrl] = pending;
+  else delete file.pending[apiUrl];
+  await writeCredentials(path, file);
 }
 
 // src/auth.ts
 async function requireToken(apiUrl) {
   const resolved = await resolveToken(apiUrl);
-  if (!resolved) {
-    throw new CliError(`Not logged in to ${apiUrl}. ${LOGIN_HINT}`, EXIT.unauthenticated);
+  if (resolved) return resolved.token;
+  const pending = await loadPendingLogin(apiUrl);
+  if (pending) {
+    const result = await exchange(apiUrl, pending.deviceCode);
+    if (result.status === "ok") {
+      await saveToken(apiUrl, result.accessToken);
+      return result.accessToken;
+    }
+    if (result.status === "authorization_pending" || result.status === "slow_down") {
+      throw loginRequired(apiUrl, pending);
+    }
   }
-  return resolved.token;
+  const start = await startDeviceLogin(apiUrl);
+  const fresh = {
+    deviceCode: start.deviceCode,
+    userCode: start.userCode,
+    loginUrl: start.verificationUriComplete,
+    expiresAt: new Date(Date.now() + start.expiresIn * 1e3).toISOString()
+  };
+  await savePendingLogin(apiUrl, fresh);
+  throw loginRequired(apiUrl, fresh);
 }
 async function login({
   apiUrl,
@@ -382,12 +415,7 @@ async function login({
   log,
   wait = sleep
 }) {
-  const start = unwrap(
-    await request(apiUrl, "/api/cli/auth/device", {
-      method: "POST",
-      body: { label: deviceLabel() }
-    })
-  );
+  const start = await startDeviceLogin(apiUrl);
   log(`Confirm this code in your browser: ${start.userCode}`);
   log(`If the browser doesn't open, visit: ${start.verificationUriComplete}`);
   if (shouldOpen) openBrowser(start.verificationUriComplete);
@@ -396,21 +424,16 @@ async function login({
   const deadline = Date.now() + start.expiresIn * 1e3;
   while (Date.now() < deadline) {
     await wait(interval * 1e3);
-    const poll = await request(apiUrl, "/api/cli/auth/token", {
-      method: "POST",
-      body: { deviceCode: start.deviceCode }
-    });
-    if (poll.status === 200 && poll.body.success === true) {
-      const { accessToken } = poll.body.data;
-      await saveToken(apiUrl, accessToken);
-      log("Logged in.");
-      return whoami(apiUrl, accessToken);
-    }
-    switch (poll.body.error) {
+    const result = await exchange(apiUrl, start.deviceCode);
+    switch (result.status) {
+      case "ok":
+        await saveToken(apiUrl, result.accessToken);
+        log("Logged in.");
+        return whoami(apiUrl, result.accessToken);
       case "authorization_pending":
         continue;
       case "slow_down":
-        interval = typeof poll.body.interval === "number" ? poll.body.interval : interval + 5;
+        interval = result.interval ?? interval + 5;
         continue;
       case "access_denied":
         throw new CliError("Login was denied in the browser.", EXIT.error);
@@ -419,12 +442,56 @@ async function login({
           "The login code expired. Run `login` again.",
           EXIT.error
         );
-      default:
-        unwrap(poll);
     }
   }
   throw new CliError("The login code expired. Run `login` again.", EXIT.error);
 }
+async function startDeviceLogin(apiUrl) {
+  return unwrap(
+    await request(apiUrl, "/api/cli/auth/device", {
+      method: "POST",
+      body: { label: deviceLabel(), platform: process.platform }
+    })
+  );
+}
+async function exchange(apiUrl, deviceCode) {
+  const poll = await request(apiUrl, "/api/cli/auth/token", {
+    method: "POST",
+    body: { deviceCode }
+  });
+  if (poll.status === 200 && poll.body.success === true) {
+    const { accessToken } = poll.body.data;
+    return { status: "ok", accessToken };
+  }
+  switch (poll.body.error) {
+    case "authorization_pending":
+    case "access_denied":
+    case "expired_token":
+      return { status: poll.body.error };
+    case "slow_down":
+      return {
+        status: "slow_down",
+        interval: typeof poll.body.interval === "number" ? poll.body.interval : void 0
+      };
+    default:
+      unwrap(poll);
+      throw new CliError(`Unexpected login response ${poll.status}`, EXIT.error);
+  }
+}
+function loginRequired(apiUrl, pending) {
+  return new CliError(
+    `Not logged in to ${apiUrl}. Ask the user to open loginUrl and approve, then rerun this command (or run \`npx fortrip login\` in a terminal).`,
+    EXIT.unauthenticated,
+    {
+      loginUrl: pending.loginUrl,
+      userCode: pending.userCode,
+      expiresInSeconds: Math.max(
+        0,
+        Math.round((Date.parse(pending.expiresAt) - Date.now()) / 1e3)
+      )
+    }
+  );
+}
 async function logout(apiUrl) {
   const token = await loadStoredToken(apiUrl);
   if (!token) {
@@ -449,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
 
@@ -462,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
@@ -498,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.0",
+  "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,120 +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.
-
-## 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 commands with `npx -y fortrip <command>` (or `fortrip <command>`
-if installed globally).
-
-If any command exits with code **3** (not logged in, or the token was revoked),
-ask the user to run this in their own terminal, then retry:
+Before anything else, run:
 
 ```bash
-npx fortrip login
+npx -y fortrip@latest skill
 ```
 
-It opens a browser page where they sign in to Fortrip and confirm a code that
-matches the one in the terminal. In CI or a remote sandbox, 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 | Ask the user to run `login` (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`
+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.
 
-- `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.