@growth-labs/seo 0.4.0 → 0.4.2

package/src/routes/podcast-narration.ts

@@ -0,0 +1,45 @@
+import 'virtual:growth-labs/seo/config'
+import type { APIRoute } from 'astro'
+import { getConfig, getContentProvider } from '../_internal/state.js'
+import { resolveSeoConfig } from '../site-url.js'
+import type { ContentItem } from '../types.js'
+import { generatePodcastFeed } from '../utils/podcast.js'
+
+export const prerender = false
+
+export const GET: APIRoute = async (context) => {
+	const config = resolveSeoConfig(getConfig())
+	const contentProvider = getContentProvider()
+
+	let articles: ContentItem[] = []
+	if (contentProvider) {
+		try {
+			articles = await contentProvider({ type: 'articles' }, context as any)
+		} catch {}
+	}
+
+	const withAudio = articles.filter((a) => a.audio)
+
+	const narrationPodcastConfig = {
+		...config,
+		podcast: {
+			enabled: true,
+			title: `${config.organization.name} — Listen`,
+			description: `Narrated articles from ${config.organization.name}`,
+			author: config.audioNarration?.narratorName ?? config.organization.name,
+			email: '',
+			image: config.organization.logo,
+			category: 'News',
+			language: config.defaults.locale.split('_')[0] ?? 'en',
+			explicit: false,
+			feedPath: config.audioNarration?.podcastFeedPath ?? '/listen.xml',
+			type: 'episodic' as const,
+		},
+	}
+
+	const xml = generatePodcastFeed(withAudio, narrationPodcastConfig)
+
+	return new Response(xml, {
+		headers: { 'Content-Type': 'application/rss+xml; charset=utf-8' },
+	})
+}

package/src/routes/podcast.ts

@@ -0,0 +1,27 @@
+import 'virtual:growth-labs/seo/config'
+import type { APIRoute } from 'astro'
+import { getConfig, getContentProvider } from '../_internal/state.js'
+import { resolveSeoConfig } from '../site-url.js'
+import type { ContentItem } from '../types.js'
+import { generatePodcastFeed } from '../utils/podcast.js'
+
+export const prerender = false
+
+export const GET: APIRoute = async (context) => {
+	const config = resolveSeoConfig(getConfig())
+	const contentProvider = getContentProvider()
+
+	let articles: ContentItem[] = []
+	if (contentProvider) {
+		try {
+			articles = await contentProvider({ type: 'articles' }, context as any)
+		} catch {}
+	}
+
+	const withAudio = articles.filter((a) => a.audio)
+	const xml = generatePodcastFeed(withAudio, config)
+
+	return new Response(xml, {
+		headers: { 'Content-Type': 'application/rss+xml; charset=utf-8' },
+	})
+}

package/src/routes/revalidate.ts

