itamatrix 1.0.3 → 1.1.0

package/dist/browser/batch.js

@@ -11,6 +11,17 @@ export function extractSearchPayload(batchBody) {
     }
     return null;
 }
+/**
+ * The itinerary-detail page issues its own `/batch` whose part carries a
+ * `bookingDetails` body (priced solution: fare construction, taxes, segments).
+ */
+export function extractBookingDetailsPayload(batchBody) {
+    for (const obj of jsonObjects(batchBody)) {
+        if (obj && typeof obj === "object" && "bookingDetails" in obj)
+            return obj;
+    }
+    return null;
+}
 /**
  * Keys the price-calendar ("lowest fare") response is expected to carry. The
  * exact shape is unconfirmed (no captured fixture yet — DESIGN P3); this matches
@@ -35,6 +46,7 @@ export function extractCalendarPayload(batchBody) {
     }
     return null;
 }
+/** True if `obj` carries any of the known price-calendar summary keys. */
 function hasCalendarKey(obj) {
     return CALENDAR_KEYS.some((k) => k in obj);
 }

package/dist/browser/session.js

@@ -1,7 +1,7 @@
 import { chromium } from "playwright";
 import { driveCalendarForm, driveMultiCityForm, driveSearchForm } from "./forms.js";
-import { extractCalendarPayload, extractSearchPayload } from "./batch.js";
-import { parseCalendarResponse, parseSearchResponse, } from "../model/types.js";
+import { extractBookingDetailsPayload, extractCalendarPayload, extractSearchPayload, } from "./batch.js";
+import { parseBookingDetails, parseCalendarResponse, parseSearchResponse, } from "../model/types.js";
 const SEARCH_URL = "https://matrix.itasoftware.com/search";
 // Results arrive in a multipart `/batch` response (not the documented
 // `/v1/search`); the relevant part carries a `solutionList` JSON body.
