untappd-mcp 2.4.0 → 2.5.0

package/dist/cache/sync-beers.js

@@ -1,5 +1,6 @@
 import { createHelpfulError, RateLimitError, messageOf } from '@chrischall/mcp-utils';
 import { mapBeerRow } from './store.js';
+import { checkRateBudget, resumeAdvice, stopFrom429, stopFromVerdict } from '../ratelimit.js';
 const PAGE_LIMIT = 50; // Untappd's max page size for /user/beers.
 // A resumed backfill re-reads this many already-fetched items: if beers dropped
 // out of the list between runs, everything below shifted UP past the stored
@@ -65,8 +66,25 @@ export async function syncUserBeers(client, cache, rawUsername, maxPages = 10) {
         }
     };
     const gapNow = async () => total === null ? 0 : total - (await cache.distinctBeersCount(rawUsername));
+    let rateStop;
     for (; pages < maxPages && !complete;) {
-        const page = pages === 0 ? await firstFetch(offset) : await fetchBeersPage(client, encodedUser, offset);
+        // Stop BEFORE a call that would run into the hourly limit; progress so far
+        // is already persisted (setState after every page), so the next run resumes.
+        const verdict = await checkRateBudget(client, cache);
+        if (!verdict.ok) {
+            rateStop = stopFromVerdict(verdict);
+            break;
+        }
+        let page;
+        try {
+            page = pages === 0 ? await firstFetch(offset) : await fetchBeersPage(client, encodedUser, offset);
+        }
+        catch (e) {
+            if (!(e instanceof RateLimitError))
+                throw e;
+            rateStop = stopFrom429(e);
+            break;
+        }
         pages++;
         if (page.total !== null)
             total = page.total;
@@ -146,7 +164,9 @@ export async function syncUserBeers(client, cache, rawUsername, maxPages = 10) {
     const anotherRunNeeded = !complete;
     const note = complete
         ? 'Full distinct-beers list is cached — has-had coverage is complete for this user. Re-run occasionally to pick up newly-had beers.'
-        : `Distinct-beers sync in progress (${cachedBeers}${total !== null ? `/${total}` : ''}). Run untappd_sync_user_beers again to fetch the next ${maxPages} pages.`;
+        : rateStop
+            ? `Distinct-beers sync paused (${cachedBeers}${total !== null ? `/${total}` : ''}). ${resumeAdvice(rateStop, 'untappd_sync_user_beers')}`
+            : `Distinct-beers sync in progress (${cachedBeers}${total !== null ? `/${total}` : ''}). Run untappd_sync_user_beers again to fetch the next ${maxPages} pages.`;
     return {
         username: rawUsername,
         beers_added: added,
@@ -158,6 +178,8 @@ export async function syncUserBeers(client, cache, rawUsername, maxPages = 10) {
         incremental,
         stopped_at_bid: stoppedAtBid,
         another_run_needed: anotherRunNeeded,
+        stopped_for_rate_limit: rateStop !== undefined,
+        ...(rateStop ? { rate_limit: rateStop } : {}),
         last_synced_at: now(),
         note,
     };

package/dist/cache/sync-brewery-likes.js

@@ -0,0 +1,124 @@
+import { createHelpfulError, RateLimitError, messageOf } from '@chrischall/mcp-utils';
+import { mapBreweryLikeItem } from './store.js';
+import { checkRateBudget, resumeAdvice, stopFrom429, stopFromVerdict } from '../ratelimit.js';
+/** The `list_sync_state` key for a user's brewery-likes cursor (literal also in store.ts breweryLikesCoverage). */
+export const BREWERY_LIKES_LIST = 'brewery_likes';
+/**
+ * The `list_sync_state` key whose `last_synced_at` holds the CURRENT pass's
+ * stamp (same scheme as the wishlist mirror): rows a finished pass did not
+ * stamp were unliked upstream.
+ */
+export const BREWERY_LIKES_PASS_LIST = 'brewery_likes_pass';
+/** user/brewerylikes honours limit=50 (live, 6a); still advance by what it returns. */
+export const BREWERY_LIKES_PAGE_REQUEST = 50;
+/** A resumed pass re-reads this many items (the list may have shifted up between runs). */
+export const BREWERY_LIKES_RESUME_OVERLAP = 5;
+export const BREWERY_LIKES_MAX_PAGES_CAP = 50;
+const offsetOf = (po) => typeof po === 'number' ? po : typeof po === 'string' && /^\d+$/.test(po) ? Number(po) : null;
+/**
+ * Mirror the breweries a user "likes" on Untappd (user/brewerylikes — the
+ * app's "following"; works for non-self users) into `brewery_likes`, where they
+ * become the "untappd" favorite source. Same shape as the wishlist mirror: each
+ * sync is a full pass from the top, resumable across runs with the cursor
+ * persisted every page and the stop-before-429 guard before every call; rows
+ * are stamped with the pass and only a FINISHED pass removes unliked breweries.
+ */
+export async function syncBreweryLikes(client, cache, rawUsername, maxPages = 10) {
+    const pagesBudget = Math.max(1, Math.min(BREWERY_LIKES_MAX_PAGES_CAP, Math.floor(maxPages)));
+    const encodedUser = encodeURIComponent(rawUsername);
+    const now = () => new Date().toISOString();
+    const prior = await cache.getListState(rawUsername, BREWERY_LIKES_LIST);
+    const passRow = await cache.getListState(rawUsername, BREWERY_LIKES_PASS_LIST);
+    const resuming = !!prior && !prior.complete && prior.next_offset !== null && !!passRow?.last_synced_at;
+    let passStamp;
+    let offset;
+    if (resuming) {
+        passStamp = passRow.last_synced_at;
+        offset = Math.max(0, prior.next_offset - BREWERY_LIKES_RESUME_OVERLAP);
+    }
+    else {
+        const prev = passRow?.last_synced_at ? Date.parse(passRow.last_synced_at) : 0;
+        passStamp = new Date(Math.max(Date.now(), prev + 1)).toISOString();
+        offset = 0;
+        await cache.setListState(rawUsername, BREWERY_LIKES_PASS_LIST, { last_synced_at: passStamp, complete: false, next_offset: null });
+    }
+    let total = prior?.total_count ?? null;
+    let pages = 0;
+    let added = 0;
+    let removed = 0;
+    let complete = false;
+    let rateStop;
+    while (pages < pagesBudget && !complete) {
+        const verdict = await checkRateBudget(client, cache);
+        if (!verdict.ok) {
+            rateStop = stopFromVerdict(verdict);
+            break;
+        }
+        let data;
+        try {
+            data = await client.get(`/user/brewerylikes/${encodedUser}`, { limit: BREWERY_LIKES_PAGE_REQUEST, offset });
+        }
+        catch (e) {
+            if (e instanceof RateLimitError) {
+                rateStop = stopFrom429(e);
+                break;
+            }
+            if (pages > 0)
+                throw e;
+            throw createHelpfulError(`Could not fetch the liked breweries for "${rawUsername}": ${messageOf(e)}`, {
+                hint: "Untappd only returns another user's lists if their account is public or they're your friend.",
+            });
+        }
+        pages++;
+        const items = Array.isArray(data?.items) ? data.items : [];
+        if (typeof data?.total_count === 'number')
+            total = data.total_count;
+        const rows = [];
+        for (const it of items) {
+            const r = mapBreweryLikeItem(it);
+            if (r)
+                rows.push(r);
+        }
+        added += await cache.upsertBreweryLikes(rawUsername, rows, passStamp);
+        // pagination.offset is ABSENT on an empty list (live, 6a) — fall back to offset + items.
+        const next = offsetOf(data?.pagination?.offset);
+        const advanced = next !== null && next > offset ? next : offset + items.length;
+        complete =
+            items.length === 0 || (total !== null ? advanced >= total : items.length < BREWERY_LIKES_PAGE_REQUEST);
+        offset = advanced;
+        if (complete)
+            removed = await cache.pruneBreweryLikes(rawUsername, passStamp);
+        await cache.setListState(rawUsername, BREWERY_LIKES_LIST, {
+            next_offset: complete ? null : offset,
+            total_count: total,
+            complete,
+            last_synced_at: now(),
+        });
+        if (complete)
+            await cache.setListState(rawUsername, BREWERY_LIKES_PASS_LIST, { complete: true });
+    }
+    const cached = await cache.breweryLikesCount(rawUsername);
+    const percent = total !== null && total > 0 ? Math.min(100, Math.round((cached / total) * 100)) : complete ? 100 : null;
+    const progress = `${cached}${total !== null ? `/${total}` : ''}`;
+    const note = complete
+        ? `Liked breweries mirrored (${progress}). They now count as favorites with source "untappd". Re-run to pick up changes — each sync is a fresh pass from the top.`
+        : rateStop
+            ? `Brewery-likes sync paused (pass at offset ${offset}). ${resumeAdvice(rateStop, 'untappd_sync_brewery_likes')}`
+            : `Brewery-likes sync in progress (pass at offset ${offset}). Run untappd_sync_brewery_likes again to continue; unlikes apply when the pass finishes.`;
+    return {
+        username: rawUsername,
+        likes_added: added,
+        likes_removed: removed,
+        pages_fetched: pages,
+        cached,
+        total,
+        percent,
+        complete,
+        another_run_needed: !complete,
+        next_offset: complete ? null : offset,
+        stopped_for_rate_limit: rateStop !== undefined,
+        ...(rateStop ? { rate_limit: rateStop } : {}),
+        last_synced_at: now(),
+        note,
+    };
+}

package/dist/cache/sync-venues.js

@@ -0,0 +1,200 @@
+import { createHelpfulError, RateLimitError, messageOf } from '@chrischall/mcp-utils';
+import { mapUserVenueItem } from './store.js';
+import { checkRateBudget, resumeAdvice, stopFrom429, stopFromVerdict } from '../ratelimit.js';
+/** The `list_sync_state` key for a user's venue history. */
+export const VENUES_LIST = 'venues';
+/**
+ * The `list_sync_state` key for an incremental refresh in flight. A row with
+ * `complete = false` means a refresh was cut short (max_pages, the rate guard
+ * or a 429) before it reached its stop page; `next_offset` is where it resumes.
+ * Without it an interrupted refresh would restart at 0, find the pages it had
+ * already upserted unchanged, and stop short of the changes further down.
+ */
+export const VENUES_REFRESH_LIST = 'venues_refresh';
+/**
+ * What we ASK for per page. Untappd returns at most 25 venues whatever the
+ * limit (live, 2026-11), so the cursor advances by the returned
+ * `pagination.offset` — never by this number.
+ */
+export const VENUES_PAGE_REQUEST = 50;
+/** The most venues a page has been seen to hold; a shorter page is the last one. */
+const VENUES_SERVER_PAGE_MAX = 25;
+/**
+ * A resumed backfill re-reads this many already-fetched venues: if the list
+ * shifted up between runs (a venue dropped out), the ones that crossed the
+ * stored offset would otherwise be skipped. Upserts are idempotent.
+ */
+export const VENUES_RESUME_OVERLAP = 5;
+/** Hard cap on pages per call, whatever the caller asks. */
+export const VENUES_MAX_PAGES_CAP = 50;
+async function fetchVenuesPage(client, encodedUser, offset) {
+    const data = await client.get(`/user/venues/${encodedUser}`, { limit: VENUES_PAGE_REQUEST, offset, sort: 'date' });
+    const items = Array.isArray(data?.venues?.items)
+        ? data.venues.items
+        : Array.isArray(data?.items)
+            ? data.items
+            : [];
+    const total = typeof data?.total_count === 'number'
+        ? data.total_count
+        : typeof data?.venues?.total_count === 'number'
+            ? data.venues.total_count
+            : null;
+    const po = data?.pagination?.offset;
+    const nextOffset = typeof po === 'number' ? po : typeof po === 'string' && /^\d+$/.test(po) ? Number(po) : null;
+    return { items, total, nextOffset };
+}
+/**
+ * Sync a user's complete venue history (user/venues) into `venues` +
+ * `user_venues`. Unlike user/checkins, user/venues pages a NON-self account's
+ * whole history, so this is how "has this person been here?" gets answered.
+ *
+ * Resumable backfill: offset-paged (sort=date), the cursor and total persisted
+ * after EVERY page, at most `maxPages` (capped at 50) per call, stopping before
+ * the hourly rate limit. Once the whole list is cached, a re-run is an
+ * incremental refresh: page from offset 0 and stop at the first page on which
+ * every venue's recent_visit (and visit count) is unchanged. A refresh cut short
+ * before that stop page persists its own cursor and the next run resumes it
+ * (the history counts as incomplete meanwhile); only a finished refresh
+ * restarts at 0.
+ */
+export async function syncUserVenues(client, cache, rawUsername, maxPages = 10) {
+    const pagesBudget = Math.max(1, Math.min(VENUES_MAX_PAGES_CAP, Math.floor(maxPages)));
+    const encodedUser = encodeURIComponent(rawUsername);
+    const now = () => new Date().toISOString();
+    const prior = await cache.getListState(rawUsername, VENUES_LIST);
+    const incremental = (prior?.complete ?? false) && !!prior?.last_synced_at;
+    const refreshPrior = incremental ? await cache.getListState(rawUsername, VENUES_REFRESH_LIST) : undefined;
+    const resumeFrom = (o) => Math.max(0, (o ?? 0) - (o ? VENUES_RESUME_OVERLAP : 0));
+    // A finished refresh (or none yet) starts at the top; an unfinished one resumes.
+    let offset = incremental
+        ? refreshPrior && !refreshPrior.complete
+            ? resumeFrom(refreshPrior.next_offset)
+            : 0
+        : resumeFrom(prior?.next_offset);
+    let total = prior?.total_count ?? null;
+    let complete = false; // backfill: the whole list cached; refresh: the stop page (or the end) reached
+    let done = false;
+    let pages = 0;
+    let added = 0;
+    let updated = 0;
+    let rateStop;
+    while (pages < pagesBudget && !done) {
+        const verdict = await checkRateBudget(client, cache);
+        if (!verdict.ok) {
+            rateStop = stopFromVerdict(verdict);
+            break;
+        }
+        let page;
+        try {
+            page = await fetchVenuesPage(client, encodedUser, offset);
+        }
+        catch (e) {
+            if (e instanceof RateLimitError) {
+                rateStop = stopFrom429(e);
+                break;
+            }
+            if (pages > 0)
+                throw e;
+            throw createHelpfulError(`Could not fetch the venue history for "${rawUsername}": ${messageOf(e)}`, {
+                hint: "Untappd only returns another user's venues if their account is public or they're your friend. If the account is private, add them as a friend (untappd_add_friend) first.",
+            });
+        }
+        pages++;
+        if (page.total !== null)
+            total = page.total;
+        const mapped = [];
+        for (const it of page.items) {
+            const m = mapUserVenueItem(rawUsername, it);
+            if (m)
+                mapped.push(m);
+        }
+        // Incremental: a page on which every venue is already cached with the same
+        // recent_visit and count is where this refresh meets the last one — the
+        // list is newest-visit first, so nothing below it has changed.
+        let unchangedPage = false;
+        if (incremental && mapped.length > 0) {
+            const known = new Map((await cache.getUserVenueVisits(rawUsername, mapped.map((m) => m.visit.venue_id))).map((r) => [r.venue_id, r]));
+            unchangedPage = mapped.every((m) => {
+                const k = known.get(m.visit.venue_id);
+                return k !== undefined && k.recent_visit === m.visit.recent_visit && k.total_count === m.visit.total_count;
+            });
+        }
+        if (!unchangedPage && mapped.length > 0) {
+            const r = await cache.upsertUserVenues(rawUsername, mapped);
+            added += r.added;
+            updated += r.updated;
+        }
+        // Advance by what Untappd says the next offset is (it serves 25 per page
+        // even when asked for 50); fall back to counting the items it sent.
+        const advanced = page.nextOffset !== null && page.nextOffset > offset ? page.nextOffset : offset + page.items.length;
+        const atEnd = page.items.length === 0 ||
+            (total !== null ? advanced >= total : page.items.length < VENUES_SERVER_PAGE_MAX);
+        offset = advanced;
+        if (unchangedPage || atEnd) {
+            done = true;
+            complete = true;
+        }
+        if (incremental) {
+            // The backfill row stays complete (its cursor at the end of the list);
+            // the refresh's own progress lives in VENUES_REFRESH_LIST.
+            await cache.setListState(rawUsername, VENUES_REFRESH_LIST, {
+                next_offset: complete ? null : offset,
+                total_count: total,
+                complete,
+                last_synced_at: now(),
+            });
+            await cache.setListState(rawUsername, VENUES_LIST, {
+                next_offset: total ?? offset,
+                total_count: total,
+                complete: true,
+                ...(complete ? { last_synced_at: now() } : {}),
+            });
+        }
+        else {
+            await cache.setListState(rawUsername, VENUES_LIST, {
+                next_offset: complete ? (total ?? offset) : offset,
+                total_count: total,
+                complete,
+                last_synced_at: now(),
+            });
+        }
+    }
+    // A refresh that fetched nothing (rate-stopped before page 1) leaves any
+    // earlier unfinished refresh as it was; if there was none, the history is
+    // as complete as after the last finished refresh — but this one still has
+    // to run.
+    const refreshInProgress = incremental && (pages > 0 ? !complete : !!refreshPrior && !refreshPrior.complete);
+    const historyComplete = incremental ? !refreshInProgress : complete;
+    const cached = await cache.userVenuesCount(rawUsername);
+    const percent = total && total > 0 ? Math.min(100, Math.round((cached / total) * 100)) : historyComplete ? 100 : null;
+    const anotherRunNeeded = !complete;
+    const progress = `${cached}${total !== null ? `/${total}` : ''}`;
+    const note = complete
+        ? incremental
+            ? `Venue history refreshed (${progress} cached). Re-run occasionally to pick up new visits.`
+            : `Full venue history is cached (${progress}) — untappd_cache_has_visited answers are complete for this user.`
+        : refreshInProgress
+            ? `Venue history refresh unfinished (${progress} cached; resumes at offset ${offset}) — re-visited or new venues further down the list may not be cached yet. ${rateStop ? resumeAdvice(rateStop, 'untappd_sync_user_venues') : 'Run untappd_sync_user_venues again to continue the refresh.'}`
+            : rateStop
+                ? `Venue history sync paused (${progress}). ${resumeAdvice(rateStop, 'untappd_sync_user_venues')}`
+                : `Venue history sync in progress (${progress}). Run untappd_sync_user_venues again to fetch the next ${pagesBudget} pages.`;
+    const state = await cache.getListState(rawUsername, VENUES_LIST);
+    return {
+        username: rawUsername,
+        venues_added: added,
+        venues_updated: updated,
+        pages_fetched: pages,
+        cached_venues: cached,
+        total_venues: total,
+        backfill_percent: percent,
+        venues_complete: historyComplete,
+        incremental,
+        refresh_in_progress: refreshInProgress,
+        another_run_needed: anotherRunNeeded,
+        next_offset: refreshInProgress ? offset : (state?.next_offset ?? null),
+        stopped_for_rate_limit: rateStop !== undefined,
+        ...(rateStop ? { rate_limit: rateStop } : {}),
+        last_synced_at: now(),
+        note,
+    };
+}

package/dist/cache/sync-wishlist.js

@@ -0,0 +1,126 @@
+import { createHelpfulError, RateLimitError, messageOf } from '@chrischall/mcp-utils';
+import { mapWishlistItem } from './store.js';
+import { checkRateBudget, resumeAdvice, stopFrom429, stopFromVerdict } from '../ratelimit.js';
+/** The `list_sync_state` key for a user's wishlist cursor (literal also in store.ts wishlistCoverage). */
+export const WISHLIST_LIST = 'wishlist';
+/**
+ * The `list_sync_state` key whose `last_synced_at` holds the CURRENT pass's
+ * stamp. Every row a pass sees is stamped with it, so when the pass reaches the
+ * end, rows carrying any other stamp were removed from the wishlist upstream.
+ */
+export const WISHLIST_PASS_LIST = 'wishlist_pass';
+/** What we ask for per page; Untappd may serve fewer, so advance by what it returns. */
+export const WISHLIST_PAGE_REQUEST = 50;
+const WISHLIST_SERVER_PAGE_MAX = 25;
+/** A resumed pass re-reads this many items (the list may have shifted up between runs). */
+export const WISHLIST_RESUME_OVERLAP = 5;
+export const WISHLIST_MAX_PAGES_CAP = 50;
+/**
+ * Mirror a user's wishlist (user/wishlist) into the `wishlist` table so pick
+ * tools can boost wishlisted beers without an API call. Wishlists change in
+ * both directions, so each sync is a full pass from the top (they are small:
+ * ~25 beers per call), resumable across runs with the cursor persisted every
+ * page and the stop-before-429 guard before every call. Removals are applied
+ * only when a pass reaches the end — a partial pass never deletes.
+ */
+export async function syncWishlist(client, cache, rawUsername, maxPages = 10) {
+    const pagesBudget = Math.max(1, Math.min(WISHLIST_MAX_PAGES_CAP, Math.floor(maxPages)));
+    const encodedUser = encodeURIComponent(rawUsername);
+    const now = () => new Date().toISOString();
+    const prior = await cache.getListState(rawUsername, WISHLIST_LIST);
+    const passRow = await cache.getListState(rawUsername, WISHLIST_PASS_LIST);
+    // Resume an unfinished pass; otherwise start a new one from the top, with a
+    // stamp strictly later than the previous pass's so old rows never share it.
+    const resuming = !!prior && !prior.complete && prior.next_offset !== null && !!passRow?.last_synced_at;
+    let passStamp;
+    let offset;
+    if (resuming) {
+        passStamp = passRow.last_synced_at;
+        offset = Math.max(0, prior.next_offset - WISHLIST_RESUME_OVERLAP);
+    }
+    else {
+        const prev = passRow?.last_synced_at ? Date.parse(passRow.last_synced_at) : 0;
+        passStamp = new Date(Math.max(Date.now(), prev + 1)).toISOString();
+        offset = 0;
+        await cache.setListState(rawUsername, WISHLIST_PASS_LIST, { last_synced_at: passStamp, complete: false, next_offset: null });
+    }
+    let total = prior?.total_count ?? null;
+    let pages = 0;
+    let added = 0;
+    let removed = 0;
+    let complete = false;
+    let rateStop;
+    while (pages < pagesBudget && !complete) {
+        const verdict = await checkRateBudget(client, cache);
+        if (!verdict.ok) {
+            rateStop = stopFromVerdict(verdict);
+            break;
+        }
+        let data;
+        try {
+            data = await client.get(`/user/wishlist/${encodedUser}`, { limit: WISHLIST_PAGE_REQUEST, offset, sort: 'date' });
+        }
+        catch (e) {
+            if (e instanceof RateLimitError) {
+                rateStop = stopFrom429(e);
+                break;
+            }
+            if (pages > 0)
+                throw e;
+            throw createHelpfulError(`Could not fetch the wishlist for "${rawUsername}": ${messageOf(e)}`, {
+                hint: "Untappd only returns another user's wishlist if their account is public or they're your friend.",
+            });
+        }
+        pages++;
+        const items = Array.isArray(data?.beers?.items) ? data.beers.items : [];
+        if (typeof data?.total_count === 'number')
+            total = data.total_count;
+        else if (typeof data?.beers?.total_count === 'number')
+            total = data.beers.total_count;
+        const rows = [];
+        for (const it of items) {
+            const r = mapWishlistItem(it);
+            if (r)
+                rows.push(r);
+        }
+        added += await cache.upsertWishlist(rawUsername, rows, passStamp);
+        const po = data?.pagination?.offset;
+        const next = typeof po === 'number' ? po : typeof po === 'string' && /^\d+$/.test(po) ? Number(po) : null;
+        const advanced = next !== null && next > offset ? next : offset + items.length;
+        complete =
+            items.length === 0 || (total !== null ? advanced >= total : items.length < WISHLIST_SERVER_PAGE_MAX);
+        offset = advanced;
+        if (complete)
+            removed = await cache.pruneWishlist(rawUsername, passStamp);
+        await cache.setListState(rawUsername, WISHLIST_LIST, {
+            next_offset: complete ? null : offset,
+            total_count: total,
+            complete,
+            last_synced_at: now(),
+        });
+        if (complete)
+            await cache.setListState(rawUsername, WISHLIST_PASS_LIST, { complete: true });
+    }
+    const cached = await cache.wishlistCount(rawUsername);
+    const progress = `${cached}${total !== null ? `/${total}` : ''}`;
+    const note = complete
+        ? `Wishlist mirrored (${progress} beers). Re-run to pick up changes — each sync is a fresh pass from the top.`
+        : rateStop
+            ? `Wishlist sync paused (pass at offset ${offset}). ${resumeAdvice(rateStop, 'untappd_sync_wishlist')}`
+            : `Wishlist sync in progress (pass at offset ${offset}). Run untappd_sync_wishlist again to continue; removals apply when the pass finishes.`;
+    return {
+        username: rawUsername,
+        wishlist_added: added,
+        wishlist_removed: removed,
+        pages_fetched: pages,
+        cached,
+        total,
+        complete,
+        another_run_needed: !complete,
+        next_offset: complete ? null : offset,
+        stopped_for_rate_limit: rateStop !== undefined,
+        ...(rateStop ? { rate_limit: rateStop } : {}),
+        last_synced_at: now(),
+        note,
+    };
+}

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,
     };