itamatrix 0.1.0

package/dist/commands/search.test.js

@@ -0,0 +1,124 @@
+import { describe, it, expect, vi } from "vitest";
+import { resolveRouting, runSearchCommand } from "./search.js";
+const captured = [];
+vi.mock("../browser/session.js", () => ({
+    runSearch: (spec) => {
+        captured.push(spec);
+        return Promise.resolve({ solutionList: { solutions: [] } });
+    },
+}));
+const opts = (over = {}) => ({
+    depart: "2026-08-10",
+    adults: 1,
+    limit: 25,
+    format: "json",
+    cache: false,
+    ...over,
+});
+// These all fail validation before any browser launch, so they stay deterministic.
+describe("runSearchCommand validation", () => {
+    it("rejects a missing origin/destination", async () => {
+        await expect(runSearchCommand("", "LAX", opts())).rejects.toThrow(/required/);
+    });
+    it("rejects a malformed --depart", async () => {
+        await expect(runSearchCommand("BOS", "LAX", opts({ depart: "08-10-2026" }))).rejects.toThrow(/--depart must be a valid date/);
+    });
+    it("rejects a malformed --return", async () => {
+        await expect(runSearchCommand("BOS", "LAX", opts({ return: "2026/08/17" }))).rejects.toThrow(/--return must be a valid date/);
+    });
+    it("rejects an impossible calendar date", async () => {
+        await expect(runSearchCommand("BOS", "LAX", opts({ depart: "2026-13-99" }))).rejects.toThrow(/--depart must be a valid date/);
+    });
+    it("rejects a --return earlier than --depart", async () => {
+        await expect(runSearchCommand("BOS", "LAX", opts({ return: "2026-08-01" }))).rejects.toThrow(/--return must be on or after --depart/);
+    });
+    it("rejects adults < 1", async () => {
+        await expect(runSearchCommand("BOS", "LAX", opts({ adults: 0 }))).rejects.toThrow(/--adults must be an integer >= 1/);
+    });
+    it("rejects a non-numeric --adults (NaN) before launching the browser", async () => {
+        await expect(runSearchCommand("BOS", "LAX", opts({ adults: NaN }))).rejects.toThrow(/--adults must be an integer >= 1/);
+    });
+    it("rejects an invalid --limit", async () => {
+        await expect(runSearchCommand("BOS", "LAX", opts({ limit: 0 }))).rejects.toThrow(/--limit must be an integer >= 1/);
+    });
+    it("rejects a --limit above the single-page maximum", async () => {
+        await expect(runSearchCommand("BOS", "LAX", opts({ limit: 50 }))).rejects.toThrow(/--limit cannot exceed 25/);
+    });
+    it("ignores a malformed --return when --one-way is set", async () => {
+        const out = await runSearchCommand("BOS", "LAX", opts({ return: "not-a-date", oneWay: true }));
+        expect(out).toContain("\"solutions\"");
+    });
+    it("rejects an unknown --cabin", async () => {
+        await expect(runSearchCommand("BOS", "LAX", opts({ cabin: "economy" }))).rejects.toThrow(/--cabin must be one of/);
+    });
+    it("rejects an unknown --stops", async () => {
+        await expect(runSearchCommand("BOS", "LAX", opts({ stops: "3" }))).rejects.toThrow(/--stops must be one of/);
+    });
+    it("rejects an unknown --extra-stops", async () => {
+        await expect(runSearchCommand("BOS", "LAX", opts({ extraStops: "lots" }))).rejects.toThrow(/--extra-stops must be one of/);
+    });
+});
+describe("resolveRouting (--carriers sugar)", () => {
+    it("turns multiple --carriers into a grouped OR'd routing code", () => {
+        expect(resolveRouting({ carriers: "ua,aa" })).toBe("(UA,AA)+");
+    });
+    it("does not group a single carrier", () => {
+        expect(resolveRouting({ carriers: "ua" })).toBe("UA+");
+    });
+    it("lets explicit --routing win over --carriers", () => {
+        expect(resolveRouting({ carriers: "UA,AA", routing: "X:DFW" })).toBe("X:DFW");
+    });
+    it("trims whitespace and drops empties between carriers", () => {
+        expect(resolveRouting({ carriers: " ua , , aa " })).toBe("(UA,AA)+");
+    });
+    it("is undefined for an all-empty --carriers", () => {
+        expect(resolveRouting({ carriers: " , " })).toBeUndefined();
+    });
+    it("is undefined when neither is given", () => {
+        expect(resolveRouting({})).toBeUndefined();
+    });
+});
+describe("runSearchCommand spec wiring", () => {
+    const opts = (over = {}) => ({
+        depart: "2026-08-10",
+        adults: 1,
+        limit: 25,
+        format: "json",
+        cache: false,
+        ...over,
+    });
+    it("passes advanced controls and uppercases airports", async () => {
+        captured.length = 0;
+        await runSearchCommand("bos", "lax", opts({ cabin: "business", stops: "1", ext: "-REDEYES" }));
+        expect(captured[0]).toMatchObject({
+            origin: "BOS",
+            dest: "LAX",
+            cabin: "business",
+            stops: "1",
+            ext: "-REDEYES",
+        });
+    });
+    it("folds --carriers into the routing field", async () => {
+        captured.length = 0;
+        await runSearchCommand("BOS", "LAX", opts({ carriers: "UA,AA" }));
+        expect(captured[0].routing).toBe("(UA,AA)+");
+    });
+    it("drops the return date when --one-way is set", async () => {
+        captured.length = 0;
+        await runSearchCommand("BOS", "LAX", opts({ return: "2026-08-17", oneWay: true }));
+        expect(captured[0].returnDate).toBeUndefined();
+    });
+    it("leaves advanced controls undefined when unset", async () => {
+        captured.length = 0;
+        await runSearchCommand("BOS", "LAX", opts());
+        const s = captured[0];
+        expect([s.cabin, s.stops, s.extraStops, s.routing, s.ext]).toEqual([
+            undefined,
+            undefined,
+            undefined,
+            undefined,
+            undefined,
+        ]);
+    });
+});
+//# sourceMappingURL=search.test.js.map

