@growth-labs/seo 0.4.0 → 0.4.2

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

@@ -0,0 +1,155 @@
+import type { ResolvedSeoOptions } from '../../options.js'
+import type { ContentProduct, JsonLdObject, ProductVariant } from '../../types.js'
+
+const AVAILABILITY_MAP: Record<string, string> = {
+	InStock: 'https://schema.org/InStock',
+	OutOfStock: 'https://schema.org/OutOfStock',
+	PreOrder: 'https://schema.org/PreOrder',
+	Discontinued: 'https://schema.org/Discontinued',
+}
+
+function buildOffer(
+	price: number,
+	currency: string,
+	availability: string,
+	url: string,
+	condition?: string,
+	hasReturnPolicy?: boolean,
+): JsonLdObject {
+	const offer: JsonLdObject = {
+		'@type': 'Offer',
+		price,
+		priceCurrency: currency,
+		availability: AVAILABILITY_MAP[availability] ?? `https://schema.org/${availability}`,
+		url,
+	}
+	if (condition) {
+		offer.itemCondition = `https://schema.org/${condition}`
+	}
+	if (hasReturnPolicy) {
+		offer.hasMerchantReturnPolicy = { '@id': '#return-policy' }
+	}
+	return offer
+}
+
+function buildVariantProduct(
+	variant: ProductVariant,
+	url: string,
+	productCurrency: string,
+	hasReturnPolicy: boolean,
+): JsonLdObject {
+	const currency = variant.currency ?? productCurrency
+	const v: JsonLdObject = {
+		'@type': 'Product',
+		name: variant.name,
+		offers: buildOffer(
+			variant.price,
+			currency,
+			variant.availability,
+			url,
+			undefined,
+			hasReturnPolicy,
+		),
+	}
+	if (variant.sku) v.sku = variant.sku
+	if (variant.image) v.image = variant.image
+	return v
+}
+
+export function generateProductJsonLd(
+	product: ContentProduct,
+	url: string,
+	options: ResolvedSeoOptions,
+): JsonLdObject {
+	const hasReturnPolicy = !!(options.commerce?.enabled && options.commerce.returnPolicy)
+
+	const result: JsonLdObject = {
+		'@context': 'https://schema.org',
+		'@type': 'Product',
+		name: product.name,
+		description: product.description,
+		image: product.images,
+		offers: buildOffer(
+			product.price,
+			product.currency,
+			product.availability,
+			url,
+			product.condition,
+			hasReturnPolicy,
+		),
+	}
+
+	if (product.sku) result.sku = product.sku
+	if (product.gtin) result.gtin = product.gtin
+	if (product.mpn) result.mpn = product.mpn
+
+	if (product.brand) {
+		result.brand = {
+			'@type': 'Brand',
+			name: product.brand,
+		}
+	}
+
+	if (product.rating) {
+		result.aggregateRating = {
+			'@type': 'AggregateRating',
+			ratingValue: product.rating.value,
+			reviewCount: product.rating.count,
+			...(product.rating.bestRating !== undefined ? { bestRating: product.rating.bestRating } : {}),
+		}
+	}
+
+	if (product.reviews?.length) {
+		result.review = product.reviews.map((review) => {
+			const r: JsonLdObject = {
+				'@type': 'Review',
+				author: { '@type': 'Person', name: review.author },
+				reviewRating: {
+					'@type': 'Rating',
+					ratingValue: review.rating,
+				},
+			}
+			if (review.body) r.reviewBody = review.body
+			if (review.datePublished) r.datePublished = review.datePublished
+			return r
+		})
+	}
+
+	return result
+}
+
+export function generateProductGroupJsonLd(
+	product: ContentProduct,
+	url: string,
+	options: ResolvedSeoOptions,
+): JsonLdObject {
+	const hasReturnPolicy = !!(options.commerce?.enabled && options.commerce.returnPolicy)
+	const variants = product.variants ?? []
+
+	const result: JsonLdObject = {
+		'@context': 'https://schema.org',
+		'@type': 'ProductGroup',
+		name: product.name,
+		description: product.description,
+		image: product.images,
+		hasVariant: variants.map((v) => buildVariantProduct(v, url, product.currency, hasReturnPolicy)),
+	}
+
+	if (product.brand) {
+		result.brand = {
+			'@type': 'Brand',
+			name: product.brand,
+		}
+	}
+
+	if (product.rating) {
+		result.aggregateRating = {
+			'@type': 'AggregateRating',
+			ratingValue: product.rating.value,
+			reviewCount: product.rating.count,
+			...(product.rating.bestRating !== undefined ? { bestRating: product.rating.bestRating } : {}),
+		}
+	}
+
+	return result
+}

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

