@next-buildr/payload 0.0.0-stage → 2.0.0

package/dist/mcp/route.js

@@ -0,0 +1,230 @@
+import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
+import { ok, toManifest } from '@next-buildr/core';
+import { createBuildrMcpServer, createBuildrTools, createDiscoveryCache, createResources, createSessionStore, } from '@next-buildr/mcp';
+import { handleEndpoints } from 'payload';
+import { createMemoryRateLimiter } from '../plugin/forms/rate-limit.js';
+import { createPayloadMcpBackend } from './http-backend.js';
+const AUTHORIZATION = /^([A-Za-z0-9_-]{1,100}) API-Key (\S{8,512})$/;
+const DEFAULT_SESSION_TTL_MS = 30 * 60_000;
+const FAILURE_WINDOW_MS = 60_000;
+const MAX_FAILURES = 30;
+const reply = (status, error, headers = {}) => new Response(JSON.stringify({ jsonrpc: '2.0', error: { code: -32000, message: error }, id: null }), { status, headers: { 'content-type': 'application/json', ...headers } });
+const originOf = (value) => {
+    if (value === null || value === undefined || value === '')
+        return undefined;
+    try {
+        return new URL(value).origin;
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * `createBuildrMcpRoute({ payload, registry })` returns the `POST`/`GET`/`DELETE` handlers of the
+ * MCP endpoint. Mount them at `app/(builder)/api/buildr/mcp/route.ts`.
+ *
+ * - Disabled (`404`) unless the plugin has `mcp.enabled`.
+ * - Only `Authorization: <collection> API-Key <key>` authenticates; cookies are never read (`401`),
+ *   so a browser cannot drive the endpoint cross-site. A browser `Origin` must be the site's own,
+ *   in Payload's `csrf` list or in `allowedOrigins`.
+ * - The tools run against a local backend: the builder API of the same Payload, called in-process
+ *   (no network hop) as the agent user, so Payload's access control, the plugin's `access`, the
+ *   write limits and the revision checks apply exactly as over the network.
+ * - Stateless: each request is one JSON-RPC exchange on a fresh server. Open documents live in a
+ *   per-user session store held by this route (one per `createBuildrMcpRoute` call, never global);
+ *   on serverless platforms it lives as long as the instance does, and an unknown session after a
+ *   cold start is reported to the agent, which reopens the document.
+ */
+export function createBuildrMcpRoute(options) {
+    const entries = new Map();
+    const sessionTtlMs = options.sessionTtlMs ?? DEFAULT_SESSION_TTL_MS;
+    const maxBodyBytes = options.maxBodyBytes ?? 1_000_000;
+    const limiter = options.rateLimiter ??
+        createMemoryRateLimiter(options.rateLimit ?? { limit: 120, windowMs: 60_000 });
+    // Clients that failed to authenticate too often are refused outright for a while.
+    const failures = createMemoryRateLimiter({ limit: MAX_FAILURES, windowMs: FAILURE_WINDOW_MS });
+    const blockedUntil = new Map();
+    let resolved;
+    const getPayload = () => {
+        if (typeof options.payload !== 'function')
+            return Promise.resolve(options.payload);
+        resolved ??= options.payload().catch((error) => {
+            resolved = undefined;
+            throw error;
+        });
+        return resolved;
+    };
+    const clientOf = (request) => request.headers.get('x-forwarded-for')?.split(',')[0]?.trim() || 'unknown';
+    function sweep(now) {
+        for (const [key, entry] of entries) {
+            entry.store.sweep();
+            if (entry.store.size === 0 && now - entry.lastSeen >= sessionTtlMs)
+                entries.delete(key);
+        }
+        for (const [client, until] of blockedUntil)
+            if (until <= now)
+                blockedUntil.delete(client);
+    }
+    async function entryFor(payload, request, key, collection, apiKey, authorization) {
+        const existing = entries.get(key);
+        if (existing !== undefined) {
+            existing.authorization = authorization;
+            existing.lastSeen = Date.now();
+            return existing;
+        }
+        const site = options.siteUrl ?? new URL(request.url).origin;
+        const apiRoot = payload.config.routes?.api ?? '/api';
+        // Payload answers the builder API from memory; the header is the user's own key, refreshed per request.
+        const holder = {};
+        const inProcess = (input, init) => {
+            const headers = new Headers(init?.headers);
+            headers.set('authorization', holder.entry?.authorization ?? authorization);
+            return handleEndpoints({
+                config: payload.config,
+                request: new Request(input, { ...init, headers }),
+            });
+        };
+        const collections = options.collections ??
+            payload.config.collections
+                .filter((c) => c.fields.some((field) => field.name === 'buildrRevision'))
+                .map((c) => c.slug);
+        const http = createPayloadMcpBackend({
+            baseUrl: `${site}${apiRoot}`,
+            apiKey,
+            collection,
+            collections: [...collections],
+            siteUrl: site,
+            fetch: inProcess,
+            retries: 0,
+            ...(options.theme === undefined ? {} : { theme: options.theme }),
+        });
+        const backend = {
+            ...http,
+            async getManifest() {
+                const served = await http.getManifest();
+                if (served.ok || served.error.code !== 'not-found')
+                    return served;
+                return ok(toManifest(options.registry.meta));
+            },
+        };
+        const store = createSessionStore({ backend, ttlMs: sessionTtlMs });
+        const discoveryCache = createDiscoveryCache();
+        const tools = await createBuildrTools({
+            store,
+            backend,
+            discoveryCache,
+            allowPublish: options.allowPublish === true,
+        });
+        const entry = {
+            store,
+            backend,
+            tools,
+            resources: createResources(discoveryCache),
+            authorization,
+            lastSeen: Date.now(),
+        };
+        holder.entry = entry;
+        entries.set(key, entry);
+        return entry;
+    }
+    /** The route is off unless the plugin registered the agent endpoints (`mcp.enabled`). */
+    const enabled = (payload) => (payload.config.endpoints ?? []).some((endpoint) => endpoint.path === '/buildr/documents');
+    async function POST(request) {
+        const payload = await getPayload();
+        if (!enabled(payload))
+            return reply(404, 'Not found.');
+        const now = Date.now();
+        sweep(now);
+        const origin = request.headers.get('origin');
+        if (origin !== null) {
+            const requested = originOf(origin);
+            const allowed = new Set([
+                originOf(request.url),
+                ...(payload.config.csrf ?? []).map(originOf),
+                ...(options.allowedOrigins ?? []).map(originOf),
+            ].filter((value) => value !== undefined));
+            if (requested === undefined || !allowed.has(requested)) {
+                return reply(403, 'The origin of the request is not allowed.');
+            }
+        }
+        const client = clientOf(request);
+        const until = blockedUntil.get(client);
+        if (until !== undefined && until > now) {
+            return reply(429, 'Too many failed attempts. Try again later.', {
+                'retry-after': String(Math.ceil((until - now) / 1000)),
+            });
+        }
+        // Cookies are never read here: a session cookie alone is not credentials.
+        const deny = async () => {
+            const failed = await failures.hit(client);
+            if (!failed.allowed)
+                blockedUntil.set(client, now + failed.retryAfterSeconds * 1000);
+            return reply(401, 'Send an API key: Authorization: <collection> API-Key <key>.', {
+                'www-authenticate': 'API-Key',
+            });
+        };
+        const authorization = request.headers.get('authorization') ?? '';
+        const match = AUTHORIZATION.exec(authorization);
+        if (match === null)
+            return deny();
+        const collection = match[1];
+        const apiKey = match[2];
+        let user;
+        try {
+            // Only the Authorization header is passed on, so Payload can only use the API-key strategy.
+            const auth = await payload.auth({ headers: new Headers({ authorization }) });
+            user = auth.user;
+        }
+        catch {
+            user = null;
+        }
+        if (user === null ||
+            user === undefined ||
+            user.id === undefined ||
+            user._strategy !== 'api-key') {
+            return deny();
+        }
+        const key = `${user.collection ?? collection}:${String(user.id)}`;
+        const limit = await limiter.hit(key);
+        if (!limit.allowed) {
+            return reply(429, 'Too many requests. Try again later.', {
+                'retry-after': String(limit.retryAfterSeconds),
+            });
+        }
+        const declared = Number(request.headers.get('content-length'));
+        if (Number.isFinite(declared) && declared > maxBodyBytes) {
+            return reply(413, 'The request is too large.');
+        }
+        const body = await request.text();
+        if (body.length > maxBodyBytes)
+            return reply(413, 'The request is too large.');
+        const entry = await entryFor(payload, request, key, collection, apiKey, authorization);
+        const server = createBuildrMcpServer({
+            backend: entry.backend,
+            options: {
+                tools: entry.tools,
+                resources: entry.resources,
+                allowPublish: options.allowPublish === true,
+            },
+        });
+        // No session id generator: stateless mode.
+        const transport = new WebStandardStreamableHTTPServerTransport({
+            enableJsonResponse: true,
+        });
+        try {
+            await server.connect(transport);
+            return await transport.handleRequest(new Request(request.url, { method: 'POST', headers: request.headers, body }));
+        }
+        finally {
+            await server.close().catch(() => undefined);
+        }
+    }
+    /** No server-initiated stream and no connection to end: the server is stateless. */
+    async function notAllowed() {
+        const payload = await getPayload();
+        if (!enabled(payload))
+            return reply(404, 'Not found.');
+        return reply(405, 'This MCP server only accepts POST.', { allow: 'POST' });
+    }
+    return { POST, GET: notAllowed, DELETE: notAllowed };
+}

package/dist/next/get-document.d.ts

@@ -0,0 +1,64 @@
+import type { DataContext } from '@next-buildr/core';
+import type { Payload } from 'payload';
+/** Wraps a read in a tagged cache. The default is `unstable_cache` (Next 15 and 16). */
+export type CacheRead = <T>(read: () => Promise<T>, keyParts: string[], options: {
+    readonly tags: string[];
+}) => () => Promise<T>;
+export interface GetBuildrDocumentInput {
+    readonly payload: Payload;
+    readonly collection: string;
+    /** Look the document up by its slug field... */
+    readonly slug?: string;
+    /** ...or by id. */
+    readonly id?: string | number;
+    readonly slugField?: string;
+    readonly locale?: string;
+    /**
+     * Read the latest draft with the permissions of `user` (uncached). Without a user the read is a
+     * visitor's, so it sees only what is published.
+     */
+    readonly draft?: boolean;
+    readonly user?: unknown;
+    /** The name the document is bound under (`page`, `post`); the collection slug by default. */
+    readonly contextName?: string;
+    /** The public path of the document, for the `route` scope. */
+    readonly path?: (doc: Record<string, unknown>) => string;
+    /** Relation depth of the read. Default `1`. */
+    readonly depth?: number;
+    /** The page of a paginated listing: `route.params.page`. */
+    readonly page?: number;
+    readonly timeZone?: string;
+    /** Replaces the tagged cache (tests, hosts with their own). */
+    readonly cache?: CacheRead;
+}
+/** What `BuildrPage` (`@next-buildr/next`) renders, plus the document itself and its cache tags. */
+export interface BuildrDocumentEntry {
+    /** The resolved layout, as stored: `BuildrPage` migrates and validates it. */
+    readonly document: unknown;
+    readonly context: DataContext;
+    readonly layoutRef: string | null;
+    readonly layoutSource: 'document' | 'template' | 'default-template' | 'builtin';
+    readonly currentId: string | number;
+    /** The Payload document (populated to `depth`), for metadata. */
+    readonly doc: Record<string, unknown>;
+    /** The tags this entry was cached under. */
+    readonly tags: string[];
+}
+/**
+ * The production read of a page (docs/nextjs.md): the document (by slug or id), its layout
+ * (`resolveLayout`), and the `DataContext` (`buildContext`) in one call, or `null` when there is no
+ * such document (a `404`). Published reads go through a tagged cache that `revalidateHooks()`
+ * invalidates; a draft read is never cached.
+ */
+export declare function getBuildrDocument(input: GetBuildrDocumentInput): Promise<BuildrDocumentEntry | null>;
+export interface ListPublishedSlugsInput {
+    readonly payload: Payload;
+    readonly collection: string;
+    readonly slugField?: string;
+    readonly locale?: string;
+    /** Upper bound; a site with more pages relies on `dynamicParams` for the rest. Default `1000`. */
+    readonly limit?: number;
+}
+/** The slugs of the published documents, for `generateStaticParams`. Documents without a slug are skipped. */
+export declare function listPublishedSlugs(input: ListPublishedSlugsInput): Promise<string[]>;
+//# sourceMappingURL=get-document.d.ts.map

package/dist/next/get-document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-document.d.ts","sourceRoot":"","sources":["../../src/next/get-document.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAa,MAAM,mBAAmB,CAAC;AAChE,OAAO,KAAK,EAAE,OAAO,EAAS,MAAM,SAAS,CAAC;AAQ9C,wFAAwF;AACxF,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,EACxB,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACtB,QAAQ,EAAE,MAAM,EAAE,EAClB,OAAO,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,KACjC,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC;AAYtB,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,gDAAgD;IAChD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,mBAAmB;IACnB,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,6FAA6F;IAC7F,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC;IACzD,+CAA+C;IAC/C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,+DAA+D;IAC/D,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC;CAC5B;AAED,oGAAoG;AACpG,MAAM,WAAW,mBAAmB;IAClC,8EAA8E;IAC9E,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,YAAY,EAAE,UAAU,GAAG,UAAU,GAAG,kBAAkB,GAAG,SAAS,CAAC;IAChF,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IACpC,iEAAiE;IACjE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,4CAA4C;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC;CACzB;AAKD;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,sBAAsB,GAC5B,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAyKrC;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,kGAAkG;IAClG,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,8GAA8G;AAC9G,wBAAsB,kBAAkB,CAAC,KAAK,EAAE,uBAAuB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CA2B1F"}

package/dist/next/get-document.js

@@ -0,0 +1,208 @@
+import { buildContext, resolveLayout } from '../data/index.js';
+import { configuredLocales, localeConfigOf } from '../plugin/locales.js';
+import { collectionTag, docTag, globalTag } from './tags.js';
+const SITE_GLOBAL = 'site-settings';
+const defaultCache = (read, keyParts, options) => {
+    let cached;
+    return async () => {
+        // Loaded on first use so this module can be imported (and tested) outside Next.js.
+        const { unstable_cache } = await import('next/cache');
+        cached ??= unstable_cache(read, keyParts, { tags: options.tags });
+        return (await cached());
+    };
+};
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/**
+ * The production read of a page (docs/nextjs.md): the document (by slug or id), its layout
+ * (`resolveLayout`), and the `DataContext` (`buildContext`) in one call, or `null` when there is no
+ * such document (a `404`). Published reads go through a tagged cache that `revalidateHooks()`
+ * invalidates; a draft read is never cached.
+ */
+export async function getBuildrDocument(input) {
+    const { payload, collection } = input;
+    if ((input.slug === undefined) === (input.id === undefined)) {
+        throw new Error('getBuildrDocument needs exactly one of `slug` and `id`.');
+    }
+    const configured = configuredLocales(payload.config);
+    const locale = input.locale ?? configured?.default;
+    if (configured !== undefined && locale !== undefined && !configured.locales.includes(locale)) {
+        return null;
+    }
+    const localeArgs = configured === undefined || locale === undefined
+        ? {}
+        : { locale, ...(configured.fallback ? {} : { fallbackLocale: false }) };
+    const draft = input.draft === true && input.user !== undefined && input.user !== null;
+    const hasSite = payload.config.globals?.some((global) => global.slug === SITE_GLOBAL) === true;
+    const access = draft
+        ? { user: input.user, overrideAccess: false }
+        : { overrideAccess: false };
+    const read = async () => {
+        let doc;
+        const depth = input.depth ?? 1;
+        if (input.id !== undefined) {
+            doc = await payload
+                .findByID({
+                collection: collection,
+                id: input.id,
+                depth,
+                draft,
+                ...localeArgs,
+                ...access,
+            })
+                .then((found) => found)
+                .catch(() => undefined);
+            // A visitor sees published documents only, whatever the collection's read access says.
+            if (!draft &&
+                doc !== undefined &&
+                doc['_status'] !== undefined &&
+                doc['_status'] !== 'published') {
+                doc = undefined;
+            }
+        }
+        else {
+            const where = {
+                and: [
+                    { [input.slugField ?? 'slug']: { equals: input.slug } },
+                    ...(draft ? [] : [{ _status: { equals: 'published' } }]),
+                ],
+            };
+            const found = await payload.find({
+                collection: collection,
+                where,
+                limit: 1,
+                pagination: false,
+                depth,
+                draft,
+                ...localeArgs,
+                ...access,
+            });
+            doc = found.docs[0];
+        }
+        if (doc === undefined || (typeof doc['id'] !== 'string' && typeof doc['id'] !== 'number')) {
+            return null;
+        }
+        const id = doc['id'];
+        const contextName = input.contextName ?? collection;
+        const resolved = await resolveLayout({
+            payload,
+            collection,
+            doc,
+            contextName,
+            draft,
+            ...(draft ? { overrideAccess: false } : {}),
+        });
+        let site;
+        if (hasSite) {
+            try {
+                site = (await payload.findGlobal({
+                    slug: SITE_GLOBAL,
+                    depth: 1,
+                    draft,
+                    ...localeArgs,
+                    ...access,
+                }));
+            }
+            catch {
+                site = undefined;
+            }
+        }
+        const source = {
+            collections: payload.config.collections,
+            globals: (payload.config.globals ?? []),
+        };
+        const options = {
+            contextNames: { [collection]: contextName },
+            siteGlobal: SITE_GLOBAL,
+        };
+        const localeConfig = localeConfigOf(payload.config);
+        const path = input.path?.(doc) ?? '';
+        const scopes = buildContext({
+            source,
+            options,
+            collection,
+            doc,
+            site,
+            route: {
+                path,
+                locale: locale ?? localeConfig.default,
+                ...(input.page === undefined ? {} : { page: input.page }),
+            },
+        });
+        const context = {
+            scopes: scopes,
+            locale: locale ?? localeConfig.default,
+            locales: {
+                default: localeConfig.default,
+                fallback: localeConfig.fallback,
+                intl: localeConfig.intl,
+            },
+            timeZone: input.timeZone ?? 'UTC',
+            mode: draft ? 'preview' : 'production',
+        };
+        return {
+            document: resolved.layout,
+            context,
+            layoutRef: resolved.layoutRef,
+            layoutSource: resolved.source,
+            currentId: id,
+            doc,
+        };
+    };
+    const tags = [
+        collectionTag(collection),
+        ...(input.id === undefined ? [] : [docTag(collection, input.id)]),
+        ...(hasSite ? [globalTag(SITE_GLOBAL)] : []),
+        'buildr:theme',
+    ].sort();
+    const entry = draft
+        ? await read()
+        : await (input.cache ?? defaultCache)(read, [
+            'buildr:document',
+            collection,
+            input.slug !== undefined ? `slug:${input.slug}` : `id:${String(input.id)}`,
+            locale ?? '',
+            String(input.depth ?? 1),
+            input.page === undefined ? '' : `page:${input.page}`,
+        ], { tags })();
+    if (entry === null)
+        return null;
+    // The tags of the document that was found, which a slug lookup could not know beforehand.
+    const found = new Set(tags);
+    found.add(docTag(collection, entry.currentId));
+    if (entry.layoutRef !== null) {
+        const at = entry.layoutRef.indexOf(':');
+        const owner = entry.layoutRef.slice(0, at);
+        const ref = entry.layoutRef.slice(at + 1);
+        found.add(owner === 'buildr-templates' ? `buildr:template:${ref}` : docTag(owner, ref));
+    }
+    return { ...entry, tags: [...found].sort() };
+}
+/** The slugs of the published documents, for `generateStaticParams`. Documents without a slug are skipped. */
+export async function listPublishedSlugs(input) {
+    const field = input.slugField ?? 'slug';
+    const configured = configuredLocales(input.payload.config);
+    const localeArgs = configured === undefined
+        ? {}
+        : {
+            locale: input.locale ?? configured.default,
+            ...(configured.fallback ? {} : { fallbackLocale: false }),
+        };
+    const result = await input.payload.find({
+        collection: input.collection,
+        where: { _status: { equals: 'published' } },
+        limit: input.limit ?? 1000,
+        pagination: false,
+        depth: 0,
+        draft: false,
+        overrideAccess: false,
+        select: { [field]: true },
+        ...localeArgs,
+    });
+    const slugs = [];
+    for (const doc of result.docs) {
+        const slug = doc[field];
+        if (typeof slug === 'string' && slug !== '' && isRecord(doc))
+            slugs.push(slug);
+    }
+    return slugs;
+}

package/dist/next/get-document.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=get-document.test.d.ts.map

package/dist/next/get-document.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-document.test.d.ts","sourceRoot":"","sources":["../../src/next/get-document.test.ts"],"names":[],"mappings":""}

package/dist/next/get-document.test.js

@@ -0,0 +1,155 @@
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest';
+import { boot, title, withChild } from '../plugin/endpoints/endpoints.test-kit.js';
+import { getBuildrDocument, listPublishedSlugs } from './index.js';
+let h;
+beforeAll(async () => {
+    h = await boot('get-document', {
+        collections: {
+            pages: { context: 'page', templates: true, path: (d) => `/${String(d['slug'])}` },
+        },
+    }, {
+        pageAccess: { read: ({ req }) => (req.user ? true : { _status: { equals: 'published' } }) },
+        globals: [
+            {
+                slug: 'site-settings',
+                access: { read: () => true },
+                fields: [{ name: 'siteName', type: 'text' }],
+            },
+        ],
+    });
+    await h.payload.updateGlobal({
+        slug: 'site-settings',
+        data: { siteName: 'Acme' },
+    });
+});
+afterAll(() => h.close());
+const create = (data, status) => h.payload.create({
+    collection: 'pages',
+    data: { ...data, _status: status },
+    draft: status === 'draft',
+});
+/** A cache that only records what it was asked to cache, and runs the read. */
+const spyCache = () => {
+    const calls = [];
+    const cache = (read, keys, options) => {
+        calls.push({ keys, tags: options.tags });
+        return read;
+    };
+    return { cache, calls };
+};
+describe('getBuildrDocument', () => {
+    it('reads a published page by slug: layout, context and tags', async () => {
+        const page = await create({ title: 'About', slug: 'about', layout: withChild(title('Hi')) }, 'published');
+        const { cache, calls } = spyCache();
+        const entry = await getBuildrDocument({
+            payload: h.payload,
+            collection: 'pages',
+            slug: 'about',
+            contextName: 'page',
+            path: (doc) => `/${String(doc['slug'])}`,
+            cache,
+        });
+        expect(entry).not.toBeNull();
+        expect(entry?.layoutSource).toBe('document');
+        expect(entry?.layoutRef).toBe(`pages:${page.id}`);
+        expect(entry?.currentId).toBe(page.id);
+        expect(entry?.context).toMatchObject({
+            mode: 'production',
+            scopes: { page: { title: 'About' }, site: { siteName: 'Acme' }, route: { path: '/about' } },
+        });
+        expect(entry?.tags).toEqual([
+            'buildr:col:pages',
+            `buildr:doc:pages:${page.id}`,
+            'buildr:global:site-settings',
+            'buildr:theme',
+        ].sort());
+        // Published reads go through the cache, keyed by document and language.
+        expect(calls).toHaveLength(1);
+        expect(calls[0]?.keys).toContain('slug:about');
+    });
+    it('exposes the page of a listing as route.params.page, keyed in the cache', async () => {
+        await create({ title: 'Blog', slug: 'blog', layout: withChild(title('Hi')) }, 'published');
+        const { cache, calls } = spyCache();
+        const entry = await getBuildrDocument({
+            payload: h.payload,
+            collection: 'pages',
+            slug: 'blog',
+            contextName: 'page',
+            page: 2,
+            cache,
+        });
+        expect(entry?.context).toMatchObject({ scopes: { route: { params: { page: 2 } } } });
+        expect(calls[0]?.keys).toContain('page:2');
+    });
+    it('reads by id and falls back to the built-in layout', async () => {
+        const page = await create({ title: 'Bare', slug: 'bare' }, 'published');
+        const entry = await getBuildrDocument({
+            payload: h.payload,
+            collection: 'pages',
+            id: page.id,
+            contextName: 'page',
+            cache: spyCache().cache,
+        });
+        expect(entry?.layoutSource).toBe('builtin');
+        expect(entry?.layoutRef).toBeNull();
+    });
+    it('does not show a draft to a visitor, and does not cache a draft read', async () => {
+        await create({ title: 'Secret', slug: 'secret' }, 'draft');
+        const { cache, calls } = spyCache();
+        const visitor = await getBuildrDocument({
+            payload: h.payload,
+            collection: 'pages',
+            slug: 'secret',
+            cache,
+        });
+        expect(visitor).toBeNull();
+        const user = { id: 1, collection: 'users' };
+        const asEditor = spyCache();
+        const draftRead = await getBuildrDocument({
+            payload: h.payload,
+            collection: 'pages',
+            slug: 'secret',
+            draft: true,
+            user,
+            cache: asEditor.cache,
+        });
+        // The test config has no auth collection, so the local API treats the user as a visitor here; what
+        // matters is that a draft read never touches the cache.
+        expect(asEditor.calls).toHaveLength(0);
+        expect(draftRead === null || draftRead.context.mode === 'preview').toBe(true);
+        expect(calls).toHaveLength(1);
+    });
+    it('answers null for a missing document and needs exactly one of slug and id', async () => {
+        expect(await getBuildrDocument({
+            payload: h.payload,
+            collection: 'pages',
+            slug: 'nope',
+            cache: spyCache().cache,
+        })).toBeNull();
+        await expect(getBuildrDocument({ payload: h.payload, collection: 'pages' })).rejects.toThrow(/exactly one/);
+        await expect(getBuildrDocument({ payload: h.payload, collection: 'pages', slug: 'a', id: 1 })).rejects.toThrow(/exactly one/);
+    });
+    it('runs the read once per cache miss (the wrapper decides)', async () => {
+        const read = vi.fn();
+        const cache = (fn, _keys, _options) => {
+            let memo;
+            read();
+            return () => {
+                memo ??= fn();
+                return memo;
+            };
+        };
+        const args = { payload: h.payload, collection: 'pages', slug: 'about', cache };
+        await getBuildrDocument(args);
+        await getBuildrDocument(args);
+        expect(read).toHaveBeenCalledTimes(2); // one wrapper per call; memoization is the cache's business
+    });
+});
+describe('listPublishedSlugs', () => {
+    it('lists published slugs only', async () => {
+        const slugs = await listPublishedSlugs({ payload: h.payload, collection: 'pages' });
+        expect(slugs).toContain('about');
+        expect(slugs).toContain('bare');
+        expect(slugs).not.toContain('secret');
+    });
+});

package/dist/next/index.d.ts

@@ -0,0 +1,9 @@
+export type { BuildrDocumentEntry, CacheRead, GetBuildrDocumentInput, ListPublishedSlugsInput, } from './get-document.ts';
+export { getBuildrDocument, listPublishedSlugs } from './get-document.ts';
+export type { GlobalHookArgs, HookArgs, Revalidate, RevalidateHooks } from './revalidate.ts';
+export { revalidateHooks } from './revalidate.ts';
+export type { SeoEntry, SeoOptions } from './seo.ts';
+export { alternatesOf, seoFromDocument } from './seo.ts';
+export type { TagInput } from './tags.ts';
+export { collectionTag, docTag, globalTag, THEME_TAG, tagsFor, templateTag, } from './tags.ts';
+//# sourceMappingURL=index.d.ts.map