@paragraphcms/seo 0.1.0

package/README.md

@@ -0,0 +1,180 @@
+# @paragraphcms/seo
+
+SEO document generators for Paragraph CMS sites.
+
+`@paragraphcms/seo` builds `robots.txt`, `sitemap.xml`, `rss.xml`, and `llms.txt` from a single `@paragraphcms/client` instance plus your route definitions.
+
+## Install
+
+```bash
+npm install @paragraphcms/client @paragraphcms/seo
+```
+
+## Quick Start
+
+```ts
+import { Client } from "@paragraphcms/client";
+import {
+  SEO,
+  localizedContentRoute,
+  localizedRoute,
+} from "@paragraphcms/seo";
+
+const client = new Client({
+  apiKey: process.env.PARAGRAPH_API_KEY!,
+});
+
+const seo = new SEO({
+  client,
+  site: {
+    url: "https://example.com",
+    name: "My site",
+    description: "Latest posts from my site.",
+    defaultLocale: "en",
+  },
+  routes: {
+    home: localizedRoute(),
+    blog: localizedContentRoute("blog", {
+      params: {
+        collection: "blog",
+      },
+    }),
+    features: localizedContentRoute("features", {
+      params: {
+        collection: "features",
+      },
+    }),
+  },
+});
+
+const robots = await seo.robotsTxt();
+const sitemap = await seo.sitemapXml();
+const blogRss = await seo.rssXml({
+  locale: "en",
+  route: "blog",
+});
+const llms = await seo.llmsTxt();
+```
+
+## Default Locale
+
+If you do not pass `site.defaultLocale`, the library resolves it with `client.locales.getDefaultLocale()`.
+
+`site.defaultLocale` always wins when both are available.
+
+`rssXml()` and `llmsTxt()` use the resolved default locale when `locale` is omitted.
+
+## Route Params
+
+Each content route lives directly under `routes`, and you can attach filtering params right there:
+
+```ts
+import {
+  localizedContentRoute,
+  localizedRoute,
+} from "@paragraphcms/seo";
+
+routes: {
+  home: localizedRoute(),
+  blog: localizedContentRoute("blog", {
+    params: {
+      collection: "Blog",
+    },
+  }),
+  features: localizedContentRoute("features", {
+    params: {
+      collection: "Features",
+    },
+  }),
+}
+```
+
+`params` is forwarded to `client.pages.list()` for that route, with `language` and `requiredSlug` filled in automatically by the library.
+
+`published` defaults to `true` for every content route. If you need unpublished entries for a specific route, override it with `published: false`.
+
+The Paragraph client also supports status filters in `pages.list()`, so you can pass `statusId` or `statusType` in `params` when needed.
+
+If you prefer plain objects, content routes also support `basePath` directly:
+
+```ts
+routes: {
+  home: localizedRoute(),
+  blog: {
+    basePath: "blog",
+    params: {
+      collection: "Blog",
+    },
+  },
+}
+```
+
+`basePath: "blog"` expands to `/blog` for the default locale and `/:locale/blog` for other locales. Post URLs are generated automatically by appending the page slug.
+
+## Localized Route Helpers
+
+`localizedRoute()` returns a function, so this:
+
+```ts
+home: localizedRoute(),
+```
+
+is equivalent to writing:
+
+```ts
+home: ({ locale, defaultLocale }) =>
+  locale === defaultLocale ? "/" : `/${locale}`,
+```
+
+Pass a path when you want a localized non-root route:
+
+```ts
+const docsRoute = localizedRoute("docs");
+```
+
+## RSS
+
+If you configure more than one content route, pass `route` to `rssXml()`:
+
+```ts
+const rss = await seo.rssXml({
+  locale: "en",
+  route: "features",
+});
+```
+
+## Artifact Paths
+
+You can override the public paths used inside generated documents:
+
+```ts
+const seo = new SEO({
+  client,
+  site,
+  routes,
+  artifacts: {
+    sitemapPath: "/sitemap.xml",
+    robotsPath: "/robots.txt",
+    llmsPath: "/llms.txt",
+    rssPath: ({ locale, route, collection, defaultLocale }) =>
+      locale === defaultLocale
+        ? `/${route}-${collection?.toLowerCase()}.xml`
+        : `/${locale}/${route}-${collection?.toLowerCase()}.xml`,
+  },
+});
+```
+
+## API
+
+### `new SEO(options)`
+
+Creates an instance with four async methods:
+
+- `robotsTxt()`
+- `sitemapXml()`
+- `rssXml({ locale?, route? })`
+- `llmsTxt({ locale? })`
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { SEO } from "./seo.js";
+export { localizedContentRoute, localizedRoute, } from "./routes.js";
+export type * from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAC/B,OAAO,EACL,qBAAqB,EACrB,cAAc,GACf,MAAM,aAAa,CAAC;AACrB,mBAAmB,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { SEO } from "./seo.js";
+export { localizedContentRoute, localizedRoute, } from "./routes.js";

