@growth-labs/seo 0.4.0 → 0.4.2

package/src/utils/fresh-layer.ts

@@ -0,0 +1,175 @@
+import type { KVNamespaceLike, R2BucketLike } from '../bindings.js'
+
+// Fresh-twin layer: unified reader/writer over R2 or KV. Keys are deploymentId-
+// prefixed so a rollback (which cuts a new deployment under a different versionId)
+// automatically scopes R2 visibility to the current deployment.
+//
+// Key format: `twin/<deploymentId>/<slug>[.summary].md`
+// Example:    `twin/7b9c1f.../article/midway.md`
+
+export interface FreshLayerBinding {
+	type: 'r2' | 'kv'
+	impl: R2BucketLike | KVNamespaceLike
+	deploymentId: string
+}
+
+export interface FreshTwinReadResult {
+	body: string
+	contentType: string
+	lastModified?: Date
+}
+
+// ─── Public API ───
+
+/**
+ * Read a twin from the fresh layer for the current deployment. Returns null when
+ * no entry exists (cache miss — caller should fall back to Assets or contentProvider).
+ *
+ * Path is the URL-path form (e.g. '/article/midway.md'), not a full URL.
+ */
+export async function readFreshTwin(
+	binding: FreshLayerBinding,
+	path: string,
+): Promise<FreshTwinReadResult | null> {
+	const key = buildKey(binding.deploymentId, path)
+	if (binding.type === 'r2') {
+		const r2 = binding.impl as R2BucketLike
+		const obj = await r2.get(key)
+		if (!obj) return null
+		return {
+			body: await obj.text(),
+			contentType: obj.httpMetadata?.contentType ?? 'text/markdown; charset=utf-8',
+			lastModified: obj.uploaded,
+		}
+	}
+	const kv = binding.impl as KVNamespaceLike
+	const body = await kv.get(key)
+	if (body === null) return null
+	return { body, contentType: 'text/markdown; charset=utf-8' }
+}
+
+/**
+ * Write a twin to the fresh layer under the current deployment prefix. Called
+ * from the revalidation endpoint (POST /_seo/revalidate) and from the middleware
+ * fallthrough path after a successful on-demand render.
+ */
+export async function writeFreshTwin(
+	binding: FreshLayerBinding,
+	path: string,
+	body: string,
+	contentType = 'text/markdown; charset=utf-8',
+): Promise<void> {
+	const key = buildKey(binding.deploymentId, path)
+	if (binding.type === 'r2') {
+		const r2 = binding.impl as R2BucketLike
+		await r2.put(key, body, { httpMetadata: { contentType } })
+		return
+	}
+	const kv = binding.impl as KVNamespaceLike
+	await kv.put(key, body)
+}
+
+/**
+ * Delete a twin (and its summary) from the fresh layer. Used by the unpublish
+ * path in /_seo/revalidate.
+ */
+export async function deleteFreshTwin(binding: FreshLayerBinding, path: string): Promise<void> {
+	const key = buildKey(binding.deploymentId, path)
+	if (binding.type === 'r2') {
+		const r2 = binding.impl as R2BucketLike
+		await r2.delete(key)
+		return
+	}
+	const kv = binding.impl as KVNamespaceLike
+	await kv.delete(key)
+}
+
+/**
+ * List keys for a specific deployment prefix. Used by the prune cron to find
+ * and delete entries from old deployments.
+ */
+export async function* listKeysByDeployment(
+	binding: FreshLayerBinding,
+	deploymentId: string,
+): AsyncGenerator<string> {
+	const prefix = `twin/${deploymentId}/`
+	if (binding.type === 'r2') {
+		const r2 = binding.impl as R2BucketLike
+		let cursor: string | undefined
+		while (true) {
+			const result = await r2.list({ prefix, cursor })
+			for (const obj of result.objects) yield obj.key
+			if (!result.truncated) break
+			cursor = result.cursor
+		}
+		return
+	}
+	const kv = binding.impl as KVNamespaceLike
+	let cursor: string | undefined
+	while (true) {
+		const result = await kv.list({ prefix, cursor })
+		for (const entry of result.keys) yield entry.name
+		if (result.list_complete) break
+		cursor = result.cursor
+	}
+}
+
+/**
+ * List distinct deployment IDs currently present in the fresh layer. Used by
+ * the prune cron to find non-current deployments eligible for cleanup.
+ *
+ * Implementation note: neither R2 nor KV has a first-class "list top-level
+ * prefixes" API. We walk the top-level prefix `twin/` and parse the segment
+ * between the second and third slash. For sites with hundreds of old
+ * deployments this is O(N) in total key count — acceptable for the nightly
+ * cron, too expensive for the request path.
+ */
+export async function listDeploymentIds(binding: FreshLayerBinding): Promise<Set<string>> {
+	const deployments = new Set<string>()
+	if (binding.type === 'r2') {
+		const r2 = binding.impl as R2BucketLike
+		let cursor: string | undefined
+		while (true) {
+			const result = await r2.list({ prefix: 'twin/', cursor })
+			for (const obj of result.objects) {
+				const id = extractDeploymentId(obj.key)
+				if (id) deployments.add(id)
+			}
+			if (!result.truncated) break
+			cursor = result.cursor
+		}
+		return deployments
+	}
+	const kv = binding.impl as KVNamespaceLike
+	let cursor: string | undefined
+	while (true) {
+		const result = await kv.list({ prefix: 'twin/', cursor })
+		for (const entry of result.keys) {
+			const id = extractDeploymentId(entry.name)
+			if (id) deployments.add(id)
+		}
+		if (result.list_complete) break
+		cursor = result.cursor
+	}
+	return deployments
+}
+
+// ─── Internals ───
+
+function buildKey(deploymentId: string, path: string): string {
+	const normalized = path.startsWith('/') ? path.slice(1) : path
+	return `twin/${deploymentId}/${normalized}`
+}
+
+function extractDeploymentId(key: string): string | null {
+	// `twin/<id>/<rest>` — second segment.
+	const parts = key.split('/')
+	if (parts.length < 3) return null
+	if (parts[0] !== 'twin') return null
+	return parts[1] ?? null
+}
+
+export const _internals = {
+	buildKey,
+	extractDeploymentId,
+}

