@next-buildr/payload 0.0.0-stage → 2.0.1

package/dist/plugin/endpoints/access.test.d.ts.map

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

package/dist/plugin/endpoints/access.test.js

@@ -0,0 +1,91 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { boot, title, withChild } from './endpoints.test-kit.js';
+const emailOf = (req) => String(req.user.email);
+let h;
+let tokens;
+let path;
+beforeAll(async () => {
+    h = await boot('access', {
+        access: {
+            edit: ({ req }) => !emailOf(req).startsWith('viewer'),
+            publish: ({ req }) => emailOf(req).startsWith('publisher'),
+            unlockTemplates: ({ req }) => emailOf(req).startsWith('publisher'),
+        },
+    });
+    tokens = {
+        viewer: await h.login('viewer@example.com'),
+        author: await h.login('author@example.com'),
+        publisher: await h.login('publisher@example.com'),
+    };
+    const doc = await h.payload.create({
+        collection: 'pages',
+        data: { title: 'Home', slug: 'home' },
+        draft: true,
+    });
+    path = `/buildr/documents/pages/${doc.id}`;
+});
+afterAll(() => h.close());
+const layout = withChild(title('Hi'));
+const save = (token, revision) => h.call('PUT', path, {
+    token,
+    body: { document: layout, baseRevision: revision, autosave: false },
+});
+const publish = (token, revision) => h.call('POST', `${path}/publish`, { token, body: { baseRevision: revision } });
+describe('role x endpoint matrix', () => {
+    it('answers 401 without a user, whatever the endpoint', async () => {
+        const statuses = [
+            (await h.call('GET', path, { token: null })).status,
+            (await save(null, 0)).status,
+            (await publish(null, 0)).status,
+        ];
+        expect(statuses).toEqual([401, 401, 401]);
+    });
+    it('keeps a viewer out of the builder altogether', async () => {
+        expect((await h.call('GET', path, { token: tokens.viewer })).status).toBe(403);
+        expect((await save(tokens.viewer, 0)).status).toBe(403);
+        expect((await publish(tokens.viewer, 0)).status).toBe(403);
+    });
+    it('lets an author save but not publish, and a publisher do both', async () => {
+        expect((await save(tokens.author, 0)).status).toBe(200);
+        expect((await publish(tokens.author, 1)).status).toBe(403);
+        expect((await publish(tokens.publisher, 1)).status).toBe(200);
+    });
+    it('reports each role its permissions in the session', async () => {
+        const permissions = async (token) => (await h.call('GET', '/buildr/session', { token })).body.permissions;
+        expect(await permissions(tokens.viewer)).toEqual({
+            canEdit: false,
+            canPublish: false,
+            canUnlockTemplates: false,
+        });
+        expect(await permissions(tokens.author)).toEqual({
+            canEdit: true,
+            canPublish: false,
+            canUnlockTemplates: false,
+        });
+        expect(await permissions(tokens.publisher)).toEqual({
+            canEdit: true,
+            canPublish: true,
+            canUnlockTemplates: true,
+        });
+    });
+});
+describe('CSRF guards on mutating requests', () => {
+    const send = (headers, method = 'PUT') => h.call(method, method === 'PUT' ? path : `${path}/publish`, {
+        token: tokens.publisher,
+        body: method === 'PUT'
+            ? { document: layout, baseRevision: 99, autosave: false }
+            : { baseRevision: 99 },
+        headers,
+    });
+    it('refuses a foreign Origin, but accepts the own one and none', async () => {
+        expect((await send({ origin: 'https://evil.example' })).status).toBe(403);
+        expect((await send({ origin: 'https://evil.example' }, 'POST')).status).toBe(403);
+        expect((await send({ origin: 'null' })).status).toBe(403);
+        expect((await send({ origin: 'http://localhost' })).status).toBe(409);
+        expect((await send({})).status).toBe(409);
+    });
+    it('refuses a body that is not declared as JSON', async () => {
+        expect((await send({ 'content-type': 'text/plain' })).status).toBe(415);
+        expect((await send({ 'content-type': 'application/x-www-form-urlencoded' })).status).toBe(415);
+    });
+});

package/dist/plugin/endpoints/adapter-contract.test.d.ts

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

