@krantho/api 0.0.0-stage → 1.0.0

package/dist/handlers/seo-impact.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Collection impact analysis handler.
+ *
+ * Evaluates the impact of changing a collection's archetype by scanning
+ * all documents and identifying orphaned properties (currently set but
+ * unsupported under the new archetype) and missing required properties
+ * (required under the new archetype but not currently set).
+ *
+ * GET /api/seo/collection/:name/impact?archetype=preset-name
+ */
+import type { ApiHandler } from '../types.js';
+export interface ImpactResponse {
+    archetype: string;
+    totalDocuments: number;
+    affectedDocuments: Array<{
+        slug: string;
+        title: string;
+        orphanedProperties: Array<{
+            entityType: string;
+            property: string;
+            value: unknown;
+        }>;
+        missingRequired: Array<{
+            entityType: string;
+            property: string;
+        }>;
+    }>;
+    summary: {
+        documentsWithOrphans: number;
+        documentsWithMissingRequired: number;
+        totalOrphanedProperties: number;
+        totalMissingRequired: number;
+    };
+}
+export declare const seoCollectionImpact: ApiHandler;
+//# sourceMappingURL=seo-impact.d.ts.map

package/dist/handlers/seo-impact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seo-impact.d.ts","sourceRoot":"","sources":["../../src/handlers/seo-impact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAE7C,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAA;IACjB,cAAc,EAAE,MAAM,CAAA;IACtB,iBAAiB,EAAE,KAAK,CAAC;QACvB,IAAI,EAAE,MAAM,CAAA;QACZ,KAAK,EAAE,MAAM,CAAA;QACb,kBAAkB,EAAE,KAAK,CAAC;YACxB,UAAU,EAAE,MAAM,CAAA;YAClB,QAAQ,EAAE,MAAM,CAAA;YAChB,KAAK,EAAE,OAAO,CAAA;SACf,CAAC,CAAA;QACF,eAAe,EAAE,KAAK,CAAC;YACrB,UAAU,EAAE,MAAM,CAAA;YAClB,QAAQ,EAAE,MAAM,CAAA;SACjB,CAAC,CAAA;KACH,CAAC,CAAA;IACF,OAAO,EAAE;QACP,oBAAoB,EAAE,MAAM,CAAA;QAC5B,4BAA4B,EAAE,MAAM,CAAA;QACpC,uBAAuB,EAAE,MAAM,CAAA;QAC/B,oBAAoB,EAAE,MAAM,CAAA;KAC7B,CAAA;CACF;AAED,eAAO,MAAM,mBAAmB,EAAE,UA4IjC,CAAA"}

package/dist/handlers/seo-impact.js