package/src/utils/hreflang.ts

@@ -0,0 +1,26 @@
+import type { ContentLocaleAlternate, HreflangLink } from '../types.js'
+
+export function generateHreflang(
+	alternates: ContentLocaleAlternate[],
+	defaultLocale: string,
+): HreflangLink[] {
+	if (!alternates.length) return []
+
+	const links: HreflangLink[] = alternates.map((alt) => ({
+		rel: 'alternate',
+		hreflang: alt.lang,
+		href: alt.url,
+	}))
+
+	// Add x-default pointing to the URL of the defaultLocale
+	const defaultEntry = alternates.find((a) => a.lang === defaultLocale)
+	if (defaultEntry) {
+		links.push({
+			rel: 'alternate',
+			hreflang: 'x-default',
+			href: defaultEntry.url,
+		})
+	}
+
+	return links
+}

package/src/utils/index.ts

@@ -0,0 +1,91 @@
+export {
+	estimateTokenCount,
+	type GenerateAeoMarkdownOptions,
+	generateAeoMarkdown,
+} from './aeo.js'
+export {
+	type GenerateSummaryTwinOptions,
+	type GenerateSummaryTwinResult,
+	generateSummaryTwin,
+} from './aeo-summary.js'
+export {
+	type EmitAeoTwinsOptions,
+	type EmitAeoTwinsResult,
+	type EmittedTwin,
+	emitAeoTwins,
+	type RenderBody,
+} from './aeo-twin-emitter.js'
+export {
+	type AnfComponent,
+	type AnfDocument,
+	type GenerateAnfOptions,
+	generateAppleNewsAnf,
+} from './apple-news-anf.js'
+export {
+	type ContentHtmlResolver,
+	type GenerateAppleNewsRssOptions,
+	generateAppleNewsRss,
+} from './apple-news-rss.js'
+export * from './content-filter.js'
+export {
+	type ClassifyRequestInput,
+	classifyRequest,
+	VERIFIED_SEARCH_SUFFIXES,
+} from './crawler-class.js'
+export {
+	type ContentItemByType,
+	defineContentProvider,
+	defineContentProviderModule,
+	type TypedContentProvider,
+} from './define-content-provider.js'
+export { computeEffectiveAuthSegment, type RawAuthSegment } from './effective-auth.js'
+export {
+	createDohResolver,
+	createFcrdnsVerifier,
+	type DnsAnswer,
+	type DnsResolver,
+	type FcrdnsVerifier,
+	type FcrdnsVerifyInput,
+} from './fcrdns.js'
+export {
+	deleteFreshTwin,
+	type FreshLayerBinding,
+	type FreshTwinReadResult,
+	listDeploymentIds,
+	listKeysByDeployment,
+	readFreshTwin,
+	writeFreshTwin,
+} from './fresh-layer.js'
+export { generateHreflang } from './hreflang.js'
+export * from './json-ld/index.js'
+export { generateLlmsTxt } from './llms.js'
+export { type GenerateLlmsFullOptions, generateLlmsFull } from './llms-full.js'
+export { applyTrailingSlash, generateCanonical, generateMeta, type OgVariant } from './meta.js'
+export { generatePodcastFeed } from './podcast.js'
+export { generateRobotsTxt } from './robots.js'
+export { generateRssFeed } from './rss.js'
+export { buildSeoHeadJsonLd, buildSeoHeadTitleDescription } from './seo-head.js'
+export {
+	generateArticleSitemap,
+	generatePagesSitemap,
+	generateProductSitemap,
+	generateSitemapIndex,
+	generateVideoSitemap,
+	type SitemapEntry,
+} from './sitemap.js'
+export { generateMarkdownSitemap } from './sitemap-markdown.js'
+export {
+	checkStaleness,
+	computeContentHash,
+	type StalenessDriftRecord,
+} from './staleness.js'
+export {
+	type HreflangReciprocityIssue,
+	type PageValidationOptions,
+	type PrerenderGuardIssue,
+	type ValidationResult,
+	validateHreflangReciprocity,
+	validateJsonLd,
+	validatePage,
+	validatePrerenderedGatedRoutes,
+} from './validation.js'

