opencode-skills-collection 3.0.37 → 3.0.39

package/bundled-skills/hasdata/references/scraper-jobs.md

@@ -0,0 +1,252 @@
+# Scraper Jobs — async, bulk
+
+Use only when there's no Scraper-API equivalent (`crawler`, `contacts`, `sec-edgar`, `amazon-bestsellers`, `amazon-product-reviews`) or when you want webhook-driven fan-out without managing your own polling loop. Otherwise the matching Scraper API + paginated client loop is simpler.
+
+| Slug | Notes |
+|---|---|
+| `crawler` | Recursive site crawl. Accepts every Web Scraping API parameter. |
+| `contacts` | URL list → emails / phones / social profiles. |
+| `sec-edgar` | Bulk SEC filings by CIK / ticker / company name. |
+| `google-serp`, `google-maps`, `google-maps-reviews`, `google-trends` | Bulk Google. |
+| `amazon-search`, `amazon-product`, `amazon-product-reviews`, `amazon-seller-products`, `amazon-bestsellers` | Bulk Amazon. |
+| `shopify` | Multi-store crawl. |
+| `zillow`, `redfin`, `airbnb` | Bulk real estate. |
+| `yelp`, `yellow-pages` | Bulk local. |
+| `indeed`, `glassdoor` | Bulk jobs. |
+
+## Lifecycle
+
+1. `POST /scrapers/<slug>/jobs` → returns the full job record. **The handle is `body.id` (numeric integer), not `jobId`** despite older doc snippets — store this. Status starts as `pending`.
+2. `GET /scrapers/jobs/<id>` — poll status.
+3. `GET /scrapers/jobs/<id>/results?page=…&limit=100` — once `status === "finished"`.
+4. `DELETE /scrapers/jobs/<id>` — stop early (rows produced before stop are kept).
+
+Status values: `pending` → `in_progress` → `finished` (or `stopped` if cancelled).
+
+**Shortcut for finished jobs:** the status response on a `finished` job carries a `data` object with direct download URLs:
+
+```json
+"data": {
+  "csv":  "https://f005.backblazeb2.com/file/.../{uuid}.csv",
+  "json": "https://f005.backblazeb2.com/file/.../{uuid}.json",
+  "xlsx": "https://f005.backblazeb2.com/file/.../{uuid}.xlsx"
+}
+```
+
+For one-shot ingestion, fetch `data.json` directly instead of paging `/results`. **These URLs are short-lived** — download immediately on `finished`.
+
+## End-to-end (Python)
+
+```python
+import os, time, requests
+
+API_KEY = os.environ["HASDATA_API_KEY"]
+H = {"x-api-key": API_KEY, "Content-Type": "application/json"}
+BASE = "https://api.hasdata.com"
+
+def submit(slug, body):
+    r = requests.post(f"{BASE}/scrapers/{slug}/jobs", headers=H, json=body, timeout=60)
+    r.raise_for_status()
+    return r.json()["id"]                            # numeric job id — not "jobId"
+
+def wait(job_id, poll=10, cap=60, timeout=3600):
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        s = requests.get(f"{BASE}/scrapers/jobs/{job_id}", headers=H, timeout=60).json()
+        if s["status"] in ("finished", "stopped"):
+            return s
+        time.sleep(poll)
+        poll = min(poll * 1.5, cap)
+    raise TimeoutError(job_id)
+
+def results(job_id):
+    page = 1
+    while True:
+        body = requests.get(
+            f"{BASE}/scrapers/jobs/{job_id}/results",
+            headers=H, params={"page": page, "limit": 100}, timeout=120,
+        ).json()
+        for row in body["data"]:
+            yield row["data"]                       # double-wrapped — see below
+        if body["meta"]["currentPage"] >= body["meta"]["lastPage"]:
+            return
+        page += 1
+```
+
+### Response shapes
+
+Submit (live):
+```json
+{
+  "id": 416349,                        // ← the job handle, integer
+  "scraperId": 26,
+  "status": "pending",
+  "creditsSpent": 0,
+  "dataRowsCount": 0,
+  "input": { ... },
+  "createdAt": "...", "updatedAt": "...",
+  "scraper": { "slug": "contacts", ... },
+  "columns": [ ... ]
+}
+```
+
+Status (live; numeric fields arrive as **strings** when populated):
+```json
+{
+  "id": 416349,
+  "status": "finished",
+  "creditsSpent": "5",                 // string!
+  "dataRowsCount": "1",                // string!
+  "input": { ... },
+  "data": {
+    "csv":  "https://f005.backblazeb2.com/.../{uuid}.csv",
+    "json": "https://f005.backblazeb2.com/.../{uuid}.json",
+    "xlsx": "https://f005.backblazeb2.com/.../{uuid}.xlsx"
+  }
+}
+```
+
+Results page:
+```json
+{
+  "meta": {
+    "total": 1, "perPage": 100,
+    "currentPage": 1, "lastPage": 1,
+    "firstPage": 1, "firstPageUrl": "/?page=1",
+    "lastPageUrl": "/?page=1",
+    "nextPageUrl": null, "previousPageUrl": null
+  },
+  "data": [
+    {
+      "id": "...", "jobId": 416349, "dataId": "...",
+      "data": { /* the actual scraped row */ },
+      "createdAt": "...", "updatedAt": "..."
+    }
+  ]
+}
+```
+
+**Double `data`** — the row is `body["data"][i]["data"]`; the outer wraps with `id`, `jobId`, `dataId`, `createdAt`, `updatedAt`.
+
+## Common body fields
+
+- `limit` (int) — max rows. `0` = no cap.
+- `webhook.url` (string, https), `webhook.events` (any subset of `scraper.job.started`, `scraper.data.scraped`, `scraper.job.finished`), `webhook.headers` (sent on every callback — pin a shared secret here).
+
+## Webhooks
+
+```python
+# Submit with webhook
+submit("indeed", {
+    "keywords":  ["software engineer", "data scientist"],
+    "locations": ["New York, NY", "Remote"],
+    "limit":     500,
+    "webhook":   {
+        "url":     "https://your.app/hasdata-hook",
+        "events":  ["scraper.data.scraped", "scraper.job.finished"],
+        "headers": {"x-shared-secret": SHARED_SECRET},
+    },
+})
+```
+
+```python
+from flask import Flask, request, abort
+app = Flask(__name__)
+
+@app.post("/hasdata-hook")
+def hook():
+    if request.headers.get("x-shared-secret") != SHARED_SECRET:
+        abort(401)
+    e = request.json
+    if e["event"] == "scraper.data.scraped":
+        save_row(e["jobId"], e["data"])
+    elif e["event"] == "scraper.job.finished":
+        finalize(e["jobId"])
+    return "", 200                  # 2xx prevents retry
+```
+
+- Async with **3 retries** on non-2xx. **Order not guaranteed** — payload is the source of truth.
+- **No documented HMAC.** Pin a shared secret via `webhook.headers`, or just fetch results via the API on `scraper.job.finished` and ignore per-row deliveries.
+- **Always pair webhooks with polling.** A long quiet period probably means missed callbacks.
+
+## Per-scraper bodies
+
+### `crawler` — recursive site crawl
+
+Accepts every Web Scraping API parameter applied to **every page**.
+
+| Field | Notes |
+|---|---|
+| `urls` | **Required.** Seed URLs. |
+| `maxDepth` | Hops from seed. |
+| `includePaths` / `excludePaths` | Regex. **Case-sensitive.** |
+| `limit` | Cap on pages. `0` = unlimited. |
+
+```python
+job = submit("crawler", {
+    "urls":         ["https://docs.example.com"],
+    "maxDepth":     5,
+    "includePaths": "/docs/.+",
+    "outputFormat": ["markdown"],
+    "excludeTags":  ["script", "style", "nav", "footer"],
+    "limit":        2000,
+})
+```
+
+### `contacts` — URLs → contact info
+
+```python
+submit("contacts", {"urls": ["https://example.com/about", "https://example.com/team"]})
+```
+
+Verified row schema (one row per input URL):
+
+```json
+{
+  "url": "https://example.com/about",
+  "emails":       ["..."],
+  "phoneNumbers": ["..."],
+  "linkedin":     ["..."],
+  "xcom":         ["..."],          // X / Twitter — note key is "xcom"
+  "facebook":     ["..."],
+  "instagram":    ["..."],
+  "dribbble":     ["..."],
+  "clutch":       ["..."]
+}
+```
+
+Empty arrays for missing categories — never null. If you only have a domain, discover URLs first via SERP `site:example.com`.
+
+### `sec-edgar` — bulk SEC filings
+
+```python
+submit("sec-edgar", {
+    "limit":       100,
+    "ciks":        ["AAPL", "789019", "Alphabet Inc."],
+    "filingTypes": "10-K, 10-Q, 8-K",
+    "startDate":   "2024-01-01",
+    "endDate":     "2025-12-31",
+})
+```
+
+`ciks` accepts CIKs, tickers, or company names mixed.
+
+### Bulk-API equivalents
+
+`google-serp`, `google-maps`, `amazon-search`, `indeed`, `glassdoor`, etc. Jobs accept arrays of inputs (`keywords[]`, `locations[]`, etc.). Use them when you want webhook fan-out; otherwise the synchronous Scraper API + paginated client loop is simpler.
+
+### Crawler vs Contacts vs Web Scraping batch
+
+- **crawler** — unknown URL set, recursive discovery.
+- **contacts** — known URL list, want extracted contact fields.
+- **`/scrape/batch/web`** — known URL list, want full HTML/markdown/AI extraction at >1k scale.
+
+## Gotchas
+
+- **Persist the job `id` immediately** (the integer from the submit response — *not* `jobId`). Only handle to status, results, stop.
+- **Result file retention is short.** Download right after `finished`.
+- **Webhooks are best-effort.** Always poll as a backup.
+- **`includePaths` regex is case-sensitive.**
+- **Status `stopped` is terminal.** Rows already produced remain available.
+- **Don't poll faster than every 10 s** — wastes concurrency cap.
+- **Double-wrapped results** — `body["data"][i]["data"]`, not `body["data"][i]`.

