@cogenta/seo 0.1.0

package/dist/llms-txt.js

@@ -0,0 +1,85 @@
+import { condense } from '@cogenta/schema';
+import { indexableResources } from './indexable.js';
+import { canonicalUrl } from './url.js';
+/**
+ * Markdown link escaping.
+ *
+ * A title containing `]` closes the link text early and the rest of the line
+ * becomes prose; a URL containing a space or `)` breaks the target. Titles are
+ * escaped, URLs are wrapped in angle brackets, which is the Markdown-specified
+ * way to carry a URL with awkward characters.
+ */
+function escapeLinkText(value) {
+    return condense(value).replace(/([[\]\\])/gu, '\\$1');
+}
+function renderUrl(url) {
+    return /[()\s]/u.test(url) ? `<${url}>` : url;
+}
+export function renderLlmsTxt(options) {
+    const lines = [`# ${escapeLinkText(options.title ?? options.site.name)}`];
+    const summary = options.summary ?? options.site.description;
+    if (summary !== undefined && summary.length > 0) {
+        lines.push('', `> ${condense(summary)}`);
+    }
+    for (const paragraph of options.details ?? []) {
+        lines.push('', condense(paragraph));
+    }
+    for (const section of options.sections) {
+        if (section.links.length === 0)
+            continue;
+        lines.push('', `## ${escapeLinkText(section.title)}`, '');
+        for (const link of section.links) {
+            const note = link.note === undefined ? '' : `: ${condense(link.note)}`;
+            lines.push(`- [${escapeLinkText(link.title)}](${renderUrl(link.url)})${note}`);
+        }
+    }
+    return `${lines.join('\n')}\n`;
+}
+const TITLE_FIELDS = ['title', 'name', 'label', 'heading'];
+const NOTE_FIELDS = ['excerpt', 'description', 'summary', 'subtitle'];
+function pick(resource, candidates) {
+    for (const candidate of candidates) {
+        if (resource.collection.fields[candidate] === undefined)
+            continue;
+        const value = resource.entry.values[candidate];
+        if (typeof value === 'string' && value.trim().length > 0)
+            return condense(value);
+    }
+    return undefined;
+}
+/**
+ * One section per collection, entries newest first.
+ *
+ * Grouping by collection rather than by URL depth is what makes the file useful:
+ * "Articles", "Guides", "Authors" tells a model what kind of thing each link is
+ * before it fetches any of them.
+ */
+export function llmsTxtSectionsFor(site, resources, options = {}) {
+    const limit = options.limitPerSection ?? 100;
+    const byCollection = new Map();
+    for (const resource of indexableResources(site, resources, options)) {
+        const url = canonicalUrl(site, resource);
+        if (url === null)
+            continue;
+        const name = resource.collection.name;
+        let section = byCollection.get(name);
+        if (section === undefined) {
+            section = {
+                title: options.sectionTitle?.(name) ?? resource.collection.labels.plural,
+                links: [],
+            };
+            byCollection.set(name, section);
+        }
+        const note = pick(resource, NOTE_FIELDS);
+        section.links.push({
+            title: pick(resource, TITLE_FIELDS) ?? url,
+            url,
+            ...(note === undefined ? {} : { note }),
+        });
+    }
+    return [...byCollection.values()].map((section) => ({
+        title: section.title,
+        links: section.links.slice(0, limit),
+    }));
+}
+//# sourceMappingURL=llms-txt.js.map

package/dist/llms-txt.js.map

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

package/dist/metadata.d.ts

