@domandigital/gbp 0.3.1 → 0.3.2

package/CHANGELOG.md

@@ -12,6 +12,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 +120,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

@@ -140,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
@@ -149,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.1",
+  "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",