imprint-mcp 0.2.0

package/examples/discoverandgo/book_discoverandgo_museum_pass/index.ts

@@ -0,0 +1,89 @@
+/**
+ * GENERATED by `imprint emit` — DO NOT EDIT BY HAND.
+ *
+ * Tool: book_discoverandgo_museum_pass
+ * Site: discoverandgo
+ * Intent: Reserve a museum pass on Discover & Go for a specific offer and date using a San Diego Public Library card.
+ *
+ * To regenerate: imprint emit ~/.imprint/discoverandgo/book_discoverandgo_museum_pass/workflow.json --force
+ */
+
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import {
+  executeWorkflow,
+  type CredentialStore,
+} from 'imprint/runtime';
+import type { ToolResult, Workflow } from 'imprint/types';
+
+const WORKFLOW: Workflow = {
+  "toolName": "book_discoverandgo_museum_pass",
+  "intent": {
+    "description": "Reserve a museum pass on Discover & Go for a specific offer and date using a San Diego Public Library card.",
+    "userSaid": "clicked the cooley museum attraction and then clicked the option to view additional dates; selected may 26 and confirmaqtion dialog came up again; i confirmed it and it took me to my list of reservations"
+  },
+  "parameters": [
+    {
+      "name": "offer_id",
+      "type": "number",
+      "description": "The numeric ID of the specific museum offer to reserve (e.g. 1175 for J.A. Cooley Museum Family Pass)"
+    },
+    {
+      "name": "offer_date",
+      "type": "string",
+      "description": "The date for the reservation in YYYY-MM-DD format (e.g. 2026-05-26)"
+    },
+    {
+      "name": "notification_email",
+      "type": "string",
+      "description": "Email address to send the reservation confirmation to"
+    }
+  ],
+  "requests": [
+    {
+      "method": "GET",
+      "url": "https://sandiego.discoverandgo.net/epass_server.php?dataType=json&method=makeReservation&functionFile=Reservations%2CAttractions&language=en&patronID=${credential.patron_id}&offerID=${param.offer_id}&offerDate=${param.offer_date}&notificationMethod=Email&notificationEmail=${param.notification_email}&notificationTXTNumber=",
+      "headers": {
+        "x-epass-clientID": "1",
+        "x-epass-clientKey": "335e26134a53d4e23e4bed13517b7303",
+        "x-epass-libraryID": "63",
+        "x-epass-patronID": "${credential.patron_id}",
+        "X-Requested-With": "XMLHttpRequest",
+        "Accept": "application/json, text/javascript, */*; q=0.01"
+      }
+    }
+  ],
+  "site": "discoverandgo"
+};
+
+export interface BookDiscoverandgoMuseumPassInput {
+  /** The numeric ID of the specific museum offer to reserve (e.g. 1175 for J.A. Cooley Museum Family Pass) */
+  offer_id: number;
+  /** The date for the reservation in YYYY-MM-DD format (e.g. 2026-05-26) */
+  offer_date: string;
+  /** Email address to send the reservation confirmation to */
+  notification_email: string;
+}
+
+export async function bookDiscoverandgoMuseumPass(
+  input: BookDiscoverandgoMuseumPassInput,
+  opts: { credentials?: CredentialStore; fetchImpl?: typeof fetch; initialState?: Record<string, unknown> } = {},
+): Promise<ToolResult> {
+  const __dirname = dirname(fileURLToPath(import.meta.url));
+  const params: Record<string, string | number | boolean> = {
+    offer_id: input.offer_id,
+    offer_date: input.offer_date,
+    notification_email: input.notification_email,
+
+  };
+  return executeWorkflow({
+    workflow: WORKFLOW,
+    params,
+    credentials: opts.credentials,
+    fetchImpl: opts.fetchImpl,
+    initialState: opts.initialState,
+    workflowPath: join(__dirname, 'workflow.json'),
+  });
+}
+
+export { WORKFLOW };