@@ -0,0 +1,137 @@
+/**
+ * Collection impact analysis handler.
+ *
+ * Evaluates the impact of changing a collection's archetype by scanning
+ * all documents and identifying orphaned properties (currently set but
+ * unsupported under the new archetype) and missing required properties
+ * (required under the new archetype but not currently set).
+ *
+ * GET /api/seo/collection/:name/impact?archetype=preset-name
+ */
+import { canQuery } from '@krantho/persistence';
+import { requireRole } from '../permissions.js';
+import { loadSeoModule } from '../seo-loader.js';
+import { loadSeo } from '../seo-subsystem.js';
+export const seoCollectionImpact = async (req, ctx) => {
+    const denied = requireRole(ctx.auth, 'admin');
+    if (denied)
+        return denied;
+    if (!ctx.seoConfigAdapter) {
+        return { status: 501, body: { error: 'SEO configuration not available' } };
+    }
+    const collectionName = req.params['name'];
+    if (!collectionName) {
+        return { status: 400, body: { error: 'Collection name required' } };
+    }
+    const archetypeName = req.query['archetype'];
+    if (!archetypeName) {
+        return { status: 400, body: { error: 'Archetype query parameter required' } };
+    }
+    // Dynamically import to avoid bundling @krantho/seo in the API
+    const seo = await loadSeoModule();
+    const { readers } = await loadSeo(ctx.config);
+    // Build the set of entity types in the proposed archetype
+    // For now, accept a comma-separated list of types as the archetype parameter
+    const proposedTypes = archetypeName
+        .split(',')
+        .map((t) => t.trim())
+        .filter(Boolean);
+    if (proposedTypes.length === 0) {
+        return { status: 400, body: { error: 'No types specified in archetype' } };
+    }
+    const proposedTypeSet = new Set(proposedTypes);
+    // The properties any active reader's rule for each type requires
+    const requiredByType = new Map();
+    for (const type of proposedTypes) {
+        const required = new Set();
+        for (const id of readers) {
+            const profile = seo.getProfile(id);
+            const rule = profile ? seo.ruleFor(profile, type) : undefined;
+            if (rule?.status === 'active' || rule?.status === 'restricted') {
+                for (const property of rule.required ?? [])
+                    required.add(property);
+            }
+        }
+        if (required.size > 0)
+            requiredByType.set(type, [...required]);
+    }
+    // List all documents in the collection
+    if (!canQuery(ctx.adapter)) {
+        return { status: 501, body: { error: 'Collection listing not available' } };
+    }
+    const { items: documents } = await ctx.adapter.query({
+        state: 'current',
+        status: 'published',
+        projection: 'summary',
+        collections: [collectionName],
+    });
+    // Batch-load all document SEO configs for this collection in a single query
+    const docConfigs = await ctx.seoConfigAdapter.listConfigsByPrefix(`doc:${collectionName}/`);
+    const configBySlug = new Map();
+    for (const config of docConfigs) {
+        // Extract slug from config id: "doc:pages/home" → "home"
+        const slug = config.id.slice(`doc:${collectionName}/`.length);
+        configBySlug.set(slug, config);
+    }
+    const affectedDocuments = [];
+    for (const doc of documents) {
+        const docConfig = configBySlug.get(doc.meta.slug);
+        if (!docConfig)
+            continue;
+        const orphanedProperties = [];
+        const missingRequired = [];
+        // Find orphaned properties: properties on entities whose @type is not in the proposed archetype
+        for (const entity of docConfig.config.entities) {
+            if (!proposedTypeSet.has(entity['@type'])) {
+                // Entire entity is orphaned — list all its populated properties
+                for (const [prop, val] of Object.entries(entity.properties)) {
+                    if (val !== undefined && val !== null && val !== '') {
+                        orphanedProperties.push({
+                            entityType: entity['@type'],
+                            property: prop,
+                            value: val,
+                        });
+                    }
+                }
+            }
+        }
+        // Find missing required: required properties under the proposed types that are not set
+        for (const type of proposedTypes) {
+            const required = requiredByType.get(type);
+            if (!required)
+                continue;
+            // Find matching entity in the doc's config
+            const docEntity = docConfig.config.entities.find((e) => e['@type'] === type);
+            for (const prop of required) {
+                const value = docEntity?.properties[prop];
+                if (value === undefined || value === null || value === '') {
+                    missingRequired.push({ entityType: type, property: prop });
+                }
+            }
+        }
+        if (orphanedProperties.length > 0 || missingRequired.length > 0) {
+            const title = typeof doc.fields['title'] === 'string' ? doc.fields['title'] : doc.meta.slug;
+            affectedDocuments.push({
+                slug: doc.meta.slug,
+                title,
+                orphanedProperties,
+                missingRequired,
+            });
+        }
+    }
+    const summary = {
+        documentsWithOrphans: affectedDocuments.filter((d) => d.orphanedProperties.length > 0).length,
+        documentsWithMissingRequired: affectedDocuments.filter((d) => d.missingRequired.length > 0)
+            .length,
+        totalOrphanedProperties: affectedDocuments.reduce((sum, d) => sum + d.orphanedProperties.length, 0),
+        totalMissingRequired: affectedDocuments.reduce((sum, d) => sum + d.missingRequired.length, 0),
+    };
+    const response = {
+        archetype: archetypeName,
+        totalDocuments: documents.length,
+        affectedDocuments,
+        summary,
+    };
+    return { status: 200, body: response };
+};
+//# sourceMappingURL=seo-impact.js.map

package/dist/handlers/seo-impact.js.map

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

package/dist/handlers/seo-indexnow.d.ts