package/src/utils/json-ld/article.ts

@@ -0,0 +1,120 @@
+import type { ResolvedSeoOptions } from '../../options.js'
+import type { ContentItem, JsonLdObject } from '../../types.js'
+
+/**
+ * Redaction mode for gated content.
+ *   'full'      — no redaction. Used for verified search crawlers under Flexible Sampling
+ *                 and for the member's own request.
+ *   'redacted'  — members-safe output: description truncated, articleBody absent, FAQ
+ *                 answers truncated. Google Rich Results still passes (description is
+ *                 truncated, not omitted).
+ */
+export type ArticleRenderMode = 'full' | 'redacted'
+
+const MAX_REDACTED_DESCRIPTION_CHARS = 160
+
+export interface GenerateArticleJsonLdOptions {
+	mode?: ArticleRenderMode
+}
+
+export function generateArticleJsonLd(
+	item: ContentItem,
+	options: ResolvedSeoOptions,
+	renderOptions: GenerateArticleJsonLdOptions = {},
+): JsonLdObject {
+	const { organization, schemaType, audioNarration } = options
+	const mode = renderOptions.mode ?? 'full'
+	const isMemberItem = item.access === 'members'
+	const applyRedaction = mode === 'redacted' && isMemberItem
+
+	const authors: JsonLdObject[] = (item.authors ?? []).map((author) => {
+		const person: JsonLdObject = { '@type': 'Person', name: author.name }
+		if (author.url) person.url = author.url
+		if (author.jobTitle) person.jobTitle = author.jobTitle
+		if (author.knowsAbout?.length) person.knowsAbout = author.knowsAbout
+		if (author.sameAs?.length) person.sameAs = author.sameAs
+		return person
+	})
+
+	// Derive isAccessibleForFree: explicit field wins, otherwise derive from access.
+	const isAccessibleForFree = item.isAccessibleForFree ?? item.access !== 'members'
+
+	const result: JsonLdObject = {
+		'@context': 'https://schema.org',
+		'@type': schemaType,
+		headline: item.title,
+		url: item.url,
+		mainEntityOfPage: {
+			'@type': 'WebPage',
+			'@id': item.url,
+		},
+		publisher: {
+			'@type': 'Organization',
+			name: organization.name,
+			logo: {
+				'@type': 'ImageObject',
+				url: organization.logo,
+			},
+			...(organization.sameAs?.length ? { sameAs: organization.sameAs } : {}),
+		},
+		author: authors,
+		// Google requires the string form 'True'/'False' for Rich Results when paywall markup is emitted.
+		// See https://developers.google.com/search/docs/appearance/structured-data/paywalled-content
+		isAccessibleForFree: isAccessibleForFree ? 'True' : 'False',
+	}
+
+	if (item.image) {
+		// Consumers compose @growth-labs/media if they need multi-aspect-ratio variants;
+		// this utility takes whatever URL(s) the consumer supplied in the ContentItem.
+		result.image = Array.isArray(item.image) ? item.image : [item.image]
+	}
+
+	if (item.description) {
+		result.description = applyRedaction
+			? truncateDescription(item.description, MAX_REDACTED_DESCRIPTION_CHARS)
+			: item.description
+	}
+	if (item.datePublished) result.datePublished = item.datePublished
+	if (item.dateModified) result.dateModified = item.dateModified
+
+	// hasPart paywall marker — emitted whenever the item is gated (either via explicit
+	// isAccessibleForFree: false or via access: 'members').
+	if (!isAccessibleForFree && item.paywallCssSelector) {
+		result.hasPart = {
+			'@type': 'WebPageElement',
+			isAccessibleForFree: 'False',
+			cssSelector: item.paywallCssSelector,
+		}
+	}
+
+	if (item.audio) {
+		result.associatedMedia = {
+			'@type': 'AudioObject',
+			contentUrl: item.audio.url,
+			duration: item.audio.duration,
+			...(item.audio.narrator ? { name: item.audio.narrator } : {}),
+		}
+	}
+
+	if (audioNarration?.enabled) {
+		result.speakable = {
+			'@type': 'SpeakableSpecification',
+			cssSelector: audioNarration.speakableSelectors,
+		}
+	}
+
+	return result
+}
+
+/**
+ * Truncate a description to `maxChars` graphemes, on a word boundary if possible,
+ * with ellipsis suffix. Returns the original if shorter than maxChars.
+ */
+function truncateDescription(text: string, maxChars: number): string {
+	if (text.length <= maxChars) return text
+	const targetLen = maxChars - 1 // reserve for ellipsis
+	const sliced = text.slice(0, targetLen)
+	const lastSpace = sliced.lastIndexOf(' ')
+	const cutAt = lastSpace > targetLen * 0.6 ? lastSpace : targetLen
+	return `${sliced.slice(0, cutAt).trimEnd()}…`
+}