package/bundled-skills/hasdata/references/search.md

@@ -0,0 +1,154 @@
+# Search & SERP APIs
+
+Pre-parsed JSON for Google, AI Mode, Bing, and the specialized Google panels. Synchronous `GET` under `https://api.hasdata.com`.
+
+| Endpoint | Returns |
+|---|---|
+| `/scrape/google/serp` | Full SERP — organic + every rich-snippet block |
+| `/scrape/google-light/serp` | Organic only |
+| `/scrape/google/ai-mode` | Gemini answer + references |
+| `/scrape/google/ai-overview` | AI Overview block |
+| `/scrape/google/news` | News articles |
+| `/scrape/google/shopping` | Shopping carousel |
+| `/scrape/google/images` | Image search |
+| `/scrape/google/events` | Local events |
+| `/scrape/google/short-videos` | Short-video panel |
+| `/scrape/google/immersive-product` | Expanded product pop-up |
+| `/scrape/google-trends/search` | Trends + related queries |
+| `/scrape/bing/serp` | Bing SERP |
+
+For `/scrape/google/flights`, see `travel.md`.
+
+## Google SERP
+
+```python
+import requests
+
+resp = requests.get(
+    "https://api.hasdata.com/scrape/google/serp",
+    headers={"x-api-key": API_KEY},
+    params={"q": "coffee beans", "gl": "us", "hl": "en", "num": 100},
+    timeout=300,
+)
+for hit in resp.json().get("organicResults", []):
+    print(hit["position"], hit["title"], hit["link"])
+```
+
+### Query parameters
+
+| Param | Default | Notes |
+|---|---|---|
+| `q` | — | **Required.** |
+| `location` | — | Canonical, e.g. `"Austin,Texas,United States"`. Hyper-local. |
+| `uule` | — | Pre-encoded location (mutually exclusive with `location`). |
+| `domain` | `google.com` | `google.co.uk`, `google.de`, … |
+| `gl` | — | 2-letter country (`us`, `de`, `jp`). |
+| `hl` | — | 2-letter UI language. |
+| `lr` | — | Content-language filter (`lang_en`). |
+| `tbs` | — | Filters — `qdr:d|w|m|y` for time, `li:1` verbatim, sort, image type. |
+| `safe` | — | `active` / `off`. |
+| `start` | `0` | Pagination offset. |
+| `num` | `10` | Results/page. **Max 100** |
+| `tbm` | — | `isch` images, `vid`, `nws`, `shop`, `lcl`. |
+| `deviceType` | — | `desktop`, `mobile`, `tablet`. |
+
+### Response keys
+
+```
+requestMetadata, searchInformation, organicResults, knowledgeGraph, answerBox,
+aiOverview, topStories, newsResults, localResults, inlineShoppingResults,
+inlineVideos, inlineImages, recipesResults, perspectives, discussionsAndForums,
+relatedQuestions, relatedSearches, adResults, pagination
+```
+
+Rich-snippet keys appear **only when the SERP shows that block** — always `data.get(key, default)`.
+
+### Tips
+
+- `gl`/`hl` change ranking, not just localization. Run the same `q` with different `gl` to study geo-bias.
+- `location="Austin,Texas,United States"` produces hyperlocal results that differ from `gl=us` alone.
+
+## Google Light SERP
+
+Same params as full SERP, but the response is trimmed to a few keys — typically `requestMetadata`, `searchInformation`, `organicResults`, `relatedSearches`, and `pagination` when present. Use for crawler seeding and link discovery when you don't need the heavier rich-snippet blocks.
+
+## Google AI Mode
+
+```python
+resp = requests.get(
+    "https://api.hasdata.com/scrape/google/ai-mode",
+    headers={"x-api-key": API_KEY},
+    params={"q": "is coffee good for health?", "location": "Austin,Texas,United States"},
+    timeout=300,
+)
+```
+
+Params: `q` (required), `location`, `uule`, `gl`. Response:
+
+```json
+{
+  "requestMetadata": {...},
+  "textBlocks": [
+    {"type":"heading","snippet":"..."},
+    {"type":"paragraph","snippet":"...","snippetHighlightedWords":["..."]},
+    {"type":"list","list":[{"snippet":"..."}]},
+    {"type":"table","table":{...}},
+    {"type":"code","code":"..."}
+  ],
+  "references": [{"index":1,"link":"...","title":"...","snippet":"...","source":"..."}]
+}
+```
+
+Block types observed in practice: `heading`, `paragraph`, `list`, `table`, `code`. Always switch on `type` rather than assuming a fixed set.
+
+Pattern: AI Mode for the answer → `/scrape/web` (markdown) on each `references[].link` → cited RAG context.
+
+## Google News / Shopping / Bing
+
+Same shape: `q` + `gl`/`hl`/`location`. News supports `tbs=qdr:d|w|m|y` for time windows. Bing returns the same key set as Google SERP — useful for cross-engine consensus (disagreement = contested topic).
+
+## Patterns
+
+### Pagination
+
+```python
+def all_organic(q, target=300):
+    out, start = [], 0
+    while len(out) < target:
+        page = requests.get(
+            "https://api.hasdata.com/scrape/google-light/serp",
+            headers={"x-api-key": API_KEY},
+            params={"q": q, "num": 100, "start": start},
+            timeout=300,
+        ).json().get("organicResults", [])
+        if not page:
+            break
+        out.extend(page)
+        start += 100
+    return out[:target]
+```
+
+### Reverse lookup (email / phone / domain → identity)
+
+```python
+requests.get(
+    "https://api.hasdata.com/scrape/google/serp",
+    headers={"x-api-key": API_KEY},
+    params={"q": f'"{literal}"', "num": 20},
+    timeout=300,
+).json().get("organicResults", [])
+```
+
+Quoted literals (emails, phones, error strings) usually surface the canonical mention.
+
+### Indexation check
+
+```python
+def is_indexed(url):
+    r = requests.get(
+        "https://api.hasdata.com/scrape/google-light/serp",
+        headers={"x-api-key": API_KEY},
+        params={"q": f"site:{url}", "num": 1}, timeout=300,
+    )
+    return bool(r.json().get("organicResults"))
+```