@@ -0,0 +1,11 @@
+import type { ApiHandler } from '../types.js';
+/** The API path of the IndexNow key file; a site serves it at `/<key>.txt` */
+export declare const SEO_INDEXNOW_KEY_PATH = "/api/seo/indexnow/:key";
+/**
+ * GET /api/seo/indexnow/:key — the IndexNow key file. IndexNow reads it at
+ * `<site.baseUrl>/<key>.txt` to confirm the site owns the key, so the site
+ * routes that address here. Answers the key as plain text when it matches
+ * `seo.indexNow.key`, and 404 otherwise.
+ */
+export declare const seoIndexNowKey: ApiHandler;
+//# sourceMappingURL=seo-indexnow.d.ts.map

package/dist/handlers/seo-indexnow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seo-indexnow.d.ts","sourceRoot":"","sources":["../../src/handlers/seo-indexnow.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAE7C,8EAA8E;AAC9E,eAAO,MAAM,qBAAqB,2BAA2B,CAAA;AAE7D;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAE,UAI5B,CAAA"}

package/dist/handlers/seo-indexnow.js

@@ -0,0 +1,15 @@
+/** The API path of the IndexNow key file; a site serves it at `/<key>.txt` */
+export const SEO_INDEXNOW_KEY_PATH = '/api/seo/indexnow/:key';
+/**
+ * GET /api/seo/indexnow/:key — the IndexNow key file. IndexNow reads it at
+ * `<site.baseUrl>/<key>.txt` to confirm the site owns the key, so the site
+ * routes that address here. Answers the key as plain text when it matches
+ * `seo.indexNow.key`, and 404 otherwise.
+ */
+export const seoIndexNowKey = async (req, ctx) => {
+    const key = ctx.config.seo.indexNow.key;
+    if (!key || req.params['key'] !== key)
+        return { status: 404, body: { error: 'Not found' } };
+    return { status: 200, body: key, headers: { 'content-type': 'text/plain; charset=utf-8' } };
+};
+//# sourceMappingURL=seo-indexnow.js.map

package/dist/handlers/seo-indexnow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"seo-indexnow.js","sourceRoot":"","sources":["../../src/handlers/seo-indexnow.ts"],"names":[],"mappings":"AAEA,8EAA8E;AAC9E,MAAM,CAAC,MAAM,qBAAqB,GAAG,wBAAwB,CAAA;AAE7D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAe,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;IAC3D,MAAM,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAA;IACvC,IAAI,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,GAAG;QAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,EAAE,CAAA;IAC3F,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,cAAc,EAAE,2BAA2B,EAAE,EAAE,CAAA;AAC7F,CAAC,CAAA"}

package/dist/handlers/seo-llms-txt.d.ts

@@ -0,0 +1,26 @@
+import type { ApiContext, ApiHandler } from '../types.js';
+/** The route serving the site's llms.txt */
+export declare const SEO_LLMS_TXT_PATH = "/api/seo/llms.txt";
+/** Site settings key holding the saved llms.txt snapshot */
+export declare const LLMS_TXT_SETTING = "seo.llmsTxt";
+/** Text that replaces the generated summary and link descriptions */
+export interface LlmsTxtOverrides {
+    summary?: string | undefined;
+    /** Link descriptions keyed by `collection/slug` */
+    descriptions?: ReadonlyMap<string, string> | undefined;
+}
+/**
+ * Build llms.txt (llmstxt.org) from the live documents: the site name, its
+ * summary, then one section per collection with pages (`rendersPages()`) listing each live,
+ * indexable document with its URL and description.
+ */
+export declare function buildLlmsTxt(ctx: ApiContext, overrides?: LlmsTxtOverrides): Promise<string>;
+/** The saved llms.txt snapshot, or null when none is saved */
+export declare function loadLlmsTxtSnapshot(ctx: ApiContext): Promise<string | null>;
+/**
+ * GET /api/seo/llms.txt — the saved snapshot when there is one, else generated
+ * from the live documents, as text/plain. The `x-krantho-llms-origin` header
+ * says which: `snapshot` or `generated`.
+ */
+export declare const seoLlmsTxt: ApiHandler;
+//# sourceMappingURL=seo-llms-txt.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"seo-llms-txt.d.ts","sourceRoot":"","sources":["../../src/handlers/seo-llms-txt.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAGzD,4CAA4C;AAC5C,eAAO,MAAM,iBAAiB,sBAAsB,CAAA;AAEpD,4DAA4D;AAC5D,eAAO,MAAM,gBAAgB,gBAAgB,CAAA;AAE7C,qEAAqE;AACrE,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5B,mDAAmD;IACnD,YAAY,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAA;CACvD;AAsDD;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,UAAU,EACf,SAAS,GAAE,gBAAqB,GAC/B,OAAO,CAAC,MAAM,CAAC,CAcjB;AAED,8DAA8D;AAC9D,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAGjF;AAKD;;;;GAIG;AACH,eAAO,MAAM,UAAU,EAAE,UAcxB,CAAA"}

