itamatrix 0.1.0

package/dist/browser/forms.js

@@ -0,0 +1,233 @@
+import { CABIN_LABELS, EXTRA_STOPS_LABELS, STOPS_LABELS, hasAdvancedControls, isRoundTrip, } from "../model/spec.js";
+/**
+ * Drives the Matrix search form and clicks Search.
+ *
+ * NOTE: this layer is intentionally thin and is the part most coupled to the
+ * live DOM (DESIGN.md "Trade-offs"). Selectors target the Angular Material
+ * markup observed on matrix.itasoftware.com/search. If Matrix restructures the
+ * form, failures surface here with a clear message.
+ */
+export async function driveSearchForm(page, spec) {
+    const roundTrip = isRoundTrip(spec);
+    await selectTripType(page, roundTrip);
+    await fillAirport(page, 0, spec.origin);
+    await fillAirport(page, 1, spec.dest);
+    await fillDates(page, spec.departDate, roundTrip ? spec.returnDate : undefined);
+    await setAdults(page, spec.adults);
+    await setAdvancedControls(page, spec, roundTrip);
+    await clickSearch(page);
+}
+/**
+ * Drives the multi-city form: selects the Multi-City tab, materialises one row
+ * per leg, fills each leg's origin/destination/date, then applies the shared
+ * cabin/stops controls and clicks Search. The response is the same
+ * `solutionList` shape as a normal search (N slices instead of 1–2).
+ */
+export async function driveMultiCityForm(page, spec) {
+    await page.getByRole("tab", { name: "Multi-City", exact: true }).click();
+    await ensureLegRows(page, spec.slices.length);
+    for (const [i, leg] of spec.slices.entries()) {
+        await fillAirport(page, 2 * i, leg.origin);
+        await fillAirport(page, 2 * i + 1, leg.dest);
+        await commitDate(page.locator("input.mat-datepicker-input").nth(i), leg.departDate);
+    }
+    await dismissOverlay(page);
+    await setAdults(page, spec.adults);
+    await setMultiCityAdvanced(page, spec);
+    await clickSearch(page);
+}
+/**
+ * Drives the price-calendar form: "See calendar of lowest fares" over a
+ * departure-date range. With `tripLength` it's a round-trip calendar; without,
+ * one-way. Selectors here are provisional — the calendar UI/response could not
+ * be captured for P3 (DESIGN), so this is the thinnest, most likely-to-drift
+ * layer; failures surface with a clear message.
+ */
+export async function driveCalendarForm(page, spec) {
+    const roundTrip = spec.tripLength != null;
+    await selectTripType(page, roundTrip);
+    await fillAirport(page, 0, spec.origin);
+    await fillAirport(page, 1, spec.dest);
+    await page
+        .getByText(/see calendar of lowest fares/i)
+        .first()
+        .click();
+    await commitDate(page.locator("input.mat-start-date"), spec.departFrom);
+    await commitDate(page.locator("input.mat-end-date"), spec.departTo);
+    if (spec.tripLength != null) {
+        const len = page.locator('input[formcontrolname="tripLength"]');
+        await len.fill(String(spec.tripLength));
+        await len.dispatchEvent("change");
+    }
+    await dismissOverlay(page);
+    await setAdults(page, spec.adults);
+    await setGlobalControls(page, spec, spec.routing, spec.ext, roundTrip);
+    await clickSearch(page);
+}
+/**
+ * Expands "Show Advanced Controls" and applies cabin/stops/routing/extension.
+ * All controls live behind this panel; we open it only when a control is set.
+ * Routing/extension are per-slice: Matrix mirrors them on the return slice
+ * (formcontrolname `routingRet`/`extRet`) for symmetric round-trips.
+ */
+async function setAdvancedControls(page, spec, roundTrip) {
+    if (!hasAdvancedControls(spec))
+        return;
+    await openAdvancedPanel(page);
+    await applyCabinStops(page, spec);
+    if (spec.routing) {
+        await fillFormControl(page, "routing", spec.routing);
+        if (roundTrip)
+            await fillFormControl(page, "routingRet", spec.routing);
+    }
+    if (spec.ext) {
+        await fillFormControl(page, "ext", spec.ext);
+        if (roundTrip)
+            await fillFormControl(page, "extRet", spec.ext);
+    }
+}
+/**
+ * Adds "Add another flight" rows until the form has `count` legs. Matrix shows
+ * two legs by default, so we only click for the extras.
+ */
+async function ensureLegRows(page, count) {
+    const addLeg = page.getByRole("button", { name: /add (another )?flight/i });
+    for (let existing = 2; existing < count; existing++) {
+        await addLeg.click();
+    }
+}
+/** Multi-city: shared cabin/stops globally, routing/ext per leg by row index. */
+async function setMultiCityAdvanced(page, spec) {
+    const perLeg = spec.slices.some((s) => s.routing || s.ext);
+    if (!hasGlobalControls(spec) && !perLeg)
+        return;
+    await openAdvancedPanel(page);
+    await applyCabinStops(page, spec);
+    for (const [i, leg] of spec.slices.entries()) {
+        if (leg.routing)
+            await fillIndexedControl(page, "routing", i, leg.routing);
+        if (leg.ext)
+            await fillIndexedControl(page, "ext", i, leg.ext);
+    }
+}
+/**
+ * Calendar: shared cabin/stops plus optional single routing/ext. Routing/ext are
+ * per-slice, so for a round-trip calendar they are mirrored onto the return slice
+ * (`routingRet`/`extRet`), matching `setAdvancedControls`.
+ */
+async function setGlobalControls(page, opts, routing, ext, roundTrip = false) {
+    if (!hasGlobalControls(opts) && !routing && !ext)
+        return;
+    await openAdvancedPanel(page);
+    await applyCabinStops(page, opts);
+    if (routing) {
+        await fillFormControl(page, "routing", routing);
+        if (roundTrip)
+            await fillFormControl(page, "routingRet", routing);
+    }
+    if (ext) {
+        await fillFormControl(page, "ext", ext);
+        if (roundTrip)
+            await fillFormControl(page, "extRet", ext);
+    }
+}
+function hasGlobalControls(opts) {
+    return Boolean(opts.cabin || opts.stops || opts.extraStops);
+}
+async function openAdvancedPanel(page) {
+    await page.getByRole("button", { name: /show advanced controls/i }).click();
+}
+async function applyCabinStops(page, opts) {
+    if (opts.cabin)
+        await selectOption(page, "cabin", CABIN_LABELS[opts.cabin]);
+    if (opts.stops)
+        await selectOption(page, "stops", STOPS_LABELS[opts.stops]);
+    if (opts.extraStops) {
+        await selectOption(page, "extraStops", EXTRA_STOPS_LABELS[opts.extraStops]);
+    }
+}
+/** Per-leg routing/ext share a formcontrolname across rows; target by index. */
+async function fillIndexedControl(page, control, index, value) {
+    const input = page.locator(`input[formcontrolname="${control}"]`).nth(index);
+    await input.fill(value);
+    await input.dispatchEvent("change");
+    await input.evaluate((el) => el.blur());
+}
+/** Open a Material <mat-select> by formcontrolname and click the labelled option. */
+async function selectOption(page, control, label) {
+    await page.locator(`mat-select[formcontrolname="${control}"]`).click();
+    await page.getByRole("option", { name: label, exact: true }).click();
+}
+async function fillFormControl(page, control, value) {
+    const input = page.locator(`input[formcontrolname="${control}"]`);
+    await input.fill(value);
+    await input.dispatchEvent("change");
+    await input.evaluate((el) => el.blur());
+}
+async function selectTripType(page, roundTrip) {
+    const name = roundTrip ? "Round Trip" : "One Way";
+    await page.getByRole("tab", { name, exact: true }).click();
+}
+/**
+ * Fills the nth "Add airport" combobox. Search uses 0/1 (origin/dest);
+ * multi-city uses 2·leg / 2·leg+1.
+ */
+async function fillAirport(page, index, code) {
+    const input = page.getByRole("combobox", { name: "Add airport" }).nth(index);
+    await input.click();
+    await input.fill("");
+    await input.type(code, { delay: 60 });
+    const option = page.getByRole("option").first();
+    await option.waitFor({ state: "visible", timeout: 15_000 });
+    await option.click();
+}
+/**
+ * The start/end inputs share one Material date-range picker (a single calendar
+ * overlay). `fill()` writes the value without a pointer click, so the overlay
+ * backdrop can't intercept it; clicking the backdrop afterwards commits the
+ * typed values (blur) and closes the calendar — Escape would cancel them.
+ * Values are M/D/YYYY (en-US locale).
+ */
+async function fillDates(page, departIso, returnIso) {
+    if (returnIso) {
+        // Round-trip: a date-range picker with start/end inner inputs.
+        await commitDate(page.locator("input.mat-start-date"), departIso);
+        await commitDate(page.locator("input.mat-end-date"), returnIso);
+    }
+    else {
+        // One-way: a single datepicker input.
+        await commitDate(page.locator("input.mat-datepicker-input"), departIso);
+    }
+    await dismissOverlay(page);
+}
+/** Clicks the calendar backdrop (if open) to commit typed dates and close it. */
+async function dismissOverlay(page) {
+    const backdrop = page.locator(".cdk-overlay-backdrop").last();
+    if (await backdrop.count())
+        await backdrop.click({ force: true });
+}
+/** fill() sets the value; blur fires Material's date parse/validation. */
+async function commitDate(input, isoDate) {
+    await input.fill(toUsDate(isoDate));
+    await input.dispatchEvent("change");
+    await input.evaluate((el) => el.blur());
+}
+function toUsDate(iso) {
+    const [y, m, d] = iso.split("-");
+    return `${Number(m)}/${Number(d)}/${y}`;
+}
+async function setAdults(page, adults) {
+    if (adults === 1)
+        return; // Matrix default.
+    // Exclude the calendar trip-length field, which is also a numeric input and
+    // would otherwise be matched first, swapping the nights and adults values.
+    const input = page
+        .locator('input[type="number"]:not([formcontrolname="tripLength"])')
+        .first();
+    await input.fill(String(adults));
+    await input.dispatchEvent("change");
+}
+async function clickSearch(page) {
+    await page.getByRole("button", { name: /search/i }).last().click();
+}
+//# sourceMappingURL=forms.js.map

