@domandigital/gbp 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.7.0
+
+### Minor Changes
+
+- 59e6d85: Read a client's Facebook Page recommendations from the file Doman Digital publishes, so a site needs no Meta token.
+  
+  - **`getPublishedFacebookRecommendations({ client })`** fetches `https://files.domandigital.co.uk/reviews/<client>.facebook.json`, which the portal writes daily from the Page token it already holds.
+  - Returns Meta's own `rating` (null when Meta gives none), `count` (every recommendation), `recommends` (the positive ones) and `reviews`: positive recommendations with words, with `id`, `comment` and `createdAt`. There is no author, because Meta does not return one.
+  - Throws `GbpPublishedError` like `getPublishedReviews`, so the caller keeps its last good copy. Refuses the Google file, another client's file and a count that does not add up.
+
 ## 0.6.0
 
 ### Minor Changes

package/README.md

@@ -90,6 +90,25 @@ 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.
 
+### Facebook recommendations
+
+The portal also publishes each client's Facebook Page recommendations beside
+the Google file, at `<client-slug>.facebook.json`:
+
+```ts
+import { getPublishedFacebookRecommendations } from "@domandigital/gbp";
+
+const { rating, count, recommends, reviews } = await getPublishedFacebookRecommendations({
+  client: "rmp-electrical",
+});
+```
+
+Facebook has recommendations, not star reviews. `count` is every
+recommendation on the Page, `recommends` the positive ones, and `rating` is
+Meta's own overall figure (null when Meta gives none). `reviews` holds the
+positive recommendations that have words. There is no author, because Meta
+does not return one. It throws on failure like `getPublishedReviews`.
+
 ## Why Business Profile API, not Places API
 
 Places API's `Review` object has no field for the business's reply, full

package/dist/index.cjs

@@ -36,14 +36,17 @@ __export(index_exports, {
   getBusinessReviews: () => getBusinessReviews,
   getBusinessReviewsSafe: () => getBusinessReviewsSafe,
   getGoogleOAuthAccessToken: () => getGoogleOAuthAccessToken,
+  getPublishedFacebookRecommendations: () => getPublishedFacebookRecommendations,
   getPublishedReviews: () => getPublishedReviews,
   getPublishedReviewsSafe: () => getPublishedReviewsSafe,
   hasGoogleOAuthCredentials: () => hasGoogleOAuthCredentials,
   invalidateAccessToken: () => invalidateAccessToken,
   isBusinessProfileConfigured: () => isBusinessProfileConfigured,
   parseListReviewsResponse: () => parseListReviewsResponse,
+  parsePublishedFacebook: () => parsePublishedFacebook,
   parsePublishedReviews: () => parsePublishedReviews,
   parseRetryAfter: () => parseRetryAfter,
+  publishedFacebookUrl: () => publishedFacebookUrl,
   publishedReviewsUrl: () => publishedReviewsUrl
 });
 module.exports = __toCommonJS(index_exports);
@@ -516,6 +519,58 @@ async function getPublishedReviews(options) {
   return { ...result, reviews: order === "shuffle" ? shuffle(reviews) : reviews };
 }
 
