fortrip 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,66 @@
-# Temporary Holding Version
+# fortrip-cli
 
-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.
+Search, price and book Fortrip hotels from the terminal or an AI agent. The
+The npm package and the command are both `fortrip`.
+
+```bash
+npx fortrip login          # sign in through the browser
+npx fortrip search --query Bangkok --check-in 2026-11-10 --check-out 2026-11-12
+```
+
+Requires Node.js 22 or newer. No runtime dependencies.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `login [--no-browser]` | Device-code login: prints a code, opens `/cli/authorize`, waits for you to approve |
+| `logout` | Revokes the saved token on the server and deletes it locally |
+| `whoami` | The signed-in account |
+| `search` | Hotels with indicative prices |
+| `hotel <hotelId> [--with-rooms]` | Static hotel detail |
+| `rates` | Live rooms and rates |
+| `book` | Order + Stripe payment link |
+
+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.
+
+Output is JSON on stdout. Errors are JSON on stderr, with fixed exit codes:
+
+| Code | Meaning |
+|---|---|
+| 0 | Success |
+| 1 | Other error |
+| 2 | Invalid arguments (local or HTTP 400) |
+| 3 | Not logged in / token revoked (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.
+- `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`.
+
+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.
+
+## Development
+
+```bash
+pnpm install
+pnpm dev search --query Bangkok ...      # run from source
+pnpm test
+pnpm typecheck
+pnpm build                               # dist/cli.js
+```
+
+Point at a local Fortrip app with `FORTRIP_API_URL=http://localhost:3000`.

package/dist/cli.js

@@ -0,0 +1,575 @@
+#!/usr/bin/env node
+
+// src/errors.ts
+var EXIT = {
+  ok: 0,
+  error: 1,
+  usage: 2,
+  unauthenticated: 3,
+  rateLimited: 4
+};
+var CliError = class extends Error {
+  constructor(message, exitCode, details = {}) {
+    super(message);
+    this.exitCode = exitCode;
+    this.details = details;
+  }
+  exitCode;
+  details;
+};
+function usageError(message) {
+  return new CliError(message, EXIT.usage);
+}
+
+// src/version.ts
+var VERSION = "0.1.0";
+
+// src/api.ts
+var LOGIN_HINT = "Run `npx fortrip login` first.";
+var REQUEST_TIMEOUT_MS = 12e4;
+async function request(apiUrl, path, {
+  method = "GET",
+  token,
+  body
+} = {}) {
+  let response;
+  try {
+    response = await fetch(`${apiUrl}${path}`, {
+      method,
+      headers: {
+        accept: "application/json",
+        "user-agent": `fortrip-cli/${VERSION}`,
+        ...body !== void 0 ? { "content-type": "application/json" } : {},
+        ...token ? { authorization: `Bearer ${token}` } : {}
+      },
+      body: body !== void 0 ? JSON.stringify(body) : void 0,
+      // A redirect to another origin would drop the Authorization header and
+      // look like a logout; surface it instead.
+      redirect: "manual",
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
+    });
+  } catch (error) {
+    throw new CliError(
+      `Could not reach ${apiUrl}: ${error.message}`,
+      EXIT.error
+    );
+  }
+  const text = await response.text();
+  let parsed = null;
+  try {
+    parsed = text ? JSON.parse(text) : {};
+  } catch {
+    parsed = null;
+  }
+  const isObject = parsed !== null && typeof parsed === "object";
+  return {
+    status: response.status,
+    body: isObject ? parsed : { error: `Unexpected ${response.status} response`, raw: text.slice(0, 200) },
+    headers: response.headers
+  };
+}
+function unwrap(response) {
+  const { status, body, headers } = response;
+  if (status >= 200 && status < 300 && body.success === true) return body.data;
+  const { success: _success, error, message, ...rest } = body;
+  const text = typeof error === "string" ? error : typeof message === "string" ? message : `Request failed with status ${status}`;
+  const details = { status, ...rest };
+  if (status === 401) {
+    throw new CliError(`${text}. ${LOGIN_HINT}`, EXIT.unauthenticated, details);
+  }
+  if (status === 429) {
+    const retryAfter = Number(headers.get("retry-after"));
+    throw new CliError(text, EXIT.rateLimited, {
+      ...details,
+      ...Number.isFinite(retryAfter) && retryAfter > 0 ? { retryAfterSeconds: retryAfter } : {}
+    });
+  }
+  if (status === 400) throw new CliError(text, EXIT.usage, details);
+  if (status >= 300 && status < 400) {
+    throw new CliError(
+      `Unexpected redirect to ${headers.get("location") ?? "?"}; check FORTRIP_API_URL`,
+      EXIT.error,
+      details
+    );
+  }
+  throw new CliError(text, EXIT.error, details);
+}
+
+// src/args.ts
+import { readFileSync } from "fs";
+import { parseArgs } from "util";
+var BODY_OPTION = { body: { type: "string" } };
+function parse(argv, options) {
+  try {
+    return parseArgs({ args: argv, options, allowPositionals: true, strict: true });
+  } catch (error) {
+    throw usageError(error.message);
+  }
+}
+function baseBody(values) {
+  const raw = values.body;
+  if (typeof raw !== "string") return {};
+  let text = raw;
+  if (raw.startsWith("@")) {
+    try {
+      text = readFileSync(raw.slice(1), "utf8");
+    } catch (error) {
+      throw usageError(`Cannot read --body file: ${error.message}`);
+    }
+  }
+  try {
+    const parsed = JSON.parse(text);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed;
+    }
+  } catch {
+  }
+  throw usageError("--body must be a JSON object");
+}
+function num(flag, value) {
+  if (value === void 0) return void 0;
+  const parsed = Number(value);
+  if (value.trim() === "" || !Number.isFinite(parsed)) {
+    throw usageError(`--${flag} must be a number, got "${value}"`);
+  }
+  return parsed;
+}
+function nums(flag, values) {
+  if (!values?.length) return void 0;
+  return values.flatMap((value) => value.split(",")).map((value) => num(flag, value.trim()));
+}
+function str(value) {
+  return typeof value === "string" ? value : void 0;
+}
+function list(value) {
+  return Array.isArray(value) && value.length ? value : void 0;
+}
+function merge(base, overrides) {
+  const body = { ...base };
+  for (const [key, value] of Object.entries(overrides)) {
+    if (value !== void 0) body[key] = value;
+  }
+  return body;
+}
+var SEARCH_OPTIONS = {
+  ...BODY_OPTION,
+  query: { type: "string", short: "q" },
+  "city-code": { type: "string" },
+  near: { type: "string" },
+  "check-in": { type: "string" },
+  "check-out": { type: "string" },
+  "star-min": { type: "string" },
+  "star-max": { type: "string" },
+  facility: { type: "string", multiple: true },
+  "price-min": { type: "string" },
+  "price-max": { type: "string" },
+  sort: { type: "string" },
+  page: { type: "string" },
+  "page-size": { type: "string" }
+};
+function searchBody(values) {
+  let near;
+  const nearRaw = str(values.near);
+  if (nearRaw !== void 0) {
+    const [lat, lng, radiusKm] = nearRaw.split(",").map((part) => part.trim());
+    if (!lat || !lng || !radiusKm) {
+      throw usageError("--near must be lat,lng,radiusKm (e.g. 13.75,100.5,5)");
+    }
+    near = {
+      lat: num("near", lat),
+      lng: num("near", lng),
+      radiusKm: num("near", radiusKm)
+    };
+  }
+  return merge(baseBody(values), {
+    query: str(values.query),
+    cityCode: num("city-code", str(values["city-code"])),
+    near,
+    checkIn: str(values["check-in"]),
+    checkOut: str(values["check-out"]),
+    starMin: num("star-min", str(values["star-min"])),
+    starMax: num("star-max", str(values["star-max"])),
+    facilities: list(values.facility),
+    priceMin: num("price-min", str(values["price-min"])),
+    priceMax: num("price-max", str(values["price-max"])),
+    sortBy: str(values.sort),
+    page: num("page", str(values.page)),
+    pageSize: num("page-size", str(values["page-size"]))
+  });
+}
+var HOTEL_OPTIONS = {
+  "with-rooms": { type: "boolean" }
+};
+function hotelPath(positionals, values) {
+  const [id, ...extra] = positionals;
+  if (!id || extra.length || !/^\d+$/.test(id)) {
+    throw usageError("Usage: fortrip hotel <hotelId> [--with-rooms]");
+  }
+  return `/api/huizhi/hotels/${id}${values["with-rooms"] ? "?include=rooms" : ""}`;
+}
+var STAY_OPTIONS = {
+  "check-in": { type: "string" },
+  "check-out": { type: "string" },
+  rooms: { type: "string" },
+  adults: { type: "string" },
+  "child-age": { type: "string", multiple: true }
+};
+function stayFields(values, base) {
+  return {
+    checkIn: str(values["check-in"]),
+    checkOut: str(values["check-out"]),
+    rooms: num("rooms", str(values.rooms)) ?? (base.rooms === void 0 ? 1 : void 0),
+    adults: num("adults", str(values.adults)) ?? (base.adults === void 0 ? 2 : void 0),
+    childrenAges: nums("child-age", list(values["child-age"]))
+  };
+}
+var RATES_OPTIONS = {
+  ...BODY_OPTION,
+  ...STAY_OPTIONS,
+  hotel: { type: "string", multiple: true },
+  nationality: { type: "string" },
+  board: { type: "string", multiple: true },
+  "free-cancellation": { type: "boolean" },
+  "include-unbookable": { type: "boolean" },
+  "max-rooms": { type: "string" }
+};
+function ratesBody(values) {
+  const base = baseBody(values);
+  return merge(base, {
+    hotelIds: nums("hotel", list(values.hotel)),
+    ...stayFields(values, base),
+    nationality: str(values.nationality)?.toUpperCase(),
+    boardCodes: list(values.board)?.flatMap(
+      (code) => code.split(",").map((part) => part.trim().toUpperCase())
+    ),
+    freeCancellation: values["free-cancellation"] ? true : void 0,
+    bookableOnly: values["include-unbookable"] ? false : void 0,
+    maxRoomsPerHotel: num("max-rooms", str(values["max-rooms"]))
+  });
+}
+var BOOK_OPTIONS = {
+  ...BODY_OPTION,
+  ...STAY_OPTIONS,
+  hotel: { type: "string" },
+  "room-id": { type: "string" },
+  "rate-plan": { type: "string" },
+  guest: { type: "string", multiple: true },
+  "contact-name": { type: "string" },
+  "contact-phone": { type: "string" },
+  "contact-email": { type: "string" },
+  "special-requests": { type: "string" }
+};
+function parseGuest(value) {
+  const match = value.trim().match(/^(.+?)(?::(\d+))?$/);
+  const words = match?.[1]?.trim().split(/\s+/) ?? [];
+  if (words.length < 2) {
+    throw usageError(
+      `--guest must be "First Last" or "First Last:roomNo", got "${value}"`
+    );
+  }
+  return {
+    firstName: words.slice(0, -1).join(" "),
+    lastName: words.at(-1),
+    roomNo: match?.[2] ? Number(match[2]) : 1
+  };
+}
+function bookBody(values) {
+  const base = baseBody(values);
+  return merge(base, {
+    hotelId: num("hotel", str(values.hotel)),
+    roomId: str(values["room-id"]),
+    ratePlanCode: str(values["rate-plan"]),
+    ...stayFields(values, base),
+    guests: list(values.guest)?.map(parseGuest),
+    contactName: str(values["contact-name"]),
+    contactPhone: str(values["contact-phone"]),
+    contactEmail: str(values["contact-email"]),
+    specialRequests: str(values["special-requests"])
+  });
+}
+
+// src/auth.ts
+import { hostname } from "os";
+import { setTimeout as sleep } from "timers/promises";
+
+// src/browser.ts
+import { spawn } from "child_process";
+function openBrowser(url) {
+  const [command, args] = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["cmd", ["/c", "start", '""', url.replace(/&/g, "^&")]] : ["xdg-open", [url]];
+  try {
+    const child = spawn(command, args, { stdio: "ignore", detached: true });
+    child.on("error", () => {
+    });
+    child.unref();
+  } catch {
+  }
+}
+
+// src/credentials.ts
+import { chmod, mkdir, readFile, rm, writeFile } from "fs/promises";
+import { homedir } from "os";
+import { dirname, join } from "path";
+var DEFAULT_API_URL = "https://fortrip.ai";
+function credentialsPath(env = process.env) {
+  const base = env.XDG_CONFIG_HOME || join(homedir(), ".config");
+  return join(base, "fortrip", "credentials.json");
+}
+function resolveApiUrl(env = process.env) {
+  const raw = env.FORTRIP_API_URL?.trim() || DEFAULT_API_URL;
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw usageError(`FORTRIP_API_URL is not a valid URL: ${raw}`);
+  }
+  const isLocal = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && isLocal)) {
+    throw usageError("FORTRIP_API_URL must use https (http only for localhost)");
+  }
+  return url.origin;
+}
+async function readCredentials(path) {
+  try {
+    const parsed = JSON.parse(await readFile(path, "utf8"));
+    return { tokens: parsed?.tokens ?? {} };
+  } catch {
+    return { tokens: {} };
+  }
+}
+async function loadStoredToken(apiUrl, env = process.env) {
+  const file = await readCredentials(credentialsPath(env));
+  return file.tokens[apiUrl]?.accessToken ?? null;
+}
+async function resolveToken(apiUrl, env = process.env) {
+  const fromEnv = env.FORTRIP_TOKEN?.trim();
+  if (fromEnv) return { token: fromEnv, source: "env" };
+  const stored = await loadStoredToken(apiUrl, env);
+  return stored ? { token: stored, source: "file" } : null;
+}
+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);
+}
+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);
+}
+
+// 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);
+  }
+  return resolved.token;
+}
+async function login({
+  apiUrl,
+  openBrowser: shouldOpen,
+  log,
+  wait = sleep
+}) {
+  const start = unwrap(
+    await request(apiUrl, "/api/cli/auth/device", {
+      method: "POST",
+      body: { label: deviceLabel() }
+    })
+  );
+  log(`Confirm this code in your browser: ${start.userCode}`);
+  log(`If the browser doesn't open, visit: ${start.verificationUriComplete}`);
+  if (shouldOpen) openBrowser(start.verificationUriComplete);
+  log("Waiting for approval\u2026");
+  let interval = start.interval;
+  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) {
+      case "authorization_pending":
+        continue;
+      case "slow_down":
+        interval = typeof poll.body.interval === "number" ? poll.body.interval : interval + 5;
+        continue;
+      case "access_denied":
+        throw new CliError("Login was denied in the browser.", EXIT.error);
+      case "expired_token":
+        throw new CliError(
+          "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 logout(apiUrl) {
+  const token = await loadStoredToken(apiUrl);
+  if (!token) {
+    throw new CliError(`Not logged in to ${apiUrl}.`, EXIT.unauthenticated);
+  }
+  const response = await request(apiUrl, "/api/cli/auth/revoke", {
+    method: "POST",
+    token
+  });
+  if (response.status !== 401) unwrap(response);
+  await deleteToken(apiUrl);
+  return { loggedOut: true, apiUrl };
+}
+async function whoami(apiUrl, token) {
+  const resolved = token ?? await requireToken(apiUrl);
+  const data = unwrap(
+    await request(apiUrl, "/api/cli/auth/whoami", { token: resolved })
+  );
+  return { ...data, apiUrl };
+}
+function deviceLabel() {
+  return hostname().replace(/[^\w .@-]/g, "").slice(0, 64);
+}
+
+// src/cli.ts
+var HELP = `fortrip ${VERSION} \u2014 search, price and book Fortrip hotels
+
+Usage: fortrip <command> [options]
+
+Commands:
+  login [--no-browser]        Sign in through the browser (device code)
+  logout                      Revoke and forget the saved token
+  whoami                      Show the signed-in account
+  search                      Find hotels with indicative prices (CNY)
+  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
+
+search:  --query <text> | --city-code <n> | --near <lat,lng,km>
+         --check-in YYYY-MM-DD --check-out YYYY-MM-DD
+         [--star-min n] [--star-max n] [--facility <name>]... [--price-min n]
+         [--price-max n] [--sort recommended|price-asc|price-desc|star-desc|distance]
+         [--page n] [--page-size n]
+rates:   --hotel <id>... --check-in --check-out [--rooms 1] [--adults 2]
+         [--child-age n]... [--nationality CN] [--board BB]...
+         [--free-cancellation] [--include-unbookable] [--max-rooms n]
+book:    --hotel <id> --room-id <id> --rate-plan <code> --check-in --check-out
+         [--rooms 1] [--adults 2] [--child-age n]...
+         --guest "First Last[:roomNo]"... --contact-name <name>
+         --contact-phone <phone> [--contact-email <email>]
+         [--special-requests <english text>]
+
+search, rates and book also take --body '<json>' (or --body @file.json) with
+the raw request body; flags override its fields.
+
+Output is JSON on stdout; errors are JSON on stderr.
+Exit codes: 0 ok, 1 error, 2 invalid arguments, 3 not logged in, 4 rate limited.
+
+Environment:
+  FORTRIP_TOKEN    Use this token instead of the saved login (CI, sandboxes)
+  FORTRIP_API_URL  API base URL (default https://fortrip.ai)
+`;
+async function run(argv) {
+  const [command, ...rest] = argv;
+  if (!command || command === "help" || command === "--help" || command === "-h") {
+    process.stdout.write(HELP);
+    return void 0;
+  }
+  if (command === "--version" || command === "-v") {
+    process.stdout.write(`${VERSION}
+`);
+    return void 0;
+  }
+  const apiUrl = resolveApiUrl();
+  const log = (line) => process.stderr.write(`${line}
+`);
+  switch (command) {
+    case "login": {
+      const { values } = parse(rest, { "no-browser": { type: "boolean" } });
+      if (process.env.FORTRIP_TOKEN) {
+        log("Note: FORTRIP_TOKEN is set and takes precedence over this login.");
+      }
+      return login({ apiUrl, openBrowser: !values["no-browser"], log });
+    }
+    case "logout":
+      parse(rest, {});
+      return logout(apiUrl);
+    case "whoami":
+      parse(rest, {});
+      return whoami(apiUrl);
+    case "search": {
+      const { values } = parse(rest, SEARCH_OPTIONS);
+      return call(apiUrl, "POST", "/api/huizhi/search", searchBody(values));
+    }
+    case "hotel": {
+      const { values, positionals } = parse(rest, HOTEL_OPTIONS);
+      return call(apiUrl, "GET", hotelPath(positionals, values));
+    }
+    case "rates": {
+      const { values } = parse(rest, RATES_OPTIONS);
+      return call(apiUrl, "POST", "/api/huizhi/rates", ratesBody(values));
+    }
+    case "book": {
+      const { values } = parse(rest, BOOK_OPTIONS);
+      const data = await call(
+        apiUrl,
+        "POST",
+        "/api/huizhi/bookings",
+        bookBody(values)
+      );
+      return absolutize(apiUrl, data, ["orderUrl", "statusUrl"]);
+    }
+    default:
+      throw usageError(`Unknown command "${command}". Run \`fortrip --help\`.`);
+  }
+}
+async function call(apiUrl, method, path, body) {
+  const token = await requireToken(apiUrl);
+  return unwrap(await request(apiUrl, path, { method, token, body }));
+}
+function absolutize(apiUrl, data, keys) {
+  const out = { ...data };
+  for (const key of keys) {
+    const value = out[key];
+    if (typeof value === "string" && value.startsWith("/")) {
+      out[key] = `${apiUrl}${value}`;
+    }
+  }
+  return out;
+}
+async function main() {
+  try {
+    const result = await run(process.argv.slice(2));
+    if (result !== void 0) {
+      process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+    }
+    return EXIT.ok;
+  } catch (error) {
+    const failure = error instanceof CliError ? error : new CliError(error?.message ?? String(error), EXIT.error);
+    process.stderr.write(
+      `${JSON.stringify({ error: failure.message, exitCode: failure.exitCode, ...failure.details }, null, 2)}
+`
+    );
+    return failure.exitCode;
+  }
+}
+process.exitCode = await main();

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "fortrip",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Search, price and book Fortrip hotels from the terminal or an AI agent.",
+  "type": "module",
+  "bin": {
+    "fortrip": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/cli.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test test/*.test.ts",
+    "prepublishOnly": "pnpm typecheck && pnpm test && pnpm build"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "tsup": "^8.5.1",
+    "tsx": "^4.20.0",
+    "typescript": "^5.9.0"
+  },
+  "packageManager": "pnpm@11.21.0"
+}

package/skills/fortrip-hotels/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: fortrip-hotels
+description: Search hotels, compare live room rates and create a hotel booking with a payment link through Fortrip. Use when the user wants to find, price or book a hotel stay for specific dates, or asks for a hotel payment link.
+---
+
+# 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:
+
+```bash
+npx fortrip login
+```
+
+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`
+
+- `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`.