tablefacts 0.1.0

package/src/menu/raw/vision.mjs

@@ -0,0 +1,252 @@
+// Reads one menu page picture with a vision model and returns its sections and
+// dishes as data. The model transcribes; it does not interpret: prices come back
+// as the text printed on the page ("$95.000") and normalize.mjs turns them into
+// numbers, so a misjudged thousands separator cannot silently turn 95.000
+// into 95.
+//
+// Anthropic, Gemini and Groq can read the pages. A provider is only how to send
+// the picture and how to get the transcription out of the answer; the schema,
+// the instructions, the retries and the checks are shared, so all of them return
+// the same `{ sections, notes }`.
+import { readFileSync } from "node:fs";
+import { resolveEnv } from "../../lib/env.mjs";
+import { optionError, TablefactsError } from "../../lib/errors.mjs";
+
+const TOOL = "record_menu_page";
+const MAX_TOKENS = 16000; // Groq's model stops at 16,384
+
+// Every object is closed and every property required: Groq's strict mode
+// demands both, and Anthropic and Gemini accept them.
+const schema = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    sections: {
+      type: "array",
+      description: "Every menu section visible on the page, top to bottom (left column before right).",
+      items: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          title: {
+            type: ["string", "null"],
+            description: "The section heading as printed (e.g. ENTRADAS, GIN). null when the page starts with dishes that continue the previous page's section, with no heading of their own.",
+          },
+          group: {
+            type: "string",
+            enum: ["food", "drink", "other"],
+            description: "food: dishes, sides, desserts. drink: cocktails, wine, beer, spirits, coffee, soft drinks. other: anything not sold from the menu (thanks, QR code, chef's note).",
+          },
+          items: {
+            type: "array",
+            items: {
+              type: "object",
+              additionalProperties: false,
+              properties: {
+                name: { type: "string" },
+                description: { type: ["string", "null"], description: "Ingredients or details printed under or beside the name, joined into one line; null if none." },
+                prices: {
+                  type: "array",
+                  description: "One entry per price printed for this item, left to right.",
+                  items: {
+                    type: "object",
+                    additionalProperties: false,
+                    properties: {
+                      text: { type: "string", description: "The price exactly as printed, e.g. \"$95.000\" or \"12,5\"." },
+                      label: {
+                        type: ["string", "null"],
+                        description: "What this price is for when the page says so, in the page's language: a size, a serving, or what a column icon stands for (a bottle icon is \"Botella\", a glass icon is \"Copa\" or \"Trago\"). null when there is a single price.",
+                      },
+                    },
+                    required: ["text", "label"],
+                  },
+                },
+              },
+              required: ["name", "description", "prices"],
+            },
+          },
+        },
+        required: ["title", "group", "items"],
+      },
+    },
+    notes: {
+      type: "array",
+      items: { type: "string" },
+      description: "Anything a person should check: text too small or blurred to read with confidence, an item you could not place, a price you are unsure of. Empty when the page is clear.",
+    },
+  },
+  required: ["sections", "notes"],
+};
+
+const intro = "You are transcribing one page of a restaurant menu from a picture, to load it into a database.";
+
+const rules = `Rules:
+- Transcribe, do not improve. Keep the language of the page, its spelling and accents. Never translate, invent, or fill in an item, ingredient or price that is not visible.
+- Dish and drink names printed in capitals only as a style (LOMO AL GRILL) are written with normal capitalization (Lomo al Grill); keep capitals that are part of the name (MOM Gin, VSPR).
+- Join a description that wraps over several lines into one line. Drop the dotted or underscore leaders between a name and its price.
+- A price is only a price: copy the digits and separators as printed, drop nothing, add nothing. Currency symbols may stay.
+- When a section has several price columns, give every item one price per column in the same order, and label each by the column heading or icon.
+- Boxes and panels on one page (a side-dishes panel under the main list) are sections of their own.
+- Decorative borders, logos, page numbers and chef's notes are not items. A page with no dishes or drinks (a thank-you card) returns no sections with items.
+- If something is hard to read, give your best reading and say so in notes.`;
+
+// Anthropic is made to call a tool. Gemini and Groq answer in JSON whose shape
+// their server enforces; the schema goes in the prompt as well, because the
+// descriptions in it only help if the model sees them.
+const asToolCall = `${intro} Call ${TOOL} exactly once.\n\n${rules}`;
+const asJson = `${intro} Answer with one JSON object that follows this JSON Schema, and nothing else.\n\n${rules}\n\nJSON Schema:\n${JSON.stringify(schema)}`;
+
+const unusable = (why) => new TablefactsError(`The model did not return a usable transcription: ${why}.`, "EFAILED");
+
+/** A JSON answer that stops in the middle was cut off by the token limit. */
+function parseJson(text, cutOff) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw unusable(cutOff ? "its answer was cut off (token limit)" : "its answer was not valid JSON");
+  }
+}
+
+// `request` builds the call for one picture (`data` is its base64) and `read`
+// returns the transcription object from the answer, or throws why there is none.
+/** @type {Record<string, import('../../lib/types.mjs').VisionProvider>} */
+export const providers = {
+  anthropic: {
+    label: "Anthropic",
+    keyName: "ANTHROPIC_API_KEY",
+    defaultModel: "claude-sonnet-5-5",
+    request: ({ model, apiKey, data, mediaType }) => ({
+      url: "https://api.anthropic.com/v1/messages",
+      headers: { "x-api-key": apiKey, "anthropic-version": "2023-06-01" },
+      body: {
+        model,
+        max_tokens: MAX_TOKENS,
+        tools: [{ name: TOOL, description: "Record the sections and items transcribed from the menu page.", input_schema: schema }],
+        tool_choice: { type: "tool", name: TOOL },
+        messages: [
+          {
+            role: "user",
+            content: [
+              { type: "image", source: { type: "base64", media_type: mediaType, data } },
+              { type: "text", text: asToolCall },
+            ],
+          },
+        ],
+      },
+    }),
+    read(response) {
+      const call = response.content?.find((block) => block.type === "tool_use" && block.name === TOOL);
+      if (!Array.isArray(call?.input?.sections)) {
+        throw unusable(response.stop_reason === "max_tokens" ? "its answer was cut off (max_tokens)" : `it answered without calling ${TOOL}`);
+      }
+      return call.input;
+    },
+  },
+
+  gemini: {
+    label: "Gemini",
+    keyName: "GEMINI_API_KEY",
+    defaultModel: "gemini-3.8-flash",
+    // generateContent, not the Interactions API the guides now lead with: that
+    // one is in beta and its schema has already changed once, while Google
+    // keeps generateContent as the path for stable use.
+    request: ({ model, apiKey, data, mediaType }) => ({
+      url: `https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(model)}:generateContent`,
+      headers: { "x-goog-api-key": apiKey },
+      body: {
+        contents: [{ role: "user", parts: [{ text: asJson }, { inlineData: { mimeType: mediaType, data } }] }],
+        // Thinking models count their thoughts against the limit: leave room.
+        generationConfig: { responseMimeType: "application/json", responseJsonSchema: schema, maxOutputTokens: 32000 },
+      },
+    }),
+    read(response) {
+      const candidate = response.candidates?.[0];
+      const text = (candidate?.content?.parts ?? []).filter((part) => !part.thought).map((part) => part.text ?? "").join("");
+      if (!text) {
+        const blocked = response.promptFeedback?.blockReason;
+        throw unusable(blocked ? `Gemini blocked the page (${blocked})` : `it answered with no text (${candidate?.finishReason ?? "no candidate"})`);
+      }
+      return parseJson(text, candidate.finishReason === "MAX_TOKENS");
+    },
+  },
+
+  groq: {
+    label: "Groq",
+    keyName: "GROQ_API_KEY",
+    // The only vision model Groq lists (October 2026), and a preview one: when
+    // it is retired, `model` names its successor.
+    defaultModel: "qwen/qwen3.8-27b",
+    request: ({ model, apiKey, data, mediaType }) => ({
+      url: "https://api.groq.com/openai/v1/chat/completions",
+      headers: { authorization: `Bearer ${apiKey}` },
+      body: {
+        model,
+        messages: [{ role: "user", content: [{ type: "text", text: asJson }, { type: "image_url", image_url: { url: `data:${mediaType};base64,${data}` } }] }],
+        response_format: { type: "json_schema", json_schema: { name: TOOL, strict: true, schema } },
+        // Reading a page needs no reasoning, and none may leak into the JSON.
+        reasoning_effort: "none",
+        reasoning_format: "hidden",
+        max_completion_tokens: MAX_TOKENS,
+      },
+    }),
+    read(response) {
+      const choice = response.choices?.[0];
+      const text = choice?.message?.content;
+      if (!text) throw unusable(`it answered with no text (${choice?.finish_reason ?? "no choice"})`);
+      return parseJson(text, choice.finish_reason === "length");
+    },
+  },
+};
+
+export const defaultProvider = "anthropic";
+
+const ATTEMPTS = 4;
+const RETRY_STATUSES = [408, 429, 500, 502, 503, 504, 529];
+const LONGEST_WAIT = 60; // seconds
+
+/** Seconds the service asks us to wait: Retry-After (Groq, Anthropic) or the RetryInfo in a Gemini error. */
+function askedWait(res, detail) {
+  return [Number(res.headers.get("retry-after")), Number(detail.match(/"retryDelay":\s*"([\d.]+)s"/)?.[1])].find((seconds) => seconds > 0);
+}
+
+async function callApi(label, { url, headers, body }) {
+  let failure;
+  const payload = JSON.stringify(body);
+  for (let attempt = 1; attempt <= ATTEMPTS; attempt++) {
+    let wait = attempt * 2000;
+    try {
+      const res = await fetch(url, {
+        method: "POST",
+        headers: { "content-type": "application/json", ...headers },
+        body: payload,
+        signal: AbortSignal.timeout(180_000),
+      });
+      if (res.ok) return await res.json();
+      const detail = await res.text();
+      failure = Object.assign(new TablefactsError(`${label} API ${res.status}: ${detail.slice(0, 300)}`, "EFAILED"), { status: res.status });
+      if (!RETRY_STATUSES.includes(res.status)) break; // a bad key or request will not fix itself
+      const asked = askedWait(res, detail);
+      if (asked > LONGEST_WAIT) break; // a quota that refills in hours is not worth waiting for here
+      if (asked) wait = asked * 1000;
+    } catch (error) {
+      failure = error;
+    }
+    if (attempt < ATTEMPTS) await new Promise((resolve) => setTimeout(resolve, wait));
+  }
+  throw failure;
+}
+
+/** `file` is a downloaded picture; returns `{ sections, notes }` as the schema above describes. */
+export async function readPage({ file, mediaType }, { provider = defaultProvider, model, apiKey, env } = {}) {
+  const reader = Object.hasOwn(providers, provider) ? providers[provider] : null;
+  const names = Object.keys(providers).join(", ");
+  if (!reader) throw optionError("provider", `"${provider}" is not a provider the pages can be read with (${names}).`, "ECONFIG");
+  apiKey ??= resolveEnv(env)[reader.keyName];
+  if (!apiKey) {
+    throw optionError("provider", `${reader.keyName} is not set. Add it to .env (see .env.example); the menu pages are read with ${reader.label}. To use another provider, pass \`provider\` (${names}).`, "ECONFIG");
+  }
+  const request = reader.request({ model: model ?? reader.defaultModel, apiKey, data: readFileSync(file).toString("base64"), mediaType });
+  const answer = reader.read(await callApi(reader.label, request));
+  if (!Array.isArray(answer?.sections)) throw unusable('its answer has no "sections" list');
+  return { sections: answer.sections, notes: Array.isArray(answer.notes) ? answer.notes : [] };
+}