package/dist/plugin/endpoints/adapter-contract.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-contract.test.d.ts","sourceRoot":"","sources":["../../../src/plugin/endpoints/adapter-contract.test.ts"],"names":[],"mappings":""}

package/dist/plugin/endpoints/adapter-contract.test.js

@@ -0,0 +1,45 @@
+import { handleEndpoints } from 'payload';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { createPayloadAdapter } from '../../adapter/index.js';
+import { boot } from './endpoints.test-kit.js';
+let h;
+let pageId;
+beforeAll(async () => {
+    h = await boot('adapter-server');
+    const page = await h.payload.create({
+        collection: 'pages',
+        data: { title: 'Home', slug: 'home' },
+        draft: true,
+    });
+    pageId = String(page.id);
+});
+afterAll(() => h.close());
+/** The adapter's `fetch`, answered by the real endpoints (no network). */
+const serverFetch = ((input, init = {}) => handleEndpoints({
+    config: h.payload.config,
+    request: new Request(new URL(input, 'http://localhost'), {
+        ...init,
+        headers: { ...init.headers, authorization: `JWT ${h.token}` },
+    }),
+}));
+describe('the adapter against the real endpoints', () => {
+    const adapter = () => createPayloadAdapter({ baseUrl: '/api', fetch: serverFetch });
+    it('reads the session and the data schema', async () => {
+        const ref = { collection: 'pages', id: pageId };
+        expect(await adapter().getSession(ref)).toMatchObject({ canEdit: true, canPublish: true });
+        const schema = await adapter().getDataSchema(ref);
+        expect(Object.keys(schema.scopes)).toContain('page');
+    });
+    it('lists samples and builds a context', async () => {
+        const ref = { collection: 'pages', id: pageId };
+        expect(await adapter().listSamples?.(ref)).toEqual([{ id: `pages:${pageId}`, label: 'Home' }]);
+        const context = await adapter().getContext(ref);
+        expect(context.scopes['page']).toMatchObject({ title: 'Home' });
+        expect(context.mode).toBe('canvas');
+    });
+    it('rejects when the server refuses (a collection that is not configured)', async () => {
+        await expect(adapter().getDataSchema({ collection: 'users', id: '1' })).rejects.toMatchObject({
+            status: 404,
+        });
+    });
+});

package/dist/plugin/endpoints/context.d.ts

@@ -0,0 +1,65 @@
+import type { PayloadRequest } from 'payload';
+import type { SchemaOptions, SchemaSource } from '../../data/index.ts';
+import { type Action } from '../access.ts';
+import type { RateLimiter } from '../forms/rate-limit.ts';
+import type { LocaleArgs } from '../locales.ts';
+import type { ResolvedOptions } from '../options.ts';
+export interface DocumentTarget {
+    readonly collection: string;
+    readonly id: string;
+}
+/** Who may do what; decided per request. */
+export interface EndpointEnv {
+    readonly options: ResolvedOptions;
+    /** Limits form submissions (present when forms are enabled). */
+    readonly rateLimiter?: RateLimiter | undefined;
+    /** Limits the writes of API-key requests (present when `mcp.enabled`). */
+    readonly writeLimiter?: RateLimiter | undefined;
+}
+export type Guarded<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly response: Response;
+};
+/** Whether an API-key user may use the builder collection (`mcp.collections`; default: all of them). */
+export declare const mcpMayUse: (env: EndpointEnv, collection: string) => boolean;
+/**
+ * The write rate limit of API-key requests (browser sessions are not limited): the response to send
+ * instead (`429`), or `undefined`.
+ */
+export declare function writeLimit(env: EndpointEnv, req: PayloadRequest): Promise<Response | undefined>;
+/** The context of every builder write: the guard flag, and whether an API key made the request. */
+export declare const writeContext: (req: PayloadRequest) => Record<string, unknown>;
+/**
+ * The user a write is attributed to (`buildrUpdatedBy`, added with `mcp.enabled`); it lands in the
+ * document and in every version, so history shows the agent's user.
+ */
+export declare function updatedBy(env: EndpointEnv, req: PayloadRequest): Record<string, unknown>;
+/** An authenticated user and a configured collection (the `:collection` param). */
+export declare function collectionOf(env: EndpointEnv, req: PayloadRequest): Guarded<string>;
+/** An authenticated user and a configured collection with an id: what every document endpoint needs first. */
+export declare function targetOf(env: EndpointEnv, req: PayloadRequest): Guarded<DocumentTarget>;
+/** The global that becomes the `site` scope. */
+export declare const SITE_GLOBAL = "site-settings";
+/** What the schema and the context derive from: the live Payload config and the plugin names. */
+export declare function schemaEnv(env: EndpointEnv, req: PayloadRequest): {
+    source: SchemaSource;
+    options: SchemaOptions;
+};
+/** The JSON body of a request, or a `400` for anything else. */
+export declare function bodyOf(req: PayloadRequest): Promise<Guarded<unknown>>;
+/** Whether the user of `req` may `action` (see `plugin/access.ts`). */
+export declare const allowed: (env: EndpointEnv, action: Action, req: PayloadRequest) => Promise<boolean>;
+/** Loads the latest draft of the target, or the response to send instead (`404`). */
+export declare function latestOf(req: PayloadRequest, target: DocumentTarget, options?: {
+    readonly localeArgs?: LocaleArgs | undefined;
+    readonly depth?: number;
+    readonly draft?: boolean;
+    /** Only these fields are read (Payload's `select`). */
+    readonly select?: Record<string, true>;
+}): Promise<Guarded<Record<string, unknown>>>;
+/** The stored revision of a document: 0 until the builder saved it. */
+export declare const revisionOf: (doc: Record<string, unknown>) => number;
+//# sourceMappingURL=context.d.ts.map

