@cogenta/seo 0.1.0

package/dist/indexnow.d.ts

@@ -0,0 +1,47 @@
+/** IndexNow accepts at most 10 000 URLs in one submission. */
+export declare const INDEXNOW_MAX_URLS = 10000;
+export type IndexNowFetch = (input: string, init: {
+    readonly method: string;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body: string;
+    readonly signal: AbortSignal;
+}) => Promise<{
+    readonly ok: boolean;
+    readonly status: number;
+}>;
+export interface IndexNowOptions {
+    /** The host the URLs belong to: `example.com`. */
+    readonly host: string;
+    readonly key: string;
+    /**
+     * Where the key file is served, when it is not `/<key>.txt`.
+     *
+     * Needed by sites that cannot serve a file at the root — the endpoint fetches
+     * it to prove the submitter controls the host.
+     */
+    readonly keyLocation?: string;
+    readonly urls: readonly string[];
+    readonly endpoint?: string;
+    readonly timeoutMs?: number;
+    readonly fetch?: IndexNowFetch;
+}
+export type IndexNowResult = {
+    readonly outcome: 'submitted';
+    readonly status: number;
+    readonly urlCount: number;
+} | {
+    readonly outcome: 'skipped';
+    readonly reason: 'no-urls' | 'no-fetch';
+} | {
+    readonly outcome: 'failed';
+    readonly reason: 'http' | 'network' | 'timeout';
+    readonly status?: number;
+    readonly message: string;
+};
+/** The file the site must serve so the endpoint can verify ownership. */
+export declare function indexNowKeyFile(key: string): {
+    readonly path: string;
+    readonly contents: string;
+};
+export declare function pingIndexNow(options: IndexNowOptions): Promise<IndexNowResult>;
+//# sourceMappingURL=indexnow.d.ts.map

package/dist/indexnow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexnow.d.ts","sourceRoot":"","sources":["../src/indexnow.ts"],"names":[],"mappings":"AAwBA,8DAA8D;AAC9D,eAAO,MAAM,iBAAiB,QAAS,CAAA;AAKvC,MAAM,MAAM,aAAa,GAAG,CAC1B,KAAK,EAAE,MAAM,EACb,IAAI,EAAE;IACJ,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;CAC7B,KACE,OAAO,CAAC;IAAE,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAA;AAE/D,MAAM,WAAW,eAAe;IAC9B,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;IAChC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAA;CAC/B;AAED,MAAM,MAAM,cAAc,GACtB;IAAE,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACrF;IAAE,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,UAAU,CAAA;CAAE,GACxE;IACE,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAA;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAAA;IAC/C,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB,CAAA;AAEL,yEAAyE;AACzE,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAGjG;AAmDD,wBAAsB,YAAY,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAkDpF"}

package/dist/indexnow.js