package/dist/handlers/seo-llms-txt.js

@@ -0,0 +1,99 @@
+import { documentPath, rendersPages } from '@krantho/core';
+import { canReadPublished } from '@krantho/persistence';
+import { buildSeoFieldMap, resolveSeoField } from '@krantho/seo-shared';
+import { PUBLIC_MACHINE_READ_CACHE_CONTROL } from '../public-cache.js';
+import { isNoindex } from './seo-sitemap.js';
+/** The route serving the site's llms.txt */
+export const SEO_LLMS_TXT_PATH = '/api/seo/llms.txt';
+/** Site settings key holding the saved llms.txt snapshot */
+export const LLMS_TXT_SETTING = 'seo.llmsTxt';
+/** One line of text: runs of whitespace, newlines included, become one space */
+function oneLine(text) {
+    return text.replace(/\s+/g, ' ').trim();
+}
+/** The site summary: the override, else the site SEO config's primary entity description */
+async function siteSummary(ctx, overrides) {
+    if (overrides.summary !== undefined)
+        return oneLine(overrides.summary);
+    const config = await ctx.seoConfigAdapter?.getConfig('site');
+    const description = config?.config.entities[0]?.properties['description'];
+    return typeof description === 'string' ? oneLine(description) : '';
+}
+/** `- [title](url): description` for one live document, or null when it is not listed */
+function documentLine(ctx, collection, doc, overrides) {
+    if (isNoindex(doc.fields))
+        return null;
+    const path = documentPath(collection, doc.meta.slug);
+    if (path === null)
+        return null;
+    const fieldMap = buildSeoFieldMap(Object.keys(doc.fields));
+    const title = oneLine(resolveSeoField(fieldMap, 'title', doc.fields)) || doc.meta.slug;
+    const override = overrides.descriptions?.get(`${collection.name}/${doc.meta.slug}`);
+    const description = oneLine(override ?? resolveSeoField(fieldMap, 'description', doc.fields));
+    const baseUrl = ctx.config.site.baseUrl.replace(/\/$/, '');
+    const link = `- [${title}](${baseUrl}${path})`;
+    return description ? `${link}: ${description}` : link;
+}
+/** The `## collection` block of one collection, or null when it lists nothing */
+async function collectionBlock(ctx, adapter, collection, overrides) {
+    const { items: docs } = await adapter.query({
+        state: 'published',
+        projection: 'summary',
+        collections: [collection.name],
+    });
+    const lines = docs
+        .map((doc) => documentLine(ctx, collection, doc, overrides))
+        .filter((line) => line !== null);
+    if (lines.length === 0)
+        return null;
+    return [`## ${collection.name}`, '', ...lines].join('\n');
+}
+/**
+ * Build llms.txt (llmstxt.org) from the live documents: the site name, its
+ * summary, then one section per collection with pages (`rendersPages()`) listing each live,
+ * indexable document with its URL and description.
+ */
+export async function buildLlmsTxt(ctx, overrides = {}) {
+    const blocks = [`# ${oneLine(ctx.config.site.name)}`];
+    const summary = await siteSummary(ctx, overrides);
+    if (summary)
+        blocks.push(`> ${summary}`);
+    if (canReadPublished(ctx.adapter)) {
+        for (const collection of ctx.contentConfig.collections.values()) {
+            if (!rendersPages(collection))
+                continue;
+            const block = await collectionBlock(ctx, ctx.adapter, collection, overrides);
+            if (block)
+                blocks.push(block);
+        }
+    }
+    return `${blocks.join('\n\n')}\n`;
+}
+/** The saved llms.txt snapshot, or null when none is saved */
+export async function loadLlmsTxtSnapshot(ctx) {
+    const saved = await ctx.siteSettingsAdapter?.getSetting(LLMS_TXT_SETTING);
+    return saved ? saved : null;
+}
+/** The response header naming where the served llms.txt comes from */
+const LLMS_TXT_ORIGIN_HEADER = 'x-krantho-llms-origin';
+/**
+ * GET /api/seo/llms.txt — the saved snapshot when there is one, else generated
+ * from the live documents, as text/plain. The `x-krantho-llms-origin` header
+ * says which: `snapshot` or `generated`.
+ */
+export const seoLlmsTxt = async (_req, ctx) => {
+    if (!canReadPublished(ctx.adapter)) {
+        return { status: 501, body: { error: 'Adapter does not support reading published content' } };
+    }
+    const snapshot = await loadLlmsTxtSnapshot(ctx);
+    return {
+        status: 200,
+        body: snapshot ?? (await buildLlmsTxt(ctx)),
+        headers: {
+            'content-type': 'text/plain; charset=utf-8',
+            'cache-control': PUBLIC_MACHINE_READ_CACHE_CONTROL,
+            [LLMS_TXT_ORIGIN_HEADER]: snapshot === null ? 'generated' : 'snapshot',
+        },
+    };
+};
+//# sourceMappingURL=seo-llms-txt.js.map