package/dist/browser/forms.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"forms.js","sourceRoot":"","sources":["../../src/browser/forms.ts"],"names":[],"mappings":"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"}

package/dist/browser/session.d.ts

@@ -0,0 +1,20 @@
+import type { CalendarSpec, MultiCitySpec, SearchSpec } from "../model/spec.js";
+import { type CalendarResponse, type SearchResponse } from "../model/types.js";
+export interface SessionOptions {
+    /** Show the browser window (debugging). Default headless. */
+    headful?: boolean;
+    /** Max time to wait for the /v1/search response. Matrix is slow (40–60s). */
+    timeoutMs?: number;
+}
+/**
+ * One-shot Matrix search: launch Chromium, drive the form, intercept the
+ * `/v1/search` response, and return the parsed payload.
+ *
+ * Bundled headless Chromium works with light stealth (real Chrome UA, hide
+ * navigator.webdriver) — Google's BotGuard JS still runs and mints the token.
+ */
+export declare function runSearch(spec: SearchSpec, opts?: SessionOptions): Promise<SearchResponse>;
+/** Multi-city search (DESIGN P3): same `solutionList` response as `runSearch`. */
+export declare function runMultiCity(spec: MultiCitySpec, opts?: SessionOptions): Promise<SearchResponse>;
+/** Price-calendar search (DESIGN P3): lowest fare per departure date. */
+export declare function runCalendar(spec: CalendarSpec, opts?: SessionOptions): Promise<CalendarResponse>;

