@domandigital/gbp 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.4.0
+
+### Minor Changes
+
+- bcc2a83: Reviews survive a bad minute at Google, and stop publishing a count Google never gave.
+
+  - **Breaking: `totalReviewCount` is now `number | null`.** A missing count used to fall back to the length of the filtered, limited list, which would put a wrong number into anything built from it (an `aggregateRating`, a "120 reviews" badge). Now it is `null`, and so is an unconfigured result. Handle `null` by rendering no number.
+  - A 401 drops the cached access token, refreshes once and asks for the same page again; a second 401 throws. Concurrent callers share one token refresh.
+  - Every request has an 8 s deadline. 429 and 500/502/503/504 are retried up to three attempts with full-jitter backoff, honouring `Retry-After` up to 30 s. Tunable with `request`.
+  - Pagination stops on a repeated page token or after `maxPages` (default 50) with a `GbpPaginationError`, rather than looping.
+  - Typed errors: `GbpAuthError` (`reauthorizationRequired` on `invalid_grant`), `GbpApiError`, `GbpTimeoutError`, `GbpPaginationError`, all extending `GbpError`, none carrying a credential.
+  - New review fields from Google: attached photos and videos (`media`), the reply link (`replyUrl`), and the reply's moderation `state` with `policyViolation`. Replies Google has not approved are left off unless `includeUnapprovedReplies` is set, so a site never shows a rejected reply.
+  - The response is validated: a malformed review is skipped, a malformed page throws.
+
+- 3eb1560: CommonJS consumers now get the CommonJS type declarations. The `exports` map put a top-level `types` (the ESM `.d.ts`) ahead of `require`, so TypeScript resolving a `require` under `node16` stopped at the ESM file ("Masquerading as ESM" in @arethetypeswrong/cli). `types` now sits inside `import` and `require` separately. Runtime behaviour is unchanged.
+
+  Requires Node 22.12 or later (`engines.node`). Node 20 reached end of life on 2026-04-30. Also declares `sideEffects` so bundlers can tree-shake (craft keeps its CSS).
+
 All notable changes to `@domandigital/gbp`.
 
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
@@ -12,6 +30,29 @@ time.
 
 ## [Unreleased]
 
+## [0.3.2] - 2026-08-16
+
+### Added
+
+- `GetBusinessReviewsOptions.order`, `"shuffle" | "api"`. Default is
+  `"shuffle"`, unchanged from prior behaviour. `"api"` preserves the Business
+  Profile API's own `updateTime desc` ordering instead.
+
+### Fixed
+
+- **`limit` could silently under-return.** Pagination stopped once `raw.length`
+  reached `limit`, but the comment/star-rating filter that determines which
+  reviews are actually usable ran after the loop. A page that was mostly
+  star-only ratings with no comment -- which the API allows -- could satisfy
+  the raw count while producing far fewer, or zero, usable reviews, with no
+  error and no further pages fetched. The stopping condition now counts
+  usable reviews, so `limit` means "give me N reviews you can show."
+
+### Changed
+
+- `limit`'s doc comment now says what it actually counts (usable reviews, not
+  raw API results), matching the fix above.
+
 ## [0.3.1] - 2026-08-16
 
 ### Added
@@ -97,7 +138,8 @@ time.
   `filterMinStars` and a Next.js `next` cache hint. Returns empty results rather
   than throwing when unconfigured, so UI can render unconditionally.
 
-[Unreleased]: https://github.com/Doman-Digital/dd-gbp/compare/v0.3.1...HEAD
+[Unreleased]: https://github.com/Doman-Digital/dd-gbp/compare/v0.3.2...HEAD
+[0.3.2]: https://github.com/Doman-Digital/dd-gbp/compare/v0.3.1...v0.3.2
 [0.3.1]: https://github.com/Doman-Digital/dd-gbp/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/Doman-Digital/dd-gbp/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/Doman-Digital/dd-gbp/compare/v0.1.0...v0.2.0

