@domandigital/gbp 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.7.0
+
+### Minor Changes
+
+- 59e6d85: Read a client's Facebook Page recommendations from the file Doman Digital publishes, so a site needs no Meta token.
+  
+  - **`getPublishedFacebookRecommendations({ client })`** fetches `https://files.domandigital.co.uk/reviews/<client>.facebook.json`, which the portal writes daily from the Page token it already holds.
+  - Returns Meta's own `rating` (null when Meta gives none), `count` (every recommendation), `recommends` (the positive ones) and `reviews`: positive recommendations with words, with `id`, `comment` and `createdAt`. There is no author, because Meta does not return one.
+  - Throws `GbpPublishedError` like `getPublishedReviews`, so the caller keeps its last good copy. Refuses the Google file, another client's file and a count that does not add up.
+
+## 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

@@ -90,6 +90,25 @@ 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.
 
+### Facebook recommendations
+
+The portal also publishes each client's Facebook Page recommendations beside
+the Google file, at `<client-slug>.facebook.json`:
+
+```ts
+import { getPublishedFacebookRecommendations } from "@domandigital/gbp";
+
+const { rating, count, recommends, reviews } = await getPublishedFacebookRecommendations({
+  client: "rmp-electrical",
+});
+```
+
+Facebook has recommendations, not star reviews. `count` is every
+recommendation on the Page, `recommends` the positive ones, and `rating` is
+Meta's own overall figure (null when Meta gives none). `reviews` holds the
+positive recommendations that have words. There is no author, because Meta
+does not return one. It throws on failure like `getPublishedReviews`.
+
 ## Why Business Profile API, not Places API
 
 Places API's `Review` object has no field for the business's reply, full
