npm - @growth-labs/seo - Versions diffs - 0.4.0 → 0.4.2 - Mend

@growth-labs/seo 0.4.0 → 0.4.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (68) hide show

package/dist/utils/validation.d.ts.map +1 -1
package/dist/utils/validation.js +22 -0
package/dist/utils/validation.js.map +1 -1
package/package.json +9 -5
package/src/_internal/state.ts +26 -0
package/src/bindings.ts +146 -0
package/src/cron/prune-aeo-r2.ts +140 -0
package/src/durable-objects/aeo-revalidation-coord.ts +246 -0
package/src/index.ts +380 -0
package/src/middleware/seo.ts +350 -0
package/src/options.ts +456 -0
package/src/routes/aeo-twin.ts +130 -0
package/src/routes/apple-news.ts +36 -0
package/src/routes/llms-full.ts +36 -0
package/src/routes/llms.ts +15 -0
package/src/routes/podcast-narration.ts +45 -0
package/src/routes/podcast.ts +27 -0
package/src/routes/revalidate.ts +298 -0
package/src/routes/robots.ts +21 -0
package/src/routes/rss.ts +29 -0
package/src/routes/sitemap-articles.ts +25 -0
package/src/routes/sitemap-index.ts +89 -0
package/src/routes/sitemap-markdown.ts +39 -0
package/src/routes/sitemap-pages.ts +24 -0
package/src/routes/sitemap-products.ts +24 -0
package/src/routes/sitemap-videos.ts +24 -0
package/src/runtime.ts +17 -0
package/src/site-url-core.ts +71 -0
package/src/site-url.ts +21 -0
package/src/types.ts +166 -0
package/src/utils/aeo-summary.ts +176 -0
package/src/utils/aeo-twin-emitter.ts +173 -0
package/src/utils/aeo.ts +223 -0
package/src/utils/apple-news-anf.ts +163 -0
package/src/utils/apple-news-rss.ts +136 -0
package/src/utils/content-filter.ts +87 -0
package/src/utils/crawler-class.ts +155 -0
package/src/utils/define-content-provider.ts +65 -0
package/src/utils/effective-auth.ts +44 -0
package/src/utils/fcrdns.ts +269 -0
package/src/utils/fresh-layer.ts +175 -0
package/src/utils/hreflang.ts +26 -0
package/src/utils/index.ts +91 -0
package/src/utils/json-ld/article.ts +120 -0
package/src/utils/json-ld/audio.ts +32 -0
package/src/utils/json-ld/breadcrumb.ts +28 -0
package/src/utils/json-ld/faq.ts +18 -0
package/src/utils/json-ld/howto.ts +23 -0
package/src/utils/json-ld/index.ts +12 -0
package/src/utils/json-ld/item-list.ts +26 -0
package/src/utils/json-ld/organization.ts +42 -0
package/src/utils/json-ld/person.ts +25 -0
package/src/utils/json-ld/product.ts +155 -0
package/src/utils/json-ld/video.ts +20 -0
package/src/utils/json-ld/website.ts +27 -0
package/src/utils/llms-full.ts +90 -0
package/src/utils/llms.ts +45 -0
package/src/utils/meta.ts +184 -0
package/src/utils/podcast.ts +112 -0
package/src/utils/robots.ts +47 -0
package/src/utils/rss.ts +64 -0
package/src/utils/seo-head.ts +81 -0
package/src/utils/sitemap-markdown.ts +80 -0
package/src/utils/sitemap.ts +169 -0
package/src/utils/staleness.ts +61 -0
package/src/utils/validation.ts +308 -0
package/src/virtual.d.ts +8 -0
package/src/vite-plugin.ts +66 -0

package/src/options.ts ADDED Viewed