+// src/facebook-published.ts
+var isRecord3 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var isTime2 = (v) => typeof v === "string" && !Number.isNaN(Date.parse(v));
+var isCount = (v) => typeof v === "number" && Number.isInteger(v) && v >= 0;
+function parsePublishedFacebook(body, client) {
+  if (!isRecord3(body)) throw new GbpPublishedError("invalid", client, "the file is not an object");
+  if (body.schema !== PUBLISHED_REVIEWS_SCHEMA) throw new GbpPublishedError("unknown_schema", client, `schema ${String(body.schema)}`);
+  if (body.client !== client || body.source !== "facebook") {
+    throw new GbpPublishedError("invalid", client, `the file is for ${String(body.client)} (${String(body.source)})`);
+  }
+  const { rating, count, recommends } = body;
+  if (rating !== null && (typeof rating !== "number" || !(rating >= 0 && rating <= 5))) {
+    throw new GbpPublishedError("invalid", client, "rating out of range");
+  }
+  if (!isCount(count) || !isCount(recommends) || recommends > count) {
+    throw new GbpPublishedError("invalid", client, "count or recommends is not a whole number within the count");
+  }
+  if (!isTime2(body.synced_at) || !isTime2(body.published_at) || !Array.isArray(body.reviews)) {
+    throw new GbpPublishedError("invalid", client, "synced_at, published_at or reviews missing");
+  }
+  const reviews = body.reviews.flatMap(
+    (v) => isRecord3(v) && typeof v.id === "string" && typeof v.comment === "string" && v.comment && isTime2(v.createdAt) ? [{ id: v.id, comment: v.comment, createdAt: v.createdAt }] : []
+  );
+  return { rating, count, recommends, reviews, syncedAt: body.synced_at, publishedAt: body.published_at };
+}
+function publishedFacebookUrl(client, baseUrl) {
+  if (!/^[a-z0-9][a-z0-9-]{0,99}$/.test(client)) throw new RangeError(`not a client slug: ${client}`);
+  const base = (baseUrl ?? process.env.GBP_REVIEWS_BASE_URL ?? DEFAULT_PUBLISHED_REVIEWS_BASE_URL).replace(/\/+$/, "");
+  return `${base}/${client}.facebook.json`;
+}
+async function getPublishedFacebookRecommendations(options) {
+  const { client, limit, next, request } = options;
+  const url = publishedFacebookUrl(client, options.baseUrl);
+  const init = {
+    headers: { Accept: "application/json" },
+    next: next ?? { revalidate: 86400, tags: ["facebook-reviews"] }
+  };
+  const { response } = await fetchWithRetry(url, init, "reviews.facebook", resolvePolicy(request));
+  if (!response.ok) {
+    const body2 = excerpt(await readErrorBody(response), 120);
+    throw new GbpPublishedError("http", client, String(response.status), response.status, body2 || void 0);
+  }
+  let body;
+  try {
+    body = await response.json();
+  } catch {
+    throw new GbpPublishedError("invalid", client, "the file is not JSON");
+  }
+  const result = parsePublishedFacebook(body, client);
+  return limit === void 0 ? result : { ...result, reviews: result.reviews.slice(0, limit) };
+}
+
 // src/safe.ts
 var DEFAULT_REPORT_INTERVAL_MS = 60 * 60 * 1e3;
 var DEFAULT_MAX_STALE_MS = 30 * 24 * 60 * 60 * 1e3;
@@ -649,13 +704,16 @@ function getPublishedReviewsSafe(options) {
   getBusinessReviews,
   getBusinessReviewsSafe,
   getGoogleOAuthAccessToken,
+  getPublishedFacebookRecommendations,
   getPublishedReviews,
   getPublishedReviewsSafe,
   hasGoogleOAuthCredentials,
   invalidateAccessToken,
   isBusinessProfileConfigured,
   parseListReviewsResponse,
+  parsePublishedFacebook,
   parsePublishedReviews,
   parseRetryAfter,
+  publishedFacebookUrl,
   publishedReviewsUrl
 });

package/dist/index.d.cts

@@ -282,6 +282,46 @@ declare function publishedReviewsUrl(client: string, baseUrl?: string): string;
  */
 declare function getPublishedReviews(options: GetPublishedReviewsOptions): Promise<PublishedReviewsResult>;
 
+interface FacebookRecommendation {
+    id: string;
+    comment: string;
+    /** ISO 8601. */
+    createdAt: string;
+}
+interface PublishedFacebookResult {
+    /** Meta's overall rating out of 5, or null when Meta gives none. */
+    rating: number | null;
+    /** Every recommendation on the Page, positive and negative. */
+    count: number;
+    /** The positive ones. */
+    recommends: number;
+    /** Positive recommendations with words, newest first. */
+    reviews: FacebookRecommendation[];
+    /** When the portal last read the Page in full. */
+    syncedAt: string;
+    publishedAt: string;
+}
+interface GetPublishedFacebookOptions {
+    /** The client's slug, e.g. `"rmp-electrical"`. */
+    client: string;
+    /** Default: `GBP_REVIEWS_BASE_URL`, else the Doman Digital address. */
+    baseUrl?: string;
+    /** Max recommendations to return. Default: all of them. */
+    limit?: number;
+    /** Cache hint passed to `fetch` for Next.js. Default: revalidate daily, tag `facebook-reviews`. */
+    next?: {
+        revalidate?: number;
+        tags?: string[];
+    };
+    request?: GbpRequestOptions;
+}
+/** Validate a published Facebook file. A malformed entry is skipped; a malformed file throws. */
+declare function parsePublishedFacebook(body: unknown, client: string): PublishedFacebookResult;
+/** The URL a client's Facebook file is read from. */
+declare function publishedFacebookUrl(client: string, baseUrl?: string): string;
+/** Fetch a client's published Facebook recommendations. Throws {@link GbpPublishedError} or `GbpTimeoutError`. */
+declare function getPublishedFacebookRecommendations(options: GetPublishedFacebookOptions): Promise<PublishedFacebookResult>;
+
 /**
  * Typed failures, so a site can tell "reauthorise the Google account" from
  * "Google is having a bad minute" from "our code looped", and log the
@@ -461,4 +501,4 @@ type SafePublishedReviewsResult = SafeReviewsResult<BusinessReviewsResult & Part
  */
 declare function getPublishedReviewsSafe(options: GetPublishedReviewsOptions & SafeReviewsOptions): Promise<SafePublishedReviewsResult>;
 
