@tribe-nest/forge 1.13.0

package/src/utils/structuredData.ts

@@ -0,0 +1,126 @@
+import type { WebPage } from "../types";
+
+/**
+ * Generates Organization/Person JSON-LD for every page.
+ */
+export function buildOrganizationSchema(webPage: WebPage, origin: string) {
+  const socialLinks = webPage.themeSettings.socialLinks || [];
+  return {
+    "@context": "https://schema.org",
+    "@type": "Organization",
+    name: webPage.profile.name,
+    url: origin,
+    ...(webPage.themeSettings.header?.logo
+      ? { logo: webPage.themeSettings.header.logo }
+      : {}),
+    ...(socialLinks.length > 0
+      ? { sameAs: socialLinks.map((l: { href: string }) => l.href).filter(Boolean) }
+      : {}),
+  };
+}
+
+/**
+ * Generates WebPage JSON-LD.
+ */
+export function buildWebPageSchema(
+  webPage: WebPage,
+  canonicalUrl: string,
+) {
+  return {
+    "@context": "https://schema.org",
+    "@type": "WebPage",
+    name: webPage.page.title,
+    description: webPage.page.description || undefined,
+    url: canonicalUrl,
+  };
+}
+
+/**
+ * Generates a JSON-LD script tag string for embedding in head.
+ */
+export function buildJsonLdScript(...schemas: Record<string, unknown>[]): string {
+  return schemas
+    .map((schema) => JSON.stringify(schema))
+    .map((json) => `<script type="application/ld+json">${json}</script>`)
+    .join("");
+}
+
+// ---- Reviews / AggregateRating ------------------------------------------------
+
+export type ReviewSchemaEntityType = "Product" | "Course" | "Service";
+
+export interface ReviewSchemaAggregate {
+  avgRating: number;
+  reviewCount: number;
+}
+
+export interface ReviewSchemaReview {
+  rating: number;
+  title?: string | null;
+  body?: string | null;
+  reviewerName?: string | null;
+  publishedAt?: string | null;
+}
+
+export interface EntityReviewSchemaInput {
+  /** schema.org type of the reviewed thing. */
+  type: ReviewSchemaEntityType;
+  name: string;
+  description?: string | null;
+  image?: string | null;
+  url?: string | null;
+  aggregate?: ReviewSchemaAggregate | null;
+  /** A sample of published reviews (top-N is fine — Google reads a subset). */
+  reviews?: ReviewSchemaReview[];
+  /** Optional offer (price in major units + ISO currency) for Product rich results. */
+  offer?: { price: number; currency: string } | null;
+}
+
+/**
+ * Generates schema.org JSON-LD for a reviewed entity: the entity node with an
+ * `AggregateRating` and a sample of `Review` children — the shape Google reads
+ * for star rich snippets. Returns null when there is no aggregate (no
+ * published reviews), so callers can skip the script tag entirely.
+ */
+export function buildEntityReviewSchema(input: EntityReviewSchemaInput): Record<string, unknown> | null {
+  const { aggregate } = input;
+  if (!aggregate || aggregate.reviewCount <= 0) return null;
+
+  const reviews = (input.reviews ?? [])
+    .filter((r) => r.rating >= 1 && r.rating <= 5)
+    .slice(0, 10)
+    .map((r) => ({
+      "@type": "Review",
+      reviewRating: { "@type": "Rating", ratingValue: r.rating, bestRating: 5, worstRating: 1 },
+      author: { "@type": "Person", name: r.reviewerName || "Verified Buyer" },
+      ...(r.title ? { name: r.title } : {}),
+      ...(r.body ? { reviewBody: r.body } : {}),
+      ...(r.publishedAt ? { datePublished: r.publishedAt } : {}),
+    }));
+
+  return {
+    "@context": "https://schema.org",
+    "@type": input.type,
+    name: input.name,
+    ...(input.description ? { description: input.description } : {}),
+    ...(input.image ? { image: input.image } : {}),
+    ...(input.url ? { url: input.url } : {}),
+    aggregateRating: {
+      "@type": "AggregateRating",
+      ratingValue: Number(aggregate.avgRating.toFixed(2)),
+      reviewCount: aggregate.reviewCount,
+      bestRating: 5,
+      worstRating: 1,
+    },
+    ...(reviews.length > 0 ? { review: reviews } : {}),
+    ...(input.offer
+      ? {
+          offers: {
+            "@type": "Offer",
+            price: input.offer.price,
+            priceCurrency: input.offer.currency,
+          },
+        }
+      : {}),
+  };
+}