@@ -0,0 +1,456 @@
+import { z } from 'zod'
+import { validateSiteUrl } from './site-url-core.js'
+import type { ContentItem, ContentProvider } from './types.js'
+// ─── Locale ───
+const localeSchema = z.object({
+	lang: z.string(),
+	region: z.string().optional(),
+	urlPrefix: z.string(),
+	domain: z.string().optional(),
+})
+// ─── Podcast ───
+const podcastSchema = z.object({
+	enabled: z.boolean().default(false),
+	title: z.string(),
+	description: z.string(),
+	author: z.string(),
+	email: z.string().email(),
+	image: z.string().url(),
+	category: z.string(),
+	subcategory: z.string().optional(),
+	language: z.string().default('en'),
+	explicit: z.boolean().default(false),
+	feedPath: z.string().default('/podcast.xml'),
+	type: z.enum(['episodic', 'serial']).default('episodic'),
+	copyright: z.string().optional(),
+})
+// ─── Commerce ───
+const commerceSchema = z.object({
+	enabled: z.boolean().default(false),
+	returnPolicy: z
+		.object({
+			applicableCountry: z.string(),
+			returnPolicyCategory: z.enum([
+				'MerchantReturnFiniteReturnWindow',
+				'MerchantReturnNotPermitted',
+				'MerchantReturnUnlimitedWindow',
+			]),
+			merchantReturnDays: z.number().optional(),
+			returnMethod: z.enum(['ReturnByMail', 'ReturnInStore', 'ReturnAtKiosk']).optional(),
+			returnFees: z.enum(['FreeReturn', 'ReturnFeesCustomerResponsibility']).optional(),
+		})
+		.optional(),
+	currency: z.string().default('USD'),
+})
+// ─── Apple News ───
+const appleNewsSchema = z.object({
+	enabled: z.boolean().default(false),
+	channelName: z.string(),
+	channelId: z.string().optional(),
+	feedPath: z.string().default('/apple-news.xml'),
+	// Default publishable state applied to items that don't set their own apple-news-publishable.
+	// 'yes' opts every public article in by default.
+	defaultPublishable: z.enum(['yes', 'no']).default('yes'),
+	// Default Apple News section. Per-article sections can override.
+	defaultSection: z.string().optional(),
+	// If true, include full article body in content:encoded (recommended).
+	fullContent: z.boolean().default(true),
+	// Emit <link rel="alternate" type="application/rss+xml" title="Apple News"> in <head>.
+	discoveryLink: z.boolean().default(true),
+})
+// ─── Fresh-twin storage layer ───
+const freshLayerSchema = z.object({
+	// Binding name in wrangler.toml (R2 bucket or KV namespace).
+	bindingName: z.string().default('AEO_TWINS'),
+	// 'r2' (preferred) or 'kv'. Autodetected from the binding shape at runtime;
+	// the explicit hint avoids ambiguity.
+	type: z.enum(['r2', 'kv']).default('r2'),
+	// Durable Object class binding for revalidation coordination. A single DO class
+	// handles rate limit, per-slug lock, and idempotency; one instance per request-hostname.
+	coordinatorBindingName: z.string().default('AEO_REVALIDATION_COORD'),
+	// Days to retain old-version R2 prefixes before the scheduled prune Worker deletes them.
+	retentionDays: z.number().int().min(1).max(365).default(7),
+})
+// ─── AEO twins (object form) ───
+//
+// The boolean form `aeoTwins: true` is equivalent to `{ mode: 'static' }`.
+// The object form exposes full configuration.
+const aeoTwinsObjectSchema = z.object({
+	// 'static'     — emit prerendered .md files at build time (default, fastest serve path)
+	// 'middleware' — serve .md via Accept: text/markdown on same URL (requires SSR)
+	// 'both'       — emit static twins AND run middleware negotiation (freshness on cache-miss
+	//                via on-demand revalidation)
+	//
+	// STALENESS WARNING: `static` mode is frozen at build time. If HTML is editable
+	// post-publish (CMS corrections, breaking-news updates), the .md twin will drift.
+	// Answer engines that compare the two may downgrade trust.
+	//   - Immutable-after-publish content -> `static` is safe.
+	//   - Mutable content -> `both` + `onDemandRevalidation` + CMS webhook.
+	//   - Gated content with Flexible Sampling -> `middleware` (rejected with `static`).
+	mode: z.enum(['static', 'middleware', 'both']).default('static'),
+	// Maps an article URL to its PRIMARY markdown twin URL (singular). The primary URL is
+	// the canonical twin used in the Link: rel="alternate" header, sitemap-markdown.xml,
+	// and summary-twin naming (<primary>.summary.md).
+	// Default: appends '.md' (e.g. /article/midway -> /article/midway.md).
+	twinUrl: z.function().args(z.string()).returns(z.string()).optional(),
+	// Alias suffixes that redirect (301) to the primary twin URL via middleware.
+	// Only active when `mode !== 'static'` (pure-static aliases were dropped in v7;
+	// they created a weak fallback when Cloudflare Assets can't serve 301s).
+	// Default: ['/index.md'] so `/article/midway/index.md` aliases to `/article/midway.md`
+	// under middleware-backed modes.
+	twinAliases: z.array(z.string()).default(['/index.md']),
+	// Emit a short "summary twin" (~300 tokens) at <primary-twin-url>.summary.md
+	// for context-limited agents (Perplexity, Apple Intelligence, long-convo ChatGPT).
+	summaryTwin: z.boolean().default(true),
+	// Emit semantic chunk markers (<!-- aeo:section --> comments) in .md bodies so
+	// RAG retrievers split on our boundaries, not theirs.
+	ragChunkMarkers: z.boolean().default(true),
+	// Headers applied to every emitted .md file. Defaults enforce canonicalization
+	// back to the HTML master to prevent duplicate-content issues.
+	responseHeaders: z
+		.object({
+			noindex: z.boolean().default(true), // X-Robots-Tag: noindex
+			canonicalToHtml: z.boolean().default(true), // Link: <html-url>; rel="canonical"
+		})
+		.default({}),
+	// Predicate to filter items at twin-emission time. Defaults to the access rule
+	// (no twin for members). Override for custom gating (e.g. exclude previews).
+	include: z.function().args(z.custom<ContentItem>()).returns(z.boolean()).optional(),
+	// When to treat static twins as stale vs live HTML.
+	// 'content-hash' — SHA-256 of body+description embedded in frontmatter; validation
+	//                   hook compares against the current contentProvider output at build time.
+	// 'dateModified' — compare frontmatter.dateModified against item.dateModified.
+	// 'none'         — never check (only safe for immutable-after-publish content).
+	stalenessCheck: z.enum(['content-hash', 'dateModified', 'none']).default('content-hash'),
+	// Expose `POST /_seo/revalidate` for CMS webhooks to push fresh twins.
+	// Requires `freshLayer` + a `revalidateToken` >= 32 bytes (enforced at parse time).
+	onDemandRevalidation: z.boolean().default(false),
+	// Authentication token for the revalidate endpoint. Passed as `Authorization: Bearer`.
+	// Must be >=32 bytes when `onDemandRevalidation: true`; rejected at config-parse
+	// otherwise (a short token means a public unauthenticated DoS vector).
+	revalidateToken: z.string().min(32).optional(),
+	// Fresh-twin storage layer. Required when `mode !== 'static'` or `onDemandRevalidation: true`.
+	// Cloudflare Workers Assets are immutable at runtime, so post-build twin writes go here.
+	freshLayer: freshLayerSchema.optional(),
+})
+// ─── Flexible Sampling (Google paywall policy) ───
+const flexibleSamplingSchema = z
+	.object({
+		enabled: z.boolean().default(false),
+		// Free-content strategy visible to anonymous users.
+		sampleMode: z.enum(['metered', 'lead-in', 'none']).default('lead-in'),
+		// Paragraphs of lead-in visible before the gate.
+		leadInParagraphs: z.number().int().min(0).default(2),
+		// Free articles per rolling 30 days for 'metered' mode. Consumer enforces count;
+		// this option surfaces the signal to the package.
+		meteredLimit: z.number().int().min(0).default(3),
+	})
+	.default({})
+// ─── Crawler policy ───
+const crawlerPolicySchema = z
+	.object({
+		// Block known LLM training crawlers at robots.txt AND via 403 at middleware on `access: 'members'`.
+		blockLlmTrainingCrawlers: z.boolean().default(true),
+		// User-directed LLM agents (ChatGPT-User, Claude-User, PerplexityBot-User) get the anonymous
+		// gated body, regardless of cookies. Never the full member body.
+		userDirectedAgentsSeePublicOnly: z.boolean().default(true),
+		// If true, verified Googlebot/Bingbot/Applebot receive full body on `access: 'members'`
+		// items with paywall JSON-LD markup (requires `flexibleSampling.enabled`).
+		verifiedSearchCrawlersSeeFullBody: z.boolean().default(true),
+	})
+	.default({})
+// ─── Main schema ───
+const siteUrlSchema = z.union([
+	z.string().url(),
+	z
+		.function()
+		.args()
+		.returns(z.string())
+		.transform((resolver) => validateSiteUrl(resolver(), 'site resolver return value')),
+	z.object({ envVar: z.string().min(1) }).strict(),
+])
+export const seoOptionsSchema = z.object({
+	// ─── Required ───
+	site: siteUrlSchema,
+	organization: z.object({
+		name: z.string(),
+		url: z.string().url().optional(),
+		logo: z.string().url(),
+		sameAs: z.array(z.string().url()).optional(),
+	}),
+	// ─── Schema type for articles ───
+	schemaType: z.enum(['Article', 'NewsArticle', 'BlogPosting']).default('Article'),
+	// ─── Feature flags ───
+	googleNews: z.boolean().default(false),
+	llmsTxt: z.boolean().default(false),
+	llmsFullTxt: z.boolean().default(false),
+	markdownSitemap: z.boolean().default(true),
+	rss: z.boolean().default(false),
+	// ─── AEO twins ───
+	// Boolean form = { mode: 'static' } when true, no twins emitted when false.
+	aeoTwins: z.union([z.boolean(), aeoTwinsObjectSchema]).default(false),
+	// ─── Multilingual ───
+	locales: z.array(localeSchema).optional(),
+	defaultLocale: z.string().optional(),
+	// ─── Podcast ───
+	podcast: podcastSchema.optional(),
+	// ─── Apple News ───
+	appleNews: appleNewsSchema.optional(),
+	// ─── Commerce ───
+	commerce: commerceSchema.optional(),
+	// ─── Audio narration ───
+	audioNarration: z
+		.object({
+			enabled: z.boolean().default(false),
+			speakableSelectors: z.array(z.string()).default(['.article-headline', '.article-body']),
+			narratorName: z.string().optional(),
+			asPodcastFeed: z.boolean().default(false),
+			podcastFeedPath: z.string().default('/listen.xml'),
+		})
+		.optional(),
+	// ─── Flexible Sampling ───
+	flexibleSampling: flexibleSamplingSchema,
+	// ─── Crawler policy ───
+	crawlerPolicy: crawlerPolicySchema,
+	// ─── Trailing slash policy ───
+	trailingSlash: z.enum(['always', 'never', 'ignore']).default('never'),
+	// ─── Content-Signal header (Cloudflare convention) ───
+	contentSignal: z
+		.object({
+			aiTrain: z.enum(['yes', 'no']).default('no'),
+			search: z.enum(['yes', 'no']).default('yes'),
+			aiInput: z.enum(['yes', 'no']).default('yes'),
+		})
+		.default({}),
+	// ─── Validation thresholds ───
+	validation: z
+		.object({
+			heroMinWidth: z.number().default(1200),
+			titleMaxLength: z.number().default(110),
+			descriptionMaxLength: z.number().default(160),
+			enabled: z.boolean().default(true),
+		})
+		.default({}),
+	// ─── robots.txt ───
+	robots: z
+		.object({
+			additionalRules: z
+				.array(
+					z.object({
+						userAgent: z.string(),
+						allow: z.array(z.string()).optional(),
+						disallow: z.array(z.string()).optional(),
+					}),
+				)
+				.optional(),
+		})
+		.default({}),
+	// ─── Default meta ───
+	defaults: z
+		.object({
+			titleSuffix: z.string().optional(),
+			defaultImage: z.string().url().optional(),
+			twitterSite: z.string().optional(),
+			twitterCardType: z.enum(['summary', 'summary_large_image']).default('summary_large_image'),
+			locale: z.string().default('en_US'),
+		})
+		.default({}),
+	// ─── Content data provider (DEPRECATED) ───
+	/**
+	 * @deprecated Use `contentProviderModule` instead. Inline function providers
+	 * do not survive the Cloudflare prerender Worker because the Astro
+	 * Cloudflare adapter prerenders static routes in a separate Worker process
+	 * that does not re-execute `astro.config.mjs`. The integration still accepts
+	 * this form and emits a `logger.warn` at `astro:config:setup`; it will be
+	 * removed in the next breaking release.
+	 *
+	 * See packages-docs/seo-contentprovidermodule.md for the migration.
+	 */
+	contentProvider: z.custom<ContentProvider>().optional(),
+	// ─── Content provider module path (for Cloudflare prerender workers) ───
+	// When the Astro Cloudflare adapter prerenders routes, it spawns a separate
+	// Worker process that does NOT re-execute astro.config.mjs — so a
+	// `contentProvider` function set in the main build-time Node process never
+	// reaches the prerender Worker. Injected prerender routes (specifically
+	// `/[...aeoPath].md`) would fail with "integration not initialized".
+	//
+	// The fix: pass the provider as a module specifier here. The vite plugin
+	// emits an import into its generated virtual module so every environment
+	// Vite bundles — main Worker AND prerender Worker — seeds state at load.
+	//
+	// Specifier form: a Vite-resolvable import path. Project-root-relative
+	// (e.g. '/src/lib/content-provider.ts') is the usual case. The module must
+	// default-export a function matching the ContentProvider signature.
+	contentProviderModule: z.string().optional(),
+	// ─── llms.txt content ───
+	llmsContent: z
+		.object({
+			description: z.string(),
+			sections: z.array(
+				z.object({
+					heading: z.string(),
+					links: z.array(
+						z.object({
+							title: z.string(),
+							url: z.string(),
+							description: z.string(),
+						}),
+					),
+				}),
+			),
+			optionalLinks: z.array(z.object({ title: z.string(), url: z.string() })).optional(),
+		})
+		.optional(),
+})
+// ─── Cross-field validation ───
+//
+// Enforces invariants Zod's type system can't express on its own. These are hard
+// errors at parse time — not runtime surprises. Three invariants:
+//
+//   1. `flexibleSampling.enabled: true` + `aeoTwins.mode: 'static'` is rejected
+//      (static mode has no Worker to run the verified-Googlebot dispatch).
+//   2. `mode !== 'static'` OR `onDemandRevalidation: true` requires `freshLayer`
+//      (the R2/KV binding that stores post-build twin writes).
+//   3. `onDemandRevalidation: true` requires `revalidateToken >= 32` bytes
+//      (shorter means a public unauthenticated DoS vector; enforced here rather
+//      than discovered at runtime).
+//
+// A fourth implicit rejection: `mode: 'static'` + `onDemandRevalidation: true`
+// is incoherent — static mode has no Worker to intercept revalidation writes,
+// so R2 pushes never reach requests.
+export const validatedSeoOptionsSchema = seoOptionsSchema.superRefine((opts, ctx) => {
+	// Normalize aeoTwins to the object form for cross-field checks.
+	const aeo =
+		typeof opts.aeoTwins === 'boolean'
+			? opts.aeoTwins
+				? { mode: 'static' as const, onDemandRevalidation: false }
+				: undefined
+			: opts.aeoTwins
+	if (!aeo) {
+		// aeoTwins: false (or unset default false) -> no further checks needed.
+		// Flexible Sampling without any AEO mode set is also fine (just no markdown twins).
+		return
+	}
+	const mode = aeo.mode
+	const onDemand = 'onDemandRevalidation' in aeo && aeo.onDemandRevalidation === true
+	const token = 'revalidateToken' in aeo ? aeo.revalidateToken : undefined
+	const freshLayer = 'freshLayer' in aeo ? aeo.freshLayer : undefined
+	// Invariant 1: Flexible Sampling cannot run on static mode.
+	if (opts.flexibleSampling?.enabled && mode === 'static') {
+		ctx.addIssue({
+			code: z.ZodIssueCode.custom,
+			path: ['flexibleSampling', 'enabled'],
+			message:
+				"flexibleSampling.enabled requires aeoTwins.mode 'middleware' or 'both'. " +
+				'Static mode has no Worker to run the crawler-class dispatch, so verified Googlebot ' +
+				'never receives the full-body paywall JSON-LD. Set mode to "middleware" or "both".',
+		})
+	}
+	// Invariant 4: static + onDemandRevalidation is incoherent.
+	if (mode === 'static' && onDemand) {
+		ctx.addIssue({
+			code: z.ZodIssueCode.custom,
+			path: ['aeoTwins', 'onDemandRevalidation'],
+			message:
+				"onDemandRevalidation requires aeoTwins.mode 'middleware' or 'both' — static mode " +
+				'serves files directly from Cloudflare Assets with no Worker hop, so R2 writes from ' +
+				'the revalidate endpoint would never reach requests.',
+		})
+	}
+	// Invariant 2: freshLayer required when mode !== 'static' or onDemandRevalidation.
+	const needsFreshLayer = (mode !== undefined && mode !== 'static') || onDemand
+	if (needsFreshLayer && !freshLayer) {
+		ctx.addIssue({
+			code: z.ZodIssueCode.custom,
+			path: ['aeoTwins', 'freshLayer'],
+			message:
+				`aeoTwins.freshLayer is required when mode='${mode ?? 'undefined'}' or ` +
+				'onDemandRevalidation=true. Configure an R2 or KV binding plus a Durable Object ' +
+				'binding in wrangler.toml and reference them via { bindingName, coordinatorBindingName }.',
+		})
+	}
+	// Invariant 3: onDemandRevalidation requires >=32 byte token.
+	if (onDemand && (!token || token.length < 32)) {
+		ctx.addIssue({
+			code: z.ZodIssueCode.custom,
+			path: ['aeoTwins', 'revalidateToken'],
+			message:
+				'onDemandRevalidation requires a revalidateToken of at least 32 characters. ' +
+				'Generate one with `openssl rand -base64 32` and store it in your environment.',
+		})
+	}
+})
+export type SeoOptions = z.input<typeof validatedSeoOptionsSchema>
+export type ResolvedSeoOptions = z.output<typeof validatedSeoOptionsSchema>
+export type SeoOptionsWithResolvedSite = Omit<ResolvedSeoOptions, 'site'> & { site: string }
+/**
+ * Resolves the aeoTwins field to its object form for downstream consumers.
+ * `aeoTwins: true`  -> { mode: 'static', ...defaults }
+ * `aeoTwins: false` -> undefined (no twins)
+ * `aeoTwins: { ... }` -> as-is with schema defaults applied
+ */
+export function resolveAeoTwins(
+	aeoTwins: ResolvedSeoOptions['aeoTwins'],
+): z.output<typeof aeoTwinsObjectSchema> | undefined {
+	if (aeoTwins === false) return undefined
+	if (aeoTwins === true) {
+		// Apply schema defaults by parsing an empty object.
+		return aeoTwinsObjectSchema.parse({})
+	}
+	return aeoTwins
+}

