untappd-mcp 2.4.0 → 2.5.1

package/dist/cache/brewery-beers.js

@@ -0,0 +1,116 @@
+import { mapBreweryBeerItem } from './store.js';
+/** Default TTL of a cached brewery beer list. */
+export const BREWERY_BEERS_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+/** Untappd's own default page size for brewery/beer_list. */
+export const BREWERY_BEERS_DEFAULT_LIMIT = 25;
+/** Local sort that approximates Untappd's for each sort key. */
+function sortRows(rows, sort) {
+    const byNum = (f) => (a, b) => (f(b) ?? -Infinity) - (f(a) ?? -Infinity) || a.bid - b.bid;
+    const byStr = (f) => (a, b) => (f(a) ?? '￿').localeCompare(f(b) ?? '￿', 'en', { sensitivity: 'base' }) || a.bid - b.bid;
+    const cmp = {
+        name: byStr((r) => r.beer_name),
+        style: byStr((r) => r.style),
+        abv: byNum((r) => r.abv),
+        rating: byNum((r) => r.rating_score),
+        count: byNum((r) => r.checkin_count),
+    }[sort];
+    return [...rows].sort(cmp);
+}
+/**
+ * The requested window from a FRESH cached list, or null when the cache can't
+ * answer it faithfully: the default (popularity) order is served from the
+ * contiguous ranked prefix; any other sort only once the WHOLE list is cached
+ * (sorting a top-50 subset by name would silently be a different answer).
+ */
+export function serveFromList(list, req) {
+    const offset = req.offset ?? 0;
+    const limit = req.limit ?? BREWERY_BEERS_DEFAULT_LIMIT;
+    const total = list.total_count;
+    const complete = total !== null && list.beers.length >= total;
+    if (req.sort === undefined) {
+        const end = total !== null ? Math.min(offset + limit, total) : offset + limit;
+        if (list.ranked_count >= end || complete)
+            return list.beers.slice(offset, offset + limit);
+        return null;
+    }
+    if (!complete)
+        return null;
+    return sortRows(list.beers, req.sort).slice(offset, offset + limit);
+}
+/**
+ * A brewery's beers, from the cache when its list is fresh (TTL default 7 days)
+ * and covers the window, else from brewery/beer_list (one call) — which is then
+ * stored. A stale list, or `refresh: true`, restarts the snapshot so beers that
+ * left the list don't linger. Rows carry only global facts: beer_list's
+ * `has_had` is the AUTHENTICATED account's and is never kept or returned.
+ */
+export async function getBreweryBeers(client, cache, breweryId, req = {}) {
+    const now = req.now ?? new Date();
+    const ttl = req.ttlMs ?? BREWERY_BEERS_TTL_MS;
+    const expiry = (fetchedAt) => new Date(Date.parse(fetchedAt) + ttl).toISOString();
+    const cached = cache ? await cache.getBreweryBeerList(breweryId) : undefined;
+    const fresh = cached !== undefined && now.getTime() - Date.parse(cached.fetched_at) < ttl;
+    if (cached && fresh && !req.refresh) {
+        const rows = serveFromList(cached, req);
+        if (rows) {
+            return {
+                brewery_id: breweryId,
+                brewery_name: cached.brewery_name,
+                total_count: cached.total_count,
+                source: 'cache',
+                fetched_at: cached.fetched_at,
+                expires_at: expiry(cached.fetched_at),
+                beers: rows,
+            };
+        }
+    }
+    const offset = req.offset ?? 0;
+    const raw = await client.get(`/brewery/beer_list/${breweryId}`, {
+        limit: req.limit,
+        offset: req.offset,
+        sort: req.sort,
+    });
+    const items = Array.isArray(raw?.beers?.items) ? raw.beers.items : [];
+    const total = typeof raw?.total_count === 'number'
+        ? raw.total_count
+        : typeof raw?.beers?.total_count === 'number'
+            ? raw.beers.total_count
+            : null;
+    const stamp = now.toISOString();
+    const ranked = req.sort === undefined;
+    const rows = [];
+    let breweryName = typeof raw?.brewery?.brewery_name === 'string' ? raw.brewery.brewery_name : null;
+    items.forEach((it, i) => {
+        const r = mapBreweryBeerItem(breweryId, it, stamp, ranked ? offset + i : null);
+        if (r)
+            rows.push(r);
+        const n = it?.brewery?.brewery_name;
+        if (breweryName === null && typeof n === 'string')
+            breweryName = n;
+    });
+    let fetchedAt = null;
+    if (cache) {
+        const restart = !cached || !fresh || req.refresh === true;
+        await cache.saveBreweryBeerPage({
+            brewery_id: breweryId,
+            brewery_name: breweryName,
+            total_count: total,
+            rows,
+            ranked_offset: ranked ? offset : null,
+            item_count: items.length,
+            restart,
+            fetched_at: stamp,
+        });
+        fetchedAt = restart ? stamp : cached.fetched_at;
+    }
+    return {
+        brewery_id: breweryId,
+        brewery_name: breweryName,
+        total_count: total,
+        source: 'api',
+        fetched_at: fetchedAt,
+        expires_at: fetchedAt ? expiry(fetchedAt) : null,
+        beers: rows,
+        raw,
+    };
+}