@@ -0,0 +1,136 @@
+import { CogentaError } from '@cogenta/core';
+/**
+ * IndexNow — telling Bing, Yandex and Seznam that a URL changed.
+ *
+ * One POST, no authentication beyond a key file the site serves itself. It is
+ * the cheapest indexing win there is, and it is also the one piece of this
+ * package that talks to the network, which shapes the design:
+ *
+ * **A failed ping is not an exception.** Publishing an article must not fail
+ * because a third-party endpoint is down, rate-limiting, or slow. So a network
+ * error, a timeout and an HTTP 4xx all come back as a result object the caller
+ * can log and move on from. `CogentaError` is reserved for what is genuinely
+ * the caller's fault and would never succeed on a retry: a malformed key, a URL
+ * on the wrong host, an oversized batch.
+ *
+ * `fetch` is injected so the tests exercise every branch — including the
+ * timeout — without a socket. Rule R1 in miniature: the feature degrades to a
+ * no-op when the network is absent.
+ */
+/** IndexNow: a key is 8 to 128 hexadecimal characters. */
+const KEY_PATTERN = /^[a-fA-F0-9]{8,128}$/;
+/** IndexNow accepts at most 10 000 URLs in one submission. */
+export const INDEXNOW_MAX_URLS = 10_000;
+const DEFAULT_ENDPOINT = 'https://api.indexnow.org/indexnow';
+const DEFAULT_TIMEOUT_MS = 10_000;
+/** The file the site must serve so the endpoint can verify ownership. */
+export function indexNowKeyFile(key) {
+    assertKey(key);
+    return { path: `/${key}.txt`, contents: `${key}\n` };
+}
+function assertKey(key) {
+    if (KEY_PATTERN.test(key))
+        return;
+    throw new CogentaError({
+        code: 'CONFIG_INVALID',
+        message: 'The IndexNow key is not 8 to 128 hexadecimal characters.',
+        hint: 'Generate one with crypto.randomUUID().replaceAll("-", ""), then serve it at /<key>.txt.',
+        details: { keyLength: key.length },
+    });
+}
+/**
+ * Every URL must be on the submitted host — the endpoint rejects the whole
+ * batch otherwise, so catching it here turns a silent 422 into an error naming
+ * the offending URL.
+ */
+function assertUrls(host, urls) {
+    if (urls.length > INDEXNOW_MAX_URLS) {
+        throw new CogentaError({
+            code: 'CONFIG_INVALID',
+            message: `IndexNow accepts ${INDEXNOW_MAX_URLS} URLs per submission, not ${urls.length}.`,
+            hint: 'Submit in batches. There is no benefit to submitting a whole site at once.',
+            details: { urlCount: urls.length, limit: INDEXNOW_MAX_URLS },
+        });
+    }
+    for (const url of urls) {
+        let parsed;
+        try {
+            parsed = new URL(url);
+        }
+        catch {
+            throw new CogentaError({
+                code: 'CONFIG_INVALID',
+                message: `"${url}" is not an absolute URL.`,
+                hint: 'IndexNow takes absolute URLs only, protocol included.',
+                details: { url },
+            });
+        }
+        if (parsed.host !== host) {
+            throw new CogentaError({
+                code: 'CONFIG_INVALID',
+                message: `"${url}" is not on the submitted host "${host}".`,
+                hint: 'One submission covers one host. Group the URLs by host and ping once per group.',
+                details: { url, host, urlHost: parsed.host },
+            });
+        }
+    }
+}
+export async function pingIndexNow(options) {
+    assertKey(options.key);
+    assertUrls(options.host, options.urls);
+    if (options.urls.length === 0)
+        return { outcome: 'skipped', reason: 'no-urls' };
+    const send = options.fetch ?? globalFetch();
+    // A build target without `fetch` is a supported target, not an error: the
+    // site simply does not ping (rule R1).
+    if (send === null)
+        return { outcome: 'skipped', reason: 'no-fetch' };
+    const body = JSON.stringify({
+        host: options.host,
+        key: options.key,
+        ...(options.keyLocation === undefined ? {} : { keyLocation: options.keyLocation }),
+        urlList: options.urls,
+    });
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    try {
+        const response = await send(options.endpoint ?? DEFAULT_ENDPOINT, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json; charset=utf-8' },
+            body,
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            return {
+                outcome: 'failed',
+                reason: 'http',
+                status: response.status,
+                message: `The IndexNow endpoint answered ${response.status}.`,
+            };
+        }
+        return { outcome: 'submitted', status: response.status, urlCount: options.urls.length };
+    }
+    catch (cause) {
+        const aborted = controller.signal.aborted;
+        return {
+            outcome: 'failed',
+            reason: aborted ? 'timeout' : 'network',
+            message: aborted
+                ? `The IndexNow endpoint did not answer within ${options.timeoutMs ?? DEFAULT_TIMEOUT_MS}ms.`
+                : messageOf(cause),
+        };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function messageOf(cause) {
+    return cause instanceof Error ? cause.message : 'The IndexNow request failed.';
+}
+function globalFetch() {
+    const candidate = globalThis.fetch;
+    if (typeof candidate !== 'function')
+        return null;
+    return (input, init) => candidate(input, init);
+}
+//# sourceMappingURL=indexnow.js.map

package/dist/indexnow.js.map

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

package/dist/json-ld.d.ts

@@ -0,0 +1,69 @@
+import type { CollectionDefinition } from '@cogenta/schema';
+import type { SeoReference, SeoResolvers, SeoResource, SeoSite } from './types.js';
+/**
+ * JSON-LD **derived from the schema**, never typed by hand (L3 § Socle SEO).
+ *
+ * The spec is explicit: an `article` collection produces a schema.org `Article`
+ * with no intervention. That constraint is what makes structured data survive
+ * — a hand-written JSON-LD block is a second copy of the content that stops
+ * matching the first one within a week, and Google penalises exactly that
+ * divergence.
+ *
+ * So the mapping has two halves, and both are declarative:
+ *
+ * 1. **Collection → `@type`**, from the collection's own name and, failing
+ *    that, from the shape of its fields.
+ * 2. **Field → property**, from the field's `kind` and name.
+ *
+ * Anything the mapping cannot justify is left out. Incomplete structured data
+ * is ignored by a crawler; wrong structured data earns a manual action.
+ */
+/** A JSON-LD value. Closed on purpose: no `any` may enter the graph. */
+export type JsonLdValue = string | number | boolean | null | readonly JsonLdValue[] | {
+    readonly [key: string]: JsonLdValue | undefined;
+};
+export type JsonLdObject = {
+    readonly [key: string]: JsonLdValue | undefined;
+};
+export interface JsonLdOptions {
+    readonly resolvers?: SeoResolvers;
+    /**
+     * Force the schema.org type of a collection: `{ article: 'BlogPosting' }`.
+     *
+     * The escape hatch exists because "is a `recipe` a `Recipe` or a
+     * `HowTo`" is an editorial decision no amount of field inspection settles.
+     */
+    readonly types?: Readonly<Record<string, string>>;
+    /** Emitted as `publisher`. Usually the site's organisation. */
+    readonly publisher?: SeoReference;
+    /** Cuts `articleBody`, which is otherwise the whole article in the page head. */
+    readonly maxBodyLength?: number;
+}
+/**
+ * The schema.org type of a collection.
+ *
+ * Order matters: an explicit override, then the name, then the shape. The
+ * shape rule is deliberately blunt — long text plus a publication date is an
+ * article, and everything else is a `WebPage` — because a subtler heuristic
+ * would be a heuristic nobody can predict from reading the collection.
+ */
+export declare function schemaTypeFor(collection: CollectionDefinition, options?: JsonLdOptions): string;
+/**
+ * The JSON-LD object for one entry.
+ *
+ * `null` when the entry has no URL: structured data without a stable `@id` is
+ * an orphan node no crawler can attach to a page.
+ */
+export declare function buildJsonLd(site: SeoSite, resource: SeoResource, options?: JsonLdOptions): JsonLdObject | null;
+/**
+ * JSON-LD ready to sit inside a `<script type="application/ld+json">`.
+ *
+ * `<`, `>` and `&` are written as `\u00XX` escapes. This is not decoration: a
+ * value containing the literal text `</script>` closes the tag early, and the
+ * remainder of the JSON becomes markup in the document. Inside a script
+ * element, HTML entity escaping does *not* apply — the only escape the parser
+ * respects is the JSON one, so it has to happen here. U+2028 and U+2029 are
+ * escaped for the same reason on the JavaScript side.
+ */
+export declare function renderJsonLdScript(graph: JsonLdObject | readonly JsonLdObject[]): string;
+//# sourceMappingURL=json-ld.d.ts.map

package/dist/json-ld.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-ld.d.ts","sourceRoot":"","sources":["../src/json-ld.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAmB,MAAM,iBAAiB,CAAA;AAE5E,OAAO,KAAK,EAAY,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAG5F;;;;;;;;;;;;;;;;;GAiBG;AAEH,wEAAwE;AACxE,MAAM,MAAM,WAAW,GACnB,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,SAAS,WAAW,EAAE,GACtB;IAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAAA;CAAE,CAAA;AAEvD,MAAM,MAAM,YAAY,GAAG;IAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAAA;CAAE,CAAA;AAE9E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,YAAY,CAAA;IACjC;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACjD,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,CAAC,EAAE,YAAY,CAAA;IACjC,iFAAiF;IACjF,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAChC;AAmDD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,UAAU,EAAE,oBAAoB,EAChC,OAAO,GAAE,aAAkB,GAC1B,MAAM,CAiBR;AAqGD;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,OAAO,EACb,QAAQ,EAAE,WAAW,EACrB,OAAO,GAAE,aAAkB,GAC1B,YAAY,GAAG,IAAI,CAuGrB;AA0BD;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,SAAS,YAAY,EAAE,GAAG,MAAM,CAOxF"}

package/dist/json-ld.js

@@ -0,0 +1,319 @@
+import { condense, extractRichText } from '@cogenta/schema';
+import { canonicalUrl } from './url.js';
+/**
+ * Collection name → schema.org type.
+ *
+ * Names are matched after lower-casing and stripping non-letters, so `blogPost`,
+ * `blog_post` and `BlogPost` all land on the same row. The list is short and
+ * covers what a CMS actually models; everything else falls through to the
+ * shape-based rules below, which is the honest answer for a bespoke collection.
+ */
+const TYPE_BY_NAME = {
+    article: 'Article',
+    post: 'BlogPosting',
+    blogpost: 'BlogPosting',
+    news: 'NewsArticle',
+    newsarticle: 'NewsArticle',
+    page: 'WebPage',
+    author: 'Person',
+    person: 'Person',
+    product: 'Product',
+    event: 'Event',
+    recipe: 'Recipe',
+    faq: 'FAQPage',
+    organization: 'Organization',
+    organisation: 'Organization',
+    company: 'Organization',
+    job: 'JobPosting',
+    course: 'Course',
+    book: 'Book',
+    video: 'VideoObject',
+    tag: 'Thing',
+    category: 'Thing',
+};
+/** Types whose main text property is `articleBody` and that carry a `headline`. */
+const ARTICLE_TYPES = new Set([
+    'Article',
+    'BlogPosting',
+    'NewsArticle',
+    'TechArticle',
+    'Report',
+]);
+function normaliseName(name) {
+    return name.toLowerCase().replace(/[^a-z]/gu, '');
+}
+function fieldsOf(collection) {
+    return Object.entries(collection.fields);
+}
+/**
+ * The schema.org type of a collection.
+ *
+ * Order matters: an explicit override, then the name, then the shape. The
+ * shape rule is deliberately blunt — long text plus a publication date is an
+ * article, and everything else is a `WebPage` — because a subtler heuristic
+ * would be a heuristic nobody can predict from reading the collection.
+ */
+export function schemaTypeFor(collection, options = {}) {
+    const override = options.types?.[collection.name];
+    if (override !== undefined)
+        return override;
+    const byName = TYPE_BY_NAME[normaliseName(collection.name)];
+    if (byName !== undefined)
+        return byName;
+    const fields = fieldsOf(collection);
+    const hasProse = fields.some(([, field]) => field.kind === 'richText');
+    const hasDate = fields.some(([name, field]) => (field.kind === 'datetime' || field.kind === 'date') && /publish|date/iu.test(name));
+    if (hasProse && hasDate)
+        return 'Article';
+    if (collection.routing !== undefined)
+        return 'WebPage';
+    return 'Thing';
+}
+/** Field names that mean "the human-readable label of this thing". */
+const NAME_FIELDS = ['title', 'name', 'label', 'heading'];
+/** Field names that mean "the short summary". */
+const DESCRIPTION_FIELDS = ['excerpt', 'description', 'summary', 'subtitle', 'teaser', 'abstract'];
+function firstStringValue(resource, candidates, kinds) {
+    for (const candidate of candidates) {
+        const field = resource.collection.fields[candidate];
+        if (field === undefined || !kinds.includes(field.kind))
+            continue;
+        const value = resource.entry.values[candidate];
+        if (typeof value === 'string' && value.trim().length > 0)
+            return condense(value);
+    }
+    return undefined;
+}
+function imageValue(image) {
+    return {
+        '@type': 'ImageObject',
+        url: image.url,
+        width: image.width,
+        height: image.height,
+        caption: image.alt,
+    };
+}
+function referenceValue(reference) {
+    return {
+        '@type': reference.type ?? 'Thing',
+        name: reference.name,
+        url: reference.url,
+    };
+}
+function resolveMedia(value, resolvers) {
+    const ids = (Array.isArray(value) ? value : [value]).filter((id) => typeof id === 'string' && id.length > 0);
+    const resolve = resolvers?.media;
+    if (resolve === undefined)
+        return [];
+    const images = [];
+    for (const id of ids) {
+        const image = resolve(id);
+        if (image !== null)
+            images.push(image);
+    }
+    return images;
+}
+function resolveReferences(value, target, resolvers) {
+    const ids = (Array.isArray(value) ? value : [value]).filter((id) => typeof id === 'string' && id.length > 0);
+    const resolve = resolvers?.reference;
+    if (resolve === undefined)
+        return [];
+    const references = [];
+    for (const id of ids) {
+        const reference = resolve(target, id);
+        if (reference !== null)
+            references.push(reference);
+    }
+    return references;
+}
+/**
+ * The property a relation field maps to.
+ *
+ * Only the three relations a CMS reliably has are mapped. A relation to
+ * `relatedProducts` has no defensible schema.org property, and inventing one
+ * produces a graph that says something the site does not mean.
+ */
+function relationProperty(fieldName, target) {
+    const name = normaliseName(fieldName);
+    const to = normaliseName(target);
+    if (name === 'author' || name === 'authors' || to === 'author' || to === 'person')
+        return 'author';
+    if (name === 'tags' || name === 'keywords' || to === 'tag')
+        return 'keywords';
+    if (name === 'category' || name === 'categories' || to === 'category')
+        return 'articleSection';
+    return null;
+}
+function dateProperty(fieldName) {
+    const name = normaliseName(fieldName);
+    if (name === 'publishedat' || name === 'publishdate' || name === 'date')
+        return 'datePublished';
+    if (name === 'updatedat' || name === 'modifiedat')
+        return 'dateModified';
+    if (name === 'expiresat' || name === 'expirydate')
+        return 'expires';
+    if (name === 'startsat' || name === 'startdate')
+        return 'startDate';
+    if (name === 'endsat' || name === 'enddate')
+        return 'endDate';
+    return null;
+}
+const DEFAULT_MAX_BODY = 5_000;
+/**
+ * The JSON-LD object for one entry.
+ *
+ * `null` when the entry has no URL: structured data without a stable `@id` is
+ * an orphan node no crawler can attach to a page.
+ */
+export function buildJsonLd(site, resource, options = {}) {
+    const url = canonicalUrl(site, resource);
+    if (url === null)
+        return null;
+    const { collection, entry } = resource;
+    const type = schemaTypeFor(collection, options);
+    const resolvers = options.resolvers;
+    const graph = {
+        '@context': 'https://schema.org',
+        '@type': type,
+        '@id': url,
+        url,
+        inLanguage: entry.locale,
+    };
+    const name = firstStringValue(resource, NAME_FIELDS, ['text', 'slug']);
+    if (name !== undefined) {
+        // `headline` is the article-family property; everything else uses `name`.
+        // Google truncates `headline` past 110 characters, so both are emitted for
+        // an article: the short one for the rich result, the full one for the graph.
+        if (ARTICLE_TYPES.has(type)) {
+            graph.headline = name.length > 110 ? `${name.slice(0, 107).trimEnd()}…` : name;
+            graph.name = name;
+        }
+        else {
+            graph.name = name;
+        }
+    }
+    const description = firstStringValue(resource, DESCRIPTION_FIELDS, ['text', 'richText']);
+    if (description !== undefined)
+        graph.description = description;
+    const images = [];
+    const authors = [];
+    const keywords = [];
+    const sections = [];
+    for (const [fieldName, field] of fieldsOf(collection)) {
+        const value = entry.values[fieldName];
+        if (value === undefined || value === null)
+            continue;
+        switch (field.kind) {
+            case 'media': {
+                images.push(...resolveMedia(value, resolvers));
+                break;
+            }
+            case 'relation': {
+                const target = typeof field.options.to === 'string' ? field.options.to : fieldName;
+                const property = relationProperty(fieldName, target);
+                if (property === null)
+                    break;
+                const references = resolveReferences(value, target, resolvers);
+                if (property === 'author')
+                    authors.push(...references);
+                if (property === 'keywords')
+                    keywords.push(...references.map((one) => one.name));
+                if (property === 'articleSection')
+                    sections.push(...references.map((one) => one.name));
+                break;
+            }
+            case 'date':
+            case 'datetime': {
+                const property = dateProperty(fieldName);
+                if (property !== null && typeof value === 'string')
+                    graph[property] = value;
+                break;
+            }
+            case 'richText': {
+                if (!ARTICLE_TYPES.has(type))
+                    break;
+                const body = extractRichText(value);
+                if (body.length === 0)
+                    break;
+                const limit = options.maxBodyLength ?? DEFAULT_MAX_BODY;
+                graph.articleBody = body.length > limit ? body.slice(0, limit).trimEnd() : body;
+                break;
+            }
+            case 'geo': {
+                if (!isGeoPoint(value))
+                    break;
+                graph.geo = { '@type': 'GeoCoordinates', latitude: value.lat, longitude: value.lng };
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    if (images.length > 0) {
+        graph.image = images.length === 1 ? imageValue(images[0]) : images.map(imageValue);
+    }
+    if (authors.length > 0) {
+        graph.author =
+            authors.length === 1
+                ? referenceValue({ type: 'Person', ...authors[0] })
+                : authors.map((one) => referenceValue({ type: 'Person', ...one }));
+    }
+    if (keywords.length > 0)
+        graph.keywords = keywords.join(', ');
+    if (sections.length > 0)
+        graph.articleSection = sections[0];
+    // The system fields are authoritative for dates: a collection may have no
+    // `publishedAt` of its own, and every entry has these two (contract A).
+    if (graph.datePublished === undefined && entry.publishedAt !== null) {
+        graph.datePublished = entry.publishedAt;
+    }
+    if (graph.dateModified === undefined)
+        graph.dateModified = entry.updatedAt;
+    if (options.publisher !== undefined) {
+        graph.publisher = referenceValue({ type: 'Organization', ...options.publisher });
+    }
+    return stripUndefined(graph);
+}
+function isGeoPoint(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const point = value;
+    return typeof point.lat === 'number' && typeof point.lng === 'number';
+}
+/** `undefined` is not JSON. Dropping keys here keeps every call site free of guards. */
+function stripUndefined(value) {
+    const cleaned = {};
+    for (const [key, entry] of Object.entries(value)) {
+        if (entry === undefined)
+            continue;
+        cleaned[key] = typeof entry === 'object' && entry !== null ? stripDeep(entry) : entry;
+    }
+    return cleaned;
+}
+function stripDeep(value) {
+    if (Array.isArray(value))
+        return value.map(stripDeep);
+    if (typeof value === 'object' && value !== null) {
+        return stripUndefined(value);
+    }
+    return value;
+}
+/**
+ * JSON-LD ready to sit inside a `<script type="application/ld+json">`.
+ *
+ * `<`, `>` and `&` are written as `\u00XX` escapes. This is not decoration: a
+ * value containing the literal text `</script>` closes the tag early, and the
+ * remainder of the JSON becomes markup in the document. Inside a script
+ * element, HTML entity escaping does *not* apply — the only escape the parser
+ * respects is the JSON one, so it has to happen here. U+2028 and U+2029 are
+ * escaped for the same reason on the JavaScript side.
+ */
+export function renderJsonLdScript(graph) {
+    return JSON.stringify(graph)
+        .replace(/</gu, '\\u003c')
+        .replace(/>/gu, '\\u003e')
+        .replace(/&/gu, '\\u0026')
+        .replace(/\u2028/gu, '\\u2028')
+        .replace(/\u2029/gu, '\\u2029');
+}
+//# sourceMappingURL=json-ld.js.map

package/dist/json-ld.js.map

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

package/dist/llms-txt.d.ts

@@ -0,0 +1,50 @@
+import { type IndexableOptions } from './indexable.js';
+import type { SeoResource, SeoSite } from './types.js';
+/**
+ * `llms.txt` — the site, in Markdown, for a model that has one request to spend.
+ *
+ * The format (llmstxt.org) is a single `H1`, an optional `>` blockquote
+ * summary, then `H2` sections of links with a short note each. It is Markdown
+ * rather than XML because the consumer is a language model, and a sitemap is
+ * exactly the wrong shape for one: 50 000 bare URLs with no titles say nothing
+ * about what the site is.
+ *
+ * The same publication gate applies as everywhere else. A draft listed here is
+ * worse than a draft in a sitemap: a model does not queue the URL for later, it
+ * repeats the title in an answer immediately.
+ */
+export interface LlmsTxtLink {
+    readonly title: string;
+    readonly url: string;
+    readonly note?: string;
+}
+export interface LlmsTxtSection {
+    readonly title: string;
+    readonly links: readonly LlmsTxtLink[];
+}
+export interface LlmsTxtOptions {
+    readonly site: SeoSite;
+    /** Defaults to the site name. */
+    readonly title?: string;
+    /** The blockquote line. Defaults to the site description. */
+    readonly summary?: string;
+    /** Free paragraphs between the summary and the first section. */
+    readonly details?: readonly string[];
+    readonly sections: readonly LlmsTxtSection[];
+}
+export declare function renderLlmsTxt(options: LlmsTxtOptions): string;
+export interface LlmsTxtSectionsOptions extends IndexableOptions {
+    /** Section heading for a collection. Defaults to its plural label. */
+    readonly sectionTitle?: (collectionName: string) => string;
+    /** Entries listed per collection. Defaults to 100. */
+    readonly limitPerSection?: number;
+}
+/**
+ * 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 declare function llmsTxtSectionsFor(site: SeoSite, resources: readonly SeoResource[], options?: LlmsTxtSectionsOptions): readonly LlmsTxtSection[];
+//# sourceMappingURL=llms-txt.d.ts.map

package/dist/llms-txt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llms-txt.d.ts","sourceRoot":"","sources":["../src/llms-txt.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,gBAAgB,EAAsB,MAAM,gBAAgB,CAAA;AAC1E,OAAO,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAGtD;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAA;CACvC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;IACtB,iCAAiC;IACjC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,6DAA6D;IAC7D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,iEAAiE;IACjE,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACpC,QAAQ,CAAC,QAAQ,EAAE,SAAS,cAAc,EAAE,CAAA;CAC7C;AAkBD,wBAAgB,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,CAsB7D;AAcD,MAAM,WAAW,sBAAuB,SAAQ,gBAAgB;IAC9D,sEAAsE;IACtE,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,cAAc,EAAE,MAAM,KAAK,MAAM,CAAA;IAC1D,sDAAsD;IACtD,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAClC;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,OAAO,EACb,SAAS,EAAE,SAAS,WAAW,EAAE,EACjC,OAAO,GAAE,sBAA2B,GACnC,SAAS,cAAc,EAAE,CA8B3B"}