package/examples/discoverandgo/book_discoverandgo_museum_pass/workflow.json

@@ -0,0 +1,39 @@
+{
+  "toolName": "book_discoverandgo_museum_pass",
+  "intent": {
+    "description": "Reserve a museum pass on Discover & Go for a specific offer and date using a San Diego Public Library card.",
+    "userSaid": "clicked the cooley museum attraction and then clicked the option to view additional dates; selected may 26 and confirmaqtion dialog came up again; i confirmed it and it took me to my list of reservations"
+  },
+  "parameters": [
+    {
+      "name": "offer_id",
+      "type": "number",
+      "description": "The numeric ID of the specific museum offer to reserve (e.g. 1175 for J.A. Cooley Museum Family Pass)"
+    },
+    {
+      "name": "offer_date",
+      "type": "string",
+      "description": "The date for the reservation in YYYY-MM-DD format (e.g. 2026-05-26)"
+    },
+    {
+      "name": "notification_email",
+      "type": "string",
+      "description": "Email address to send the reservation confirmation to"
+    }
+  ],
+  "requests": [
+    {
+      "method": "GET",
+      "url": "https://sandiego.discoverandgo.net/epass_server.php?dataType=json&method=makeReservation&functionFile=Reservations%2CAttractions&language=en&patronID=${credential.patron_id}&offerID=${param.offer_id}&offerDate=${param.offer_date}&notificationMethod=Email&notificationEmail=${param.notification_email}&notificationTXTNumber=",
+      "headers": {
+        "x-epass-clientID": "1",
+        "x-epass-clientKey": "335e26134a53d4e23e4bed13517b7303",
+        "x-epass-libraryID": "63",
+        "x-epass-patronID": "${credential.patron_id}",
+        "X-Requested-With": "XMLHttpRequest",
+        "Accept": "application/json, text/javascript, */*; q=0.01"
+      }
+    }
+  ],
+  "site": "discoverandgo"
+}

package/examples/echo/README.md

@@ -0,0 +1,37 @@
+# Echo — MCP smoke-test fixture
+
+> A network-free MCP tool used by the smoke-test scripts. Not a real demo — exists so you can verify your MCP wiring works without needing outbound HTTPS or a recorded session.
+
+## What this shows off
+
+- The minimum viable shape of a generated tool: `WORKFLOW` constant + a `camelCase(toolName)` async function returning `ToolResult`.
+- Useful when debugging Claude Desktop / mcp-inspector wire-up — if `echo_test` doesn't show up in the tools panel, your MCP config is wrong (not your network).
+
+## Run it
+
+```bash
+# Inspect via mcp-inspector (recommended for debugging)
+npx @modelcontextprotocol/inspector imprint mcp-server --site echo
+
+# Or run the included client smoke test
+bun scripts/mcp-client-test.ts
+```
+
+## What you should see
+
+```
+[imprint mcp] registered echo_test (echo) — 1 param(s)
+[imprint mcp] stdio transport ready (1 tool)
+```
+
+The mcp-inspector UI lists `echo_test`. Calling it with `{"message": "hi"}` returns `{"echoed":"hi","ts":"..."}`.
+
+## Files
+
+| File | What |
+|---|---|
+| `echo_test/index.ts` | The complete tool — no `workflow.json`, no recording, no compile pipeline. Pure code. |
+
+## Why this exists
+
+Recording a session, redacting it, calling the LLM, emitting code — that's the happy path. When the happy path is broken, you want a fixture that strips every variable except "is the MCP wiring correct." Echo is that fixture.

package/examples/echo/echo_test/index.ts

