untappd-mcp 2.3.2 → 2.4.0

package/dist/menu/pick.js

@@ -0,0 +1,514 @@
+// The untappd_menu_pick / untappd_venue_pick pipeline: freshen the user's
+// distinct-beers cache, resolve each menu line to a bid, check every bid
+// against the cache, and rank what the user hasn't had.
+//
+// Everything runs under ONE per-call API budget (Untappd allows ~100
+// calls/hour per token): the sync gets what resolution doesn't need, and
+// anything the budget can't cover comes back flagged for another run rather
+// than looping.
+import { RateLimitError, messageOf } from '@chrischall/mcp-utils';
+import { beerMetaFrom } from '../cache/store.js';
+import { syncUserBeers } from '../cache/sync-beers.js';
+import { breweryNameMatch, candidateFromSearch, isConfident, looksSeasonal, normalizeLine, rankCandidates, searchQueries, } from './match.js';
+import { walkVenueMenu } from './venue-menu.js';
+// Re-fetch cached beer metadata at most this often (matches untappd_top_not_had).
+const BEER_META_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+// A brewery's "possible" list goes stale as it releases beers; a no-match line
+// may start matching once someone adds the beer. Resolved bids don't change.
+const POSSIBLE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+const UNRESOLVED_TTL_MS = 24 * 60 * 60 * 1000;
+// Bump when matching logic changes, so old resolutions are re-scored.
+const RESOLUTION_KEY_VERSION = 'r1';
+const SEARCH_LIMIT = 15;
+const POSSIBLE_MAX = 8;
+const DEFAULT_CONCURRENCY = 4;
+// 429 handling: retry this many times, waiting at most this long. A longer
+// Retry-After is the hourly limit itself — waiting it out inside a tool call
+// is pointless, so the item is reported for another run instead.
+const MAX_RETRIES = 2;
+const MAX_BACKOFF_MS = 8000;
+/** Per-call API budget. Every request the pipeline sends takes one unit. */
+export class ApiBudget {
+    limit;
+    used = 0;
+    constructor(limit) {
+        this.limit = limit;
+    }
+    get remaining() {
+        return Math.max(0, this.limit - this.used);
+    }
+    take() {
+        if (this.used >= this.limit)
+            return false;
+        this.used++;
+        return true;
+    }
+}
+class BudgetExhausted extends Error {
+    constructor() {
+        super('API budget exhausted');
+    }
+}
+const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Call `fn` under the budget, retrying a 429 with bounded backoff. */
+async function guarded(budget, sleep, fn) {
+    for (let attempt = 0;; attempt++) {
+        if (!budget.take())
+            throw new BudgetExhausted();
+        try {
+            return await fn();
+        }
+        catch (e) {
+            if (!(e instanceof RateLimitError) || attempt >= MAX_RETRIES)
+                throw e;
+            const wait = e.retryAfterSeconds !== undefined ? e.retryAfterSeconds * 1000 : 1000 * 2 ** attempt;
+            if (wait > MAX_BACKOFF_MS)
+                throw e;
+            await sleep(wait);
+        }
+    }
+}
+/** Run `fn` over `items` with at most `n` in flight; results keep input order. */
+async function mapPool(items, n, fn) {
+    const out = new Array(items.length);
+    let next = 0;
+    const worker = async () => {
+        while (next < items.length) {
+            const i = next++;
+            out[i] = await fn(items[i]);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(n, items.length) }, worker));
+    return out;
+}
+/**
+ * Bring the user's distinct-beers cache up to date within `maxCalls`: an
+ * incremental top-of-list refresh when the cache is complete (it stops at the
+ * first unchanged cached beer), otherwise a backfill that resumes from the
+ * persisted offset and pages until done or out of budget. `coverageComplete`
+ * is the state AFTER the sync.
+ */
+export async function ensureFresh(client, cache, username, maxCalls) {
+    const prior = await cache.getState(username);
+    const mode = prior?.beers_complete ? 'incremental' : 'backfill';
+    let calls = 0;
+    const counting = { get: (p, q) => (calls++, client.get(p, q)) };
+    const extra = {};
+    if (maxCalls < 1) {
+        extra.skipped = 'no API budget left for a sync this run';
+    }
+    else {
+        try {
+            const s = await syncUserBeers(counting, cache, username, maxCalls);
+            if (s.incremental)
+                extra.stopped_at_bid = s.stopped_at_bid;
+        }
+        catch (e) {
+            if (e instanceof RateLimitError)
+                extra.rate_limited = true;
+            else
+                extra.error = messageOf(e);
+        }
+    }
+    const state = await cache.getState(username);
+    return {
+        report: { mode, api_calls: calls, ...extra },
+        coverageComplete: (state?.beers_complete ?? false) || (state?.backfill_complete ?? false),
+    };
+}
+function resolutionKey(line, venueCity) {
+    const city = venueCity ? venueCity.trim().toLowerCase() : '';
+    const text = line.kind === 'brewery_generic' ? `brewery:${line.breweryHint}` : line.tokens.join(' ');
+    return `${RESOLUTION_KEY_VERSION}|${text}|${city}`;
+}
+function fromCache(row, item, nowMs) {
+    const age = nowMs - Date.parse(row.resolved_at);
+    try {
+        const data = row.data ? JSON.parse(row.data) : null;
+        if (row.status === 'resolved' && row.bid !== null && data) {
+            return { kind: 'resolved', beer: { ...data, item }, cached: true };
+        }
+        if (row.status === 'possible' && data && age < POSSIBLE_TTL_MS) {
+            return { kind: 'possible', possible: { ...data, item }, cached: true };
+        }
+        if (row.status === 'unresolved' && data && age < UNRESOLVED_TTL_MS) {
+            return { kind: 'unresolved', unresolved: { item, reason: data.reason }, cacheable: false, cached: true };
+        }
+    }
+    catch {
+        /* corrupt row — re-resolve */
+    }
+    return null;
+}
+function toResolution(key, item, o, nowIso) {
+    if (o.cached)
+        return null;
+    if (o.kind === 'resolved') {
+        const { item: _i, ...beer } = o.beer;
+        return { key, item, status: 'resolved', bid: o.beer.bid, data: JSON.stringify(beer), resolved_at: nowIso };
+    }
+    if (o.kind === 'possible') {
+        const { item: _i, ...p } = o.possible;
+        return { key, item, status: 'possible', bid: null, data: JSON.stringify(p), resolved_at: nowIso };
+    }
+    if (!o.cacheable)
+        return null;
+    return { key, item, status: 'unresolved', bid: null, data: JSON.stringify({ reason: o.unresolved.reason }), resolved_at: nowIso };
+}
+/** Turn an API failure during resolution into an unresolved line (never cached). */
+function failure(item, e) {
+    const reason = e instanceof BudgetExhausted
+        ? 'api budget exhausted — run again to resolve'
+        : e instanceof RateLimitError
+            ? 'rate limited by Untappd — run again later'
+            : `lookup failed: ${messageOf(e)}`;
+    return { kind: 'unresolved', unresolved: { item, reason }, cacheable: false, cached: false };
+}
+async function resolveBeerLine(line, ctx) {
+    const cands = [];
+    let ranked = rankCandidates(line.tokens, cands, ctx.venueCity);
+    // Most specific query first; the style-less fallback only when the first
+    // found nothing confident (Untappd ANDs every term, so "… nashville blonde"
+    // can return zero hits while "… nashville" finds the beer).
+    for (const q of searchQueries(line)) {
+        const data = await guarded(ctx.budget, ctx.sleep, () => ctx.client.get('/search/beer', { q, limit: SEARCH_LIMIT }));
+        for (const it of data?.beers?.items ?? []) {
+            const c = candidateFromSearch(it);
+            if (c)
+                cands.push(c);
+        }
+        ranked = rankCandidates(line.tokens, cands, ctx.venueCity);
+        if (isConfident(ranked[0]))
+            break;
+    }
+    const top = ranked[0];
+    if (isConfident(top)) {
+        return {
+            kind: 'resolved',
+            beer: { item: line.raw, bid: top.bid, name: top.name, brewery: top.brewery, brewery_id: top.brewery_id, style: top.style, abv: top.abv },
+            cached: false,
+        };
+    }
+    if (ranked.length) {
+        return {
+            kind: 'possible',
+            possible: {
+                item: line.raw,
+                reason: 'no confident match — pick one',
+                candidates: ranked.slice(0, 3).map((c) => ({
+                    bid: c.bid, name: `${c.brewery} ${c.name}`.trim(), style: c.style, abv: c.abv, global_rating: c.rating,
+                })),
+                needs_confirmation: true,
+            },
+            cached: false,
+        };
+    }
+    return { kind: 'unresolved', unresolved: { item: line.raw, reason: 'no Untappd match' }, cacheable: true, cached: false };
+}
+/**
+ * "<Brewery> SEASONAL": find the brewery, then offer its in-production beers
+ * that look seasonal/limited (falling back to its newest releases) as
+ * `possible` candidates — the menu doesn't say which one is pouring.
+ * Brewery lists carry global ratings, so they also seed beer metadata.
+ */
+async function resolveBreweryLine(line, ctx) {
+    const hint = line.breweryHint ?? '';
+    const found = await guarded(ctx.budget, ctx.sleep, () => ctx.client.get('/search/brewery', { q: hint, limit: 10 }));
+    const breweries = (found?.brewery?.items ?? [])
+        .map((i) => i.brewery ?? {})
+        .map((b) => {
+        const city = b.location?.brewery_city;
+        const sameCity = ctx.venueCity && typeof city === 'string' && city.toLowerCase() === ctx.venueCity.toLowerCase();
+        return { b, score: breweryNameMatch(hint, String(b.brewery_name ?? '')) + (sameCity ? 0.25 : 0) };
+    })
+        .filter((x) => typeof x.b.brewery_id === 'number' && x.score >= 0.5)
+        .sort((a, b) => b.score - a.score);
+    const brewery = breweries[0]?.b;
+    if (!brewery) {
+        return { kind: 'unresolved', unresolved: { item: line.raw, reason: `brewery "${hint}" not found` }, cacheable: true, cached: false };
+    }
+    const list = await guarded(ctx.budget, ctx.sleep, () => ctx.client.get(`/brewery/beer_list/${brewery.brewery_id}`, { limit: 50 }));
+    const items = (list?.beers?.items ?? []).filter((i) => typeof i.beer?.bid === 'number');
+    const meta = items.map((i) => beerMetaFrom(i.beer, i.brewery ?? brewery, ctx.nowIso)).filter((m) => m !== null);
+    if (meta.length)
+        await ctx.cache.upsertBeerMeta(meta);
+    const live = items.filter((i) => i.beer?.is_in_production !== 0);
+    const seasonal = live.filter((i) => looksSeasonal(String(i.beer?.beer_name ?? ''), i.beer?.beer_style ?? null));
+    // No seasonal-looking names: the newest releases are the next-best guess at
+    // "what's rotating"; the list itself is popularity-ordered.
+    const newest = live
+        .slice()
+        .sort((a, b) => Date.parse(String(b.beer?.created_at ?? '')) - Date.parse(String(a.beer?.created_at ?? '')) || 0);
+    const chosen = (seasonal.length ? seasonal : newest).slice(0, POSSIBLE_MAX);
+    if (!chosen.length) {
+        return { kind: 'unresolved', unresolved: { item: line.raw, reason: 'brewery has no beers listed' }, cacheable: true, cached: false };
+    }
+    return {
+        kind: 'possible',
+        possible: {
+            item: line.raw,
+            brewery: String(brewery.brewery_name ?? hint),
+            reason: seasonal.length ? 'seasonal-looking beers from this brewery' : "brewery's newest releases",
+            candidates: chosen.map((i) => ({
+                bid: i.beer.bid,
+                name: String(i.beer.beer_name ?? ''),
+                style: i.beer.beer_style ?? null,
+                abv: typeof i.beer.beer_abv === 'number' ? i.beer.beer_abv : null,
+                global_rating: typeof i.beer.rating_score === 'number' && i.beer.rating_score > 0 ? i.beer.rating_score : null,
+            })),
+            needs_confirmation: true,
+        },
+        cached: false,
+    };
+}
+const ratingOf = (m) => m?.weighted_rating_score ?? m?.rating_score ?? null;
+/**
+ * Split resolved beers into had / not-had from the cache (no API), fill in
+ * global ratings for the not-had ones (beer_meta, else beer/info within the
+ * budget), and rank. `possible` candidates get a `had` flag but are never
+ * picks — the caller has to confirm which one is actually pouring.
+ */
+async function checkAndRank(ctx, username, resolved, possible, styleFilter, topN) {
+    const { cache } = ctx;
+    const seen = new Set();
+    const had = [];
+    const notHadBeers = [];
+    const candidateBids = possible.flatMap((p) => p.candidates.map((c) => c.bid));
+    const verdicts = await cache.hasHadMany(username, [...resolved.map((r) => r.bid), ...candidateBids]);
+    for (const r of resolved) {
+        if (seen.has(r.bid))
+            continue;
+        seen.add(r.bid);
+        const h = verdicts.get(r.bid);
+        if (h.had) {
+            had.push({ item: r.item, bid: r.bid, name: r.name, brewery: r.brewery, count: h.count, last_date: h.last_date, user_rating: h.best_rating });
+        }
+        else
+            notHadBeers.push(r);
+    }
+    for (const p of possible) {
+        for (const c of p.candidates)
+            c.had = verdicts.get(c.bid).had;
+    }
+    // Ratings: a fresh cached rating is used as-is; otherwise beer/info, within
+    // the budget. A null cached rating counts as missing — search results carry
+    // no rating, so a null there means "never fetched", not "unrated".
+    const nowMs = Date.parse(ctx.nowIso);
+    const metaByBid = new Map((await cache.getBeerMeta(notHadBeers.map((b) => b.bid))).map((m) => [m.bid, m]));
+    const fresh = (m) => !!m && ratingOf(m) !== null && !!m.fetched_at && nowMs - Date.parse(m.fetched_at) < BEER_META_TTL_MS;
+    let need = notHadBeers.filter((b) => !fresh(metaByBid.get(b.bid)) && b.rating == null);
+    let deferred = 0;
+    const newMeta = [];
+    // Two or more beers from one brewery: its beer list (up to 50, most popular
+    // first, ratings included) is one call instead of one beer/info each. Beers
+    // the list doesn't reach fall through to beer/info below.
+    const byBrewery = new Map();
+    for (const b of need) {
+        if (typeof b.brewery_id === 'number')
+            byBrewery.set(b.brewery_id, [...(byBrewery.get(b.brewery_id) ?? []), b]);
+    }
+    const groups = [...byBrewery.entries()].filter(([, bs]) => bs.length >= 2);
+    const lists = await mapPool(groups, ctx.concurrency, async ([breweryId]) => {
+        try {
+            const data = await guarded(ctx.budget, ctx.sleep, () => ctx.client.get(`/brewery/beer_list/${breweryId}`, { limit: 50 }));
+            return (data?.beers?.items ?? [])
+                .map((i) => beerMetaFrom(i.beer, i.brewery, ctx.nowIso))
+                .filter((m) => m !== null && ratingOf(m) !== null);
+        }
+        catch {
+            return []; // the per-beer fallback below still gets a try
+        }
+    });
+    for (const m of lists.flat()) {
+        newMeta.push(m);
+        metaByBid.set(m.bid, m);
+    }
+    need = need.filter((b) => !fresh(metaByBid.get(b.bid)));
+    const fetched = await mapPool(need, ctx.concurrency, async (b) => {
+        try {
+            const data = await guarded(ctx.budget, ctx.sleep, () => ctx.client.get(`/beer/info/${b.bid}`, { compact: 'true' }));
+            return beerMetaFrom(data?.beer, undefined, ctx.nowIso);
+        }
+        catch {
+            deferred++;
+            return null;
+        }
+    });
+    for (const m of fetched) {
+        if (!m)
+            continue;
+        newMeta.push(m);
+        metaByBid.set(m.bid, m);
+    }
+    // Seeds the whole brewery list too, so later menus from it cost nothing.
+    if (newMeta.length)
+        await cache.upsertBeerMeta(newMeta);
+    const not_had = notHadBeers.map((b) => {
+        const m = metaByBid.get(b.bid);
+        const rating = b.rating ?? ratingOf(m);
+        return {
+            item: b.item,
+            bid: b.bid,
+            name: b.name,
+            brewery: b.brewery,
+            style: b.style ?? m?.style ?? null,
+            abv: b.abv ?? m?.abv ?? null,
+            global_rating: rating !== null ? Math.round(rating * 100) / 100 : null,
+            ...(m && rating !== null && b.rating == null && !fresh(m) ? { stale_rating: true } : {}),
+        };
+    });
+    not_had.sort((a, b) => (b.global_rating ?? -1) - (a.global_rating ?? -1));
+    const s = styleFilter?.toLowerCase();
+    const eligible = s
+        ? not_had.filter((b) => {
+            const parent = metaByBid.get(b.bid)?.parent_style ?? '';
+            return (b.style ?? '').toLowerCase().includes(s) || parent.toLowerCase().includes(s);
+        })
+        : not_had;
+    const picks = eligible.slice(0, topN).map((b, i) => ({
+        ...b,
+        reason: `not had · ` +
+            (b.global_rating !== null ? `${b.global_rating.toFixed(2)} global rating` : 'no global rating yet') +
+            ` · #${i + 1} of ${eligible.length} not-had${s ? ` "${styleFilter}"` : ''} beer${eligible.length === 1 ? '' : 's'} on this list`,
+    }));
+    return { picks, not_had, had, possible, rating_fetch_deferred: deferred };
+}
+/** untappd_menu_pick: raw menu lines in, ranked not-had picks out. */
+export async function menuPick(client, cache, input, deps = {}) {
+    const budget = new ApiBudget(input.apiBudget);
+    const sleep = deps.sleep ?? defaultSleep;
+    const concurrency = deps.concurrency ?? DEFAULT_CONCURRENCY;
+    const nowIso = new Date().toISOString();
+    const nowMs = Date.parse(nowIso);
+    const ctx = { client, cache, budget, sleep, venueCity: input.venueCity, nowIso, concurrency };
+    // Resolution cache first (no API) so the sync budget can leave room for misses.
+    const lines = input.items.map(normalizeLine);
+    const keys = lines.map((l) => resolutionKey(l, input.venueCity));
+    const cachedRows = input.refreshResolutions ? [] : await cache.getResolutions(keys.filter((_, i) => lines[i].kind !== 'generic'));
+    const byKey = new Map(cachedRows.map((r) => [r.key, r]));
+    const outcomes = lines.map((l, i) => {
+        if (l.kind === 'generic') {
+            return { kind: 'unresolved', unresolved: { item: l.raw, reason: 'ask bartender' }, cacheable: false, cached: false };
+        }
+        const row = byKey.get(keys[i]);
+        return row ? (fromCache(row, l.raw, nowMs) ?? undefined) : undefined;
+    });
+    const misses = outcomes.filter((o) => o === undefined).length;
+    // Reserve ~2 calls per unresolved line (search + fallback, or brewery search +
+    // beer list) and ~1 per beer for a rating lookup; the sync gets the rest, but
+    // never less than one page (the incremental refresh's cost).
+    const reserve = misses * 3;
+    const syncCalls = Math.min(budget.remaining, Math.max(1, budget.remaining - reserve));
+    const { report: sync, coverageComplete } = await ensureFresh(client, cache, input.username, syncCalls);
+    budget.used += sync.api_calls;
+    const misIdx = outcomes.map((o, i) => (o === undefined ? i : -1)).filter((i) => i >= 0);
+    const resolvedNow = await mapPool(misIdx, concurrency, async (i) => {
+        const line = lines[i];
+        try {
+            return line.kind === 'brewery_generic' ? await resolveBreweryLine(line, ctx) : await resolveBeerLine(line, ctx);
+        }
+        catch (e) {
+            return failure(line.raw, e);
+        }
+    });
+    misIdx.forEach((i, j) => (outcomes[i] = resolvedNow[j]));
+    const toStore = misIdx
+        .map((i) => toResolution(keys[i], lines[i].raw, outcomes[i], nowIso))
+        .filter((r) => r !== null);
+    if (toStore.length)
+        await cache.upsertResolutions(toStore);
+    const resolved = [];
+    const possible = [];
+    const unresolved = [];
+    for (const o of outcomes) {
+        if (o.kind === 'resolved')
+            resolved.push(o.beer);
+        else if (o.kind === 'possible')
+            possible.push(o.possible);
+        else
+            unresolved.push(o.unresolved);
+    }
+    const ranked = await checkAndRank(ctx, input.username, resolved, possible, input.styleFilter, input.topN);
+    const { rating_fetch_deferred, ...rest } = ranked;
+    const retryable = unresolved.some((u) => /run again/.test(u.reason)) || rating_fetch_deferred > 0;
+    return {
+        ...rest,
+        unresolved,
+        sync,
+        api_calls: budget.used,
+        api_budget: budget.limit,
+        another_run_needed: !coverageComplete || retryable,
+    };
+}
+// Menu pages walk to completion within this many calls (menus are a handful of
+// sections; 50 per page).
+const VENUE_MENU_MAX_PAGES = 10;
+/**
+ * untappd_venue_pick: pull a venue's FULL verified menu (walking sections to
+ * completion, within the budget), then run the same check + rank. Menu items
+ * already carry bids, so there is no search step.
+ */
+export async function venuePick(client, cache, input, deps = {}) {
+    const budget = new ApiBudget(input.apiBudget);
+    const sleep = deps.sleep ?? defaultSleep;
+    const concurrency = deps.concurrency ?? DEFAULT_CONCURRENCY;
+    const nowIso = new Date().toISOString();
+    // Leave at least one call for the sync's incremental refresh.
+    let menuCalls = 0;
+    const counting = {
+        get: (p, q) => (menuCalls++, client.get(p, q)),
+    };
+    // No budget at all (e.g. Untappd reported 0 calls left): don't fetch the
+    // menu — the floor of one page below is for a small budget, not an empty one.
+    const walk = budget.remaining < 1
+        ? { beers: [], totalCount: 0, sawMenu: false, pagesFetched: 0, reachedEnd: false, nextOffset: 0, venueCity: null, venueName: null }
+        : await walkVenueMenu(counting, input.venueId, {
+            maxPages: Math.max(1, Math.min(VENUE_MENU_MAX_PAGES, budget.remaining - 1)),
+        });
+    budget.used += menuCalls;
+    const metaRows = walk.beers
+        .map((b) => beerMetaFrom(b.rawBeer, b.rawBrewery, nowIso))
+        .filter((m) => m !== null && ratingOf(m) !== null);
+    if (metaRows.length)
+        await cache.upsertBeerMeta(metaRows);
+    const resolved = walk.beers.map((b) => ({
+        item: [b.brewery, b.name].filter((x) => typeof x === 'string' && x).join(' ').trim(),
+        bid: b.bid,
+        name: typeof b.name === 'string' ? b.name.trim() : String(b.name ?? ''),
+        brewery: typeof b.brewery === 'string' ? b.brewery.trim() : '',
+        brewery_id: typeof b.rawBrewery?.brewery_id === 'number' ? b.rawBrewery.brewery_id : null,
+        style: typeof b.style === 'string' ? b.style : null,
+        abv: typeof b.abv === 'number' ? b.abv : null,
+    }));
+    const distinctBids = new Set(resolved.map((r) => r.bid)).size;
+    const cachedMeta = await cache.getBeerMeta([...new Set(resolved.map((r) => r.bid))]);
+    const reserve = distinctBids - cachedMeta.filter((m) => ratingOf(m) !== null).length;
+    const syncCalls = Math.min(budget.remaining, Math.max(1, budget.remaining - reserve));
+    const { report: sync, coverageComplete } = await ensureFresh(client, cache, input.username, syncCalls);
+    budget.used += sync.api_calls;
+    const ctx = { client, cache, budget, sleep, venueCity: walk.venueCity ?? undefined, nowIso, concurrency };
+    const ranked = await checkAndRank(ctx, input.username, resolved, [], input.styleFilter, input.topN);
+    const { rating_fetch_deferred, ...rest } = ranked;
+    const unresolved = walk.sawMenu
+        ? []
+        : walk.pagesFetched === 0
+            ? [{ item: `venue ${input.venueId}`, reason: 'api budget exhausted — run again to fetch the menu' }]
+            : [{ item: `venue ${input.venueId}`, reason: 'venue has no verified menu on Untappd — use untappd_menu_pick with the tap list' }];
+    return {
+        ...rest,
+        unresolved,
+        venue: {
+            venue_id: input.venueId,
+            name: walk.venueName,
+            city: walk.venueCity,
+            menu_beers: walk.beers.length,
+            menu_total: walk.totalCount,
+            menu_complete: walk.reachedEnd,
+            menu_pages: walk.pagesFetched,
+        },
+        sync,
+        api_calls: budget.used,
+        api_budget: budget.limit,
+        another_run_needed: !coverageComplete || rating_fetch_deferred > 0 || !walk.reachedEnd,
+    };
+}