package/src/research/README.md

@@ -0,0 +1,69 @@
+# Restaurant research
+
+Give it a name and a place, it reads the public web and writes what the template needs.
+
+```bash
+tablefacts research "Casa Luna" "Medellín, Colombia" --country CO
+tablefacts research "Casa Luna" "Medellín" --website https://casaluna.co --instagram casaluna --photos 6
+```
+
+Output goes to `.tablefacts/research/<slug>/` (git-ignored, it holds third-party data):
+
+| File | What it is |
+| --- | --- |
+| `report.md` | Read first. Facts table in BRIEF.md's order (value, source, confidence, where it goes), disagreements, hours as `hoursRows` for both languages, links (menu, delivery, hub), material for the copy, what to ask the client |
+| `profile.json` | The same with provenance, plus each source's raw result |
+| `setup-answers.txt` | One line per prompt of `npm run setup`; blank keeps the placeholder |
+| `photos/` | Only with `--photos n`. Reference, not assets: ask the client for originals |
+
+From code, `research()` returns the same data (`profile`, `notes`, `photos`, `outDir`, `files`, the paths absolute);
+see the [main README](../../README.md#use-it-as-a-library). `out` (relative paths resolve against `projectDir`),
+`projectDir`, `env` (where `GOOGLE_PLACES_API_KEY` is read from, `process.env` by default), `googleKey` and
+`log(message, level)` are options; it is silent without `log`. A missing `name` throws a `TablefactsError`
+(`EUSAGE`, `err.option === 'name'`; the CLI exits `2`). A source that fails never throws: it is a note in the report.
+
+## Sources
+
+| Source | Gives | Notes |
+| --- | --- | --- |
+| Google Maps (Places API) | address, map point, phone, hours, price, cuisine types, photos, status | Needs `GOOGLE_PLACES_API_KEY` in `.env` (Places API (New) enabled). Phone and hours fields are billed at the Enterprise rate; one search per run |
+| OpenStreetMap (Nominatim) | address, map point, sometimes phone, hours, website, socials | No key. Often stale or sparse |
+| Website | JSON-LD, contact page, WhatsApp, reserve platform, menu links, images, logo, theme colour, page text | Falls back to Playwright on 403 or client-rendered pages (`--render` forces it) |
+| Instagram | handle, followers, bio, bio link | Public share card only. Usually login-walled |
+| TripAdvisor | JSON-LD (address, phone, cuisine, price, rating) | Usually bot-blocked: the link is kept for a manual read |
+| Linktree and similar | WhatsApp, reserve, menu, delivery links | Found from the website, Instagram bio or `--linktree` |
+
+Sources find each other (website → Instagram, TripAdvisor, hub). Order of trust per field is in `lib/merge.mjs`; two sources agreeing is "high", one is "medium", a guess is "low".
+
+## How it runs
+
+- **Concurrent lookups.** Google and OpenStreetMap run together; then the website is read. Instagram, TripAdvisor and
+  the link-in-bio page start as soon as their address is known (given, or found on the website), so a slow source does
+  not hold up the others. Report notes keep a fixed order whatever finishes first. Photo downloads run four at a time.
+- **One shared browser.** Playwright's Chromium is launched at most once per run, only when a page needs rendering
+  (`--render`, a 403, a client-rendered page), is shared by the website, TripAdvisor and link-in-bio readers, and is
+  closed at the end even on failure.
+- **Fetch cap.** Pages are read up to 2 MB each; larger bodies are truncated, so a huge page cannot exhaust memory.
+
+## Limits
+
+- It does not log in anywhere or get past bot protection. A blocked source is reported, not worked around.
+- It finds facts, not copy, logos or licensed photos.
+- A wrong match (a sister branch, a closed place) is the main risk: read the Warnings and "Sources disagree" first.
+
+## For agents
+
+Use it first, whenever you are given only a restaurant's name and place (or little else).
+
+1. **Run it** from the repo root: `tablefacts research "<name>" "<city, country>" --country <ISO>`. Add `--website`, `--instagram`, `--tripadvisor` or `--linktree` for anything the user gave you; a user-supplied value is trusted over a search result. It takes under a minute, needs no prompts and prints the output folder.
+2. **Read `out/<slug>/report.md`**, in this order: Warnings, "What each source did", Facts, "Sources disagree". Confirm the match is the right restaurant (name, address, not closed) before using anything. If it matched the wrong place, rerun with a more specific location or `--website`.
+3. **Treat every value as unconfirmed.** Fill `BRIEF.md` with the value and its source, never as client-confirmed. Anything under "not found" stays a placeholder and goes in your hand-off as an open question. Do not invent it.
+4. **Apply the facts**: review `setup-answers.txt`, run `npm run setup < .tablefacts/research/<slug>/setup-answers.txt`, read `git diff`. Setup does not cover `phone`, `email`, `MENU_LOCALE`, `brand.tagline`, `visit.hoursRows` or `jsonld.ts`: take those from the report by hand. Hours are ready to paste. Add street, phone and hours to `jsonld.ts` only for values the client confirmed.
+5. **Use the leads**: a Cluvi menu link means `tablefacts menu cluvi`, a PDF means `tablefacts menu raw` (`src/menu/README.md`). The theme colour and logo candidates are hints for `tokens.css` and `public/logo.svg`, not decisions.
+6. **Blocked sources** (Instagram, TripAdvisor) are normal. Open the link yourself, or ask the user for the bio and hours. Do not try to get around a login wall.
+
+`profile.json` has the same data as JSON for scripting: `fields.<name>` is `{ value, source, confidence, alternatives? }`, `hours.rows.{es,en}` are `hoursRows`, and `raw` holds each source's untouched result. Field names: `name street locality region country coordinates phone whatsapp email instagram facebook tiktok tripadvisor website reserveUrl priceRange mapsUrl descriptor cuisines menuLocale`.
+
+Do not commit `out/`, and never paste the Google key anywhere but `.env`. Photos it downloads belong to the restaurant or the photographer: use them as reference, not as site assets.
+
+Code map: `research.mjs` runs the sources in order and writes the files; `lib/google.mjs`, `osm.mjs`, `website.mjs`, `social.mjs` read one source each; `merge.mjs` holds the per-field trust order; `hours.mjs` normalises hours; `report.mjs` writes the report and the setup answers. A new source is a reader returning plain data, a line in `research.mjs` and its candidates in `merge.mjs`.

package/src/research/index.mjs

@@ -0,0 +1,147 @@
+// Programmatic entry for the research pipeline: gathers what the public web says
+// about a restaurant and writes profile.json, report.md and setup-answers.txt.
+// Silent by default and never exits the process; the CLI lives in research.mjs.
+import { mkdir, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { resolveEnv } from "../lib/env.mjs";
+import { optionError } from "../lib/errors.mjs";
+import { normalizeLog } from "../lib/log.mjs";
+import { resolveIn, workDirIn } from "../lib/project.mjs";
+import { downloadPhotos, searchGoogle } from "./lib/google.mjs";
+import { buildProfile } from "./lib/merge.mjs";
+import { searchOsm } from "./lib/osm.mjs";
+import { renderReport, setupAnswers } from "./lib/report.mjs";
+import { readHub, readInstagram, readTripadvisor } from "./lib/social.mjs";
+import { mapPool, slugify } from "./lib/util.mjs";
+import { createBrowser, scrapeSite } from "./lib/website.mjs";
+
+/**
+ * Researches a restaurant from public sources and writes profile.json, report.md and
+ * setup-answers.txt. Silent unless `log` is given; a source that fails becomes a note in the
+ * report, not an error. Throws a TablefactsError with code 'EUSAGE' (and `option` 'name') when
+ * `name` is missing.
+ * @param {import('../lib/types.mjs').ResearchOptions} options
+ * @returns {Promise<import('../lib/types.mjs').ResearchResult>}
+ */
+export async function research(options = {}) {
+  const { name, location = "", country, website, instagram: instagramOpt, tripadvisor: tripadvisorOpt, linktree, photos: photosOpt = 0, render = false, google: useGoogle = true } = options;
+  if (typeof name !== "string" || !name.trim()) throw optionError("name", "research: `name` is required");
+  const log = normalizeLog(options.log);
+  const env = resolveEnv(options.env);
+
+  const slug = slugify(name);
+  const outDir = options.out ? resolveIn(options.projectDir, options.out) : workDirIn(options.projectDir, "research", slug);
+  const query = { name, location, slug, country, website, instagram: instagramOpt, tripadvisor: tripadvisorOpt, linktree };
+  const notes = [];
+
+  /** Runs one source; a failure is a note in the report, never the end of the run. */
+  async function source(label, fn, sink = notes) {
+    try {
+      return (await fn()) ?? null;
+    } catch (e) {
+      sink.push(`${label}: failed (${e.message})`);
+      log(`  ${label}: failed (${e.message})`, "warn");
+      return null;
+    }
+  }
+
+  const key = useGoogle === false ? "" : (options.googleKey ?? env.GOOGLE_PLACES_API_KEY);
+  log(`Researching "${name}"${location ? ` in ${location}` : ""}`, "info");
+
+  // One Chromium for the whole run, launched only if a page needs rendering.
+  const browser = createBrowser();
+  let site, instagram, hub, tripadvisor, taUrl, handle, google, osm;
+  try {
+    // Google and OpenStreetMap only need the name and place, so they run together; their notes are added in this order afterwards.
+    const googleNotes = [];
+    const osmNotes = [];
+    if (!key) notes.push("Google Places: skipped (no GOOGLE_PLACES_API_KEY in .env, and no `googleKey`). Address, hours and phone come from OpenStreetMap and the website instead.");
+    const [googleResult, osmResult] = await Promise.all([
+      key ? source("Google Places", () => searchGoogle({ name, location, country, key }), googleNotes) : null,
+      source("OpenStreetMap", () => searchOsm({ name, location, country }), osmNotes),
+    ]);
+    if (googleResult) googleNotes.push(googleResult.place ? `Google Places: matched "${googleResult.place.name}", ${googleResult.place.formattedAddress}` : `Google Places: no result named like "${name}". Closest: ${googleResult.candidates.map((c) => `${c.name} (${c.address})`).join("; ") || "none"}`);
+    if (osmResult) osmNotes.push(osmResult.place ? `OpenStreetMap: matched "${osmResult.place.name}"` : `OpenStreetMap: no match. Closest: ${osmResult.candidates.map((c) => c.name || c.address).join("; ") || "none"}`);
+    notes.push(...googleNotes, ...osmNotes);
+    google = googleResult?.place ?? null;
+    osm = osmResult?.place ?? null;
+
+    const websiteUrl = website ?? google?.website ?? osm?.website;
+    site = websiteUrl ? await source("Website", () => scrapeSite(websiteUrl, { renderJs: render, browser })) : null;
+    if (site) notes.push(`Website: read ${site.pages.length} page(s) of ${site.url}${site.pages.some((p) => p.rendered) ? " (rendered with Playwright)" : ""}`);
+    else if (!websiteUrl) notes.push("Website: none found. Pass the website (--website / `website`) if the restaurant has one.");
+
+    // Follow the leads the first sources gave. What is already known (handle, TripAdvisor link, hub link)
+    // starts right away; the rest waits only for the source that can supply it.
+    handle = (instagramOpt ?? site?.links.instagram[0] ?? osm?.instagram ?? "").replace(/^https?:\/\/(www\.)?instagram\.com\//i, "").replace(/^@/, "").split(/[/?#]/)[0];
+    taUrl = tripadvisorOpt ?? site?.links.tripadvisor[0] ?? (site?.jsonld?.sameAs ?? []).find((u) => /tripadvisor\./.test(u));
+    const directHubUrl = linktree ?? site?.links.hubs[0];
+    const readHubAt = (url) => source("Link-in-bio", () => readHub(url, { browser }));
+
+    const instagramP = handle ? source("Instagram", () => readInstagram(handle)) : null;
+    const tripadvisorP = taUrl ? source("TripAdvisor", () => readTripadvisor(taUrl, { browser })) : null;
+    // The hub URL comes from the options or the website, else from the Instagram bio.
+    const hubTask = (async () => {
+      let url = directHubUrl;
+      if (!url) {
+        const ig = await instagramP;
+        url = ig?.links?.find((l) => /linktr|beacons|bio\.link|lnk\.bio|taplink/.test(l));
+      }
+      return url ? { url, result: await readHubAt(url) } : { url: null, result: null };
+    })();
+
+    instagram = instagramP ? await instagramP : null;
+    const hubRead = await hubTask;
+    hub = hubRead.result;
+    const hubUrl = hubRead.url;
+    if (!taUrl) {
+      // Links found on the hub can add the pages the website did not link to.
+      taUrl = hub?.links?.tripadvisor?.[0];
+      if (taUrl) tripadvisor = await source("TripAdvisor", () => readTripadvisor(taUrl, { browser }));
+    } else {
+      tripadvisor = await tripadvisorP;
+    }
+
+    // Notes keep the order of the sequential flow: Instagram, link-in-bio, TripAdvisor.
+    if (instagram) notes.push(instagram.blocked ? `Instagram @${handle}: not readable (${instagram.blocked}). Add the bio by hand, or use \`tablefacts photos instagram\` for posts.` : `Instagram @${handle}: profile card read`);
+    else if (!handle) notes.push("Instagram: no handle found. Pass the handle (--instagram / `instagram`).");
+    if (hub) notes.push(hub.blocked ? `Link-in-bio ${hubUrl}: not readable (${hub.blocked})` : `Link-in-bio: read ${hub.url}`);
+    if (tripadvisor) notes.push(tripadvisor.blocked ? `TripAdvisor ${taUrl}: blocked (${tripadvisor.blocked}). The link is kept; read it by hand.` : "TripAdvisor: page read");
+    else notes.push("TripAdvisor: no link found. Pass the page (--tripadvisor / `tripadvisor`).");
+  } finally {
+    await browser.close();
+  }
+
+  const profile = buildProfile({ query, google, osm, site, hub: hub?.blocked ? null : hub, instagram, tripadvisor: tripadvisor?.blocked ? null : tripadvisor });
+  if (tripadvisor?.blocked && taUrl && !profile.fields.tripadvisor) profile.fields.tripadvisor = { value: taUrl, source: "website", confidence: "medium" };
+
+  // Optional photo downloads: reference material, never wired into the site.
+  const photos = [];
+  const wanted = Number(photosOpt ?? 0);
+  if (wanted > 0) {
+    await mkdir(join(outDir, "photos"), { recursive: true });
+    const save = (file, buf) => writeFile(join(outDir, "photos", file), buf);
+    if (google && key) photos.push(...(await source("Google photos", () => downloadPhotos(google, key, wanted, save)) ?? []));
+    const images = (site?.images ?? []).filter((x) => /\.(jpe?g|png|webp)(\?|$)/i.test(x.url)).slice(0, wanted);
+    const saved = await mapPool(images, 4, async (img, i) => {
+      try {
+        const res = await fetch(img.url, { signal: AbortSignal.timeout(20000) });
+        if (!res.ok) return null;
+        const buf = Buffer.from(await res.arrayBuffer());
+        if (buf.length < 15000) return null;
+        const file = `site-${String(i + 1).padStart(2, "0")}${img.url.match(/\.(jpe?g|png|webp)/i)?.[0].toLowerCase() ?? ".jpg"}`;
+        await save(file, buf);
+        return { file, source: img.url, alt: img.alt };
+      } catch { return null; /* one bad image should not stop the rest */ }
+    });
+    photos.push(...saved.filter(Boolean));
+  }
+
+  const files = { profile: resolve(outDir, "profile.json"), report: resolve(outDir, "report.md"), setupAnswers: resolve(outDir, "setup-answers.txt") };
+  await mkdir(outDir, { recursive: true });
+  await writeFile(files.profile, JSON.stringify({ ...profile, raw: { google, osm, site, hub, instagram, tripadvisor }, photos }, null, 2));
+  await writeFile(files.report, renderReport(profile, { notes, photos }));
+  await writeFile(files.setupAnswers, setupAnswers(profile));
+
+  return { profile, notes, photos, outDir, files };
+}

package/src/research/lib/google.mjs

@@ -0,0 +1,93 @@
+// Google Places API (New): the best single source for address, map point,
+// phone, hours and photos. Needs GOOGLE_PLACES_API_KEY in .env.
+import { fromGoogle } from "./hours.mjs";
+import { mapPool, sameText } from "./util.mjs";
+
+const FIELDS = [
+  "id", "displayName", "formattedAddress", "addressComponents", "location", "nationalPhoneNumber",
+  "internationalPhoneNumber", "websiteUri", "googleMapsUri", "regularOpeningHours", "priceLevel",
+  "rating", "userRatingCount", "types", "primaryTypeDisplayName", "editorialSummary", "photos",
+  "businessStatus", "reservable",
+].map((f) => `places.${f}`).join(",");
+
+const GENERIC_TYPES = new Set(["restaurant", "fast_food_restaurant", "family_restaurant", "meal_takeaway", "meal_delivery", "food_court", "buffet_restaurant"]);
+const PRICE = { PRICE_LEVEL_INEXPENSIVE: "$", PRICE_LEVEL_MODERATE: "$$", PRICE_LEVEL_EXPENSIVE: "$$$", PRICE_LEVEL_VERY_EXPENSIVE: "$$$$" };
+
+const component = (place, ...types) => {
+  for (const t of types) {
+    const c = place.addressComponents?.find((x) => x.types?.includes(t));
+    if (c) return c;
+  }
+  return null;
+};
+
+/** "italian_restaurant" -> "Italian", "steak_house" -> "Steakhouse". */
+function cuisinesFromTypes(types = []) {
+  const out = [];
+  for (const t of types) {
+    if (GENERIC_TYPES.has(t)) continue;
+    const m = t.match(/^(.+)_restaurant$/);
+    if (m) out.push(m[1].split("_").map((w) => w[0].toUpperCase() + w.slice(1)).join(" "));
+    else if (t === "steak_house") out.push("Steakhouse");
+  }
+  return out;
+}
+
+function normalize(p) {
+  return {
+    source: "google",
+    id: p.id,
+    name: p.displayName?.text ?? "",
+    formattedAddress: p.formattedAddress ?? "",
+    // The first comma-separated part is the street line in every format Google uses.
+    street: (p.formattedAddress ?? "").split(",")[0].trim(),
+    locality: (component(p, "locality", "administrative_area_level_2", "sublocality")?.longText) ?? "",
+    region: component(p, "administrative_area_level_1")?.longText ?? "",
+    country: component(p, "country")?.shortText ?? "",
+    postcode: component(p, "postal_code")?.longText ?? "",
+    coords: p.location ? { lat: p.location.latitude, lng: p.location.longitude } : null,
+    phone: p.internationalPhoneNumber ?? "",
+    nationalPhone: p.nationalPhoneNumber ?? "",
+    website: p.websiteUri ?? "",
+    mapsUrl: p.googleMapsUri ?? "",
+    hours: fromGoogle(p.regularOpeningHours?.periods),
+    priceRange: PRICE[p.priceLevel] ?? "",
+    rating: p.rating ?? null,
+    ratingCount: p.userRatingCount ?? null,
+    cuisines: cuisinesFromTypes(p.types),
+    types: p.types ?? [],
+    descriptor: p.primaryTypeDisplayName?.text ?? "",
+    summary: p.editorialSummary?.text ?? "",
+    status: p.businessStatus ?? "",
+    reservable: p.reservable ?? null,
+    photos: (p.photos ?? []).map((ph) => ({ name: ph.name, width: ph.widthPx, height: ph.heightPx, authors: (ph.authorAttributions ?? []).map((a) => a.displayName) })),
+  };
+}
+
+/** Returns { place, candidates }: `place` is the first result whose name matches, or null. */
+export async function searchGoogle({ name, location, country, key }) {
+  const res = await fetch("https://places.googleapis.com/v1/places:searchText", {
+    method: "POST",
+    headers: { "content-type": "application/json", "x-goog-api-key": key, "x-goog-fieldmask": FIELDS },
+    body: JSON.stringify({ textQuery: `${name} ${location}`.trim(), maxResultCount: 5, ...(country && { regionCode: country }) }),
+    signal: AbortSignal.timeout(15000),
+  });
+  if (!res.ok) throw new Error(`Google Places ${res.status}: ${(await res.text()).slice(0, 300)}`);
+  const places = ((await res.json()).places ?? []).map(normalize);
+  return {
+    place: places.find((p) => sameText(p.name, name)) ?? null,
+    candidates: places.map((p) => ({ name: p.name, address: p.formattedAddress, status: p.status })),
+  };
+}
+
+/** Downloads up to `count` photos into `dir`, returns what was saved. The key stays out of the result. */
+export async function downloadPhotos(place, key, count, save) {
+  const saved = await mapPool(place.photos.slice(0, count), 4, async (ph, i) => {
+    const res = await fetch(`https://places.googleapis.com/v1/${ph.name}/media?maxWidthPx=2400&key=${key}`, { signal: AbortSignal.timeout(30000) });
+    if (!res.ok) return null;
+    const file = `google-${String(i + 1).padStart(2, "0")}.jpg`;
+    await save(file, Buffer.from(await res.arrayBuffer()));
+    return { file, width: ph.width, height: ph.height, authors: ph.authors };
+  });
+  return saved.filter(Boolean);
+}