package/dist/commands/search.test.js.map

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

package/dist/commands/shared.d.ts

@@ -0,0 +1,44 @@
+import { type Cabin, type StopLimit } from "../model/spec.js";
+import { type CacheOptions } from "../cache.js";
+export type OutputFormat = "table" | "json";
+/** Cache controls shared by every command (`--no-cache`, `--cache-ttl`). */
+export interface CacheControlOptions {
+    /** Default true; `--no-cache` sets it false. */
+    cache?: boolean;
+    /** TTL in minutes; defaults to {@link DEFAULT_CACHE_TTL_MINUTES}. */
+    cacheTtlMinutes?: number;
+}
+export declare function resolveCacheOptions(opts: CacheControlOptions): CacheOptions;
+export declare const DATE_RE: RegExp;
+/**
+ * The driver reads a single Matrix results page; pagination isn't driven, so a
+ * `--limit` above the page size can't be honored. Cap it instead of silently
+ * returning fewer results than asked. (Multi-page fetch is future work.)
+ */
+export declare const MAX_LIMIT = 25;
+export declare const CABINS: Cabin[];
+export declare const STOPS: StopLimit[];
+/** Shared cabin/stops/extra-stops/adults/limit validation across all commands. */
+export interface TripControlOptions {
+    adults: number;
+    limit: number;
+    cabin?: string;
+    stops?: string;
+    extraStops?: string;
+}
+export declare function validateTripControls(opts: TripControlOptions): void;
+/**
+ * Reject a page-size `--limit` above {@link MAX_LIMIT}. Used by the page-based
+ * commands (search, multicity); calendar's `--limit` is a display cap, not a page
+ * size, so it does not call this.
+ */
+export declare function requirePageLimit(limit: number): void;
+/**
+ * `--carriers UA,AA` → `(UA,AA)+`: one or more segments on *any* listed carrier.
+ * The alternatives must be grouped before the `+` repeat operator, otherwise ITA
+ * reads `UA,AA+` as "a single UA segment, or one-or-more AA segments", which
+ * drops valid connecting itineraries (e.g. all-UA multi-leg). Returns undefined
+ * when no carriers are given.
+ */
+export declare function carriersToRouting(carriers?: string): string | undefined;
+export declare function requireIsoDate(value: string, flag: string): void;

package/dist/commands/shared.js