@@ -0,0 +1,31 @@
+import type { ToolResult, Workflow } from '../../../src/imprint/types.ts';
+
+/**
+ * Echo workflow — a network-free fixture for MCP smoke tests. Exercises the
+ * full handler path (async tool with awaits, JSON-encoded result) without
+ * depending on outbound HTTPS, which the stdio client transport strips env
+ * for and may fail in restrictive environments (corporate MITM, no
+ * NODE_EXTRA_CA_CERTS passthrough).
+ */
+export const WORKFLOW: Workflow = {
+  toolName: 'echo_test',
+  intent: { description: 'Echo back a message after a tiny async tick.' },
+  parameters: [
+    {
+      name: 'message',
+      type: 'string',
+      description: 'The text to echo back.',
+    },
+  ],
+  requests: [],
+  site: 'echo',
+};
+
+export async function echoTest(input: { message: string }): Promise<ToolResult> {
+  process.stderr.write(`[echo] received: ${input.message}\n`);
+  // Force a real microtask + macrotask boundary so we'd notice if the
+  // transport closed mid-handler (the original fastmcp/bun failure mode).
+  await Promise.resolve();
+  await new Promise((r) => setTimeout(r, 5));
+  return { ok: true, data: { echoed: input.message, ts: new Date().toISOString() } };
+}

package/examples/google-flights/search_google_flights/index.ts

@@ -0,0 +1,101 @@
+/**
+ * GENERATED by `imprint emit` — DO NOT EDIT BY HAND.
+ *
+ * Tool: search_google_flights
+ * Site: google-flights
+ * Intent: Search Google Flights for round-trip flights between two airports on specific dates.
+ *
+ * To regenerate: imprint emit ~/.imprint/google-flights/search_google_flights/workflow.json --force
+ */
+
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import {
+  executeWorkflow,
+  type CredentialStore,
+} from 'imprint/runtime';
+import type { ToolResult, Workflow } from 'imprint/types';
+
+const WORKFLOW: Workflow = {
+  "toolName": "search_google_flights",
+  "intent": {
+    "description": "Search Google Flights for round-trip flights between two airports on specific dates.",
+    "userSaid": "i searched for a sample flight the default mode is economy (include basic) now i changed to economy (exclude basic) now i searched for premium economy now i searched for business now i searched for first class now im going to start messing with all the filters available i played with all the filters now i clicked one of the departure flights, and now it's showing me a list of the return flights i selected the return flight, and now it's showing me the booking options"
+  },
+  "parameters": [
+    {
+      "name": "origin_airport",
+      "type": "string",
+      "description": "Origin airport IATA code.",
+      "default": "SJC"
+    },
+    {
+      "name": "destination_airport",
+      "type": "string",
+      "description": "Destination airport IATA code.",
+      "default": "SAN"
+    },
+    {
+      "name": "depart_date",
+      "type": "string",
+      "description": "Outbound departure date in YYYY-MM-DD format.",
+      "default": "2026-07-10"
+    },
+    {
+      "name": "return_date",
+      "type": "string",
+      "description": "Return departure date in YYYY-MM-DD format.",
+      "default": "2026-07-16"
+    }
+  ],
+  "requests": [
+    {
+      "method": "POST",
+      "url": "https://www.google.com/_/FlightsFrontendUi/data/travel.frontend.flights.FlightsFrontendService/GetShoppingResults?f.sid=-1290970187393889182&bl=boq_travel-frontend-flights-ui_20260506.02_p0&hl=en-US&soc-app=162&soc-platform=1&soc-device=1&_reqid=4008662&rt=c",
+      "headers": {
+        "Content-Type": "application/x-www-form-urlencoded;charset=UTF-8",
+        "Referer": "https://www.google.com/travel/flights",
+        "X-Same-Domain": "1",
+        "x-goog-ext-259736195-jspb": "[\"en-US\",\"US\",\"USD\",2,null,[420],null,null,7,[]]"
+      },
+      "body": "f.req=%5Bnull%2C%22%5B%5B%5D%2C%5Bnull%2Cnull%2C1%2Cnull%2C%5B%5D%2C1%2C%5B1%2C0%2C0%2C0%5D%2Cnull%2Cnull%2Cnull%2Cnull%2Cnull%2Cnull%2C%5B%5B%5B%5B%5B%5C%22${param.origin_airport}%5C%22%2C0%5D%5D%5D%2C%5B%5B%5B%5C%22${param.destination_airport}%5C%22%2C0%5D%5D%5D%2Cnull%2C0%2Cnull%2Cnull%2C%5C%22${param.depart_date}%5C%22%2Cnull%2Cnull%2Cnull%2Cnull%2Cnull%2C690%2Cnull%2C3%5D%2C%5B%5B%5B%5B%5C%22${param.destination_airport}%5C%22%2C0%5D%5D%5D%2C%5B%5B%5B%5C%22${param.origin_airport}%5C%22%2C0%5D%5D%5D%2Cnull%2C0%2Cnull%2Cnull%2C%5C%22${param.return_date}%5C%22%2Cnull%2Cnull%2Cnull%2Cnull%2Cnull%2C690%2Cnull%2C3%5D%5D%2Cnull%2Cnull%2Cnull%2C1%2Cnull%2Cnull%2Cnull%2Cnull%2Cnull%2Cnull%2Cnull%2Cnull%2Cnull%2Cnull%2C0%5D%2C0%2C0%2C0%2C1%5D%22%5D&"
+    }
+  ],
+  "site": "google-flights",
+  "parserModule": "./parser.ts"
+};
+
+export interface SearchGoogleFlightsInput {
+  /** Origin airport IATA code. */
+  origin_airport?: string;
+  /** Destination airport IATA code. */
+  destination_airport?: string;
+  /** Outbound departure date in YYYY-MM-DD format. */
+  depart_date?: string;
+  /** Return departure date in YYYY-MM-DD format. */
+  return_date?: string;
+}
+
+export async function searchGoogleFlights(
+  input: SearchGoogleFlightsInput,
+  opts: { credentials?: CredentialStore; fetchImpl?: typeof fetch; initialState?: Record<string, unknown> } = {},
+): Promise<ToolResult> {
+  const __dirname = dirname(fileURLToPath(import.meta.url));
+  const params: Record<string, string | number | boolean> = {
+    origin_airport: input.origin_airport ?? "SJC",
+    destination_airport: input.destination_airport ?? "SAN",
+    depart_date: input.depart_date ?? "2026-07-10",
+    return_date: input.return_date ?? "2026-07-16",
+
+  };
+  return executeWorkflow({
+    workflow: WORKFLOW,
+    params,
+    credentials: opts.credentials,
+    fetchImpl: opts.fetchImpl,
+    initialState: opts.initialState,
+    workflowPath: join(__dirname, 'workflow.json'),
+  });
+}
+
+export { WORKFLOW };