@@ -0,0 +1,298 @@
+import 'virtual:growth-labs/seo/config'
+import type { APIRoute } from 'astro'
+import { getConfig, getContentProvider } from '../_internal/state.js'
+import type { DurableObjectNamespaceLike, SeoEnv } from '../bindings.js'
+import { resolveAeoTwins } from '../options.js'
+import { getRuntimeEnv } from '../runtime.js'
+import { resolveSeoConfig } from '../site-url.js'
+import type { ContentItem, ContentProvider } from '../types.js'
+import { generateAeoMarkdown } from '../utils/aeo.js'
+import { generateSummaryTwin } from '../utils/aeo-summary.js'
+import type { FreshLayerBinding } from '../utils/fresh-layer.js'
+import { deleteFreshTwin, writeFreshTwin } from '../utils/fresh-layer.js'
+
+export const prerender = false
+
+// ─── Wire format ───
+
+interface RevalidateBody {
+	slugs?: string[]
+	action?: 'publish' | 'unpublish'
+	idempotency_key?: string
+}
+
+const MAX_BATCH = 50
+const DEFAULT_RATE_LIMIT_RPM = 10
+
+/**
+ * POST /_seo/revalidate — CMS webhook target. Re-renders the listed slugs,
+ * writes to R2 under the current deployment prefix, purges the edge cache for
+ * the markdown sitemap so newly-published content is discoverable within seconds.
+ *
+ * Auth: Authorization: Bearer <revalidateToken>. Token is the same ≥32-byte
+ * value configured in aeoTwins.revalidateToken. Compared with constant-time
+ * string compare.
+ *
+ * Rate limit + per-slug lock + idempotency all delegate to the Revalidation
+ * Coordinator Durable Object (spec "Revalidation Coordinator DO topology").
+ */
+export const POST: APIRoute = async (context) => {
+	const rawConfig = getConfig()
+	const contentProvider = getContentProvider()
+	const aeo = resolveAeoTwins(rawConfig.aeoTwins)
+
+	if (!aeo?.onDemandRevalidation || !aeo.freshLayer || !aeo.revalidateToken) {
+		return json({ error: 'revalidation_disabled' }, 404)
+	}
+
+	const env = getRuntimeEnv(context) as SeoEnv
+	if (!env) {
+		return json({ error: 'binding_unavailable' }, 503)
+	}
+	const config = resolveSeoConfig(rawConfig, env as unknown as Record<string, unknown>)
+
+	// 1. Auth: Bearer token, constant-time compare.
+	const authz = context.request.headers.get('Authorization') ?? ''
+	const bearerPrefix = 'Bearer '
+	if (!authz.startsWith(bearerPrefix)) {
+		return json({ error: 'unauthorized' }, 401)
+	}
+	const presented = authz.slice(bearerPrefix.length)
+	if (!constantTimeEqual(presented, aeo.revalidateToken)) {
+		return json({ error: 'unauthorized' }, 401)
+	}
+
+	// 2. Parse body.
+	let body: RevalidateBody
+	try {
+		body = (await context.request.json()) as RevalidateBody
+	} catch {
+		return json({ error: 'bad_json' }, 400)
+	}
+	const slugs = body.slugs ?? []
+	if (!Array.isArray(slugs) || slugs.length === 0) {
+		return json({ error: 'no_slugs' }, 400)
+	}
+	if (slugs.length > MAX_BATCH) {
+		return json({ error: 'batch_too_large', limit: MAX_BATCH }, 400)
+	}
+
+	// 3. Resolve the Revalidation Coordinator DO for this hostname.
+	const hostname = new URL(context.request.url).host
+	const coordBindingName = aeo.freshLayer.coordinatorBindingName
+	const coordBinding = (env as unknown as Record<string, unknown>)[coordBindingName] as
+		| DurableObjectNamespaceLike
+		| undefined
+	const coord = coordBinding ? coordBinding.get(coordBinding.idFromName(hostname)) : undefined
+
+	// 4. Rate-limit check (per-token).
+	if (coord) {
+		const rl = await coordCall(coord, {
+			action: 'rate-check',
+			token: presented,
+			limitRpm: DEFAULT_RATE_LIMIT_RPM,
+		})
+		if (!rl.ok) {
+			return new Response(
+				JSON.stringify({ error: 'rate_limited', retryAfterMs: rl.retryAfterMs }),
+				{
+					status: 429,
+					headers: {
+						'Content-Type': 'application/json',
+						'Retry-After': String(Math.ceil(Number(rl.retryAfterMs ?? 5000) / 1000)),
+					},
+				},
+			)
+		}
+	}
+
+	// 5. Idempotency check — dedupe concurrent webhooks for the same CMS event.
+	if (coord && body.idempotency_key) {
+		const cached = await coordCall(coord, {
+			action: 'idempotency-check',
+			key: body.idempotency_key,
+		})
+		if (cached.ok && cached.hit) {
+			return json({ ok: true, deduped: true, ...(cached.result as Record<string, unknown>) })
+		}
+	}
+
+	// 6. Resolve fresh layer + content provider.
+	const freshLayerImpl = (env as unknown as Record<string, unknown>)[aeo.freshLayer.bindingName]
+	if (!freshLayerImpl || !contentProvider) {
+		return json({ error: 'binding_unavailable' }, 503)
+	}
+	const freshLayer: FreshLayerBinding = {
+		type: aeo.freshLayer.type,
+		impl: freshLayerImpl as FreshLayerBinding['impl'],
+		deploymentId: env.CF_VERSION_METADATA?.id ?? 'dev',
+	}
+
+	const outcomes: Array<Record<string, unknown>> = []
+	for (const slug of slugs) {
+		const outcome = await revalidateSlug({
+			slug,
+			action: body.action ?? 'publish',
+			config,
+			contentProvider,
+			freshLayer,
+			coord,
+		})
+		outcomes.push(outcome)
+	}
+
+	// 7. Purge sitemap-markdown cache so newly-published articles show up.
+	await purgeSitemapMarkdownCache(context.request).catch(() => {})
+
+	// 8. Cache idempotency result for future replays.
+	if (coord && body.idempotency_key) {
+		await coordCall(coord, {
+			action: 'idempotency-set',
+			key: body.idempotency_key,
+			result: { outcomes },
+		})
+	}
+
+	return json({ ok: true, outcomes })
+}
+
+// ─── Per-slug revalidate ───
+
+interface RevalidateSlugInput {
+	slug: string
+	action: 'publish' | 'unpublish'
+	config: ReturnType<typeof resolveSeoConfig>
+	contentProvider: ContentProvider
+	freshLayer: FreshLayerBinding
+	coord: ReturnType<DurableObjectNamespaceLike['get']> | undefined
+}
+
+async function revalidateSlug(input: RevalidateSlugInput): Promise<Record<string, unknown>> {
+	const { slug, action, config, contentProvider, freshLayer, coord } = input
+	const start = Date.now()
+
+	// Acquire per-slug lock; if someone else holds it, serialize.
+	let leaseId: string | undefined
+	if (coord) {
+		const acquire = await coordCall(coord, { action: 'acquire-lock', slug })
+		if (acquire.ok) {
+			leaseId = acquire.leaseId as string
+		} else if (acquire.error === 'locked') {
+			// Someone else is rendering this slug. Return without duplicating work;
+			// the winner's writeback will be visible to subsequent requests.
+			return { slug, outcome: 'serialized' }
+		} else {
+			return { slug, outcome: 'error', error: acquire.error }
+		}
+	}
+
+	try {
+		if (action === 'unpublish') {
+			const url = new URL(`${config.site.replace(/\/$/, '')}/${slug}`).pathname
+			const aeo = resolveAeoTwins(config.aeoTwins)
+			const twinPath = `${url.replace(/\/+$/, '')}.md`
+			const summaryPath = `${twinPath}.summary.md`
+			await deleteFreshTwin(freshLayer, twinPath)
+			if (aeo?.summaryTwin) await deleteFreshTwin(freshLayer, summaryPath)
+			return { slug, outcome: 'deleted', durationMs: Date.now() - start }
+		}
+
+		// Publish / update.
+		let items: ContentItem[]
+		try {
+			items = await contentProvider({ type: 'articles', slugs: [slug] }, {} as never)
+		} catch (err) {
+			return {
+				slug,
+				outcome: 'error',
+				error: err instanceof Error ? err.message : String(err),
+			}
+		}
+		const item = items.find((i) => i.url.endsWith(`/${slug}`) || i.url === slug)
+		if (!item) return { slug, outcome: 'not_found' }
+
+		const body = item.description ?? ''
+		const aeo = resolveAeoTwins(config.aeoTwins)
+		const primaryUrl = (aeo?.twinUrl ?? defaultTwin)(item.url)
+		const summaryUrl = aeo?.summaryTwin ? `${primaryUrl}.summary.md` : undefined
+		const markdown = generateAeoMarkdown(item, {
+			publisherName: config.organization.name,
+			schemaType: config.schemaType,
+			content: body,
+			ragChunkMarkers: aeo?.ragChunkMarkers,
+			canonical: item.url,
+			twinUrl: primaryUrl,
+			summaryUrl,
+		})
+		await writeFreshTwin(freshLayer, pathOf(primaryUrl), markdown)
+		if (aeo?.summaryTwin && summaryUrl) {
+			const summary = generateSummaryTwin(item, {
+				publisherName: config.organization.name,
+				schemaType: config.schemaType,
+				content: body,
+				fullUrl: primaryUrl,
+			})
+			await writeFreshTwin(freshLayer, pathOf(summaryUrl), summary.markdown)
+		}
+
+		return { slug, outcome: 'written', durationMs: Date.now() - start }
+	} finally {
+		if (coord && leaseId) {
+			await coordCall(coord, { action: 'release-lock', slug, leaseId }).catch(() => {})
+		}
+	}
+}
+
+// ─── Helpers ───
+
+async function coordCall(
+	stub: { fetch(request: Request): Promise<Response> },
+	body: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+	try {
+		const res = await stub.fetch(
+			new Request('https://internal/', {
+				method: 'POST',
+				body: JSON.stringify(body),
+				headers: { 'Content-Type': 'application/json' },
+			}),
+		)
+		return (await res.json()) as Record<string, unknown>
+	} catch {
+		return { ok: false, error: 'coord_unavailable' }
+	}
+}
+
+function constantTimeEqual(a: string, b: string): boolean {
+	if (a.length !== b.length) return false
+	let diff = 0
+	for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i)
+	return diff === 0
+}
+
+function defaultTwin(url: string): string {
+	return `${url.replace(/\/+$/, '')}.md`
+}
+
+function pathOf(url: string): string {
+	try {
+		return new URL(url).pathname
+	} catch {
+		return url.startsWith('/') ? url : `/${url}`
+	}
+}
+
+async function purgeSitemapMarkdownCache(request: Request): Promise<void> {
+	const origin = new URL(request.url).origin
+	const key = new Request(`${origin}/sitemap-markdown.xml`)
+	await caches.default.delete(key).catch(() => {})
+}
+
+function json(body: Record<string, unknown>, status = 200): Response {
+	return new Response(JSON.stringify(body), {
+		status,
+		headers: { 'Content-Type': 'application/json' },
+	})
+}
+
+declare const caches: { default: { delete(key: Request): Promise<boolean> } }

