@domandigital/gbp 0.3.2 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 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
+
+- 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

package/README.md

@@ -38,10 +38,57 @@ 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.
+
+## 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
 
@@ -59,7 +106,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 +169,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,10 +181,21 @@ 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 *usable* reviews are
@@ -155,12 +213,47 @@ Options:
   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
 
@@ -180,5 +273,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).