@@ -0,0 +1,61 @@
+import type { HreflangAlternate } from './hreflang.js';
+import type { IndexableOptions } from './indexable.js';
+import type { SeoImage, SeoResolvers, SeoResource, SeoSite } from './types.js';
+/**
+ * The head of a page: canonical, `hreflang`, Open Graph, Twitter Card, robots.
+ *
+ * Tags are returned as data and rendered separately. The renderer is one
+ * function of eight lines, so returning strings would have been shorter — but a
+ * theme needs to *inspect* the tags to merge its own, an Astro integration
+ * wants them as component props, and a test wants to assert on a tag rather
+ * than on a substring of HTML. A string is the one shape none of the three can
+ * use.
+ */
+export type MetaTag = {
+    readonly kind: 'meta';
+    readonly name: string;
+    readonly content: string;
+} | {
+    readonly kind: 'property';
+    readonly property: string;
+    readonly content: string;
+} | {
+    readonly kind: 'link';
+    readonly rel: string;
+    readonly href: string;
+    readonly hreflang?: string;
+} | {
+    readonly kind: 'title';
+    readonly text: string;
+};
+export interface MetadataOptions extends IndexableOptions {
+    readonly resolvers?: SeoResolvers;
+    /** The family's alternates, from `buildHreflangMap`. */
+    readonly alternates?: readonly HreflangAlternate[];
+    /** Overrides the derived title. */
+    readonly title?: string;
+    readonly description?: string;
+    /** Overrides the derived social image. */
+    readonly image?: SeoImage;
+    /**
+     * Forces `noindex` even on a published entry — a tag archive page, a search
+     * result page, a paginated tail.
+     */
+    readonly noindex?: boolean;
+    readonly types?: Readonly<Record<string, string>>;
+}
+export declare function buildMetaTags(site: SeoSite, resource: SeoResource, options?: MetadataOptions): readonly MetaTag[];
+/**
+ * Escaping for an HTML attribute value.
+ *
+ * Separate from the XML escaper because HTML has no `&apos;` — it is an XML
+ * entity that HTML 4 parsers do not know — so the numeric reference is used
+ * instead. The two look interchangeable and are not; sharing one function here
+ * is how a feed ends up with `&#39;` and a page with `&apos;`, one of which is
+ * wrong in each context.
+ */
+export declare function escapeHtmlAttribute(value: string): string;
+export declare function escapeHtmlText(value: string): string;
+/** The tags as HTML, one per line, ready to drop into `<head>`. */
+export declare function renderMetaTags(tags: readonly MetaTag[]): string;
+//# sourceMappingURL=metadata.d.ts.map

package/dist/metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AACtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAA;AAGtD,OAAO,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAG9E;;;;;;;;;GASG;AAEH,MAAM,MAAM,OAAO,GACf;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC1E;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAClF;IACE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAC3B,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAA;AAErD,MAAM,WAAW,eAAgB,SAAQ,gBAAgB;IACvD,QAAQ,CAAC,SAAS,CAAC,EAAE,YAAY,CAAA;IACjC,wDAAwD;IACxD,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAA;IAClD,mCAAmC;IACnC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,0CAA0C;IAC1C,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAA;IACzB;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CAClD;AAwDD,wBAAgB,aAAa,CAC3B,IAAI,EAAE,OAAO,EACb,QAAQ,EAAE,WAAW,EACrB,OAAO,GAAE,eAAoB,GAC5B,SAAS,OAAO,EAAE,CA6GpB;AAUD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpD;AAkBD,mEAAmE;AACnE,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,OAAO,EAAE,GAAG,MAAM,CAE/D"}

package/dist/metadata.js

