imprint-mcp 0.2.1 → 0.3.1

package/examples/google-flights/_shared/flights_request.ts

@@ -0,0 +1,95 @@
+// Builds the double-encoded `f.req` form body for FlightsFrontendService RPCs
+// (GetShoppingResults / GetCalendarPicker / GetBookingResults). Body construction
+// is session-independent; f.sid/bl/_reqid/X-Goog-BatchExecute-Bgr are runtime state
+// and are intentionally left untouched (transform returns the input url verbatim).
+//
+// NOTE (correction to spec): the leg encoding is NOT byte-for-byte identical across
+// all three RPCs. GetCalendarPicker uses 4-slot legs ([ORIGIN,DEST,TIMES|null,STOPS])
+// with the date range living in the outer wrapper; Shopping/Booking use the full
+// 15-slot leg with DATE at [6]. Verified by decoding seq 97 vs seq 111.
+
+// Fresh searches emit wrapper `...,0,0,0,1]` and leg[14]=3 (proven seq 111/140).
+// In-page-refined searches use `...,0,1,0,1]` with return-leg[14]=1 (seq 194/425) —
+// a UI freshness flag, not a user param; we always emit the fresh form for shopping.
+// Booking outbound legs use [14]=3, return legs [14]=1 (seq 764/811).
+
+function buildLeg(leg: any): any[] {
+  const out: any[] = new Array(15).fill(null);
+  out[0] = [[[leg?.origin, 0]]];
+  out[1] = [[[leg?.dest, 0]]];
+  out[2] = leg?.times ?? null;
+  out[3] = leg?.stops ?? 0;
+  out[4] = leg?.alliances ?? null;
+  out[5] = leg?.carriers ?? null;
+  out[6] = leg?.date ?? null;
+  out[7] = leg?.duration ?? null;
+  out[8] = Array.isArray(leg?.selected)
+    ? leg.selected.map((s: any) => [s?.origin, s?.date, s?.dest, null, s?.carrier, s?.flightNumber])
+    : null;
+  out[14] = 3;
+  return out;
+}
+
+export function buildFlightSearchParams(params: Record<string, any>): any[] {
+  const p: Record<string, any> = params ?? {};
+  // 18-slot positional search array shared by every body (proven seq 111).
+  const sp: any[] = new Array(18).fill(null);
+  sp[2] = p.tripType ?? 1; // 1=round, 2=one-way, 3=multi-city
+  sp[4] = [];
+  sp[5] = 1;
+  sp[6] = [p.adults ?? 1, p.children ?? 0, p.infantsSeat ?? 0, p.infantsLap ?? 0];
+  sp[7] = p.maxPrice != null ? [null, p.maxPrice] : null;
+  sp[10] = p.bags ? [p.bags.carryOn ?? 0, p.bags.checked ?? 0] : null;
+  const legs: any[] = Array.isArray(p.legs) ? p.legs : [];
+  sp[13] = legs.map((l: any) => buildLeg(l));
+  sp[17] = 1;
+  return sp;
+}
+
+export function encodeFreq(payload: any): string {
+  // payload -> inner json string -> embedded in [null, inner] -> x-www-form-urlencoded.
+  // Verified byte-for-byte against seq 111: `\"`->%5C%22, `[`->%5B, `,`->%2C, `=`->%3D.
+  const inner = JSON.stringify(payload);
+  const outer = JSON.stringify([null, inner]);
+  return 'f.req=' + encodeURIComponent(outer) + '&';
+}
+
+export function transform(
+  method: string,
+  url: string,
+  responses: Record<string, any>,
+  params?: Record<string, any>,
+): { url: string; body: string } {
+  // method/responses are part of the contract but unused for body construction
+  // (the booking token arrives via params.flight_token). Reference to satisfy strict.
+  void method;
+  void responses;
+
+  const p: Record<string, any> = params ?? {};
+  const m = /FlightsFrontendService\/(\w+)/.exec(url);
+  if (!m || !m[1]) throw new Error(`unrecognized FlightsFrontendService rpc in url: ${url}`);
+  const rpc: string = m[1];
+
+  const sp = buildFlightSearchParams(p);
+  let payload: any;
+
+  if (rpc === 'GetShoppingResults') {
+    payload = [[], sp, 0, 0, 0, 1];
+  } else if (rpc === 'GetCalendarPicker') {
+    const legs = sp[13];
+    if (Array.isArray(legs)) sp[13] = legs.map((l: any) => (Array.isArray(l) ? l.slice(0, 4) : l));
+    payload = [null, sp, [p.startDate ?? null, p.endDate ?? null], null, [7, 7]];
+  } else if (rpc === 'GetBookingResults') {
+    const legs = sp[13];
+    if (Array.isArray(legs)) {
+      legs.forEach((l: any, i: number) => {
+        if (i >= 1 && Array.isArray(l)) l[14] = 1; // return leg(s)
+      });
+    }
+    payload = [[null, p.flight_token ?? null], sp, null, p.tripType === 2 ? 0 : 1];
+  } else {
+    throw new Error(`unsupported FlightsFrontendService rpc: ${rpc}`);
+  }
+
+  return { url, body: encodeFreq(payload) };
+}