package/dist/cache/favorites.js

@@ -0,0 +1,244 @@
+export const FAVORITE_SOURCES = ['untappd', 'derived', 'manual'];
+export const DEFAULT_FAVORITE_THRESHOLDS = Object.freeze({
+    venue_min_checkins: 5,
+    venue_min_months: 3,
+    brewery_min_beers: 5,
+    brewery_min_avg_rating: 3.75,
+    brewery_min_beers_any_rating: 15,
+    beer_min_rating: 4.25,
+    beer_min_times_had: 3,
+});
+/** Rating a brewery with no rated beers is ranked at (a neutral mid-scale value). */
+const UNRATED_BREWERY_RATING = 3.5;
+export const NOT_FAVORITE = Object.freeze({ is_favorite: false, sources: [], reason: null });
+function thresholds(t) {
+    const out = { ...DEFAULT_FAVORITE_THRESHOLDS };
+    for (const [k, v] of Object.entries(t ?? {}))
+        if (v !== undefined)
+            out[k] = v;
+    return out;
+}
+/** Calendar months covered from `first` to `recent`, inclusive (UTC); 0 when either is missing. */
+export function monthSpan(first, recent) {
+    if (!first || !recent)
+        return 0;
+    const a = new Date(first);
+    const b = new Date(recent);
+    if (Number.isNaN(a.getTime()) || Number.isNaN(b.getTime()))
+        return 0;
+    const months = (b.getUTCFullYear() - a.getUTCFullYear()) * 12 + (b.getUTCMonth() - a.getUTCMonth()) + 1;
+    return Math.max(months, 1);
+}
+const fmt = (x) => String(Number(x.toFixed(2)));
+const ym = (iso) => (iso ? iso.slice(0, 7) : '?');
+function deriveVenue(v, t) {
+    const count = v.total_count ?? 0;
+    const months = monthSpan(v.first_visit, v.recent_visit);
+    const byCount = count >= t.venue_min_checkins;
+    // Only first/recent visit dates are known, so N visits can cover at most N
+    // distinct months: a 2-visit venue is never a "3 distinct months" favorite.
+    const byMonths = months >= t.venue_min_months && count >= t.venue_min_months;
+    if (!byCount && !byMonths)
+        return null;
+    const reason = byCount
+        ? `${count} check-ins since ${v.first_visit ? v.first_visit.slice(0, 4) : 'unknown'}`
+        : `${count} check-ins over ${months} months (${ym(v.first_visit)} to ${ym(v.recent_visit)})`;
+    return {
+        kind: 'venue',
+        id: v.venue_id,
+        name: v.name,
+        reason,
+        score: count,
+        metrics: { total_count: count, months_spanned: months, first_visit: v.first_visit, recent_visit: v.recent_visit, city: v.city, state: v.state },
+    };
+}
+/**
+ * Derived favorites of one kind for one user, best first. `ids` restricts the
+ * check to those items (for annotating results); thresholds default to the spec.
+ */
+export async function deriveFavorites(cache, username, kind, t, ids) {
+    const th = thresholds(t);
+    const out = [];
+    if (kind === 'venue') {
+        const rows = await cache.venueVisitStats(username, {
+            venueIds: ids,
+            minCheckins: Math.min(th.venue_min_checkins, th.venue_min_months),
+        });
+        for (const v of rows) {
+            const f = deriveVenue(v, th);
+            if (f)
+                out.push(f);
+        }
+    }
+    else if (kind === 'brewery') {
+        for (const b of await cache.breweryHadStats(username, ids)) {
+            const byRating = b.beers >= th.brewery_min_beers && b.avg_rating !== null && b.avg_rating >= th.brewery_min_avg_rating;
+            const byCount = b.beers >= th.brewery_min_beers_any_rating;
+            if (!byRating && !byCount)
+                continue;
+            const avg = b.avg_rating;
+            const reason = byRating
+                ? `avg ${fmt(avg)} across ${b.rated_beers === b.beers ? `${b.beers} beers` : `${b.rated_beers} rated of ${b.beers} beers`}`
+                : `${b.beers} beers had${avg !== null ? ` (avg ${fmt(avg)})` : ''}`;
+            out.push({
+                kind: 'brewery',
+                id: b.brewery_id,
+                name: b.brewery_name,
+                reason,
+                // Blend: average rating weighted by log2(beers + 1) — more beers matters, with diminishing returns.
+                score: Number(((avg ?? UNRATED_BREWERY_RATING) * Math.log2(b.beers + 1)).toFixed(3)),
+                metrics: { beers: b.beers, rated_beers: b.rated_beers, avg_rating: avg === null ? null : Number(avg.toFixed(3)) },
+            });
+        }
+    }
+    else {
+        const rows = await cache.beerHadStats(username, ids ? { bids: ids } : { minRating: th.beer_min_rating, minTimesHad: th.beer_min_times_had });
+        for (const b of rows) {
+            const byRating = b.rating !== null && b.rating >= th.beer_min_rating;
+            const byTimes = b.times_had >= th.beer_min_times_had;
+            if (!byRating && !byTimes)
+                continue;
+            const parts = [];
+            if (byRating)
+                parts.push(`rated ${fmt(b.rating)}`);
+            if (byTimes)
+                parts.push(`had ${b.times_had} times`);
+            out.push({
+                kind: 'beer',
+                id: b.bid,
+                name: b.beer_name,
+                reason: parts.join(', '),
+                score: b.rating ?? 0,
+                metrics: { rating: b.rating, times_had: b.times_had, brewery_id: b.brewery_id, brewery_name: b.brewery_name },
+            });
+        }
+        out.sort((a, b) => b.score - a.score || Number(b.metrics.times_had) - Number(a.metrics.times_had) || a.id - b.id);
+        return out;
+    }
+    out.sort((a, b) => b.score - a.score || a.id - b.id);
+    return out;
+}
+const manualReason = (note) => (note ? `manual: ${note}` : 'added manually');
+const likedReason = (l) => (l.liked_at ? `liked on Untappd (since ${ym(l.liked_at)})` : 'liked on Untappd');
+/** The user's Untappd brewery likes (the only kind Untappd has a list for). */
+async function likesFor(cache, username, kind, ids) {
+    if (kind !== 'brewery')
+        return [];
+    return cache.getBreweryLikes(username, ids);
+}
+function orderSources(s) {
+    const set = new Set(s);
+    return FAVORITE_SOURCES.filter((x) => set.has(x));
+}
+/**
+ * Every favorite of one user (optionally one kind / one source), each listed
+ * once with merged sources: derived ones in rank order, then manual-only ones
+ * newest first, then Untappd-liked-only ones, most recently liked first.
+ */
+export async function listFavorites(cache, username, opts = {}) {
+    const kinds = opts.kind ? [opts.kind] : ['venue', 'brewery', 'beer'];
+    const out = [];
+    for (const kind of kinds) {
+        const manual = await cache.getManualFavorites(username, { kind });
+        const manualById = new Map(manual.map((m) => [m.id, m]));
+        const liked = await likesFor(cache, username, kind);
+        const likedById = new Map(liked.map((l) => [l.brewery_id, l]));
+        // Filtering to a source this kind has nothing in: no need to derive (it only adds merged sources).
+        const skipDerived = (opts.source === 'manual' && manual.length === 0) || (opts.source === 'untappd' && liked.length === 0);
+        const derived = skipDerived ? [] : await deriveFavorites(cache, username, kind, opts.thresholds);
+        const derivedById = new Map(derived.map((d) => [d.id, d]));
+        const entry = (id) => {
+            const d = derivedById.get(id);
+            const m = manualById.get(id);
+            const l = likedById.get(id);
+            const sources = [];
+            const reasons = [];
+            // Reasons follow FAVORITE_SOURCES order: untappd, derived, manual.
+            if (l) {
+                sources.push('untappd');
+                reasons.push(likedReason(l));
+            }
+            if (d) {
+                sources.push('derived');
+                reasons.push(d.reason);
+            }
+            if (m) {
+                sources.push('manual');
+                reasons.push(manualReason(m.note));
+            }
+            return {
+                kind,
+                id,
+                name: d?.name ?? m?.name ?? l?.brewery_name ?? null,
+                is_favorite: true,
+                sources: orderSources(sources),
+                reason: reasons.join('; '),
+                ...(l ? { liked_at: l.liked_at } : {}),
+                ...(m ? { note: m.note, created_at: m.created_at } : {}),
+                ...(d ? { score: d.score, metrics: d.metrics } : {}),
+            };
+        };
+        const seen = new Set();
+        const ids = [...derived.map((d) => d.id), ...manual.map((m) => m.id), ...liked.map((l) => l.brewery_id)].filter((id) => {
+            if (seen.has(id))
+                return false;
+            seen.add(id);
+            return true;
+        });
+        for (const id of ids) {
+            const e = entry(id);
+            if (opts.source && !e.sources.includes(opts.source))
+                continue;
+            out.push(e);
+        }
+    }
+    return out;
+}
+/**
+ * Build a {@link FavoriteIndex} for the given ids, for one user or a group (a
+ * favorite of ANY member counts; with several users each reason part names its
+ * user). Cache only. Shared by every tool that carries a `favorite` field.
+ */
+export async function favoriteLookup(cache, usernames, ids, t) {
+    const group = usernames.length > 1;
+    const map = new Map();
+    const add = (kind, id, source, reason, user) => {
+        const k = `${kind}:${id}`;
+        const cur = map.get(k) ?? { sources: new Set(), reasons: [] };
+        cur.sources.add(source);
+        cur.reasons.push(group ? `${user}: ${reason}` : reason);
+        map.set(k, cur);
+    };
+    for (const kind of ['beer', 'brewery', 'venue']) {
+        const list = [...new Set((ids[kind] ?? []).filter((x) => typeof x === 'number' && Number.isFinite(x)))];
+        if (list.length === 0)
+            continue;
+        for (const user of usernames) {
+            const derived = await deriveFavorites(cache, user, kind, t, list);
+            const manual = await cache.getManualFavorites(user, { kind, ids: list });
+            const manualIds = new Map(manual.map((m) => [m.id, m]));
+            const liked = new Map((await likesFor(cache, user, kind, list)).map((l) => [l.brewery_id, l]));
+            // Per user, for each id: untappd, derived, then manual reason.
+            for (const id of list) {
+                const l = liked.get(id);
+                if (l)
+                    add(kind, id, 'untappd', likedReason(l), user);
+                const d = derived.find((x) => x.id === id);
+                if (d)
+                    add(kind, id, 'derived', d.reason, user);
+                const m = manualIds.get(id);
+                if (m)
+                    add(kind, id, 'manual', manualReason(m.note), user);
+            }
+        }
+    }
+    const get = (kind, id) => {
+        if (id === null || id === undefined)
+            return { ...NOT_FAVORITE, sources: [] };
+        const hit = map.get(`${kind}:${id}`);
+        if (!hit)
+            return { ...NOT_FAVORITE, sources: [] };
+        return { is_favorite: true, sources: orderSources(hit.sources), reason: hit.reasons.join('; ') };
+    };
+    return { get, isFavorite: (kind, id) => get(kind, id).is_favorite };
+}