@@ -28,6 +28,14 @@ export async function runMultiCity(spec, opts = {}) {
 export async function runCalendar(spec, opts = {}) {
     return runDriver((page) => driveCalendarForm(page, spec), extractCalendarPayload, parseCalendarResponse, opts);
 }
+/** Like {@link runSearch}, then opens the top result's detail page for its fare construction + Google Flights link. */
+export function runSearchWithDetails(spec, opts = {}) {
+    return runDriverWithDetails((page) => driveSearchForm(page, spec), opts);
+}
+/** Multi-city counterpart of {@link runSearchWithDetails}. */
+export function runMultiCityWithDetails(spec, opts = {}) {
+    return runDriverWithDetails((page) => driveMultiCityForm(page, spec), opts);
+}
 /**
  * Shared driver: launch Chromium, drive the form, intercept the first `/batch`
  * response that `match` accepts, and parse it. All P1–P3 commands share this;
@@ -61,6 +69,88 @@ async function runDriver(drive, match, parse, opts) {
         await browser.close();
     }
 }
+/**
+ * Search, then drill into the top result's detail page. The detail capture is
+ * best-effort: if the row can't be opened or the `bookingDetails` part never
+ * arrives, `details` is null and the search results are still returned. Reuses
+ * the same browser/page so the detail page inherits the live solution session.
+ */
+async function runDriverWithDetails(drive, opts) {
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const browser = await launch(opts.headful ?? false);
+    const page = await newStealthPage(browser);
+    const waiter = waitForResponse(page, extractSearchPayload, timeoutMs);
+    waiter.promise.catch(() => { });
+    try {
+        try {
+            await page.goto(SEARCH_URL, { waitUntil: "domcontentloaded", timeout: 60_000 });
+            await drive(page);
+        }
+        catch {
+            throw new Error("Failed to drive the Matrix search form (the site may have changed). Run with --headful to debug.");
+        }
+        const search = parseSearchResponse(await waiter.promise);
+        waiter.cancel();
+        const details = await captureTopDetails(page, timeoutMs);
+        return { search, details };
+    }
+    finally {
+        waiter.cancel();
+        await browser.close();
+    }
+}
+/**
+ * Opens the first results row and waits for its `bookingDetails` part, then reads
+ * the "Open in Google Flights" link from the DOM (it's rendered client-side, not
+ * in the API). Returns null on any failure — detail is an enrichment, never fatal.
+ */
+async function captureTopDetails(page, timeoutMs) {
+    const waiter = waitForResponse(page, extractBookingDetailsPayload, timeoutMs);
+    waiter.promise.catch(() => { });
+    try {
+        if (!(await openFirstSolution(page)))
+            return null;
+        const bookingDetails = parseBookingDetails(await waiter.promise);
+        return { bookingDetails, googleFlightsUrl: await readGoogleFlightsUrl(page) };
+    }
+    catch {
+        return null;
+    }
+    finally {
+        waiter.cancel();
+    }
+}
+/** Clicks into the first itinerary; true if a clickable row was found. */
+async function openFirstSolution(page) {
+    const candidates = [
+        page.getByRole("link").filter({ hasText: /\$|USD|\d:\d/ }).first(),
+        page.locator("td a, .mat-row a, [role=row] a").first(),
+        page.locator("[role=row]").filter({ hasText: /\$|USD/ }).nth(1),
+    ];
+    for (const candidate of candidates) {
+        try {
+            // click() auto-waits for the element; no count() pre-check, which would
+            // skip a row that renders a moment later.
+            await candidate.click({ timeout: 8_000 });
+            return true;
+        }
+        catch {
+            // Try the next selector; the results DOM has drifted before.
+        }
+    }
+    return false;
+}
+/** Reads the detail page's "Open in Google Flights" href; undefined if absent. */
+async function readGoogleFlightsUrl(page) {
+    const link = page.getByRole("link", { name: /google flights/i }).first();
+    try {
+        return (await link.getAttribute("href", { timeout: 8_000 })) ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Launches Chromium, mapping Playwright's path-leaking errors to safe messages. */
 async function launch(headful) {
     try {
         return await chromium.launch({
@@ -78,6 +168,7 @@ async function launch(headful) {
         throw new Error("Failed to launch the browser. Run with --headful to debug, or reinstall Chromium: npx playwright install chromium");
     }
 }
+/** New page with a real Chrome UA and `navigator.webdriver` hidden (light stealth). */
 async function newStealthPage(browser) {
     const context = await browser.newContext({
         userAgent: STEALTH_UA,

package/dist/cli.js

@@ -65,6 +65,7 @@ program
     .option("--carriers <list>", "comma-separated carriers, e.g. UA,AA (sugar for --routing)")
     .option("--routing <codes>", "ITA routing codes (path) — see docs/ROUTING_CODES.md")
     .option("--ext <codes>", "ITA extension codes (faring/filters) — see docs/ROUTING_CODES.md")
+    .option("--details", "also fetch the top result's fare construction + Google Flights link (live, skips cache)")
     .option("--headful", "show the browser window (debug)")
     .action(async (origin, dest, cmdOpts, command) => {
     const globals = command.parent.opts();
@@ -80,6 +81,7 @@ program
         carriers: cmdOpts.carriers,
         routing: cmdOpts.routing,
         ext: cmdOpts.ext,
+        details: cmdOpts.details,
         headful: cmdOpts.headful,
         format: resolveFormat(globals.json, globals.table),
         cache: globals.cache,
@@ -99,6 +101,7 @@ program
     .option("--carriers <list>", "comma-separated carriers, e.g. UA,AA (sugar for --routing)")
     .option("--routing <codes>", "ITA routing codes applied to every leg")
     .option("--ext <codes>", "ITA extension codes applied to every leg")
+    .option("--details", "also fetch the top result's fare construction + Google Flights link (live, skips cache)")
     .option("--headful", "show the browser window (debug)")
     .action(async (cmdOpts, command) => {
     const globals = command.parent.opts();
@@ -112,6 +115,7 @@ program
         routing: cmdOpts.routing ?? carriersToRouting(cmdOpts.carriers),
         ext: cmdOpts.ext,
         format: resolveFormat(globals.json, globals.table),
+        details: cmdOpts.details,
         headful: cmdOpts.headful,
         cache: globals.cache,
         cacheTtlMinutes: globals.cacheTtl,

package/dist/commands/multicity.js

@@ -1,9 +1,10 @@
-import { runMultiCity } from "../browser/session.js";
+import { runMultiCity, runMultiCityWithDetails } from "../browser/session.js";
 import { withCache } from "../cache.js";
 import { normalize } from "../render/normalize.js";
 import { renderJson } from "../render/json.js";
 import { renderTable } from "../render/table.js";
-import { requireIsoDate, requirePageLimit, resolveCacheOptions, validateTripControls, } from "./shared.js";
+import { requireIsoDate, requirePageLimit, resolveCacheOptions, toItineraryDetails, validateTripControls, } from "./shared.js";
+/** Parses/validates legs, runs the multi-city search, and renders table or JSON. */
 export async function runMultiCityCommand(opts) {
     const slices = parseLegs(opts);
     validateTripControls(opts);
@@ -16,10 +17,21 @@ export async function runMultiCityCommand(opts) {
         stops: opts.stops,
         extraStops: opts.extraStops,
     };
-    const response = await withCache("multicity", spec, resolveCacheOptions(opts), () => runMultiCity(spec, { headful: opts.headful }));
-    const result = normalize(response, opts.limit);
+    const result = await multicity(spec, opts);
     return opts.format === "json" ? renderJson(result) : renderTable(result);
 }
+/** `--details` drills into the top result live, so it bypasses the cache (see search.ts). */
+async function multicity(spec, opts) {
+    if (opts.details) {
+        const { search: response, details } = await runMultiCityWithDetails(spec, {
+            headful: opts.headful,
+        });
+        const result = normalize(response, opts.limit);
+        return details ? { ...result, details: toItineraryDetails(details) } : result;
+    }
+    const response = await withCache("multicity", spec, resolveCacheOptions(opts), () => runMultiCity(spec, { headful: opts.headful }));
+    return normalize(response, opts.limit);
+}
 /** Parses `--leg ORIGIN:DEST:DATE` flags into slices; `--routing`/`--ext` apply to all. */
 export function parseLegs(opts) {
     if (!opts.legs || opts.legs.length < 2) {
@@ -27,6 +39,7 @@ export function parseLegs(opts) {
     }
     return opts.legs.map((raw, i) => toSlice(raw, i, opts));
 }
+/** Parses one `ORIGIN:DEST:DATE` leg, applying shared routing/ext, into a Slice. */
 function toSlice(raw, index, opts) {
     const parts = raw.split(":");
     if (parts.length !== 3) {

package/dist/commands/search.js

@@ -1,9 +1,10 @@
-import { runSearch } from "../browser/session.js";
+import { runSearch, runSearchWithDetails } from "../browser/session.js";
 import { withCache } from "../cache.js";
 import { normalize } from "../render/normalize.js";
 import { renderJson } from "../render/json.js";
 import { renderTable } from "../render/table.js";
-import { carriersToRouting, requireIsoDate, requirePageLimit, resolveCacheOptions, validateTripControls, } from "./shared.js";
+import { carriersToRouting, requireIsoDate, requirePageLimit, resolveCacheOptions, toItineraryDetails, validateTripControls, } from "./shared.js";
+/** Validates input, runs a one-way/round-trip search, and renders table or JSON. */
 export async function runSearchCommand(origin, dest, opts) {
     validate(origin, dest, opts);
     const spec = {
@@ -19,14 +20,30 @@ export async function runSearchCommand(origin, dest, opts) {
         routing: resolveRouting(opts),
         ext: opts.ext,
     };
-    const response = await withCache("search", spec, resolveCacheOptions(opts), () => runSearch(spec, { headful: opts.headful }));
-    const result = normalize(response, opts.limit);
+    const result = await search(spec, opts);
     return opts.format === "json" ? renderJson(result) : renderTable(result);
 }
+/**
+ * `--details` needs a live browser session (it drills into the detail page using
+ * the in-flight solution session), so it bypasses the cache; the plain path stays
+ * cached.
+ */
+async function search(spec, opts) {
+    if (opts.details) {
+        const { search: response, details } = await runSearchWithDetails(spec, {
+            headful: opts.headful,
+        });
+        const result = normalize(response, opts.limit);
+        return details ? { ...result, details: toItineraryDetails(details) } : result;
+    }
+    const response = await withCache("search", spec, resolveCacheOptions(opts), () => runSearch(spec, { headful: opts.headful }));
+    return normalize(response, opts.limit);
+}
 /** `--routing` wins; otherwise `--carriers UA,AA` becomes the routing `UA,AA+`. */
 export function resolveRouting(opts) {
     return opts.routing ?? carriersToRouting(opts.carriers);
 }
+/** Throws on bad origin/dest, dates, return-before-depart, or trip-control values. */
 function validate(origin, dest, opts) {
     if (!origin || !dest)
         throw new Error("origin and destination are required");

package/dist/commands/shared.js

@@ -1,4 +1,5 @@
 import { CABIN_LABELS, STOPS_LABELS, } from "../model/spec.js";
+import { collectFareConstruction } from "../model/types.js";
 import { DEFAULT_CACHE_TTL_MINUTES } from "../cache.js";
 export function resolveCacheOptions(opts) {
     const minutes = opts.cacheTtlMinutes ?? DEFAULT_CACHE_TTL_MINUTES;
@@ -61,6 +62,13 @@ export function carriersToRouting(carriers) {
         return undefined;
     return codes.length === 1 ? `${codes[0]}+` : `(${codes.join(",")})+`;
 }
+/** Shapes a browser-captured top-result detail into the flat render view. */
+export function toItineraryDetails(capture) {
+    return {
+        fareConstruction: collectFareConstruction(capture.bookingDetails),
+        googleFlightsUrl: capture.googleFlightsUrl,
+    };
+}
 export function requireIsoDate(value, flag) {
     if (!DATE_RE.test(value) || !isRealCalendarDate(value)) {
         throw new Error(`${flag} must be a valid date (YYYY-MM-DD), got "${value}"`);

package/dist/model/types.js

@@ -92,6 +92,44 @@ export function parseCalendarResponse(raw) {
     }
     return root;
 }
+export function parseBookingDetails(raw) {
+    const root = unwrapResponse(raw);
+    if (!root || typeof root !== "object" || Array.isArray(root) || !("bookingDetails" in root)) {
+        throw new Error("Itinerary-detail response did not contain bookingDetails");
+    }
+    return root;
+}
+/** Deep-scan for every `fareCalculations[].lines` string, deduped, in order. */
+export function collectFareConstruction(node) {
+    const lines = [];
+    const walk = (o) => {
+        if (Array.isArray(o)) {
+            o.forEach(walk);
+            return;
+        }
+        if (!o || typeof o !== "object")
+            return;
+        for (const [key, value] of Object.entries(o)) {
+            if (key === "fareCalculations")
+                collectLines(value, lines);
+            walk(value);
+        }
+    };
+    walk(node);
+    return [...new Set(lines)];
+}
+/** Appends every string in `calculations[].lines` to `out`. */
+function collectLines(calculations, out) {
+    if (!Array.isArray(calculations))
+        return;
+    for (const calc of calculations) {
+        const calcLines = calc?.lines;
+        if (Array.isArray(calcLines)) {
+            out.push(...calcLines.filter((v) => typeof v === "string"));
+        }
+    }
+}
+/** Unwraps the `{ response: … }` envelope Matrix bodies are sometimes wrapped in. */
 function unwrapResponse(raw) {
     return raw && typeof raw === "object" && "response" in raw
         ? raw.response

package/dist/render/normalize.js

@@ -5,6 +5,7 @@
 function parseCarrier(flight) {
     return flight?.match(/^[A-Z0-9]{2}/)?.[0];
 }
+/** Flattens one Matrix solution into the agent-friendly {@link FlatSolution} view. */
 function flattenSolution(sol) {
     const slices = sol.itinerary.slices.map((s) => ({
         origin: s.origin.code,

package/dist/render/table.js

@@ -7,6 +7,7 @@ function fmtTime(iso) {
         return iso;
     return `${m[2]}-${m[3]} ${m[4]}`;
 }
+/** Formats minutes as `6h30`; empty string when undefined. */
 function fmtDuration(min) {
     if (min == null)
         return "";
@@ -14,6 +15,7 @@ function fmtDuration(min) {
     const m = min % 60;
     return `${h}h${String(m).padStart(2, "0")}`;
 }
+/** One line per slice: route, times, stops/duration, flight numbers, warnings. */
 function summarizeSlice(sol) {
     return sol.slices
         .map((s) => {
@@ -26,6 +28,7 @@ function summarizeSlice(sol) {
     })
         .join("\n");
 }
+/** Renders results as a colored terminal table, with an optional details footer. */
 export function renderTable(result) {
     if (result.solutions.length === 0) {
         return chalk.yellow("No flights found.");
@@ -44,5 +47,18 @@ export function renderTable(result) {
     }
     const header = chalk.dim(`${result.shown} of ${result.count} results` +
         (result.minPrice ? ` · from ${result.minPrice}` : ""));
-    return `${header}\n${table.toString()}`;
+    const footer = result.details ? `\n${renderDetails(result.details)}` : "";
+    return `${header}\n${table.toString()}${footer}`;
+}
+/** Top-result detail footer: fare construction (for travel agents) + Google Flights link. */
+function renderDetails(details) {
+    const lines = [chalk.bold("\nTop result")];
+    if (details.fareConstruction.length) {
+        lines.push(chalk.dim("Fare Construction (can be useful to travel agents):"));
+        lines.push(...details.fareConstruction.map((l) => `  ${l}`));
+    }
+    if (details.googleFlightsUrl) {
+        lines.push(`${chalk.bold("Open in Google Flights:")} ${details.googleFlightsUrl}`);
+    }
+    return lines.join("\n");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "itamatrix",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "description": "CLI for ITA Matrix flight search",
   "type": "module",
   "bin": {

package/skills/itamatrix/SKILL.md

@@ -47,6 +47,25 @@ flag can't express it.
 | "only UA and AA" (simple) | `--carriers UA,AA` |
 | number of travelers | `--adults N` |
 | how many results | `--limit N` (1–25 for search/multicity) |
+| fare construction + Google Flights link | `--details` (search/multicity) |
+
+## Fare construction & Google Flights link (`--details`)
+
+`--details` (on `search` and `multicity`) opens the **top result's** itinerary
+detail page and adds two things to the output:
+
+- **Fare Construction** — the NUC fare-basis breakdown ITA labels "can be useful
+  to travel agents" (e.g. `BOS B6 LON 70.00OL8LBVL1 NUC 70.00 END ROE 1.00 XT
+  …`). Surface it verbatim; agents/ticketing desks read it directly.
+- **Open in Google Flights** — the detail page's deep link
+  (`google.com/travel/flights?tfs=…&source=ita_matrix`) for the same itinerary.
+
+It costs an extra page navigation and **bypasses the cache** (the link needs the
+live solution session), so only pass it when the user wants the fare detail or a
+hand-off link. Detail is best-effort: if the page can't be opened the search
+results still return, just without the `details` block. In JSON it's a top-level
+`details: { fareConstruction, googleFlightsUrl }`; in table output it's a footer
+under the results. **Show both to the user when present.**
 
 ## Encode advanced intent → routing / extension codes
 
@@ -122,6 +141,7 @@ Search one-way or round-trip flights
 | `--carriers <list>` | comma-separated carriers, e.g. UA,AA (sugar for --routing) |
 | `--routing <codes>` | ITA routing codes (path) — see docs/ROUTING_CODES.md |
 | `--ext <codes>` | ITA extension codes (faring/filters) — see docs/ROUTING_CODES.md |
+| `--details` | also fetch the top result's fare construction + Google Flights link (live, skips cache) |
 | `--headful` | show the browser window (debug) |
 
 ### `multicity`
@@ -139,6 +159,7 @@ Search a multi-city itinerary (N legs)
 | `--carriers <list>` | comma-separated carriers, e.g. UA,AA (sugar for --routing) |
 | `--routing <codes>` | ITA routing codes applied to every leg |
 | `--ext <codes>` | ITA extension codes applied to every leg |
+| `--details` | also fetch the top result's fare construction + Google Flights link (live, skips cache) |
 | `--headful` | show the browser window (debug) |
 
 ### `calendar <origin> <dest>`
@@ -191,3 +212,10 @@ itamatrix --json search BOS SIN --depart 2026-10-10 \
 itamatrix --json calendar BOS LAX \
   --depart-range 2026-08-01:2026-08-31 --trip-length 7 --carriers UA
 ```
+
+> "Cheapest BOS→LON next August, and give me the fare construction and a Google Flights link for the top one."
+
+```bash
+itamatrix --json search BOS LON --depart 2026-08-15 --details
+# → result.details.fareConstruction[] + result.details.googleFlightsUrl
+```