package/examples/google-flights/search_google_flights/parser.test.ts

@@ -0,0 +1,140 @@
+import { test, expect, describe } from 'bun:test';
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { extract } from './parser';
+
+const fixtureResponse = readFileSync(
+  join(
+    import.meta.dir,
+    '../../../test/fixtures/examples/google-flights/search_google_flights/fixture_response.txt',
+  ),
+  'utf-8'
+);
+
+describe('Google Flights parser', () => {
+  test('extract returns an object with flights array', () => {
+    const result = extract(fixtureResponse) as any;
+    expect(result).toBeDefined();
+    expect(result.flights).toBeDefined();
+    expect(Array.isArray(result.flights)).toBe(true);
+  });
+
+  test('returns multiple flights (SFO to Tokyo search)', () => {
+    const result = extract(fixtureResponse) as any;
+    expect(result.flights.length).toBeGreaterThan(0);
+    expect(result.totalCount).toBeGreaterThan(0);
+    expect(result.flights.length).toBe(result.totalCount);
+  });
+
+  test('flights originate from SFO (San Francisco)', () => {
+    const result = extract(fixtureResponse) as any;
+    const sfFlights = result.flights.filter((f: any) => f.origin === 'SFO');
+    expect(sfFlights.length).toBeGreaterThan(0);
+    // All flights should be from SFO
+    expect(result.flights.every((f: any) => f.origin === 'SFO')).toBe(true);
+  });
+
+  test('flights go to Tokyo airports (NRT or HND)', () => {
+    const result = extract(fixtureResponse) as any;
+    const tokyoFlights = result.flights.filter(
+      (f: any) => f.destination === 'NRT' || f.destination === 'HND'
+    );
+    expect(tokyoFlights.length).toBeGreaterThan(0);
+    // All flights should go to Tokyo area airports
+    expect(result.flights.every((f: any) => f.destination === 'NRT' || f.destination === 'HND')).toBe(true);
+  });
+
+  test('flights have valid prices in USD', () => {
+    const result = extract(fixtureResponse) as any;
+    const flightsWithPrice = result.flights.filter((f: any) => f.priceUsd !== null);
+    expect(flightsWithPrice.length).toBeGreaterThan(0);
+    // Prices should be reasonable for SFO-TYO (between $500 and $10000)
+    for (const flight of flightsWithPrice) {
+      expect(flight.priceUsd).toBeGreaterThan(500);
+      expect(flight.priceUsd).toBeLessThan(10000);
+    }
+  });
+
+  test('cheapest flight is ZIPAIR Tokyo at $1245', () => {
+    const result = extract(fixtureResponse) as any;
+    // Flights are sorted by price ascending
+    const cheapest = result.flights[0];
+    expect(cheapest.priceUsd).toBe(1245);
+    expect(cheapest.airlineCode).toBe('ZG');
+    expect(cheapest.airlineName).toBe('ZIPAIR Tokyo');
+  });
+
+  test('flights have valid departure dates in 2026', () => {
+    const result = extract(fixtureResponse) as any;
+    for (const flight of result.flights) {
+      expect(flight.departureDate).toMatch(/^2026-/);
+      expect(flight.departureDate).toBeTruthy();
+    }
+  });
+
+  test('flights have valid departure and arrival times', () => {
+    const result = extract(fixtureResponse) as any;
+    for (const flight of result.flights) {
+      expect(flight.departureTime).toMatch(/^\d{2}:\d{2}$/);
+      expect(flight.arrivalTime).toMatch(/^\d{2}:\d{2}$/);
+    }
+  });
+
+  test('flights have positive duration in minutes', () => {
+    const result = extract(fixtureResponse) as any;
+    for (const flight of result.flights) {
+      // SFO to Tokyo is roughly 10-28 hours
+      expect(flight.durationMinutes).toBeGreaterThan(600);
+      expect(flight.durationMinutes).toBeLessThan(2000);
+    }
+  });
+
+  test('flights have segment details', () => {
+    const result = extract(fixtureResponse) as any;
+    for (const flight of result.flights) {
+      expect(Array.isArray(flight.segments)).toBe(true);
+      expect(flight.segments.length).toBeGreaterThan(0);
+      const seg = flight.segments[0];
+      expect(seg.origin).toBe('SFO');
+      expect(seg.flightNumber).toBeTruthy();
+      expect(seg.aircraft).toBeTruthy();
+    }
+  });
+
+  test('includes known airlines: United, ANA, JAL', () => {
+    const result = extract(fixtureResponse) as any;
+    const airlineCodes = result.flights.map((f: any) => f.airlineCode);
+    expect(airlineCodes).toContain('UA'); // United
+    expect(airlineCodes).toContain('NH'); // ANA
+    expect(airlineCodes).toContain('JL'); // JAL
+  });
+
+  test('United flight to NRT costs $1809', () => {
+    const result = extract(fixtureResponse) as any;
+    const unitedNRT = result.flights.find(
+      (f: any) => f.airlineCode === 'UA' && f.destination === 'NRT'
+    );
+    expect(unitedNRT).toBeDefined();
+    expect(unitedNRT.priceUsd).toBe(1809);
+    expect(unitedNRT.durationMinutes).toBe(635);
+  });
+
+  test('flights have booking tokens', () => {
+    const result = extract(fixtureResponse) as any;
+    const flightsWithToken = result.flights.filter((f: any) => f.bookingToken !== null);
+    expect(flightsWithToken.length).toBeGreaterThan(0);
+  });
+
+  test('stops field is correctly parsed (0 for nonstop, 1+ for connecting)', () => {
+    const result = extract(fixtureResponse) as any;
+    // All flights in this response have at least 1 segment
+    for (const flight of result.flights) {
+      expect(flight.stopCount).toBeGreaterThanOrEqual(0);
+    }
+    // Asiana Airlines goes via ICN (1 stop)
+    const asiana = result.flights.find((f: any) => f.airlineCode === 'OZ');
+    if (asiana) {
+      expect(asiana.stopCount).toBeGreaterThan(0);
+    }
+  });
+});