package/src/routes/aeo-twin.ts ADDED Viewed

@@ -0,0 +1,130 @@
+import 'virtual:growth-labs/seo/config'
+// Dynamic prerender route that emits AEO markdown twins at build time.
+//
+// This replaces the previous `astro:build:done` filesystem-write approach. The
+// problem with that approach: integration hooks run in raw Node ESM, where
+// Vite-virtual imports like `astro:content` can't resolve. Consumers whose
+// `contentProvider` transitively imported `astro:content` saw zero twin files
+// emitted. Reference: https://github.com/withastro/astro/issues/...
+//
+// getStaticPaths runs INSIDE Astro's build pipeline, so Vite resolves virtual
+// modules correctly. The route produces one prerendered file per twin URL:
+// primary at `/article/midway.md` and, when enabled, summary at
+// `/article/midway.md.summary.md`.
+import type { APIRoute, GetStaticPaths } from 'astro'
+import { getConfig, getContentProvider } from '../_internal/state.js'
+import { resolveAeoTwins } from '../options.js'
+import type { ContentItem } from '../types.js'
+import { estimateTokenCount, generateAeoMarkdown } from '../utils/aeo.js'
+import { generateSummaryTwin } from '../utils/aeo-summary.js'
+import { forMarkdownTwin } from '../utils/content-filter.js'
+import { computeContentHash } from '../utils/staleness.js'
+// Prerender these URLs at build time so they're served as static files.
+export const prerender = true
+interface TwinPathProps {
+	body: string
+	kind: 'primary' | 'summary'
+	// Astro's GetStaticPaths Props type requires an index signature.
+	[key: string]: unknown
+}
+function defaultTwin(url: string): string {
+	return `${url.replace(/\/+$/, '')}.md`
+}
+function stripOrigin(url: string): string {
+	try {
+		return new URL(url).pathname
+	} catch {
+		return url.startsWith('/') ? url : `/${url}`
+	}
+}
+export const getStaticPaths: GetStaticPaths = async () => {
+	const config = getConfig()
+	const contentProvider = getContentProvider()
+	const aeo = resolveAeoTwins(config.aeoTwins)
+	// Emit twins for static + both modes; middleware mode serves on-demand.
+	if (!aeo || aeo.mode === 'middleware' || !contentProvider) return []
+	let items: ContentItem[]
+	try {
+		// contentProvider resolves here because this function runs inside Astro's
+		// build pipeline — `astro:content` and other Vite virtual modules work.
+		items = await contentProvider({ type: 'articles' }, {} as never)
+	} catch {
+		// Don't fail the build; log nothing here because astro's getStaticPaths
+		// swallows console output. The consumer sees "zero paths emitted" which
+		// is the right signal to inspect their contentProvider.
+		return []
+	}
+	const filtered = forMarkdownTwin(items).filter(aeo.include ?? (() => true))
+	const twinUrl = aeo.twinUrl ?? defaultTwin
+	const emitSummary = aeo.summaryTwin !== false
+	const ragMarkers = aeo.ragChunkMarkers !== false
+	const stalenessMode = aeo.stalenessCheck ?? 'content-hash'
+	const paths: Array<{ params: { aeoPath: string }; props: TwinPathProps }> = []
+	for (const item of filtered) {
+		const primaryUrl = twinUrl(item.url)
+		const primaryPath = stripOrigin(primaryUrl).replace(/^\//, '')
+		const body = item.description ?? ''
+		const contentHash =
+			stalenessMode === 'content-hash' ? await computeContentHash(item, body) : undefined
+		const summaryUrl = emitSummary ? `${primaryUrl}.summary.md` : undefined
+		// Primary twin.
+		paths.push({
+			params: { aeoPath: primaryPath.replace(/\.md$/, '') },
+			props: {
+				body: generateAeoMarkdown(item, {
+					publisherName: config.organization.name,
+					schemaType: config.schemaType,
+					content: body,
+					ragChunkMarkers: ragMarkers,
+					canonical: item.url,
+					twinUrl: primaryUrl,
+					summaryUrl,
+					contentHash,
+				}),
+				kind: 'primary',
+			},
+		})
+		// Summary twin.
+		if (emitSummary && summaryUrl) {
+			const summaryPath = stripOrigin(summaryUrl).replace(/^\//, '').replace(/\.md$/, '')
+			const summary = generateSummaryTwin(item, {
+				publisherName: config.organization.name,
+				schemaType: config.schemaType,
+				content: body,
+				fullUrl: primaryUrl,
+			})
+			paths.push({
+				params: { aeoPath: summaryPath },
+				props: { body: summary.markdown, kind: 'summary' },
+			})
+		}
+	}
+	return paths
+}
+export const GET: APIRoute = async ({ props }) => {
+	const { body } = props as unknown as TwinPathProps
+	const tokenCount = estimateTokenCount(body)
+	return new Response(body, {
+		headers: {
+			'Content-Type': 'text/markdown; charset=utf-8',
+			'X-Robots-Tag': 'noindex',
+			'x-markdown-tokens': String(tokenCount),
+		},
+	})
+}

package/src/routes/apple-news.ts ADDED Viewed

@@ -0,0 +1,36 @@
+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 { generateAppleNewsRss } from '../utils/apple-news-rss.js'
+export const prerender = false
+export const GET: APIRoute = async (context) => {
+	const config = resolveSeoConfig(getConfig())
+	const contentProvider = getContentProvider()
+	if (!config.appleNews?.enabled) {
+		return new Response('Apple News not enabled', { status: 404 })
+	}
+	let articles: ContentItem[] = []
+	if (contentProvider) {
+		try {
+			articles = await contentProvider({ type: 'articles' }, context)
+		} catch {}
+	}
+	// content-filter.forAppleNews is applied inside generateAppleNewsRss.
+	const xml = generateAppleNewsRss({
+		items: articles,
+		options: config,
+		// Consumers can supply an HTML resolver by extending the config surface.
+		// For v1, pass through; description-only is acceptable when fullContent: false.
+	})
+	return new Response(xml, {
+		headers: { 'Content-Type': 'application/rss+xml; charset=utf-8' },
+	})
+}

package/src/routes/llms-full.ts ADDED Viewed

@@ -0,0 +1,36 @@
+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 { generateLlmsFull } from '../utils/llms-full.js'
+export const prerender = false
+export const GET: APIRoute = async (context) => {
+	const config = getConfig()
+	const contentProvider = getContentProvider()
+	if (!config.llmsFullTxt) {
+		return new Response('llms-full.txt disabled', { status: 404 })
+	}
+	let articles: ContentItem[] = []
+	if (contentProvider) {
+		try {
+			articles = await contentProvider({ type: 'articles' }, context)
+		} catch {}
+	}
+	// Members items excluded by forLlmsFull inside the generator.
+	const text = generateLlmsFull({
+		items: articles,
+		siteName: config.organization.name,
+	})
+	return new Response(text, {
+		headers: {
+			'Content-Type': 'text/plain; charset=utf-8',
+			'X-Robots-Tag': 'noindex',
+		},
+	})
+}

package/src/routes/llms.ts ADDED Viewed

@@ -0,0 +1,15 @@
+import 'virtual:growth-labs/seo/config'
+import type { APIRoute } from 'astro'
+import { getConfig } from '../_internal/state.js'
+import { generateLlmsTxt } from '../utils/llms.js'
+export const prerender = false
+export const GET: APIRoute = async () => {
+	const config = getConfig()
+	const txt = generateLlmsTxt(config)
+	return new Response(txt, {
+		headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+	})
+}