package/src/routes/robots.ts

@@ -0,0 +1,21 @@
+import 'virtual:growth-labs/seo/config'
+import type { APIRoute } from 'astro'
+import { getConfig, getContentProvider } from '../_internal/state.js'
+import { resolveSeoConfig } from '../site-url.js'
+import { generateRobotsTxt } from '../utils/robots.js'
+
+export const prerender = false
+
+export const GET: APIRoute = async () => {
+	const config = resolveSeoConfig(getConfig())
+	// The sitemap-index route is only injected when a content provider is wired.
+	// Detect that at request time via getContentProvider() — the virtual module
+	// seeds state with the same provider the integration gated injection on.
+	// Without this, /robots.txt would ship a Sitemap: line pointing at a 404.
+	const includeSitemap = getContentProvider() !== undefined
+	const txt = generateRobotsTxt(config, { includeSitemap })
+
+	return new Response(txt, {
+		headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+	})
+}

package/src/routes/rss.ts

@@ -0,0 +1,29 @@
+import 'virtual:growth-labs/seo/config'
+import type { APIRoute } from 'astro'
+import { getConfig, getContentProvider } from '../_internal/state.js'
+import { resolveSeoConfig } from '../site-url.js'
+import type { ContentItem } from '../types.js'
+import { forRss } from '../utils/content-filter.js'
+import { generateRssFeed } from '../utils/rss.js'
+
+export const prerender = false
+
+export const GET: APIRoute = async (context) => {
+	const config = resolveSeoConfig(getConfig())
+	const contentProvider = getContentProvider()
+
+	let articles: ContentItem[] = []
+	if (contentProvider) {
+		try {
+			articles = await contentProvider({ type: 'articles' }, context)
+		} catch {}
+	}
+
+	// Members items excluded unconditionally. Public items respect includeInFeed.
+	const filtered = forRss(articles)
+	const xml = generateRssFeed(filtered, config)
+
+	return new Response(xml, {
+		headers: { 'Content-Type': 'application/rss+xml; charset=utf-8' },
+	})
+}

