tablefacts 0.1.0

package/src/research/lib/website.mjs

@@ -0,0 +1,285 @@
+// Reads a restaurant's own web pages (and link-in-bio hubs like Linktree, and a
+// TripAdvisor page when it lets us in) with plain fetch and regexes: no HTML
+// parser dependency. Falls back to Playwright when a page renders client-side.
+import { loadPlaywright } from "../../lib/playwright.mjs";
+import { fetchText, sleep, BROWSER_UA } from "./util.mjs";
+import { fromOsm, fromSpec } from "./hours.mjs";
+
+const ENT = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", nbsp: " " };
+const decode = (s) =>
+  s.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (m, e) => {
+    if (e[0] === "#") {
+      const n = e[1].toLowerCase() === "x" ? parseInt(e.slice(2), 16) : Number(e.slice(1));
+      return Number.isFinite(n) ? String.fromCodePoint(n) : m;
+    }
+    return ENT[e.toLowerCase()] ?? m;
+  });
+
+const attrs = (tag) => {
+  const out = {};
+  for (const m of tag.matchAll(/([a-zA-Z_:][-\w:.]*)\s*(?:=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>]+)))?/g))
+    out[m[1].toLowerCase()] = decode(m[2] ?? m[3] ?? m[4] ?? "");
+  return out;
+};
+const abs = (u, base) => { try { return new URL(u, base).href; } catch { return null; } };
+const strip = (s) => decode(s.replace(/<[^>]+>/g, " ")).replace(/\s+/g, " ").trim();
+const host = (u) => { try { return new URL(u).hostname.replace(/^www\./, ""); } catch { return ""; } };
+
+const IG_RESERVED = new Set(["p", "reel", "reels", "explore", "accounts", "tv", "stories", "share", "direct", "about", "legal", "web", "developer"]);
+const RESERVE = /(opentable|resy\.com|thefork|eltenedor|exploretock|sevenrooms|covermanager|quandoo|tablein|mesa247|bookatable|tablecheck|resos\.com|reservandonos|agendapro|fudo\.)/i;
+const DELIVERY = /(rappi|ubereats|pedidosya|doordash|grubhub|domicilios\.com|didi-food|glovoapp)/i;
+const HUBS = /(linktr\.ee|beacons\.ai|bio\.link|lnk\.bio|linktree\.com|taplink|campsite\.bio|solo\.to|linkin\.bio|flow\.page)/i;
+const DAY_RE = /\b(lun(es)?|mar(tes)?|mi[eé](rcoles)?|jue(ves)?|vie(rnes)?|s[aá]b(ado)?|dom(ingo)?|mon(day)?|tue(sday)?|wed(nesday)?|thu(rsday)?|fri(day)?|sat(urday)?|sun(day)?)\b/i;
+const TIME_RE = /\d{1,2}([:.]\d{2})?\s*(am|pm|h|hrs)?\s*(-|–|—|a|to|hasta)\s*\d{1,2}([:.]\d{2})?/i;
+const BUSINESS_TYPE = /Restaurant|FoodEstablishment|BarOrPub|CafeOrCoffeeShop|Bakery|NightClub|LocalBusiness|Hotel/;
+
+function visibleLines(html) {
+  const body = html
+    .replace(/<!--[\s\S]*?-->/g, "")
+    .replace(/<(script|style|noscript|svg|template|head)\b[\s\S]*?<\/\1>/gi, "");
+  return decode(body.replace(/<\/(p|div|li|h[1-6]|tr|section|article|header|footer|ul|ol|table)>|<br\s*\/?>/gi, "\n").replace(/<[^>]+>/g, " "))
+    .split("\n").map((l) => l.replace(/\s+/g, " ").trim()).filter(Boolean);
+}
+
+function jsonLd(html) {
+  const nodes = [];
+  for (const m of html.matchAll(/<script[^>]+application\/ld\+json[^>]*>([\s\S]*?)<\/script>/gi)) {
+    try {
+      const data = JSON.parse(decode(m[1]).trim());
+      for (const n of [data].flat()) nodes.push(...(n["@graph"] ? n["@graph"] : [n]));
+    } catch { /* malformed block: skip it */ }
+  }
+  const biz = nodes.find((n) => BUSINESS_TYPE.test([n["@type"]].flat().join(" ")));
+  if (!biz) return null;
+  const addr = biz.address && typeof biz.address === "object" ? biz.address : {};
+  const text = (v) => (typeof v === "string" ? v : v?.name ?? v?.url ?? "");
+  return {
+    name: text(biz.name),
+    telephone: text(biz.telephone),
+    email: text(biz.email),
+    priceRange: text(biz.priceRange),
+    cuisines: [biz.servesCuisine].flat().filter((c) => typeof c === "string"),
+    address: { street: addr.streetAddress ?? "", locality: addr.addressLocality ?? "", region: addr.addressRegion ?? "", postcode: addr.postalCode ?? "", country: typeof addr.addressCountry === "string" ? addr.addressCountry : addr.addressCountry?.name ?? "" },
+    geo: biz.geo?.latitude ? { lat: Number(biz.geo.latitude), lng: Number(biz.geo.longitude) } : null,
+    sameAs: [biz.sameAs].flat().filter((u) => typeof u === "string"),
+    logo: text(biz.logo),
+    rating: biz.aggregateRating ? { value: Number(biz.aggregateRating.ratingValue), count: Number(biz.aggregateRating.reviewCount ?? biz.aggregateRating.ratingCount) || null } : null,
+    hours: fromSpec(biz.openingHoursSpecification) ?? fromOsm([biz.openingHours].flat().filter(Boolean).join("; ")),
+  };
+}
+
+/** Pulls every fact a page holds. `base` resolves relative links. */
+export function analyzeHtml(html, base, lines = visibleLines(html)) {
+  const meta = {};
+  for (const m of html.matchAll(/<meta\b([^>]*)>/gi)) {
+    const a = attrs(m[1]);
+    const key = (a.property || a.name || "").toLowerCase();
+    if (key && a.content && !(key in meta)) meta[key] = a.content;
+  }
+  const anchors = [...html.matchAll(/<a\b([^>]*)>([\s\S]*?)<\/a>/gi)]
+    .map((m) => ({ href: abs(attrs(m[1]).href ?? "", base), text: strip(m[2]) }))
+    .filter((a) => a.href);
+  // Hubs and single-page apps keep their links in JSON blobs, not in <a> tags.
+  const hrefs = new Set(anchors.map((a) => a.href));
+  for (const m of html.matchAll(/"(?:url|href|link)"\s*:\s*"(https?:[^"]+)"/g)) {
+    const u = m[1].replace(/\\u0026/g, "&").replace(/\\\//g, "/");
+    if (!hrefs.has(u)) {
+      hrefs.add(u);
+      anchors.push({ href: u, text: "" });
+    }
+  }
+
+  const links = { tel: [], mail: [], whatsapp: [], reserve: [], menu: [], delivery: [], maps: [], waze: [], facebook: [], tiktok: [], tripadvisor: [], hubs: [], instagram: [] };
+  const ig = new Map();
+  const push = (k, v) => { if (v && !links[k].includes(v)) links[k].push(v); };
+  for (const { href, text } of anchors) {
+    let u;
+    try { u = new URL(href); } catch { continue; }
+    const h = u.hostname.replace(/^www\./, "");
+    if (u.protocol === "tel:") push("tel", decodeURIComponent(href.slice(4)).trim());
+    else if (u.protocol === "mailto:") push("mail", decodeURIComponent(href.slice(7).split("?")[0]).trim());
+    else if (/(^|\.)wa\.me$|whatsapp\.com$|wa\.link$/.test(h)) {
+      const num = (u.pathname.match(/^\/(\d{7,})/)?.[1]) ?? u.searchParams.get("phone");
+      push("whatsapp", num ? num.replace(/\D/g, "") : href);
+    } else if (/(^|\.)instagram\.com$/.test(h)) {
+      const handle = u.pathname.split("/")[1]?.toLowerCase();
+      if (handle && !IG_RESERVED.has(handle) && /^[a-z0-9._]+$/.test(handle)) ig.set(handle, (ig.get(handle) ?? 0) + 1);
+    } else if (/facebook\.com$|fb\.com$/.test(h)) push("facebook", href);
+    else if (/tiktok\.com$/.test(h)) push("tiktok", href);
+    else if (/tripadvisor\./.test(h)) push("tripadvisor", href);
+    else if (/maps\.app\.goo\.gl|google\.[a-z.]+\/maps|goo\.gl\/maps/.test(href)) push("maps", href);
+    else if (/waze\.com/.test(h)) push("waze", href);
+    else if (HUBS.test(h)) push("hubs", href);
+    else if (RESERVE.test(href)) push("reserve", href);
+    else if (DELIVERY.test(href)) push("delivery", href);
+    else if (/\.pdf($|\?)/i.test(u.pathname) || /\b(menu|men[uú]|carta)\b/i.test(`${text} ${u.pathname}`)) push("menu", href);
+  }
+  links.instagram = [...ig].sort((a, b) => b[1] - a[1]).map(([h]) => h);
+
+  const images = [];
+  const imageKeys = new Set();
+  const addImage = (url, alt = "", extra = {}) => {
+    if (!url || /^data:/.test(url) || /(icon|sprite|favicon|pixel|spacer|avatar|badge|payment|flag|tripadvisor|facebook|instagram|whatsapp)\b/i.test(url)) return;
+    const key = url.split("?")[0];
+    if (!imageKeys.has(key)) {
+      imageKeys.add(key);
+      images.push({ url, alt, ...extra });
+    }
+  };
+  addImage(abs(meta["og:image"], base), "og:image");
+  const logos = [];
+  for (const m of html.matchAll(/<img\b([^>]*)>/gi)) {
+    const a = attrs(m[1]);
+    const srcset = (a.srcset || a["data-srcset"] || "").split(",").map((s) => s.trim().split(/\s+/)).filter((p) => p[0]);
+    const best = srcset.sort((x, y) => parseInt(y[1] ?? "0") - parseInt(x[1] ?? "0"))[0]?.[0];
+    const url = abs(best || a.src || a["data-src"] || a["data-lazy-src"], base);
+    if (!url) continue;
+    if (/logo/i.test(`${a.src} ${a.class} ${a.id} ${a.alt}`)) logos.push({ url, kind: "img" });
+    else addImage(url, a.alt, { width: Number(a.width) || undefined, height: Number(a.height) || undefined });
+  }
+  for (const m of html.matchAll(/url\(\s*['"]?([^'")]+\.(?:jpe?g|png|webp))['"]?\s*\)/gi)) addImage(abs(m[1], base));
+  for (const m of html.matchAll(/<link\b([^>]*)>/gi)) {
+    const a = attrs(m[1]);
+    if (/apple-touch-icon|icon/.test(a.rel ?? "") && a.href) logos.push({ url: abs(a.href, base), kind: a.rel });
+  }
+
+  const ld = jsonLd(html);
+  if (ld?.logo) logos.unshift({ url: abs(ld.logo, base), kind: "json-ld" });
+  return {
+    url: base,
+    title: strip(html.match(/<title[^>]*>([\s\S]*?)<\/title>/i)?.[1] ?? ""),
+    lang: (html.match(/<html[^>]*\blang=["']?([a-zA-Z-]+)/i)?.[1] ?? "").toLowerCase(),
+    meta: { siteName: meta["og:site_name"] ?? "", title: meta["og:title"] ?? "", description: meta["og:description"] ?? meta.description ?? "", themeColor: meta["theme-color"] ?? "" },
+    jsonld: ld, links, images, logos,
+    textLength: lines.join(" ").length,
+    headings: [...html.matchAll(/<h[1-3][^>]*>([\s\S]*?)<\/h[1-3]>/gi)].map((m) => strip(m[1])).filter((t) => t && t.length < 140),
+    paragraphs: lines.filter((l) => l.length >= 70 && !/[©]|cookie/i.test(l)).slice(0, 12),
+    hoursText: lines.filter((l) => l.length <= 160 && ((DAY_RE.test(l) && TIME_RE.test(l)) || /^(horarios?|opening hours|hours)\b/i.test(l))),
+    anchors: anchors.filter((a) => /^https?:/.test(a.href)),
+  };
+}
+
+/**
+ * One lazily launched Chromium shared by every render of a run. `get()` launches on first use;
+ * `close()` is safe to call when nothing was launched.
+ */
+export function createBrowser() {
+  let launching = null;
+  return {
+    get() {
+      launching ??= loadPlaywright().then(({ chromium }) => chromium.launch());
+      return launching;
+    },
+    async close() {
+      if (!launching) return;
+      const pending = launching;
+      launching = null;
+      try { await (await pending).close(); } catch { /* it never launched */ }
+    },
+  };
+}
+
+// `strict` (the caller asked for rendering) reports a missing Playwright; the automatic fallbacks stay silent.
+async function render(url, strict, browser) {
+  let page;
+  try {
+    page = await (await browser.get()).newPage({ userAgent: BROWSER_UA });
+    await page.goto(url, { waitUntil: "networkidle", timeout: 25000 });
+    return await page.content();
+  } catch (e) {
+    if (strict && e.code === "EDEPENDENCY") throw e;
+    return null;
+  } finally {
+    await page?.close().catch(() => {});
+  }
+}
+
+/** One page, analysed. Returns { page, blocked } and never throws on HTTP errors. `browser` is a shared createBrowser(); without one a private browser is used and closed. */
+export async function readPage(url, { renderJs = false, browser } = {}) {
+  const own = browser ? null : createBrowser();
+  const shared = browser ?? own;
+  try {
+    let r;
+    try { r = await fetchText(url); } catch (e) { return { page: null, blocked: `${e.message}` }; }
+    if (!r.ok) {
+      // Bot walls answer 403/429/503 to a plain fetch; a real browser often gets through.
+      const html = [403, 429, 503].includes(r.status) ? await render(url, false, shared) : null;
+      return html ? { page: { ...analyzeHtml(html, url), rendered: true } } : { page: null, blocked: `HTTP ${r.status}` };
+    }
+    // Decide "thin" from the visible text first, so a thin page is parsed only once (rendered) and a full one once (as fetched).
+    const lines = visibleLines(r.text);
+    if (renderJs || lines.join(" ").length < 300) {
+      const html = await render(r.url, renderJs, shared);
+      if (html) return { page: { ...analyzeHtml(html, r.url), rendered: true } };
+    }
+    return { page: analyzeHtml(r.text, r.url, lines) };
+  } finally {
+    await own?.close();
+  }
+}
+
+const PAGE_HINT = /contact|ubica|visit|about|nosotros|historia|story|nuestra|menu|carta|reserv|evento|event|horario|hours|donde|find/i;
+
+/** The restaurant's own site: the home page plus a few contact/about/menu pages, merged. */
+export async function scrapeSite(startUrl, { renderJs = false, maxPages = 6, browser } = {}) {
+  const own = browser ? null : createBrowser();
+  try {
+    return await scrape(startUrl, { renderJs, maxPages, browser: browser ?? own });
+  } finally {
+    await own?.close();
+  }
+}
+
+async function scrape(startUrl, { renderJs, maxPages, browser }) {
+  const first = await readPage(startUrl, { renderJs, browser });
+  if (!first.page) throw new Error(`could not read ${startUrl} (${first.blocked})`);
+  const pages = [first.page];
+  const seen = new Set([first.page.url.split("#")[0]]);
+  const same = host(first.page.url);
+  const next = first.page.anchors
+    .filter((a) => host(a.href) === same && !/\.(pdf|jpe?g|png|webp|svg|zip)($|\?)/i.test(a.href) && PAGE_HINT.test(`${a.text} ${new URL(a.href).pathname}`))
+    .map((a) => a.href.split("#")[0]);
+  const queue = [];
+  for (const url of next) {
+    if (seen.has(url)) continue;
+    seen.add(url);
+    queue.push(url);
+  }
+  // Batches of 3 pages, started 200 ms apart: it is the restaurant's own site, so no hammering.
+  for (let i = 0; i < queue.length && pages.length < maxPages; ) {
+    const batch = queue.slice(i, i + Math.min(3, maxPages - pages.length));
+    i += batch.length;
+    const read = await Promise.all(
+      batch.map(async (url, n) => {
+        await sleep(n * 200);
+        return readPage(url, { renderJs, browser });
+      }),
+    );
+    for (const { page } of read) if (page) pages.push(page);
+  }
+
+  const uniq = (list, key = (x) => x) => {
+    const keys = new Set();
+    return list.filter((x) => {
+      const k = key(x);
+      if (keys.has(k)) return false;
+      keys.add(k);
+      return true;
+    });
+  };
+  const links = {};
+  for (const k of Object.keys(pages[0].links)) links[k] = uniq(pages.flatMap((p) => p.links[k]));
+  return {
+    url: first.page.url,
+    pages: pages.map((p) => ({ url: p.url, title: p.title, rendered: !!p.rendered })),
+    lang: first.page.lang,
+    meta: first.page.meta,
+    jsonld: pages.map((p) => p.jsonld).find(Boolean) ?? null,
+    links,
+    images: uniq(pages.flatMap((p) => p.images), (i) => i.url.split("?")[0]),
+    logos: uniq(pages.flatMap((p) => p.logos), (l) => l.url),
+    headings: uniq(pages.flatMap((p) => p.headings)).slice(0, 30),
+    paragraphs: uniq(pages.flatMap((p) => p.paragraphs)).slice(0, 20),
+    hoursText: uniq(pages.flatMap((p) => p.hoursText)).slice(0, 12),
+  };
+}

package/src/research/research.mjs

@@ -0,0 +1,67 @@
+// Gathers what the public web says about a restaurant, to fill the template.
+// Usage: tablefacts research "Restaurant name" "City, Country" [options]
+import { parseArgs } from "node:util";
+import { research } from "./index.mjs";
+import { loadEnv } from "../lib/env.mjs";
+import { cliMessage, exitCodeFor } from "../lib/errors.mjs";
+import { consoleLog } from "../lib/log.mjs";
+
+const HELP = `Research a restaurant from public sources and write a profile for the template.
+
+  tablefacts research "<name>" "<city, country>" [options]
+
+Sources: Google Maps (Places API), OpenStreetMap, the restaurant's website,
+Instagram, TripAdvisor and link-in-bio pages (Linktree and similar). They find
+each other: the website or Google leads to Instagram, TripAdvisor and the hub.
+
+Options:
+  --country <ISO>       country code, narrows the search (CO, MX, US...)
+  --website <url>       the restaurant's site, if the search does not find it
+  --instagram <handle>  Instagram handle or URL
+  --tripadvisor <url>   TripAdvisor page
+  --linktree <url>      Linktree or other link-in-bio page
+  --photos <n>          also download up to n Google and n website photos (reference only)
+  --render              render the website with Playwright (sites built in JavaScript)
+  --no-google           skip Google even if GOOGLE_PLACES_API_KEY is set
+  --out <dir>           output folder (default .tablefacts/research/<slug>)
+  -h, --help            this text
+
+Writes profile.json, report.md and setup-answers.txt. GOOGLE_PLACES_API_KEY goes
+in .env (see .env.example); without it OpenStreetMap and the web pages
+still work, with fewer facts.`;
+
+const { values, positionals } = parseArgs({
+  allowPositionals: true,
+  options: {
+    country: { type: "string" }, website: { type: "string" }, instagram: { type: "string" },
+    tripadvisor: { type: "string" }, linktree: { type: "string" }, photos: { type: "string" },
+    render: { type: "boolean" }, "no-google": { type: "boolean" }, out: { type: "string" },
+    help: { type: "boolean", short: "h" },
+  },
+});
+if (values.help || !positionals.length) {
+  console.log(HELP);
+  process.exit(values.help ? 0 : 1);
+}
+
+loadEnv();
+const [name, location = ""] = positionals;
+try {
+  const { profile, outDir } = await research({
+    name, location, country: values.country, website: values.website, instagram: values.instagram,
+    tripadvisor: values.tripadvisor, linktree: values.linktree, render: values.render,
+    google: !values["no-google"], photos: Number(values.photos ?? 0), out: values.out, log: consoleLog,
+  });
+  const found = Object.keys(profile.fields).filter((k) => profile.fields[k]);
+  console.log(`
+Found ${found.length} fields: ${found.join(", ")}`);
+  for (const w of profile.warnings) console.log(`Warning: ${w}`);
+  console.log(`
+Wrote ${outDir}
+  report.md          read this first
+  profile.json       everything, with sources
+  setup-answers.txt  npm run setup < that file`);
+} catch (e) {
+  console.error(cliMessage(e, { name: "<name>" }));
+  process.exitCode = exitCodeFor(e);
+}

package/src/tripadvisor/README.md

@@ -0,0 +1,78 @@
+# TripAdvisor photos
+
+Downloads the photos on a restaurant's TripAdvisor page, driven by Playwright in **the user's own Edge window**. Use it when the restaurant has no originals to send and the research report (`tablefacts research`) found a TripAdvisor link.
+
+**Rights first.** Most TripAdvisor photos were uploaded by guests, who keep the rights to them; TripAdvisor's terms also forbid scraping. Ask the restaurant for its originals first. Use these photos as reference, or only where the restaurant confirms it may use them, and say in the hand-off where each one came from.
+
+## Status
+
+The URL parsing, size upgrade and file naming are unit-tested (`tests/tripadvisor-links.test.ts`).
+
+**Verified once** on Maki Bar Medellín (tripadvisor.co, October 2026): Edge started by the script, no check shown, the slideshow opened and showed "1 de 16", and all 16 photos saved as valid JPEGs (originals, 100 KB to 3.7 MB); a re-run skipped all 16. **Not verified:** other country domains, restaurants with hundreds of photos, a run where the DataDome check does appear, and the English/other-language page (the selector is a `data-section-signature` attribute, not text, so it should hold). TripAdvisor changes its markup: do a `--dry-run --debug` first and fix `openGallery` and `collect` in `photos.mjs` from the saved HTML if it finds nothing or the wrong photos.
+
+**Check the count.** The slideshow says "N de M"; the tool should report M photos. A page-wide scrape was tried first and returned 35 URLs, most from other places ("keep planning", nearby attractions, other hotels), so the tool reads only the restaurant's own carousel and slideshow.
+
+## The browser
+
+TripAdvisor guards its pages with DataDome. Like `tablefacts photos instagram`, the script does not drive a browser of its own: it **attaches to an ordinary Edge window** started with remote debugging (`--cdp http://localhost:9222`, the default) and opens its own tab. If nothing is listening, it starts Edge with the profile `C:\ig-edge` (`--edge-dir` changes it), the same window `photos:instagram` uses. See [the Instagram README](../instagram/README.md) for starting it by hand and its Windows notes.
+
+Rules for agents:
+
+- **Never try to bypass, solve or fake the check** (no stealth plugins, header tricks, solvers). The script only waits for the real page to appear (2 minutes). If a "verify you are human" box shows, **the user ticks it**. Tell them when you are waiting.
+- **Never kill Edge or its processes.** Leave the window open between runs.
+
+## Run
+
+```bash
+# list what it finds, write nothing, keep the page HTML to fix selectors
+tablefacts photos tripadvisor --dry-run --debug --out <folder> <restaurant link>
+
+# for real
+tablefacts photos tripadvisor --out <folder> <restaurant link>
+tablefacts photos tripadvisor --out <folder> --max 30 <link> <another link>
+```
+
+| Flag | Meaning |
+| --- | --- |
+| `--out <folder>` | required; created if missing. Use a scratch folder outside the site's public folder, then copy what you pick |
+| `--cdp <url>` | the Edge debugging address (default `http://localhost:9222`) |
+| `--edge-dir <dir>` | profile folder of the Edge it starts (default `C:\ig-edge`) |
+| `--max <n>` | stop after n photos per restaurant |
+| `--dry-run` | print the photo URLs found, save nothing. Do this first |
+| `--debug` | save the page HTML in `<out>/_debug/<id>.html` |
+
+The link is the restaurant's own page (`…/Restaurant_Review-g…-d…-Reviews-….html`, any country domain); the query string is dropped. Output files are `<d-id>-<photo path>-<name>.jpg`, so a re-run skips what is already there. The summary prints saved, already there and failed; the exit code is non-zero if anything failed.
+
+## From code
+
+```js
+import { downloadTripadvisor } from 'tablefacts'
+
+const { saved, skipped, failed, found } = await downloadTripadvisor({
+  links: ['https://www.tripadvisor.com/Restaurant_Review-g...-d...-Reviews-....html'],
+  out: 'photos/tripadvisor',    // relative paths resolve against `projectDir`
+  max: 30,
+  dryRun: true,                 // `found` ([{ name, url }]) is only present in a dry run
+  projectDir: '/path/to/project',
+  log: (message, level) => console.log(level ?? 'info', message),
+})
+for (const { item, reason } of failed) console.error(item, reason)   // the restaurant link that failed
+```
+
+`out` resolves against `projectDir` (default `TABLEFACTS_PROJECT`, then the current folder). `log(message, level)` gets
+`'info'`, `'warn'` (skipped links) or `'error'`; without it nothing is printed. No valid link or no `out` throws a
+`TablefactsError` with code `EUSAGE` and `err.option` (the CLI exits `2`); a missing Playwright is `EDEPENDENCY`; a
+page that fails is in `failed` (the CLI exits `1`).
+
+## What the script does
+
+1. Opens the restaurant page and waits for the DataDome challenge to go away (an iframe from `captcha-delivery.com`, or a page without an `h1`).
+2. Clicks the first photo of the restaurant's carousel, `[data-section-signature="photo_viewer"]`, which opens the slideshow (`openGallery`).
+3. Presses the right arrow key through the slideshow and, at each step, reads the big photo on screen (`visibleSlides`, then `findPhotos` for `dynamic-media-cdn.tripadvisor.com` / `media-cdn.tripadvisor.com` `/media/photo-<size>/…`). It stops after two steps with nothing new. Without a carousel it reads only that element, never the rest of the page.
+4. Tries each photo's original (`photo-o`), then `photo-w`, `photo-l`, then the size the page showed (`sizeCandidates`), and saves the first that is an image over 5 KB. Reviewer avatars, maps and logos are skipped.
+
+Only what the page loads is reachable: a restaurant with hundreds of photos may give a fraction of them.
+
+## After the download
+
+Look at every image. TripAdvisor mixes dishes with receipts, menus and people. Copy the chosen files into your site's public folder, and record real pixel `width`/`height` and an `alt` text for each.

package/src/tripadvisor/index.mjs

@@ -0,0 +1,178 @@
+// Library entry for downloading the photos of a restaurant's TripAdvisor page, in the user's own Edge window.
+// Silent unless a `log` function is given; importing this file loads nothing heavy (playwright is loaded on use).
+import { writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { DEFAULT_CDP, ensureEdge } from '../lib/edge.mjs'
+import { TablefactsError, optionError } from '../lib/errors.mjs'
+import { assertImageResponse, writeImage } from '../lib/images.mjs'
+import { normalizeLog } from '../lib/log.mjs'
+import { DELAY_MS, newSummary, prepareOut, storeFile } from '../lib/photos.mjs'
+import { loadPlaywright } from '../lib/playwright.mjs'
+import { fileName, findPhotos, normalizeRestaurant, sizeCandidates } from './links.mjs'
+
+const MIN_BYTES = 5000
+
+// TripAdvisor's bot protection (DataDome) puts a challenge page, often in an iframe from
+// captcha-delivery.com, in front of the restaurant. In a real window it passes alone or after a
+// tick by the user. We only wait for the real page (it has an h1) to appear, never try to solve it.
+const CHALLENGE = 'iframe[src*="captcha-delivery.com"], iframe[src*="datadome"]'
+
+async function waitForCheck(page, log) {
+  const passed = () => page.evaluate((sel) => !document.querySelector(sel) && !!document.querySelector('h1'), CHALLENGE)
+  if (await passed()) return
+  log('  waiting for the TripAdvisor check: tick it in the browser window if it asks (2 min)')
+  await page
+    .waitForFunction((sel) => !document.querySelector(sel) && !!document.querySelector('h1'), CHALLENGE, { timeout: 120000 })
+    .catch(() => {
+      throw new TablefactsError('the TripAdvisor check was not passed: tick it in the window, or use a normal Edge window', 'EFAILED')
+    })
+}
+
+// The restaurant's own photos are in the carousel under data-section-signature="photo_viewer";
+// clicking a photo opens a slideshow ("1 de 16 en Todas las fotos"). The rest of the page (nearby
+// places, "keep planning", reviews of other places) also carries TripAdvisor photos that are NOT
+// this restaurant's, so nothing outside the carousel and the slideshow is ever read.
+const VIEWER = '[data-section-signature="photo_viewer"]'
+
+async function openGallery(page) {
+  const first = page.locator(`${VIEWER} button`).first()
+  if (!(await first.count())) return false
+  await first.click({ timeout: 4000 }).catch(() => {})
+  await page.waitForTimeout(2000)
+  return true
+}
+
+// The big photos on screen now: the slideshow's current slide (and the carousel behind it).
+const visibleSlides = (page) =>
+  page.evaluate(() =>
+    [...document.querySelectorAll('img')]
+      .filter((img) => {
+        const r = img.getBoundingClientRect()
+        return r.width > 400 && r.height > 300 && r.right > 0 && r.left < innerWidth && r.bottom > 0 && r.top < innerHeight
+      })
+      .map((img) => img.src)
+      .join('\n'),
+  )
+
+// Steps through the slideshow with the arrow key, reading each slide, until two steps in a row show
+// nothing new (the end or a wrap-around) or `max` photos are known. Without a slideshow, reads only
+// the carousel on the page.
+async function collect(page, max, opened) {
+  const found = new Map()
+  const add = (text) => {
+    for (const photo of findPhotos(text)) if (!found.has(photo.key)) found.set(photo.key, photo)
+  }
+  if (!opened) {
+    add(await page.locator(VIEWER).first().evaluate((el) => el.outerHTML).catch(() => ''))
+    return [...found.values()].slice(0, max)
+  }
+  let idle = 0
+  for (let step = 0; step < 300 && idle < 2 && found.size < max; step++) {
+    const before = found.size
+    add(await visibleSlides(page))
+    idle = found.size === before ? idle + 1 : 0
+    await page.keyboard.press('ArrowRight')
+    await page.waitForTimeout(1000)
+  }
+  return [...found.values()].slice(0, max)
+}
+
+// Tries the biggest size first; not every photo exists in every size.
+async function save(context, photo, file) {
+  let last = 'no size worked'
+  for (const url of sizeCandidates(photo)) {
+    try {
+      const res = await context.request.get(url)
+      const bytes = await res.body()
+      assertImageResponse({ ok: res.ok(), status: res.status(), contentType: res.headers()['content-type'], bytes, minBytes: MIN_BYTES })
+      await writeImage(file, bytes)
+      return
+    } catch (err) {
+      last = err.message
+    }
+  }
+  throw new TablefactsError(last, 'EFAILED')
+}
+
+/**
+ * Downloads the photos of TripAdvisor restaurant pages through the user's own Edge.
+ * Resolves to a summary whose `failed` lists `{ item, reason }` and whose `found` is present only
+ * in a dry run. Throws a TablefactsError on invalid arguments (code 'EUSAGE', with `option`), a
+ * missing playwright ('EDEPENDENCY') or a browser that cannot be reached.
+ * `out` resolves against `projectDir` (default: TABLEFACTS_PROJECT or the current folder).
+ * `log(message, level)` gets level 'info', 'warn' or 'error'.
+ * @param {import('../lib/types.mjs').TripadvisorOptions} options
+ * @returns {Promise<import('../lib/types.mjs').PhotoSummary>}
+ */
+export async function downloadTripadvisor({
+  links = [],
+  out,
+  cdp = DEFAULT_CDP,
+  edgeDir,
+  max = Infinity,
+  projectDir,
+  dryRun = false,
+  debug = false,
+  log: logOption,
+} = {}) {
+  const log = normalizeLog(logOption)
+  if (!out) throw optionError('out', '`out` is required')
+  const restaurants = []
+  for (const raw of links) {
+    const r = normalizeRestaurant(raw)
+    if (r) restaurants.push(r)
+    else log(`Skipping, not a TripAdvisor restaurant link: ${raw}`, 'warn')
+  }
+  if (!restaurants.length) throw optionError('links', 'no valid TripAdvisor restaurant links in `links`')
+
+  const { outDir, debugDir } = await prepareOut({ out, dryRun, debug, projectDir })
+  const summary = newSummary({ dryRun })
+
+  const { chromium } = await loadPlaywright()
+  let close
+  try {
+    await ensureEdge(cdp, edgeDir)
+    const browser = await chromium.connectOverCDP(cdp)
+    const context = browser.contexts()[0]
+    let page
+    close = async () => {
+      try {
+        await page?.close()
+      } finally {
+        await browser.close()
+      }
+    }
+    page = await context.newPage()
+
+    for (const [i, restaurant] of restaurants.entries()) {
+      log(`[${i + 1}/${restaurants.length}] ${restaurant.url}`)
+      try {
+        await page.goto(restaurant.url, { waitUntil: 'domcontentloaded' })
+        await waitForCheck(page, log)
+        await page.getByRole('button', { name: /accept|aceptar|i agree/i }).first().click({ timeout: 2000 }).catch(() => {})
+        const opened = await openGallery(page)
+        log(opened ? '  photo slideshow opened' : '  no photo carousel found; reading nothing else on the page', opened ? 'info' : 'warn')
+        const photos = await collect(page, max, opened)
+        if (debugDir) await writeFile(join(debugDir, `${restaurant.id}.html`), await page.content())
+        if (!photos.length) throw new TablefactsError('no photos found (markup changed, or the check page is still showing); run with `debug`', 'EFAILED')
+        log(`  ${photos.length} photos`)
+        for (const photo of photos) {
+          const name = `${restaurant.id}-${fileName(photo)}`
+          try {
+            await storeFile({ outDir, name, url: photo.url, dryRun, summary, log, save: ({ file }) => save(context, photo, file) })
+          } catch (err) {
+            summary.failed.push({ item: name, reason: err.message })
+            log(`  ${name} failed: ${err.message}`, 'error')
+          }
+        }
+      } catch (err) {
+        summary.failed.push({ item: restaurant.url, reason: err.message })
+        log(`  failed: ${err.message}`, 'error')
+      }
+      if (i < restaurants.length - 1) await page.waitForTimeout(DELAY_MS)
+    }
+  } finally {
+    await close?.().catch(() => {})
+  }
+  return summary
+}