package/examples/google-flights/_shared/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "imprint-shared",
+  "private": true,
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/node": "latest",
+    "bun-types": "latest"
+  }
+}

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

@@ -0,0 +1,159 @@
+/**
+ * GENERATED by `imprint emit` — DO NOT EDIT BY HAND.
+ *
+ * Tool: get_flight_booking_details
+ * Site: google-flights
+ * Intent: Get booking/fare details and bookable options for a specific selected flight itinerary on Google Flights.
+ *
+ * To regenerate: imprint emit ~/.imprint/google-flights/get_flight_booking_details/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": "get_flight_booking_details",
+  "intent": {
+    "description": "Get booking/fare details and bookable options for a specific selected flight itinerary on Google Flights.",
+    "userSaid": "clicked one of the one-way fares to find more details and booking details; saw the options for another flight; chose round trip fares; kept exploring round trip fare details"
+  },
+  "parameters": [
+    {
+      "name": "origin",
+      "type": "string",
+      "description": "Origin airport IATA code for the outbound leg, e.g. SJC",
+      "verified": false,
+      "verifyNote": "annotated"
+    },
+    {
+      "name": "destination",
+      "type": "string",
+      "description": "Destination airport IATA code for the outbound leg, e.g. SAN",
+      "verified": false,
+      "verifyNote": "annotated"
+    },
+    {
+      "name": "departure_date",
+      "type": "string",
+      "description": "Outbound date in YYYY-MM-DD",
+      "verified": false,
+      "verifyNote": "annotated"
+    },
+    {
+      "name": "return_date",
+      "type": "string",
+      "description": "Return date in YYYY-MM-DD. Empty/omit for a one-way booking.",
+      "default": "",
+      "verified": true
+    },
+    {
+      "name": "outbound_flight",
+      "type": "string",
+      "description": "Selected outbound flight as 'carrier number', e.g. 'WN 3489'",
+      "verified": false,
+      "verifyNote": "annotated"
+    },
+    {
+      "name": "return_flight",
+      "type": "string",
+      "description": "Selected return flight as 'carrier number' (round trip only), e.g. 'WN 3540'. Empty for one-way.",
+      "default": "",
+      "verified": false,
+      "verifyNote": "annotated"
+    },
+    {
+      "name": "flight_token",
+      "type": "string",
+      "description": "Opaque per-itinerary booking token minted by the search_flights tool's flight_token output for the selected itinerary."
+    }
+  ],
+  "requests": [
+    {
+      "method": "POST",
+      "url": "https://www.google.com/_/FlightsFrontendUi/data/travel.frontend.flights.FlightsFrontendService/GetBookingResults?f.sid=${state.f_sid}&bl=${state.bl}&hl=en-US&soc-app=162&soc-platform=1&soc-device=1&_reqid=1659189&rt=c",
+      "headers": {
+        "Content-Type": "application/x-www-form-urlencoded;charset=UTF-8",
+        "X-Same-Domain": "1",
+        "Referer": "https://www.google.com/travel/flights",
+        "x-goog-ext-259736195-jspb": "[\"en-US\",\"US\",\"USD\",2,null,[420],null,null,7,[]]"
+      },
+      "body": "f.req=${param.origin}|${param.destination}|${param.departure_date}|${param.return_date}|${param.outbound_flight}|${param.return_flight}|${param.flight_token}&",
+      "effect": "safe"
+    }
+  ],
+  "site": "google-flights",
+  "bootstrap": {
+    "url": "https://www.google.com/travel/flights",
+    "waitUntil": "domcontentloaded",
+    "timeoutMs": 30000,
+    "captures": [
+      {
+        "name": "f_sid",
+        "required": false,
+        "capability": "browser_bootstrap",
+        "source": "html_regex",
+        "pattern": "\"FdrFJe\":\"([^\"]+)\"",
+        "group": 1
+      },
+      {
+        "name": "bl",
+        "required": false,
+        "capability": "browser_bootstrap",
+        "source": "html_regex",
+        "pattern": "\"cfb2h\":\"([^\"]+)\"",
+        "group": 1
+      }
+    ]
+  },
+  "parserModule": "./parser.ts",
+  "requestTransformModule": "./request-transform.ts",
+  "liveVerified": true
+};
+
+export interface GetFlightBookingDetailsInput {
+  /** Origin airport IATA code for the outbound leg, e.g. SJC */
+  origin: string;
+  /** Destination airport IATA code for the outbound leg, e.g. SAN */
+  destination: string;
+  /** Outbound date in YYYY-MM-DD */
+  departure_date: string;
+  /** Return date in YYYY-MM-DD. Empty/omit for a one-way booking. */
+  return_date?: string;
+  /** Selected outbound flight as 'carrier number', e.g. 'WN 3489' */
+  outbound_flight: string;
+  /** Selected return flight as 'carrier number' (round trip only), e.g. 'WN 3540'. Empty for one-way. */
+  return_flight?: string;
+  /** Opaque per-itinerary booking token minted by the search_flights tool's flight_token output for the selected itinerary. */
+  flight_token: string;
+}
+
+export async function getFlightBookingDetails(
+  input: GetFlightBookingDetailsInput,
+  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> = {
+    return_date: input.return_date ?? "",
+    return_flight: input.return_flight ?? "",
+    origin: input.origin,
+    destination: input.destination,
+    departure_date: input.departure_date,
+    outbound_flight: input.outbound_flight,
+    flight_token: input.flight_token,
+  };
+  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/get_flight_booking_details/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "imprint-tool-google-flights",
+  "private": true,
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/node": "latest",
+    "bun-types": "latest"
+  }
+}

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