package/src/utils/json-ld/audio.ts

@@ -0,0 +1,32 @@
+import type { ContentAudio, JsonLdObject } from '../../types.js'
+
+export function generateAudioJsonLd(
+	audio: ContentAudio,
+	options: { title: string; datePublished?: string; articleUrl?: string },
+): JsonLdObject {
+	const result: JsonLdObject = {
+		'@context': 'https://schema.org',
+		'@type': 'AudioObject',
+		name: options.title,
+		contentUrl: audio.url,
+		duration: audio.duration,
+	}
+
+	if (audio.narrator) {
+		result.creator = {
+			'@type': 'Person',
+			name: audio.narrator,
+		}
+	}
+
+	if (options.datePublished) result.datePublished = options.datePublished
+
+	if (options.articleUrl) {
+		result.isPartOf = {
+			'@type': 'Article',
+			url: options.articleUrl,
+		}
+	}
+
+	return result
+}

package/src/utils/json-ld/breadcrumb.ts

@@ -0,0 +1,28 @@
+import type { JsonLdObject } from '../../types.js'
+
+export interface BreadcrumbItem {
+	name: string
+	url: string
+}
+
+export function generateBreadcrumbJsonLd(items: BreadcrumbItem[]): JsonLdObject {
+	const lastIndex = items.length - 1
+
+	const itemListElement = items.map((item, index) => {
+		const listItem: JsonLdObject = {
+			'@type': 'ListItem',
+			position: index + 1,
+			name: item.name,
+		}
+		if (index !== lastIndex) {
+			listItem.item = item.url
+		}
+		return listItem
+	})
+
+	return {
+		'@context': 'https://schema.org',
+		'@type': 'BreadcrumbList',
+		itemListElement,
+	}
+}

package/src/utils/json-ld/faq.ts

@@ -0,0 +1,18 @@
+import type { JsonLdObject } from '../../types.js'
+
+export function generateFaqJsonLd(
+	items: Array<{ question: string; answer: string }>,
+): JsonLdObject {
+	return {
+		'@context': 'https://schema.org',
+		'@type': 'FAQPage',
+		mainEntity: items.map((item) => ({
+			'@type': 'Question',
+			name: item.question,
+			acceptedAnswer: {
+				'@type': 'Answer',
+				text: item.answer,
+			},
+		})),
+	}
+}

package/src/utils/json-ld/howto.ts

@@ -0,0 +1,23 @@
+import type { JsonLdObject } from '../../types.js'
+
+export function generateHowToJsonLd(
+	name: string,
+	description: string,
+	steps: Array<{ name: string; text: string; image?: string }>,
+): JsonLdObject {
+	return {
+		'@context': 'https://schema.org',
+		'@type': 'HowTo',
+		name,
+		description,
+		step: steps.map((step) => {
+			const s: JsonLdObject = {
+				'@type': 'HowToStep',
+				name: step.name,
+				text: step.text,
+			}
+			if (step.image) s.image = step.image
+			return s
+		}),
+	}
+}