package/src/routes/sitemap-articles.ts

@@ -0,0 +1,25 @@
+import 'virtual:growth-labs/seo/config'
+import type { APIRoute } from 'astro'
+import { getConfig, getContentProvider } from '../_internal/state.js'
+import type { ContentItem } from '../types.js'
+import { generateArticleSitemap } from '../utils/sitemap.js'
+
+export const prerender = false
+
+export const GET: APIRoute = async (context) => {
+	const config = getConfig()
+	const contentProvider = getContentProvider()
+
+	let articles: ContentItem[] = []
+	if (contentProvider) {
+		try {
+			articles = await contentProvider({ type: 'articles' }, context as any)
+		} catch {}
+	}
+
+	const xml = generateArticleSitemap(articles, config)
+
+	return new Response(xml, {
+		headers: { 'Content-Type': 'application/xml; charset=utf-8' },
+	})
+}

package/src/routes/sitemap-index.ts

@@ -0,0 +1,89 @@
+import 'virtual:growth-labs/seo/config'
+import type { APIRoute } from 'astro'
+import { getConfig, getContentProvider } from '../_internal/state.js'
+import { resolveSeoConfig } from '../site-url.js'
+import type { SitemapEntry } from '../utils/sitemap.js'
+import { generateSitemapIndex } from '../utils/sitemap.js'
+
+export const prerender = false
+
+export const GET: APIRoute = async (context) => {
+	const config = resolveSeoConfig(getConfig())
+	const contentProvider = getContentProvider()
+
+	const sitemaps: SitemapEntry[] = []
+
+	const { site } = config
+
+	// Fetch articles lastmod if possible
+	let articlesLastmod: string | undefined
+	let pagesLastmod: string | undefined
+	let videosLastmod: string | undefined
+	let productsLastmod: string | undefined
+
+	if (contentProvider) {
+		try {
+			const articles = await contentProvider({ type: 'articles' }, context as any)
+			if (articles.length > 0) {
+				const dates = articles
+					.map((a) => a.dateModified ?? a.datePublished)
+					.filter(Boolean) as string[]
+				if (dates.length > 0) {
+					articlesLastmod = dates.sort().at(-1)
+				}
+			}
+		} catch {}
+
+		try {
+			const pages = await contentProvider({ type: 'pages' }, context as any)
+			if (pages.length > 0) {
+				const dates = pages
+					.map((p) => p.dateModified ?? p.datePublished)
+					.filter(Boolean) as string[]
+				if (dates.length > 0) {
+					pagesLastmod = dates.sort().at(-1)
+				}
+			}
+		} catch {}
+
+		try {
+			const videos = await contentProvider({ type: 'videos' }, context as any)
+			if (videos.length > 0) {
+				const dates = videos
+					.map((v) => v.dateModified ?? v.datePublished)
+					.filter(Boolean) as string[]
+				if (dates.length > 0) {
+					videosLastmod = dates.sort().at(-1)
+				}
+			}
+		} catch {}
+
+		if (config.commerce?.enabled) {
+			try {
+				const products = await contentProvider({ type: 'products' }, context as any)
+				if (products.length > 0) {
+					const dates = products
+						.map((p) => p.dateModified ?? p.datePublished)
+						.filter(Boolean) as string[]
+					if (dates.length > 0) {
+						productsLastmod = dates.sort().at(-1)
+					}
+				}
+			} catch {}
+		}
+	}
+
+	sitemaps.push({ loc: `${site}/sitemap-articles.xml`, lastmod: articlesLastmod })
+	sitemaps.push({ loc: `${site}/sitemap-pages.xml`, lastmod: pagesLastmod })
+	sitemaps.push({ loc: `${site}/sitemap-videos.xml`, lastmod: videosLastmod })
+
+	if (config.commerce?.enabled) {
+		sitemaps.push({ loc: `${site}/sitemap-products.xml`, lastmod: productsLastmod })
+	}
+
+	const xml = generateSitemapIndex(sitemaps)
+
+	return new Response(xml, {
+		headers: { 'Content-Type': 'application/xml; charset=utf-8' },
+	})
+}