-export { type AccessTokenOptions, type BusinessReview, type BusinessReviewsResult, DEFAULT_AUTH_RETRY_MS, DEFAULT_MAX_PAGES, DEFAULT_MAX_STALE_MS, DEFAULT_PUBLISHED_REVIEWS_BASE_URL, DEFAULT_REPORT_INTERVAL_MS, DEFAULT_REQUEST_POLICY, GbpApiError, GbpAuthError, type GbpAuthErrorCode, GbpError, type GbpFailureReport, GbpPaginationError, GbpPublishedError, type GbpRequestOptions, GbpTimeoutError, type GetBusinessReviewsOptions, type GetPublishedReviewsOptions, PUBLISHED_REVIEWS_SCHEMA, type PublishedReviewsResult, type ReviewMedia, type ReviewOrder, type ReviewReply, type ReviewReplyState, type ReviewsSource, type SafePublishedReviewsResult, type SafeReviewsOptions, type SafeReviewsResult, getBusinessReviews, getBusinessReviewsSafe, getGoogleOAuthAccessToken, getPublishedReviews, getPublishedReviewsSafe, hasGoogleOAuthCredentials, invalidateAccessToken, isBusinessProfileConfigured, parseListReviewsResponse, parsePublishedReviews, parseRetryAfter, publishedReviewsUrl };
+export { type AccessTokenOptions, type BusinessReview, type BusinessReviewsResult, DEFAULT_AUTH_RETRY_MS, DEFAULT_MAX_PAGES, DEFAULT_MAX_STALE_MS, DEFAULT_PUBLISHED_REVIEWS_BASE_URL, DEFAULT_REPORT_INTERVAL_MS, DEFAULT_REQUEST_POLICY, type FacebookRecommendation, GbpApiError, GbpAuthError, type GbpAuthErrorCode, GbpError, type GbpFailureReport, GbpPaginationError, GbpPublishedError, type GbpRequestOptions, GbpTimeoutError, type GetBusinessReviewsOptions, type GetPublishedFacebookOptions, type GetPublishedReviewsOptions, PUBLISHED_REVIEWS_SCHEMA, type PublishedFacebookResult, type PublishedReviewsResult, type ReviewMedia, type ReviewOrder, type ReviewReply, type ReviewReplyState, type ReviewsSource, type SafePublishedReviewsResult, type SafeReviewsOptions, type SafeReviewsResult, getBusinessReviews, getBusinessReviewsSafe, getGoogleOAuthAccessToken, getPublishedFacebookRecommendations, getPublishedReviews, getPublishedReviewsSafe, hasGoogleOAuthCredentials, invalidateAccessToken, isBusinessProfileConfigured, parseListReviewsResponse, parsePublishedFacebook, parsePublishedReviews, parseRetryAfter, publishedFacebookUrl, publishedReviewsUrl };

package/dist/index.d.ts

@@ -282,6 +282,46 @@ declare function publishedReviewsUrl(client: string, baseUrl?: string): string;
  */
 declare function getPublishedReviews(options: GetPublishedReviewsOptions): Promise<PublishedReviewsResult>;
 