package/dist/routes.d.ts

@@ -0,0 +1,6 @@
+import type { PageSummary } from "@paragraphcms/client";
+import type { SeoLocalizedContentRouteDefinition, SeoRouteContext } from "./types.js";
+export declare function buildLocalizedPath(context: Pick<SeoRouteContext, "locale" | "defaultLocale">, ...parts: string[]): string;
+export declare function localizedRoute(basePath?: string): (context: Pick<SeoRouteContext, "locale" | "defaultLocale">) => string;
+export declare function localizedContentRoute<TPage extends PageSummary = PageSummary>(basePath: string, options?: Omit<SeoLocalizedContentRouteDefinition<TPage>, "basePath">): SeoLocalizedContentRouteDefinition<TPage>;
+//# sourceMappingURL=routes.d.ts.map

package/dist/routes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../src/routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,KAAK,EACV,kCAAkC,EAClC,eAAe,EAChB,MAAM,YAAY,CAAC;AAyCpB,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,IAAI,CAAC,eAAe,EAAE,QAAQ,GAAG,eAAe,CAAC,EAC1D,GAAG,KAAK,EAAE,MAAM,EAAE,UAQnB;AAED,wBAAgB,cAAc,CAAC,QAAQ,CAAC,EAAE,MAAM,IAc5C,SAAS,IAAI,CAAC,eAAe,EAAE,QAAQ,GAAG,eAAe,CAAC,YAE7D;AAED,wBAAgB,qBAAqB,CACnC,KAAK,SAAS,WAAW,GAAG,WAAW,EAEvC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,IAAI,CACX,kCAAkC,CAAC,KAAK,CAAC,EACzC,UAAU,CACN,GACL,kCAAkC,CAAC,KAAK,CAAC,CAK3C"}

package/dist/routes.js

@@ -0,0 +1,42 @@
+function isAbsoluteUrl(value) {
+    return /^https?:\/\//i.test(value);
+}
+function normalizePathParts(value, fieldName) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new TypeError(`${fieldName} must be a non-empty string.`);
+    }
+    const trimmed = value.trim();
+    if (isAbsoluteUrl(trimmed)) {
+        throw new TypeError(`${fieldName} must be a relative path, not an absolute URL.`);
+    }
+    return trimmed
+        .split("/")
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0);
+}
+function joinLocalizedPath(context, parts) {
+    const localePrefix = context.locale === context.defaultLocale
+        ? []
+        : normalizePathParts(context.locale, "locale");
+    const segments = [...localePrefix, ...parts];
+    return segments.length > 0 ? `/${segments.join("/")}` : "/";
+}
+export function buildLocalizedPath(context, ...parts) {
+    return joinLocalizedPath(context, parts.flatMap((part, index) => normalizePathParts(part, `path part ${index + 1}`)));
+}
+export function localizedRoute(basePath) {
+    if (basePath !== undefined &&
+        typeof basePath !== "string") {
+        throw new TypeError("basePath must be a string.");
+    }
+    const parts = basePath === undefined
+        ? []
+        : normalizePathParts(basePath, "basePath");
+    return (context) => joinLocalizedPath(context, parts);
+}
+export function localizedContentRoute(basePath, options = {}) {
+    return {
+        basePath: normalizePathParts(basePath, "basePath").join("/"),
+        ...options,
+    };
+}

package/dist/seo.d.ts

@@ -0,0 +1,34 @@
+import type { PageSummary } from "@paragraphcms/client";
+import type { CreateSeoOptions, SeoApi } from "./types.js";
+export declare class SEO<TPage extends PageSummary = PageSummary> implements SeoApi<TPage> {
+    private readonly client;
+    private readonly homeRoute;
+    private readonly namedRoutes;
+    private readonly artifacts?;
+    private readonly siteName;
+    private readonly siteUrl;
+    private readonly siteDescription?;
+    private readonly siteDefaultLocale?;
+    constructor(options: CreateSeoOptions<TPage>);
+    private resolveDefaultLocale;
+    private makeResolvedSite;
+    private listLocales;
+    private makeRouteContext;
+    private makeNamedRouteContext;
+    private resolveNamedRouteIndexPath;
+    private resolveNamedRoutePostPath;
+    private resolveRssPath;
+    private resolveSitemapPath;
+    private resolveRobotsPath;
+    private resolveLlmsPath;
+    private listNamedRoutePages;
+    private listLocaleRoutePages;
+    private resolvePageTitle;
+    private resolvePageDescription;
+    private resolveRssRoute;
+    robotsTxt: () => Promise<string>;
+    sitemapXml: () => Promise<string>;
+    rssXml: SeoApi<TPage>["rssXml"];
+    llmsTxt: SeoApi<TPage>["llmsTxt"];
+}
+//# sourceMappingURL=seo.d.ts.map