package/dist/handlers/seo-llms-txt.js.map

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

package/dist/handlers/seo-preview.d.ts

@@ -0,0 +1,8 @@
+import type { ApiHandler } from '../types.js';
+/**
+ * GET /api/seo/preview/:collection/:slug — compose the JSON-LD of the
+ * document's current version in its collection and locale (`?locale=`, the
+ * site's default when absent; 400 when it is not a locale code)
+ */
+export declare const seoPreview: ApiHandler;
+//# sourceMappingURL=seo-preview.d.ts.map

package/dist/handlers/seo-preview.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seo-preview.d.ts","sourceRoot":"","sources":["../../src/handlers/seo-preview.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAG7C;;;;GAIG;AACH,eAAO,MAAM,UAAU,EAAE,UAuCxB,CAAA"}

package/dist/handlers/seo-preview.js

@@ -0,0 +1,49 @@
+import { documentPath } from '@krantho/core';
+import { canGetContent } from '@krantho/persistence';
+import { composePageJsonLd } from '../seo-compose.js';
+import { parseLocaleParam, requireParam, validateCollectionParam } from '../validators.js';
+/**
+ * GET /api/seo/preview/:collection/:slug — compose the JSON-LD of the
+ * document's current version in its collection and locale (`?locale=`, the
+ * site's default when absent; 400 when it is not a locale code)
+ */
+export const seoPreview = async (req, ctx) => {
+    const validated = validateCollectionParam(req.params['collection'], ctx);
+    if (!validated.isValid)
+        return validated.response;
+    const slugResult = requireParam(req.params, 'slug');
+    if (!slugResult.isValid)
+        return slugResult.response;
+    const slug = slugResult.value;
+    const collection = validated.collection;
+    const requestedLocale = req.query['locale'];
+    const locale = parseLocaleParam(requestedLocale);
+    if (requestedLocale !== undefined && locale === undefined) {
+        return {
+            status: 400,
+            body: { error: '"locale" must be a locale code, such as "en" or "nb-NO"' },
+        };
+    }
+    if (!canGetContent(ctx.adapter)) {
+        return { status: 501, body: { error: 'Adapter does not support reading a document' } };
+    }
+    const current = await ctx.adapter.getContent(collection, slug, locale);
+    if (!current) {
+        return {
+            status: 404,
+            body: { error: `Content "${slug}" not found in "${collection}"` },
+        };
+    }
+    const graph = await composePageJsonLd({
+        collection,
+        slug,
+        path: documentPath(validated.collectionDef, slug),
+        fields: current.fields,
+        metadata: current.metadata,
+        documentMeta: current.meta,
+        config: ctx.config,
+        seoConfigs: ctx.seoConfigAdapter,
+    });
+    return { status: 200, body: graph };
+};
+//# sourceMappingURL=seo-preview.js.map