@@ -0,0 +1,77 @@
+import { CABIN_LABELS, STOPS_LABELS, } from "../model/spec.js";
+import { DEFAULT_CACHE_TTL_MINUTES } from "../cache.js";
+export function resolveCacheOptions(opts) {
+    const minutes = opts.cacheTtlMinutes ?? DEFAULT_CACHE_TTL_MINUTES;
+    if (!Number.isFinite(minutes) || minutes < 0) {
+        throw new Error("--cache-ttl must be a number >= 0 (minutes)");
+    }
+    return { enabled: opts.cache !== false, ttlMs: minutes * 60_000 };
+}
+export const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+/**
+ * The driver reads a single Matrix results page; pagination isn't driven, so a
+ * `--limit` above the page size can't be honored. Cap it instead of silently
+ * returning fewer results than asked. (Multi-page fetch is future work.)
+ */
+export const MAX_LIMIT = 25;
+export const CABINS = Object.keys(CABIN_LABELS);
+export const STOPS = Object.keys(STOPS_LABELS);
+export function validateTripControls(opts) {
+    if (!Number.isInteger(opts.adults) || opts.adults < 1) {
+        throw new Error("--adults must be an integer >= 1");
+    }
+    if (!Number.isInteger(opts.limit) || opts.limit < 1) {
+        throw new Error("--limit must be an integer >= 1");
+    }
+    if (opts.cabin && !CABINS.includes(opts.cabin)) {
+        throw new Error(`--cabin must be one of ${CABINS.join(", ")}, got "${opts.cabin}"`);
+    }
+    if (opts.stops && !STOPS.includes(opts.stops)) {
+        throw new Error(`--stops must be one of ${STOPS.join(", ")}, got "${opts.stops}"`);
+    }
+    if (opts.extraStops && !STOPS.includes(opts.extraStops)) {
+        throw new Error(`--extra-stops must be one of ${STOPS.join(", ")}, got "${opts.extraStops}"`);
+    }
+}
+/**
+ * Reject a page-size `--limit` above {@link MAX_LIMIT}. Used by the page-based
+ * commands (search, multicity); calendar's `--limit` is a display cap, not a page
+ * size, so it does not call this.
+ */
+export function requirePageLimit(limit) {
+    if (limit > MAX_LIMIT) {
+        throw new Error(`--limit cannot exceed ${MAX_LIMIT} (one Matrix results page; pagination is not yet supported)`);
+    }
+}
+/**
+ * `--carriers UA,AA` → `(UA,AA)+`: one or more segments on *any* listed carrier.
+ * The alternatives must be grouped before the `+` repeat operator, otherwise ITA
+ * reads `UA,AA+` as "a single UA segment, or one-or-more AA segments", which
+ * drops valid connecting itineraries (e.g. all-UA multi-leg). Returns undefined
+ * when no carriers are given.
+ */
+export function carriersToRouting(carriers) {
+    if (!carriers)
+        return undefined;
+    const codes = carriers
+        .split(",")
+        .map((c) => c.trim().toUpperCase())
+        .filter(Boolean);
+    if (!codes.length)
+        return undefined;
+    return codes.length === 1 ? `${codes[0]}+` : `(${codes.join(",")})+`;
+}
+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}"`);
+    }
+}
+/** True only for an existing calendar date — rejects e.g. 2026-13-99, 2026-02-31. */
+function isRealCalendarDate(value) {
+    const [y, m, d] = value.split("-").map(Number);
+    const date = new Date(Date.UTC(y, m - 1, d));
+    return (date.getUTCFullYear() === y &&
+        date.getUTCMonth() === m - 1 &&
+        date.getUTCDate() === d);
+}
+//# sourceMappingURL=shared.js.map

