@domandigital/gbp 0.3.2 → 0.4.0

package/dist/index.js

@@ -1,18 +1,158 @@
+// 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({
@@ -20,17 +160,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
@@ -42,6 +212,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--) {
@@ -51,19 +222,49 @@ function shuffleArray(arr) {
   return copy;
 }
 function isUsableReview(r, filterMinStars) {
-  if (!r.comment || !r.starRating) return false;
+  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",
@@ -72,15 +273,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, order = "shuffle" } = 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;
@@ -88,32 +307,68 @@ 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.filter((r) => isUsableReview(r, filterMinStars)).length < limit));
-  const reviews = raw.filter((r) => isUsableReview(r, 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,
+    totalReviewCount: totalReviewCount ?? null,
     reviews: order === "api" ? reviews : shuffleArray(reviews)
   };
 }
 export {
+  DEFAULT_MAX_PAGES,
+  DEFAULT_REQUEST_POLICY,
+  GbpApiError,
+  GbpAuthError,
+  GbpError,
+  GbpPaginationError,
+  GbpTimeoutError,
   getBusinessReviews,
   getGoogleOAuthAccessToken,
   hasGoogleOAuthCredentials,
-  isBusinessProfileConfigured
+  invalidateAccessToken,
+  isBusinessProfileConfigured,
+  parseListReviewsResponse,
+  parseRetryAfter
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@domandigital/gbp",
-  "version": "0.3.2",
+  "version": "0.4.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",
@@ -8,10 +8,13 @@
   "main": "dist/index.cjs",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
+  "sideEffects": false,
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
       "require": {
         "types": "./dist/index.d.cts",
         "default": "./dist/index.cjs"
@@ -25,12 +28,6 @@
     "README.md",
     "dist"
   ],
-  "scripts": {
-    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "prepublishOnly": "pnpm run build"
-  },
   "devDependencies": {
     "@types/node": "^20",
     "tsup": "^8.3.5",
@@ -38,19 +35,24 @@
     "vitest": "^2.1.9"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22.12"
   },
-  "packageManager": "pnpm@9.15.9",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Doman-Digital/dd-gbp.git"
+    "url": "git+https://github.com/Doman-Digital/dd-packages.git",
+    "directory": "packages/gbp"
   },
-  "homepage": "https://github.com/Doman-Digital/dd-gbp#readme",
+  "homepage": "https://github.com/Doman-Digital/dd-packages/tree/main/packages/gbp#readme",
   "bugs": {
-    "url": "https://github.com/Doman-Digital/dd-gbp/issues"
+    "url": "https://github.com/Doman-Digital/dd-packages/issues"
   },
   "publishConfig": {
     "access": "public",
     "provenance": true
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
   }
-}
+}