@@ -0,0 +1,20 @@
+import type { ContentItem, JsonLdObject } from '../../types.js'
+
+export function generateVideoJsonLd(item: ContentItem): JsonLdObject {
+	const video = item.video!
+
+	const result: JsonLdObject = {
+		'@context': 'https://schema.org',
+		'@type': 'VideoObject',
+		name: item.title,
+		thumbnailUrl: video.thumbnailUrl,
+		duration: video.duration,
+	}
+
+	if (item.description) result.description = item.description
+	if (video.contentUrl) result.contentUrl = video.contentUrl
+	if (video.embedUrl) result.embedUrl = video.embedUrl
+	if (item.datePublished) result.uploadDate = item.datePublished
+
+	return result
+}

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

@@ -0,0 +1,27 @@
+import type { SeoOptionsWithResolvedSite } from '../../options.js'
+import type { JsonLdObject } from '../../types.js'
+
+export function generateWebSiteJsonLd(options: SeoOptionsWithResolvedSite): JsonLdObject {
+	const { site, organization, locales } = options
+
+	const result: JsonLdObject = {
+		'@context': 'https://schema.org',
+		'@type': 'WebSite',
+		name: organization.name,
+		url: site,
+		potentialAction: {
+			'@type': 'SearchAction',
+			target: {
+				'@type': 'EntryPoint',
+				urlTemplate: `${site}/?q={search_term_string}`,
+			},
+			'query-input': 'required name=search_term_string',
+		},
+	}
+
+	if (locales?.length) {
+		result.inLanguage = locales.map((l) => l.lang)
+	}
+
+	return result
+}

package/src/utils/llms-full.ts