package/dist/plugin/endpoints/context.d.ts.map

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

package/dist/plugin/endpoints/context.js

@@ -0,0 +1,113 @@
+import { allowed as isAllowed, isApiKeyRequest } from '../access.js';
+import { BUILDR_WRITE } from '../write-guard.js';
+import { fail, notFound, unauthorized } from './respond.js';
+/** Whether an API-key user may use the builder collection (`mcp.collections`; default: all of them). */
+export const mcpMayUse = (env, collection) => env.options.collections[collection] !== undefined &&
+    (env.options.mcp.collections === undefined || env.options.mcp.collections.includes(collection));
+/**
+ * The write rate limit of API-key requests (browser sessions are not limited): the response to send
+ * instead (`429`), or `undefined`.
+ */
+export async function writeLimit(env, req) {
+    if (!isApiKeyRequest(req) || env.writeLimiter === undefined)
+        return undefined;
+    const user = req.user;
+    const result = await env.writeLimiter.hit(`${user.collection ?? ''}:${String(user.id)}`);
+    if (result.allowed)
+        return undefined;
+    const response = fail(429, 'Too many writes. Try again later.');
+    response.headers.set('retry-after', String(result.retryAfterSeconds));
+    return response;
+}
+/** The context of every builder write: the guard flag, and whether an API key made the request. */
+export const writeContext = (req) => ({
+    [BUILDR_WRITE]: true,
+    ...(isApiKeyRequest(req) ? { buildrApiKey: true } : {}),
+});
+/**
+ * The user a write is attributed to (`buildrUpdatedBy`, added with `mcp.enabled`); it lands in the
+ * document and in every version, so history shows the agent's user.
+ */
+export function updatedBy(env, req) {
+    const user = req.user;
+    if (!env.options.mcp.enabled || user?.id === undefined || user.collection === undefined) {
+        return {};
+    }
+    return { buildrUpdatedBy: { relationTo: user.collection, value: user.id } };
+}
+/** An authenticated user and a configured collection (the `:collection` param). */
+export function collectionOf(env, req) {
+    if (req.user === null || req.user === undefined)
+        return { ok: false, response: unauthorized() };
+    const collection = req.routeParams?.['collection'];
+    if (typeof collection !== 'string' || collection === '') {
+        return { ok: false, response: fail(400, 'A collection is required.') };
+    }
+    if (env.options.collections[collection] === undefined) {
+        return { ok: false, response: notFound(`The collection "${collection}"`) };
+    }
+    if (isApiKeyRequest(req) && !mcpMayUse(env, collection)) {
+        return { ok: false, response: fail(403, `Agents may not use the collection "${collection}".`) };
+    }
+    return { ok: true, value: collection };
+}
+/** An authenticated user and a configured collection with an id: what every document endpoint needs first. */
+export function targetOf(env, req) {
+    const collection = collectionOf(env, req);
+    if (!collection.ok)
+        return collection;
+    const id = req.routeParams?.['id'];
+    if (typeof id !== 'string' || id === '') {
+        return { ok: false, response: fail(400, 'A collection and an id are required.') };
+    }
+    return { ok: true, value: { collection: collection.value, id } };
+}
+/** The global that becomes the `site` scope. */
+export const SITE_GLOBAL = 'site-settings';
+/** What the schema and the context derive from: the live Payload config and the plugin names. */
+export function schemaEnv(env, req) {
+    const config = req.payload.config;
+    const contextNames = {};
+    for (const [slug, own] of Object.entries(env.options.collections)) {
+        contextNames[slug] = own.context;
+    }
+    return {
+        source: {
+            collections: config.collections,
+            globals: (config.globals ?? []),
+        },
+        options: { contextNames, siteGlobal: SITE_GLOBAL },
+    };
+}
+/** The JSON body of a request, or a `400` for anything else. */
+export async function bodyOf(req) {
+    try {
+        return { ok: true, value: await req.json?.() };
+    }
+    catch {
+        return { ok: false, response: fail(400, 'The request body must be JSON.') };
+    }
+}
+/** Whether the user of `req` may `action` (see `plugin/access.ts`). */
+export const allowed = (env, action, req) => isAllowed(env.options, action, req);
+/** Loads the latest draft of the target, or the response to send instead (`404`). */
+export async function latestOf(req, target, options = {}) {
+    try {
+        const doc = await req.payload.findByID({
+            collection: target.collection,
+            id: target.id,
+            draft: options.draft ?? true,
+            depth: options.depth ?? 0,
+            ...(options.select === undefined ? {} : { select: options.select }),
+            req,
+            overrideAccess: false,
+            ...options.localeArgs,
+        });
+        return { ok: true, value: doc };
+    }
+    catch {
+        return { ok: false, response: notFound(`The document "${target.collection}/${target.id}"`) };
+    }
+}
+/** The stored revision of a document: 0 until the builder saved it. */
+export const revisionOf = (doc) => typeof doc['buildrRevision'] === 'number' ? doc['buildrRevision'] : 0;

