@domandigital/gbp 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # 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
+
+- 4588886: Read reviews from the file Doman Digital publishes, so a site needs no Google token.
+  
+  - **`getPublishedReviews({ client })`** fetches `https://files.domandigital.co.uk/reviews/<client>.json` (override with `baseUrl` or `GBP_REVIEWS_BASE_URL`). One collector reads every listing with the only Google credential and the portal publishes the file each night, so a dead token makes reviews stale, not missing.
+  - Same shape as `getBusinessReviews`: Google's own `averageRating` and `totalReviewCount` for the whole listing, plus `reviews` (four and five stars with words, replies Google shows). Adds `syncedAt`, when Google was last read.
+  - Throws `GbpPublishedError` (`http`, `invalid`, `unknown_schema`) instead of returning an empty result, so the caller keeps the copy it already has. Retries 429 and transient 5xx within the usual deadline.
+  - Defaults to newest first (`order: "api"`) and a daily Next.js revalidate tagged `google-reviews`.
+
 ## 0.4.0
 
 ### Minor Changes

package/README.md

@@ -61,6 +61,35 @@ remove such markup and "You won't get a manual action just for this"
 Showing the reviews on the page is unaffected. Just do not sell or expect the
 stars. `@domandigital/graph`'s `findGraphIssues` can flag the pattern.
 
+## Reading the published file (no Google token on the site)
+
+Client sites should read reviews from the file Doman Digital publishes rather
+than from Google. One collector holds the only Google credential, the portal
+stores what it reads, and each night it writes
+`https://files.domandigital.co.uk/reviews/<client-slug>.json`:
+
+```ts
+import { getPublishedReviews } from "@domandigital/gbp";
+
+// Throws when the file is missing or malformed: keep the copy you already have.
+const { averageRating, totalReviewCount, reviews, syncedAt } = await getPublishedReviews({
+  client: "chair-and-blade",
+});
+```
+
+The result has the same shape as `getBusinessReviews`, plus `syncedAt`. The
+file already holds only what a site shows (four and five stars, with words,
+and owner replies Google shows); `filterMinStars` can only raise that floor.
+
+It throws `GbpPublishedError` instead of returning an empty result. Catch it
+where the site has an older copy to fall back to (a Next.js fetch keeps its
+last good response; a static build should refuse to publish and leave the
+last deploy live), and render no rating, count or review section when there
+is no copy at all. Never fall back to a hardcoded number.
+
+A site that reads this file needs none of the `GBP_*` or `GOOGLE_BUSINESS_*`
+variables below.
+
 ## Why Business Profile API, not Places API
 
 Places API's `Review` object has no field for the business's reply, full
@@ -198,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
 
@@ -208,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,36 +20,55 @@ 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,
   GbpError: () => GbpError,
   GbpPaginationError: () => GbpPaginationError,
+  GbpPublishedError: () => GbpPublishedError,
   GbpTimeoutError: () => GbpTimeoutError,
+  PUBLISHED_REVIEWS_SCHEMA: () => PUBLISHED_REVIEWS_SCHEMA,
   getBusinessReviews: () => getBusinessReviews,
+  getBusinessReviewsSafe: () => getBusinessReviewsSafe,
   getGoogleOAuthAccessToken: () => getGoogleOAuthAccessToken,
+  getPublishedReviews: () => getPublishedReviews,
+  getPublishedReviewsSafe: () => getPublishedReviewsSafe,
   hasGoogleOAuthCredentials: () => hasGoogleOAuthCredentials,
   invalidateAccessToken: () => invalidateAccessToken,
   isBusinessProfileConfigured: () => isBusinessProfileConfigured,
   parseListReviewsResponse: () => parseListReviewsResponse,
-  parseRetryAfter: () => parseRetryAfter
+  parsePublishedReviews: () => parsePublishedReviews,
+  parseRetryAfter: () => parseRetryAfter,
+  publishedReviewsUrl: () => publishedReviewsUrl
 });
 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;
@@ -57,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;
@@ -67,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;
   }
@@ -75,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;
@@ -85,6 +115,19 @@ function excerpt(text, max = 300) {
   const flat = text.replace(/\s+/g, " ").trim();
   return flat.length > max ? `${flat.slice(0, max)}...` : flat;
 }
