@domandigital/gbp 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -0,0 +1,128 @@
+# Changelog
+
+All notable changes to `@domandigital/gbp`.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
+this project uses [semantic versioning](https://semver.org/spec/v2.0.0.html).
+
+Releases before 0.3.1 were consumed as git dependencies pinned to a tag. This
+file was written retroactively from that tag history, so entries below 0.3.1
+describe what the diffs actually changed rather than what was recorded at the
+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
+
+- `./package.json` is now exposed in the `exports` map. Tooling that reads a
+  dependency's manifest previously hit `ERR_PACKAGE_PATH_NOT_EXPORTED`.
+- `@types/node` is declared as a devDependency, and `tsconfig.json` sets
+  `"types": ["node"]`. This package uses `process.env`, `fetch`,
+  `URLSearchParams`, `RequestInit` and `Response`, all of which need those
+  types, and none of which had a declared source. `pnpm typecheck` passed only
+  because TypeScript walks up past the repo root and can find an `@types/node`
+  installed elsewhere on the machine. No consumer was affected, since published
+  `.d.ts` files carry their own references, but the check was not real.
+- CI on every push and pull request: typecheck, test and build across Node 20,
+  22 and 24. Previously the only workflow was the tag-triggered release.
+- README section covering `scripts/oauth-listener.mjs`, the one-time local flow
+  that mints a client's `GBP_REFRESH_TOKEN` and writes it straight to Doppler.
+  It shipped in 0.3.0 with no documentation at all.
+
+### Changed
+
+- `engines.node` raised from `>=18` to `>=20`. Node 18 reached end of life in
+  April 2025, and the previous range was never exercised by anything.
+- README rewritten for npm distribution. The install section still described the
+  package as unpublished and pointed at the `#v0.1.0` git tag.
+
+## [0.3.0] - 2026-08-16
+
+### Added
+
+- `scripts/oauth-listener.mjs`: a one-time local OAuth flow that prints a
+  consent URL, catches Google's redirect on a local listener, exchanges the
+  code, looks up the account and location IDs, and writes all three values to
+  Doppler. The token never passes through stdout, so it can't land in a
+  captured log.
+
+  This script is not part of the published package. It isn't in `files`, so it's
+  absent from the npm tarball: it shells out to the `doppler` binary, which has
+  no place in a public library's runtime contract. Clone the repo to use it.
+
+### Fixed
+
+- The pagination test asserted a fixed order against a result the library
+  deliberately shuffles. With two reviews a shuffle returns the input order
+  about half the time, so the test failed roughly 50% of runs and survived two
+  releases because nothing ran the suite automatically. It now compares the set
+  of ids.
+
+### Changed
+
+- Licensed Apache-2.0, with publish metadata and `publishConfig` for public
+  access and provenance. First version published to the npm registry.
+
+## [0.2.0] - 2026-07-31
+
+### Changed
+
+- **`getBusinessReviews` now returns reviews in random order.** Results are
+  shuffled before being returned, replacing the API's own
+  `orderBy=updateTime desc` ordering. There is no way to opt out.
+
+  Two consequences worth knowing before you upgrade from 0.1.0: output is not
+  stable across builds, so a statically generated testimonial section reorders
+  on every rebuild; and because the shuffle runs after `limit` is applied, you
+  get the most recent N reviews in random order rather than a random N.
+
+  (The 0.2.0 tag message also credits min-star filtering. That's inaccurate:
+  `filterMinStars` shipped in 0.1.0.)
+
+## [0.1.0] - 2026-07-30
+
+### Added
+
+- Initial release, extracted from MMM Beauty's `packages/google-apis`. Zero
+  runtime dependencies.
+- `getGoogleOAuthAccessToken` and `hasGoogleOAuthCredentials`: user
+  refresh-token OAuth, with the access token cached in process and refreshed a
+  minute before expiry. Service accounts are rejected by the Business Profile
+  API entirely, so this is the only auth route.
+- `getBusinessReviews` and `isBusinessProfileConfigured`: a paginated reviews
+  fetch (the API caps each page at 50) that decodes Google's star-rating enums,
+  includes the business's reply to each review, and supports `limit`,
+  `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.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
+[0.1.0]: https://github.com/Doman-Digital/dd-gbp/releases/tag/v0.1.0

package/README.md

@@ -53,19 +53,16 @@ with the reply attached, for free.
 
 ## Install
 
-Not published to npm. Consumed as a git dependency pinned to a tag:
-
-```json
-{
-  "dependencies": {
-    "@domandigital/gbp": "github:Doman-Digital/dd-gbp#v0.1.0"
-  }
-}
+```bash
+pnpm add @domandigital/gbp
 ```
 
-`dist/` is committed to this repo (no CI build step runs on a git-dependency
-install), so no build step is required in the consuming project beyond a
-normal `pnpm install`.
+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.
+
+Upgrading a repo that still pins `github:Doman-Digital/dd-gbp#vX.Y.Z`? Swap it
+for a semver range.
 
 ## Env
 
@@ -81,6 +78,42 @@ Which actual Google Cloud OAuth client + refresh token you point at (the
 agency's shared credential, or a business's own dedicated one) is entirely a
 deployment-env decision, not a code-level one -- each app configures its own.
 
+## Minting a client's refresh token
+
+`GBP_REFRESH_TOKEN` can only be obtained by a human completing Google's consent
+flow as the business owner. `scripts/oauth-listener.mjs` in this repo automates
+everything around that: it prints a consent URL, catches Google's redirect on a
+local listener, exchanges the code, looks up the account and location IDs, and
+writes all three values straight to Doppler.
+
+The token and both IDs travel via argv into `doppler secrets set` and are never
+printed to stdout or returned from the process, so a captured terminal log can't
+leak them.
+
+This script is repo-only. It isn't in the package's `files`, so it's absent from
+the npm tarball, deliberately: it shells out to the `doppler` binary, which has
+no business being a runtime expectation of a public library. Clone the repo to
+use it.
+
+Run it from inside the **client's** repo, so `doppler secrets set` targets that
+client's own project and config via their local `.doppler.yaml` scoping:
+
+```bash
+GBP_CLIENT_ID=$(doppler secrets get GBP_CLIENT_ID --plain) GBP_CLIENT_SECRET=$(doppler secrets get GBP_CLIENT_SECRET --plain) node ../dd-gbp/scripts/oauth-listener.mjs
+```
+
+Two things that will bite you once each:
+
+- `http://127.0.0.1:3333/oauth2callback` has to be registered as an authorised
+  redirect URI on the OAuth client in the GCP console. If it isn't, Google
+  returns `redirect_uri_mismatch`.
+- If the account has already granted this app access, Google can decline to
+  issue a new refresh token even with `prompt=consent`. Revoke it at
+  https://myaccount.google.com/permissions and run the script again.
+
+If the account has more than one location, the script uses the first and prints
+every location it saw, so you can check it picked the right one.
+
 ## API
 
 ### `getBusinessReviews(options?): Promise<BusinessReviewsResult>`
@@ -107,8 +140,9 @@ interface BusinessReview {
 
 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
@@ -116,6 +150,11 @@ 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.
 
 Never throws on missing configuration -- `isBusinessProfileConfigured()` gates
 internally and returns an empty result, so UI can render unconditionally.

package/dist/index.cjs

@@ -79,6 +79,11 @@ function shuffleArray(arr) {
   }
   return copy;
 }
+function isUsableReview(r, filterMinStars) {
+  if (!r.comment || !r.starRating) return false;
+  if (filterMinStars !== void 0 && STAR_VALUES[r.starRating] < filterMinStars) return false;
+  return true;
+}
 var EMPTY = {
   averageRating: null,
   totalReviewCount: 0,
@@ -102,7 +107,7 @@ function toBusinessReview(r) {
   return review;
 }
 async function getBusinessReviews(options = {}) {
-  const { limit, filterMinStars, next } = options;
+  const { limit, filterMinStars, next, order = "shuffle" } = options;
   if (!isBusinessProfileConfigured()) return EMPTY;
   const token = await getGoogleOAuthAccessToken();
   if (!token) return EMPTY;
@@ -127,12 +132,12 @@ async function getBusinessReviews(options = {}) {
     averageRating = data.averageRating ?? averageRating;
     totalReviewCount = data.totalReviewCount ?? 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);
+  } while (pageToken && (limit === void 0 || raw.filter((r) => isUsableReview(r, filterMinStars)).length < limit));
+  const reviews = raw.filter((r) => isUsableReview(r, filterMinStars)).map(toBusinessReview).slice(0, limit);
   return {
     averageRating: averageRating ?? null,
     totalReviewCount: totalReviewCount ?? reviews.length,
-    reviews: shuffleArray(reviews)
+    reviews: order === "api" ? reviews : shuffleArray(reviews)
   };
 }
 // Annotate the CommonJS export names for ESM import in node:

package/dist/index.d.cts

@@ -64,8 +64,11 @@ interface BusinessReviewsResult {
 }
 /** True when account + location + OAuth credentials are all configured. */
 declare function isBusinessProfileConfigured(): boolean;
+type ReviewOrder = "shuffle" | "api";
 interface GetBusinessReviewsOptions {
-    /** Max reviews to return (default: all of them, paginated). */
+    /** Max reviews to return (default: all of them, paginated). Counts usable
+     * reviews only -- see `filterMinStars` -- so this is "give me N reviews you
+     * can show", not "give me N raw API results". */
     limit?: number;
     /**
      * When set, only reviews at or above this star rating are returned -- for
@@ -80,6 +83,12 @@ interface GetBusinessReviewsOptions {
         revalidate?: number;
         tags?: string[];
     };
+    /**
+     * `"shuffle"` (default): randomizes the returned order, applied after
+     * `limit`. `"api"`: preserves the Business Profile API's own ordering
+     * (`updateTime desc`, most recent first).
+     */
+    order?: ReviewOrder;
 }
 /**
  * Fetch reviews for the configured location, paginating through all pages

package/dist/index.d.ts

@@ -64,8 +64,11 @@ interface BusinessReviewsResult {
 }
 /** True when account + location + OAuth credentials are all configured. */
 declare function isBusinessProfileConfigured(): boolean;
+type ReviewOrder = "shuffle" | "api";
 interface GetBusinessReviewsOptions {
-    /** Max reviews to return (default: all of them, paginated). */
+    /** Max reviews to return (default: all of them, paginated). Counts usable
+     * reviews only -- see `filterMinStars` -- so this is "give me N reviews you
+     * can show", not "give me N raw API results". */
     limit?: number;
     /**
      * When set, only reviews at or above this star rating are returned -- for
@@ -80,6 +83,12 @@ interface GetBusinessReviewsOptions {
         revalidate?: number;
         tags?: string[];
     };
+    /**
+     * `"shuffle"` (default): randomizes the returned order, applied after
+     * `limit`. `"api"`: preserves the Business Profile API's own ordering
+     * (`updateTime desc`, most recent first).
+     */
+    order?: ReviewOrder;
 }
 /**
  * Fetch reviews for the configured location, paginating through all pages

package/dist/index.js

@@ -50,6 +50,11 @@ function shuffleArray(arr) {
   }
   return copy;
 }
+function isUsableReview(r, filterMinStars) {
+  if (!r.comment || !r.starRating) return false;
+  if (filterMinStars !== void 0 && STAR_VALUES[r.starRating] < filterMinStars) return false;
+  return true;
+}
 var EMPTY = {
   averageRating: null,
   totalReviewCount: 0,
@@ -73,7 +78,7 @@ function toBusinessReview(r) {
   return review;
 }
 async function getBusinessReviews(options = {}) {
-  const { limit, filterMinStars, next } = options;
+  const { limit, filterMinStars, next, order = "shuffle" } = options;
   if (!isBusinessProfileConfigured()) return EMPTY;
   const token = await getGoogleOAuthAccessToken();
   if (!token) return EMPTY;
@@ -98,12 +103,12 @@ async function getBusinessReviews(options = {}) {
     averageRating = data.averageRating ?? averageRating;
     totalReviewCount = data.totalReviewCount ?? 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);
+  } while (pageToken && (limit === void 0 || raw.filter((r) => isUsableReview(r, filterMinStars)).length < limit));
+  const reviews = raw.filter((r) => isUsableReview(r, filterMinStars)).map(toBusinessReview).slice(0, limit);
   return {
     averageRating: averageRating ?? null,
     totalReviewCount: totalReviewCount ?? reviews.length,
-    reviews: shuffleArray(reviews)
+    reviews: order === "api" ? reviews : shuffleArray(reviews)
   };
 }
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@domandigital/gbp",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "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",
@@ -16,9 +16,11 @@
         "types": "./dist/index.d.cts",
         "default": "./dist/index.cjs"
       }
-    }
+    },
+    "./package.json": "./package.json"
   },
   "files": [
+    "CHANGELOG.md",
     "LICENSE",
     "README.md",
     "dist"
@@ -30,12 +32,13 @@
     "prepublishOnly": "pnpm run build"
   },
   "devDependencies": {
+    "@types/node": "^20",
     "tsup": "^8.3.5",
     "typescript": "^5.6.3",
     "vitest": "^2.1.9"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "packageManager": "pnpm@9.15.9",
   "repository": {