feat(seo): JSON-LD structured data for course pages (#424) (#486)

- Course + Offer + AggregateRating on the public course detail page,
  built from data the page already fetches (no new queries)
- ItemList on the unfiltered catalog; EducationalOrganization on
  tenant landing pages (both Puck and fallback branches)
- Extract the deterministic cheapest-paid product pick (PR #422) into
  lib/course-pricing.ts and use it on the catalog too, so cards,
  detail page, and the structured Offer always agree on price
- XSS-safe serializer escapes <, >, & as unicode sequences


Claude-Session: https://claude.ai/code/session_018NavuM4mERjDbemsms8ST8

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: guillermoscript

app/[locale]/(public)/courses/[id]/page.tsx

@@ -25,7 +25,9 @@ import { getTranslations } from 'next-intl/server';
 import { getCurrentTenantId, getCurrentUserId } from '@/lib/supabase/tenant'
 import { hasCourseAccess } from '@/lib/services/course-access'
 import type { Metadata } from 'next';
-import { buildPageMetadata } from '@/lib/seo';
+import { buildPageMetadata, getSeoContext } from '@/lib/seo';
+import { pickCourseProduct } from '@/lib/course-pricing';
+import { JsonLd, courseJsonLd } from '@/lib/structured-data';
 import { AutoFreeEnrollButton, FreeEnrollButton } from '@/components/public/free-enroll-button';
 import { PlanEnrollButton } from '@/components/public/plan-enroll-button';
 import { createAdminClient } from '@/lib/supabase/admin';
@@ -83,7 +85,7 @@ interface Lesson {
 }
 
 export default async function CourseDetailsPage(props: {
-    params: Promise<{ id: string }>;
+    params: Promise<{ id: string; locale: string }>;
     searchParams: Promise<{ enroll?: string }>;
 }) {
     const [params, searchParams, t, supabase, userId, tenantId] = await Promise.all([
@@ -167,13 +169,14 @@ export default async function CourseDetailsPage(props: {
         })()
         : Promise.resolve(false);
 
-    const [{ data: author }, hasAccess, { data: productCourses }, planCoversCourse, socialProof, { data: lessonRows }] = await Promise.all([
+    const [{ data: author }, hasAccess, { data: productCourses }, planCoversCourse, socialProof, { data: lessonRows }, seo] = await Promise.all([
         authorPromise,
         accessPromise,
         productCoursesPromise,
         planCoveragePromise,
         getCourseSocialProof(courseId, tenantId),
         lessonsPromise,
+        getSeoContext(),
     ]);
 
     const { averageRating, reviewCount, studentCount, recentReviews } = socialProof;
@@ -184,14 +187,9 @@ export default async function CourseDetailsPage(props: {
     const estimatedMinutes = (totalLessons * 10) % 60;
 
     type CourseProduct = { price: number | string; currency: string | null };
-    const linkedProducts = (productCourses ?? [])
-        .map(({ product }) => product as unknown as CourseProduct | null)
-        .filter((product): product is CourseProduct => product !== null);
-    // Deterministic pick: cheapest paid product (catalog cards should agree).
-    const paidProducts = linkedProducts
-        .filter((product) => Number(product.price) > 0)
-        .sort((a, b) => Number(a.price) - Number(b.price));
-    const courseProduct = paidProducts[0] ?? linkedProducts[0];
+    const courseProduct = pickCourseProduct(
+        (productCourses ?? []).map(({ product }) => product as unknown as CourseProduct | null)
+    );
     const isFree = !courseProduct || Number(courseProduct.price) === 0;
     const priceDisplay = isFree
         ? t('pricing.free')
@@ -213,8 +211,27 @@ export default async function CourseDetailsPage(props: {
         ? new Intl.DateTimeFormat(undefined, { year: 'numeric', month: 'long', day: 'numeric' }).format(new Date(course.published_at))
         : null;
 
+    // schema.org Course rich-result markup. Offer mirrors the deterministic
+    // product pick above so the structured price always matches the page.
+    const courseUrl = `${seo.baseUrl}/${params.locale}/courses/${course.course_id}`;
+    const structuredData = courseJsonLd({
+        name: course.title,
+        description: course.description,
+        url: courseUrl,
+        image: course.thumbnail_url,
+        providerName: seo.siteName,
+        providerUrl: seo.baseUrl,
+        datePublished: course.published_at,
+        price: !isFree && courseProduct ? Number(courseProduct.price) : null,
+        currency: !isFree && courseProduct ? courseProduct.currency : null,
+        isFree,
+        averageRating,
+        reviewCount,
+    });
+
     return (
         <div className="min-h-screen bg-[#09090b] text-zinc-100 font-sans">
+            <JsonLd data={structuredData} />
             {/* Breadcrumbs */}
             <nav aria-label="Breadcrumb" className="bg-[#18181b]/50 border-b border-zinc-800">
                 <div className="container mx-auto px-4 py-3 flex items-center gap-2 text-sm text-zinc-400">

app/[locale]/(public)/courses/page.tsx

@@ -6,7 +6,9 @@ import { CourseSearchBar } from "@/components/shared/course-search-bar";
 import { Search } from "lucide-react";
 import { getTranslations } from 'next-intl/server';
 import type { Metadata } from 'next';
-import { buildPageMetadata } from '@/lib/seo';
+import { buildPageMetadata, getSeoContext } from '@/lib/seo';
+import { pickCourseProduct, type LinkedProduct } from '@/lib/course-pricing';
+import { JsonLd, itemListJsonLd } from '@/lib/structured-data';
 
 export const dynamic = 'force-dynamic';
 
@@ -17,10 +19,13 @@ export async function generateMetadata({ params }: { params: Promise<{ locale: s
 }
 
 export default async function CoursesPage({
+    params,
     searchParams,
 }: {
+    params: Promise<{ locale: string }>
     searchParams: Promise<{ search?: string; category?: string }>
 }) {
+    const { locale } = await params;
     const { search, category } = await searchParams;
     const t = await getTranslations('coursesCatalog');
     const tSearch = await getTranslations('courseSearch');
@@ -77,7 +82,7 @@ export default async function CoursesPage({
 
     // Fetch product prices for all courses in one query
     const courseIds = courses?.map(c => c.course_id) || [];
-    let productMap: Record<number, { price: number; currency: string }> = {};
+    const productMap: Record<number, { price: number; currency: string | null }> = {};
 
     // Published-lesson counts via admin client: the anon role can only read
     // preview lessons (RLS), so a nested select would undercount for visitors.
@@ -101,12 +106,19 @@ export default async function CoursesPage({
             .in('course_id', courseIds);
 
         if (productCourses) {
+            const productsByCourse: Record<number, LinkedProduct[]> = {};
             for (const pc of productCourses) {
-                const product = pc.product as any;
-                if (product && !productMap[pc.course_id]) {
-                    productMap[pc.course_id] = {
-                        price: parseFloat(product.price),
-                        currency: product.currency
+                const product = pc.product as unknown as LinkedProduct | null;
+                if (product) (productsByCourse[pc.course_id] ??= []).push(product);
+            }
+            // Same deterministic pick as the course detail page (cheapest paid
+            // product), so cards and detail never show different prices.
+            for (const [courseId, products] of Object.entries(productsByCourse)) {
+                const picked = pickCourseProduct(products);
+                if (picked) {
+                    productMap[Number(courseId)] = {
+                        price: Number(picked.price),
+                        currency: picked.currency
                     };
                 }
             }
@@ -132,8 +144,19 @@ export default async function CoursesPage({
 
     const hasActiveFilters = sanitizedSearch || category;
 
+    // ItemList rich-result markup for the unfiltered catalog only — filtered
+    // views are ephemeral search results, not the canonical course list.
+    const { baseUrl } = await getSeoContext();
+    const catalogStructuredData = !hasActiveFilters && enrichedCourses.length > 0
+        ? itemListJsonLd(enrichedCourses.map((course) => ({
+            name: course.title,
+            url: `${baseUrl}/${locale}/courses/${course.course_id}`,
+        })))
+        : null;
+
     return (
         <div className="min-h-screen bg-[#09090b] text-zinc-100">
+            {catalogStructuredData && <JsonLd data={catalogStructuredData} />}
             <div className="container mx-auto py-16 px-4 md:px-8">
                 {/* Header */}
                 <div className="mb-12 space-y-4 max-w-2xl">

app/[locale]/(public)/page.tsx

@@ -35,7 +35,8 @@ import { createClient } from "@/lib/supabase/server";
 import { createAdminClient } from "@/lib/supabase/admin";
 import { SchoolLandingPage } from "@/components/public/school-landing-page";
 import type { Metadata } from "next";
-import { buildPageMetadata } from "@/lib/seo";
+import { buildPageMetadata, getRequestBaseUrl } from "@/lib/seo";
+import { JsonLd, organizationJsonLd } from "@/lib/structured-data";
 import { PuckPageRenderer } from "@/components/public/landing-page/puck-page-renderer";
 import { getLandingData } from "@/lib/puck/utils/landing-data";
 
@@ -52,8 +53,13 @@ export default async function LandingPage() {
   // Branch to school landing page on subdomains
   const tenantId = await getCurrentTenantId()
   if (tenantId !== DEFAULT_TENANT_ID) {
-    const [tenant, supabase] = await Promise.all([getCurrentTenant(), createClient()])
+    const [tenant, supabase, baseUrl] = await Promise.all([getCurrentTenant(), createClient(), getRequestBaseUrl()])
     if (tenant) {
+      const orgStructuredData = organizationJsonLd({
+        name: tenant.name,
+        url: baseUrl,
+        logo: tenant.logo_url,
+      })
       // Check if tenant has a paid plan with a custom active landing page
       if (PAID_PLANS.includes(tenant.plan)) {
         const adminClient = createAdminClient()
@@ -66,7 +72,12 @@ export default async function LandingPage() {
           .maybeSingle()
         if (customPage?.puck_data && typeof customPage.puck_data === 'object') {
           const landingData = await getLandingData(tenantId)
-          return <PuckPageRenderer data={customPage.puck_data as any} landingData={landingData} />
+          return (
+            <>
+              <JsonLd data={orgStructuredData} />
+              <PuckPageRenderer data={customPage.puck_data as any} landingData={landingData} />
+            </>
+          )
         }
       }
 
@@ -78,7 +89,12 @@ export default async function LandingPage() {
         .eq('status', 'active')
         .order('created_at', { ascending: false })
         .limit(9)
-      return <SchoolLandingPage tenant={tenant} products={products ?? []} />
+      return (
+        <>
+          <JsonLd data={orgStructuredData} />
+          <SchoolLandingPage tenant={tenant} products={products ?? []} />
+        </>
+      )
     }
   }
 

lib/course-pricing.ts

@@ -0,0 +1,19 @@
+export interface LinkedProduct {
+  price: number | string
+  currency: string | null
+}
+
+/**
+ * Deterministic product pick for a course linked to multiple products
+ * (product_courses is many-to-many — never assume one row): the cheapest
+ * paid product wins, else the first linked product, else null. The catalog
+ * cards, the course detail page, and the JSON-LD Offer must all agree on
+ * the price a visitor sees, so they all go through this helper.
+ */
+export function pickCourseProduct<T extends LinkedProduct>(products: (T | null | undefined)[]): T | null {
+  const linked = products.filter((product): product is T => product != null)
+  const paid = linked
+    .filter((product) => Number(product.price) > 0)
+    .sort((a, b) => Number(a.price) - Number(b.price))
+  return paid[0] ?? linked[0] ?? null
+}

lib/structured-data.tsx

@@ -0,0 +1,127 @@
+import type { ReactElement } from 'react'
+
+/**
+ * schema.org JSON-LD builders + renderer for public SEO surfaces.
+ * Builders return plain objects; <JsonLd> serializes them into a
+ * <script type="application/ld+json"> tag with XSS-safe escaping.
+ */
+
+type JsonLdNode = Record<string, unknown>
+
+/**
+ * Serialize for embedding inside a <script> tag. User-controlled strings
+ * (course titles, descriptions, tenant names) could contain `</script>` or
+ * HTML — escape the dangerous characters as unicode sequences, which JSON
+ * parsers (and search engines) read identically.
+ */
+export function serializeJsonLd(data: JsonLdNode): string {
+  return JSON.stringify(data)
+    .replace(/</g, '\\u003c')
+    .replace(/>/g, '\\u003e')
+    .replace(/&/g, '\\u0026')
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029')
+}
+
+export function JsonLd({ data }: { data: JsonLdNode }): ReactElement {
+  return (
+    <script
+      type="application/ld+json"
+      dangerouslySetInnerHTML={{ __html: serializeJsonLd(data) }}
+    />
+  )
+}
+
+interface CourseJsonLdInput {
+  name: string
+  description?: string | null
+  /** Absolute URL of the course page. */
+  url: string
+  image?: string | null
+  providerName: string
+  /** Absolute base URL of the tenant site. */
+  providerUrl: string
+  datePublished?: string | null
+  /** Real price/currency of the deterministic product pick; null when free. */
+  price?: number | null
+  currency?: string | null
+  isFree: boolean
+  /** Only emitted when there is at least one review. */
+  averageRating?: number | null
+  reviewCount?: number
+}
+
+export function courseJsonLd(input: CourseJsonLdInput): JsonLdNode {
+  const node: JsonLdNode = {
+    '@context': 'https://schema.org',
+    '@type': 'Course',
+    name: input.name,
+    url: input.url,
+    provider: {
+      '@type': 'EducationalOrganization',
+      name: input.providerName,
+      url: input.providerUrl,
+    },
+  }
+  if (input.description) node.description = input.description
+  if (input.image) node.image = input.image
+  if (input.datePublished) node.datePublished = input.datePublished
+
+  if (input.isFree) {
+    node.isAccessibleForFree = true
+    node.offers = { '@type': 'Offer', category: 'Free', price: 0 }
+  } else if (input.price != null && input.currency) {
+    node.offers = {
+      '@type': 'Offer',
+      category: 'Paid',
+      price: input.price,
+      priceCurrency: input.currency.toUpperCase(),
+      availability: 'https://schema.org/InStock',
+      url: input.url,
+    }
+  }
+
+  if (
+    input.averageRating != null &&
+    typeof input.reviewCount === 'number' &&
+    input.reviewCount > 0
+  ) {
+    node.aggregateRating = {
+      '@type': 'AggregateRating',
+      ratingValue: Math.round(input.averageRating * 10) / 10,
+      reviewCount: input.reviewCount,
+      bestRating: 5,
+      worstRating: 1,
+    }
+  }
+
+  return node
+}
+
+export function itemListJsonLd(items: { url: string; name: string }[]): JsonLdNode {
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'ItemList',
+    itemListElement: items.map((item, index) => ({
+      '@type': 'ListItem',
+      position: index + 1,
+      name: item.name,
+      url: item.url,
+    })),
+  }
+}
+
+export function organizationJsonLd(input: {
+  name: string
+  url: string
+  logo?: string | null
+}): JsonLdNode {
+  const node: JsonLdNode = {
+    '@context': 'https://schema.org',
+    '@type': 'EducationalOrganization',
+    name: input.name,
+    url: input.url,
+  }
+  if (input.logo) node.logo = input.logo
+  return node
+}