+var GbpPublishedError = class extends GbpError {
+  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;
+  }
+};
 
 // src/http.ts
 var DEFAULT_REQUEST_POLICY = {
@@ -395,20 +438,224 @@ async function getBusinessReviews(options = {}) {
     reviews: order === "api" ? reviews : shuffleArray(reviews)
   };
 }
+
+// src/published.ts
+var DEFAULT_PUBLISHED_REVIEWS_BASE_URL = "https://files.domandigital.co.uk/reviews";
+var PUBLISHED_REVIEWS_SCHEMA = 1;
+var isRecord2 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var isTime = (v) => typeof v === "string" && !Number.isNaN(Date.parse(v));
+function parseReview2(v) {
+  if (!isRecord2(v)) return null;
+  const { id, author, rating, comment, createdAt, reply } = v;
+  if (typeof id !== "string" || typeof author !== "string" || typeof comment !== "string" || !comment) return null;
+  if (typeof rating !== "number" || !Number.isInteger(rating) || rating < 1 || rating > 5) return null;
+  const review = { id, author, rating, comment, createdAt: isTime(createdAt) ? createdAt : "" };
+  if (isRecord2(reply) && typeof reply.text === "string" && reply.text) {
+    review.reply = { text: reply.text, updatedAt: isTime(reply.updatedAt) ? reply.updatedAt : "" };
+  }
+  return review;
+}
+function parsePublishedReviews(body, client) {
+  if (!isRecord2(body)) throw new GbpPublishedError("invalid", client, "the file is not an object");
+  if (body.schema !== PUBLISHED_REVIEWS_SCHEMA) {
+    throw new GbpPublishedError("unknown_schema", client, `schema ${String(body.schema)}`);
+  }
+  if (body.client !== client) throw new GbpPublishedError("invalid", client, `the file is for ${String(body.client)}`);
+  const { rating, count } = body;
+  if (rating !== null && (typeof rating !== "number" || !(rating >= 0 && rating <= 5))) {
+    throw new GbpPublishedError("invalid", client, "rating out of range");
+  }
+  if (count !== null && (typeof count !== "number" || !Number.isInteger(count) || count < 0)) {
+    throw new GbpPublishedError("invalid", client, "count is not a whole number");
+  }
+  if (!isTime(body.synced_at) || !isTime(body.published_at) || !Array.isArray(body.reviews)) {
+    throw new GbpPublishedError("invalid", client, "synced_at, published_at or reviews missing");
+  }
+  return {
+    averageRating: rating,
+    totalReviewCount: count,
+    reviews: body.reviews.map(parseReview2).filter((r) => r !== null),
+    syncedAt: body.synced_at,
+    publishedAt: body.published_at
+  };
+}
+function shuffle(arr) {
+  const copy = [...arr];
+  for (let i = copy.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    [copy[i], copy[j]] = [copy[j], copy[i]];
+  }
+  return copy;
+}
+function publishedReviewsUrl(client, baseUrl) {
+  if (!/^[a-z0-9][a-z0-9-]{0,99}$/.test(client)) throw new RangeError(`not a client slug: ${client}`);
+  const base = (baseUrl ?? process.env.GBP_REVIEWS_BASE_URL ?? DEFAULT_PUBLISHED_REVIEWS_BASE_URL).replace(/\/+$/, "");
+  return `${base}/${client}.json`;
+}
+async function getPublishedReviews(options) {
+  const { client, filterMinStars, limit, order = "api", next, request } = options;
+  const url = publishedReviewsUrl(client, options.baseUrl);
+  const init = {
+    headers: { Accept: "application/json" },
+    next: next ?? { revalidate: 86400, tags: ["google-reviews"] }
+  };
+  const { response } = await fetchWithRetry(url, init, "reviews.published", resolvePolicy(request));
+  if (!response.ok) {
+    const body2 = excerpt(await readErrorBody(response), 120);
+    throw new GbpPublishedError("http", client, String(response.status), response.status, body2 || void 0);
+  }
+  let body;
+  try {
+    body = await response.json();
+  } catch {
+    throw new GbpPublishedError("invalid", client, "the file is not JSON");
+  }
+  const result = parsePublishedReviews(body, client);
+  let reviews = filterMinStars === void 0 ? result.reviews : result.reviews.filter((r) => r.rating >= filterMinStars);
+  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,
   GbpError,
   GbpPaginationError,
+  GbpPublishedError,
   GbpTimeoutError,
+  PUBLISHED_REVIEWS_SCHEMA,
   getBusinessReviews,
+  getBusinessReviewsSafe,
   getGoogleOAuthAccessToken,
+  getPublishedReviews,
+  getPublishedReviewsSafe,
   hasGoogleOAuthCredentials,
   invalidateAccessToken,
   isBusinessProfileConfigured,
   parseListReviewsResponse,
-  parseRetryAfter
+  parsePublishedReviews,
+  parseRetryAfter,
+  publishedReviewsUrl
 });