package/README.md

@@ -38,10 +38,28 @@ const reviewNodes = reviews.map((r) =>
 );
 ```
 
-`averageRating` / `totalReviewCount` feed `OrganizationInput.aggregateRating`
-directly -- don't hardcode a rating/count literal in a site's settings file
-once this is wired in. That literal drifting from the real listing (a site
-claiming 7 reviews when Google has 6) is the bug this package exists to kill.
+`averageRating` / `totalReviewCount` are Google's own numbers for the whole
+profile, rating-only reviews included. Show them instead of hardcoding a
+rating/count literal in a site's settings file: that literal drifting from the
+real listing (a site claiming 7 reviews when Google has 6) is the bug this
+package exists to kill. Both are `null` when Google did not report them;
+render nothing in that case rather than a number.
+
+### Structured data: these reviews earn no stars on the business's own site
+
+Google calls a review "self-serving" when a review about a business sits on
+that business's own website, whether written into the markup or through an
+embedded widget. For `LocalBusiness` and `Organization`, Google shows review
+stars only "for sites that capture reviews about other" businesses
+(developers.google.com/search/docs/appearance/structured-data/review-snippet,
+updated 2026-09-08). So `Review` or `AggregateRating` markup built from these
+reviews, on the client's own site, is ineligible for stars.
+
+It is not a penalty: Google's announcement of the rule says you do not need to
+remove such markup and "You won't get a manual action just for this"
+(developers.google.com/search/blog/2019/09/making-review-rich-results-more-helpful).
+Showing the reviews on the page is unaffected. Just do not sell or expect the
+stars. `@domandigital/graph`'s `findGraphIssues` can flag the pattern.
 
 ## Why Business Profile API, not Places API
 
@@ -59,7 +77,7 @@ pnpm add @domandigital/gbp
 
 Public on npm, Apache-2.0, published with provenance from a tagged release.
 Zero runtime dependencies. ESM and CJS builds ship together, each with its own
-types. Requires Node 20 or newer.
+types. Requires Node 22.12 or newer.
 
 Upgrading a repo that still pins `github:Doman-Digital/dd-gbp#vX.Y.Z`? Swap it
 for a semver range.
@@ -122,8 +140,8 @@ Paginates through every review (GBP caps each page at 50) and returns:
 
 ```ts
 interface BusinessReviewsResult {
-  averageRating: number | null;
-  totalReviewCount: number;
+  averageRating: number | null;    // Google's, for the whole profile; null if not reported
+  totalReviewCount: number | null; // Google's, for the whole profile; null if not reported
   reviews: BusinessReview[];
 }
 
@@ -134,14 +152,26 @@ interface BusinessReview {
   rating: number; // 1-5
   comment: string;
   createdAt: string; // ISO
-  reply?: { text: string; updatedAt: string }; // no author field -- see below
+  reply?: {        // no author field -- see below
+    text: string;
+    updatedAt: string;
+    state?: "PENDING" | "REJECTED" | "APPROVED"; // Google's moderation state
+    policyViolation?: string;                    // why, when REJECTED
+  };
+  media?: { thumbnailUrl: string; label?: string; videoUrl?: string }[]; // photos/videos the reviewer attached
+  replyUrl?: string; // Google's URL for replying, for an owner-facing surface
 }
 ```
 
+`totalReviewCount` and `averageRating` are never computed from the returned
+list. Before 0.4.0, a missing `totalReviewCount` fell back to the length of
+the filtered, limited list, which would have published a wrong count.
+
 Options:
 
-- `limit?: number` -- stop paginating once this many reviews are collected.
-  Omit to fetch all of them.
+- `limit?: number` -- stop paginating once this many *usable* reviews are
+  collected (a raw result needs both a comment and a star rating to count, and
+  `filterMinStars` narrows it further). Omit to fetch all of them.
 - `filterMinStars?: number` -- drop reviews below this rating. Use for a
   public testimonial feed; omit for an owner-facing surface where the point
   is to see everything. `totalReviewCount` always reflects the location's