package/dist/cache/multi-user.js

@@ -0,0 +1,61 @@
+import { createHelpfulError } from '@chrischall/mcp-utils';
+export const MULTI_USER_MODES = ['none_had', 'any_not_had'];
+export const DEFAULT_MULTI_USER_MODE = 'none_had';
+/** Most usernames one group check accepts. */
+export const MAX_GROUP_USERS = 10;
+/**
+ * The users a cache read is about: `usernames` (deduped case-insensitively,
+ * first spelling kept) when given, else `username`, else the configured login.
+ * Passing both `username` and `usernames` is ambiguous and rejected.
+ */
+export function resolveUsers(username, usernames, loginName) {
+    if (usernames && usernames.length > 0) {
+        if (username !== undefined) {
+            throw createHelpfulError('Pass either username or usernames, not both.', {
+                hint: 'For a group check put every user in usernames (include yourself explicitly).',
+            });
+        }
+        const seen = new Set();
+        const out = [];
+        for (const u of usernames) {
+            const k = u.toLowerCase();
+            if (seen.has(k))
+                continue;
+            seen.add(k);
+            out.push(u);
+        }
+        return out;
+    }
+    const u = username ?? loginName;
+    if (!u) {
+        throw createHelpfulError('No username given and no configured account to fall back to.', {
+            hint: 'Pass `username` (or `usernames`), or set UNTAPPD_USERNAME so cache tools default to your own account.',
+        });
+    }
+    return [u];
+}
+/**
+ * Group has-had over the cache only: one batched {@link CacheStore.hasHadMany}
+ * per user, then each bid (deduped, input order kept) is marked against `mode`.
+ */
+export async function multiHasHad(cache, usernames, bids, mode) {
+    const candidates = [...new Set(bids)];
+    const out = new Map();
+    for (const bid of candidates)
+        out.set(bid, { bid, qualifies: false, had_by: [], not_had_by: [] });
+    for (const user of usernames) {
+        const verdicts = await cache.hasHadMany(user, candidates);
+        for (const bid of candidates) {
+            const v = verdicts.get(bid);
+            const g = out.get(bid);
+            if (v?.had)
+                g.had_by.push({ username: user, count: v.count, last_date: v.last_date, best_rating: v.best_rating });
+            else
+                g.not_had_by.push(user);
+        }
+    }
+    for (const g of out.values()) {
+        g.qualifies = mode === 'none_had' ? g.had_by.length === 0 : g.not_had_by.length > 0;
+    }
+    return out;
+}