@@ -227,7 +246,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 +294,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,31 +34,44 @@ __export(index_exports, {
   GbpTimeoutError: () => GbpTimeoutError,
   PUBLISHED_REVIEWS_SCHEMA: () => PUBLISHED_REVIEWS_SCHEMA,
   getBusinessReviews: () => getBusinessReviews,
+  getBusinessReviewsSafe: () => getBusinessReviewsSafe,
   getGoogleOAuthAccessToken: () => getGoogleOAuthAccessToken,
+  getPublishedFacebookRecommendations: () => getPublishedFacebookRecommendations,
   getPublishedReviews: () => getPublishedReviews,
+  getPublishedReviewsSafe: () => getPublishedReviewsSafe,
   hasGoogleOAuthCredentials: () => hasGoogleOAuthCredentials,
   invalidateAccessToken: () => invalidateAccessToken,
   isBusinessProfileConfigured: () => isBusinessProfileConfigured,
   parseListReviewsResponse: () => parseListReviewsResponse,
+  parsePublishedFacebook: () => parsePublishedFacebook,
   parsePublishedReviews: () => parsePublishedReviews,
   parseRetryAfter: () => parseRetryAfter,
+  publishedFacebookUrl: () => publishedFacebookUrl,
   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;
@@ -63,7 +79,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 +97,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 +105,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 +119,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 +504,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 +518,181 @@ async function getPublishedReviews(options) {
   if (limit !== void 0) reviews = reviews.slice(0, limit);
   return { ...result, reviews: order === "shuffle" ? shuffle(reviews) : reviews };
 }
+
+// src/facebook-published.ts
+var isRecord3 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var isTime2 = (v) => typeof v === "string" && !Number.isNaN(Date.parse(v));
+var isCount = (v) => typeof v === "number" && Number.isInteger(v) && v >= 0;
+function parsePublishedFacebook(body, client) {
+  if (!isRecord3(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 || body.source !== "facebook") {
+    throw new GbpPublishedError("invalid", client, `the file is for ${String(body.client)} (${String(body.source)})`);
+  }
+  const { rating, count, recommends } = body;
+  if (rating !== null && (typeof rating !== "number" || !(rating >= 0 && rating <= 5))) {
+    throw new GbpPublishedError("invalid", client, "rating out of range");
+  }
+  if (!isCount(count) || !isCount(recommends) || recommends > count) {
+    throw new GbpPublishedError("invalid", client, "count or recommends is not a whole number within the count");
+  }
+  if (!isTime2(body.synced_at) || !isTime2(body.published_at) || !Array.isArray(body.reviews)) {
+    throw new GbpPublishedError("invalid", client, "synced_at, published_at or reviews missing");
+  }
+  const reviews = body.reviews.flatMap(
+    (v) => isRecord3(v) && typeof v.id === "string" && typeof v.comment === "string" && v.comment && isTime2(v.createdAt) ? [{ id: v.id, comment: v.comment, createdAt: v.createdAt }] : []
+  );
+  return { rating, count, recommends, reviews, syncedAt: body.synced_at, publishedAt: body.published_at };
+}
+function publishedFacebookUrl(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}.facebook.json`;
+}
+async function getPublishedFacebookRecommendations(options) {
+  const { client, limit, next, request } = options;
+  const url = publishedFacebookUrl(client, options.baseUrl);
+  const init = {
+    headers: { Accept: "application/json" },
+    next: next ?? { revalidate: 86400, tags: ["facebook-reviews"] }
+  };
+  const { response } = await fetchWithRetry(url, init, "reviews.facebook", 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 = parsePublishedFacebook(body, client);
+  return limit === void 0 ? result : { ...result, reviews: result.reviews.slice(0, limit) };
+}
+
+// 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,13 +702,18 @@ async function getPublishedReviews(options) {
   GbpTimeoutError,
   PUBLISHED_REVIEWS_SCHEMA,
   getBusinessReviews,
+  getBusinessReviewsSafe,
   getGoogleOAuthAccessToken,
+  getPublishedFacebookRecommendations,
   getPublishedReviews,
+  getPublishedReviewsSafe,
   hasGoogleOAuthCredentials,
   invalidateAccessToken,
   isBusinessProfileConfigured,
   parseListReviewsResponse,
+  parsePublishedFacebook,
   parsePublishedReviews,
   parseRetryAfter,
+  publishedFacebookUrl,
   publishedReviewsUrl
 });

package/dist/index.d.cts

@@ -282,18 +282,72 @@ declare function publishedReviewsUrl(client: string, baseUrl?: string): string;
  */
 declare function getPublishedReviews(options: GetPublishedReviewsOptions): Promise<PublishedReviewsResult>;
 
+interface FacebookRecommendation {
+    id: string;
+    comment: string;
+    /** ISO 8601. */
+    createdAt: string;
+}
+interface PublishedFacebookResult {
+    /** Meta's overall rating out of 5, or null when Meta gives none. */
+    rating: number | null;
+    /** Every recommendation on the Page, positive and negative. */
+    count: number;
+    /** The positive ones. */
+    recommends: number;
+    /** Positive recommendations with words, newest first. */
+    reviews: FacebookRecommendation[];
+    /** When the portal last read the Page in full. */
+    syncedAt: string;
+    publishedAt: string;
+}
+interface GetPublishedFacebookOptions {
+    /** The client's slug, e.g. `"rmp-electrical"`. */
+    client: string;
+    /** Default: `GBP_REVIEWS_BASE_URL`, else the Doman Digital address. */
+    baseUrl?: string;
+    /** Max recommendations to return. Default: all of them. */
+    limit?: number;
+    /** Cache hint passed to `fetch` for Next.js. Default: revalidate daily, tag `facebook-reviews`. */
+    next?: {
+        revalidate?: number;
+        tags?: string[];
+    };
+    request?: GbpRequestOptions;
+}
+/** Validate a published Facebook file. A malformed entry is skipped; a malformed file throws. */
+declare function parsePublishedFacebook(body: unknown, client: string): PublishedFacebookResult;
+/** The URL a client's Facebook file is read from. */
+declare function publishedFacebookUrl(client: string, baseUrl?: string): string;
+/** Fetch a client's published Facebook recommendations. Throws {@link GbpPublishedError} or `GbpTimeoutError`. */
+declare function getPublishedFacebookRecommendations(options: GetPublishedFacebookOptions): Promise<PublishedFacebookResult>;
+
 /**
  * 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";
 /**
@@ -319,6 +373,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 +410,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, type FacebookRecommendation, GbpApiError, GbpAuthError, type GbpAuthErrorCode, GbpError, type GbpFailureReport, GbpPaginationError, GbpPublishedError, type GbpRequestOptions, GbpTimeoutError, type GetBusinessReviewsOptions, type GetPublishedFacebookOptions, type GetPublishedReviewsOptions, PUBLISHED_REVIEWS_SCHEMA, type PublishedFacebookResult, type PublishedReviewsResult, type ReviewMedia, type ReviewOrder, type ReviewReply, type ReviewReplyState, type ReviewsSource, type SafePublishedReviewsResult, type SafeReviewsOptions, type SafeReviewsResult, getBusinessReviews, getBusinessReviewsSafe, getGoogleOAuthAccessToken, getPublishedFacebookRecommendations, getPublishedReviews, getPublishedReviewsSafe, hasGoogleOAuthCredentials, invalidateAccessToken, isBusinessProfileConfigured, parseListReviewsResponse, parsePublishedFacebook, parsePublishedReviews, parseRetryAfter, publishedFacebookUrl, publishedReviewsUrl };

package/dist/index.d.ts

@@ -282,18 +282,72 @@ declare function publishedReviewsUrl(client: string, baseUrl?: string): string;
  */
 declare function getPublishedReviews(options: GetPublishedReviewsOptions): Promise<PublishedReviewsResult>;
 
+interface FacebookRecommendation {
+    id: string;
+    comment: string;
+    /** ISO 8601. */
+    createdAt: string;
+}
+interface PublishedFacebookResult {
+    /** Meta's overall rating out of 5, or null when Meta gives none. */
+    rating: number | null;
+    /** Every recommendation on the Page, positive and negative. */
+    count: number;
+    /** The positive ones. */
+    recommends: number;
+    /** Positive recommendations with words, newest first. */
+    reviews: FacebookRecommendation[];
+    /** When the portal last read the Page in full. */
+    syncedAt: string;
+    publishedAt: string;
+}
+interface GetPublishedFacebookOptions {
+    /** The client's slug, e.g. `"rmp-electrical"`. */
+    client: string;
+    /** Default: `GBP_REVIEWS_BASE_URL`, else the Doman Digital address. */
+    baseUrl?: string;
+    /** Max recommendations to return. Default: all of them. */
+    limit?: number;
+    /** Cache hint passed to `fetch` for Next.js. Default: revalidate daily, tag `facebook-reviews`. */
+    next?: {
+        revalidate?: number;
+        tags?: string[];
+    };
+    request?: GbpRequestOptions;
+}
+/** Validate a published Facebook file. A malformed entry is skipped; a malformed file throws. */
+declare function parsePublishedFacebook(body: unknown, client: string): PublishedFacebookResult;
+/** The URL a client's Facebook file is read from. */
+declare function publishedFacebookUrl(client: string, baseUrl?: string): string;
+/** Fetch a client's published Facebook recommendations. Throws {@link GbpPublishedError} or `GbpTimeoutError`. */
+declare function getPublishedFacebookRecommendations(options: GetPublishedFacebookOptions): Promise<PublishedFacebookResult>;
+
 /**
  * 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";
 /**
@@ -319,6 +373,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 +410,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, type FacebookRecommendation, GbpApiError, GbpAuthError, type GbpAuthErrorCode, GbpError, type GbpFailureReport, GbpPaginationError, GbpPublishedError, type GbpRequestOptions, GbpTimeoutError, type GetBusinessReviewsOptions, type GetPublishedFacebookOptions, type GetPublishedReviewsOptions, PUBLISHED_REVIEWS_SCHEMA, type PublishedFacebookResult, type PublishedReviewsResult, type ReviewMedia, type ReviewOrder, type ReviewReply, type ReviewReplyState, type ReviewsSource, type SafePublishedReviewsResult, type SafeReviewsOptions, type SafeReviewsResult, getBusinessReviews, getBusinessReviewsSafe, getGoogleOAuthAccessToken, getPublishedFacebookRecommendations, getPublishedReviews, getPublishedReviewsSafe, hasGoogleOAuthCredentials, invalidateAccessToken, isBusinessProfileConfigured, parseListReviewsResponse, parsePublishedFacebook, parsePublishedReviews, parseRetryAfter, publishedFacebookUrl, 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,180 @@ async function getPublishedReviews(options) {
   if (limit !== void 0) reviews = reviews.slice(0, limit);
   return { ...result, reviews: order === "shuffle" ? shuffle(reviews) : reviews };
 }
+
+// src/facebook-published.ts
+var isRecord3 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var isTime2 = (v) => typeof v === "string" && !Number.isNaN(Date.parse(v));
+var isCount = (v) => typeof v === "number" && Number.isInteger(v) && v >= 0;
+function parsePublishedFacebook(body, client) {
+  if (!isRecord3(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 || body.source !== "facebook") {
+    throw new GbpPublishedError("invalid", client, `the file is for ${String(body.client)} (${String(body.source)})`);
+  }
+  const { rating, count, recommends } = body;
+  if (rating !== null && (typeof rating !== "number" || !(rating >= 0 && rating <= 5))) {
+    throw new GbpPublishedError("invalid", client, "rating out of range");
+  }
+  if (!isCount(count) || !isCount(recommends) || recommends > count) {
+    throw new GbpPublishedError("invalid", client, "count or recommends is not a whole number within the count");
+  }
+  if (!isTime2(body.synced_at) || !isTime2(body.published_at) || !Array.isArray(body.reviews)) {
+    throw new GbpPublishedError("invalid", client, "synced_at, published_at or reviews missing");
+  }
+  const reviews = body.reviews.flatMap(
+    (v) => isRecord3(v) && typeof v.id === "string" && typeof v.comment === "string" && v.comment && isTime2(v.createdAt) ? [{ id: v.id, comment: v.comment, createdAt: v.createdAt }] : []
+  );
+  return { rating, count, recommends, reviews, syncedAt: body.synced_at, publishedAt: body.published_at };
+}
+function publishedFacebookUrl(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}.facebook.json`;
+}
+async function getPublishedFacebookRecommendations(options) {
+  const { client, limit, next, request } = options;
+  const url = publishedFacebookUrl(client, options.baseUrl);
+  const init = {
+    headers: { Accept: "application/json" },
+    next: next ?? { revalidate: 86400, tags: ["facebook-reviews"] }
+  };
+  const { response } = await fetchWithRetry(url, init, "reviews.facebook", 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 = parsePublishedFacebook(body, client);
+  return limit === void 0 ? result : { ...result, reviews: result.reviews.slice(0, limit) };
+}
+
+// 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,13 +648,18 @@ export {
   GbpTimeoutError,
   PUBLISHED_REVIEWS_SCHEMA,
   getBusinessReviews,
+  getBusinessReviewsSafe,
   getGoogleOAuthAccessToken,
+  getPublishedFacebookRecommendations,
   getPublishedReviews,
+  getPublishedReviewsSafe,
   hasGoogleOAuthCredentials,
   invalidateAccessToken,
   isBusinessProfileConfigured,
   parseListReviewsResponse,
+  parsePublishedFacebook,
   parsePublishedReviews,
   parseRetryAfter,
+  publishedFacebookUrl,
   publishedReviewsUrl
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@domandigital/gbp",
-  "version": "0.5.0",
+  "version": "0.7.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",