package/dist/plugin/endpoints/data-context.d.ts

@@ -0,0 +1,8 @@
+import type { Endpoint } from 'payload';
+import { type EndpointEnv } from './context.ts';
+/**
+ * `GET /api/buildr/data/context?collection&id&draft&locale`: the scopes the canvas binds against,
+ * built with the access of the user who asks (`overrideAccess: false`), relations and uploads populated.
+ */
+export declare const dataContextEndpoint: (env: EndpointEnv) => Endpoint;
+//# sourceMappingURL=data-context.d.ts.map

package/dist/plugin/endpoints/data-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-context.d.ts","sourceRoot":"","sources":["../../../src/plugin/endpoints/data-context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAIxC,OAAO,EAAW,KAAK,WAAW,EAAoC,MAAM,cAAc,CAAC;AAG3F;;;GAGG;AACH,eAAO,MAAM,mBAAmB,QAAS,WAAW,KAAG,QAwDrD,CAAC"}

package/dist/plugin/endpoints/data-context.js

@@ -0,0 +1,63 @@
+import { dataContextQuerySchema, dataContextResponseSchema } from '../../contract.js';
+import { buildContext } from '../../data/index.js';
+import { chooseLocale } from '../locales.js';
+import { allowed, latestOf, SITE_GLOBAL, schemaEnv } from './context.js';
+import { fail, json, notFound, unauthorized } from './respond.js';
+/**
+ * `GET /api/buildr/data/context?collection&id&draft&locale`: the scopes the canvas binds against,
+ * built with the access of the user who asks (`overrideAccess: false`), relations and uploads populated.
+ */
+export const dataContextEndpoint = (env) => ({
+    path: '/buildr/data/context',
+    method: 'get',
+    handler: async (req) => {
+        if (req.user === null || req.user === undefined)
+            return unauthorized();
+        if (!(await allowed(env, 'edit', req)))
+            return fail(403, 'You may not edit with the builder.');
+        const parsed = dataContextQuerySchema.safeParse(Object.fromEntries(req.searchParams?.entries() ?? []));
+        if (!parsed.success)
+            return fail(400, 'The query does not match the contract.');
+        const { collection, id } = parsed.data;
+        const locale = chooseLocale(req, parsed.data.locale);
+        if (!locale.ok)
+            return locale.response;
+        const own = env.options.collections[collection];
+        if (own === undefined)
+            return notFound(`The collection "${collection}"`);
+        const found = await latestOf(req, { collection, id }, {
+            depth: Math.max(1, own.depth),
+            draft: parsed.data.draft !== '0',
+            localeArgs: locale.args,
+        });
+        if (!found.ok)
+            return found.response;
+        const { source, options } = schemaEnv(env, req);
+        let site;
+        if (source.globals?.some((global) => global.slug === SITE_GLOBAL) === true) {
+            try {
+                site = (await req.payload.findGlobal({
+                    slug: SITE_GLOBAL,
+                    depth: 1,
+                    req,
+                    overrideAccess: false,
+                    ...locale.args,
+                }));
+            }
+            catch {
+                site = undefined; // the user may not read it: the scope is then null, not an error
+            }
+        }
+        const path = own.path?.(found.value) ?? '';
+        return json(dataContextResponseSchema.parse({
+            scopes: buildContext({
+                source,
+                options,
+                collection,
+                doc: found.value,
+                site,
+                route: { path, locale: locale.locale ?? req.locale ?? '' },
+            }),
+        }));
+    },
+});