package/dist/index.d.cts

@@ -240,18 +240,74 @@ declare function parseListReviewsResponse(body: unknown): ReviewsPage;
  */
 declare function getBusinessReviews(options?: GetBusinessReviewsOptions): Promise<BusinessReviewsResult>;
 
+/** Where Doman Digital's portal publishes review files. */
+declare const DEFAULT_PUBLISHED_REVIEWS_BASE_URL = "https://files.domandigital.co.uk/reviews";
+/** The file schema this reader understands. A newer file is refused rather than misread. */
+declare const PUBLISHED_REVIEWS_SCHEMA = 1;
+interface GetPublishedReviewsOptions {
+    /** The client's slug, e.g. `"chair-and-blade"`. */
+    client: string;
+    /** Default: `GBP_REVIEWS_BASE_URL` from the environment, else {@link DEFAULT_PUBLISHED_REVIEWS_BASE_URL}. */
+    baseUrl?: string;
+    /** Raise the published floor (four stars). Values at or below four change nothing. */
+    filterMinStars?: number;
+    /** Max reviews to return. Default: all of them. */
+    limit?: number;
+    /** `"api"` (default): newest first, as published. `"shuffle"`: random order, applied after `limit`. */
+    order?: ReviewOrder;
+    /** Cache hint passed to `fetch` for Next.js. Default: revalidate daily, tag `google-reviews`. */
+    next?: {
+        revalidate?: number;
+        tags?: string[];
+    };
+    /** Deadline and retry policy. */
+    request?: GbpRequestOptions;
+}
+interface PublishedReviewsResult extends BusinessReviewsResult {
+    /** When the collector last read Google in full. */
+    syncedAt: string;
+    /** When the file was written. */
+    publishedAt: string;
+}
+/**
+ * Validate a published file. A malformed review is skipped; a malformed file, a file for another client or a schema
+ * this reader does not know throws {@link GbpPublishedError}.
+ */
+declare function parsePublishedReviews(body: unknown, client: string): PublishedReviewsResult;
+/** The URL a client's file is read from. */
+declare function publishedReviewsUrl(client: string, baseUrl?: string): string;
+/**
+ * Fetch a client's published reviews. Retries 429 and transient 5xx within a deadline (see `request`), then throws:
+ * {@link GbpPublishedError} for a missing or malformed file, `GbpTimeoutError` for a deadline.
+ */
+declare function getPublishedReviews(options: GetPublishedReviewsOptions): Promise<PublishedReviewsResult>;
+
 /**
  * Typed failures, so a site can tell "reauthorise the Google account" from
  * "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";
 /**
@@ -277,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;
@@ -303,5 +361,104 @@ declare class GbpPaginationError extends GbpError {
     readonly pagesFetched: number;
     constructor(reason: "repeated_token" | "page_limit", pagesFetched: number);
 }
+/**
+ * A published reviews file could not be used: the address answered an error (`http`, with `status`), the file was
+ * malformed or for another client (`invalid`), or it uses a schema this version does not read (`unknown_schema`,
+ * upgrade the package). The caller keeps the copy it already has.
+ */
+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, 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_REQUEST_POLICY, GbpApiError, GbpAuthError, type GbpAuthErrorCode, GbpError, GbpPaginationError, type GbpRequestOptions, GbpTimeoutError, type GetBusinessReviewsOptions, type ReviewMedia, type ReviewOrder, type ReviewReply, type ReviewReplyState, getBusinessReviews, getGoogleOAuthAccessToken, hasGoogleOAuthCredentials, invalidateAccessToken, isBusinessProfileConfigured, parseListReviewsResponse, parseRetryAfter };
+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

@@ -240,18 +240,74 @@ declare function parseListReviewsResponse(body: unknown): ReviewsPage;
  */
 declare function getBusinessReviews(options?: GetBusinessReviewsOptions): Promise<BusinessReviewsResult>;
 