package/examples/google-flights/search_google_flights/parser.ts

@@ -0,0 +1,189 @@
+interface Segment {
+  origin: string;
+  originName: string;
+  destination: string;
+  destinationName: string;
+  departureDate: string;
+  departureTime: string;
+  arrivalDate: string;
+  arrivalTime: string;
+  durationMinutes: number;
+  airlineCode: string;
+  airlineName: string;
+  flightNumber: string;
+  aircraft: string;
+  cabinClass: string;
+}
+
+interface Flight {
+  airlineCode: string;
+  airlineName: string;
+  origin: string;
+  destination: string;
+  departureDate: string;
+  departureTime: string;
+  arrivalDate: string;
+  arrivalTime: string;
+  durationMinutes: number;
+  stopCount: number;
+  priceUsd: number | null;
+  bookingToken: string | null;
+  flightNumbers: string[];
+  segments: Segment[];
+}
+
+function formatDate(parts: unknown): string {
+  if (!Array.isArray(parts) || parts.length < 3) return '';
+  const [year, month, day] = parts as number[];
+  return `${year}-${String(month).padStart(2, '0')}-${String(day).padStart(2, '0')}`;
+}
+
+function formatTime(parts: unknown): string {
+  if (!Array.isArray(parts) || parts.length === 0) return '';
+  const [hour = 0, minute = 0] = parts as number[];
+  return `${String(hour).padStart(2, '0')}:${String(minute).padStart(2, '0')}`;
+}
+
+function cabinClassLabel(code: unknown): string {
+  switch (code) {
+    case 1:
+      return 'economy';
+    case 2:
+      return 'premium_economy';
+    case 3:
+      return 'business';
+    case 4:
+      return 'first';
+    default:
+      return 'unknown';
+  }
+}
+
+function parseEnvelope(rawResponse: string): unknown[] | null {
+  const jsonLine = rawResponse
+    .split('\n')
+    .find((line) => line.startsWith('[[') || line.startsWith('[["'));
+
+  if (!jsonLine) return null;
+
+  let outer: unknown[];
+  try {
+    outer = JSON.parse(jsonLine) as unknown[];
+  } catch {
+    return null;
+  }
+
+  const innerString = (outer as unknown[][])?.[0]?.[2];
+  if (typeof innerString !== 'string') return null;
+
+  try {
+    return JSON.parse(innerString) as unknown[];
+  } catch {
+    return null;
+  }
+}
+
+function parseSegment(rawSegment: unknown): Segment | null {
+  if (!Array.isArray(rawSegment)) return null;
+
+  const flightInfo = rawSegment[22];
+  return {
+    origin: typeof rawSegment[3] === 'string' ? rawSegment[3] : '',
+    originName: typeof rawSegment[4] === 'string' ? rawSegment[4] : '',
+    destination: typeof rawSegment[6] === 'string' ? rawSegment[6] : '',
+    destinationName: typeof rawSegment[5] === 'string' ? rawSegment[5] : '',
+    departureDate: formatDate(rawSegment[20]),
+    departureTime: formatTime(rawSegment[8]),
+    arrivalDate: formatDate(rawSegment[21]),
+    arrivalTime: formatTime(rawSegment[10]),
+    durationMinutes: typeof rawSegment[11] === 'number' ? rawSegment[11] : 0,
+    airlineCode:
+      Array.isArray(flightInfo) && typeof flightInfo[0] === 'string' ? flightInfo[0] : '',
+    airlineName:
+      Array.isArray(flightInfo) && typeof flightInfo[3] === 'string' ? flightInfo[3] : '',
+    flightNumber:
+      Array.isArray(flightInfo) &&
+      typeof flightInfo[0] === 'string' &&
+      typeof flightInfo[1] === 'string'
+        ? `${flightInfo[0]}${flightInfo[1]}`
+        : '',
+    aircraft: typeof rawSegment[17] === 'string' ? rawSegment[17] : '',
+    cabinClass: cabinClassLabel(rawSegment[13]),
+  };
+}
+
+function parseFlight(rawOption: unknown): Flight | null {
+  if (!Array.isArray(rawOption) || rawOption.length < 2) return null;
+
+  const details = rawOption[0];
+  const priceInfo = rawOption[1];
+  if (!Array.isArray(details) || !Array.isArray(details[2])) return null;
+
+  const segments = details[2]
+    .map((segment) => parseSegment(segment))
+    .filter((segment): segment is Segment => segment !== null);
+
+  const firstPrice = Array.isArray(priceInfo) && Array.isArray(priceInfo[0]) ? priceInfo[0] : null;
+  const priceUsd = firstPrice && typeof firstPrice[1] === 'number' ? firstPrice[1] : null;
+  const bookingToken = Array.isArray(priceInfo) && typeof priceInfo[1] === 'string' ? priceInfo[1] : null;
+
+  return {
+    airlineCode: typeof details[0] === 'string' ? details[0] : '',
+    airlineName:
+      Array.isArray(details[1]) && typeof details[1][0] === 'string' ? details[1][0] : '',
+    origin: typeof details[3] === 'string' ? details[3] : '',
+    destination: typeof details[6] === 'string' ? details[6] : '',
+    departureDate: formatDate(details[4]),
+    departureTime: formatTime(details[5]),
+    arrivalDate: formatDate(details[7]),
+    arrivalTime: formatTime(details[8]),
+    durationMinutes: typeof details[9] === 'number' ? details[9] : 0,
+    stopCount: Math.max(segments.length - 1, 0),
+    priceUsd,
+    bookingToken,
+    flightNumbers: segments.map((segment) => segment.flightNumber).filter(Boolean),
+    segments,
+  };
+}
+
+function isFlightSection(section: unknown): section is [unknown[], ...unknown[]] {
+  return (
+    Array.isArray(section) &&
+    Array.isArray(section[0]) &&
+    section[0].length > 0 &&
+    Array.isArray(section[0][0]) &&
+    Array.isArray(section[0][0][0])
+  );
+}
+
+export function extract(rawResponse: unknown): unknown {
+  if (typeof rawResponse !== 'string') {
+    return { flights: [], totalCount: 0, error: 'Expected raw response string.' };
+  }
+
+  const envelope = parseEnvelope(rawResponse);
+  if (!envelope) {
+    return { flights: [], totalCount: 0, error: 'Unable to parse Google Flights response.' };
+  }
+
+  const flights: Flight[] = [];
+  for (const section of envelope) {
+    if (!isFlightSection(section)) continue;
+    for (const rawOption of section[0]) {
+      const flight = parseFlight(rawOption);
+      if (flight) flights.push(flight);
+    }
+  }
+
+  flights.sort((a, b) => {
+    if (a.priceUsd == null && b.priceUsd == null) return 0;
+    if (a.priceUsd == null) return 1;
+    if (b.priceUsd == null) return -1;
+    return a.priceUsd - b.priceUsd;
+  });
+
+  return {
+    flights,
+    totalCount: flights.length,
+  };
+}