package/bundled-skills/hasdata/references/travel.md

@@ -0,0 +1,202 @@
+# Travel APIs — Airbnb, Booking, Google Flights
+
+| Endpoint | Returns |
+|---|---|
+| `/scrape/airbnb/listing` | Airbnb search results |
+| `/scrape/airbnb/property` | Single Airbnb listing |
+| `/scrape/booking/search` | Booking.com search results (hotels, apartments) |
+| `/scrape/booking/place` | Single Booking.com property with room/rate list |
+| `/scrape/google/flights` | Google Flights prices and itineraries |
+
+All synchronous `GET`. Airbnb is 5 credits; Booking is 10; Google Flights is 15.
+
+For activities at the destination see `/scrape/google/events` (in `search.md`); for ground transport, scrape the operator's site with `POST /scrape/web`.
+
+## Airbnb
+
+```python
+import requests
+
+def airbnb_search(location, check_in, check_out, **kwargs):
+    return requests.get(
+        "https://api.hasdata.com/scrape/airbnb/listing",
+        headers={"x-api-key": API_KEY},
+        params={"location": location, "checkIn": check_in, "checkOut": check_out, **kwargs},
+        timeout=300,
+    ).json()
+```
+
+| Param | Notes |
+|---|---|
+| `location` | **Required.** Free-form. |
+| `checkIn` | **Required.** `YYYY-MM-DD`. |
+| `checkOut`, `adults`, `children`, `infants`, `pets` | Optional. |
+| `nextPageToken` | Pagination cursor. |
+
+### Token pagination
+
+```python
+def airbnb_all(location, check_in, check_out):
+    out, token = [], None
+    while True:
+        page = airbnb_search(location, check_in, check_out,
+                             **({"nextPageToken": token} if token else {}))
+        out.extend(page.get("listings", []))
+        token = page.get("nextPageToken")
+        if not token:
+            return out
+```
+
+### Airbnb Property
+
+```python
+requests.get(
+    "https://api.hasdata.com/scrape/airbnb/property",
+    headers={"x-api-key": API_KEY},
+    params={"url": "https://www.airbnb.com/rooms/12345678"},
+    timeout=300,
+)
+```
+
+## Booking Search
+
+```python
+import json, requests
+
+def booking_search(keyword, check_in, check_out, *, adults=2, children=0,
+                   children_ages=None, rooms=1, **filters):
+    params = {
+        "keyword":      keyword,
+        "checkInDate":  check_in,
+        "checkOutDate": check_out,
+        "adults":       adults,
+        "children":     children,
+        "rooms":        rooms,
+        **filters,
+    }
+    if children and children_ages:
+        params["childrenAgesJson"] = json.dumps(children_ages)
+    return requests.get(
+        "https://api.hasdata.com/scrape/booking/search",
+        headers={"x-api-key": API_KEY},
+        params=params, timeout=300,
+    ).json()
+```
+
+| Param | Notes |
+|---|---|
+| `keyword` | **Required.** City, neighborhood, or property name. |
+| `checkInDate` / `checkOutDate` | **Required.** `YYYY-MM-DD`. |
+| `adults`, `children`, `rooms` | **Required.** Pass `children=0` explicitly when none. |
+| `childrenAgesJson` | Required iff `children > 0` — JSON array of ages (0–17), one per child. |
+| `price[min]` / `price[max]` | `>= 10` / `>= 20`. Bracketed — `requests`/`axios` serialize nested dicts as `price[min]=…`. |
+| `rating[]`, `reviewScore[]`, `propertyType[]`, `facilities[]`, `meals[]`, `bedPreference[]`, `roomFacilities[]`, `propertyAccessibility[]`, `roomAccessibility[]`, `distanceFromCenter[]`, `travelGroup[]`, `onlinePayment[]`, `reservationPolicy[]` | Multi-value filters (OR). |
+| `bedrooms`, `bathrooms` | Minimum count. |
+| `sort` | `ourTopPicks`, `homesAndApartmentsFirst`, `priceLowestFirst`, `priceHighestFirst`, `bestReviewedAndLowestPrice`, `ratingHighToLow`, `ratingLowToHigh`, `ratingAndPrice`, `distanceFromDowntown`, `topReviewed`. |
+| `page` | 1-indexed, 25 results per page. |
+| `currency` | ISO code or `hotelCurrency` to keep native. |
+| `language` | UI locale. |
+
+Top-level response (verified live): `requestMetadata`, `searchInformation`, `pagination`, `results`. Per-result keys: `hotelId`, `roomId`, `title`, `url`, `location`, `rating`, `reviews`, `price` (object with `total` / `nightly` / `currency`), `room`, `beds`, `bedTypes`, `policies`, `photo`.
+
+## Booking Place
+
+```python
+resp = requests.get(
+    "https://api.hasdata.com/scrape/booking/place",
+    headers={"x-api-key": API_KEY},
+    params={
+        "url":           "https://www.booking.com/hotel/fr/le-bristol-paris.html",
+        "checkInDate":   "2026-07-10",
+        "checkOutDate":  "2026-07-13",
+        "adults":         2,
+        "children":       0,
+        "rooms":          1,
+    },
+    timeout=300,
+).json()
+```
+
+`url` must be `booking.com` / `www.booking.com`. The remaining stay/guest parameters share the same rules as `booking-search` (including `childrenAgesJson` when `children > 0`).
+
+Response top-level keys: `requestMetadata`, `overview`, `bookingDetails`, `rooms`, `facilities`, `houseRules`, `ratings`, `reviews`, `restaurants`, `breadcrumbs`, `questionsAndAnswers`.
+
+- `overview` → `id`, `title`, `address`, `description`, `propertyType`, `photos`, `highlights`, `mostPopularFacilities`.
+- `rooms[i]` → `roomId`, `name`, `bedTypes`, `beds`, `facilities`, `otherFacilities`, `variants[]` (per-rate price/availability). Variants are the actual buyable units; `rooms[i]` is the floor-plan.
+
+## Google Flights
+
+```python
+resp = requests.get(
+    "https://api.hasdata.com/scrape/google/flights",
+    headers={"x-api-key": API_KEY},
+    params={
+        "departureId":  "JFK",
+        "arrivalId":    "LAX",
+        "outboundDate": "2026-06-15",
+        "returnDate":   "2026-06-22",     # omit for one-way
+        "currency":     "USD",
+    },
+    timeout=300,
+).json()
+```
+
+| Param | Notes |
+|---|---|
+| `departureId` / `arrivalId` | **Required.** IATA airport codes (`JFK`, `LAX`). |
+| `outboundDate` | **Required.** `YYYY-MM-DD`. |
+| `returnDate` | Optional — omit for one-way. |
+| `currency` | ISO code. |
+| `gl`, `hl` | Country / language. |
+| `travelClass` | `1` economy, `2` premium economy, `3` business, `4` first. |
+| `stops` | `0` any, `1` non-stop, `2` ≤1 stop, `3` ≤2 stops. |
+| `adults`, `children`, `infantsInSeat`, `infantsOnLap` | Passenger counts. |
+
+## Patterns
+
+### STR yield estimate
+
+```python
+rentals = airbnb_search(area, ci, co).get("listings", [])           # Airbnb → "listings"
+# pair with /scrape/zillow/listing (see real-estate.md) for purchase price
+night   = sum(r.get("price", 0) for r in rentals) / max(len(rentals), 1)
+```
+
+### Hotel-vs-rental price diff
+
+```python
+b = booking_search(city, ci, co, adults=2, children=0, rooms=1, sort="priceLowestFirst")
+a = airbnb_search(city, ci, co, adults=2)
+def median(xs): xs = sorted(xs); return xs[len(xs)//2] if xs else None
+median_hotel = median([r["price"]["nightly"] for r in b.get("results", []) if r.get("price")])
+median_str   = median([r["price"]            for r in a.get("listings", []) if r.get("price")])
+```
+
+### Full trip cost
+
+```python
+flight = requests.get(
+    "https://api.hasdata.com/scrape/google/flights",
+    headers={"x-api-key": API_KEY},
+    params={"departureId": origin, "arrivalId": dest_iata,
+            "outboundDate": dep, "returnDate": ret, "currency": "USD"},
+    timeout=300,
+).json()
+cheapest_flight = min((f["price"] for f in flight.get("best_flights", [])), default=None)
+
+stay = booking_search(city, dep, ret, adults=2, children=0, rooms=1, sort="priceLowestFirst")
+cheapest_stay = stay.get("results", [{}])[0].get("price", {}).get("total")
+
+total = (cheapest_flight or 0) + (cheapest_stay or 0)
+```
+
+## Gotchas
+
+- **Airbnb requires `checkIn`** and uses **token** pagination — store `nextPageToken`, not page numbers.
+- **Airbnb property endpoints take URLs**, not IDs.
+- **Booking requires `children` even when zero.** Pass `children=0`. When `children > 0`, also pass `childrenAgesJson` with exactly that many ages.
+- **Booking `price[min]` / `price[max]`** are bracketed — use a nested dict with `requests`/`axios`.
+- **Booking `rooms[i].variants[]` is where prices live** — the parent `rooms[i]` describes the floor-plan, variants are the buyable rates with `priceBreakdown` / `cancellationPolicy` / `mealPlan`.
+- **`bookingDetails` carries the resolved stay context** the response was priced for — echo it back when persisting results so future comparisons use the same dates / occupancy.
+- **Google Flights uses IATA codes**, not city names. `JFK` not `New York`.
+- **Round-trip vs one-way** is determined by `returnDate` presence — pass it for round-trip, omit for one-way.