+/** Where Doman Digital's portal publishes review files. */
+declare const DEFAULT_PUBLISHED_REVIEWS_BASE_URL = "https://files.domandigital.co.uk/reviews";
+/** The file schema this reader understands. A newer file is refused rather than misread. */
+declare const PUBLISHED_REVIEWS_SCHEMA = 1;
+interface GetPublishedReviewsOptions {
+    /** The client's slug, e.g. `"chair-and-blade"`. */
+    client: string;
+    /** Default: `GBP_REVIEWS_BASE_URL` from the environment, else {@link DEFAULT_PUBLISHED_REVIEWS_BASE_URL}. */
+    baseUrl?: string;
+    /** Raise the published floor (four stars). Values at or below four change nothing. */
+    filterMinStars?: number;
+    /** Max reviews to return. Default: all of them. */
+    limit?: number;
+    /** `"api"` (default): newest first, as published. `"shuffle"`: random order, applied after `limit`. */
+    order?: ReviewOrder;
+    /** Cache hint passed to `fetch` for Next.js. Default: revalidate daily, tag `google-reviews`. */
+    next?: {
+        revalidate?: number;
+        tags?: string[];
+    };
+    /** Deadline and retry policy. */
+    request?: GbpRequestOptions;
+}
+interface PublishedReviewsResult extends BusinessReviewsResult {
+    /** When the collector last read Google in full. */
+    syncedAt: string;
+    /** When the file was written. */
+    publishedAt: string;
+}
+/**
+ * Validate a published file. A malformed review is skipped; a malformed file, a file for another client or a schema
+ * this reader does not know throws {@link GbpPublishedError}.
+ */
+declare function parsePublishedReviews(body: unknown, client: string): PublishedReviewsResult;
+/** The URL a client's file is read from. */
+declare function publishedReviewsUrl(client: string, baseUrl?: string): string;
+/**
+ * Fetch a client's published reviews. Retries 429 and transient 5xx within a deadline (see `request`), then throws:
+ * {@link GbpPublishedError} for a missing or malformed file, `GbpTimeoutError` for a deadline.
+ */
+declare function getPublishedReviews(options: GetPublishedReviewsOptions): Promise<PublishedReviewsResult>;
+
 /**
  * Typed failures, so a site can tell "reauthorise the Google account" from
  * "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";
 /**
@@ -277,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;
@@ -303,5 +361,104 @@ declare class GbpPaginationError extends GbpError {
     readonly pagesFetched: number;
     constructor(reason: "repeated_token" | "page_limit", pagesFetched: number);
 }
+/**
+ * A published reviews file could not be used: the address answered an error (`http`, with `status`), the file was
+ * malformed or for another client (`invalid`), or it uses a schema this version does not read (`unknown_schema`,
+ * upgrade the package). The caller keeps the copy it already has.
+ */
+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, 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_REQUEST_POLICY, GbpApiError, GbpAuthError, type GbpAuthErrorCode, GbpError, GbpPaginationError, type GbpRequestOptions, GbpTimeoutError, type GetBusinessReviewsOptions, type ReviewMedia, type ReviewOrder, type ReviewReply, type ReviewReplyState, getBusinessReviews, getGoogleOAuthAccessToken, hasGoogleOAuthCredentials, invalidateAccessToken, isBusinessProfileConfigured, parseListReviewsResponse, parseRetryAfter };
+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;
@@ -46,6 +65,19 @@ function excerpt(text, max = 300) {
   const flat = text.replace(/\s+/g, " ").trim();
   return flat.length > max ? `${flat.slice(0, max)}...` : flat;
 }
+var GbpPublishedError = class extends GbpError {
+  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;
+  }
+};
 
 // src/http.ts
 var DEFAULT_REQUEST_POLICY = {
@@ -356,19 +388,223 @@ async function getBusinessReviews(options = {}) {
     reviews: order === "api" ? reviews : shuffleArray(reviews)
   };
 }