@@ -0,0 +1,182 @@
+// Parser for Google Flights GetBookingResults (batchexecute RPC).
+// Decodes the streaming envelope with the shared helper, then walks the deeply
+// nested positional payload to extract the itinerary's per-segment detail and
+// the list of bookable fare options (price USD + booking provider).
+import { decodeBatchExecute } from '../_shared/batchexecute.ts';
+
+const AIRPORT = /^[A-Z]{3}$/;
+
+interface Segment {
+  carrier: string;
+  carrierName: string | null;
+  flightNumber: string;
+  origin: string;
+  originName: string | null;
+  destination: string;
+  destinationName: string | null;
+  departDate: string | null;
+  departTime: string | null;
+  arriveDate: string | null;
+  arriveTime: string | null;
+  durationMinutes: number | null;
+  aircraft: string | null;
+  operatingCarrier: { carrier: string; flightNumber: string | null; name: string | null } | null;
+}
+
+interface FareOption {
+  priceUSD: number;
+  provider: string;
+  bookingUrl: string | null;
+  fareClass: string | null;
+}
+
+function fmtTime(t: unknown): string | null {
+  if (!Array.isArray(t) || t.length === 0) return null;
+  const h = typeof t[0] === 'number' ? t[0] : 0;
+  const m = typeof t[1] === 'number' ? t[1] : 0;
+  return `${String(h).padStart(2, '0')}:${String(m).padStart(2, '0')}`;
+}
+
+function fmtDate(d: unknown): string | null {
+  if (!Array.isArray(d) || d.length < 3) return null;
+  const [y, mo, day] = d as number[];
+  if (typeof y !== 'number') return null;
+  return `${y}-${String(mo).padStart(2, '0')}-${String(day).padStart(2, '0')}`;
+}
+
+// A segment node: airport codes at [3]/[6], aircraft string at [17],
+// and a marketing-flight tuple [carrier, number, _, carrierName] at [22].
+function isSegment(node: unknown): node is unknown[] {
+  if (!Array.isArray(node)) return false;
+  if (typeof node[3] !== 'string' || !AIRPORT.test(node[3] as string)) return false;
+  if (typeof node[6] !== 'string' || !AIRPORT.test(node[6] as string)) return false;
+  const fn = node[22];
+  return Array.isArray(fn) && typeof fn[0] === 'string' && fn[1] != null;
+}
+
+// A booking-option node: provider tuple at [1][0] = [carrier, providerName,...]
+// and price at [7] = [[null, priceUSD], "<fareToken>"].
+function isBookingOption(node: unknown): node is unknown[] {
+  if (!Array.isArray(node)) return false;
+  const provider = node[1];
+  if (!Array.isArray(provider) || !Array.isArray(provider[0])) return false;
+  if (typeof provider[0][1] !== 'string') return false;
+  const price = node[7];
+  if (!Array.isArray(price) || !Array.isArray(price[0])) return false;
+  return typeof price[0][1] === 'number';
+}
+
+function toSegment(seg: unknown[]): Segment {
+  const fn = seg[22] as unknown[];
+  let operatingCarrier: Segment['operatingCarrier'] = null;
+  const op = seg[15];
+  if (Array.isArray(op) && Array.isArray(op[0]) && typeof op[0][0] === 'string') {
+    const o = op[0] as unknown[];
+    operatingCarrier = {
+      carrier: o[0] as string,
+      flightNumber: typeof o[1] === 'string' ? (o[1] as string) : null,
+      name: typeof o[3] === 'string' ? (o[3] as string) : null,
+    };
+  }
+  return {
+    carrier: typeof fn[0] === 'string' ? (fn[0] as string) : '',
+    carrierName: typeof fn[3] === 'string' ? (fn[3] as string) : null,
+    flightNumber: fn[1] != null ? String(fn[1]) : '',
+    origin: seg[3] as string,
+    originName: typeof seg[4] === 'string' ? (seg[4] as string) : null,
+    destination: seg[6] as string,
+    destinationName: typeof seg[5] === 'string' ? (seg[5] as string) : null,
+    departDate: fmtDate(seg[20]),
+    departTime: fmtTime(seg[8]),
+    arriveDate: fmtDate(seg[21]),
+    arriveTime: fmtTime(seg[10]),
+    durationMinutes: typeof seg[11] === 'number' ? (seg[11] as number) : null,
+    aircraft: typeof seg[17] === 'string' ? (seg[17] as string) : null,
+    operatingCarrier,
+  };
+}
+
+function toFareOption(node: unknown[]): FareOption {
+  const provider = node[1] as unknown[];
+  const price = node[7] as unknown[];
+  const link = node[5];
+  let bookingUrl: string | null = null;
+  if (Array.isArray(link) && typeof link[0] === 'string') bookingUrl = link[0] as string;
+
+  let fareClass: string | null = null;
+  const fc = node[14];
+  // node[14] = [[[null, ["WN","BASIC"], 1]]]
+  const inner = Array.isArray(fc) ? (fc[0] as unknown[]) : undefined;
+  const innerInner = Array.isArray(inner) ? (inner[0] as unknown[]) : undefined;
+  if (Array.isArray(innerInner) && Array.isArray(innerInner[1])) {
+    const code = (innerInner[1] as unknown[])[1];
+    if (typeof code === 'string') fareClass = code;
+  }
+
+  return {
+    priceUSD: (price[0] as unknown[])[1] as number,
+    provider: (provider[0] as unknown[])[1] as string,
+    bookingUrl,
+    fareClass,
+  };
+}
+
+function walk(node: unknown, segs: unknown[][], fares: unknown[][]): void {
+  if (!Array.isArray(node)) return;
+  if (isBookingOption(node)) {
+    fares.push(node);
+    // booking options also contain a nested segment listing; keep recursing
+    // so those segments are still discovered (dedup handles overlap).
+  }
+  if (isSegment(node)) {
+    segs.push(node);
+    return; // a segment is a leaf for our purposes
+  }
+  for (const child of node) walk(child, segs, fares);
+}
+
+export function extract(
+  rawResponse: unknown,
+  _context?: { params: Record<string, string | number | boolean>; responses: unknown[] },
+): unknown {
+  let frames: Array<{ rpcid: string | null; payload: any }> = [];
+  if (typeof rawResponse === 'string') {
+    frames = decodeBatchExecute(rawResponse);
+  } else if (rawResponse != null) {
+    frames = [{ rpcid: null, payload: rawResponse }];
+  }
+
+  const segNodes: unknown[][] = [];
+  const fareNodes: unknown[][] = [];
+  for (const f of frames) walk(f.payload, segNodes, fareNodes);
+
+  // Dedup segments by carrier+number+departDate+departTime.
+  const segMap = new Map<string, Segment>();
+  for (const s of segNodes) {
+    const seg = toSegment(s);
+    if (!seg.carrier && !seg.flightNumber) continue;
+    const key = `${seg.carrier}${seg.flightNumber}|${seg.departDate}|${seg.departTime}|${seg.origin}`;
+    if (!segMap.has(key)) segMap.set(key, seg);
+  }
+
+  // Dedup fare options by fareClass + price + provider.
+  const fareMap = new Map<string, FareOption>();
+  for (const n of fareNodes) {
+    const fare = toFareOption(n);
+    if (!fare.provider || typeof fare.priceUSD !== 'number') continue;
+    const key = `${fare.fareClass}|${fare.priceUSD}|${fare.provider}`;
+    if (!fareMap.has(key)) fareMap.set(key, fare);
+  }
+
+  const segments = [...segMap.values()];
+  const fareOptions = [...fareMap.values()];
+  const prices = fareOptions.map((f) => f.priceUSD);
+
+  return {
+    segments,
+    fareOptions,
+    segmentCount: segments.length,
+    fareOptionCount: fareOptions.length,
+    lowestPriceUSD: prices.length ? Math.min(...prices) : null,
+  };
+}