package/dist/menu/venue-menu.js

@@ -0,0 +1,108 @@
+/**
+ * Walk a venue's verified menu sections via venue/info, spending at most
+ * `maxPages` API calls.
+ *
+ * venue/info pages its MENUS with limit/offset, but caps each menu's SECTION
+ * list — echoing `section_limit`/`section_offset` back as accepted params
+ * (the response even carries a `section_offset ` key with a stray trailing
+ * space; the real param name is the clean one the web menu UI sends). We
+ * forward them and walk sections, deduping by menu+section+bid so overlapping
+ * or param-ignoring pages can't double-count.
+ *
+ * Termination is driven by SECTION availability, not a running beer count:
+ * a page that returns fewer sections than we asked for is the end of the
+ * list. That's what makes resuming correct — the walk is stateless across
+ * calls, so on a resumed tail (section_offset > 0) `beers.length` covers
+ * only this run and can never equal the whole-menu total, which would
+ * otherwise mislabel a finished tail as truncated.
+ */
+export async function walkVenueMenu(client, venueId, opts) {
+    const pageSize = opts.sectionLimit ?? 50;
+    const menuId = opts.menuId;
+    let offset = opts.sectionOffset ?? 0;
+    const seen = new Set();
+    const beers = [];
+    let totalCount = 0;
+    let sawMenu = false;
+    let pagesFetched = 0;
+    let reachedEnd = false;
+    let venueCity = null;
+    let venueName = null;
+    for (let page = 0; page < opts.maxPages; page++) {
+        const data = await client.get(`/venue/info/${venueId}`, {
+            section_limit: pageSize,
+            section_offset: offset,
+            menu_id: menuId,
+            sort: opts.sort,
+        });
+        pagesFetched++;
+        const venue = data?.venue;
+        if (page === 0 && venue) {
+            const loc = venue.location;
+            venueCity = typeof loc?.venue_city === 'string' ? loc.venue_city : null;
+            venueName = typeof venue.venue_name === 'string' ? venue.venue_name : null;
+        }
+        const vb = venue?.verfied_beers;
+        if (!vb) {
+            reachedEnd = true; // no menu payload — nothing more to page
+            break;
+        }
+        sawMenu = true;
+        let added = 0;
+        let matchedItemCount = 0;
+        let sectionsReturned = 0;
+        for (const wrap of vb.items ?? []) {
+            const menu = wrap?.menu;
+            if (!menu)
+                continue;
+            if (menuId && menu.menu_id !== menuId)
+                continue;
+            if (typeof menu.total_item_count === 'number')
+                matchedItemCount += menu.total_item_count;
+            const sections = menu.sections?.items ?? [];
+            for (const section of sections) {
+                sectionsReturned++;
+                for (const it of section.items ?? []) {
+                    const beer = it?.beer;
+                    if (!beer || typeof beer.bid !== 'number')
+                        continue;
+                    const key = `${String(menu.menu_id)}:${String(section.section_id)}:${beer.bid}`;
+                    if (seen.has(key))
+                        continue;
+                    seen.add(key);
+                    const sectionName = section.section_name;
+                    const brewery = it.brewery;
+                    beers.push({
+                        bid: beer.bid,
+                        name: beer.beer_name,
+                        brewery: brewery?.brewery_name,
+                        style: beer.beer_style,
+                        abv: beer.beer_abv,
+                        price: it.price?.value,
+                        serving_type: it.serving_type,
+                        menu: menu.menu_name,
+                        section: typeof sectionName === 'string' ? sectionName.trim() : sectionName,
+                        rawBeer: beer,
+                        rawBrewery: brewery,
+                    });
+                    added++;
+                }
+            }
+        }
+        // Coverage target: with a menu_id filter, aim for THAT menu's own item
+        // count — verfied_beers.total_count spans every menu, so a single-menu
+        // slice could never reach it (it would burn the whole page budget and
+        // wrongly report a shortfall). Without a filter, the venue-wide total.
+        totalCount = menuId ? matchedItemCount : typeof vb.total_count === 'number' ? vb.total_count : totalCount;
+        offset += pageSize;
+        if (totalCount > 0 && beers.length >= totalCount) {
+            reachedEnd = true; // full coverage from this walk
+            break;
+        }
+        if (sectionsReturned < pageSize || added === 0) {
+            reachedEnd = true; // a short (or all-duplicate) page is the end of the section list
+            break;
+        }
+    }
+    return { beers, totalCount, sawMenu, pagesFetched, reachedEnd, nextOffset: offset, venueCity, venueName };
+}