package/dist/handlers/seo-preview.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"seo-preview.js","sourceRoot":"","sources":["../../src/handlers/seo-preview.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AACpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAErD,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAA;AAE1F;;;;GAIG;AACH,MAAM,CAAC,MAAM,UAAU,GAAe,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;IACvD,MAAM,SAAS,GAAG,uBAAuB,CAAC,GAAG,CAAC,MAAM,CAAC,YAAY,CAAC,EAAE,GAAG,CAAC,CAAA;IACxE,IAAI,CAAC,SAAS,CAAC,OAAO;QAAE,OAAO,SAAS,CAAC,QAAQ,CAAA;IAEjD,MAAM,UAAU,GAAG,YAAY,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IACnD,IAAI,CAAC,UAAU,CAAC,OAAO;QAAE,OAAO,UAAU,CAAC,QAAQ,CAAA;IACnD,MAAM,IAAI,GAAG,UAAU,CAAC,KAAK,CAAA;IAC7B,MAAM,UAAU,GAAG,SAAS,CAAC,UAAU,CAAA;IACvC,MAAM,eAAe,GAAG,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAA;IAC3C,MAAM,MAAM,GAAG,gBAAgB,CAAC,eAAe,CAAC,CAAA;IAChD,IAAI,eAAe,KAAK,SAAS,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QAC1D,OAAO;YACL,MAAM,EAAE,GAAG;YACX,IAAI,EAAE,EAAE,KAAK,EAAE,yDAAyD,EAAE;SAC3E,CAAA;IACH,CAAC;IACD,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;QAChC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,6CAA6C,EAAE,EAAE,CAAA;IACxF,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC,UAAU,EAAE,IAAI,EAAE,MAAM,CAAC,CAAA;IACtE,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO;YACL,MAAM,EAAE,GAAG;YACX,IAAI,EAAE,EAAE,KAAK,EAAE,YAAY,IAAI,mBAAmB,UAAU,GAAG,EAAE;SAClE,CAAA;IACH,CAAC;IAED,MAAM,KAAK,GAAG,MAAM,iBAAiB,CAAC;QACpC,UAAU;QACV,IAAI;QACJ,IAAI,EAAE,YAAY,CAAC,SAAS,CAAC,aAAa,EAAE,IAAI,CAAC;QACjD,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,YAAY,EAAE,OAAO,CAAC,IAAI;QAC1B,MAAM,EAAE,GAAG,CAAC,MAAM;QAClB,UAAU,EAAE,GAAG,CAAC,gBAAgB;KACjC,CAAC,CAAA;IACF,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,CAAA;AACrC,CAAC,CAAA"}

package/dist/handlers/seo-robots.d.ts

@@ -0,0 +1,22 @@
+import type { ApiContext, ApiHandler } from '../types.js';
+/**
+ * The seo_config id whose `robotsTxt` holds a saved robots.txt override: the
+ * site scope's configuration, beside its entities and never among them. An
+ * admin saves it through `PUT /api/seo/config/site`; while set, the handler
+ * serves it verbatim, otherwise the generated body.
+ */
+export declare const robotsOverrideConfigId: "site";
+/** Build the default robots.txt body, naming the sitemap at the site's root (`/sitemap.xml`) */
+export declare function buildDefaultRobotsBody(baseUrl: string): string;
+/** Read a saved robots override from the site's seo_config, or null if none exists */
+export declare function loadRobotsOverride(ctx: ApiContext): Promise<string | null>;
+/**
+ * GET /api/seo/robots.txt — generate robots.txt with sitemap reference.
+ *
+ * If an override is stored in seo_config (the site scope's `robotsTxt`), it
+ * is returned verbatim. Otherwise a standard robots.txt that
+ * allows all crawlers and points to the sitemap is generated dynamically
+ * from the handler's site.baseUrl.
+ */
+export declare const seoRobots: ApiHandler;
+//# sourceMappingURL=seo-robots.d.ts.map

package/dist/handlers/seo-robots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seo-robots.d.ts","sourceRoot":"","sources":["../../src/handlers/seo-robots.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAGzD;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,EAAG,MAAe,CAAA;AAErD,gGAAgG;AAChG,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAG9D;AAED,sFAAsF;AACtF,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAShF;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS,EAAE,UAYvB,CAAA"}