package/dist/plugin/endpoints/data-endpoints.test.d.ts

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

package/dist/plugin/endpoints/data-endpoints.test.d.ts.map

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

package/dist/plugin/endpoints/data-endpoints.test.js

@@ -0,0 +1,125 @@
+import { dataSchemaSchema } from '@next-buildr/core';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { dataContextResponseSchema, samplesResponseSchema } from '../../contract.js';
+import { boot } from './endpoints.test-kit.js';
+let h;
+let authorId;
+let pageId;
+beforeAll(async () => {
+    h = await boot('data-endpoints', {
+        collections: {
+            pages: { context: 'page', depth: 1, path: (doc) => `/${String(doc['slug'])}` },
+        },
+    }, {
+        pageFields: [
+            { name: 'author', type: 'relationship', relationTo: 'authors' },
+            { name: 'owner', type: 'relationship', relationTo: 'users' },
+            { name: 'internalNote', type: 'text', hidden: true },
+            { name: 'publishedOn', type: 'date' },
+        ],
+        collections: [
+            {
+                slug: 'authors',
+                fields: [
+                    { name: 'name', type: 'text' },
+                    { name: 'apiKey', type: 'text' },
+                ],
+            },
+        ],
+        globals: [
+            {
+                slug: 'site-settings',
+                fields: [
+                    { name: 'siteName', type: 'text' },
+                    { name: 'token', type: 'text' },
+                ],
+            },
+        ],
+    });
+    const author = await h.payload.create({
+        collection: 'authors',
+        data: { name: 'Ada', apiKey: 'secret-key' },
+    });
+    authorId = Number(author.id);
+    await h.payload.updateGlobal({
+        slug: 'site-settings',
+        data: { siteName: 'Buildr', token: 'global-secret' },
+    });
+    const users = await h.payload.find({ collection: 'users' });
+    const page = await h.payload.create({
+        collection: 'pages',
+        data: {
+            title: 'Home',
+            slug: 'home',
+            author: authorId,
+            owner: users.docs[0]?.id,
+            internalNote: 'private',
+            publishedOn: '2026-03-04T00:00:00.000Z',
+        },
+        draft: true,
+    });
+    pageId = Number(page.id);
+});
+afterAll(() => h.close());
+describe('GET /buildr/data-schema/:collection', () => {
+    it('describes the collection and never the users', async () => {
+        const { status, body } = await h.call('GET', '/buildr/data-schema/pages');
+        expect(status).toBe(200);
+        const schema = dataSchemaSchema.parse(body);
+        expect(Object.keys(schema.scopes).sort()).toEqual(['page', 'route', 'site']);
+        expect(Object.keys(schema.entities)).toEqual(['authors']);
+        const json = JSON.stringify(body);
+        for (const leaked of ['users', 'email', 'apiKey', 'token', 'internalNote', 'owner', 'layout']) {
+            expect(json).not.toContain(`"${leaked}"`);
+        }
+        expect(json).toContain('"publishedOn"');
+    });
+    it('is for the builder only: 401, 404', async () => {
+        expect((await h.call('GET', '/buildr/data-schema/pages', { token: null })).status).toBe(401);
+        expect((await h.call('GET', '/buildr/data-schema/authors')).status).toBe(404);
+    });
+});
+describe('GET /buildr/data/context', () => {
+    it('builds the scopes of a document, its author included', async () => {
+        const { status, body } = await h.call('GET', `/buildr/data/context?collection=pages&id=${pageId}&locale=pl`);
+        expect(status).toBe(200);
+        const { scopes } = dataContextResponseSchema.parse(body);
+        expect(scopes['page']).toMatchObject({
+            id: String(pageId),
+            title: 'Home',
+            slug: 'home',
+            publishedOn: '2026-03-04T00:00:00.000Z',
+            author: { id: String(authorId), name: 'Ada' },
+        });
+        expect(scopes['site']).toMatchObject({ siteName: 'Buildr' });
+        expect(scopes['route']).toEqual({ path: '/home', locale: 'pl', params: { page: null } });
+        const json = JSON.stringify(scopes);
+        for (const leaked of ['secret-key', 'global-secret', 'private', 'editor@example.com']) {
+            expect(json).not.toContain(leaked);
+        }
+    });
+    it('answers 400, 401 and 404 to a bad, anonymous or unknown request', async () => {
+        expect((await h.call('GET', '/buildr/data/context?collection=pages')).status).toBe(400);
+        expect((await h.call('GET', `/buildr/data/context?collection=pages&id=${pageId}`, { token: null }))
+            .status).toBe(401);
+        expect((await h.call('GET', '/buildr/data/context?collection=pages&id=99999')).status).toBe(404);
+        expect((await h.call('GET', `/buildr/data/context?collection=users&id=${pageId}`)).status).toBe(404);
+    });
+});
+describe('GET /buildr/samples/:collection', () => {
+    it('lists documents by their title and filters by search', async () => {
+        await h.payload.create({
+            collection: 'pages',
+            data: { title: 'About us', slug: 'about' },
+            draft: true,
+        });
+        const all = samplesResponseSchema.parse((await h.call('GET', '/buildr/samples/pages')).body);
+        expect(all.items.map((item) => item.title).sort()).toEqual(['About us', 'Home']);
+        const found = samplesResponseSchema.parse((await h.call('GET', '/buildr/samples/pages?search=about')).body);
+        expect(found.items.map((item) => item.title)).toEqual(['About us']);
+    });
+    it('answers 401 and 404', async () => {
+        expect((await h.call('GET', '/buildr/samples/pages', { token: null })).status).toBe(401);
+        expect((await h.call('GET', '/buildr/samples/users')).status).toBe(404);
+    });
+});