+
+// src/published.ts
+var DEFAULT_PUBLISHED_REVIEWS_BASE_URL = "https://files.domandigital.co.uk/reviews";
+var PUBLISHED_REVIEWS_SCHEMA = 1;
+var isRecord2 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var isTime = (v) => typeof v === "string" && !Number.isNaN(Date.parse(v));
+function parseReview2(v) {
+  if (!isRecord2(v)) return null;
+  const { id, author, rating, comment, createdAt, reply } = v;
+  if (typeof id !== "string" || typeof author !== "string" || typeof comment !== "string" || !comment) return null;
+  if (typeof rating !== "number" || !Number.isInteger(rating) || rating < 1 || rating > 5) return null;
+  const review = { id, author, rating, comment, createdAt: isTime(createdAt) ? createdAt : "" };
+  if (isRecord2(reply) && typeof reply.text === "string" && reply.text) {
+    review.reply = { text: reply.text, updatedAt: isTime(reply.updatedAt) ? reply.updatedAt : "" };
+  }
+  return review;
+}
+function parsePublishedReviews(body, client) {
+  if (!isRecord2(body)) throw new GbpPublishedError("invalid", client, "the file is not an object");
+  if (body.schema !== PUBLISHED_REVIEWS_SCHEMA) {
+    throw new GbpPublishedError("unknown_schema", client, `schema ${String(body.schema)}`);
+  }
+  if (body.client !== client) throw new GbpPublishedError("invalid", client, `the file is for ${String(body.client)}`);
+  const { rating, count } = body;
+  if (rating !== null && (typeof rating !== "number" || !(rating >= 0 && rating <= 5))) {
+    throw new GbpPublishedError("invalid", client, "rating out of range");
+  }
+  if (count !== null && (typeof count !== "number" || !Number.isInteger(count) || count < 0)) {
+    throw new GbpPublishedError("invalid", client, "count is not a whole number");
+  }
+  if (!isTime(body.synced_at) || !isTime(body.published_at) || !Array.isArray(body.reviews)) {
+    throw new GbpPublishedError("invalid", client, "synced_at, published_at or reviews missing");
+  }
+  return {
+    averageRating: rating,
+    totalReviewCount: count,
+    reviews: body.reviews.map(parseReview2).filter((r) => r !== null),
+    syncedAt: body.synced_at,
+    publishedAt: body.published_at
+  };
+}
+function shuffle(arr) {
+  const copy = [...arr];
+  for (let i = copy.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    [copy[i], copy[j]] = [copy[j], copy[i]];
+  }
+  return copy;
+}
+function publishedReviewsUrl(client, baseUrl) {
+  if (!/^[a-z0-9][a-z0-9-]{0,99}$/.test(client)) throw new RangeError(`not a client slug: ${client}`);
+  const base = (baseUrl ?? process.env.GBP_REVIEWS_BASE_URL ?? DEFAULT_PUBLISHED_REVIEWS_BASE_URL).replace(/\/+$/, "");
+  return `${base}/${client}.json`;
+}
+async function getPublishedReviews(options) {
+  const { client, filterMinStars, limit, order = "api", next, request } = options;
+  const url = publishedReviewsUrl(client, options.baseUrl);
+  const init = {
+    headers: { Accept: "application/json" },
+    next: next ?? { revalidate: 86400, tags: ["google-reviews"] }
+  };
+  const { response } = await fetchWithRetry(url, init, "reviews.published", resolvePolicy(request));
+  if (!response.ok) {
+    const body2 = excerpt(await readErrorBody(response), 120);
+    throw new GbpPublishedError("http", client, String(response.status), response.status, body2 || void 0);
+  }
+  let body;
+  try {
+    body = await response.json();
+  } catch {
+    throw new GbpPublishedError("invalid", client, "the file is not JSON");
+  }
+  const result = parsePublishedReviews(body, client);
+  let reviews = filterMinStars === void 0 ? result.reviews : result.reviews.filter((r) => r.rating >= filterMinStars);
+  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,
   GbpError,
   GbpPaginationError,
+  GbpPublishedError,
   GbpTimeoutError,
+  PUBLISHED_REVIEWS_SCHEMA,
   getBusinessReviews,
+  getBusinessReviewsSafe,
   getGoogleOAuthAccessToken,
+  getPublishedReviews,
+  getPublishedReviewsSafe,
   hasGoogleOAuthCredentials,
   invalidateAccessToken,
   isBusinessProfileConfigured,
   parseListReviewsResponse,
-  parseRetryAfter
+  parsePublishedReviews,
+  parseRetryAfter,
+  publishedReviewsUrl
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@domandigital/gbp",
-  "version": "0.4.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",
@@ -32,7 +32,7 @@
     "@types/node": "^20",
     "tsup": "^8.3.5",
     "typescript": "^5.6.3",
-    "vitest": "^2.1.9"
+    "vitest": "^4.0.0"
   },
   "engines": {
     "node": ">=22.12"