@@ -0,0 +1,200 @@
+import { condense } from '@cogenta/schema';
+import { isPublished } from './indexable.js';
+import { schemaTypeFor } from './json-ld.js';
+import { canonicalUrl } from './url.js';
+const TITLE_FIELDS = ['title', 'name', 'label', 'heading'];
+const DESCRIPTION_FIELDS = ['excerpt', 'description', 'summary', 'subtitle', 'teaser'];
+/** Google truncates a description near 160 characters; longer is wasted bytes. */
+const MAX_DESCRIPTION = 160;
+function pickString(resource, candidates) {
+    for (const candidate of candidates) {
+        if (resource.collection.fields[candidate] === undefined)
+            continue;
+        const value = resource.entry.values[candidate];
+        if (typeof value === 'string' && value.trim().length > 0)
+            return condense(value);
+    }
+    return undefined;
+}
+function truncate(value, limit) {
+    if (value.length <= limit)
+        return value;
+    const cut = value.slice(0, limit - 1);
+    const lastSpace = cut.lastIndexOf(' ');
+    return `${(lastSpace > limit / 2 ? cut.slice(0, lastSpace) : cut).trimEnd()}…`;
+}
+function firstImage(resource, resolvers) {
+    const resolve = resolvers?.media;
+    if (resolve === undefined)
+        return undefined;
+    for (const [name, field] of Object.entries(resource.collection.fields)) {
+        if (field.kind !== 'media')
+            continue;
+        const value = resource.entry.values[name];
+        const id = Array.isArray(value) ? value[0] : value;
+        if (typeof id !== 'string' || id.length === 0)
+            continue;
+        const image = resolve(id);
+        if (image !== null)
+            return image;
+    }
+    return undefined;
+}
+/**
+ * Open Graph's `og:type` vocabulary is not schema.org's, and it is tiny:
+ * `article`, `profile`, `website`, `book`, plus the music and video families.
+ * Mapping through it rather than passing the schema.org type keeps Facebook and
+ * LinkedIn from silently falling back to `website` on every page.
+ */
+function openGraphType(schemaType) {
+    if (schemaType.endsWith('Article') || schemaType === 'BlogPosting')
+        return 'article';
+    if (schemaType === 'Person')
+        return 'profile';
+    if (schemaType === 'Book')
+        return 'book';
+    if (schemaType === 'VideoObject')
+        return 'video.other';
+    return 'website';
+}
+export function buildMetaTags(site, resource, options = {}) {
+    const tags = [];
+    const url = canonicalUrl(site, resource);
+    const schemaType = schemaTypeFor(resource.collection, {
+        ...(options.types === undefined ? {} : { types: options.types }),
+    });
+    const title = options.title ?? pickString(resource, TITLE_FIELDS) ?? site.name;
+    const rawDescription = options.description ?? pickString(resource, DESCRIPTION_FIELDS) ?? site.description;
+    const description = rawDescription === undefined ? undefined : truncate(rawDescription, MAX_DESCRIPTION);
+    const image = options.image ?? firstImage(resource, options.resolvers);
+    tags.push({ kind: 'title', text: title });
+    // The robots tag comes first among the meta tags because it is the one that
+    // matters when it is wrong. An unpublished entry rendered through a preview
+    // token must carry `noindex`: preview URLs leak — they get pasted into chats,
+    // into tickets, and eventually into a crawler's referrer log.
+    const indexable = options.noindex !== true && isPublished(resource.entry, options) && url !== null;
+    if (!indexable) {
+        tags.push({ kind: 'meta', name: 'robots', content: 'noindex, nofollow' });
+    }
+    if (description !== undefined) {
+        tags.push({ kind: 'meta', name: 'description', content: description });
+    }
+    if (url !== null && indexable) {
+        tags.push({ kind: 'link', rel: 'canonical', href: url });
+    }
+    for (const alternate of options.alternates ?? []) {
+        tags.push({
+            kind: 'link',
+            rel: 'alternate',
+            href: alternate.href,
+            hreflang: alternate.hreflang,
+        });
+    }
+    // Open Graph.
+    tags.push({ kind: 'property', property: 'og:type', content: openGraphType(schemaType) });
+    tags.push({ kind: 'property', property: 'og:title', content: title });
+    tags.push({ kind: 'property', property: 'og:site_name', content: site.name });
+    tags.push({ kind: 'property', property: 'og:locale', content: resource.entry.locale });
+    if (url !== null)
+        tags.push({ kind: 'property', property: 'og:url', content: url });
+    if (description !== undefined) {
+        tags.push({ kind: 'property', property: 'og:description', content: description });
+    }
+    if (image !== undefined) {
+        tags.push({ kind: 'property', property: 'og:image', content: image.url });
+        if (image.width !== undefined) {
+            tags.push({ kind: 'property', property: 'og:image:width', content: String(image.width) });
+        }
+        if (image.height !== undefined) {
+            tags.push({ kind: 'property', property: 'og:image:height', content: String(image.height) });
+        }
+        if (image.alt !== undefined) {
+            tags.push({ kind: 'property', property: 'og:image:alt', content: image.alt });
+        }
+    }
+    // `og:locale:alternate` takes the *other* languages only — listing the page's
+    // own locale there makes Facebook drop the whole set.
+    for (const alternate of options.alternates ?? []) {
+        if (alternate.hreflang === 'x-default')
+            continue;
+        if (alternate.hreflang === resource.entry.locale)
+            continue;
+        tags.push({ kind: 'property', property: 'og:locale:alternate', content: alternate.hreflang });
+    }
+    if (openGraphType(schemaType) === 'article') {
+        if (resource.entry.publishedAt !== null) {
+            tags.push({
+                kind: 'property',
+                property: 'article:published_time',
+                content: resource.entry.publishedAt,
+            });
+        }
+        tags.push({
+            kind: 'property',
+            property: 'article:modified_time',
+            content: resource.entry.updatedAt,
+        });
+    }
+    // Twitter Card. `summary_large_image` only when there is an image: the card
+    // type is a promise, and an unfulfilled one renders as a broken frame.
+    tags.push({
+        kind: 'meta',
+        name: 'twitter:card',
+        content: image === undefined ? 'summary' : 'summary_large_image',
+    });
+    if (site.twitterSite !== undefined) {
+        tags.push({ kind: 'meta', name: 'twitter:site', content: site.twitterSite });
+    }
+    tags.push({ kind: 'meta', name: 'twitter:title', content: title });
+    if (description !== undefined) {
+        tags.push({ kind: 'meta', name: 'twitter:description', content: description });
+    }
+    if (image !== undefined) {
+        tags.push({ kind: 'meta', name: 'twitter:image', content: image.url });
+        if (image.alt !== undefined) {
+            tags.push({ kind: 'meta', name: 'twitter:image:alt', content: image.alt });
+        }
+    }
+    return tags;
+}
+const HTML_ATTRIBUTE_ESCAPES = {
+    '&': '&amp;',
+    '<': '&lt;',
+    '>': '&gt;',
+    '"': '&quot;',
+    "'": '&#39;',
+};
+/**
+ * Escaping for an HTML attribute value.
+ *
+ * Separate from the XML escaper because HTML has no `&apos;` — it is an XML
+ * entity that HTML 4 parsers do not know — so the numeric reference is used
+ * instead. The two look interchangeable and are not; sharing one function here
+ * is how a feed ends up with `&#39;` and a page with `&apos;`, one of which is
+ * wrong in each context.
+ */
+export function escapeHtmlAttribute(value) {
+    return value.replace(/[&<>"']/gu, (char) => HTML_ATTRIBUTE_ESCAPES[char] ?? char);
+}
+export function escapeHtmlText(value) {
+    return value.replace(/[&<>]/gu, (char) => HTML_ATTRIBUTE_ESCAPES[char] ?? char);
+}
+function renderMetaTag(tag) {
+    switch (tag.kind) {
+        case 'title':
+            return `<title>${escapeHtmlText(tag.text)}</title>`;
+        case 'meta':
+            return `<meta name="${escapeHtmlAttribute(tag.name)}" content="${escapeHtmlAttribute(tag.content)}" />`;
+        case 'property':
+            return `<meta property="${escapeHtmlAttribute(tag.property)}" content="${escapeHtmlAttribute(tag.content)}" />`;
+        case 'link': {
+            const hreflang = tag.hreflang === undefined ? '' : ` hreflang="${escapeHtmlAttribute(tag.hreflang)}"`;
+            return `<link rel="${escapeHtmlAttribute(tag.rel)}"${hreflang} href="${escapeHtmlAttribute(tag.href)}" />`;
+        }
+    }
+}
+/** The tags as HTML, one per line, ready to drop into `<head>`. */
+export function renderMetaTags(tags) {
+    return tags.map(renderMetaTag).join('\n');
+}
+//# sourceMappingURL=metadata.js.map

package/dist/metadata.js.map

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

package/dist/robots.d.ts

@@ -0,0 +1,35 @@
+import type { SeoSite } from './types.js';
+/**
+ * `robots.txt`.
+ *
+ * The format has no escaping whatsoever: a directive ends at the newline, full
+ * stop. That makes a value containing a newline an *injection* — a path built
+ * from a site setting could append `Disallow: /` and de-index the whole site
+ * with no error anywhere. There is nothing to escape it with, so the only
+ * correct handling is refusal, which is what `assertSingleLine` does.
+ */
+export interface RobotsGroup {
+    /** One or more user agents this group applies to. */
+    readonly userAgent: string | readonly string[];
+    readonly allow?: readonly string[];
+    readonly disallow?: readonly string[];
+    /** Seconds. Ignored by Google, honoured by Bing and Yandex. */
+    readonly crawlDelay?: number;
+}
+export interface RobotsOptions {
+    readonly site: SeoSite;
+    /** Defaults to a single group allowing everything. */
+    readonly groups?: readonly RobotsGroup[];
+    /** Site-relative sitemap paths. Emitted as absolute URLs, as the spec requires. */
+    readonly sitemaps?: readonly string[];
+    /**
+     * Blocks every crawler, whatever `groups` says.
+     *
+     * For staging and preview hosts. It is a separate flag rather than a
+     * convention so that "is this environment indexable" is one boolean somebody
+     * can find, instead of a `Disallow` buried in a config file.
+     */
+    readonly allowIndexing?: boolean;
+}
+export declare function renderRobotsTxt(options: RobotsOptions): string;
+//# sourceMappingURL=robots.d.ts.map

package/dist/robots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"robots.d.ts","sourceRoot":"","sources":["../src/robots.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAGzC;;;;;;;;GAQG;AAEH,MAAM,WAAW,WAAW;IAC1B,qDAAqD;IACrD,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAA;IAC9C,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAClC,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACrC,+DAA+D;IAC/D,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAC7B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,sDAAsD;IACtD,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,WAAW,EAAE,CAAA;IACxC,mFAAmF;IACnF,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACrC;;;;;;OAMG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAA;CACjC;AAYD,wBAAgB,eAAe,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CAoC9D"}

package/dist/robots.js

@@ -0,0 +1,50 @@
+import { CogentaError } from '@cogenta/core';
+import { absoluteUrl } from './url.js';
+function assertSingleLine(value, what) {
+    if (!/[\n\r]/u.test(value))
+        return value;
+    throw new CogentaError({
+        code: 'CONFIG_INVALID',
+        message: `A robots.txt ${what} may not contain a line break.`,
+        hint: 'robots.txt has no escaping: a line break would be read as a new directive. Fix the value at its source.',
+        details: { what },
+    });
+}
+export function renderRobotsTxt(options) {
+    const lines = [];
+    if (options.allowIndexing === false) {
+        lines.push('User-agent: *', 'Disallow: /');
+    }
+    else {
+        const groups = options.groups ?? [{ userAgent: '*', allow: ['/'] }];
+        for (const group of groups) {
+            const agents = typeof group.userAgent === 'string' ? [group.userAgent] : group.userAgent;
+            for (const agent of agents) {
+                lines.push(`User-agent: ${assertSingleLine(agent, 'user agent')}`);
+            }
+            // Allow before Disallow: both Google and Bing resolve a conflict by the
+            // most specific rule, but a human reading the file resolves it by order.
+            for (const path of group.allow ?? []) {
+                lines.push(`Allow: ${assertSingleLine(path, 'path')}`);
+            }
+            for (const path of group.disallow ?? []) {
+                lines.push(`Disallow: ${assertSingleLine(path, 'path')}`);
+            }
+            if (group.crawlDelay !== undefined)
+                lines.push(`Crawl-delay: ${group.crawlDelay}`);
+            lines.push('');
+        }
+    }
+    // Sitemap lines are host-level, not group-level, so they go last and outside
+    // any group. Put inside one, they are ignored by half the crawlers.
+    const sitemaps = options.sitemaps ?? ['/sitemap.xml'];
+    if (sitemaps.length > 0) {
+        if (lines.at(-1) !== '')
+            lines.push('');
+        for (const path of sitemaps) {
+            lines.push(`Sitemap: ${assertSingleLine(absoluteUrl(options.site, path), 'sitemap URL')}`);
+        }
+    }
+    return `${lines.join('\n').trimEnd()}\n`;
+}
+//# sourceMappingURL=robots.js.map

package/dist/robots.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"robots.js","sourceRoot":"","sources":["../src/robots.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAE5C,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAqCtC,SAAS,gBAAgB,CAAC,KAAa,EAAE,IAAY;IACnD,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAA;IACxC,MAAM,IAAI,YAAY,CAAC;QACrB,IAAI,EAAE,gBAAgB;QACtB,OAAO,EAAE,gBAAgB,IAAI,gCAAgC;QAC7D,IAAI,EAAE,yGAAyG;QAC/G,OAAO,EAAE,EAAE,IAAI,EAAE;KAClB,CAAC,CAAA;AACJ,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,OAAsB;IACpD,MAAM,KAAK,GAAa,EAAE,CAAA;IAE1B,IAAI,OAAO,CAAC,aAAa,KAAK,KAAK,EAAE,CAAC;QACpC,KAAK,CAAC,IAAI,CAAC,eAAe,EAAE,aAAa,CAAC,CAAA;IAC5C,CAAC;SAAM,CAAC;QACN,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,EAAE,SAAS,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;QACnE,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,MAAM,MAAM,GAAG,OAAO,KAAK,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,SAAS,CAAA;YACxF,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;gBAC3B,KAAK,CAAC,IAAI,CAAC,eAAe,gBAAgB,CAAC,KAAK,EAAE,YAAY,CAAC,EAAE,CAAC,CAAA;YACpE,CAAC;YACD,wEAAwE;YACxE,yEAAyE;YACzE,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,IAAI,EAAE,EAAE,CAAC;gBACrC,KAAK,CAAC,IAAI,CAAC,UAAU,gBAAgB,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC,CAAA;YACxD,CAAC;YACD,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,QAAQ,IAAI,EAAE,EAAE,CAAC;gBACxC,KAAK,CAAC,IAAI,CAAC,aAAa,gBAAgB,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC,CAAA;YAC3D,CAAC;YACD,IAAI,KAAK,CAAC,UAAU,KAAK,SAAS;gBAAE,KAAK,CAAC,IAAI,CAAC,gBAAgB,KAAK,CAAC,UAAU,EAAE,CAAC,CAAA;YAClF,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;QAChB,CAAC;IACH,CAAC;IAED,6EAA6E;IAC7E,oEAAoE;IACpE,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,CAAC,cAAc,CAAC,CAAA;IACrD,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,IAAI,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,EAAE;YAAE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;QACvC,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;YAC5B,KAAK,CAAC,IAAI,CAAC,YAAY,gBAAgB,CAAC,WAAW,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,aAAa,CAAC,EAAE,CAAC,CAAA;QAC5F,CAAC;IACH,CAAC;IAED,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,IAAI,CAAA;AAC1C,CAAC"}

package/dist/sitemap.d.ts

@@ -0,0 +1,65 @@
+import type { HreflangAlternate } from './hreflang.js';
+import { type IndexableOptions } from './indexable.js';
+import type { SeoResource, SeoSite } from './types.js';
+/**
+ * `sitemap.xml`, split and indexed when it has to be.
+ *
+ * The two limits are the protocol's, not a preference: sitemaps.org caps a
+ * single file at **50 000 URLs and 50 MB uncompressed**, and a file that
+ * exceeds either is rejected whole. Both are enforced, because a site can hit
+ * the byte limit well before the URL limit once `xhtml:link` alternates are
+ * included — twelve languages multiply the size of every entry by roughly
+ * thirteen while the URL count stays put.
+ */
+/** sitemaps.org: 50 000 URLs per file, and the same cap on entries in an index. */
+export declare const SITEMAP_MAX_URLS = 50000;
+/** sitemaps.org: 50 MB uncompressed, counted as 50 × 2²⁰ bytes. */
+export declare const SITEMAP_MAX_BYTES = 52428800;
+export type ChangeFrequency = 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
+export interface SitemapUrl {
+    readonly loc: string;
+    /** W3C datetime. An invalid one makes a crawler ignore the field, not the file. */
+    readonly lastmod?: string;
+    readonly changefreq?: ChangeFrequency;
+    /** 0.0 to 1.0. Rounded to one decimal on output. */
+    readonly priority?: number;
+    readonly alternates?: readonly HreflangAlternate[];
+}
+/** One file to write, with the site-relative path it must be served at. */
+export interface SitemapFile {
+    readonly path: string;
+    readonly contents: string;
+    /** True for the index that lists the others. Exactly one when there is a split. */
+    readonly isIndex: boolean;
+    readonly urlCount: number;
+}
+export interface SitemapOptions extends IndexableOptions {
+    readonly maxUrls?: number;
+    readonly maxBytes?: number;
+    /** How many files an index may list. The protocol limit unless a crawler says otherwise. */
+    readonly maxIndexEntries?: number;
+    /** Path of the single file, and of the index once there is a split. */
+    readonly indexPath?: string;
+    /** Path of chunk `n`, one-based. */
+    readonly chunkPath?: (index: number) => string;
+    /** `lastmod` of the index itself. Defaults to the newest child `lastmod`. */
+    readonly lastmod?: string;
+}
+/**
+ * The files to write for a set of URLs.
+ *
+ * One file below the limits, an index plus N chunks above them. The caller
+ * writes what it gets and never has to know which case it is in — a shape that
+ * makes the split untestable in production is how sites discover at 60 000 URLs
+ * that nobody ever exercised the second branch.
+ */
+export declare function buildSitemap(site: SeoSite, urls: readonly SitemapUrl[], options?: SitemapOptions): readonly SitemapFile[];
+/**
+ * Sitemap URLs for a set of resources: published only, alternates attached.
+ *
+ * `lastmod` is `updatedAt` rather than `publishedAt`: the field answers "has
+ * this changed since you last fetched it", which is what makes a crawler come
+ * back for a corrected article.
+ */
+export declare function sitemapUrlsFor(site: SeoSite, resources: readonly SeoResource[], options?: SitemapOptions): readonly SitemapUrl[];
+//# sourceMappingURL=sitemap.d.ts.map

package/dist/sitemap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sitemap.d.ts","sourceRoot":"","sources":["../src/sitemap.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAEtD,OAAO,EAAE,KAAK,gBAAgB,EAAsB,MAAM,gBAAgB,CAAA;AAC1E,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAItD;;;;;;;;;GASG;AAEH,mFAAmF;AACnF,eAAO,MAAM,gBAAgB,QAAS,CAAA;AAEtC,mEAAmE;AACnE,eAAO,MAAM,iBAAiB,WAAa,CAAA;AAK3C,MAAM,MAAM,eAAe,GACvB,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,OAAO,CAAA;AAEX,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,mFAAmF;IACnF,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,eAAe,CAAA;IACrC,oDAAoD;IACpD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAA;CACnD;AAED,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,mFAAmF;IACnF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAC1B;AAED,MAAM,WAAW,cAAe,SAAQ,gBAAgB;IACtD,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,4FAA4F;IAC5F,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;IACjC,uEAAuE;IACvE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,oCAAoC;IACpC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAA;IAC9C,6EAA6E;IAC7E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAC1B;AAmFD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,OAAO,EACb,IAAI,EAAE,SAAS,UAAU,EAAE,EAC3B,OAAO,GAAE,cAAmB,GAC3B,SAAS,WAAW,EAAE,CAyExB;AAWD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,OAAO,EACb,SAAS,EAAE,SAAS,WAAW,EAAE,EACjC,OAAO,GAAE,cAAmB,GAC3B,SAAS,UAAU,EAAE,CAiBvB"}