package/dist/handlers/seo-robots.js

@@ -0,0 +1,48 @@
+import { PUBLIC_MACHINE_READ_CACHE_CONTROL } from '../public-cache.js';
+import { SITEMAP_PUBLIC_PATH } from './seo-sitemap.js';
+/**
+ * The seo_config id whose `robotsTxt` holds a saved robots.txt override: the
+ * site scope's configuration, beside its entities and never among them. An
+ * admin saves it through `PUT /api/seo/config/site`; while set, the handler
+ * serves it verbatim, otherwise the generated body.
+ */
+export const robotsOverrideConfigId = 'site';
+/** Build the default robots.txt body, naming the sitemap at the site's root (`/sitemap.xml`) */
+export function buildDefaultRobotsBody(baseUrl) {
+    const trimmed = baseUrl.replace(/\/$/, '');
+    return ['User-agent: *', 'Allow: /', '', `Sitemap: ${trimmed}${SITEMAP_PUBLIC_PATH}`].join('\n');
+}
+/** Read a saved robots override from the site's seo_config, or null if none exists */
+export async function loadRobotsOverride(ctx) {
+    if (!ctx.seoConfigAdapter)
+        return null;
+    try {
+        const config = await ctx.seoConfigAdapter.getConfig(robotsOverrideConfigId);
+        const override = config?.config.robotsTxt;
+        return typeof override === 'string' && override.length > 0 ? override : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * GET /api/seo/robots.txt — generate robots.txt with sitemap reference.
+ *
+ * If an override is stored in seo_config (the site scope's `robotsTxt`), it
+ * is returned verbatim. Otherwise a standard robots.txt that
+ * allows all crawlers and points to the sitemap is generated dynamically
+ * from the handler's site.baseUrl.
+ */
+export const seoRobots = async (_req, ctx) => {
+    const override = await loadRobotsOverride(ctx);
+    const body = override ?? buildDefaultRobotsBody(ctx.config.site.baseUrl);
+    return {
+        status: 200,
+        body,
+        headers: {
+            'content-type': 'text/plain; charset=utf-8',
+            'cache-control': PUBLIC_MACHINE_READ_CACHE_CONTROL,
+        },
+    };
+};
+//# sourceMappingURL=seo-robots.js.map

package/dist/handlers/seo-robots.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"seo-robots.js","sourceRoot":"","sources":["../../src/handlers/seo-robots.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iCAAiC,EAAE,MAAM,oBAAoB,CAAA;AAEtE,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AAEtD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,MAAe,CAAA;AAErD,gGAAgG;AAChG,MAAM,UAAU,sBAAsB,CAAC,OAAe;IACpD,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAA;IAC1C,OAAO,CAAC,eAAe,EAAE,UAAU,EAAE,EAAE,EAAE,YAAY,OAAO,GAAG,mBAAmB,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AAClG,CAAC;AAED,sFAAsF;AACtF,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,GAAe;IACtD,IAAI,CAAC,GAAG,CAAC,gBAAgB;QAAE,OAAO,IAAI,CAAA;IACtC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,gBAAgB,CAAC,SAAS,CAAC,sBAAsB,CAAC,CAAA;QAC3E,MAAM,QAAQ,GAAG,MAAM,EAAE,MAAM,CAAC,SAAS,CAAA;QACzC,OAAO,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAA;IAC9E,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAA;IACb,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,SAAS,GAAe,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE;IACvD,MAAM,QAAQ,GAAG,MAAM,kBAAkB,CAAC,GAAG,CAAC,CAAA;IAC9C,MAAM,IAAI,GAAG,QAAQ,IAAI,sBAAsB,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;IAExE,OAAO;QACL,MAAM,EAAE,GAAG;QACX,IAAI;QACJ,OAAO,EAAE;YACP,cAAc,EAAE,2BAA2B;YAC3C,eAAe,EAAE,iCAAiC;SACnD;KACF,CAAA;AACH,CAAC,CAAA"}

package/dist/handlers/seo-sitemap.d.ts

@@ -0,0 +1,68 @@
+import type { ApiContext, ApiHandler } from '../types.js';
+/**
+ * Canonical paths for the SEO routes registered in `create-api-handlers.ts`.
+ *
+ * Exported as constants so callers (e.g., the robots.txt handler) reference
+ * the same path the router registers, preventing drift if a route is renamed.
+ */
+export declare const SEO_SITEMAP_PATH = "/api/seo/sitemap";
+/** Where a site serves the sitemap — the address robots.txt names; the site routes it to SEO_SITEMAP_PATH */
+export declare const SITEMAP_PUBLIC_PATH = "/sitemap.xml";
+export declare const SEO_SITEMAP_JSON_PATH = "/api/seo/sitemap.json";
+export declare const SEO_ROBOTS_PATH = "/api/seo/robots.txt";
+/** A single URL entry in the sitemap output */
+export interface SitemapUrl {
+    loc: string;
+    /** When the page last changed, as a W3C Datetime in UTC (`2026-09-30T22:17:06.000Z`) */
+    lastmod?: string | undefined;
+    changefreq: string;
+    priority: string;
+}
+/**
+ * Whether a document asks not to be indexed. The field name is resolved
+ * dynamically so CMS schemas with different conventions (e.g. `robots-index`
+ * vs `noindex`) all work.
+ */
+export declare function isNoindex(fields: Record<string, unknown>): boolean;
+/**
+ * Build the list of sitemap URLs from the handler's content config.
+ *
+ * Pure: reads from the context, returns an array. No side effects. This is
+ * the shared core used by both `seoSitemap` (XML output) and `seoSitemapJson`
+ * (JSON output for the Studio preview), plus any future consumer that needs
+ * the url list.
+ *
+ * Iterates every published item in every collection that renders pages
+ * (`rendersPages()`), skips noindex pages (resolved via the dynamic field map
+ * so CMS field names can differ), and derives the URL with `documentPath()`
+ * from the collection's `path` — or, without one, `pages` items at the site
+ * root (the `home` page is the homepage) and other collections under their
+ * name (`/{name}/slug`). A path is listed once: the homepage, and a fixed-path
+ * collection whose documents share one page.
+ */
+export declare function buildSitemapUrls(ctx: ApiContext): Promise<SitemapUrl[]>;
+/**
+ * Serialize a list of sitemap URLs to XML.
+ *
+ * Exported so tests can drive the serializer directly without needing to
+ * stub the full ApiContext. Also used by the XML handler below.
+ */
+export declare function serializeSitemapXml(urls: readonly SitemapUrl[]): string;
+/**
+ * GET /api/seo/sitemap — generate sitemap XML dynamically from all collections.
+ *
+ * Lists all published content across the collections that render pages, at
+ * site.baseUrl + `documentPath()`. Excludes collections without pages and
+ * noindex pages.
+ */
+export declare const seoSitemap: ApiHandler;
+/**
+ * GET /api/seo/sitemap.json — same url list as the XML handler, served as JSON.
+ *
+ * Used by Studio's Structure → Sitemap & Robots tab to render a sortable table
+ * without parsing XML client-side. Not intended as a public SEO endpoint —
+ * search engines consume the XML at `/api/seo/sitemap` (or wherever your
+ * framework rewrites it, e.g. `/sitemap.xml`).
+ */
+export declare const seoSitemapJson: ApiHandler;
+//# sourceMappingURL=seo-sitemap.d.ts.map

package/dist/handlers/seo-sitemap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seo-sitemap.d.ts","sourceRoot":"","sources":["../../src/handlers/seo-sitemap.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAEzD;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,qBAAqB,CAAA;AAClD,6GAA6G;AAC7G,eAAO,MAAM,mBAAmB,iBAAiB,CAAA;AACjD,eAAO,MAAM,qBAAqB,0BAA0B,CAAA;AAC5D,eAAO,MAAM,eAAe,wBAAwB,CAAA;AAEpD,+CAA+C;AAC/C,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAA;IACX,wFAAwF;IACxF,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5B,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CASlE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CA2C7E;AAyBD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,SAAS,UAAU,EAAE,GAAG,MAAM,CAYvE;AAED;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,EAAE,UAUxB,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,EAAE,UAM5B,CAAA"}