@growth-labs/seo 0.4.0 → 0.4.2

package/src/utils/rss.ts

@@ -0,0 +1,64 @@
+import type { SeoOptionsWithResolvedSite } from '../options.js'
+import type { ContentItem } from '../types.js'
+
+function escapeXml(str: string): string {
+	return str
+		.replace(/&/g, '&')
+		.replace(/</g, '&lt;')
+		.replace(/>/g, '&gt;')
+		.replace(/"/g, '&quot;')
+		.replace(/'/g, '&apos;')
+}
+
+function toRfc822(dateStr: string): string {
+	return new Date(dateStr).toUTCString()
+}
+
+export function generateRssFeed(
+	items: ContentItem[],
+	options: SeoOptionsWithResolvedSite,
+	description?: string,
+): string {
+	const { site, organization, defaults } = options
+	const feedDescription = description ?? organization.name
+	const language = defaults.locale.replace('_', '-').toLowerCase()
+	const lastBuildDate = new Date().toUTCString()
+
+	const itemsXml = items
+		.map((item) => {
+			const pubDate = item.datePublished ? toRfc822(item.datePublished) : ''
+			const pubDateTag = pubDate ? `\n      <pubDate>${escapeXml(pubDate)}</pubDate>` : ''
+			const descTag = item.description
+				? `\n      <description>${escapeXml(item.description)}</description>`
+				: ''
+			const creatorsXml = (item.authors ?? [])
+				.map((a) => `\n      <dc:creator>${escapeXml(a.name)}</dc:creator>`)
+				.join('')
+			const enclosureTag = item.audio
+				? `\n      <enclosure url="${escapeXml(item.audio.url)}" type="audio/mpeg" length="0"/>`
+				: ''
+
+			return `    <item>
+      <title>${escapeXml(item.title)}</title>
+      <link>${escapeXml(item.url)}</link>
+      <guid isPermaLink="true">${escapeXml(item.url)}</guid>${pubDateTag}${descTag}${creatorsXml}${enclosureTag}
+    </item>`
+		})
+		.join('\n')
+
+	return `<?xml version="1.0" encoding="UTF-8"?>
+<rss version="2.0"
+  xmlns:atom="http://www.w3.org/2005/Atom"
+  xmlns:dc="http://purl.org/dc/elements/1.1/"
+  xmlns:content="http://purl.org/rss/1.0/modules/content/">
+  <channel>
+    <title>${escapeXml(organization.name)}</title>
+    <description>${escapeXml(feedDescription)}</description>
+    <link>${escapeXml(site)}</link>
+    <language>${escapeXml(language)}</language>
+    <atom:link href="${escapeXml(`${site}/feed.xml`)}" rel="self" type="application/rss+xml"/>
+    <lastBuildDate>${lastBuildDate}</lastBuildDate>
+${itemsXml}
+  </channel>
+</rss>`
+}

package/src/utils/seo-head.ts

@@ -0,0 +1,81 @@
+import type { SeoOptionsWithResolvedSite } from '../options.js'
+import type { ContentItem, JsonLdObject } from '../types.js'
+import {
+	generateArticleJsonLd,
+	generateAudioJsonLd,
+	generateOrganizationJsonLd,
+	generateProductJsonLd,
+	generateVideoJsonLd,
+	generateWebSiteJsonLd,
+} from './json-ld/index.js'
+import type { OgVariant } from './meta.js'
+
+interface BuildSeoHeadTitleDescriptionOptions {
+	item?: ContentItem
+	options: SeoOptionsWithResolvedSite
+	title?: string
+	description?: string
+}
+
+interface BuildSeoHeadJsonLdOptions {
+	item?: ContentItem
+	options: SeoOptionsWithResolvedSite
+	variant: OgVariant
+	emitJsonLd?: boolean
+}
+
+export function buildSeoHeadTitleDescription({
+	item,
+	options,
+	title,
+	description,
+}: BuildSeoHeadTitleDescriptionOptions): { title: string; description?: string } {
+	const baseTitle = title ?? item?.title ?? options.organization.name
+	const suffix = options.defaults.titleSuffix
+	const resolvedTitle = suffix && !baseTitle.endsWith(suffix) ? `${baseTitle}${suffix}` : baseTitle
+	const resolvedDescription = description ?? item?.description
+
+	return {
+		title: resolvedTitle,
+		description: resolvedDescription,
+	}
+}
+
+export function buildSeoHeadJsonLd({
+	item,
+	options,
+	variant,
+	emitJsonLd = true,
+}: BuildSeoHeadJsonLdOptions): JsonLdObject[] {
+	if (!emitJsonLd) return []
+
+	if (!item) {
+		return [generateWebSiteJsonLd(options), generateOrganizationJsonLd(options)]
+	}
+
+	const jsonLd: JsonLdObject[] = []
+
+	if (variant === 'article') {
+		jsonLd.push(generateArticleJsonLd(item, options))
+	} else if (variant === 'product' && item.product) {
+		jsonLd.push(generateProductJsonLd(item.product, item.url, options))
+	} else if (variant === 'website') {
+		jsonLd.push(generateWebSiteJsonLd(options))
+	}
+
+	if (item.video) {
+		jsonLd.push(generateVideoJsonLd(item))
+	}
+
+	if (item.audio) {
+		jsonLd.push(
+			generateAudioJsonLd(item.audio, {
+				title: item.title,
+				datePublished: item.datePublished,
+				articleUrl: item.url,
+			}),
+		)
+	}
+
+	return jsonLd
+}

package/src/utils/sitemap-markdown.ts

@@ -0,0 +1,80 @@
+import type { ContentItem } from '../types.js'
+import { forMarkdownSitemap } from './content-filter.js'
+
+function escapeXml(str: string): string {
+	return str
+		.replace(/&/g, '&')
+		.replace(/</g, '&lt;')
+		.replace(/>/g, '&gt;')
+		.replace(/"/g, '&quot;')
+		.replace(/'/g, '&apos;')
+}
+
+/**
+ * Map an article URL to its primary markdown twin URL. Default appends `.md` to
+ * the URL, collapsing any trailing slash.
+ *
+ * Consumers can override via `aeoTwins.twinUrl` in config; when overridden, the
+ * same function drives both twin emission and sitemap discovery URL.
+ */
+function defaultTwinUrl(articleUrl: string): string {
+	const trimmed = articleUrl.replace(/\/+$/, '')
+	return `${trimmed}.md`
+}
+
+export interface MarkdownSitemapEntry {
+	primaryTwinUrl: string
+	lastmod?: string
+	// Optional: freshLayer-sourced override (for when R2 has a later lastModified
+	// than the item's dateModified at build time).
+	freshLayerLastModified?: string
+}
+
+export interface GenerateMarkdownSitemapOptions {
+	items: ContentItem[]
+	twinUrl?: (articleUrl: string) => string
+	// Optional: per-slug R2 lastmod overrides (keyed by the article URL).
+	// When present, lastmod reflects max(item.dateModified, freshLayer.lastModified).
+	freshLayerLastmod?: Map<string, string>
+}
+
+/**
+ * Generate `/sitemap-markdown.xml` — the AEO twin URL sitemap.
+ *
+ * Google discovers URLs via crawlable links and sitemaps, not MIME-probing. This
+ * sitemap lists every emitted `.md` twin URL so the markdown corpus is discoverable
+ * the same way HTML pages are.
+ *
+ * Filtering rules (centralized in content-filter.forMarkdownSitemap):
+ *   - Members items excluded unconditionally (no .md twin exists for them).
+ *   - Public items with `includeInSitemap: false` excluded.
+ */
+export function generateMarkdownSitemap({
+	items,
+	twinUrl = defaultTwinUrl,
+	freshLayerLastmod,
+}: GenerateMarkdownSitemapOptions): string {
+	const filtered = forMarkdownSitemap(items)
+	const entries = filtered
+		.map((item) => {
+			const url = twinUrl(item.url)
+			const freshMod = freshLayerLastmod?.get(item.url)
+			const buildMod = item.dateModified ?? item.datePublished ?? ''
+			// Pick the most recent of build-time and fresh-layer lastmod.
+			const lastmod = pickLatest(freshMod, buildMod)
+			const lastmodTag = lastmod ? `\n    <lastmod>${escapeXml(lastmod)}</lastmod>` : ''
+			return `  <url>\n    <loc>${escapeXml(url)}</loc>${lastmodTag}\n  </url>`
+		})
+		.join('\n')
+
+	return `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${entries}
+</urlset>`
+}
+
+function pickLatest(a: string | undefined, b: string | undefined): string | undefined {
+	if (!a) return b
+	if (!b) return a
+	return new Date(a).getTime() >= new Date(b).getTime() ? a : b
+}

package/src/utils/sitemap.ts

@@ -0,0 +1,169 @@
+import type { ResolvedSeoOptions } from '../options.js'
+import type { ContentItem } from '../types.js'
+
+export const SITEMAP_INDEX_PATH = '/sitemap-index.xml'
+
+export interface SitemapEntry {
+	loc: string
+	lastmod?: string
+}
+
+function escapeXml(str: string): string {
+	return str
+		.replace(/&/g, '&')
+		.replace(/</g, '&lt;')
+		.replace(/>/g, '&gt;')
+		.replace(/"/g, '&quot;')
+		.replace(/'/g, '&apos;')
+}
+
+export function generateSitemapIndex(sitemaps: SitemapEntry[]): string {
+	const entries = sitemaps
+		.map((s) => {
+			const lastmod = s.lastmod ? `\n    <lastmod>${escapeXml(s.lastmod)}</lastmod>` : ''
+			return `  <sitemap>\n    <loc>${escapeXml(s.loc)}</loc>${lastmod}\n  </sitemap>`
+		})
+		.join('\n')
+
+	return `<?xml version="1.0" encoding="UTF-8"?>
+<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${entries}
+</sitemapindex>`
+}
+
+function isWithin48Hours(dateStr: string): boolean {
+	const published = new Date(dateStr)
+	const now = new Date()
+	const diff = now.getTime() - published.getTime()
+	return diff <= 48 * 60 * 60 * 1000
+}
+
+export function generateArticleSitemap(
+	articles: ContentItem[],
+	options: ResolvedSeoOptions,
+): string {
+	const { googleNews, organization } = options
+
+	const entries = articles
+		.map((item) => {
+			const lastmod = item.dateModified ?? item.datePublished ?? ''
+			const lastmodTag = lastmod ? `\n    <lastmod>${escapeXml(lastmod)}</lastmod>` : ''
+
+			// image:image
+			const imageTag = item.image
+				? `\n    <image:image>\n      <image:loc>${escapeXml(item.image)}</image:loc>\n    </image:image>`
+				: ''
+
+			// news:news (only for recent articles when googleNews enabled)
+			let newsTag = ''
+			if (googleNews && item.datePublished && isWithin48Hours(item.datePublished)) {
+				newsTag = `\n    <news:news>
+      <news:publication>
+        <news:name>${escapeXml(organization.name)}</news:name>
+        <news:language>${escapeXml('en')}</news:language>
+      </news:publication>
+      <news:publication_date>${escapeXml(item.datePublished)}</news:publication_date>
+      <news:title>${escapeXml(item.title)}</news:title>
+    </news:news>`
+			}
+
+			// xhtml:link hreflang
+			const hreflangTags = (item.alternateLocales ?? [])
+				.map(
+					(alt) =>
+						`\n    <xhtml:link rel="alternate" hreflang="${escapeXml(alt.lang)}" href="${escapeXml(alt.url)}"/>`,
+				)
+				.join('')
+
+			return `  <url>\n    <loc>${escapeXml(item.url)}</loc>${lastmodTag}${imageTag}${newsTag}${hreflangTags}\n  </url>`
+		})
+		.join('\n')
+
+	return `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
+  xmlns:image="http://www.google.com/schemas/sitemap-image/1.1"
+  xmlns:news="http://www.google.com/schemas/sitemap-news/0.9"
+  xmlns:xhtml="http://www.w3.org/1999/xhtml">
+${entries}
+</urlset>`
+}
+
+export function generatePagesSitemap(pages: ContentItem[]): string {
+	const entries = pages
+		.map((item) => {
+			const lastmod = item.dateModified ?? item.datePublished ?? ''
+			const lastmodTag = lastmod ? `\n    <lastmod>${escapeXml(lastmod)}</lastmod>` : ''
+			return `  <url>\n    <loc>${escapeXml(item.url)}</loc>${lastmodTag}\n  </url>`
+		})
+		.join('\n')
+
+	return `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${entries}
+</urlset>`
+}
+
+export function generateVideoSitemap(items: ContentItem[]): string {
+	const entries = items
+		.filter((item) => item.video)
+		.map((item) => {
+			const v = item.video!
+			const contentUrlTag = v.contentUrl
+				? `\n      <video:content_loc>${escapeXml(v.contentUrl)}</video:content_loc>`
+				: ''
+			const embedUrlTag = v.embedUrl
+				? `\n      <video:player_loc>${escapeXml(v.embedUrl)}</video:player_loc>`
+				: ''
+			const descriptionTag = item.description
+				? `\n      <video:description>${escapeXml(item.description)}</video:description>`
+				: ''
+			const durationTag = v.duration
+				? `\n      <video:duration>${escapeXml(v.duration)}</video:duration>`
+				: ''
+			const pubDateTag = item.datePublished
+				? `\n      <video:publication_date>${escapeXml(item.datePublished)}</video:publication_date>`
+				: ''
+
+			return `  <url>
+    <loc>${escapeXml(item.url)}</loc>
+    <video:video>
+      <video:thumbnail_loc>${escapeXml(v.thumbnailUrl)}</video:thumbnail_loc>
+      <video:title>${escapeXml(item.title)}</video:title>${descriptionTag}${contentUrlTag}${embedUrlTag}${durationTag}${pubDateTag}
+    </video:video>
+  </url>`
+		})
+		.join('\n')
+
+	return `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
+  xmlns:video="http://www.google.com/schemas/sitemap-video/1.1">
+${entries}
+</urlset>`
+}
+
+export function generateProductSitemap(items: ContentItem[]): string {
+	const entries = items
+		.filter((item) => item.product)
+		.map((item) => {
+			const p = item.product!
+			const images = p.images.length > 0 ? p.images : item.image ? [item.image] : []
+			const imageTags = images
+				.map(
+					(img) =>
+						`\n    <image:image>\n      <image:loc>${escapeXml(img)}</image:loc>\n    </image:image>`,
+				)
+				.join('')
+
+			const lastmod = item.dateModified ?? item.datePublished ?? ''
+			const lastmodTag = lastmod ? `\n    <lastmod>${escapeXml(lastmod)}</lastmod>` : ''
+
+			return `  <url>\n    <loc>${escapeXml(item.url)}</loc>${lastmodTag}${imageTags}\n  </url>`
+		})
+		.join('\n')
+
+	return `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
+  xmlns:image="http://www.google.com/schemas/sitemap-image/1.1">
+${entries}
+</urlset>`
+}

package/src/utils/staleness.ts

@@ -0,0 +1,61 @@
+import type { ContentItem } from '../types.js'
+
+/**
+ * Compute a SHA-256 content hash for staleness validation. Uses `crypto.subtle`
+ * so the same implementation runs in Node (build-time) and Workers (runtime).
+ * Never node:crypto.
+ *
+ * The hash input is deterministic: item title + description + rendered body.
+ * Order matters: changes to any field produce a new hash. Whitespace-insensitive
+ * if the consumer normalizes before calling.
+ */
+export async function computeContentHash(
+	item: Pick<ContentItem, 'title' | 'description'>,
+	renderedBody: string,
+): Promise<string> {
+	const input = [item.title, item.description ?? '', renderedBody].join('\u0001')
+	const bytes = new TextEncoder().encode(input)
+	const digest = await crypto.subtle.digest('SHA-256', bytes)
+	return toHex(new Uint8Array(digest))
+}
+
+function toHex(bytes: Uint8Array): string {
+	let out = ''
+	for (const b of bytes) {
+		out += b.toString(16).padStart(2, '0')
+	}
+	return out
+}
+
+export interface StalenessDriftRecord {
+	url: string
+	expectedHash: string
+	actualHash: string
+}
+
+/**
+ * Compare expected-vs-actual content hashes across a batch of items. Used by the
+ * build-time validator to detect drift between two `contentProvider` calls made
+ * during the same build (rare but possible when provider pulls from a mutating
+ * source).
+ *
+ * Returns the list of items whose hash differs. Callers log these as warnings;
+ * the build does NOT fail on drift (spec 1403: "does not fail the build").
+ */
+export async function checkStaleness(
+	items: ContentItem[],
+	expectedHashes: Map<string, string>,
+	renderBody: (item: ContentItem) => string | Promise<string>,
+): Promise<StalenessDriftRecord[]> {
+	const drift: StalenessDriftRecord[] = []
+	for (const item of items) {
+		const expected = expectedHashes.get(item.url)
+		if (!expected) continue
+		const body = await renderBody(item)
+		const actual = await computeContentHash(item, body)
+		if (actual !== expected) {
+			drift.push({ url: item.url, expectedHash: expected, actualHash: actual })
+		}
+	}
+	return drift
+}