package/dist/plugin/endpoints/data-query.test.d.ts

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

package/dist/plugin/endpoints/data-query.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-query.test.d.ts","sourceRoot":"","sources":["../../../src/plugin/endpoints/data-query.test.ts"],"names":[],"mappings":""}

package/dist/plugin/endpoints/data-query.test.js

@@ -0,0 +1,96 @@
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { dataMediaResponseSchema, dataQueryResponseSchema } from '../../contract.js';
+import { boot } from './endpoints.test-kit.js';
+let h;
+beforeAll(async () => {
+    h = await boot('data-query', {
+        queryable: {
+            articles: { fields: ['title', 'views'], sort: ['views'] },
+            pages: { fields: ['title'], sort: [] },
+        },
+        media: { collection: 'assets' },
+    }, {
+        collections: [
+            {
+                slug: 'articles',
+                access: { read: () => true },
+                fields: [
+                    { name: 'title', type: 'text', required: true },
+                    { name: 'views', type: 'number', required: true },
+                    { name: 'secret', type: 'text' },
+                ],
+            },
+            {
+                slug: 'assets',
+                fields: [
+                    { name: 'url', type: 'text' },
+                    { name: 'alt', type: 'text' },
+                ],
+            },
+        ],
+    });
+    for (const [title, views] of [
+        ['One', 1],
+        ['Two', 2],
+        ['Three', 3],
+    ]) {
+        await h.payload.create({
+            collection: 'articles',
+            data: { title, views, secret: 'hidden' },
+        });
+    }
+    await h.payload.create({
+        collection: 'assets',
+        data: { url: 'https://cdn.test/a.png', alt: 'A' },
+    });
+});
+afterAll(() => h.close());
+const query = (spec, init = {}) => h.call('POST', '/buildr/data/query', { body: { spec }, ...init });
+const base = { source: 'articles', limit: 10, page: 1 };
+describe('POST /buildr/data/query', () => {
+    it('answers an allowlisted query with the shared QueryResult', async () => {
+        const { status, body } = await query({
+            ...base,
+            where: { field: 'views', op: 'gte', value: 2 },
+            sort: [{ field: 'views', dir: 'desc' }],
+        });
+        expect(status).toBe(200);
+        const result = dataQueryResponseSchema.parse(body);
+        expect(result.total).toBe(2);
+        expect(result.items.map((item) => item.title)).toEqual(['Three', 'Two']);
+        expect(JSON.stringify(body)).not.toContain('hidden');
+    });
+    it('refuses what was not allowlisted: 422', async () => {
+        expect((await query({ ...base, where: { field: 'secret', op: 'eq', value: 'x' } })).status).toBe(422);
+        expect((await query({ ...base, source: 'users' })).status).toBe(422);
+        expect((await query({ ...base, sort: [{ field: 'title', dir: 'asc' }] })).status).toBe(422);
+    });
+    it('validates the request and the caller: 400, 401, 403, 415', async () => {
+        expect((await query({ source: 'articles' })).status).toBe(400);
+        expect((await query(base, { token: null })).status).toBe(401);
+        const viewer = await h.login('viewer@example.com');
+        expect((await query(base, { token: viewer })).status).toBeLessThan(500);
+        const noJson = await h.call('POST', '/buildr/data/query', {
+            body: { spec: base },
+            headers: { 'content-type': 'text/plain' },
+        });
+        expect(noJson.status).toBe(415);
+    });
+});
+describe('POST /buildr/data/media', () => {
+    it('returns the assets by id and leaves unknown ids out', async () => {
+        const found = await h.payload.find({ collection: 'assets' });
+        const id = String(found.docs[0].id);
+        const { status, body } = await h.call('POST', '/buildr/data/media', {
+            body: { ids: [id, '9999'] },
+        });
+        expect(status).toBe(200);
+        const assets = dataMediaResponseSchema.parse(body);
+        expect(Object.keys(assets)).toEqual([id]);
+        expect(assets[id]).toMatchObject({ url: 'https://cdn.test/a.png', alt: 'A' });
+    });
+    it('is for the builder only, and validates ids', async () => {
+        expect((await h.call('POST', '/buildr/data/media', { body: { ids: [] }, token: null })).status).toBe(401);
+        expect((await h.call('POST', '/buildr/data/media', { body: { ids: 'x' } })).status).toBe(400);
+    });
+});

package/dist/plugin/endpoints/data-schema.d.ts

@@ -0,0 +1,5 @@
+import type { Endpoint } from 'payload';
+import { type EndpointEnv } from './context.ts';
+/** `GET /api/buildr/data-schema/:collection`: what the bindings of this collection's documents can reach. */
+export declare const dataSchemaEndpoint: (env: EndpointEnv) => Endpoint;
+//# sourceMappingURL=data-schema.d.ts.map

package/dist/plugin/endpoints/data-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-schema.d.ts","sourceRoot":"","sources":["../../../src/plugin/endpoints/data-schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAGxC,OAAO,EAAyB,KAAK,WAAW,EAAa,MAAM,cAAc,CAAC;AAGlF,6GAA6G;AAC7G,eAAO,MAAM,kBAAkB,QAAS,WAAW,KAAG,QAYpD,CAAC"}