package/dist/quota.js

@@ -0,0 +1,14 @@
+/**
+ * Cap a per-call API budget to the calls Untappd says are left this hour, so
+ * two tools run back to back don't each plan as if they had the whole quota.
+ * When the quota is unknown (no response has carried X-Ratelimit-Remaining)
+ * the requested budget stands. `floor` keeps tools whose paging logic needs at
+ * least one page from being handed zero.
+ */
+export function clampToQuota(client, requested, floor = 0) {
+    // Test fakes and other stand-ins may not implement the getter at all.
+    const remaining = client.quotaRemaining ?? null;
+    if (remaining === null || remaining >= requested)
+        return { budget: requested, quota_remaining: remaining, clamped: false };
+    return { budget: Math.max(floor, remaining), quota_remaining: remaining, clamped: true };
+}

package/dist/tools/beer.js

@@ -13,9 +13,12 @@ async function seedBeerMeta(cache, beers) {
         return;
     try {
         const now = new Date().toISOString();
+        // Search results carry no rating. Seeding one would overwrite a real cached
+        // rating with null under a fresh timestamp, so the ranking tools would
+        // trust it for 30 days — only rows that actually carry a rating are seeded.
         const rows = beers
             .map((b) => beerMetaFrom(b.beer, b.brewery, now))
-            .filter((m) => m !== null);
+            .filter((m) => m !== null && (m.weighted_rating_score ?? m.rating_score) !== null);
         if (rows.length)
             await cache().upsertBeerMeta(rows);
     }