package/dist/cache/response-cache.js

@@ -0,0 +1,23 @@
+/** Default TTL for cached venue menus and venue activity. */
+export const VENUE_RESPONSE_TTL_MS = 6 * 60 * 60 * 1000;
+/**
+ * Serve `key` from the short-TTL `response_cache` when fresh, else call
+ * `fetch` and store what it returns. A thrown fetch (429, budget, network) is
+ * never cached. With no cache it just fetches.
+ */
+export async function cachedResponse(cache, key, kind, fetch, opts = {}) {
+    const now = opts.now ?? new Date();
+    const ttl = opts.ttlMs ?? VENUE_RESPONSE_TTL_MS;
+    const expiry = (at) => new Date(Date.parse(at) + ttl).toISOString();
+    if (cache && !opts.refresh) {
+        const hit = await cache.getCachedResponse(key);
+        if (hit && now.getTime() - Date.parse(hit.fetched_at) < ttl) {
+            return { data: hit.data, hit: true, fetched_at: hit.fetched_at, expires_at: expiry(hit.fetched_at) };
+        }
+    }
+    const data = await fetch();
+    const stamp = now.toISOString();
+    if (cache)
+        await cache.putCachedResponse(key, kind, data, stamp);
+    return { data, hit: false, fetched_at: stamp, expires_at: cache ? expiry(stamp) : null };
+}