package/src/utils/json-ld/index.ts

@@ -0,0 +1,12 @@
+export { generateArticleJsonLd } from './article.js'
+export { generateAudioJsonLd } from './audio.js'
+export type { BreadcrumbItem } from './breadcrumb.js'
+export { generateBreadcrumbJsonLd } from './breadcrumb.js'
+export { generateFaqJsonLd } from './faq.js'
+export { generateHowToJsonLd } from './howto.js'
+export { generateItemListJsonLd } from './item-list.js'
+export { generateOrganizationJsonLd } from './organization.js'
+export { generatePersonJsonLd } from './person.js'
+export { generateProductGroupJsonLd, generateProductJsonLd } from './product.js'
+export { generateVideoJsonLd } from './video.js'
+export { generateWebSiteJsonLd } from './website.js'

package/src/utils/json-ld/item-list.ts

@@ -0,0 +1,26 @@
+import type { JsonLdObject } from '../../types.js'
+
+const ORDER_MAP: Record<string, string> = {
+	ascending: 'https://schema.org/ItemListOrderAscending',
+	descending: 'https://schema.org/ItemListOrderDescending',
+	unordered: 'https://schema.org/ItemListUnordered',
+}
+
+export function generateItemListJsonLd(
+	name: string,
+	items: Array<{ url: string }>,
+	order: 'ascending' | 'descending' | 'unordered' = 'ascending',
+): JsonLdObject {
+	return {
+		'@context': 'https://schema.org',
+		'@type': 'ItemList',
+		name,
+		itemListOrder: ORDER_MAP[order],
+		numberOfItems: items.length,
+		itemListElement: items.map((item, index) => ({
+			'@type': 'ListItem',
+			position: index + 1,
+			url: item.url,
+		})),
+	}
+}

package/src/utils/json-ld/organization.ts

@@ -0,0 +1,42 @@
+import type { SeoOptionsWithResolvedSite } from '../../options.js'
+import type { JsonLdObject } from '../../types.js'
+
+export function generateOrganizationJsonLd(options: SeoOptionsWithResolvedSite): JsonLdObject {
+	const { organization, site, commerce } = options
+
+	const result: JsonLdObject = {
+		'@context': 'https://schema.org',
+		'@type': 'Organization',
+		name: organization.name,
+		url: organization.url ?? site,
+		logo: {
+			'@type': 'ImageObject',
+			url: organization.logo,
+		},
+	}
+
+	if (organization.sameAs?.length) {
+		result.sameAs = organization.sameAs
+	}
+
+	if (commerce?.enabled && commerce.returnPolicy) {
+		const policy = commerce.returnPolicy
+		const policyObj: JsonLdObject = {
+			'@type': 'MerchantReturnPolicy',
+			applicableCountry: policy.applicableCountry,
+			returnPolicyCategory: `https://schema.org/${policy.returnPolicyCategory}`,
+		}
+		if (policy.merchantReturnDays !== undefined) {
+			policyObj.merchantReturnDays = policy.merchantReturnDays
+		}
+		if (policy.returnMethod) {
+			policyObj.returnMethod = `https://schema.org/${policy.returnMethod}`
+		}
+		if (policy.returnFees) {
+			policyObj.returnFees = `https://schema.org/${policy.returnFees}`
+		}
+		result.hasMerchantReturnPolicy = policyObj
+	}
+
+	return result
+}

package/src/utils/json-ld/person.ts

@@ -0,0 +1,25 @@
+import type { ContentAuthor, JsonLdObject } from '../../types.js'
+
+export function generatePersonJsonLd(
+	author: ContentAuthor,
+	options?: { image?: string; organizationName?: string },
+): JsonLdObject {
+	const result: JsonLdObject = {
+		'@context': 'https://schema.org',
+		'@type': 'Person',
+		name: author.name,
+	}
+
+	if (author.url) result.url = author.url
+	if (author.jobTitle) result.jobTitle = author.jobTitle
+	if (author.sameAs?.length) result.sameAs = author.sameAs
+	if (options?.image) result.image = options.image
+	if (options?.organizationName) {
+		result.worksFor = {
+			'@type': 'Organization',
+			name: options.organizationName,
+		}
+	}
+
+	return result
+}