package/examples/google-flights/get_flight_booking_details/playbook.yaml

@@ -0,0 +1,138 @@
+toolName: get_flight_booking_details
+summary: "On Google Flights, search a route/date, open a selected flight itinerary, and capture its GetBookingResults fare/booking-provider detail."
+parameters:
+  - name: origin
+    type: string
+    description: Origin airport code, e.g. SJC
+  - name: destination
+    type: string
+    description: Destination airport code, e.g. SAN
+  - name: departure_date
+    type: string
+    description: Outbound date, YYYY-MM-DD
+  - name: return_date
+    type: string
+    description: Return date YYYY-MM-DD. Omit for one-way (the recorded primary flow is one-way).
+  - name: outbound_flight
+    type: string
+    description: Selected outbound flight as carrier+number, e.g. "WN 3489". Used to pick the flight card whose booking details are fetched.
+  - name: return_flight
+    type: string
+    description: Selected return flight as carrier+number (round-trip only); omit for one-way.
+steps:
+  - action: navigate
+    url: https://www.google.com/travel/flights
+    wait_for: networkidle
+
+  - action: type
+    locators:
+      - by: aria_label
+        value: Where from?
+      - by: css
+        value: div.wUiEcc.SOcuWe input.II2One.j0Ppje
+    value: ${origin}
+    wait_for:
+      sleep_ms: 500
+  - action: click
+    locators:
+      - by: aria_label
+        value_pattern: ${origin}
+      - by: text
+        value_pattern: ${origin}
+    wait_for: visible
+
+  - action: type
+    locators:
+      - by: aria_label
+        value: "Where to?"
+      - by: css
+        value: div.cQnuXe.k0gFV input.II2One.j0Ppje
+    value: ${destination}
+    wait_for:
+      sleep_ms: 500
+  - action: click
+    locators:
+      - by: aria_label
+        value_pattern: ${destination}
+      - by: text
+        value_pattern: ${destination}
+    wait_for: visible
+
+  # Trip type -> One way (omit these two steps for a round trip)
+  - action: click
+    locators:
+      - by: aria_label
+        value: "Select your ticket type."
+      - by: css
+        value: div.TQYpgc.gInvKb div.VfPpkd-aPP78e
+    wait_for:
+      sleep_ms: 300
+  - action: click
+    locators:
+      - by: text
+        value: One way
+      - by: role
+        value: option
+        name: One way
+    wait_for: visible
+
+  - action: type
+    locators:
+      - by: aria_label
+        value: Departure
+      - by: css
+        value: div.GYgkab.YICvqf input.TP4Lpb.eoY5cb
+    value: ${departure_date}
+    wait_for:
+      sleep_ms: 400
+  - action: click
+    locators:
+      - by: text
+        value: Done
+      - by: aria_label
+        value: Done
+    wait_for:
+      sleep_ms: 300
+
+  - action: click
+    locators:
+      - by: text
+        value: Search
+      - by: aria_label
+        value: Search
+    wait_for:
+      xhr: /GetShoppingResults
+
+  # Open the chosen flight; this is the click that triggers GetBookingResults.
+  - action: click
+    locators:
+      - by: text
+        value_pattern: ${outbound_flight}
+      - by: css
+        value: ul.Rk10dc > li.pIav2d div.yR1fYc
+    wait_for:
+      xhr: /GetBookingResults
+result:
+  source: xhr
+  url_pattern: /data/travel.frontend.flights.FlightsFrontendService/GetBookingResults
+  extract: "[1][5][0]"
+  return_as: booking_details
+notes: >
+  Response is a Google batchexecute payload prefixed with )]}' and split into length-prefixed
+  chunks; the parser must strip the prefix, split on the numeric length markers, and JSON.parse
+  each "wrb.fr" envelope's double-encoded inner JSON. Flight data is positional, not keyed: in the
+  first wrb.fr chunk, [1][5][0] holds the selected itinerary slices (each slice = [carrier,[airlineName],
+  [[segment...]], origCode,[y,m,d],[h,m], destCode,...], with segment carrier+number at the
+  [\"WN\",\"3489\",null,\"Southwest\"] tuple). The bookable fare options with provider and price live in
+  the SECOND wrb.fr chunk of the same response at [1][0]: each option is
+  [0,[[provider,providerName,...]],null,[[carrier,number]],false,[bookingUrl...],...,priceCents]; price is
+  in cents (e.g. 88008 = $880.08) and provider name is option[1][0][1]. Auth is session-bound:
+  f.sid (per-page session id) plus the X-Goog-BatchExecute-Bgr header are captured fresh from page
+  bootstrap and are NOT parameterized. The per-itinerary base64 flight token required by the underlying
+  GetBookingResults RPC is produced by the prior GetShoppingResults and is not user-controllable — the
+  DOM flow handles it automatically by clicking the rendered flight card, which is why this playbook
+  clicks rather than POSTs. For a round trip, do NOT set trip type to "One way"; supply return_date so
+  the search returns round-trip results, then after the outbound-flight click pick the return flight
+  (matching return_flight) before GetBookingResults fires. Result cards show airline name + times rather
+  than the raw flight number, so the ${outbound_flight} text locator may need the carrier/time; the
+  css fallback selects the first result card.

package/examples/google-flights/get_flight_booking_details/request-transform.ts

@@ -0,0 +1,86 @@
+// Adapter around the shared FlightsFrontendService body builder for
+// GetBookingResults. The tool exposes flat snake_case params (origin,
+// destination, departure_date, return_date, outbound_flight, return_flight,
+// flight_token); the shared encoder consumes a structured shape
+// ({ tripType, legs:[{origin,dest,date,selected:[{origin,date,dest,carrier,flightNumber}]}], flight_token }).
+// We map between them here and delegate the byte-for-byte positional encoding
+// (legs, trip-type, the [[null,token],sp,null,selIdx] outer wrapper, token
+// injection, encodeFreq) to the shared module — required reuse.
+import { transform as sharedTransform } from '../_shared/flights_request.ts';
+
+type Params = Record<string, string | number | boolean | undefined | null>;
+
+// "WN 3489" / "WN3489" -> { carrier:"WN", flightNumber:"3489" }
+function parseFlight(v: unknown): { carrier: string; flightNumber: string } | null {
+  if (v == null || v === '') return null;
+  const s = String(v).trim();
+  const m = /^([A-Za-z0-9]{2})\s*([0-9]{1,5})$/.exec(s) ?? /^(\S+)\s+(\S+)$/.exec(s);
+  if (!m) return null;
+  const carrier = m[1];
+  const flightNumber = m[2];
+  if (carrier == null || flightNumber == null) return null;
+  return { carrier: carrier.toUpperCase(), flightNumber };
+}
+
+export function transform(
+  method: string,
+  url: string,
+  responses: Record<string, any>,
+  params?: Params,
+): { url: string; body: string } {
+  const p: Params = params ?? {};
+  const origin = p.origin != null ? String(p.origin) : '';
+  const destination = p.destination != null ? String(p.destination) : '';
+  const departureDate = p.departure_date ? String(p.departure_date) : null;
+  const returnDate = p.return_date != null ? String(p.return_date).trim() : '';
+  const roundTrip = returnDate !== '';
+  const tripType = roundTrip ? 1 : 2; // 1=round trip, 2=one way
+
+  const ob = parseFlight(p.outbound_flight);
+  const legs: any[] = [
+    {
+      origin,
+      dest: destination,
+      date: departureDate,
+      selected: ob
+        ? [
+            {
+              origin,
+              date: departureDate,
+              dest: destination,
+              carrier: ob.carrier,
+              flightNumber: ob.flightNumber,
+            },
+          ]
+        : null,
+    },
+  ];
+
+  if (roundTrip) {
+    const rb = parseFlight(p.return_flight);
+    legs.push({
+      origin: destination,
+      dest: origin,
+      date: returnDate,
+      selected: rb
+        ? [
+            {
+              origin: destination,
+              date: returnDate,
+              dest: origin,
+              carrier: rb.carrier,
+              flightNumber: rb.flightNumber,
+            },
+          ]
+        : null,
+    });
+  }
+
+  const mapped: Record<string, any> = {
+    tripType,
+    legs,
+    flight_token: p.flight_token != null ? String(p.flight_token) : null,
+  };
+
+  return sharedTransform(method, url, responses, mapped);
+}