untappd-mcp 2.4.0 → 2.5.1

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`:
@@ -13,8 +14,6 @@ if (import.meta.url) {
 const BASE_URL = 'https://api.untappd.com/v4';
 const SERVICE = 'Untappd';
 const REQUEST_TIMEOUT_MS = 30_000;
-// Untappd's limit is per hour, so a remaining-count older than that says nothing.
-const QUOTA_WINDOW_MS = 60 * 60 * 1000;
 // Non-secret client constants that mimic the Untappd iPad app (v4.7.13). The
 // API accepts requests carrying these; NONE are user secrets (the secrets are
 // UNTAPPD_CLIENT_ID / UNTAPPD_CLIENT_SECRET / UNTAPPD_USERNAME / _PASSWORD,
@@ -153,8 +152,9 @@ export class UntappdClient {
     userAgent = readEnvVar('UNTAPPD_USER_AGENT') ?? DEFAULTS.userAgent;
     token;
     loginInFlight = null;
-    /** Last `X-Ratelimit-Remaining` seen, and when (see {@link quotaRemaining}). */
-    lastQuota = 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
@@ -211,22 +211,36 @@ export class UntappdClient {
         return this._loginName;
     }
     /**
-     * Calls left this hour, from the most recent response's
-     * `X-Ratelimit-Remaining` — or null when no response has carried the header
-     * within the hour. Untappd's public API documents the header; whether the
-     * private v4 endpoints send it is unverified, so every consumer must treat
-     * null as "unknown" and fall back to its own budget.
+     * 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() {
-        if (!this.lastQuota || Date.now() - this.lastQuota.at > QUOTA_WINDOW_MS)
+        const obs = this.rateLimit.observations();
+        if (obs.length === 0)
             return null;
-        return this.lastQuota.remaining;
+        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 raw = res.headers.get('x-ratelimit-remaining');
-        const n = raw === null ? NaN : Number(raw);
-        if (raw !== null && raw.trim() !== '' && Number.isFinite(n) && n >= 0) {
-            this.lastQuota = { remaining: Math.floor(n), at: Date.now() };
+        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. */

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,57 @@ 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,
+        // Always present (null when favorites aren't known: no cache, or no username) so
+        // the cached and no-cache paths return the same keys.
+        favorite: favorites ? favorites.brewery : null,
+        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,6 +14,8 @@ 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, describeCachePath } from './cache/db.js';
@@ -28,15 +30,28 @@ const client = new UntappdClient();
 const cachePath = defaultCachePath();
 console.error(describeCachePath(cachePath));
 let nodeCache;
-const nodeCacheProvider = () => (nodeCache ??= CheckinCache.open(cachePath));
+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),
@@ -48,6 +63,8 @@ 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/pick.js

@@ -92,7 +92,11 @@ 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 counting = {
+        get: (p, q) => (calls++, client.get(p, q)),
+        // Hand the sync's rate guard the real tracker (absent on test fakes).
+        rateLimit: client.rateLimit,
+    };
     const extra = {};
     if (maxCalls < 1) {
         extra.skipped = 'no API budget left for a sync this run';
@@ -102,6 +106,8 @@ export async function ensureFresh(client, cache, username, maxCalls) {
             const s = await syncUserBeers(counting, cache, username, maxCalls);
             if (s.incremental)
                 extra.stopped_at_bid = s.stopped_at_bid;
+            if (s.stopped_for_rate_limit)
+                extra.rate_limited = true;
         }
         catch (e) {
             if (e instanceof RateLimitError)

package/dist/ratelimit.js

@@ -0,0 +1,236 @@
+// Rate-limit tracking for the ~100 calls/hour Untappd v4 limit.
+//
+// Every response the client receives is recorded as an ApiCallObservation
+// (time, status, and whatever X-Ratelimit-* / Retry-After headers it carried).
+// The headers alone can't be trusted: the v4 API sends `X-Ratelimit-Remaining:
+// 0` on EVERY successful response (observed live 2026-11-02), so a header-only
+// reading would report the quota exhausted after the first call. The estimate
+// therefore rests on a LOCAL count of calls in the rolling hour, and only takes
+// the header into account once it has reported a live (non-zero) value — or
+// when Untappd actually answered 429.
+//
+// The stdio server also persists observations into the shared cache file
+// (`api_calls` table), so a fresh process — or a second one sharing the file —
+// knows what was already spent this hour. `checkRateBudget` merges both views
+// and is the guard every paging sync consults before each page, so it can stop
+// cleanly with resume info instead of failing mid-batch on a 429.
+import { readEnvVar } from '@chrischall/mcp-utils';
+export const RATE_WINDOW_MS = 60 * 60 * 1000;
+/** Untappd's documented per-token limit; override with UNTAPPD_RATE_LIMIT_PER_HOUR. */
+export const DEFAULT_HOURLY_LIMIT = 100;
+/** Calls the guard leaves unspent so interactive tools still work after a sync. */
+export const DEFAULT_RESERVE = 2;
+function intHeader(h, name) {
+    const raw = h.get(name);
+    if (raw === null || raw.trim() === '')
+        return null;
+    const n = Number(raw);
+    return Number.isFinite(n) && n >= 0 ? Math.floor(n) : null;
+}
+/** Build an observation from a response's status and headers. */
+export function observeResponse(status, headers, now = Date.now()) {
+    const limit = intHeader(headers, 'x-ratelimit-limit');
+    const reset = intHeader(headers, 'x-ratelimit-reset');
+    let reset_at = null;
+    if (reset !== null) {
+        if (reset > 1e12)
+            reset_at = reset; // epoch ms
+        else if (reset > 1e9)
+            reset_at = reset * 1000; // epoch seconds
+        else
+            reset_at = now + reset * 1000; // seconds from now
+    }
+    const ra = intHeader(headers, 'retry-after');
+    return {
+        at: now,
+        status,
+        remaining: intHeader(headers, 'x-ratelimit-remaining'),
+        limit: limit !== null && limit > 0 ? limit : null,
+        reset_at,
+        retry_after_s: ra !== null && ra > 0 ? ra : null,
+    };
+}
+/** UNTAPPD_RATE_LIMIT_PER_HOUR, when set to a positive integer. */
+export function configuredHourlyLimit() {
+    const raw = readEnvVar('UNTAPPD_RATE_LIMIT_PER_HOUR');
+    const n = raw === undefined || raw === null ? NaN : Number(raw);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : null;
+}
+const iso = (ms) => (ms === null ? null : new Date(ms).toISOString());
+function compute(all, now, opts) {
+    const obs = all.filter((o) => o.at > now - RATE_WINDOW_MS).sort((a, b) => a.at - b.at);
+    const latestWith = (k) => {
+        for (let i = obs.length - 1; i >= 0; i--)
+            if (obs[i][k] !== null)
+                return obs[i];
+        return undefined;
+    };
+    const headerLimit = latestWith('limit')?.limit ?? null;
+    const configured = opts.configuredLimit ?? null;
+    const hourly_limit = configured ?? headerLimit ?? DEFAULT_HOURLY_LIMIT;
+    const limit_source = configured !== null ? 'env' : headerLimit !== null ? 'header' : 'assumed';
+    const lastRemaining = latestWith('remaining');
+    const headerRemaining = lastRemaining?.remaining ?? null;
+    const headerLive = obs.some((o) => o.remaining !== null && o.remaining > 0);
+    const resetMs = lastRemaining?.reset_at ?? null;
+    const headerTrusted = lastRemaining !== undefined && (headerLive || lastRemaining.status === 429) && (resetMs === null || resetMs > now);
+    let blockedUntilMs = null;
+    let last429 = null;
+    for (const o of obs) {
+        if (o.status !== 429)
+            continue;
+        last429 = o.at;
+        const until = o.retry_after_s !== null
+            ? o.at + o.retry_after_s * 1000
+            : o.reset_at ?? (obs[0] ? obs[0].at + RATE_WINDOW_MS : o.at + RATE_WINDOW_MS);
+        if (until > now && (blockedUntilMs === null || until > blockedUntilMs))
+            blockedUntilMs = until;
+    }
+    const local = hourly_limit - obs.length;
+    let estimate = local;
+    if (headerTrusted && headerRemaining !== null)
+        estimate = Math.min(estimate, headerRemaining);
+    if (blockedUntilMs !== null)
+        estimate = 0;
+    return {
+        hourly_limit,
+        limit_source,
+        calls_last_hour: obs.length,
+        estimated_remaining: Math.max(0, estimate),
+        header_remaining: headerRemaining,
+        header_remaining_trusted: headerTrusted,
+        header_reset_at: iso(resetMs),
+        last_response_at: iso(obs.length ? obs[obs.length - 1].at : null),
+        last_429_at: iso(last429),
+        blocked_until: iso(blockedUntilMs),
+        times: obs.map((o) => o.at),
+        blockedUntilMs,
+        headerBoundResetMs: headerTrusted ? resetMs : null,
+    };
+}
+/** The rate-limit picture for a set of observations (pure; for tests and the status tool). */
+export function computeRateLimitStatus(obs, now, opts) {
+    const { times: _t, blockedUntilMs: _b, headerBoundResetMs: _h, ...status } = compute(obs, now, opts);
+    return status;
+}
+/** In-memory record of this process's responses within the rolling hour. */
+export class RateLimitTracker {
+    obs = [];
+    record(o) {
+        this.obs.push(o);
+        this.prune(o.at);
+    }
+    observations(now = Date.now()) {
+        this.prune(now);
+        return [...this.obs];
+    }
+    prune(now) {
+        const cutoff = now - RATE_WINDOW_MS;
+        if (this.obs.length && this.obs[0].at <= cutoff)
+            this.obs = this.obs.filter((o) => o.at > cutoff);
+    }
+}
+/** This process's observations merged with the shared cache log, de-duplicated. */
+async function mergedObservations(client, cache, now) {
+    const tracker = client.rateLimit;
+    const mine = tracker?.observations(now) ?? [];
+    let theirs = [];
+    try {
+        theirs = (await cache?.recentApiCalls?.(now - RATE_WINDOW_MS)) ?? [];
+    }
+    catch {
+        /* an unreadable log just means "this process's view only" */
+    }
+    // The shared log normally already holds this process's own calls (the stdio
+    // server persists each one), so merge as a multiset: per identical
+    // observation, keep the larger of the two counts rather than summing them.
+    // Two genuinely separate calls in the same millisecond stay two.
+    const key = (o) => `${o.at}:${o.status}:${o.remaining}:${o.retry_after_s}`;
+    const group = (xs) => {
+        const m = new Map();
+        for (const o of xs)
+            m.set(key(o), [...(m.get(key(o)) ?? []), o]);
+        return m;
+    };
+    const a = group(mine);
+    const b = group(theirs);
+    const out = [];
+    for (const k of new Set([...a.keys(), ...b.keys()])) {
+        const x = a.get(k) ?? [];
+        const y = b.get(k) ?? [];
+        out.push(...(x.length >= y.length ? x : y));
+    }
+    return out;
+}
+/** The current rate-limit picture (this process + the shared cache log). */
+export async function rateLimitStatus(client, cache) {
+    const now = Date.now();
+    return computeRateLimitStatus(await mergedObservations(client, cache, now), now, {
+        configuredLimit: configuredHourlyLimit(),
+    });
+}
+/**
+ * The stop-before-429 guard: may a sync spend `needed` more calls and still
+ * leave `reserve` unspent? Paging syncs call it before EVERY page and stop
+ * cleanly (progress is persisted per page) with `resume_at` when it says no.
+ */
+export async function checkRateBudget(client, cache, opts = {}) {
+    const needed = opts.needed ?? 1;
+    const reserve = opts.reserve ?? DEFAULT_RESERVE;
+    const now = Date.now();
+    const c = compute(await mergedObservations(client, cache, now), now, { configuredLimit: configuredHourlyLimit() });
+    const base = {
+        estimated_remaining: c.estimated_remaining,
+        calls_last_hour: c.calls_last_hour,
+        hourly_limit: c.hourly_limit,
+        reserve,
+    };
+    if (c.estimated_remaining - needed >= reserve) {
+        return { ok: true, ...base, resume_at: null, resume_after_s: null };
+    }
+    let resumeMs = null;
+    if (c.blockedUntilMs !== null)
+        resumeMs = c.blockedUntilMs;
+    else if (c.headerBoundResetMs !== null)
+        resumeMs = c.headerBoundResetMs;
+    else {
+        // Rolling window: wait until enough of the oldest calls age out.
+        const deficit = needed + reserve - (c.hourly_limit - c.calls_last_hour);
+        if (deficit > 0 && deficit <= c.times.length)
+            resumeMs = c.times[deficit - 1] + RATE_WINDOW_MS;
+    }
+    return {
+        ok: false,
+        ...base,
+        resume_at: iso(resumeMs),
+        resume_after_s: resumeMs === null ? null : Math.max(0, Math.ceil((resumeMs - now) / 1000)),
+        reason: c.blockedUntilMs !== null
+            ? 'Untappd answered 429 (rate limited) and its wait has not elapsed yet.'
+            : `Stopped before Untappd's hourly rate limit: ~${c.estimated_remaining} of ${c.hourly_limit} calls left this hour, ${reserve} held in reserve.`,
+    };
+}
+/** A guard verdict as a sync's stop record. */
+export function stopFromVerdict(v) {
+    return {
+        reason: v.reason ?? 'rate limit',
+        estimated_remaining: v.estimated_remaining,
+        calls_last_hour: v.calls_last_hour,
+        hourly_limit: v.hourly_limit,
+        resume_at: v.resume_at,
+        resume_after_s: v.resume_after_s,
+    };
+}
+/** A 429 that slipped past the guard, as a sync's stop record. */
+export function stopFrom429(e, now = Date.now()) {
+    const ra = e.retryAfterSeconds;
+    return {
+        reason: 'Untappd answered 429 (rate limited); progress up to the last full page is saved.',
+        resume_at: ra !== undefined ? new Date(now + ra * 1000).toISOString() : null,
+        resume_after_s: ra ?? null,
+    };
+}
+/** One-line resume advice for a sync's `note`. */
+export function resumeAdvice(stop, tool) {
+    const when = stop.resume_at ? ` after ${stop.resume_at} (~${Math.ceil((stop.resume_after_s ?? 0) / 60)} min)` : ' later';
+    return `${stop.reason} Progress is saved — run ${tool} again${when} to resume.`;
+}