package/dist/seo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seo.d.ts","sourceRoot":"","sources":["../src/seo.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,KAAK,EACV,gBAAgB,EAEhB,MAAM,EAUP,MAAM,YAAY,CAAC;AAwOpB,qBAAa,GAAG,CAAC,KAAK,SAAS,WAAW,GAAG,WAAW,CACtD,YAAW,MAAM,CAAC,KAAK,CAAC;IAExB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;IAC1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA2B;IACrD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA8B;IAC1D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAqB;IAChD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAS;gBAEhC,OAAO,EAAE,gBAAgB,CAAC,KAAK,CAAC;YA8I9B,oBAAoB;IAWlC,OAAO,CAAC,gBAAgB;YAWV,WAAW;IAczB,OAAO,CAAC,gBAAgB;IAYxB,OAAO,CAAC,qBAAqB;IAY7B,OAAO,CAAC,0BAA0B;IAUlC,OAAO,CAAC,yBAAyB;IAejC,OAAO,CAAC,cAAc;IAoBtB,OAAO,CAAC,kBAAkB;IAO1B,OAAO,CAAC,iBAAiB;IAOzB,OAAO,CAAC,eAAe;YAOT,mBAAmB;YAoBnB,oBAAoB;IASlC,OAAO,CAAC,gBAAgB;IAcxB,OAAO,CAAC,sBAAsB;IAuB9B,OAAO,CAAC,eAAe;IA8BvB,SAAS,wBAWP;IAEF,UAAU,wBAgHR;IAEF,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,CA+F7B;IAEF,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,SAAS,CAAC,CA4E/B;CACH"}

package/dist/seo.js