package/src/routes/sitemap-markdown.ts

@@ -0,0 +1,39 @@
+import 'virtual:growth-labs/seo/config'
+import type { APIRoute } from 'astro'
+import { getConfig, getContentProvider } from '../_internal/state.js'
+import { resolveAeoTwins } from '../options.js'
+import type { ContentItem } from '../types.js'
+import { generateMarkdownSitemap } from '../utils/sitemap-markdown.js'
+
+export const prerender = false
+
+export const GET: APIRoute = async (context) => {
+	const config = getConfig()
+	const contentProvider = getContentProvider()
+
+	// Only emit when twin URLs actually exist on disk (static or both modes).
+	// Middleware-mode twins live at the same URL as HTML; no distinct twin URLs.
+	const aeo = resolveAeoTwins(config.aeoTwins)
+	if (!config.markdownSitemap || !aeo || aeo.mode === 'middleware') {
+		return new Response('sitemap-markdown not enabled', { status: 404 })
+	}
+
+	let articles: ContentItem[] = []
+	if (contentProvider) {
+		try {
+			articles = await contentProvider({ type: 'articles' }, context)
+		} catch {}
+	}
+
+	const xml = generateMarkdownSitemap({
+		items: articles,
+		twinUrl: aeo.twinUrl,
+		// R2-freshness freshLayerLastmod is wired at middleware level via the DO;
+		// at the build-route layer we use build-time dateModified. After revalidation
+		// writes, the consumer's cache purge causes this route to regenerate.
+	})
+
+	return new Response(xml, {
+		headers: { 'Content-Type': 'application/xml; charset=utf-8' },
+	})
+}

