@domandigital/gbp 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.6.0
+
+### Minor Changes
+
+- 7437827: A dead Google token or a Google 503 no longer reaches the page, and no longer files a new error-tracker issue every time.
+  
+  - **`getBusinessReviewsSafe(options)` and `getPublishedReviewsSafe(options)`** never throw. On any failure they serve the last good result this process fetched (up to `maxStaleMs`, default 30 days), then your `fallback` (a snapshot, or a loader such as a KV read), then an empty result. `source` says which (`live`, `cache`, `fallback`, `empty`) and `error` holds the failure.
+  - They report each kind of failure at most once per `reportIntervalMs` (default one hour) per process, through `report(error, { fingerprint, context, transient, served, suppressed })`. Pass `fingerprint` and `context` straight to `Sentry.captureException`.
+  - After `invalid_grant` or `invalid_client` they skip the token request for `authRetryMs` (default five minutes) and serve the cache or fallback straight away.
+  - **Error messages are now short and stable**, with what varies moved to `error.context`: `GBP token refresh failed: invalid_grant` (was `Google OAuth token refresh failed: 400 invalid_grant (...)`), `GBP reviews.list failed: 5xx` (was the status plus Google's body), `GBP reviews.list timed out`. A published-file HTTP failure no longer puts the body in its message. Anything matching on the old message text needs updating; match on `error.code` instead.
+  - Every `GbpError` has `code`, `transient`, `context` and `fingerprint` (`["gbp", code]`). Every 5xx shares the code `api_5xx`, so a Google outage is one issue rather than one per status. `GbpApiError` also has `body`.
+
 ## 0.5.0
 
 ### Minor Changes

package/README.md

@@ -227,7 +227,45 @@ Options:
 Never throws on missing configuration -- `isBusinessProfileConfigured()` gates
 internally and returns an empty result, so UI can render unconditionally.
 Does throw on a real failure, so a calling route should catch and degrade
-explicitly if it wants zero-downtime behaviour on a Google outage.
+explicitly if it wants zero-downtime behaviour on a Google outage, or use
+`getBusinessReviewsSafe`, which does that for it.
+
+### `getBusinessReviewsSafe(options?)` and `getPublishedReviewsSafe(options)`: reviews that never throw
+
+Use these in a page render. They take the same options as `getBusinessReviews`
+and `getPublishedReviews`, catch every failure, and serve in order: the last
+good result this process fetched for the same options (up to `maxStaleMs`,
+default 30 days), then your `fallback`, then an empty result, which has a
+`null` rating and count and an empty `reviews` list. `source` says which:
+`"live"`, `"cache"`, `"fallback"` or `"empty"`, and `error` holds the failure
+when there was one.
+
+```ts
+import * as Sentry from "@sentry/nextjs";
+import { getBusinessReviewsSafe } from "@domandigital/gbp";
+
+const { averageRating, totalReviewCount, reviews, source } = await getBusinessReviewsSafe({
+  filterMinStars: 4,
+  next: { revalidate: 86400, tags: ["google-reviews"] },
+  // A snapshot, or a loader for one (a KV read). Served as given.
+  fallback: () => kv.get(LAST_KNOWN_GOOD_KEY),
+  report: (error, { fingerprint, context, transient }) =>
+    Sentry.captureException(error, { fingerprint, extra: context, level: transient ? "warning" : "error" }),
+});
+if (source === "live") await kv.set(LAST_KNOWN_GOOD_KEY, { averageRating, totalReviewCount, reviews });
+```
+
+- `report` runs at most once per kind of failure per `reportIntervalMs`
+  (default one hour) in each process, not on every request. It is told how
+  many it held back since the last report (`suppressed`). Without `report`, one
+  `console.warn` per window.
+- After `invalid_grant` or `invalid_client` the live call is skipped for
+  `authRetryMs` (default five minutes), because retrying cannot fix it.
+- A `fallback` is served as given: `limit` and `filterMinStars` are not
+  applied to it. A loader that throws counts as no fallback.
+
+A static build that should refuse to publish rather than ship stale or empty
+reviews should keep using the throwing functions.
 
 ### Failures, and what each one means
 
@@ -237,7 +275,13 @@ a few times with backoff; Google documents the 429 for quota
 A 401 means the cached access token is no longer good: it is dropped,
 refreshed once, and the page is asked for again; a second 401 throws.
 
-All errors extend `GbpError`, and none carries a credential:
+All errors extend `GbpError`, and none carries a credential. Each message is
+short and stable (`GBP token refresh failed: invalid_grant`, `GBP reviews.list
+failed: 5xx`), so an error tracker files every occurrence under one issue.
+What varies, such as the status, Google's description or a body excerpt, is in
+`error.context`. `error.code` names the failure, `error.fingerprint` is
+`["gbp", code]` to pass to Sentry, and `error.transient` says whether it may
+clear without anyone acting. Every 5xx shares the code `api_5xx`.
 
 | Error | When | What to do |
 |---|---|---|

package/dist/index.cjs

@@ -20,8 +20,11 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  DEFAULT_AUTH_RETRY_MS: () => DEFAULT_AUTH_RETRY_MS,
   DEFAULT_MAX_PAGES: () => DEFAULT_MAX_PAGES,
+  DEFAULT_MAX_STALE_MS: () => DEFAULT_MAX_STALE_MS,
   DEFAULT_PUBLISHED_REVIEWS_BASE_URL: () => DEFAULT_PUBLISHED_REVIEWS_BASE_URL,
+  DEFAULT_REPORT_INTERVAL_MS: () => DEFAULT_REPORT_INTERVAL_MS,
   DEFAULT_REQUEST_POLICY: () => DEFAULT_REQUEST_POLICY,
   GbpApiError: () => GbpApiError,
   GbpAuthError: () => GbpAuthError,
@@ -31,8 +34,10 @@ __export(index_exports, {
   GbpTimeoutError: () => GbpTimeoutError,
   PUBLISHED_REVIEWS_SCHEMA: () => PUBLISHED_REVIEWS_SCHEMA,
   getBusinessReviews: () => getBusinessReviews,
+  getBusinessReviewsSafe: () => getBusinessReviewsSafe,
   getGoogleOAuthAccessToken: () => getGoogleOAuthAccessToken,
   getPublishedReviews: () => getPublishedReviews,
+  getPublishedReviewsSafe: () => getPublishedReviewsSafe,
   hasGoogleOAuthCredentials: () => hasGoogleOAuthCredentials,
   invalidateAccessToken: () => invalidateAccessToken,
   isBusinessProfileConfigured: () => isBusinessProfileConfigured,
@@ -45,17 +50,25 @@ module.exports = __toCommonJS(index_exports);
 
 // src/errors.ts
 var GbpError = class extends Error {
-  constructor(message) {
+  constructor(message, code = "unknown", transient = false, context = {}) {
     super(message);
     this.name = new.target.name;
+    this.code = code;
+    this.transient = transient;
+    this.context = context;
+  }
+  /** `["gbp", code]`: one error-tracker issue per kind of failure. */
+  get fingerprint() {
+    return ["gbp", this.code];
   }
 };
 var GbpAuthError = class extends GbpError {
   constructor(code, status, description) {
-    super(
-      `Google OAuth token refresh failed: ${status} ${code}${description ? ` (${description})` : ""}` + (code === "invalid_grant" ? ". Reauthorise the Google account and replace GBP_REFRESH_TOKEN." : "")
-    );
-    this.code = code;
+    super(`GBP token refresh failed: ${code}`, code, code === "token_request_failed" && status >= 500, {
+      status,
+      ...description ? { description } : {},
+      ...code === "invalid_grant" ? { remedy: "Reauthorise the Google account and replace GBP_REFRESH_TOKEN." } : {}
+    });
     this.reauthorizationRequired = code === "invalid_grant";
     this.status = status;
     this.description = description;
@@ -63,7 +76,15 @@ var GbpAuthError = class extends GbpError {
 };
 var GbpApiError = class extends GbpError {
   constructor(options) {
-    super(`Business Profile reviews failed: ${options.status}${options.body ? ` ${options.body}` : ""}`);
+    const server = options.status >= 500;
+    super(`GBP ${options.operation} failed: ${server ? "5xx" : options.status}`, server ? "api_5xx" : `api_${options.status}`, options.retryable, {
+      operation: options.operation,
+      status: options.status,
+      attempts: options.attempts,
+      ...options.body ? { body: options.body } : {},
+      ...options.retryAfterMs !== void 0 ? { retryAfterMs: options.retryAfterMs } : {}
+    });
+    this.body = options.body;
     this.operation = options.operation;
     this.status = options.status;
     this.retryable = options.retryable;
@@ -73,7 +94,7 @@ var GbpApiError = class extends GbpError {
 };
 var GbpTimeoutError = class extends GbpError {
   constructor(operation, timeoutMs) {
-    super(`${operation} timed out after ${timeoutMs}ms`);
+    super(`GBP ${operation} timed out`, "timeout", true, { operation, timeoutMs });
     this.operation = operation;
     this.timeoutMs = timeoutMs;
   }
@@ -81,7 +102,10 @@ var GbpTimeoutError = class extends GbpError {
 var GbpPaginationError = class extends GbpError {
   constructor(reason, pagesFetched) {
     super(
-      reason === "repeated_token" ? `Business Profile returned a page token it had already returned, after ${pagesFetched} page(s)` : `Business Profile reviews stopped at the page limit (${pagesFetched} pages)`
+      reason === "repeated_token" ? "GBP reviews.list returned a page token it had already returned" : "GBP reviews.list stopped at the page limit",
+      `pagination_${reason}`,
+      false,
+      { pagesFetched }
     );
     this.reason = reason;
     this.pagesFetched = pagesFetched;
@@ -92,8 +116,13 @@ function excerpt(text, max = 300) {
   return flat.length > max ? `${flat.slice(0, max)}...` : flat;
 }
 var GbpPublishedError = class extends GbpError {
-  constructor(reason, client, detail, status) {
-    super(`Published reviews for ${client} unusable (${reason}): ${detail}`);
+  constructor(reason, client, detail, status, body) {
+    const transient = reason === "http" && status !== void 0 && (status === 429 || status >= 500);
+    super(`Published reviews for ${client} unusable (${reason}): ${detail}`, `published_${reason}`, transient, {
+      client,
+      ...status !== void 0 ? { status } : {},
+      ...body ? { body } : {}
+    });
     this.reason = reason;
     this.client = client;
     this.status = status;
@@ -472,7 +501,8 @@ async function getPublishedReviews(options) {
   };
   const { response } = await fetchWithRetry(url, init, "reviews.published", resolvePolicy(request));
   if (!response.ok) {
-    throw new GbpPublishedError("http", client, `${response.status} ${excerpt(await readErrorBody(response), 120)}`.trim(), response.status);
+    const body2 = excerpt(await readErrorBody(response), 120);
+    throw new GbpPublishedError("http", client, String(response.status), response.status, body2 || void 0);
   }
   let body;
   try {
@@ -485,10 +515,129 @@ async function getPublishedReviews(options) {
   if (limit !== void 0) reviews = reviews.slice(0, limit);
   return { ...result, reviews: order === "shuffle" ? shuffle(reviews) : reviews };
 }
+
+// src/safe.ts
+var DEFAULT_REPORT_INTERVAL_MS = 60 * 60 * 1e3;
+var DEFAULT_MAX_STALE_MS = 30 * 24 * 60 * 60 * 1e3;
+var DEFAULT_AUTH_RETRY_MS = 5 * 60 * 1e3;
+var lastGood = /* @__PURE__ */ new Map();
+var reported = /* @__PURE__ */ new Map();
+var authBlockedUntil = /* @__PURE__ */ new Map();
+function toGbpError(error) {
+  if (error instanceof GbpError) return error;
+  const name = error instanceof Error ? error.name : typeof error;
+  const message = error instanceof Error ? error.message : String(error);
+  const wrapped = new GbpError("GBP reviews failed: unexpected error", "unexpected", true, { name, message: excerpt(message, 200) });
+  wrapped.cause = error;
+  return wrapped;
+}
+function isAuthFailure(error) {
+  return error.code === "invalid_grant" || error.code === "invalid_client";
+}
+function defaultReport(error, report) {
+  console.warn(`[gbp] ${error.message}; serving ${report.served}`, report.context);
+}
+async function loadFallback(fallback) {
+  if (fallback === void 0) return null;
+  try {
+    return (typeof fallback === "function" ? await fallback() : fallback) ?? null;
+  } catch {
+    return null;
+  }
+}
+function reportOnce(error, served, options) {
+  const now = Date.now();
+  const window = options.reportIntervalMs ?? DEFAULT_REPORT_INTERVAL_MS;
+  const last = reported.get(error.code);
+  if (last && now - last.at < window) {
+    last.suppressed++;
+    return;
+  }
+  reported.set(error.code, { at: now, suppressed: 0 });
+  try {
+    (options.report ?? defaultReport)(error, {
+      fingerprint: error.fingerprint,
+      code: error.code,
+      transient: error.transient,
+      context: error.context,
+      served,
+      suppressed: last?.suppressed ?? 0
+    });
+  } catch {
+  }
+}
+async function safely(key, load, empty, options) {
+  const now = Date.now();
+  let error;
+  const blocked = authBlockedUntil.get(key);
+  if (blocked && blocked.until > now) {
+    error = blocked.error;
+  } else {
+    try {
+      const result = await load();
+      lastGood.set(key, { result, at: Date.now() });
+      authBlockedUntil.delete(key);
+      return { ...result, source: "live" };
+    } catch (caught) {
+      error = toGbpError(caught);
+      const retryMs = options.authRetryMs ?? DEFAULT_AUTH_RETRY_MS;
+      if (isAuthFailure(error) && retryMs > 0) authBlockedUntil.set(key, { until: Date.now() + retryMs, error });
+    }
+  }
+  let cached2 = lastGood.get(key);
+  if (cached2 && now - cached2.at > (options.maxStaleMs ?? DEFAULT_MAX_STALE_MS)) {
+    lastGood.delete(key);
+    cached2 = void 0;
+  }
+  let served;
+  if (cached2) {
+    served = { ...cached2.result, reviews: [...cached2.result.reviews], source: "cache", error };
+  } else {
+    const fallback = await loadFallback(options.fallback);
+    served = fallback ? { ...fallback, source: "fallback", error } : { ...empty(), error };
+  }
+  reportOnce(error, served.source, options);
+  return served;
+}
+function getBusinessReviewsSafe(options = {}) {
+  const { fallback, report, reportIntervalMs, maxStaleMs, authRetryMs, ...fetchOptions } = options;
+  const key = JSON.stringify([
+    "business",
+    process.env.GOOGLE_BUSINESS_LOCATION_ID ?? null,
+    fetchOptions.limit ?? null,
+    fetchOptions.filterMinStars ?? null,
+    fetchOptions.includeUnapprovedReplies ?? false
+  ]);
+  return safely(
+    key,
+    () => getBusinessReviews(fetchOptions),
+    () => ({ averageRating: null, totalReviewCount: null, reviews: [], source: "empty" }),
+    { fallback, report, reportIntervalMs, maxStaleMs, authRetryMs }
+  );
+}
+function getPublishedReviewsSafe(options) {
+  const { fallback, report, reportIntervalMs, maxStaleMs, authRetryMs, ...fetchOptions } = options;
+  const key = JSON.stringify([
+    "published",
+    fetchOptions.client,
+    fetchOptions.baseUrl ?? process.env.GBP_REVIEWS_BASE_URL ?? null,
+    fetchOptions.limit ?? null,
+    fetchOptions.filterMinStars ?? null
+  ]);
+  return safely(
+    key,
+    () => getPublishedReviews(fetchOptions),
+    () => ({ averageRating: null, totalReviewCount: null, reviews: [], source: "empty" }),
+    { fallback, report, reportIntervalMs, maxStaleMs, authRetryMs }
+  );
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  DEFAULT_AUTH_RETRY_MS,
   DEFAULT_MAX_PAGES,
+  DEFAULT_MAX_STALE_MS,
   DEFAULT_PUBLISHED_REVIEWS_BASE_URL,
+  DEFAULT_REPORT_INTERVAL_MS,
   DEFAULT_REQUEST_POLICY,
   GbpApiError,
   GbpAuthError,
@@ -498,8 +647,10 @@ async function getPublishedReviews(options) {
   GbpTimeoutError,
   PUBLISHED_REVIEWS_SCHEMA,
   getBusinessReviews,
+  getBusinessReviewsSafe,
   getGoogleOAuthAccessToken,
   getPublishedReviews,
+  getPublishedReviewsSafe,
   hasGoogleOAuthCredentials,
   invalidateAccessToken,
   isBusinessProfileConfigured,

package/dist/index.d.cts

@@ -287,13 +287,27 @@ declare function getPublishedReviews(options: GetPublishedReviewsOptions): Promi
  * "Google is having a bad minute" from "our code looped", and log the
  * difference without ever logging a credential.
  *
- * No message here carries a client id, client secret, refresh token, access
- * token or review text. Bodies from Google are cut to a short, bounded
- * excerpt.
+ * Every message is short and stable: the same failure always reads the same,
+ * so an error tracker groups it as one issue rather than one per response
+ * body. What varies (status, Google's description, a body excerpt) sits in
+ * `context`, and `fingerprint` is `["gbp", code]` for a tracker that takes
+ * one (Sentry's `captureException(error, { fingerprint, extra: context })`).
+ *
+ * No message or context here carries a client id, client secret, refresh
+ * token, access token or review text. Bodies from Google are cut to a short,
+ * bounded excerpt.
  */
 /** Base class: `instanceof GbpError` catches every failure this package throws. */
 declare class GbpError extends Error {
-    constructor(message: string);
+    /** Short, stable name for the failure, e.g. `invalid_grant` or `api_5xx`. */
+    readonly code: string;
+    /** True when the same request may well work later without anyone changing anything. */
+    readonly transient: boolean;
+    /** What varies between occurrences: status, Google's description, a body excerpt. Never a credential. */
+    readonly context: Record<string, unknown>;
+    constructor(message: string, code?: string, transient?: boolean, context?: Record<string, unknown>);
+    /** `["gbp", code]`: one error-tracker issue per kind of failure. */
+    get fingerprint(): string[];
 }
 type GbpAuthErrorCode = "invalid_grant" | "invalid_client" | "token_request_failed";
 /**
@@ -319,6 +333,8 @@ declare class GbpApiError extends GbpError {
     readonly attempts: number;
     /** Set when Google asked for a longer wait than this package will sleep through. */
     readonly retryAfterMs?: number;
+    /** A short excerpt of Google's error body. In `context` too, never in the message. */
+    readonly body?: string;
     constructor(options: {
         operation: string;
         status: number;
@@ -354,7 +370,95 @@ declare class GbpPublishedError extends GbpError {
     readonly reason: "http" | "invalid" | "unknown_schema";
     readonly client: string;
     readonly status?: number;
-    constructor(reason: "http" | "invalid" | "unknown_schema", client: string, detail: string, status?: number);
+    constructor(reason: "http" | "invalid" | "unknown_schema", client: string, detail: string, status?: number, body?: string);
+}
+
+/**
+ * Reviews that never throw into a page render.
+ *
+ * `getBusinessReviews` and `getPublishedReviews` throw on a real failure, so a
+ * caller can choose what to do. Most callers want the same thing: keep showing
+ * what they showed last time, tell someone once, and carry on. A dead refresh
+ * token (`invalid_grant`, every 7 days while the OAuth app is in Testing) or a
+ * Google 503 otherwise reaches every server render, and a site that reports
+ * each one sends thousands of events about one fault.
+ *
+ * The `...Safe` functions here catch every failure and serve, in order:
+ *
+ *   1. the last good result this process fetched for the same options
+ *      (`source: "cache"`), up to `maxStaleMs` old;
+ *   2. the caller's `fallback`, a snapshot or a loader for one such as a KV
+ *      read (`source: "fallback"`);
+ *   3. an empty result: no rating, no count, no reviews (`source: "empty"`).
+ *
+ * Each kind of failure is reported at most once per `reportIntervalMs` per
+ * process, through `report`. After an auth failure no amount of retrying
+ * helps, so the live call is skipped for `authRetryMs` and the cache or
+ * fallback is served straight away.
+ */
+
+/** Where a safe result came from. */
+type ReviewsSource = "live" | "cache" | "fallback" | "empty";
+/** A result from a `...Safe` function: the reviews, where they came from, and the failure if there was one. */
+type SafeReviewsResult<T extends BusinessReviewsResult = BusinessReviewsResult> = T & {
+    source: ReviewsSource;
+    /** The failure behind a `cache`, `fallback` or `empty` result. */
+    error?: GbpError;
+};
+/** What `report` is told alongside the error. */
+interface GbpFailureReport {
+    /** `["gbp", code]`. Pass it to Sentry as `fingerprint` so every occurrence is one issue. */
+    fingerprint: string[];
+    code: string;
+    /** True when the failure may clear by itself (a 5xx, a timeout); false when a person has to act. */
+    transient: boolean;
+    /** Status, Google's description, a body excerpt. Never a credential. Pass it as Sentry `extra`. */
+    context: Record<string, unknown>;
+    /** What the page was given instead. */
+    served: Exclude<ReviewsSource, "live">;
+    /** Failures of this kind left unreported since the last report, because they fell inside the window. */
+    suppressed: number;
 }
+interface SafeReviewsOptions<F extends BusinessReviewsResult = BusinessReviewsResult> {
+    /**
+     * Served when there is no cached result: a snapshot, or a function that loads one (a KV read, say). A loader that
+     * throws or returns nothing falls through to an empty result. Served as given: `limit` and `filterMinStars` are
+     * not applied to it.
+     */
+    fallback?: F | (() => F | null | undefined | Promise<F | null | undefined>);
+    /**
+     * Called at most once per kind of failure per `reportIntervalMs`, per process. Default: one `console.warn`.
+     *
+     * ```ts
+     * report: (error, { fingerprint, context, transient }) =>
+     *   Sentry.captureException(error, { fingerprint, extra: context, level: transient ? "warning" : "error" }),
+     * ```
+     */
+    report?: (error: GbpError, report: GbpFailureReport) => void;
+    /** Default one hour. */
+    reportIntervalMs?: number;
+    /** Longest a cached result is served after the last good fetch. Default 30 days. */
+    maxStaleMs?: number;
+    /** After an auth failure, skip the live call for this long. Default five minutes. `0` turns it off. */
+    authRetryMs?: number;
+}
+declare const DEFAULT_REPORT_INTERVAL_MS: number;
+declare const DEFAULT_MAX_STALE_MS: number;
+declare const DEFAULT_AUTH_RETRY_MS: number;
+/**
+ * `getBusinessReviews`, but it never throws: on any failure it serves the last good result, the `fallback`, or an
+ * empty result, and reports the failure at most once per window. `source` says which.
+ */
+declare function getBusinessReviewsSafe(options?: GetBusinessReviewsOptions & SafeReviewsOptions): Promise<SafeReviewsResult>;
+/** A published result, or a fallback or empty one, which carries no sync times. */
+type SafePublishedReviewsResult = SafeReviewsResult<BusinessReviewsResult & Partial<Pick<PublishedReviewsResult, "syncedAt" | "publishedAt">>>;
+/**
+ * `getPublishedReviews`, but it never throws: on any failure it serves the last good result, the `fallback`, or an
+ * empty result, and reports the failure at most once per window. `source` says which.
+ *
+ * Where a framework keeps the last good page when a render throws (a static build that refuses to publish), the
+ * throwing `getPublishedReviews` keeps that behaviour; use this where a throw would reach the visitor.
+ */
+declare function getPublishedReviewsSafe(options: GetPublishedReviewsOptions & SafeReviewsOptions): Promise<SafePublishedReviewsResult>;
 
-export { type AccessTokenOptions, type BusinessReview, type BusinessReviewsResult, DEFAULT_MAX_PAGES, DEFAULT_PUBLISHED_REVIEWS_BASE_URL, DEFAULT_REQUEST_POLICY, GbpApiError, GbpAuthError, type GbpAuthErrorCode, GbpError, GbpPaginationError, GbpPublishedError, type GbpRequestOptions, GbpTimeoutError, type GetBusinessReviewsOptions, type GetPublishedReviewsOptions, PUBLISHED_REVIEWS_SCHEMA, type PublishedReviewsResult, type ReviewMedia, type ReviewOrder, type ReviewReply, type ReviewReplyState, getBusinessReviews, getGoogleOAuthAccessToken, getPublishedReviews, hasGoogleOAuthCredentials, invalidateAccessToken, isBusinessProfileConfigured, parseListReviewsResponse, parsePublishedReviews, parseRetryAfter, publishedReviewsUrl };
+export { type AccessTokenOptions, type BusinessReview, type BusinessReviewsResult, DEFAULT_AUTH_RETRY_MS, DEFAULT_MAX_PAGES, DEFAULT_MAX_STALE_MS, DEFAULT_PUBLISHED_REVIEWS_BASE_URL, DEFAULT_REPORT_INTERVAL_MS, DEFAULT_REQUEST_POLICY, GbpApiError, GbpAuthError, type GbpAuthErrorCode, GbpError, type GbpFailureReport, GbpPaginationError, GbpPublishedError, type GbpRequestOptions, GbpTimeoutError, type GetBusinessReviewsOptions, type GetPublishedReviewsOptions, PUBLISHED_REVIEWS_SCHEMA, type PublishedReviewsResult, type ReviewMedia, type ReviewOrder, type ReviewReply, type ReviewReplyState, type ReviewsSource, type SafePublishedReviewsResult, type SafeReviewsOptions, type SafeReviewsResult, getBusinessReviews, getBusinessReviewsSafe, getGoogleOAuthAccessToken, getPublishedReviews, getPublishedReviewsSafe, hasGoogleOAuthCredentials, invalidateAccessToken, isBusinessProfileConfigured, parseListReviewsResponse, parsePublishedReviews, parseRetryAfter, publishedReviewsUrl };

package/dist/index.d.ts

@@ -287,13 +287,27 @@ declare function getPublishedReviews(options: GetPublishedReviewsOptions): Promi
  * "Google is having a bad minute" from "our code looped", and log the
  * difference without ever logging a credential.
  *
- * No message here carries a client id, client secret, refresh token, access
- * token or review text. Bodies from Google are cut to a short, bounded
- * excerpt.
+ * Every message is short and stable: the same failure always reads the same,
+ * so an error tracker groups it as one issue rather than one per response
+ * body. What varies (status, Google's description, a body excerpt) sits in
+ * `context`, and `fingerprint` is `["gbp", code]` for a tracker that takes
+ * one (Sentry's `captureException(error, { fingerprint, extra: context })`).
+ *
+ * No message or context here carries a client id, client secret, refresh
+ * token, access token or review text. Bodies from Google are cut to a short,
+ * bounded excerpt.
  */
 /** Base class: `instanceof GbpError` catches every failure this package throws. */
 declare class GbpError extends Error {
-    constructor(message: string);
+    /** Short, stable name for the failure, e.g. `invalid_grant` or `api_5xx`. */
+    readonly code: string;
+    /** True when the same request may well work later without anyone changing anything. */
+    readonly transient: boolean;
+    /** What varies between occurrences: status, Google's description, a body excerpt. Never a credential. */
+    readonly context: Record<string, unknown>;
+    constructor(message: string, code?: string, transient?: boolean, context?: Record<string, unknown>);
+    /** `["gbp", code]`: one error-tracker issue per kind of failure. */
+    get fingerprint(): string[];
 }
 type GbpAuthErrorCode = "invalid_grant" | "invalid_client" | "token_request_failed";
 /**
@@ -319,6 +333,8 @@ declare class GbpApiError extends GbpError {
     readonly attempts: number;
     /** Set when Google asked for a longer wait than this package will sleep through. */
     readonly retryAfterMs?: number;
+    /** A short excerpt of Google's error body. In `context` too, never in the message. */
+    readonly body?: string;
     constructor(options: {
         operation: string;
         status: number;
@@ -354,7 +370,95 @@ declare class GbpPublishedError extends GbpError {
     readonly reason: "http" | "invalid" | "unknown_schema";
     readonly client: string;
     readonly status?: number;
-    constructor(reason: "http" | "invalid" | "unknown_schema", client: string, detail: string, status?: number);
+    constructor(reason: "http" | "invalid" | "unknown_schema", client: string, detail: string, status?: number, body?: string);
+}
+
+/**
+ * Reviews that never throw into a page render.
+ *
+ * `getBusinessReviews` and `getPublishedReviews` throw on a real failure, so a
+ * caller can choose what to do. Most callers want the same thing: keep showing
+ * what they showed last time, tell someone once, and carry on. A dead refresh
+ * token (`invalid_grant`, every 7 days while the OAuth app is in Testing) or a
+ * Google 503 otherwise reaches every server render, and a site that reports
+ * each one sends thousands of events about one fault.
+ *
+ * The `...Safe` functions here catch every failure and serve, in order:
+ *
+ *   1. the last good result this process fetched for the same options
+ *      (`source: "cache"`), up to `maxStaleMs` old;
+ *   2. the caller's `fallback`, a snapshot or a loader for one such as a KV
+ *      read (`source: "fallback"`);
+ *   3. an empty result: no rating, no count, no reviews (`source: "empty"`).
+ *
+ * Each kind of failure is reported at most once per `reportIntervalMs` per
+ * process, through `report`. After an auth failure no amount of retrying
+ * helps, so the live call is skipped for `authRetryMs` and the cache or
+ * fallback is served straight away.
+ */
+
+/** Where a safe result came from. */
+type ReviewsSource = "live" | "cache" | "fallback" | "empty";
+/** A result from a `...Safe` function: the reviews, where they came from, and the failure if there was one. */
+type SafeReviewsResult<T extends BusinessReviewsResult = BusinessReviewsResult> = T & {
+    source: ReviewsSource;
+    /** The failure behind a `cache`, `fallback` or `empty` result. */
+    error?: GbpError;
+};
+/** What `report` is told alongside the error. */
+interface GbpFailureReport {
+    /** `["gbp", code]`. Pass it to Sentry as `fingerprint` so every occurrence is one issue. */
+    fingerprint: string[];
+    code: string;
+    /** True when the failure may clear by itself (a 5xx, a timeout); false when a person has to act. */
+    transient: boolean;
+    /** Status, Google's description, a body excerpt. Never a credential. Pass it as Sentry `extra`. */
+    context: Record<string, unknown>;
+    /** What the page was given instead. */
+    served: Exclude<ReviewsSource, "live">;
+    /** Failures of this kind left unreported since the last report, because they fell inside the window. */
+    suppressed: number;
 }
+interface SafeReviewsOptions<F extends BusinessReviewsResult = BusinessReviewsResult> {
+    /**
+     * Served when there is no cached result: a snapshot, or a function that loads one (a KV read, say). A loader that
+     * throws or returns nothing falls through to an empty result. Served as given: `limit` and `filterMinStars` are
+     * not applied to it.
+     */
+    fallback?: F | (() => F | null | undefined | Promise<F | null | undefined>);
+    /**
+     * Called at most once per kind of failure per `reportIntervalMs`, per process. Default: one `console.warn`.
+     *
+     * ```ts
+     * report: (error, { fingerprint, context, transient }) =>
+     *   Sentry.captureException(error, { fingerprint, extra: context, level: transient ? "warning" : "error" }),
+     * ```
+     */
+    report?: (error: GbpError, report: GbpFailureReport) => void;
+    /** Default one hour. */
+    reportIntervalMs?: number;
+    /** Longest a cached result is served after the last good fetch. Default 30 days. */
+    maxStaleMs?: number;
+    /** After an auth failure, skip the live call for this long. Default five minutes. `0` turns it off. */
+    authRetryMs?: number;
+}
+declare const DEFAULT_REPORT_INTERVAL_MS: number;
+declare const DEFAULT_MAX_STALE_MS: number;
+declare const DEFAULT_AUTH_RETRY_MS: number;
+/**
+ * `getBusinessReviews`, but it never throws: on any failure it serves the last good result, the `fallback`, or an
+ * empty result, and reports the failure at most once per window. `source` says which.
+ */
+declare function getBusinessReviewsSafe(options?: GetBusinessReviewsOptions & SafeReviewsOptions): Promise<SafeReviewsResult>;
+/** A published result, or a fallback or empty one, which carries no sync times. */
+type SafePublishedReviewsResult = SafeReviewsResult<BusinessReviewsResult & Partial<Pick<PublishedReviewsResult, "syncedAt" | "publishedAt">>>;
+/**
+ * `getPublishedReviews`, but it never throws: on any failure it serves the last good result, the `fallback`, or an
+ * empty result, and reports the failure at most once per window. `source` says which.
+ *
+ * Where a framework keeps the last good page when a render throws (a static build that refuses to publish), the
+ * throwing `getPublishedReviews` keeps that behaviour; use this where a throw would reach the visitor.
+ */
+declare function getPublishedReviewsSafe(options: GetPublishedReviewsOptions & SafeReviewsOptions): Promise<SafePublishedReviewsResult>;
 
-export { type AccessTokenOptions, type BusinessReview, type BusinessReviewsResult, DEFAULT_MAX_PAGES, DEFAULT_PUBLISHED_REVIEWS_BASE_URL, DEFAULT_REQUEST_POLICY, GbpApiError, GbpAuthError, type GbpAuthErrorCode, GbpError, GbpPaginationError, GbpPublishedError, type GbpRequestOptions, GbpTimeoutError, type GetBusinessReviewsOptions, type GetPublishedReviewsOptions, PUBLISHED_REVIEWS_SCHEMA, type PublishedReviewsResult, type ReviewMedia, type ReviewOrder, type ReviewReply, type ReviewReplyState, getBusinessReviews, getGoogleOAuthAccessToken, getPublishedReviews, hasGoogleOAuthCredentials, invalidateAccessToken, isBusinessProfileConfigured, parseListReviewsResponse, parsePublishedReviews, parseRetryAfter, publishedReviewsUrl };
+export { type AccessTokenOptions, type BusinessReview, type BusinessReviewsResult, DEFAULT_AUTH_RETRY_MS, DEFAULT_MAX_PAGES, DEFAULT_MAX_STALE_MS, DEFAULT_PUBLISHED_REVIEWS_BASE_URL, DEFAULT_REPORT_INTERVAL_MS, DEFAULT_REQUEST_POLICY, GbpApiError, GbpAuthError, type GbpAuthErrorCode, GbpError, type GbpFailureReport, GbpPaginationError, GbpPublishedError, type GbpRequestOptions, GbpTimeoutError, type GetBusinessReviewsOptions, type GetPublishedReviewsOptions, PUBLISHED_REVIEWS_SCHEMA, type PublishedReviewsResult, type ReviewMedia, type ReviewOrder, type ReviewReply, type ReviewReplyState, type ReviewsSource, type SafePublishedReviewsResult, type SafeReviewsOptions, type SafeReviewsResult, getBusinessReviews, getBusinessReviewsSafe, getGoogleOAuthAccessToken, getPublishedReviews, getPublishedReviewsSafe, hasGoogleOAuthCredentials, invalidateAccessToken, isBusinessProfileConfigured, parseListReviewsResponse, parsePublishedReviews, parseRetryAfter, publishedReviewsUrl };

package/dist/index.js

@@ -1,16 +1,24 @@
 // src/errors.ts
 var GbpError = class extends Error {
-  constructor(message) {
+  constructor(message, code = "unknown", transient = false, context = {}) {
     super(message);
     this.name = new.target.name;
+    this.code = code;
+    this.transient = transient;
+    this.context = context;
+  }
+  /** `["gbp", code]`: one error-tracker issue per kind of failure. */
+  get fingerprint() {
+    return ["gbp", this.code];
   }
 };
 var GbpAuthError = class extends GbpError {
   constructor(code, status, description) {
-    super(
-      `Google OAuth token refresh failed: ${status} ${code}${description ? ` (${description})` : ""}` + (code === "invalid_grant" ? ". Reauthorise the Google account and replace GBP_REFRESH_TOKEN." : "")
-    );
-    this.code = code;
+    super(`GBP token refresh failed: ${code}`, code, code === "token_request_failed" && status >= 500, {
+      status,
+      ...description ? { description } : {},
+      ...code === "invalid_grant" ? { remedy: "Reauthorise the Google account and replace GBP_REFRESH_TOKEN." } : {}
+    });
     this.reauthorizationRequired = code === "invalid_grant";
     this.status = status;
     this.description = description;
@@ -18,7 +26,15 @@ var GbpAuthError = class extends GbpError {
 };
 var GbpApiError = class extends GbpError {
   constructor(options) {
-    super(`Business Profile reviews failed: ${options.status}${options.body ? ` ${options.body}` : ""}`);
+    const server = options.status >= 500;
+    super(`GBP ${options.operation} failed: ${server ? "5xx" : options.status}`, server ? "api_5xx" : `api_${options.status}`, options.retryable, {
+      operation: options.operation,
+      status: options.status,
+      attempts: options.attempts,
+      ...options.body ? { body: options.body } : {},
+      ...options.retryAfterMs !== void 0 ? { retryAfterMs: options.retryAfterMs } : {}
+    });
+    this.body = options.body;
     this.operation = options.operation;
     this.status = options.status;
     this.retryable = options.retryable;
@@ -28,7 +44,7 @@ var GbpApiError = class extends GbpError {
 };
 var GbpTimeoutError = class extends GbpError {
   constructor(operation, timeoutMs) {
-    super(`${operation} timed out after ${timeoutMs}ms`);
+    super(`GBP ${operation} timed out`, "timeout", true, { operation, timeoutMs });
     this.operation = operation;
     this.timeoutMs = timeoutMs;
   }
@@ -36,7 +52,10 @@ var GbpTimeoutError = class extends GbpError {
 var GbpPaginationError = class extends GbpError {
   constructor(reason, pagesFetched) {
     super(
-      reason === "repeated_token" ? `Business Profile returned a page token it had already returned, after ${pagesFetched} page(s)` : `Business Profile reviews stopped at the page limit (${pagesFetched} pages)`
+      reason === "repeated_token" ? "GBP reviews.list returned a page token it had already returned" : "GBP reviews.list stopped at the page limit",
+      `pagination_${reason}`,
+      false,
+      { pagesFetched }
     );
     this.reason = reason;
     this.pagesFetched = pagesFetched;
@@ -47,8 +66,13 @@ function excerpt(text, max = 300) {
   return flat.length > max ? `${flat.slice(0, max)}...` : flat;
 }
 var GbpPublishedError = class extends GbpError {
-  constructor(reason, client, detail, status) {
-    super(`Published reviews for ${client} unusable (${reason}): ${detail}`);
+  constructor(reason, client, detail, status, body) {
+    const transient = reason === "http" && status !== void 0 && (status === 429 || status >= 500);
+    super(`Published reviews for ${client} unusable (${reason}): ${detail}`, `published_${reason}`, transient, {
+      client,
+      ...status !== void 0 ? { status } : {},
+      ...body ? { body } : {}
+    });
     this.reason = reason;
     this.client = client;
     this.status = status;
@@ -427,7 +451,8 @@ async function getPublishedReviews(options) {
   };
   const { response } = await fetchWithRetry(url, init, "reviews.published", resolvePolicy(request));
   if (!response.ok) {
-    throw new GbpPublishedError("http", client, `${response.status} ${excerpt(await readErrorBody(response), 120)}`.trim(), response.status);
+    const body2 = excerpt(await readErrorBody(response), 120);
+    throw new GbpPublishedError("http", client, String(response.status), response.status, body2 || void 0);
   }
   let body;
   try {
@@ -440,9 +465,128 @@ async function getPublishedReviews(options) {
   if (limit !== void 0) reviews = reviews.slice(0, limit);
   return { ...result, reviews: order === "shuffle" ? shuffle(reviews) : reviews };
 }
+
+// src/safe.ts
+var DEFAULT_REPORT_INTERVAL_MS = 60 * 60 * 1e3;
+var DEFAULT_MAX_STALE_MS = 30 * 24 * 60 * 60 * 1e3;
+var DEFAULT_AUTH_RETRY_MS = 5 * 60 * 1e3;
+var lastGood = /* @__PURE__ */ new Map();
+var reported = /* @__PURE__ */ new Map();
+var authBlockedUntil = /* @__PURE__ */ new Map();
+function toGbpError(error) {
+  if (error instanceof GbpError) return error;
+  const name = error instanceof Error ? error.name : typeof error;
+  const message = error instanceof Error ? error.message : String(error);
+  const wrapped = new GbpError("GBP reviews failed: unexpected error", "unexpected", true, { name, message: excerpt(message, 200) });
+  wrapped.cause = error;
+  return wrapped;
+}
+function isAuthFailure(error) {
+  return error.code === "invalid_grant" || error.code === "invalid_client";
+}
+function defaultReport(error, report) {
+  console.warn(`[gbp] ${error.message}; serving ${report.served}`, report.context);
+}
+async function loadFallback(fallback) {
+  if (fallback === void 0) return null;
+  try {
+    return (typeof fallback === "function" ? await fallback() : fallback) ?? null;
+  } catch {
+    return null;
+  }
+}
+function reportOnce(error, served, options) {
+  const now = Date.now();
+  const window = options.reportIntervalMs ?? DEFAULT_REPORT_INTERVAL_MS;
+  const last = reported.get(error.code);
+  if (last && now - last.at < window) {
+    last.suppressed++;
+    return;
+  }
+  reported.set(error.code, { at: now, suppressed: 0 });
+  try {
+    (options.report ?? defaultReport)(error, {
+      fingerprint: error.fingerprint,
+      code: error.code,
+      transient: error.transient,
+      context: error.context,
+      served,
+      suppressed: last?.suppressed ?? 0
+    });
+  } catch {
+  }
+}
+async function safely(key, load, empty, options) {
+  const now = Date.now();
+  let error;
+  const blocked = authBlockedUntil.get(key);
+  if (blocked && blocked.until > now) {
+    error = blocked.error;
+  } else {
+    try {
+      const result = await load();
+      lastGood.set(key, { result, at: Date.now() });
+      authBlockedUntil.delete(key);
+      return { ...result, source: "live" };
+    } catch (caught) {
+      error = toGbpError(caught);
+      const retryMs = options.authRetryMs ?? DEFAULT_AUTH_RETRY_MS;
+      if (isAuthFailure(error) && retryMs > 0) authBlockedUntil.set(key, { until: Date.now() + retryMs, error });
+    }
+  }
+  let cached2 = lastGood.get(key);
+  if (cached2 && now - cached2.at > (options.maxStaleMs ?? DEFAULT_MAX_STALE_MS)) {
+    lastGood.delete(key);
+    cached2 = void 0;
+  }
+  let served;
+  if (cached2) {
+    served = { ...cached2.result, reviews: [...cached2.result.reviews], source: "cache", error };
+  } else {
+    const fallback = await loadFallback(options.fallback);
+    served = fallback ? { ...fallback, source: "fallback", error } : { ...empty(), error };
+  }
+  reportOnce(error, served.source, options);
+  return served;
+}
+function getBusinessReviewsSafe(options = {}) {
+  const { fallback, report, reportIntervalMs, maxStaleMs, authRetryMs, ...fetchOptions } = options;
+  const key = JSON.stringify([
+    "business",
+    process.env.GOOGLE_BUSINESS_LOCATION_ID ?? null,
+    fetchOptions.limit ?? null,
+    fetchOptions.filterMinStars ?? null,
+    fetchOptions.includeUnapprovedReplies ?? false
+  ]);
+  return safely(
+    key,
+    () => getBusinessReviews(fetchOptions),
+    () => ({ averageRating: null, totalReviewCount: null, reviews: [], source: "empty" }),
+    { fallback, report, reportIntervalMs, maxStaleMs, authRetryMs }
+  );
+}
+function getPublishedReviewsSafe(options) {
+  const { fallback, report, reportIntervalMs, maxStaleMs, authRetryMs, ...fetchOptions } = options;
+  const key = JSON.stringify([
+    "published",
+    fetchOptions.client,
+    fetchOptions.baseUrl ?? process.env.GBP_REVIEWS_BASE_URL ?? null,
+    fetchOptions.limit ?? null,
+    fetchOptions.filterMinStars ?? null
+  ]);
+  return safely(
+    key,
+    () => getPublishedReviews(fetchOptions),
+    () => ({ averageRating: null, totalReviewCount: null, reviews: [], source: "empty" }),
+    { fallback, report, reportIntervalMs, maxStaleMs, authRetryMs }
+  );
+}
 export {
+  DEFAULT_AUTH_RETRY_MS,
   DEFAULT_MAX_PAGES,
+  DEFAULT_MAX_STALE_MS,
   DEFAULT_PUBLISHED_REVIEWS_BASE_URL,
+  DEFAULT_REPORT_INTERVAL_MS,
   DEFAULT_REQUEST_POLICY,
   GbpApiError,
   GbpAuthError,
@@ -452,8 +596,10 @@ export {
   GbpTimeoutError,
   PUBLISHED_REVIEWS_SCHEMA,
   getBusinessReviews,
+  getBusinessReviewsSafe,
   getGoogleOAuthAccessToken,
   getPublishedReviews,
+  getPublishedReviewsSafe,
   hasGoogleOAuthCredentials,
   invalidateAccessToken,
   isBusinessProfileConfigured,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@domandigital/gbp",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "private": false,
   "description": "Zero-dependency Google Business Profile client: OAuth refresh-token auth and a reviews (with owner replies) fetch, shared across Doman Digital / IDS client sites.",
   "license": "Apache-2.0",