package/dist/commands/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../src/commands/shared.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,YAAY,GAGb,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,yBAAyB,EAAqB,MAAM,aAAa,CAAC;AAY3E,MAAM,UAAU,mBAAmB,CAAC,IAAyB;IAC3D,MAAM,OAAO,GAAG,IAAI,CAAC,eAAe,IAAI,yBAAyB,CAAC;IAClE,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;QAC7C,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;IACjE,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,KAAK,KAAK,KAAK,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAAC;AACpE,CAAC;AAED,MAAM,CAAC,MAAM,OAAO,GAAG,qBAAqB,CAAC;AAC7C;;;;GAIG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,EAAE,CAAC;AAC5B,MAAM,CAAC,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,YAAY,CAAY,CAAC;AAC3D,MAAM,CAAC,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,YAAY,CAAgB,CAAC;AAW9D,MAAM,UAAU,oBAAoB,CAAC,IAAwB;IAC3D,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtD,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;IACtD,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,KAAK,GAAG,CAAC,EAAE,CAAC;QACpD,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;IACrD,CAAC;IACD,IAAI,IAAI,CAAC,KAAK,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAc,CAAC,EAAE,CAAC;QACxD,MAAM,IAAI,KAAK,CAAC,0BAA0B,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC;IACtF,CAAC;IACD,IAAI,IAAI,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAkB,CAAC,EAAE,CAAC;QAC3D,MAAM,IAAI,KAAK,CAAC,0BAA0B,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC;IACrF,CAAC;IACD,IAAI,IAAI,CAAC,UAAU,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,UAAuB,CAAC,EAAE,CAAC;QACrE,MAAM,IAAI,KAAK,CACb,gCAAgC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,IAAI,CAAC,UAAU,GAAG,CAC7E,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,IAAI,KAAK,GAAG,SAAS,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CACb,yBAAyB,SAAS,6DAA6D,CAChG,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAiB;IACjD,IAAI,CAAC,QAAQ;QAAE,OAAO,SAAS,CAAC;IAChC,MAAM,KAAK,GAAG,QAAQ;SACnB,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;SAClC,MAAM,CAAC,OAAO,CAAC,CAAC;IACnB,IAAI,CAAC,KAAK,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC;IACpC,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC;AACvE,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,KAAa,EAAE,IAAY;IACxD,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,kBAAkB,CAAC,KAAK,CAAC,EAAE,CAAC;QACvD,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,4CAA4C,KAAK,GAAG,CAAC,CAAC;IAC/E,CAAC;AACH,CAAC;AAED,qFAAqF;AACrF,SAAS,kBAAkB,CAAC,KAAa;IACvC,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAA6B,CAAC;IAC3E,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC7C,OAAO,CACL,IAAI,CAAC,cAAc,EAAE,KAAK,CAAC;QAC3B,IAAI,CAAC,WAAW,EAAE,KAAK,CAAC,GAAG,CAAC;QAC5B,IAAI,CAAC,UAAU,EAAE,KAAK,CAAC,CACxB,CAAC;AACJ,CAAC"}

package/dist/model/spec.d.ts

@@ -0,0 +1,63 @@
+/** Normalized search request the CLI builds and the browser driver consumes. */
+export interface SearchSpec {
+    origin: string;
+    dest: string;
+    departDate: string;
+    returnDate?: string;
+    adults: number;
+    /** Matrix page size; defaults to 25 (Matrix default). */
+    limit: number;
+    /** Advanced controls (P2). Omitted fields keep Matrix defaults. */
+    cabin?: Cabin;
+    stops?: StopLimit;
+    extraStops?: StopLimit;
+    /** ITA routing codes (the flight path) — see docs/ROUTING_CODES.md. */
+    routing?: string;
+    /** ITA extension codes (faring & filters) — see docs/ROUTING_CODES.md. */
+    ext?: string;
+}
+/** One leg of a multi-city trip. Routing/ext are per-slice in Matrix. */
+export interface Slice {
+    origin: string;
+    dest: string;
+    departDate: string;
+    routing?: string;
+    ext?: string;
+}
+/** Shared advanced controls applied to a whole trip (P3 multicity/calendar). */
+export interface TripOptions {
+    adults: number;
+    limit: number;
+    cabin?: Cabin;
+    stops?: StopLimit;
+    extraStops?: StopLimit;
+}
+/** Multi-city request: N independent legs (DESIGN P3). */
+export interface MultiCitySpec extends TripOptions {
+    slices: Slice[];
+}
+/**
+ * Price-calendar request: lowest fare per departure date across a range, for a
+ * fixed trip length (DESIGN P3, "See calendar of lowest fares").
+ */
+export interface CalendarSpec extends TripOptions {
+    origin: string;
+    dest: string;
+    departFrom: string;
+    departTo: string;
+    /** Nights between departure and return; omit for one-way calendar. */
+    tripLength?: number;
+    routing?: string;
+    ext?: string;
+}
+export type Cabin = "cheapest" | "premium-economy" | "business" | "first";
+export type StopLimit = "any" | "none" | "1" | "2";
+/** Matrix Cabin dropdown option labels, keyed by CLI value. */
+export declare const CABIN_LABELS: Record<Cabin, string>;
+/** Matrix Stops dropdown option labels, keyed by CLI value. */
+export declare const STOPS_LABELS: Record<StopLimit, string>;
+/** Matrix Extra stops dropdown option labels, keyed by CLI value. */
+export declare const EXTRA_STOPS_LABELS: Record<StopLimit, string>;
+export declare function isRoundTrip(spec: SearchSpec): boolean;
+/** True when any advanced control is set and the panel must be expanded. */
+export declare function hasAdvancedControls(spec: SearchSpec): boolean;