@@ -149,12 +179,52 @@ Options:
 - `next?: { revalidate?: number; tags?: string[] }` -- passed straight through
   to `fetch`'s Next.js cache-hint augmentation. A no-op outside Next.js.
   Default: revalidate hourly.
+- `order?: "shuffle" | "api"` -- `"shuffle"` (default) randomizes the returned
+  order, applied after `limit`. `"api"` preserves the Business Profile API's
+  own ordering (`updateTime desc`, most recent first). Pick `"api"` for
+  anything that should read as chronological, e.g. an activity feed; the
+  default suits a testimonial grid where a fixed order would look stale.
+- `includeUnapprovedReplies?: boolean` -- default `false`: an owner reply
+  Google has marked `PENDING` or `REJECTED` is left off, so a public page never
+  shows a reply Google does not. Set `true` for an owner-facing surface, where
+  `reply.state` and `reply.policyViolation` say what happened.
+- `maxPages?: number` -- stop after this many pages (default 50, i.e. 2,500
+  reviews) rather than loop.
+- `request?: { timeoutMs?, maxAttempts?, baseDelayMs?, maxDelayMs?, maxRetryAfterMs?, signal? }`
+  -- deadline and retry policy for every request the call makes. Defaults: 8 s
+  per attempt, 3 attempts, full-jitter backoff from 250 ms capped at 5 s, and a
+  `Retry-After` of up to 30 s honoured.
 
 Never throws on missing configuration -- `isBusinessProfileConfigured()` gates
 internally and returns an empty result, so UI can render unconditionally.
-Does throw on a real API failure (non-OK response), so a calling route should
-catch and degrade explicitly if it wants zero-downtime behavior on a Google
-outage.
+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.
+
+### Failures, and what each one means
+
+Every request has a deadline. A 429 or a transient 500/502/503/504 is retried
+a few times with backoff; Google documents the 429 for quota
+(developers.google.com/my-business/content/limits). Nothing else is retried.
+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:
+
+| Error | When | What to do |
+|---|---|---|
+| `GbpAuthError` with `reauthorizationRequired: true` (`code: "invalid_grant"`) | Google refused the refresh token | Reauthorise the account and replace `GBP_REFRESH_TOKEN`. Retrying does nothing. |
+| `GbpAuthError` (`code: "invalid_client"`) | The client id or secret is wrong | Fix the environment. |
+| `GbpApiError` | The API returned an error after the retry budget. `status`, `retryable`, `attempts`, and `retryAfterMs` when Google asked for a long wait | Degrade, and try again on the next revalidation. |
+| `GbpTimeoutError` | An attempt passed its deadline | As above. |
+| `GbpPaginationError` | Google repeated a page token, or `maxPages` ran out | Report it: something upstream is wrong. |
+
+Refresh tokens stop working when the user revokes access, when a token goes
+unused for six months, when the account passes 100 live refresh tokens for
+the client (the oldest is dropped without warning), and **after 7 days if the
+OAuth app is still in "Testing" status**: publish the app, or expect weekly
+reauthorisation (developers.google.com/identity/protocols/oauth2). Google can
+also delete an OAuth client that goes unused, recoverable for 30 days
+(developers.google.com/identity/protocols/oauth2/web-server).
 
 ### Why a reply has no author field
 
@@ -174,5 +244,8 @@ True once all five env vars above are set.
 
 Lower-level OAuth primitives, exported in case a consumer needs the raw
 access token for another Business Profile endpoint this package doesn't wrap
-(e.g. business hours, Q&A). The token is cached in-process and refreshed a
-minute before expiry.
+(e.g. business hours). The token is cached in-process and refreshed a minute
+before expiry; concurrent callers share one refresh.
+`getGoogleOAuthAccessToken({ forceRefresh: true })` refreshes now, and
+`invalidateAccessToken(token)` drops a token an API has rejected (only if it is
+still the cached one).