@@ -0,0 +1,90 @@
+import type { ContentItem } from '../types.js'
+import { forLlmsFull } from './content-filter.js'
+
+export interface GenerateLlmsFullOptions {
+	items: ContentItem[]
+	siteName: string
+	// Resolver that produces the full markdown body for an item. Items for which
+	// the resolver returns undefined are emitted as title/url/description only.
+	contentMarkdown?: (item: ContentItem) => string | undefined
+	// Soft cap on total bytes. Defaults to 8 MB. When exceeded, truncation happens
+	// on item boundaries (never mid-body) with a trailing note. Bytes, not UTF-16
+	// length — measured via TextEncoder.
+	maxBytes?: number
+}
+
+const DEFAULT_MAX_BYTES = 8 * 1024 * 1024
+
+/**
+ * Generate `/llms-full.txt` — a bulk public corpus dump for LLM retrievers.
+ *
+ * Structure:
+ *   # <siteName>
+ *
+ *   ## <article title>
+ *   URL: <canonical>
+ *
+ *   <markdown body>
+ *
+ *   ---
+ *
+ *   [next article...]
+ *
+ * Rules:
+ *   - Members items excluded UNCONDITIONALLY.
+ *   - Size cap honored; on-boundary truncation with a note.
+ *   - Deterministic order: items passed in, order preserved.
+ */
+export function generateLlmsFull({
+	items,
+	siteName,
+	contentMarkdown,
+	maxBytes = DEFAULT_MAX_BYTES,
+}: GenerateLlmsFullOptions): string {
+	const filtered = forLlmsFull(items)
+	const encoder = new TextEncoder()
+
+	const header = `# ${siteName}\n\n`
+	let byteCount = encoder.encode(header).length
+	const parts: string[] = [header]
+	let truncated = false
+
+	for (const item of filtered) {
+		const body = contentMarkdown?.(item)
+		const chunk = buildChunk(item, body)
+		const chunkBytes = encoder.encode(chunk).length
+		if (byteCount + chunkBytes > maxBytes) {
+			truncated = true
+			break
+		}
+		parts.push(chunk)
+		byteCount += chunkBytes
+	}
+
+	if (truncated) {
+		parts.push(
+			'\n\n---\n\n> Corpus truncated at configured size cap. See /sitemap-markdown.xml for the full twin URL list.\n',
+		)
+	}
+
+	return parts.join('')
+}
+
+function buildChunk(item: ContentItem, body: string | undefined): string {
+	const lines: string[] = []
+	lines.push(`## ${item.title}`)
+	lines.push('')
+	lines.push(`URL: ${item.url}`)
+	if (item.datePublished) lines.push(`Published: ${item.datePublished}`)
+	if (item.dateModified) lines.push(`Modified: ${item.dateModified}`)
+	lines.push('')
+	if (body) {
+		lines.push(body.trim())
+	} else if (item.description) {
+		lines.push(item.description.trim())
+	}
+	lines.push('')
+	lines.push('---')
+	lines.push('')
+	return `${lines.join('\n')}\n`
+}

package/src/utils/llms.ts

@@ -0,0 +1,45 @@
+import type { ResolvedSeoOptions } from '../options.js'
+
+/**
+ * Generate llms.txt per the llmstxt.org spec
+ * Format: # Title, > description, ## sections with links, ## Optional links
+ */
+export function generateLlmsTxt(options: ResolvedSeoOptions): string {
+	const { organization, llmsContent } = options
+
+	const lines: string[] = []
+
+	// Title
+	lines.push(`# ${organization.name}`)
+	lines.push('')
+
+	if (llmsContent) {
+		// Description block
+		if (llmsContent.description) {
+			lines.push(`> ${llmsContent.description}`)
+			lines.push('')
+		}
+
+		// Sections with links
+		for (const section of llmsContent.sections) {
+			lines.push(`## ${section.heading}`)
+			lines.push('')
+			for (const link of section.links) {
+				lines.push(`- [${link.title}](${link.url}): ${link.description}`)
+			}
+			lines.push('')
+		}
+
+		// Optional links
+		if (llmsContent.optionalLinks?.length) {
+			lines.push('## Optional')
+			lines.push('')
+			for (const link of llmsContent.optionalLinks) {
+				lines.push(`- [${link.title}](${link.url})`)
+			}
+			lines.push('')
+		}
+	}
+
+	return `${lines.join('\n').trimEnd()}\n`
+}

package/src/utils/meta.ts

