untappd-mcp 2.3.2 → 2.5.0

package/dist/cache/sync.js

@@ -1,5 +1,6 @@
 import { createHelpfulError, RateLimitError, messageOf } from '@chrischall/mcp-utils';
 import { mapCheckinRow } from './store.js';
+import { checkRateBudget, resumeAdvice, stopFrom429, stopFromVerdict } from '../ratelimit.js';
 const PAGE_LIMIT = 50; // Untappd's max page size for /user/checkins.
 // Backfill counts as complete only when the cache holds ~this fraction of the
 // API's reported total_checkins — allowing drift for deleted check-ins. Below
@@ -41,7 +42,10 @@ async function fetchTotalCheckins(client, encodedUser) {
         const t = info?.user?.stats?.total_checkins;
         return typeof t === 'number' ? t : null;
     }
-    catch {
+    catch (e) {
+        // A 429 here means every later call would 429 too — let the caller stop.
+        if (e instanceof RateLimitError)
+            throw e;
         return null;
     }
 }
@@ -74,7 +78,42 @@ export async function syncCheckins(client, cache, rawUsername, options = {}) {
     const encodedUser = encodeURIComponent(rawUsername);
     const now = () => new Date().toISOString();
     const priorState = await cache.getState(rawUsername);
-    const total = await fetchTotalCheckins(client, encodedUser);
+    // The stop-before-429 guard, consulted before EVERY call. Once it (or a real
+    // 429) stops the run, nothing else is fetched; progress is persisted per page.
+    let rateStop;
+    const gate = async () => {
+        if (rateStop)
+            return false;
+        const v = await checkRateBudget(client, cache);
+        if (!v.ok)
+            rateStop = stopFromVerdict(v);
+        return v.ok;
+    };
+    /** Fetch a page, or return null (and record why) when rate limited. */
+    const guardedFetch = async (maxId) => {
+        if (!(await gate()))
+            return null;
+        try {
+            return await nextFetch(maxId);
+        }
+        catch (e) {
+            if (!(e instanceof RateLimitError))
+                throw e;
+            rateStop = stopFrom429(e);
+            return null;
+        }
+    };
+    let total = priorState?.total_checkins ?? null;
+    if (await gate()) {
+        try {
+            total = await fetchTotalCheckins(client, encodedUser);
+        }
+        catch (e) {
+            if (!(e instanceof RateLimitError))
+                throw e;
+            rateStop = stopFrom429(e);
+        }
+    }
     const cachedAtStart = await cache.cachedCount(rawUsername);
     // Self-heal a cache wrongly flagged complete (the historical bug): if state
     // claims done but coverage is well short of total, treat it like a forced reset.
@@ -176,7 +215,10 @@ export async function syncCheckins(client, cache, rawUsername, options = {}) {
         let caughtUp = false;
         let phase1Pages = 0;
         for (; phase1Pages < phase1Budget;) {
-            const page = await nextFetch(maxId);
+            const fetched = await guardedFetch(maxId);
+            if (fetched === null)
+                break; // rate limited: catch-up resumes next run
+            const page = fetched;
             pages++;
             phase1Pages++;
             if (page.items.length === 0) {
@@ -231,7 +273,10 @@ export async function syncCheckins(client, cache, rawUsername, options = {}) {
         let maxId = oldestMaxId ?? undefined;
         let phase2Pages = 0;
         for (; phase2Pages < phase2Budget;) {
-            const page = await nextFetch(maxId);
+            const fetched = await guardedFetch(maxId);
+            if (fetched === null)
+                break; // rate limited: backfill resumes from oldest_max_id next run
+            const page = fetched;
             pages++;
             phase2Pages++;
             if (page.items.length === 0) {
@@ -287,14 +332,16 @@ export async function syncCheckins(client, cache, rawUsername, options = {}) {
     // Re-running user/checkins only helps while there is more of the OWN history to
     // page. A truncated (non-self) history can't advance that way — the caller
     // should switch to untappd_sync_user_beers for has-had coverage.
-    const anotherRunNeeded = catchupInProgress || (!backfillComplete && !checkinsTruncated);
-    const note = checkinsTruncated
-        ? 'Untappd only returns the most recent check-ins for this account (history_truncated), so the full check-in history cannot be paged. Use untappd_sync_user_beers to cache the complete distinct-beers list for has-had coverage.'
-        : catchupInProgress
-            ? 'More new check-ins remain than fit in this run — run untappd_sync_checkins again to finish catching up.'
-            : backfillComplete
-                ? 'Full check-in history is cached. Re-run occasionally to pick up new check-ins.'
-                : `Backfill incomplete — run untappd_sync_checkins again to fetch the next ${maxPages} pages of older check-ins.`;
+    const anotherRunNeeded = catchupInProgress || (!backfillComplete && !checkinsTruncated) || rateStop !== undefined;
+    const note = rateStop
+        ? `Check-in sync paused (${cached}${total !== null ? `/${total}` : ''} cached). ${resumeAdvice(rateStop, 'untappd_sync_checkins')}`
+        : checkinsTruncated
+            ? 'Untappd only returns the most recent check-ins for this account (history_truncated), so the full check-in history cannot be paged. Use untappd_sync_user_beers to cache the complete distinct-beers list for has-had coverage.'
+            : catchupInProgress
+                ? 'More new check-ins remain than fit in this run — run untappd_sync_checkins again to finish catching up.'
+                : backfillComplete
+                    ? 'Full check-in history is cached. Re-run occasionally to pick up new check-ins.'
+                    : `Backfill incomplete — run untappd_sync_checkins again to fetch the next ${maxPages} pages of older check-ins.`;
     return {
         username: rawUsername,
         rows_added: added,
@@ -308,6 +355,8 @@ export async function syncCheckins(client, cache, rawUsername, options = {}) {
         history_truncated: checkinsTruncated,
         forced: doReset,
         another_run_needed: anotherRunNeeded,
+        stopped_for_rate_limit: rateStop !== undefined,
+        ...(rateStop ? { rate_limit: rateStop } : {}),
         last_synced_at: now(),
         note,
     };

package/dist/cache/venue-drinks.js

@@ -0,0 +1,101 @@
+import { RateLimitError, messageOf } from '@chrischall/mcp-utils';
+import { mapCheckinRow } from './store.js';
+import { checkRateBudget, resumeAdvice, stopFrom429, stopFromVerdict } from '../ratelimit.js';
+export const VENUE_DRINKS_DEFAULT_CALLS = 10;
+export const VENUE_DRINKS_MAX_CALLS_CAP = 50;
+const TOOL = 'untappd_sync_venue_drinks';
+/** A check-in that no longer exists or isn't visible answers 404 (not a transient failure). */
+function isGone(e) {
+    return /\b404\b|not found|does not exist/i.test(messageOf(e));
+}
+/**
+ * Opt-in "what did they drink there": for the user's cached user_venues rows,
+ * fetch the first and most-recent visit check-ins via checkin/view (works for
+ * any public check-in) and store the beer + date in `venue_drinks`. A PARTIAL
+ * picture by design — two check-ins per venue at most. Budgeted by `maxCalls`,
+ * with the stop-before-429 guard before every call; progress is stored per
+ * call, so a re-run continues with what is still pending.
+ */
+export async function syncVenueDrinks(client, cache, username, opts) {
+    const budget = Math.max(1, Math.min(VENUE_DRINKS_MAX_CALLS_CAP, Math.floor(opts.maxCalls)));
+    const filter = { venueIds: opts.venueIds, which: opts.which ?? 'both' };
+    const candidates = await cache.venueDrinkCandidates(username, filter);
+    let calls = 0;
+    let stored = 0;
+    let unavailable = 0;
+    let errors = 0;
+    let firstError;
+    let rateStop;
+    for (const c of candidates) {
+        if (calls >= budget)
+            break;
+        const verdict = await checkRateBudget(client, cache);
+        if (!verdict.ok) {
+            rateStop = stopFromVerdict(verdict);
+            break;
+        }
+        calls++;
+        let data;
+        try {
+            data = await client.get(`/checkin/view/${c.checkin_id}`);
+        }
+        catch (e) {
+            if (e instanceof RateLimitError) {
+                rateStop = stopFrom429(e);
+                break;
+            }
+            if (isGone(e)) {
+                unavailable++;
+                await cache.upsertVenueDrinks(username, [{ venue_id: c.venue_id, checkin_id: c.checkin_id, bid: null, beer_name: null, brewery_id: null, brewery_name: null, created_at: null }], new Date().toISOString());
+            }
+            else {
+                errors++;
+                firstError ??= messageOf(e);
+            }
+            continue;
+        }
+        // Only the beer, brewery and date are kept — never the comment (other people's free text).
+        const r = mapCheckinRow(username, data?.checkin);
+        const row = {
+            venue_id: c.venue_id,
+            checkin_id: c.checkin_id,
+            bid: r?.bid ?? null,
+            beer_name: r?.beer_name ?? null,
+            brewery_id: r?.brewery_id ?? null,
+            brewery_name: r?.brewery_name ?? null,
+            created_at: r?.created_at ?? null,
+        };
+        if (row.bid === null && row.beer_name === null) {
+            // An unexpected shape — don't store a tombstone for it; count and retry later.
+            errors++;
+            firstError ??= `checkin/view ${c.checkin_id} had no beer`;
+            continue;
+        }
+        await cache.upsertVenueDrinks(username, [row], new Date().toISOString());
+        stored++;
+    }
+    const pending = (await cache.venueDrinkCandidates(username, filter)).length;
+    const another = pending > 0;
+    let note;
+    if (rateStop)
+        note = `Paused with ${pending} check-in(s) pending. ${resumeAdvice(rateStop, TOOL)}`;
+    else if (another)
+        note = `${pending} check-in(s) still pending — run ${TOOL} again to continue (max_calls per run).`;
+    else
+        note = 'Every selected venue\'s first/recent visit drink is cached; untappd_cache_has_visited lists them under matches[].drinks.';
+    if (errors > 0)
+        note += ` ${errors} fetch(es) failed and stay pending.`;
+    return {
+        username,
+        api_calls: calls,
+        stored,
+        unavailable,
+        errors,
+        pending,
+        another_run_needed: another,
+        stopped_for_rate_limit: rateStop !== undefined,
+        ...(rateStop ? { rate_limit: rateStop } : {}),
+        ...(firstError ? { first_error: firstError } : {}),
+        note,
+    };
+}

package/dist/client.js

@@ -1,6 +1,7 @@
 import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 import { loadDotenvSafely, readEnvVar, buildQueryString, formatApiError, createHelpfulError, McpToolError, RateLimitError, UnreachableError, } from '@chrischall/mcp-utils';
+import { RateLimitTracker, computeRateLimitStatus, configuredHourlyLimit, observeResponse, } from './ratelimit.js';
 // Load .env for local (Node) dev; silently skip if dotenv is unavailable (e.g.
 // the mcpb bundle). `loadDotenvSafely` swallows a missing dotenv module and
 // never lets .env override a host-provided value. Guard on `import.meta.url`:
@@ -151,6 +152,9 @@ export class UntappdClient {
     userAgent = readEnvVar('UNTAPPD_USER_AGENT') ?? DEFAULTS.userAgent;
     token;
     loginInFlight = null;
+    /** Every response this process received within the rolling hour (see src/ratelimit.ts). */
+    rateLimit = new RateLimitTracker();
+    apiCallListeners = [];
     tokenIsSupplied;
     /**
      * Defer the config error so the server can still start (and respond to the
@@ -206,6 +210,39 @@ export class UntappdClient {
     get loginName() {
         return this._loginName;
     }
+    /**
+     * Estimated calls left this hour, or null before this process has made any
+     * call in the window. Rests on a LOCAL count of calls (the v4 API sends
+     * `X-Ratelimit-Remaining: 0` on every success, so the header is only believed
+     * once it has reported a live non-zero value, or on a 429) — see
+     * src/ratelimit.ts. Consumers must still treat null as "unknown".
+     */
+    get quotaRemaining() {
+        const obs = this.rateLimit.observations();
+        if (obs.length === 0)
+            return null;
+        return computeRateLimitStatus(obs, Date.now(), { configuredLimit: configuredHourlyLimit() }).estimated_remaining;
+    }
+    /**
+     * Subscribe to every API response (status + rate-limit headers). The stdio
+     * server uses it to persist the call log into the shared cache file, so other
+     * processes (and the next one) know what this hour has already spent.
+     */
+    onApiCall(listener) {
+        this.apiCallListeners.push(listener);
+    }
+    noteQuota(res) {
+        const o = observeResponse(res.status, res.headers);
+        this.rateLimit.record(o);
+        for (const l of this.apiCallListeners) {
+            try {
+                l(o);
+            }
+            catch {
+                /* a listener failure must never fail the API call */
+            }
+        }
+    }
     /** App creds for a write; reached only once a token is in hand. */
     requireAppCreds() {
         if (!this.clientId || !this.clientSecret) {
@@ -315,6 +352,7 @@ export class UntappdClient {
             body = f.toString();
         }
         const res = await this.send(method, `${BASE_URL}${path}${qs}`, { headers, body });
+        this.noteQuota(res);
         // A 401 means the token went stale. Re-minting one needs a login, and a
         // deployment that SUPPLIED the token may have no username/password to log
         // in with — that fell through to `missingCredsError()` and told the

package/dist/compact.js

@@ -75,36 +75,6 @@ export function compactUserBeer(item) {
         last_had: i.recent_created_at,
     };
 }
-/**
- * Slim one `/brewery/beer_list/` item.
- *
- * This endpoint needs its OWN projector rather than reusing
- * {@link compactBeerResult}, and the reason is easy to miss: the item shape IS
- * `{beer:{…}, brewery:{…}}`-wrapped, so `beerCore` fits perfectly — but the two
- * fields the search projector adds on top of it are named differently here.
- * `/search/beer` says `checkin_count` / `have_had`; `/brewery/beer_list/` says
- * `total_count` / `has_had`. Reusing the search projector would therefore have
- * emitted a page of records carrying two silent `undefined`s — a beer with no
- * check-ins that you have never had — and `projectItems`' drift guard cannot
- * catch that, because the CONTAINER is exactly where it expects it to be.
- * Established against a live capture of brewery 1142, not by inference.
- *
- * Rating rides along because the tool's own description promises "per-beer
- * rating and check-in counts"; a compact rung that dropped them would
- * contradict the thing the caller was told they were getting.
- */
-export function compactBreweryBeer(item) {
-    const i = asDict(item) ?? {};
-    const beer = asDict(i.beer) ?? {};
-    return {
-        ...beerCore(i),
-        rating: beer.rating_score,
-        rating_count: beer.rating_count,
-        checkin_count: i.total_count,
-        have_had: i.has_had,
-        your_count: i.total_user_count,
-    };
-}
 /**
  * Project `<container>.items` in a response with `mapFn`, preserving the rest of
  * the container (pagination etc.). Drift-safe: returns the raw response
@@ -125,20 +95,55 @@ export const compactBeerSearch = (resp) => projectItems(resp, 'beers', compactBe
 export const compactWishlist = (resp) => projectItems(resp, 'beers', compactWishlistBeer);
 export const compactUserBeers = (resp) => projectItems(resp, 'beers', compactUserBeer);
 /**
- * Project a brewery beer list, and drop `sorting_options` with it.
+ * The ONE compact shape of `untappd_brewery_beers`, whether its rows came from
+ * Untappd just now or from the local cache — so a caller never sees different
+ * keys depending on whether the cache happened to open. Both paths first map
+ * the page through `mapBreweryBeerItem` (store.ts), which is where the
+ * endpoint's own naming is read: `/brewery/beer_list/` says `total_count` (not
+ * `checkin_count`) and `has_had` (not `have_had`), established against a live
+ * capture of brewery 1142.
  *
- * `sorting_options` is 16 `{sort_key, sort_name}` pairs of UI chrome repeated on
- * every page. The tool's `sort` parameter is already a closed enum on its input
- * schema, so the list tells a caller nothing they were not handed with the
- * schema — it is pure duplication of a contract they already hold.
+ * It evolves the old live-only projection as a superset: every item keeps
+ * bid/name/style/abv/ibu/brewery/rating/rating_count/checkin_count and gains
+ * in_production (+ favorite when the cache marks one). Two old item fields are
+ * gone on purpose: `have_had` / `your_count` were the item's `has_had` /
+ * `total_user_count`, which describe the AUTHENTICATED account, never the user
+ * being asked about. The old top-level `total_count` and `beers.count` stay;
+ * Untappd's `sorting_options` (UI chrome duplicating the input enum) stays
+ * dropped; `pagination` is ours, so paging reads the same off either path.
  */
-export function compactBreweryBeers(resp) {
-    const projected = projectItems(resp, 'beers', compactBreweryBeer);
-    // projectItems returns the SAME object on drift; don't reshape that.
-    if (projected === resp)
-        return resp;
-    const { sorting_options: _dropped, ...rest } = projected;
-    return rest;
+export function compactBreweryBeerList(r, page, favorites) {
+    const count = r.beers.length;
+    const more = r.total_count !== null ? page.offset + count < r.total_count : count > 0 && count >= page.limit;
+    return {
+        brewery_id: r.brewery_id,
+        brewery_name: r.brewery_name,
+        total_count: r.total_count,
+        source: r.source,
+        fetched_at: r.fetched_at,
+        expires_at: r.expires_at,
+        ...(favorites ? { favorite: favorites.brewery } : {}),
+        pagination: { offset: page.offset, limit: page.limit, next_offset: more ? page.offset + count : null },
+        beers: {
+            count,
+            items: r.beers.map((b) => {
+                const fav = favorites?.beer(b.bid);
+                return {
+                    bid: b.bid,
+                    name: b.beer_name,
+                    style: b.style,
+                    abv: b.abv,
+                    ibu: b.ibu,
+                    brewery: r.brewery_name,
+                    rating: b.rating_score,
+                    rating_count: b.rating_count,
+                    checkin_count: b.checkin_count,
+                    in_production: b.in_production,
+                    ...(fav !== undefined ? { favorite: fav } : {}),
+                };
+            }),
+        },
+    };
 }
 /**
  * The rungs this server honours (`@chrischall/mcp-utils`' `view` vocabulary,

package/dist/index.js

@@ -14,24 +14,44 @@ import { registerWishlistTools } from './tools/wishlist.js';
 import { registerCheckinTools } from './tools/checkin.js';
 import { registerUtilityTools } from './tools/utilities.js';
 import { registerCacheTools } from './tools/cache.js';
+import { registerFavoriteTools } from './tools/favorites.js';
+import { registerTripTools } from './tools/trip.js';
+import { registerMenuTools } from './tools/menu.js';
 import { logRegisteredTools } from './tools/diagnostics.js';
-import { CheckinCache, defaultCachePath } from './cache/db.js';
+import { CheckinCache, defaultCachePath, describeCachePath } from './cache/db.js';
 // Build the env-based client once and inject it into each registrar. The
 // constructor defers its config error, so the server still boots (and answers
 // the host's install-time tools/list probe) when credentials are absent.
 const client = new UntappdClient();
 // The stdio server backs the cache with a local `node:sqlite` file, opened lazily
 // on first cache-tool use so the server still boots when no path is configured.
+// The path is resolved (and logged) once at startup, so it can't drift with the
+// working directory a host happens to launch from.
+const cachePath = defaultCachePath();
+console.error(describeCachePath(cachePath));
 let nodeCache;
-const nodeCacheProvider = () => (nodeCache ??= CheckinCache.open(defaultCachePath()));
+const nodeCacheProvider = () => {
+    if (!nodeCache) {
+        nodeCache = CheckinCache.open(cachePath);
+        // Hand the shared call log what this process already spent before the cache opened.
+        void nodeCache.recordApiCalls?.(client.rateLimit.observations()).catch(() => { });
+    }
+    return nodeCache;
+};
+// Persist every API response's rate-limit observation into the shared cache file
+// (once it is open), so a second process — or the next one — counts this hour's
+// calls too (src/ratelimit.ts). Recording never fails an API call.
+client.onApiCall((o) => {
+    void nodeCache?.recordApiCalls?.([o]).catch(() => { });
+});
 await runMcp({
     name: 'untappd-mcp',
     version: VERSION,
     banner: '[untappd-mcp] This project was developed and is maintained by AI (Claude Opus 4.8). Use at your own discretion.',
     tools: [
         (s) => registerBeerTools(s, client, nodeCacheProvider),
-        (s) => registerBreweryTools(s, client),
-        (s) => registerVenueTools(s, client),
+        (s) => registerBreweryTools(s, client, nodeCacheProvider),
+        (s) => registerVenueTools(s, client, nodeCacheProvider),
         (s) => registerUserTools(s, client),
         (s) => registerFeedTools(s, client),
         (s) => registerResolveTools(s, client),
@@ -43,6 +63,9 @@ await runMcp({
         // The cache is backed by a local `node:sqlite` file here; the provider is
         // injectable, so another deployment can back the same tools differently.
         (s) => registerCacheTools(s, client, nodeCacheProvider),
+        (s) => registerFavoriteTools(s, client, nodeCacheProvider),
+        (s) => registerTripTools(s, client, nodeCacheProvider),
+        (s) => registerMenuTools(s, client, nodeCacheProvider),
         // Keep last: logs the full registered toolset (count + names) at startup.
         (s) => logRegisteredTools(s, 'stdio'),
     ],

package/dist/menu/match.js

@@ -0,0 +1,178 @@
+// Menu-line normalisation and candidate scoring for untappd_menu_pick.
+//
+// A tap list read off a photo is noisy ("HAP & HARRY'S TENNESSEE LAGER  $6"),
+// and Untappd's beer search ANDs every term — one stray word returns nothing
+// (live: "i believe in nashville blonde" → 0 hits, "i believe in nashville" →
+// the right beer). So a line is normalised to search-friendly tokens, searched,
+// and every candidate is scored against those tokens. Pure functions only; the
+// API calls live in pick.ts.
+// Words that make a line generic ("whatever's on this week").
+const GENERIC_WORDS = new Set([
+    'seasonal', 'seasonals', 'rotating', 'rotation', 'rotational', 'rotator', 'guest', 'featured', 'selection',
+]);
+// Words that carry no identity on a generic line ("ROTATING DRAFT BEER").
+const GENERIC_FILLER = new Set([
+    'draft', 'draught', 'beer', 'beers', 'tap', 'taps', 'handle', 'cider', 'ciders', 'seltzer', 'seltzers',
+    'select', 'of', 'the', 'our', 'current', 'ask', 'your', 'server', 'bartender', 'on', 'brew', 'brews', 'release',
+]);
+// Serving words a menu adds that are never part of a beer's name.
+const SERVING_WORDS = new Set(['draft', 'draught', 'pint', 'pints', 'pour', 'can', 'cans', 'bottle', 'bottles', 'glass']);
+/**
+ * Bare style words. Untappd keeps the style out of most beer NAMES ("Fennario",
+ * style "IPA - American"), so a line's style word is dropped from the fallback
+ * search query and, when scoring, is explained by the candidate's style.
+ * Deliberately excludes differentiators like "double"/"imperial" — "Double
+ * Homestyle" is a different beer from "Homestyle".
+ */
+const STYLE_WORDS = new Set([
+    'ipa', 'ipas', 'lager', 'pilsner', 'pils', 'blonde', 'blond', 'ale', 'stout', 'porter', 'sour', 'saison', 'gose',
+    'hefeweizen', 'kolsch', 'cider', 'seltzer', 'pale', 'amber', 'wheat', 'witbier', 'helles', 'marzen', 'dunkel',
+]);
+// Brewery-name words that don't identify the brewery ("Brewing Company").
+const BREWERY_NOISE = new Set([
+    'brewing', 'brewery', 'breweries', 'brewers', 'brewhouse', 'brew', 'company', 'co', 'beer', 'beers', 'ales',
+    'the', 'and', 'works', 'project', 'craft', 'inc', 'llc',
+]);
+/** Lowercase, strip accents/apostrophes, turn every other non-alphanumeric into a space. */
+export function tokenize(s) {
+    return s
+        .normalize('NFKD')
+        .replace(/[̀-ͯ]/g, '')
+        .toLowerCase()
+        .replace(/['’‘`´]/g, '') // harry's / harry’s → harrys, so either spelling matches
+        .replace(/[^a-z0-9]+/g, ' ')
+        .split(' ')
+        .filter(Boolean);
+}
+// Prices, pour sizes and ABV a menu prints next to the name.
+const NOISE_PATTERNS = [
+    /\$\s*\d+(?:[.,]\d{1,2})?/g, // $6, $ 7.50
+    /\b\d+(?:[.,]\d+)?\s*%(?:\s*abv)?/gi, // 6.5%, 7% ABV
+    /\babv\b\s*\d+(?:[.,]\d+)?/gi, // ABV 6.5
+    /\b\d+(?:[.,]\d+)?\s*(?:oz|ml|cl|l)\b/gi, // 16oz, 12 oz, 330ml
+    /\b\d+[.,]\d{2}\b/g, // 7.00
+    /\b\d{1,2}\s*\/\s*\d{1,2}\s*$/g, // trailing "6/9" price columns (a bare trailing number may be part of a name)
+];
+/** Normalise one raw menu line and classify it. */
+export function normalizeLine(raw) {
+    let s = raw;
+    for (const re of NOISE_PATTERNS)
+        s = s.replace(re, ' ');
+    const tokens = [];
+    for (const t of tokenize(s)) {
+        // Collapse a duplicated word ("IPA IPA", "Lager Lager") from OCR or a
+        // style column printed after a name that already ends in the style.
+        if (tokens[tokens.length - 1] === t)
+            continue;
+        tokens.push(t);
+    }
+    // Generic only when nothing but filler follows the last generic word:
+    // "BLACK ABBEY SEASONAL" and "ROTATING DRAFT BEER" are, but "Widmer Rotator
+    // IPA" is a real beer whose name happens to contain one.
+    let lastGeneric = -1;
+    tokens.forEach((t, i) => {
+        if (GENERIC_WORDS.has(t))
+            lastGeneric = i;
+    });
+    if (lastGeneric !== -1 && tokens.slice(lastGeneric + 1).every((t) => GENERIC_FILLER.has(t))) {
+        const rest = tokens.filter((t) => !GENERIC_WORDS.has(t) && !GENERIC_FILLER.has(t));
+        return rest.length === 0
+            ? { raw, kind: 'generic', tokens }
+            : { raw, kind: 'brewery_generic', tokens, breweryHint: rest.join(' ') };
+    }
+    const named = tokens.filter((t) => !SERVING_WORDS.has(t));
+    return { raw, kind: named.length ? 'beer' : 'generic', tokens: named };
+}
+/** Search queries to try for a line, most specific first (deduped). */
+export function searchQueries(line) {
+    const full = line.tokens.join(' ');
+    const noStyle = line.tokens.filter((t) => !STYLE_WORDS.has(t)).join(' ');
+    return [...new Set([full, noStyle].filter(Boolean))];
+}
+const dict = (v) => (v && typeof v === 'object' && !Array.isArray(v) ? v : {});
+const numOr = (v, d) => (typeof v === 'number' && Number.isFinite(v) ? v : d);
+const strOr = (v) => (typeof v === 'string' && v.trim() ? v.trim() : null);
+/** Map a raw `/search/beer` item (`{checkin_count, beer, brewery}`) to a {@link Candidate}. */
+export function candidateFromSearch(item) {
+    const i = dict(item);
+    const beer = dict(i.beer);
+    const brewery = dict(i.brewery);
+    const bid = numOr(beer.bid, null);
+    if (bid === null)
+        return null;
+    return {
+        bid,
+        name: strOr(beer.beer_name) ?? '',
+        brewery: strOr(brewery.brewery_name) ?? '',
+        brewery_id: numOr(brewery.brewery_id, null),
+        brewery_city: strOr(dict(brewery.location).brewery_city),
+        style: strOr(beer.beer_style),
+        abv: numOr(beer.beer_abv, null),
+        checkin_count: numOr(i.checkin_count, 0) ?? 0,
+        rating: numOr(beer.rating_score, null) || null,
+    };
+}
+/**
+ * Score a candidate against a line's tokens. Higher is better. The terms:
+ *  - beer-name tokens found in the line (×4) and brewery tokens found (×3);
+ *  - each beer-name token NOT in the line costs 1.5 — the "Double Homestyle"
+ *    / "Triple Homestyle" guard when the menu said "Homestyle";
+ *  - each line token the candidate can't explain (by brewery, name or style)
+ *    costs 1;
+ *  - popularity, log10(check-ins) × 0.5 — the canonical 35k-check-in entry
+ *    beats a 3-check-in duplicate with the same name;
+ *  - +1 when the brewery's city is the venue's city (the tie-breaker).
+ */
+export function scoreCandidate(lineTokens, c, venueCity) {
+    const line = new Set(lineTokens);
+    const breweryAll = tokenize(c.brewery);
+    const breweryId = breweryAll.filter((t) => !BREWERY_NOISE.has(t));
+    const brewery = breweryId.length ? breweryId : breweryAll;
+    const name = tokenize(c.name);
+    const style = tokenize(c.style ?? '');
+    const frac = (ts) => (ts.length ? ts.filter((t) => line.has(t)).length / ts.length : 0);
+    const brewery_match = frac(brewery);
+    const name_match = frac(name);
+    const extraName = name.filter((t) => !line.has(t)).length;
+    const explained = new Set([...breweryAll, ...name, ...style, ...BREWERY_NOISE]);
+    const unexplained = lineTokens.filter((t) => !explained.has(t)).length;
+    const sameCity = venueCity && c.brewery_city && tokenize(venueCity).join(' ') === tokenize(c.brewery_city).join(' ') ? 1 : 0;
+    const score = 4 * name_match +
+        3 * brewery_match -
+        1.5 * extraName -
+        unexplained +
+        0.5 * Math.log10(c.checkin_count + 1) +
+        sameCity;
+    return { ...c, score: Math.round(score * 1000) / 1000, name_match, brewery_match };
+}
+/** Rank candidates for a line, best first. Duplicate bids keep their best score. */
+export function rankCandidates(lineTokens, cands, venueCity) {
+    const best = new Map();
+    for (const c of cands) {
+        const s = scoreCandidate(lineTokens, c, venueCity);
+        const prev = best.get(c.bid);
+        if (!prev || s.score > prev.score)
+            best.set(c.bid, s);
+    }
+    return [...best.values()].sort((a, b) => b.score - a.score || b.checkin_count - a.checkin_count);
+}
+/**
+ * Is the top candidate a confident match? Most of the beer's name must be on
+ * the line, and the total must clear a floor that a name-only hit from an
+ * unrelated brewery doesn't reach.
+ */
+export function isConfident(top) {
+    return !!top && top.name_match >= 0.5 && top.score >= 4.5;
+}
+// Name/style hints that a brewery's beer is a seasonal or limited release.
+const SEASONAL_RE = /season|oktoberfest|okto|marzen|festbier|\bfest\b|pumpkin|winter|summer|spring|autumn|\bfall\b|harvest|holiday|christmas|xmas|noel|snow|maibock|wet hop|fresh hop|shandy|radler|limited|rotat|anniversary/i;
+/** Does this beer look like a seasonal / limited release? */
+export function looksSeasonal(name, style) {
+    return SEASONAL_RE.test(tokenize(name).join(' ')) || SEASONAL_RE.test(tokenize(style ?? '').join(' '));
+}
+/** Score a `/search/brewery` result's name against a brewery hint (fraction of hint tokens matched). */
+export function breweryNameMatch(hint, breweryName) {
+    const hintTokens = tokenize(hint).filter((t) => !BREWERY_NOISE.has(t));
+    const name = new Set(tokenize(breweryName));
+    return hintTokens.length ? hintTokens.filter((t) => name.has(t)).length / hintTokens.length : 0;
+}