@@ -0,0 +1,516 @@
+import { buildLocalizedPath, localizedRoute, } from "./routes.js";
+const DEFAULT_SITEMAP_PATH = "/sitemap.xml";
+const DEFAULT_ROBOTS_PATH = "/robots.txt";
+const DEFAULT_LLMS_PATH = "/llms.txt";
+function assertNonEmptyString(value, fieldName) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new TypeError(`${fieldName} must be a non-empty string.`);
+    }
+    return value.trim();
+}
+function normalizeSiteUrl(value) {
+    const trimmed = assertNonEmptyString(value, "site.url");
+    const normalized = trimmed.replace(/\/+$/, "");
+    try {
+        return new URL(normalized).toString().replace(/\/$/, "");
+    }
+    catch {
+        throw new TypeError("site.url must be a valid absolute URL.");
+    }
+}
+function isAbsoluteUrl(value) {
+    return /^https?:\/\//i.test(value);
+}
+function normalizePath(value, fallback) {
+    const candidate = value?.trim() || fallback;
+    if (isAbsoluteUrl(candidate)) {
+        return candidate;
+    }
+    if (candidate === "/") {
+        return candidate;
+    }
+    return candidate.startsWith("/") ? candidate : `/${candidate}`;
+}
+function appendPathSegment(basePath, segment) {
+    if (isAbsoluteUrl(basePath)) {
+        const url = new URL(basePath);
+        url.pathname =
+            url.pathname === "/"
+                ? `/${segment}`
+                : `${url.pathname.replace(/\/+$/, "")}/${segment}`;
+        url.search = "";
+        url.hash = "";
+        return url.toString();
+    }
+    const normalizedBase = normalizePath(basePath, "/");
+    return normalizedBase === "/"
+        ? `/${segment}`
+        : `${normalizedBase.replace(/\/+$/, "")}/${segment}`;
+}
+function toAbsoluteUrl(siteUrl, path) {
+    if (isAbsoluteUrl(path)) {
+        return path;
+    }
+    return new URL(normalizePath(path, "/"), `${siteUrl}/`).toString();
+}
+function escapeXml(value) {
+    return value
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&apos;");
+}
+function toIsoDate(value) {
+    if (!value) {
+        return undefined;
+    }
+    const date = new Date(value);
+    if (Number.isNaN(date.getTime())) {
+        return undefined;
+    }
+    return date.toISOString();
+}
+function toRssDate(value) {
+    if (!value) {
+        return undefined;
+    }
+    const date = new Date(value);
+    if (Number.isNaN(date.getTime())) {
+        return undefined;
+    }
+    return date.toUTCString();
+}
+function dedupeStrings(values) {
+    return Array.from(new Set(values
+        .map((value) => value.trim())
+        .filter((value) => value.length > 0)));
+}
+function getLatestDate(values) {
+    let latest = 0;
+    for (const value of values) {
+        if (!value) {
+            continue;
+        }
+        const timestamp = new Date(value).getTime();
+        if (!Number.isNaN(timestamp) && timestamp > latest) {
+            latest = timestamp;
+        }
+    }
+    return latest > 0 ? new Date(latest).toISOString() : undefined;
+}
+function getSitemapDate(page) {
+    return toIsoDate(page.updatedAt ?? page.publishedAt ?? page.createdAt);
+}
+function getFeedDate(page) {
+    return toRssDate(page.publishedAt ?? page.updatedAt ?? page.createdAt);
+}
+function comparePagesForFeed(left, right) {
+    const leftDate = new Date(left.publishedAt ?? left.updatedAt ?? left.createdAt ?? 0).getTime();
+    const rightDate = new Date(right.publishedAt ?? right.updatedAt ?? right.createdAt ?? 0).getTime();
+    if (leftDate !== rightDate) {
+        return rightDate - leftDate;
+    }
+    return left.title.localeCompare(right.title);
+}
+function compareRoutedPages(left, right) {
+    return comparePagesForFeed(left.page, right.page);
+}
+function resolveRoutePath(value, fieldName) {
+    return normalizePath(assertNonEmptyString(value, fieldName), "/");
+}
+function hasSlug(page) {
+    return typeof page.slug === "string" && page.slug.trim().length > 0;
+}
+function isPlainObject(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value));
+}
+export class SEO {
+    client;
+    homeRoute;
+    namedRoutes;
+    artifacts;
+    siteName;
+    siteUrl;
+    siteDescription;
+    siteDefaultLocale;
+    constructor(options) {
+        if (!options || typeof options !== "object") {
+            throw new TypeError("SEO options are required.");
+        }
+        const { client, routes, artifacts } = options;
+        if (!client || typeof client !== "object") {
+            throw new TypeError("client is required.");
+        }
+        if (!routes || typeof routes !== "object") {
+            throw new TypeError("routes are required.");
+        }
+        if (typeof routes.home !== "function") {
+            throw new TypeError("routes.home must be a function.");
+        }
+        const routeEntries = Object.entries(routes).filter(([name]) => name !== "home");
+        if (routeEntries.length === 0) {
+            throw new TypeError("At least one content route is required.");
+        }
+        const namedRoutes = routeEntries.map(([name, route]) => {
+            const fieldName = `routes.${name}`;
+            if (!isPlainObject(route)) {
+                throw new TypeError(`${fieldName} must be an object.`);
+            }
+            const contentRoute = route;
+            if (contentRoute.params !== undefined &&
+                !isPlainObject(contentRoute.params)) {
+                throw new TypeError(`${fieldName}.params must be an object.`);
+            }
+            const hasBasePath = contentRoute.basePath !== undefined;
+            const hasIndex = typeof contentRoute.index === "function";
+            const hasPost = typeof contentRoute.post === "function";
+            let index;
+            let post;
+            if (hasBasePath) {
+                if (hasIndex || hasPost) {
+                    throw new TypeError(`${fieldName}.basePath cannot be combined with ${fieldName}.index or ${fieldName}.post.`);
+                }
+                const basePath = assertNonEmptyString(contentRoute.basePath, `${fieldName}.basePath`);
+                const localizedIndex = localizedRoute(basePath);
+                index = (context) => localizedIndex(context);
+                post = (context) => buildLocalizedPath(context, basePath, context.slug);
+            }
+            else {
+                if (!hasIndex) {
+                    throw new TypeError(`${fieldName}.index must be a function.`);
+                }
+                if (!hasPost) {
+                    throw new TypeError(`${fieldName}.post must be a function.`);
+                }
+                index = contentRoute.index;
+                post = contentRoute.post;
+            }
+            if (contentRoute.params) {
+                if ("language" in contentRoute.params) {
+                    throw new TypeError(`${fieldName}.params.language is not supported.`);
+                }
+                if ("requiredSlug" in contentRoute.params) {
+                    throw new TypeError(`${fieldName}.params.requiredSlug is not supported.`);
+                }
+                if ("page" in contentRoute.params ||
+                    "limit" in contentRoute.params) {
+                    throw new TypeError(`${fieldName}.params.page and ${fieldName}.params.limit are not supported.`);
+                }
+                if ("collection" in contentRoute.params &&
+                    contentRoute.params.collection !== undefined) {
+                    assertNonEmptyString(contentRoute.params.collection, `${fieldName}.params.collection`);
+                }
+            }
+            return {
+                fieldName,
+                name,
+                params: contentRoute.params,
+                index,
+                post,
+                title: contentRoute.title,
+                description: contentRoute.description,
+            };
+        });
+        this.client = client;
+        this.homeRoute = routes.home;
+        this.namedRoutes = namedRoutes;
+        this.artifacts = artifacts;
+        this.siteName = assertNonEmptyString(options.site?.name, "site.name");
+        this.siteUrl = normalizeSiteUrl(options.site?.url ?? "");
+        this.siteDescription =
+            typeof options.site?.description === "string" &&
+                options.site.description.trim().length > 0
+                ? options.site.description.trim()
+                : undefined;
+        this.siteDefaultLocale = options.site?.defaultLocale?.trim() || undefined;
+    }
+    async resolveDefaultLocale() {
+        if (this.siteDefaultLocale) {
+            return this.siteDefaultLocale;
+        }
+        return assertNonEmptyString(await this.client.locales.getDefaultLocale(), "client.locales.getDefaultLocale() result");
+    }
+    makeResolvedSite(defaultLocale) {
+        return {
+            url: this.siteUrl,
+            name: this.siteName,
+            description: this.siteDescription,
+            defaultLocale,
+        };
+    }
+    async listLocales(defaultLocale, extra = []) {
+        const locales = await this.client.locales.list();
+        const localeCodes = dedupeStrings([
+            ...locales.map((locale) => locale.code),
+            defaultLocale,
+            ...extra,
+        ]);
+        return localeCodes.length > 0 ? localeCodes : [defaultLocale];
+    }
+    makeRouteContext(locale, defaultLocale, site) {
+        return {
+            locale,
+            defaultLocale,
+            site,
+        };
+    }
+    makeNamedRouteContext(locale, defaultLocale, site, routeName) {
+        return {
+            ...this.makeRouteContext(locale, defaultLocale, site),
+            route: routeName,
+        };
+    }
+    resolveNamedRouteIndexPath(route, context) {
+        return resolveRoutePath(route.index(context), `${route.fieldName}.index`);
+    }
+    resolveNamedRoutePostPath(route, page, context) {
+        return resolveRoutePath(route.post({
+            ...context,
+            page,
+            slug: page.slug,
+        }), `${route.fieldName}.post`);
+    }
+    resolveRssPath(context, route) {
+        if (typeof this.artifacts?.rssPath === "function") {
+            return resolveRoutePath(this.artifacts.rssPath(context), "artifacts.rssPath");
+        }
+        return appendPathSegment(this.resolveNamedRouteIndexPath(route, {
+            ...context,
+            route: route.name,
+        }), "rss.xml");
+    }
+    resolveSitemapPath() {
+        return normalizePath(this.artifacts?.sitemapPath, DEFAULT_SITEMAP_PATH);
+    }
+    resolveRobotsPath() {
+        return normalizePath(this.artifacts?.robotsPath, DEFAULT_ROBOTS_PATH);
+    }
+    resolveLlmsPath() {
+        return normalizePath(this.artifacts?.llmsPath, DEFAULT_LLMS_PATH);
+    }
+    async listNamedRoutePages(locale, route) {
+        const { data } = await this.client.pages.list({
+            published: true,
+            ...route.params,
+            language: locale,
+            requiredSlug: true,
+        });
+        return data
+            .filter(hasSlug)
+            .map((page) => ({
+            ...page,
+            slug: page.slug.trim(),
+        }))
+            .sort(comparePagesForFeed);
+    }
+    async listLocaleRoutePages(locale) {
+        return Promise.all(this.namedRoutes.map(async (route) => ({
+            route,
+            pages: await this.listNamedRoutePages(locale, route),
+        })));
+    }
+    resolvePageTitle(page, route) {
+        if (route.title) {
+            return assertNonEmptyString(route.title(page), `${route.fieldName}.title() result`);
+        }
+        return page.metaName?.trim() || page.title;
+    }
+    resolvePageDescription(page, route) {
+        if (route.description) {
+            const customDescription = route.description(page);
+            if (typeof customDescription === "string") {
+                return (customDescription.trim() ||
+                    page.metaDescription?.trim() ||
+                    page.title);
+            }
+            if (customDescription === null) {
+                return page.title;
+            }
+        }
+        return page.metaDescription?.trim() || page.title;
+    }
+    resolveRssRoute(routeName) {
+        if (routeName?.trim()) {
+            const normalizedRouteName = assertNonEmptyString(routeName, "options.route");
+            const route = this.namedRoutes.find((candidate) => candidate.name === normalizedRouteName);
+            if (!route) {
+                throw new TypeError(`No route configured for "${normalizedRouteName}".`);
+            }
+            return route;
+        }
+        if (this.namedRoutes.length === 1) {
+            return this.namedRoutes[0];
+        }
+        throw new TypeError("options.route is required when multiple content routes are configured.");
+    }
+    robotsTxt = async () => {
+        const lines = [
+            "User-agent: *",
+            "Allow: /",
+            `Sitemap: ${toAbsoluteUrl(this.siteUrl, this.resolveSitemapPath())}`,
+        ];
+        return `${lines.join("\n")}\n`;
+    };
+    sitemapXml = async () => {
+        const defaultLocale = await this.resolveDefaultLocale();
+        const site = this.makeResolvedSite(defaultLocale);
+        const locales = await this.listLocales(defaultLocale);
+        const entries = new Map();
+        function addEntry(url, lastModified) {
+            const current = entries.get(url);
+            if (!current) {
+                entries.set(url, { url, lastModified });
+                return;
+            }
+            const resolvedLastModified = getLatestDate([
+                current.lastModified,
+                lastModified,
+            ]);
+            entries.set(url, {
+                url,
+                lastModified: resolvedLastModified,
+            });
+        }
+        await Promise.all(locales.map(async (locale) => {
+            const context = this.makeRouteContext(locale, defaultLocale, site);
+            const routePages = await this.listLocaleRoutePages(locale);
+            const latestLocaleUpdate = getLatestDate(routePages.flatMap(({ pages }) => pages.map((page) => getSitemapDate(page))));
+            addEntry(toAbsoluteUrl(site.url, resolveRoutePath(this.homeRoute(context), "routes.home")), latestLocaleUpdate);
+            for (const { route, pages } of routePages) {
+                const routeContext = this.makeNamedRouteContext(locale, defaultLocale, site, route.name);
+                const latestRouteUpdate = getLatestDate(pages.map((page) => getSitemapDate(page)));
+                addEntry(toAbsoluteUrl(site.url, this.resolveNamedRouteIndexPath(route, routeContext)), latestRouteUpdate);
+                for (const page of pages) {
+                    addEntry(toAbsoluteUrl(site.url, this.resolveNamedRoutePostPath(route, page, routeContext)), getSitemapDate(page));
+                }
+            }
+        }));
+        const body = Array.from(entries.values())
+            .sort((left, right) => left.url.localeCompare(right.url))
+            .map((entry) => [
+            "  <url>",
+            `    <loc>${escapeXml(entry.url)}</loc>`,
+            entry.lastModified
+                ? `    <lastmod>${escapeXml(entry.lastModified)}</lastmod>`
+                : undefined,
+            "  </url>",
+        ]
+            .filter(Boolean)
+            .join("\n"))
+            .join("\n");
+        return [
+            '<?xml version="1.0" encoding="UTF-8"?>',
+            '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">',
+            body,
+            "</urlset>",
+            "",
+        ].join("\n");
+    };
+    rssXml = async (input = {}) => {
+        const defaultLocale = await this.resolveDefaultLocale();
+        const locale = input.locale?.trim() || defaultLocale;
+        const site = this.makeResolvedSite(defaultLocale);
+        const route = this.resolveRssRoute(input.route);
+        const context = this.makeNamedRouteContext(locale, defaultLocale, site, route.name);
+        const collection = typeof route.params?.collection === "string"
+            ? route.params.collection
+            : undefined;
+        const feedPath = this.resolveRssPath({ ...context, collection }, route);
+        const indexUrl = toAbsoluteUrl(site.url, this.resolveNamedRouteIndexPath(route, context));
+        const feedUrl = toAbsoluteUrl(site.url, feedPath);
+        const pages = await this.listNamedRoutePages(locale, route);
+        const title = this.namedRoutes.length === 1
+            ? site.name
+            : `${site.name} - ${route.name}`;
+        const descriptionBase = site.description ?? `RSS feed for ${route.name} on ${site.name}.`;
+        const description = locale === defaultLocale
+            ? descriptionBase
+            : `${descriptionBase} (${locale})`;
+        const lastBuildDate = getLatestDate(pages.map((page) => toIsoDate(page.publishedAt ??
+            page.updatedAt ??
+            page.createdAt)));
+        const items = pages
+            .map((page) => {
+            const url = toAbsoluteUrl(site.url, this.resolveNamedRoutePostPath(route, page, context));
+            const pubDate = getFeedDate(page);
+            return [
+                "    <item>",
+                `      <title>${escapeXml(this.resolvePageTitle(page, route))}</title>`,
+                `      <link>${escapeXml(url)}</link>`,
+                `      <guid>${escapeXml(url)}</guid>`,
+                pubDate
+                    ? `      <pubDate>${escapeXml(pubDate)}</pubDate>`
+                    : undefined,
+                `      <description>${escapeXml(this.resolvePageDescription(page, route))}</description>`,
+                ...page.labels.map((label) => `      <category>${escapeXml(label.name)}</category>`),
+                "    </item>",
+            ]
+                .filter(Boolean)
+                .join("\n");
+        })
+            .join("\n");
+        return [
+            '<?xml version="1.0" encoding="UTF-8"?>',
+            '<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">',
+            "  <channel>",
+            `    <title>${escapeXml(title)}</title>`,
+            `    <link>${escapeXml(indexUrl)}</link>`,
+            `    <description>${escapeXml(description)}</description>`,
+            `    <language>${escapeXml(locale)}</language>`,
+            "    <generator>@paragraphcms/seo</generator>",
+            `    <atom:link href="${escapeXml(feedUrl)}" rel="self" type="application/rss+xml" />`,
+            lastBuildDate
+                ? `    <lastBuildDate>${escapeXml(toRssDate(lastBuildDate) ?? "")}</lastBuildDate>`
+                : undefined,
+            items || undefined,
+            "  </channel>",
+            "</rss>",
+            "",
+        ]
+            .filter(Boolean)
+            .join("\n");
+    };
+    llmsTxt = async (input = {}) => {
+        const defaultLocale = await this.resolveDefaultLocale();
+        const locale = input.locale?.trim() || defaultLocale;
+        const site = this.makeResolvedSite(defaultLocale);
+        const locales = await this.listLocales(defaultLocale, [locale]);
+        const routePages = await this.listLocaleRoutePages(locale);
+        const pages = routePages
+            .flatMap(({ route, pages }) => pages.map((page) => ({ route, page })))
+            .sort(compareRoutedPages);
+        const lines = [
+            `# ${site.name}`,
+            site.description ? `> ${site.description}` : undefined,
+            "",
+            `Canonical: ${site.url}`,
+            `Default locale: ${defaultLocale}`,
+            `Sitemap: ${toAbsoluteUrl(site.url, this.resolveSitemapPath())}`,
+            `Robots: ${toAbsoluteUrl(site.url, this.resolveRobotsPath())}`,
+            `LLMs: ${toAbsoluteUrl(site.url, this.resolveLlmsPath())}`,
+            "",
+            "## Routes",
+            ...locales.flatMap((currentLocale) => this.namedRoutes.map((route) => {
+                const routeContext = this.makeNamedRouteContext(currentLocale, defaultLocale, site, route.name);
+                const collection = typeof route.params?.collection === "string"
+                    ? route.params.collection
+                    : undefined;
+                return `- ${currentLocale} / ${route.name}: ${toAbsoluteUrl(site.url, this.resolveNamedRouteIndexPath(route, routeContext))} (RSS: ${toAbsoluteUrl(site.url, this.resolveRssPath({ ...routeContext, collection }, route))})`;
+            })),
+            "",
+            `## Posts (${locale})`,
+            ...(pages.length > 0
+                ? pages.map(({ route, page }) => {
+                    const routeContext = this.makeNamedRouteContext(locale, defaultLocale, site, route.name);
+                    return `- [${route.name}] ${this.resolvePageTitle(page, route)}: ${toAbsoluteUrl(site.url, this.resolveNamedRoutePostPath(route, page, routeContext))}`;
+                })
+                : ["- No posts found."]),
+        ];
+        return `${lines
+            .filter((line) => line !== undefined)
+            .join("\n")}\n`;
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,102 @@
+import type { ListResponse, Locale, PageListQuery, PageSummary } from "@paragraphcms/client";
+export type SeoPage<TPage extends PageSummary = PageSummary> = TPage & {
+    slug: string;
+};
+export interface SeoClient<TPage extends PageSummary = PageSummary> {
+    locales: {
+        list(): Promise<Locale[]>;
+        getDefaultLocale(): Promise<string>;
+    };
+    pages: {
+        list(query?: PageListQuery): Promise<ListResponse<TPage>>;
+    };
+}
+export interface SeoSiteConfig {
+    url: string;
+    name: string;
+    description?: string;
+    defaultLocale?: string;
+}
+export interface ResolvedSeoSiteConfig {
+    url: string;
+    name: string;
+    description?: string;
+    defaultLocale: string;
+}
+export interface SeoRouteContext {
+    locale: string;
+    defaultLocale: string;
+    site: ResolvedSeoSiteConfig;
+}
+export interface SeoNamedRouteContext extends SeoRouteContext {
+    route: string;
+}
+export interface SeoPostRouteContext<TPage extends PageSummary = PageSummary> extends SeoNamedRouteContext {
+    page: SeoPage<TPage>;
+    slug: string;
+}
+export type SeoRouteParams = Omit<PageListQuery, "language" | "requiredSlug" | "page" | "limit">;
+export interface SeoContentRouteDefinition<TPage extends PageSummary = PageSummary> {
+    /**
+     * Forwarded to `client.pages.list()`.
+     * `published` defaults to `true` unless you override it here.
+     * Supports client filters such as `statusId` and `statusType`.
+     */
+    params?: SeoRouteParams;
+    index: (params: SeoNamedRouteContext) => string;
+    post: (params: SeoPostRouteContext<TPage>) => string;
+    title?: (page: SeoPage<TPage>) => string;
+    description?: (page: SeoPage<TPage>) => string | null | undefined;
+}
+export interface SeoLocalizedContentRouteDefinition<TPage extends PageSummary = PageSummary> {
+    /**
+     * Localized base path for the route, without the locale prefix
+     * and without the trailing post slug.
+     * Example: `"blog"` -> `/blog` and `/pl/blog`.
+     */
+    basePath: string;
+    /**
+     * Forwarded to `client.pages.list()`.
+     * `published` defaults to `true` unless you override it here.
+     * Supports client filters such as `statusId` and `statusType`.
+     */
+    params?: SeoRouteParams;
+    title?: (page: SeoPage<TPage>) => string;
+    description?: (page: SeoPage<TPage>) => string | null | undefined;
+}
+export type SeoNamedRouteDefinition<TPage extends PageSummary = PageSummary> = SeoContentRouteDefinition<TPage> | SeoLocalizedContentRouteDefinition<TPage>;
+export type SeoRouteEntry<TPage extends PageSummary = PageSummary> = ((params: SeoRouteContext) => string) | SeoNamedRouteDefinition<TPage>;
+export interface SeoRoutes<TPage extends PageSummary = PageSummary> {
+    home: (params: SeoRouteContext) => string;
+    [routeName: string]: SeoRouteEntry<TPage>;
+}
+export interface SeoArtifactPathContext extends SeoRouteContext {
+    route?: string;
+    collection?: string;
+}
+export interface SeoArtifactsConfig {
+    sitemapPath?: string;
+    robotsPath?: string;
+    llmsPath?: string;
+    rssPath?: (params: SeoArtifactPathContext) => string;
+}
+export interface CreateSeoOptions<TPage extends PageSummary = PageSummary> {
+    client: SeoClient<TPage>;
+    site: SeoSiteConfig;
+    routes: SeoRoutes<TPage>;
+    artifacts?: SeoArtifactsConfig;
+}
+export interface SeoRssXmlOptions {
+    locale?: string;
+    route?: string;
+}
+export interface SeoLlmsTxtOptions {
+    locale?: string;
+}
+export interface SeoApi<TPage extends PageSummary = PageSummary> {
+    robotsTxt(): Promise<string>;
+    sitemapXml(): Promise<string>;
+    rssXml(options?: SeoRssXmlOptions): Promise<string>;
+    llmsTxt(options?: SeoLlmsTxtOptions): Promise<string>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@paragraphcms/seo",
+  "version": "0.1.0",
+  "description": "SEO document generators for Paragraph CMS sites.",
+  "license": "MIT",
+  "author": "Paragraph CMS",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run check && npm run build",
+    "test": "npm run build && node --test test/*.test.mjs"
+  },
+  "keywords": [
+    "paragraphcms",
+    "seo",
+    "sitemap",
+    "rss",
+    "robots"
+  ],
+  "peerDependencies": {
+    "@paragraphcms/client": "^2.4.0"
+  },
+  "devDependencies": {
+    "@paragraphcms/client": "^2.4.0",
+    "typescript": "^5.9.3"
+  }
+}