@@ -0,0 +1,184 @@
+import type { ResolvedSeoOptions } from '../options.js'
+import type { CanonicalLink, ContentItem, MetaTag } from '../types.js'
+
+export type OgVariant = 'article' | 'product' | 'website'
+
+export function applyTrailingSlash(url: string, policy: string): string {
+	if (policy === 'never') {
+		// Strip trailing slash but preserve root slash
+		if (url.endsWith('/') && url !== '/') {
+			try {
+				const parsed = new URL(url)
+				if (parsed.pathname !== '/') {
+					parsed.pathname = parsed.pathname.replace(/\/+$/, '')
+					return parsed.toString()
+				}
+				return url
+			} catch {
+				return url.endsWith('/') && url.length > 1 ? url.slice(0, -1) : url
+			}
+		}
+		return url
+	}
+	if (policy === 'always') {
+		if (!url.endsWith('/')) {
+			try {
+				const parsed = new URL(url)
+				// Don't add slash if there's a query string or hash
+				if (!parsed.search && !parsed.hash) {
+					parsed.pathname = parsed.pathname.replace(/\/*$/, '/')
+					return parsed.toString()
+				}
+				return url
+			} catch {
+				return `${url}/`
+			}
+		}
+		return url
+	}
+	// ignore
+	return url
+}
+
+export function generateCanonical(url: string, options: ResolvedSeoOptions): CanonicalLink {
+	return {
+		rel: 'canonical',
+		href: applyTrailingSlash(url, options.trailingSlash),
+	}
+}
+
+export interface GenerateMetaOptions {
+	// When true, emits <meta name="googlebot" content="noarchive"> to prevent Google
+	// from serving the (paywalled) full body as a cached page under Flexible Sampling.
+	// Called by middleware when the response includes the full gated body for verified
+	// Googlebot.
+	flexibleSamplingActive?: boolean
+}
+
+export function generateMeta(
+	item: ContentItem,
+	variant: OgVariant,
+	options: ResolvedSeoOptions,
+	metaOptions: GenerateMetaOptions = {},
+): MetaTag[] {
+	const tags: MetaTag[] = []
+	const { defaults, organization } = options
+	const canonicalUrl = applyTrailingSlash(item.url, options.trailingSlash)
+	const firstImage = Array.isArray(item.image) ? item.image[0] : item.image
+	const image = firstImage ?? defaults.defaultImage ?? ''
+
+	const ogType =
+		variant === 'article' ? 'article' : variant === 'product' ? 'og:product' : 'website'
+
+	// og:type
+	tags.push({ property: 'og:type', content: ogType })
+
+	// og:title
+	tags.push({ property: 'og:title', content: item.title })
+
+	// og:description
+	if (item.description) {
+		tags.push({ property: 'og:description', content: item.description })
+	}
+
+	// og:url
+	tags.push({ property: 'og:url', content: canonicalUrl })
+
+	// og:image
+	if (image) {
+		tags.push({ property: 'og:image', content: image })
+		tags.push({ property: 'og:image:width', content: '1200' })
+		tags.push({ property: 'og:image:height', content: '630' })
+	}
+
+	// og:site_name
+	tags.push({ property: 'og:site_name', content: organization.name })
+
+	// og:locale
+	const locale = item.locale ?? defaults.locale
+	tags.push({ property: 'og:locale', content: locale })
+
+	// og:locale:alternate
+	if (item.alternateLocales?.length) {
+		for (const alt of item.alternateLocales) {
+			tags.push({ property: 'og:locale:alternate', content: alt.lang })
+		}
+	}
+
+	// twitter:card
+	tags.push({ name: 'twitter:card', content: defaults.twitterCardType })
+
+	// twitter:site
+	if (defaults.twitterSite) {
+		tags.push({ name: 'twitter:site', content: defaults.twitterSite })
+	}
+
+	// twitter:title
+	tags.push({ name: 'twitter:title', content: item.title })
+
+	// twitter:description
+	if (item.description) {
+		tags.push({ name: 'twitter:description', content: item.description })
+	}
+
+	// twitter:image
+	if (image) {
+		tags.push({ name: 'twitter:image', content: image })
+	}
+
+	// robots
+	tags.push({ name: 'robots', content: 'max-image-preview:large' })
+
+	// Flexible Sampling: prevent Google from serving the premium body from cache.
+	if (metaOptions.flexibleSamplingActive) {
+		tags.push({ name: 'googlebot', content: 'noarchive' })
+	}
+
+	// Apple News meta tags.
+	// `apple-news-publishable` is opt-in for the channel to pick up the article.
+	// Resolved at item level: `appleNewsPublishable: 'no'` overrides the channel default.
+	// Channel default comes from options.appleNews.defaultPublishable.
+	if (options.appleNews?.enabled) {
+		const channelDefault = options.appleNews.defaultPublishable
+		const effective = item.appleNewsPublishable ?? channelDefault
+		if (effective === 'yes' && item.access !== 'members') {
+			tags.push({ name: 'apple-news-publishable', content: 'yes' })
+		}
+		if (item.appleNewsId) {
+			tags.push({ name: 'apple-news-id', content: item.appleNewsId })
+		}
+	}
+
+	// news_keywords — read by both Google News and Apple News.
+	if (item.newsKeywords?.length) {
+		tags.push({ name: 'news_keywords', content: item.newsKeywords.join(', ') })
+	}
+
+	// Article-specific
+	if (variant === 'article') {
+		if (item.datePublished) {
+			tags.push({ property: 'article:published_time', content: item.datePublished })
+		}
+		if (item.dateModified) {
+			tags.push({ property: 'article:modified_time', content: item.dateModified })
+		}
+		if (item.authors?.length) {
+			for (const author of item.authors) {
+				tags.push({ property: 'article:author', content: author.url ?? author.name })
+			}
+		}
+	}
+
+	// Product-specific
+	if (variant === 'product' && item.product) {
+		const p = item.product
+		tags.push({ property: 'product:price:amount', content: String(p.price) })
+		tags.push({ property: 'product:price:currency', content: p.currency })
+		tags.push({ property: 'product:availability', content: p.availability })
+		if (p.brand) {
+			tags.push({ property: 'product:brand', content: p.brand })
+		}
+	}
+
+	return tags
+}

package/src/utils/podcast.ts

@@ -0,0 +1,112 @@
+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;')
+}
+
+/**
+ * Convert ISO 8601 duration (e.g. PT8M30S, PT1H2M3S) to M:SS or H:MM:SS
+ */
+export function convertIso8601Duration(duration: string): string {
+	const match = duration.match(/^PT(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?$/)
+	if (!match) return duration
+
+	const hours = parseInt(match[1] ?? '0', 10)
+	const minutes = parseInt(match[2] ?? '0', 10)
+	const seconds = parseInt(match[3] ?? '0', 10)
+
+	if (hours > 0) {
+		const mm = String(minutes).padStart(2, '0')
+		const ss = String(seconds).padStart(2, '0')
+		return `${hours}:${mm}:${ss}`
+	}
+	const ss = String(seconds).padStart(2, '0')
+	return `${minutes}:${ss}`
+}
+
+function toRfc822(dateStr: string): string {
+	return new Date(dateStr).toUTCString()
+}
+
+export function generatePodcastFeed(
+	episodes: ContentItem[],
+	options: SeoOptionsWithResolvedSite,
+): string {
+	const { site, organization } = options
+	const podcast = options.podcast
+
+	// Use podcast config if available, fall back to organization
+	const author = podcast?.author ?? organization.name
+	const podcastTitle = podcast?.title ?? organization.name
+	const podcastDescription = podcast?.description ?? ''
+	const podcastImage = podcast?.image ?? organization.logo
+	const podcastCategory = podcast?.category ?? 'Technology'
+	const podcastLanguage = podcast?.language ?? 'en'
+	const podcastExplicit = podcast?.explicit ?? false
+	const podcastType = podcast?.type ?? 'episodic'
+	const ownerEmail = podcast?.email ?? ''
+
+	const episodesXml = episodes
+		.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 enclosureTag = item.audio
+				? `\n      <enclosure url="${escapeXml(item.audio.url)}" type="audio/mpeg" length="0"/>`
+				: ''
+
+			const durationTag = item.audio?.duration
+				? `\n      <itunes:duration>${escapeXml(convertIso8601Duration(item.audio.duration))}</itunes:duration>`
+				: ''
+
+			const ep = item.podcastEpisode
+			const episodeTag =
+				ep?.episodeNumber != null
+					? `\n      <itunes:episode>${ep.episodeNumber}</itunes:episode>`
+					: ''
+			const seasonTag =
+				ep?.seasonNumber != null ? `\n      <itunes:season>${ep.seasonNumber}</itunes:season>` : ''
+			const episodeTypeTag = ep?.episodeType
+				? `\n      <itunes:episodeType>${escapeXml(ep.episodeType)}</itunes:episodeType>`
+				: ''
+
+			return `    <item>
+      <title>${escapeXml(item.title)}</title>
+      <link>${escapeXml(item.url)}</link>
+      <guid isPermaLink="true">${escapeXml(item.url)}</guid>${pubDateTag}${descTag}${enclosureTag}${durationTag}${episodeTag}${seasonTag}${episodeTypeTag}
+    </item>`
+		})
+		.join('\n')
+
+	return `<?xml version="1.0" encoding="UTF-8"?>
+<rss version="2.0"
+  xmlns:itunes="http://www.itunes.com/dtds/podcast-1.0.dtd"
+  xmlns:podcast="https://podcastindex.org/namespace/1.0"
+  xmlns:atom="http://www.w3.org/2005/Atom">
+  <channel>
+    <title>${escapeXml(podcastTitle)}</title>
+    <description>${escapeXml(podcastDescription)}</description>
+    <link>${escapeXml(site)}</link>
+    <language>${escapeXml(podcastLanguage)}</language>
+    <itunes:author>${escapeXml(author)}</itunes:author>
+    <itunes:owner>
+      <itunes:name>${escapeXml(author)}</itunes:name>
+      <itunes:email>${escapeXml(ownerEmail)}</itunes:email>
+    </itunes:owner>
+    <itunes:image href="${escapeXml(podcastImage)}"/>
+    <itunes:category text="${escapeXml(podcastCategory)}"/>
+    <itunes:explicit>${podcastExplicit ? 'true' : 'false'}</itunes:explicit>
+    <itunes:type>${escapeXml(podcastType)}</itunes:type>
+${episodesXml}
+  </channel>
+</rss>`
+}

package/src/utils/robots.ts

@@ -0,0 +1,47 @@
+import type { SeoOptionsWithResolvedSite } from '../options.js'
+import { SITEMAP_INDEX_PATH } from './sitemap.js'
+
+export interface GenerateRobotsTxtOptions {
+	/**
+	 * Emit a `Sitemap:` line pointing at SITEMAP_INDEX_PATH.
+	 *
+	 * The caller is responsible for ensuring the sitemap index route is
+	 * actually being served. Pass `false` when no content provider is wired;
+	 * otherwise crawlers follow the Sitemap: line to an empty or 404 index,
+	 * which is a live, crawler-visible SEO regression.
+	 */
+	includeSitemap: boolean
+}
+
+export function generateRobotsTxt(
+	options: SeoOptionsWithResolvedSite,
+	{ includeSitemap }: GenerateRobotsTxtOptions,
+): string {
+	const { site, robots } = options
+	const lines: string[] = []
+
+	lines.push('User-agent: *')
+	lines.push('Allow: /')
+	if (includeSitemap) {
+		lines.push(`Sitemap: ${new URL(SITEMAP_INDEX_PATH, site).toString()}`)
+	}
+
+	if (robots.additionalRules?.length) {
+		for (const rule of robots.additionalRules) {
+			lines.push('')
+			lines.push(`User-agent: ${rule.userAgent}`)
+			if (rule.allow?.length) {
+				for (const path of rule.allow) {
+					lines.push(`Allow: ${path}`)
+				}
+			}
+			if (rule.disallow?.length) {
+				for (const path of rule.disallow) {
+					lines.push(`Disallow: ${path}`)
+				}
+			}
+		}
+	}
+
+	return `${lines.join('\n')}\n`
+}