package/dist/model/spec.js

@@ -0,0 +1,29 @@
+/** Matrix Cabin dropdown option labels, keyed by CLI value. */
+export const CABIN_LABELS = {
+    cheapest: "Cheapest available",
+    "premium-economy": "Premium Economy",
+    business: "Business class or higher",
+    first: "First class",
+};
+/** Matrix Stops dropdown option labels, keyed by CLI value. */
+export const STOPS_LABELS = {
+    any: "No limit",
+    none: "Nonstop only",
+    "1": "Up to 1 stop",
+    "2": "Up to 2 stops",
+};
+/** Matrix Extra stops dropdown option labels, keyed by CLI value. */
+export const EXTRA_STOPS_LABELS = {
+    any: "No limit",
+    none: "No extra stops",
+    "1": "Up to 1 extra stop",
+    "2": "Up to 2 extra stops",
+};
+export function isRoundTrip(spec) {
+    return Boolean(spec.returnDate);
+}
+/** True when any advanced control is set and the panel must be expanded. */
+export function hasAdvancedControls(spec) {
+    return Boolean(spec.cabin || spec.stops || spec.extraStops || spec.routing || spec.ext);
+}
+//# sourceMappingURL=spec.js.map

package/dist/model/spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec.js","sourceRoot":"","sources":["../../src/model/spec.ts"],"names":[],"mappings":"AA4DA,+DAA+D;AAC/D,MAAM,CAAC,MAAM,YAAY,GAA0B;IACjD,QAAQ,EAAE,oBAAoB;IAC9B,iBAAiB,EAAE,iBAAiB;IACpC,QAAQ,EAAE,0BAA0B;IACpC,KAAK,EAAE,aAAa;CACrB,CAAC;AAEF,+DAA+D;AAC/D,MAAM,CAAC,MAAM,YAAY,GAA8B;IACrD,GAAG,EAAE,UAAU;IACf,IAAI,EAAE,cAAc;IACpB,GAAG,EAAE,cAAc;IACnB,GAAG,EAAE,eAAe;CACrB,CAAC;AAEF,qEAAqE;AACrE,MAAM,CAAC,MAAM,kBAAkB,GAA8B;IAC3D,GAAG,EAAE,UAAU;IACf,IAAI,EAAE,gBAAgB;IACtB,GAAG,EAAE,oBAAoB;IACzB,GAAG,EAAE,qBAAqB;CAC3B,CAAC;AAEF,MAAM,UAAU,WAAW,CAAC,IAAgB;IAC1C,OAAO,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;AAClC,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,mBAAmB,CAAC,IAAgB;IAClD,OAAO,OAAO,CAAC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC;AAC1F,CAAC"}

package/dist/model/spec.test.d.ts

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

package/dist/model/spec.test.js