+interface FacebookRecommendation {
+    id: string;
+    comment: string;
+    /** ISO 8601. */
+    createdAt: string;
+}
+interface PublishedFacebookResult {
+    /** Meta's overall rating out of 5, or null when Meta gives none. */
+    rating: number | null;
+    /** Every recommendation on the Page, positive and negative. */
+    count: number;
+    /** The positive ones. */
+    recommends: number;
+    /** Positive recommendations with words, newest first. */
+    reviews: FacebookRecommendation[];
+    /** When the portal last read the Page in full. */
+    syncedAt: string;
+    publishedAt: string;
+}
+interface GetPublishedFacebookOptions {
+    /** The client's slug, e.g. `"rmp-electrical"`. */
+    client: string;
+    /** Default: `GBP_REVIEWS_BASE_URL`, else the Doman Digital address. */
+    baseUrl?: string;
+    /** Max recommendations to return. Default: all of them. */
+    limit?: number;
+    /** Cache hint passed to `fetch` for Next.js. Default: revalidate daily, tag `facebook-reviews`. */
+    next?: {
+        revalidate?: number;
+        tags?: string[];
+    };
+    request?: GbpRequestOptions;
+}
+/** Validate a published Facebook file. A malformed entry is skipped; a malformed file throws. */
+declare function parsePublishedFacebook(body: unknown, client: string): PublishedFacebookResult;
+/** The URL a client's Facebook file is read from. */
+declare function publishedFacebookUrl(client: string, baseUrl?: string): string;
+/** Fetch a client's published Facebook recommendations. Throws {@link GbpPublishedError} or `GbpTimeoutError`. */
+declare function getPublishedFacebookRecommendations(options: GetPublishedFacebookOptions): Promise<PublishedFacebookResult>;
+
 /**
  * Typed failures, so a site can tell "reauthorise the Google account" from
  * "Google is having a bad minute" from "our code looped", and log the
@@ -461,4 +501,4 @@ type SafePublishedReviewsResult = SafeReviewsResult<BusinessReviewsResult & Part
  */
 declare function getPublishedReviewsSafe(options: GetPublishedReviewsOptions & SafeReviewsOptions): Promise<SafePublishedReviewsResult>;
 
-export { type AccessTokenOptions, type BusinessReview, type BusinessReviewsResult, DEFAULT_AUTH_RETRY_MS, DEFAULT_MAX_PAGES, DEFAULT_MAX_STALE_MS, DEFAULT_PUBLISHED_REVIEWS_BASE_URL, DEFAULT_REPORT_INTERVAL_MS, DEFAULT_REQUEST_POLICY, GbpApiError, GbpAuthError, type GbpAuthErrorCode, GbpError, type GbpFailureReport, GbpPaginationError, GbpPublishedError, type GbpRequestOptions, GbpTimeoutError, type GetBusinessReviewsOptions, type GetPublishedReviewsOptions, PUBLISHED_REVIEWS_SCHEMA, type PublishedReviewsResult, type ReviewMedia, type ReviewOrder, type ReviewReply, type ReviewReplyState, type ReviewsSource, type SafePublishedReviewsResult, type SafeReviewsOptions, type SafeReviewsResult, getBusinessReviews, getBusinessReviewsSafe, getGoogleOAuthAccessToken, getPublishedReviews, getPublishedReviewsSafe, hasGoogleOAuthCredentials, invalidateAccessToken, isBusinessProfileConfigured, parseListReviewsResponse, parsePublishedReviews, parseRetryAfter, publishedReviewsUrl };
+export { type AccessTokenOptions, type BusinessReview, type BusinessReviewsResult, DEFAULT_AUTH_RETRY_MS, DEFAULT_MAX_PAGES, DEFAULT_MAX_STALE_MS, DEFAULT_PUBLISHED_REVIEWS_BASE_URL, DEFAULT_REPORT_INTERVAL_MS, DEFAULT_REQUEST_POLICY, type FacebookRecommendation, GbpApiError, GbpAuthError, type GbpAuthErrorCode, GbpError, type GbpFailureReport, GbpPaginationError, GbpPublishedError, type GbpRequestOptions, GbpTimeoutError, type GetBusinessReviewsOptions, type GetPublishedFacebookOptions, type GetPublishedReviewsOptions, PUBLISHED_REVIEWS_SCHEMA, type PublishedFacebookResult, type PublishedReviewsResult, type ReviewMedia, type ReviewOrder, type ReviewReply, type ReviewReplyState, type ReviewsSource, type SafePublishedReviewsResult, type SafeReviewsOptions, type SafeReviewsResult, getBusinessReviews, getBusinessReviewsSafe, getGoogleOAuthAccessToken, getPublishedFacebookRecommendations, getPublishedReviews, getPublishedReviewsSafe, hasGoogleOAuthCredentials, invalidateAccessToken, isBusinessProfileConfigured, parseListReviewsResponse, parsePublishedFacebook, parsePublishedReviews, parseRetryAfter, publishedFacebookUrl, publishedReviewsUrl };