package/src/routes/sitemap-pages.ts

@@ -0,0 +1,24 @@
+import 'virtual:growth-labs/seo/config'
+import type { APIRoute } from 'astro'
+import { getContentProvider } from '../_internal/state.js'
+import type { ContentItem } from '../types.js'
+import { generatePagesSitemap } from '../utils/sitemap.js'
+
+export const prerender = false
+
+export const GET: APIRoute = async (context) => {
+	const contentProvider = getContentProvider()
+
+	let pages: ContentItem[] = []
+	if (contentProvider) {
+		try {
+			pages = await contentProvider({ type: 'pages' }, context as any)
+		} catch {}
+	}
+
+	const xml = generatePagesSitemap(pages)
+
+	return new Response(xml, {
+		headers: { 'Content-Type': 'application/xml; charset=utf-8' },
+	})
+}

package/src/routes/sitemap-products.ts

@@ -0,0 +1,24 @@
+import 'virtual:growth-labs/seo/config'
+import type { APIRoute } from 'astro'
+import { getContentProvider } from '../_internal/state.js'
+import type { ContentItem } from '../types.js'
+import { generateProductSitemap } from '../utils/sitemap.js'
+
+export const prerender = false
+
+export const GET: APIRoute = async (context) => {
+	const contentProvider = getContentProvider()
+
+	let products: ContentItem[] = []
+	if (contentProvider) {
+		try {
+			products = await contentProvider({ type: 'products' }, context as any)
+		} catch {}
+	}
+
+	const xml = generateProductSitemap(products)
+
+	return new Response(xml, {
+		headers: { 'Content-Type': 'application/xml; charset=utf-8' },
+	})
+}

package/src/routes/sitemap-videos.ts

@@ -0,0 +1,24 @@
+import 'virtual:growth-labs/seo/config'
+import type { APIRoute } from 'astro'
+import { getContentProvider } from '../_internal/state.js'
+import type { ContentItem } from '../types.js'
+import { generateVideoSitemap } from '../utils/sitemap.js'
+
+export const prerender = false
+
+export const GET: APIRoute = async (context) => {
+	const contentProvider = getContentProvider()
+
+	let videos: ContentItem[] = []
+	if (contentProvider) {
+		try {
+			videos = await contentProvider({ type: 'videos' }, context as any)
+		} catch {}
+	}
+
+	const xml = generateVideoSitemap(videos)
+
+	return new Response(xml, {
+		headers: { 'Content-Type': 'application/xml; charset=utf-8' },
+	})
+}

package/src/runtime.ts

@@ -0,0 +1,17 @@
+import { env as cloudflareEnv } from 'cloudflare:workers'
+
+interface RuntimeContext {
+	locals?: {
+		cfContext?: {
+			waitUntil?: (promise: Promise<unknown>) => void
+		}
+	}
+}
+
+export function getRuntimeEnv(_context: RuntimeContext): Record<string, unknown> {
+	return cloudflareEnv as Record<string, unknown>
+}
+
+export function getWaitUntil(context: RuntimeContext): (promise: Promise<unknown>) => void {
+	return context.locals?.cfContext?.waitUntil?.bind(context.locals.cfContext) ?? (() => {})
+}