@@ -0,0 +1,55 @@
+import { describe, it, expect } from "vitest";
+import { CABIN_LABELS, EXTRA_STOPS_LABELS, STOPS_LABELS, hasAdvancedControls, isRoundTrip, } from "./spec.js";
+const base = {
+    origin: "BOS",
+    dest: "LAX",
+    departDate: "2026-08-10",
+    adults: 1,
+    limit: 25,
+};
+describe("isRoundTrip", () => {
+    it("is false without a return date", () => {
+        expect(isRoundTrip(base)).toBe(false);
+    });
+    it("is true with a return date", () => {
+        expect(isRoundTrip({ ...base, returnDate: "2026-08-17" })).toBe(true);
+    });
+});
+describe("hasAdvancedControls", () => {
+    it("is false for a bare spec", () => {
+        expect(hasAdvancedControls(base)).toBe(false);
+    });
+    it("is true when any advanced control is set", () => {
+        expect(hasAdvancedControls({ ...base, cabin: "business" })).toBe(true);
+        expect(hasAdvancedControls({ ...base, stops: "none" })).toBe(true);
+        expect(hasAdvancedControls({ ...base, routing: "UA+" })).toBe(true);
+        expect(hasAdvancedControls({ ...base, ext: "-OVERNIGHTS" })).toBe(true);
+    });
+});
+describe("Matrix dropdown label maps", () => {
+    it("covers every cabin value with the live option label", () => {
+        expect(CABIN_LABELS).toEqual({
+            cheapest: "Cheapest available",
+            "premium-economy": "Premium Economy",
+            business: "Business class or higher",
+            first: "First class",
+        });
+    });
+    it("covers every stops value", () => {
+        expect(STOPS_LABELS).toEqual({
+            any: "No limit",
+            none: "Nonstop only",
+            "1": "Up to 1 stop",
+            "2": "Up to 2 stops",
+        });
+    });
+    it("covers every extra-stops value", () => {
+        expect(EXTRA_STOPS_LABELS).toEqual({
+            any: "No limit",
+            none: "No extra stops",
+            "1": "Up to 1 extra stop",
+            "2": "Up to 2 extra stops",
+        });
+    });
+});
+//# sourceMappingURL=spec.test.js.map

package/dist/model/spec.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec.test.js","sourceRoot":"","sources":["../../src/model/spec.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,YAAY,EACZ,mBAAmB,EACnB,WAAW,GAEZ,MAAM,WAAW,CAAC;AAEnB,MAAM,IAAI,GAAe;IACvB,MAAM,EAAE,KAAK;IACb,IAAI,EAAE,KAAK;IACX,UAAU,EAAE,YAAY;IACxB,MAAM,EAAE,CAAC;IACT,KAAK,EAAE,EAAE;CACV,CAAC;AAEF,QAAQ,CAAC,aAAa,EAAE,GAAG,EAAE;IAC3B,EAAE,CAAC,gCAAgC,EAAE,GAAG,EAAE;QACxC,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACxC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,4BAA4B,EAAE,GAAG,EAAE;QACpC,MAAM,CAAC,WAAW,CAAC,EAAE,GAAG,IAAI,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACxE,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,qBAAqB,EAAE,GAAG,EAAE;IACnC,EAAE,CAAC,0BAA0B,EAAE,GAAG,EAAE;QAClC,MAAM,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAChD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,0CAA0C,EAAE,GAAG,EAAE;QAClD,MAAM,CAAC,mBAAmB,CAAC,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACvE,MAAM,CAAC,mBAAmB,CAAC,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnE,MAAM,CAAC,mBAAmB,CAAC,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACpE,MAAM,CAAC,mBAAmB,CAAC,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,aAAa,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1E,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,4BAA4B,EAAE,GAAG,EAAE;IAC1C,EAAE,CAAC,qDAAqD,EAAE,GAAG,EAAE;QAC7D,MAAM,CAAC,YAAY,CAAC,CAAC,OAAO,CAAC;YAC3B,QAAQ,EAAE,oBAAoB;YAC9B,iBAAiB,EAAE,iBAAiB;YACpC,QAAQ,EAAE,0BAA0B;YACpC,KAAK,EAAE,aAAa;SACrB,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,0BAA0B,EAAE,GAAG,EAAE;QAClC,MAAM,CAAC,YAAY,CAAC,CAAC,OAAO,CAAC;YAC3B,GAAG,EAAE,UAAU;YACf,IAAI,EAAE,cAAc;YACpB,GAAG,EAAE,cAAc;YACnB,GAAG,EAAE,eAAe;SACrB,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,gCAAgC,EAAE,GAAG,EAAE;QACxC,MAAM,CAAC,kBAAkB,CAAC,CAAC,OAAO,CAAC;YACjC,GAAG,EAAE,UAAU;YACf,IAAI,EAAE,gBAAgB;YACtB,GAAG,EAAE,oBAAoB;YACzB,GAAG,EAAE,qBAAqB;SAC3B,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}