package/dist/index.cjs

@@ -20,28 +20,178 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  DEFAULT_MAX_PAGES: () => DEFAULT_MAX_PAGES,
+  DEFAULT_REQUEST_POLICY: () => DEFAULT_REQUEST_POLICY,
+  GbpApiError: () => GbpApiError,
+  GbpAuthError: () => GbpAuthError,
+  GbpError: () => GbpError,
+  GbpPaginationError: () => GbpPaginationError,
+  GbpTimeoutError: () => GbpTimeoutError,
   getBusinessReviews: () => getBusinessReviews,
   getGoogleOAuthAccessToken: () => getGoogleOAuthAccessToken,
   hasGoogleOAuthCredentials: () => hasGoogleOAuthCredentials,
-  isBusinessProfileConfigured: () => isBusinessProfileConfigured
+  invalidateAccessToken: () => invalidateAccessToken,
+  isBusinessProfileConfigured: () => isBusinessProfileConfigured,
+  parseListReviewsResponse: () => parseListReviewsResponse,
+  parseRetryAfter: () => parseRetryAfter
 });
 module.exports = __toCommonJS(index_exports);
 
+// src/errors.ts
+var GbpError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = new.target.name;
+  }
+};
+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;
+    this.reauthorizationRequired = code === "invalid_grant";
+    this.status = status;
+    this.description = description;
+  }
+};
+var GbpApiError = class extends GbpError {
+  constructor(options) {
+    super(`Business Profile reviews failed: ${options.status}${options.body ? ` ${options.body}` : ""}`);
+    this.operation = options.operation;
+    this.status = options.status;
+    this.retryable = options.retryable;
+    this.attempts = options.attempts;
+    this.retryAfterMs = options.retryAfterMs;
+  }
+};
+var GbpTimeoutError = class extends GbpError {
+  constructor(operation, timeoutMs) {
+    super(`${operation} timed out after ${timeoutMs}ms`);
+    this.operation = operation;
+    this.timeoutMs = timeoutMs;
+  }
+};
+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)`
+    );
+    this.reason = reason;
+    this.pagesFetched = pagesFetched;
+  }
+};
+function excerpt(text, max = 300) {
+  const flat = text.replace(/\s+/g, " ").trim();
+  return flat.length > max ? `${flat.slice(0, max)}...` : flat;
+}
+
+// src/http.ts
+var DEFAULT_REQUEST_POLICY = {
+  timeoutMs: 8e3,
+  maxAttempts: 3,
+  baseDelayMs: 250,
+  maxDelayMs: 5e3,
+  maxRetryAfterMs: 3e4
+};
+var RETRYABLE_STATUSES = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
+function resolvePolicy(options = {}) {
+  const policy = { ...DEFAULT_REQUEST_POLICY, ...options };
+  const check = (name, min, integer = false) => {
+    const value = policy[name];
+    if (!Number.isFinite(value) || value < min || integer && !Number.isInteger(value)) {
+      throw new RangeError(`request.${name} must be ${integer ? "an integer" : "a number"} >= ${min}, got ${value}`);
+    }
+  };
+  check("timeoutMs", 1);
+  check("maxAttempts", 1, true);
+  check("baseDelayMs", 0);
+  check("maxDelayMs", 0);
+  check("maxRetryAfterMs", 0);
+  return policy;
+}
+function parseRetryAfter(value, nowMs = Date.now()) {
+  if (!value) return null;
+  const v = value.trim();
+  if (/^\d+(\.\d+)?$/.test(v)) return Math.round(Number.parseFloat(v) * 1e3);
+  const at = Date.parse(v);
+  return Number.isNaN(at) ? null : Math.max(0, at - nowMs);
+}
+function backoffMs(attempt, policy, random = Math.random) {
+  const cap = Math.min(policy.maxDelayMs, policy.baseDelayMs * 2 ** (attempt - 1));
+  return Math.floor(random() * cap);
+}
+function sleep(ms, signal) {
+  if (ms <= 0) return Promise.resolve();
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(signal.reason);
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        reject(signal.reason);
+      },
+      { once: true }
+    );
+  });
+}
+async function attemptOnce(url, init, operation, policy) {
+  const deadline = new AbortController();
+  const timer = setTimeout(() => deadline.abort(new GbpTimeoutError(operation, policy.timeoutMs)), policy.timeoutMs);
+  const signal = policy.signal ? AbortSignal.any([policy.signal, deadline.signal]) : deadline.signal;
+  try {
+    return await fetch(url, { ...init, signal });
+  } catch (error) {
+    if (deadline.signal.aborted && !policy.signal?.aborted) throw new GbpTimeoutError(operation, policy.timeoutMs);
+    throw error;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function fetchWithRetry(url, init, operation, policy) {
+  for (let attempt = 1; ; attempt++) {
+    if (policy.signal?.aborted) throw policy.signal.reason;
+    let response;
+    try {
+      response = await attemptOnce(url, init, operation, policy);
+    } catch (error) {
+      if (policy.signal?.aborted || attempt >= policy.maxAttempts) throw error;
+      await sleep(backoffMs(attempt, policy), policy.signal);
+      continue;
+    }
+    if (response.ok || !RETRYABLE_STATUSES.has(response.status)) return { response, attempts: attempt };
+    const retryAfter = parseRetryAfter(response.headers?.get?.("retry-after"));
+    if (retryAfter !== null && retryAfter > policy.maxRetryAfterMs) return { response, attempts: attempt, retryAfterMs: retryAfter };
+    if (attempt >= policy.maxAttempts) return { response, attempts: attempt };
+    await sleep(retryAfter ?? backoffMs(attempt, policy), policy.signal);
+  }
+}
+async function readErrorBody(response) {
+  try {
+    const text = typeof response.text === "function" ? await response.text() : "";
+    return text.slice(0, 2048);
+  } catch {
+    return "";
+  }
+}
+
 // src/oauth-client.ts
 var TOKEN_URI = "https://oauth2.googleapis.com/token";
 var EXPIRY_SKEW_MS = 60 * 1e3;
+var DEFAULT_LIFETIME_S = 3600;
 var cached = null;
+var refreshing = null;
 function hasGoogleOAuthCredentials() {
   return Boolean(
     process.env.GBP_CLIENT_ID && process.env.GBP_CLIENT_SECRET && process.env.GBP_REFRESH_TOKEN
   );
 }
-async function getGoogleOAuthAccessToken() {
-  if (cached && cached.expiresAt > Date.now()) {
-    return cached.accessToken;
-  }
-  if (!hasGoogleOAuthCredentials()) return null;
-  const res = await fetch(TOKEN_URI, {
+function invalidateAccessToken(accessToken) {
+  if (cached?.accessToken === accessToken) cached = null;
+}
+async function refresh(request) {
+  const init = {
     method: "POST",
     headers: { "Content-Type": "application/x-www-form-urlencoded" },
     body: new URLSearchParams({
@@ -49,17 +199,47 @@ async function getGoogleOAuthAccessToken() {
       client_secret: process.env.GBP_CLIENT_SECRET,
       refresh_token: process.env.GBP_REFRESH_TOKEN,
       grant_type: "refresh_token"
-    })
-  });
-  if (!res.ok) {
-    throw new Error(`Google OAuth token refresh failed: ${res.status} ${await res.text()}`);
-  }
-  const data = await res.json();
-  cached = {
-    accessToken: data.access_token,
-    expiresAt: Date.now() + (data.expires_in ?? 3600) * 1e3 - EXPIRY_SKEW_MS
+    }),
+    cache: "no-store"
   };
-  return cached.accessToken;
+  const { response } = await fetchWithRetry(TOKEN_URI, init, "oauth.refresh", resolvePolicy(request));
+  if (!response.ok) {
+    const body = await readErrorBody(response);
+    let error;
+    let description;
+    try {
+      const parsed = JSON.parse(body);
+      if (typeof parsed.error === "string") error = parsed.error;
+      if (typeof parsed.error_description === "string") description = excerpt(parsed.error_description, 200);
+    } catch {
+      if (/\binvalid_grant\b/.test(body)) error = "invalid_grant";
+      else if (/\binvalid_client\b/.test(body)) error = "invalid_client";
+    }
+    if (error === "invalid_grant") cached = null;
+    const code = error === "invalid_grant" || error === "invalid_client" ? error : "token_request_failed";
+    throw new GbpAuthError(code, response.status, description ?? (code === "token_request_failed" && body ? excerpt(body, 200) : void 0));
+  }
+  const data = await response.json();
+  if (typeof data.access_token !== "string" || !data.access_token) {
+    throw new GbpAuthError("token_request_failed", response.status, "token response had no access_token");
+  }
+  const lifetime = typeof data.expires_in === "number" && Number.isFinite(data.expires_in) && data.expires_in > 0 ? data.expires_in : DEFAULT_LIFETIME_S;
+  return { accessToken: data.access_token, expiresAt: Date.now() + lifetime * 1e3 - EXPIRY_SKEW_MS };
+}
+async function getGoogleOAuthAccessToken(options = {}) {
+  if (!options.forceRefresh && cached && cached.expiresAt > Date.now()) {
+    return cached.accessToken;
+  }
+  if (!hasGoogleOAuthCredentials()) return null;
+  if (!refreshing) {
+    refreshing = refresh(options.request).then((token) => {
+      cached = token;
+      return token;
+    }).finally(() => {
+      refreshing = null;
+    });
+  }
+  return (await refreshing).accessToken;
 }
 
 // src/reviews.ts
@@ -71,6 +251,7 @@ var STAR_VALUES = {
   FIVE: 5
 };
 var MAX_PAGE_SIZE = 50;
+var DEFAULT_MAX_PAGES = 50;
 function shuffleArray(arr) {
   const copy = [...arr];
   for (let i = copy.length - 1; i > 0; i--) {
@@ -79,15 +260,50 @@ function shuffleArray(arr) {
   }
   return copy;
 }
+function isUsableReview(r, filterMinStars) {
+  if (!r.comment || !r.starRating || !(r.starRating in STAR_VALUES)) return false;
+  if (filterMinStars !== void 0 && STAR_VALUES[r.starRating] < filterMinStars) return false;
+  return true;
+}
 var EMPTY = {
   averageRating: null,
-  totalReviewCount: 0,
+  totalReviewCount: null,
   reviews: []
 };
 function isBusinessProfileConfigured() {
   return hasGoogleOAuthCredentials() && Boolean(process.env.GOOGLE_BUSINESS_ACCOUNT_ID) && Boolean(process.env.GOOGLE_BUSINESS_LOCATION_ID);
 }
-function toBusinessReview(r) {
+var isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var str = (v) => typeof v === "string" ? v : void 0;
+function parseReview(v) {
+  if (!isRecord(v) || typeof v.reviewId !== "string") return null;
+  const reviewer = isRecord(v.reviewer) ? { displayName: str(v.reviewer.displayName), profilePhotoUrl: str(v.reviewer.profilePhotoUrl) } : void 0;
+  const reply = isRecord(v.reviewReply) ? {
+    comment: str(v.reviewReply.comment),
+    updateTime: str(v.reviewReply.updateTime),
+    reviewReplyState: str(v.reviewReply.reviewReplyState),
+    policyViolation: str(v.reviewReply.policyViolation)
+  } : void 0;
+  const media = Array.isArray(v.reviewMediaItems) ? v.reviewMediaItems.filter(isRecord).map((m) => ({ thumbnailUrl: str(m.thumbnailUrl), thumbnailLabel: str(m.thumbnailLabel), videoUrl: str(m.videoUrl) })) : void 0;
+  return {
+    reviewId: v.reviewId,
+    reviewer,
+    starRating: str(v.starRating),
+    comment: str(v.comment),
+    createTime: str(v.createTime),
+    reviewReply: reply,
+    reviewMediaItems: media,
+    reviewReplyUrl: str(v.reviewReplyUrl)
+  };
+}
+function parseListReviewsResponse(body) {
+  if (!isRecord(body)) throw new TypeError("Business Profile reviews response was not an object");
+  const reviews = Array.isArray(body.reviews) ? body.reviews.map(parseReview).filter((r) => r !== null) : [];
+  const average = typeof body.averageRating === "number" && Number.isFinite(body.averageRating) && body.averageRating >= 0 && body.averageRating <= 5 ? body.averageRating : void 0;
+  const total = typeof body.totalReviewCount === "number" && Number.isInteger(body.totalReviewCount) && body.totalReviewCount >= 0 ? body.totalReviewCount : void 0;
+  return { reviews, averageRating: average, totalReviewCount: total, nextPageToken: str(body.nextPageToken) || void 0 };
+}
+function toBusinessReview(r, includeUnapprovedReplies) {
   const review = {
     id: r.reviewId,
     author: r.reviewer?.displayName ?? "Anonymous",
@@ -96,15 +312,33 @@ function toBusinessReview(r) {
     comment: r.comment ?? "",
     createdAt: r.createTime ?? ""
   };
-  if (r.reviewReply?.comment) {
-    review.reply = { text: r.reviewReply.comment, updatedAt: r.reviewReply.updateTime ?? "" };
+  const reply = r.reviewReply;
+  if (reply?.comment) {
+    const state = reply.reviewReplyState === "PENDING" || reply.reviewReplyState === "REJECTED" || reply.reviewReplyState === "APPROVED" ? reply.reviewReplyState : void 0;
+    if (includeUnapprovedReplies || state !== "PENDING" && state !== "REJECTED") {
+      review.reply = { text: reply.comment, updatedAt: reply.updateTime ?? "" };
+      if (state) review.reply.state = state;
+      if (state === "REJECTED" && reply.policyViolation) review.reply.policyViolation = reply.policyViolation;
+    }
   }
+  const media = (r.reviewMediaItems ?? []).filter((m) => Boolean(m.thumbnailUrl));
+  if (media.length > 0) {
+    review.media = media.map((m) => ({
+      thumbnailUrl: m.thumbnailUrl,
+      ...m.thumbnailLabel ? { label: m.thumbnailLabel } : {},
+      ...m.videoUrl ? { videoUrl: m.videoUrl } : {}
+    }));
+  }
+  if (r.reviewReplyUrl) review.replyUrl = r.reviewReplyUrl;
   return review;
 }
 async function getBusinessReviews(options = {}) {
-  const { limit, filterMinStars, next } = options;
+  const { limit, filterMinStars, next, order = "shuffle", includeUnapprovedReplies = false, request } = options;
+  const maxPages = options.maxPages ?? DEFAULT_MAX_PAGES;
+  if (!Number.isInteger(maxPages) || maxPages < 1) throw new RangeError(`maxPages must be an integer >= 1, got ${maxPages}`);
   if (!isBusinessProfileConfigured()) return EMPTY;
-  const token = await getGoogleOAuthAccessToken();
+  const policy = resolvePolicy(request);
+  let token = await getGoogleOAuthAccessToken({ request });
   if (!token) return EMPTY;
   const account = process.env.GOOGLE_BUSINESS_ACCOUNT_ID;
   const location = process.env.GOOGLE_BUSINESS_LOCATION_ID;
@@ -112,33 +346,69 @@ async function getBusinessReviews(options = {}) {
   let averageRating;
   let totalReviewCount;
   let pageToken;
-  do {
-    const endpoint = `https://mybusiness.googleapis.com/v4/accounts/${account}/locations/${location}/reviews?orderBy=updateTime%20desc&pageSize=${MAX_PAGE_SIZE}` + (pageToken ? `&pageToken=${encodeURIComponent(pageToken)}` : "");
-    const fetchOptions = {
-      headers: { Authorization: `Bearer ${token}` },
+  const seenTokens = /* @__PURE__ */ new Set();
+  let pages = 0;
+  const fetchPage = (accessToken, endpoint) => {
+    const init = {
+      headers: { Authorization: `Bearer ${accessToken}` },
       next: next ?? { revalidate: 3600, tags: ["google-reviews"] }
     };
-    const res = await fetch(endpoint, fetchOptions);
-    if (!res.ok) {
-      throw new Error(`Business Profile reviews failed: ${res.status} ${await res.text()}`);
+    return fetchWithRetry(endpoint, init, "reviews.list", policy);
+  };
+  for (; ; ) {
+    const endpoint = `https://mybusiness.googleapis.com/v4/accounts/${account}/locations/${location}/reviews?orderBy=updateTime%20desc&pageSize=${MAX_PAGE_SIZE}` + (pageToken ? `&pageToken=${encodeURIComponent(pageToken)}` : "");
+    let attempt = await fetchPage(token, endpoint);
+    if (attempt.response.status === 401) {
+      invalidateAccessToken(token);
+      const fresh = await getGoogleOAuthAccessToken({ forceRefresh: true, request });
+      if (!fresh) return EMPTY;
+      token = fresh;
+      attempt = await fetchPage(token, endpoint);
+    }
+    const { response, attempts, retryAfterMs } = attempt;
+    if (!response.ok) {
+      throw new GbpApiError({
+        operation: "reviews.list",
+        status: response.status,
+        retryable: RETRYABLE_STATUSES.has(response.status),
+        attempts,
+        body: excerpt(await readErrorBody(response)),
+        retryAfterMs
+      });
     }
-    const data = await res.json();
-    raw.push(...data.reviews ?? []);
-    averageRating = data.averageRating ?? averageRating;
-    totalReviewCount = data.totalReviewCount ?? totalReviewCount;
+    const data = parseListReviewsResponse(await response.json());
+    pages++;
+    raw.push(...data.reviews);
+    averageRating ?? (averageRating = data.averageRating);
+    totalReviewCount ?? (totalReviewCount = data.totalReviewCount);
     pageToken = data.nextPageToken;
-  } while (pageToken && (limit === void 0 || raw.length < limit));
-  const reviews = raw.filter((r) => r.comment && r.starRating).filter((r) => filterMinStars === void 0 || STAR_VALUES[r.starRating] >= filterMinStars).map(toBusinessReview).slice(0, limit);
+    const enough = limit !== void 0 && raw.filter((r) => isUsableReview(r, filterMinStars)).length >= limit;
+    if (!pageToken || enough) break;
+    if (seenTokens.has(pageToken)) throw new GbpPaginationError("repeated_token", pages);
+    seenTokens.add(pageToken);
+    if (pages >= maxPages) throw new GbpPaginationError("page_limit", pages);
+  }
+  const reviews = raw.filter((r) => isUsableReview(r, filterMinStars)).map((r) => toBusinessReview(r, includeUnapprovedReplies)).slice(0, limit);
   return {
     averageRating: averageRating ?? null,
-    totalReviewCount: totalReviewCount ?? reviews.length,
-    reviews: shuffleArray(reviews)
+    totalReviewCount: totalReviewCount ?? null,
+    reviews: order === "api" ? reviews : shuffleArray(reviews)
   };
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  DEFAULT_MAX_PAGES,
+  DEFAULT_REQUEST_POLICY,
+  GbpApiError,
+  GbpAuthError,
+  GbpError,
+  GbpPaginationError,
+  GbpTimeoutError,
   getBusinessReviews,
   getGoogleOAuthAccessToken,
   hasGoogleOAuthCredentials,
-  isBusinessProfileConfigured
+  invalidateAccessToken,
+  isBusinessProfileConfigured,
+  parseListReviewsResponse,
+  parseRetryAfter
 });