package/dist/browser/session.js

@@ -0,0 +1,126 @@
+import { chromium } from "playwright";
+import { driveCalendarForm, driveMultiCityForm, driveSearchForm } from "./forms.js";
+import { extractCalendarPayload, extractSearchPayload } from "./batch.js";
+import { 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.
+const SEARCH_API_RE = /content-alkalimatrix-pa\.googleapis\.com\/batch/;
+const DEFAULT_TIMEOUT_MS = 120_000;
+// A real desktop-Chrome UA (no "Headless"); BotGuard rejects the headless UA.
+const STEALTH_UA = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 " +
+    "(KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36";
+/**
+ * One-shot Matrix search: launch Chromium, drive the form, intercept the
+ * `/v1/search` response, and return the parsed payload.
+ *
+ * Bundled headless Chromium works with light stealth (real Chrome UA, hide
+ * navigator.webdriver) — Google's BotGuard JS still runs and mints the token.
+ */
+export async function runSearch(spec, opts = {}) {
+    return runDriver((page) => driveSearchForm(page, spec), extractSearchPayload, parseSearchResponse, opts);
+}
+/** Multi-city search (DESIGN P3): same `solutionList` response as `runSearch`. */
+export async function runMultiCity(spec, opts = {}) {
+    return runDriver((page) => driveMultiCityForm(page, spec), extractSearchPayload, parseSearchResponse, opts);
+}
+/** Price-calendar search (DESIGN P3): lowest fare per departure date. */
+export async function runCalendar(spec, opts = {}) {
+    return runDriver((page) => driveCalendarForm(page, spec), extractCalendarPayload, parseCalendarResponse, 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;
+ * they differ only in how the form is driven and which payload is extracted.
+ */
+async function runDriver(drive, match, parse, opts) {
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const browser = await launch(opts.headful ?? false);
+    const page = await newStealthPage(browser);
+    const waiter = waitForResponse(page, match, timeoutMs);
+    // Never let an unobserved rejection (e.g. browser closed on form failure)
+    // crash the process; the real error is surfaced below.
+    waiter.promise.catch(() => { });
+    try {
+        try {
+            await page.goto(SEARCH_URL, { waitUntil: "domcontentloaded", timeout: 60_000 });
+            await drive(page);
+        }
+        catch {
+            // Navigation/form-driving failures are Playwright errors that leak
+            // selectors and local paths; surface a concise, user-safe message.
+            throw new Error("Failed to drive the Matrix search form (the site may have changed). Run with --headful to debug.");
+        }
+        const raw = await waiter.promise;
+        return parse(raw);
+    }
+    finally {
+        // Cancel first: a form/nav failure must clear the pending timeout so the
+        // process can exit immediately instead of waiting out `timeoutMs`.
+        waiter.cancel();
+        await browser.close();
+    }
+}
+async function launch(headful) {
+    try {
+        return await chromium.launch({
+            headless: !headful,
+            args: ["--disable-blink-features=AutomationControlled"],
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (/Executable doesn't exist|playwright install/i.test(msg)) {
+            throw new Error("Chromium is not installed. Run: npx playwright install chromium");
+        }
+        // Raw Playwright launch errors leak the browser command and local paths;
+        // surface a concise, user-safe message instead.
+        throw new Error("Failed to launch the browser. Run with --headful to debug, or reinstall Chromium: npx playwright install chromium");
+    }
+}
+async function newStealthPage(browser) {
+    const context = await browser.newContext({
+        userAgent: STEALTH_UA,
+        viewport: { width: 1280, height: 900 },
+    });
+    await context.addInitScript(() => {
+        Object.defineProperty(navigator, "webdriver", { get: () => undefined });
+    });
+    return context.newPage();
+}
+/**
+ * Resolves with the payload from the first `/batch` response whose body `match`
+ * accepts. Many `/batch` calls fire (autocomplete, facets), so we inspect
+ * bodies rather than match on URL alone. The returned `cancel` must be called
+ * once the caller is done (success or failure) to clear the pending timeout.
+ */
+function waitForResponse(page, match, timeoutMs) {
+    let cancel = () => { };
+    const promise = new Promise((resolve, reject) => {
+        const onResponse = (res) => {
+            if (!SEARCH_API_RE.test(res.url()) || res.status() !== 200)
+                return;
+            res
+                .text()
+                .then((body) => {
+                const payload = match(body);
+                if (!payload)
+                    return;
+                cancel();
+                resolve(payload);
+            })
+                .catch(() => { });
+        };
+        const timer = setTimeout(() => {
+            cancel();
+            reject(new Error(`Timed out after ${timeoutMs}ms waiting for search results`));
+        }, timeoutMs);
+        cancel = () => {
+            clearTimeout(timer);
+            page.off("response", onResponse);
+        };
+        page.on("response", onResponse);
+    });
+    return { promise, cancel: () => cancel() };
+}
+//# sourceMappingURL=session.js.map

package/dist/browser/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/browser/session.ts"],"names":[],"mappings":"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"}

package/dist/cache.d.ts

@@ -0,0 +1,21 @@
+/**
+ * File-based result cache. Matrix queries take 30–60 s and are driven by a
+ * browser, so repeat queries for the same spec are expensive; caching the raw
+ * parsed response makes them instant (DESIGN P4). The cache key is the spec, so
+ * output format is irrelevant — render happens after the cache layer.
+ */
+export interface CacheOptions {
+    /** When false, `withCache` always calls the producer and skips read/write. */
+    enabled: boolean;
+    /** Entries older than this are treated as misses. */
+    ttlMs: number;
+}
+export declare const DEFAULT_CACHE_TTL_MINUTES = 60;
+/** `$XDG_CACHE_HOME/itamatrix` → `~/.cache/itamatrix` → `$TMPDIR/itamatrix`. */
+export declare function cacheDir(): string;
+/**
+ * Return a cached response for `keyParts` if present and fresh, otherwise call
+ * `produce`, cache its result, and return it. Caching is best-effort: any I/O
+ * error degrades to calling `produce` directly.
+ */
+export declare function withCache<T>(namespace: string, keyParts: unknown, opts: CacheOptions, produce: () => Promise<T>): Promise<T>;

package/dist/cache.js

@@ -0,0 +1,71 @@
+import { createHash } from "node:crypto";
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+export const DEFAULT_CACHE_TTL_MINUTES = 60;
+/** `$XDG_CACHE_HOME/itamatrix` → `~/.cache/itamatrix` → `$TMPDIR/itamatrix`. */
+export function cacheDir() {
+    const xdg = process.env.XDG_CACHE_HOME;
+    if (xdg)
+        return join(xdg, "itamatrix");
+    const home = homedir();
+    if (home)
+        return join(home, ".cache", "itamatrix");
+    return join(tmpdir(), "itamatrix");
+}
+function hashKey(namespace, keyParts) {
+    const digest = createHash("sha256")
+        .update(namespace)
+        .update("\0")
+        .update(JSON.stringify(keyParts))
+        .digest("hex");
+    return `${namespace}-${digest}`;
+}
+function entryPath(key) {
+    return join(cacheDir(), `${key}.json`);
+}
+function readEntry(key, ttlMs, now) {
+    const path = entryPath(key);
+    if (!existsSync(path))
+        return null;
+    try {
+        const entry = JSON.parse(readFileSync(path, "utf8"));
+        if (typeof entry?.savedAt !== "number" || !("value" in entry))
+            return null;
+        if (now - entry.savedAt > ttlMs)
+            return null;
+        return entry.value;
+    }
+    catch {
+        // Corrupt/unreadable cache file: treat as a miss, never fail the query.
+        return null;
+    }
+}
+function writeEntry(key, value, now) {
+    try {
+        mkdirSync(cacheDir(), { recursive: true });
+        const entry = { savedAt: now, value };
+        writeFileSync(entryPath(key), JSON.stringify(entry));
+    }
+    catch {
+        // Cache is best-effort; a write failure must not break the command.
+    }
+}
+/**
+ * Return a cached response for `keyParts` if present and fresh, otherwise call
+ * `produce`, cache its result, and return it. Caching is best-effort: any I/O
+ * error degrades to calling `produce` directly.
+ */
+export async function withCache(namespace, keyParts, opts, produce) {
+    if (!opts.enabled)
+        return produce();
+    const key = hashKey(namespace, keyParts);
+    const now = Date.now();
+    const hit = readEntry(key, opts.ttlMs, now);
+    if (hit !== null)
+        return hit;
+    const value = await produce();
+    writeEntry(key, value, now);
+    return value;
+}
+//# sourceMappingURL=cache.js.map

package/dist/cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.js","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"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"}

package/dist/cache.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cache.test.js

@@ -0,0 +1,79 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { withCache, cacheDir, DEFAULT_CACHE_TTL_MINUTES } from "./cache.js";
+let dir;
+let prevXdg;
+beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "itamatrix-cache-"));
+    prevXdg = process.env.XDG_CACHE_HOME;
+    process.env.XDG_CACHE_HOME = dir;
+});
+afterEach(() => {
+    if (prevXdg === undefined)
+        delete process.env.XDG_CACHE_HOME;
+    else
+        process.env.XDG_CACHE_HOME = prevXdg;
+    rmSync(dir, { recursive: true, force: true });
+});
+const opts = { enabled: true, ttlMs: DEFAULT_CACHE_TTL_MINUTES * 60_000 };
+describe("withCache", () => {
+    it("returns the cache dir under XDG_CACHE_HOME", () => {
+        expect(cacheDir()).toBe(join(dir, "itamatrix"));
+    });
+    it("calls the producer once and serves the second call from cache", async () => {
+        const produce = vi.fn().mockResolvedValue({ price: 100 });
+        const first = await withCache("search", { o: "BOS" }, opts, produce);
+        const second = await withCache("search", { o: "BOS" }, opts, produce);
+        expect(first).toEqual({ price: 100 });
+        expect(second).toEqual({ price: 100 });
+        expect(produce).toHaveBeenCalledTimes(1);
+    });
+    it("treats a different key as a miss", async () => {
+        const produce = vi.fn().mockResolvedValue({ price: 100 });
+        await withCache("search", { o: "BOS" }, opts, produce);
+        await withCache("search", { o: "JFK" }, opts, produce);
+        expect(produce).toHaveBeenCalledTimes(2);
+    });
+    it("separates entries by namespace", async () => {
+        const produce = vi.fn().mockResolvedValue({ price: 100 });
+        await withCache("search", { x: 1 }, opts, produce);
+        await withCache("calendar", { x: 1 }, opts, produce);
+        expect(produce).toHaveBeenCalledTimes(2);
+    });
+    it("bypasses cache entirely when disabled", async () => {
+        const produce = vi.fn().mockResolvedValue({ price: 100 });
+        const off = { enabled: false, ttlMs: 60_000 };
+        await withCache("search", { o: "BOS" }, off, produce);
+        await withCache("search", { o: "BOS" }, off, produce);
+        expect(produce).toHaveBeenCalledTimes(2);
+    });
+    it("treats a JSON file of the wrong shape as a miss", async () => {
+        const produce = vi.fn().mockResolvedValue({ price: 100 });
+        mkdirSync(join(dir, "itamatrix"), { recursive: true });
+        // Mirror the key derivation: namespace + sha256(namespace \0 JSON(parts)).
+        const parts = { o: "BOS" };
+        const digest = createHash("sha256")
+            .update("search")
+            .update("\0")
+            .update(JSON.stringify(parts))
+            .digest("hex");
+        writeFileSync(join(dir, "itamatrix", `search-${digest}.json`), "{}");
+        const result = await withCache("search", parts, opts, produce);
+        expect(result).toEqual({ price: 100 });
+        expect(produce).toHaveBeenCalledTimes(1);
+    });
+    it("re-fetches once the entry is older than the TTL", async () => {
+        const produce = vi.fn().mockResolvedValue({ price: 100 });
+        const base = 1_000_000;
+        vi.spyOn(Date, "now").mockReturnValue(base);
+        await withCache("search", { o: "BOS" }, { enabled: true, ttlMs: 1000 }, produce);
+        vi.spyOn(Date, "now").mockReturnValue(base + 2000);
+        await withCache("search", { o: "BOS" }, { enabled: true, ttlMs: 1000 }, produce);
+        expect(produce).toHaveBeenCalledTimes(2);
+        vi.restoreAllMocks();
+    });
+});
+//# sourceMappingURL=cache.test.js.map

package/dist/cache.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.test.js","sourceRoot":"","sources":["../src/cache.test.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+export declare const program: Command;