package/dist/index.js

@@ -466,6 +466,58 @@ async function getPublishedReviews(options) {
   return { ...result, reviews: order === "shuffle" ? shuffle(reviews) : reviews };
 }
 
+// src/facebook-published.ts
+var isRecord3 = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+var isTime2 = (v) => typeof v === "string" && !Number.isNaN(Date.parse(v));
+var isCount = (v) => typeof v === "number" && Number.isInteger(v) && v >= 0;
+function parsePublishedFacebook(body, client) {
+  if (!isRecord3(body)) throw new GbpPublishedError("invalid", client, "the file is not an object");
+  if (body.schema !== PUBLISHED_REVIEWS_SCHEMA) throw new GbpPublishedError("unknown_schema", client, `schema ${String(body.schema)}`);
+  if (body.client !== client || body.source !== "facebook") {
+    throw new GbpPublishedError("invalid", client, `the file is for ${String(body.client)} (${String(body.source)})`);
+  }
+  const { rating, count, recommends } = body;
+  if (rating !== null && (typeof rating !== "number" || !(rating >= 0 && rating <= 5))) {
+    throw new GbpPublishedError("invalid", client, "rating out of range");
+  }
+  if (!isCount(count) || !isCount(recommends) || recommends > count) {
+    throw new GbpPublishedError("invalid", client, "count or recommends is not a whole number within the count");
+  }
+  if (!isTime2(body.synced_at) || !isTime2(body.published_at) || !Array.isArray(body.reviews)) {
+    throw new GbpPublishedError("invalid", client, "synced_at, published_at or reviews missing");
+  }
+  const reviews = body.reviews.flatMap(
+    (v) => isRecord3(v) && typeof v.id === "string" && typeof v.comment === "string" && v.comment && isTime2(v.createdAt) ? [{ id: v.id, comment: v.comment, createdAt: v.createdAt }] : []
+  );
+  return { rating, count, recommends, reviews, syncedAt: body.synced_at, publishedAt: body.published_at };
+}
+function publishedFacebookUrl(client, baseUrl) {
+  if (!/^[a-z0-9][a-z0-9-]{0,99}$/.test(client)) throw new RangeError(`not a client slug: ${client}`);
+  const base = (baseUrl ?? process.env.GBP_REVIEWS_BASE_URL ?? DEFAULT_PUBLISHED_REVIEWS_BASE_URL).replace(/\/+$/, "");
+  return `${base}/${client}.facebook.json`;
+}
+async function getPublishedFacebookRecommendations(options) {
+  const { client, limit, next, request } = options;
+  const url = publishedFacebookUrl(client, options.baseUrl);
+  const init = {
+    headers: { Accept: "application/json" },
+    next: next ?? { revalidate: 86400, tags: ["facebook-reviews"] }
+  };
+  const { response } = await fetchWithRetry(url, init, "reviews.facebook", resolvePolicy(request));
+  if (!response.ok) {
+    const body2 = excerpt(await readErrorBody(response), 120);
+    throw new GbpPublishedError("http", client, String(response.status), response.status, body2 || void 0);
+  }
+  let body;
+  try {
+    body = await response.json();
+  } catch {
+    throw new GbpPublishedError("invalid", client, "the file is not JSON");
+  }
+  const result = parsePublishedFacebook(body, client);
+  return limit === void 0 ? result : { ...result, reviews: result.reviews.slice(0, limit) };
+}
+
 // src/safe.ts
 var DEFAULT_REPORT_INTERVAL_MS = 60 * 60 * 1e3;
 var DEFAULT_MAX_STALE_MS = 30 * 24 * 60 * 60 * 1e3;
@@ -598,13 +650,16 @@ export {
   getBusinessReviews,
   getBusinessReviewsSafe,
   getGoogleOAuthAccessToken,
+  getPublishedFacebookRecommendations,
   getPublishedReviews,
   getPublishedReviewsSafe,
   hasGoogleOAuthCredentials,
   invalidateAccessToken,
   isBusinessProfileConfigured,
   parseListReviewsResponse,
+  parsePublishedFacebook,
   parsePublishedReviews,
   parseRetryAfter,
+  publishedFacebookUrl,
   publishedReviewsUrl
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@domandigital/gbp",
-  "version": "0.6.0",
+  "version": "0.7.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",