@next-buildr/payload 0.0.0-stage → 2.0.1

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

@@ -0,0 +1,209 @@
+import { createEmptyDocument, s } from '@next-buildr/core';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { documentResponseSchema, publishResponseSchema, saveResponseSchema, sessionResponseSchema, } from '../../contract.js';
+import { boot, title, withChild } from './endpoints.test-kit.js';
+let h;
+beforeAll(async () => {
+    h = await boot('endpoints');
+});
+afterAll(() => h.close());
+const create = async (data = {}) => {
+    const doc = await h.payload.create({
+        collection: 'pages',
+        data: { title: 'Home', slug: 'home', ...data },
+        draft: true,
+    });
+    return Number(doc.id);
+};
+const path = (docId, suffix = '') => `/buildr/documents/pages/${docId}${suffix}`;
+const save = (docId, revision, document, autosave = false) => h.call('PUT', path(docId), { body: { document, baseRevision: revision, autosave } });
+const nodesOf = (document) => document.nodes;
+describe('authentication', () => {
+    it('answers 401 to every endpoint without a user', async () => {
+        const id = await create();
+        const anonymous = { token: null };
+        const calls = await Promise.all([
+            h.call('GET', '/buildr/session', anonymous),
+            h.call('GET', '/buildr/manifest', anonymous),
+            h.call('GET', path(id), anonymous),
+            h.call('PUT', path(id), { ...anonymous, body: {} }),
+            h.call('POST', path(id, '/publish'), { ...anonymous, body: {} }),
+        ]);
+        expect(calls.map((call) => call.status)).toEqual([401, 401, 401, 401, 401]);
+    });
+});
+describe('session and manifest', () => {
+    it('describes the user, what they may do and the limits', async () => {
+        const { status, body } = await h.call('GET', '/buildr/session');
+        expect(status).toBe(200);
+        const session = sessionResponseSchema.parse(body);
+        expect(session.user.email).toBe('editor@example.com');
+        expect(session.permissions).toEqual({
+            canEdit: true,
+            canPublish: true,
+            canUnlockTemplates: true,
+        });
+        expect(session.limits).toEqual({ maxNodes: 5000, maxBytes: 2_000_000 });
+        expect(session.publishPolicy).toBe('warn');
+    });
+    it('serves the manifest of the registry', async () => {
+        const { status, body } = await h.call('GET', '/buildr/manifest');
+        expect(status).toBe(200);
+        expect(typeof body.hash).toBe('string');
+    });
+});
+describe('GET a document', () => {
+    it('opens a new document as an empty one at revision 0', async () => {
+        const docId = await create();
+        const { status, body } = await h.call('GET', path(docId));
+        expect(status).toBe(200);
+        const doc = documentResponseSchema.parse(body);
+        expect(doc).toMatchObject({
+            ref: { collection: 'pages', id: String(docId) },
+            title: 'Home',
+            slug: 'home',
+            status: 'draft',
+            revision: 0,
+            contextRef: `pages:${docId}`,
+            previewPath: '/home',
+        });
+        expect(doc.document).toEqual(createEmptyDocument());
+        expect(doc.readOnly).toBeUndefined();
+    });
+    it('answers 404 for a collection or a document that does not exist', async () => {
+        expect((await h.call('GET', '/buildr/documents/nope/1')).status).toBe(404);
+        expect((await h.call('GET', path(99999))).status).toBe(404);
+    });
+    it('marks a document that newer code wrote as read-only, and leaves it untouched', async () => {
+        const docId = await create();
+        // Straight into the database: the hooks would (rightly) refuse to store this.
+        await h.payload.db.createVersion({
+            collectionSlug: 'pages',
+            parent: docId,
+            versionData: {
+                title: 'Newer',
+                layout: withChild(title('x'), { version: 9 }),
+                buildrRevision: 4,
+                _status: 'draft',
+            },
+            createdAt: new Date().toISOString(),
+            updatedAt: new Date(Date.now() + 1000).toISOString(),
+            autosave: false,
+            returning: false,
+        });
+        const { body } = await h.call('GET', path(docId));
+        expect(body.readOnly).toBe(true);
+        expect(body.revision).toBe(4);
+        expect(body.document.components['buildr/widget']).toBe(9);
+    });
+});
+describe('PATCH a document (rename)', () => {
+    it('renames without touching the layout or the revision', async () => {
+        const docId = await create();
+        const { status, body } = await h.call('PATCH', path(docId), { body: { title: '  About us ' } });
+        expect(status).toBe(200);
+        expect(body).toEqual({ title: 'About us' });
+        const loaded = documentResponseSchema.parse((await h.call('GET', path(docId), {})).body);
+        expect(loaded.title).toBe('About us');
+        expect(loaded.revision).toBe(0);
+    });
+    it('refuses an empty name and a request without a user', async () => {
+        const docId = await create();
+        expect((await h.call('PATCH', path(docId), { body: { title: '  ' } })).status).toBe(400);
+        expect((await h.call('PATCH', path(docId), { token: null, body: { title: 'x' } })).status).toBe(401);
+    });
+});
+describe('PUT a document (save)', () => {
+    it('saves, bumps the revision and stores the layout', async () => {
+        const docId = await create();
+        const { status, body } = await save(docId, 0, withChild(title('One')));
+        expect(status).toBe(200);
+        expect(saveResponseSchema.parse(body).revision).toBe(1);
+        const opened = documentResponseSchema.parse((await h.call('GET', path(docId))).body);
+        expect(opened.revision).toBe(1);
+        expect(nodesOf(opened.document)['child00001']?.props).toEqual(title('One'));
+    });
+    it('answers 409 with the current revision when the base is stale', async () => {
+        const docId = await create();
+        expect((await save(docId, 0, withChild(title('One')))).status).toBe(200);
+        const stale = await save(docId, 0, withChild(title('Two')));
+        expect(stale).toEqual({ status: 409, body: { currentRevision: 1 } });
+    });
+    it('answers 422 with diagnostics for an invalid document, and stores nothing', async () => {
+        const docId = await create();
+        const invalid = await save(docId, 0, withChild({ title: { kind: 'static', value: 42 } }));
+        expect(invalid.status).toBe(422);
+        expect(invalid.body.diagnostics.length).toBeGreaterThan(0);
+        expect((await save(docId, 0, { schemaVersion: 1 })).status).toBe(422);
+        expect(documentResponseSchema.parse((await h.call('GET', path(docId))).body).revision).toBe(0);
+    });
+    it('answers 400 to a body that is not the contract', async () => {
+        const docId = await create();
+        expect((await h.call('PUT', path(docId), { body: { document: {} } })).status).toBe(400);
+    });
+    it('keeps one autosave version, but every explicit save is a version', async () => {
+        const docId = await create();
+        const versions = async () => (await h.payload.countVersions({ collection: 'pages', where: { parent: { equals: docId } } }))
+            .totalDocs;
+        const before = await versions();
+        await save(docId, 0, withChild(title('a')), true);
+        await save(docId, 1, withChild(title('b')), true);
+        await save(docId, 2, withChild(title('c')), true);
+        const afterAutosaves = await versions();
+        expect(afterAutosaves - before).toBeLessThanOrEqual(1);
+        await save(docId, 3, withChild(title('d')), false);
+        await save(docId, 4, withChild(title('e')), false);
+        expect((await versions()) - afterAutosaves).toBe(2);
+    });
+    it('never loses either side of concurrent admin and builder edits', async () => {
+        const docId = await create({ title: 'Original' });
+        await save(docId, 0, withChild(title('Built')), true);
+        // The admin form still holds the layout it loaded, and saves a new title.
+        await h.payload.update({
+            collection: 'pages',
+            id: docId,
+            data: { title: 'Renamed', layout: createEmptyDocument(), buildrRevision: 0 },
+            draft: true,
+            autosave: true,
+        });
+        const opened = documentResponseSchema.parse((await h.call('GET', path(docId))).body);
+        expect(opened.title).toBe('Renamed');
+        expect(opened.revision).toBe(1);
+        expect(nodesOf(opened.document)['child00001']?.props).toEqual({ title: s('Built') });
+    });
+});
+describe('POST publish', () => {
+    it('publishes the latest draft, all of it', async () => {
+        const docId = await create({ title: 'Draft title' });
+        await save(docId, 0, withChild(title('Live')));
+        await h.payload.update({
+            collection: 'pages',
+            id: docId,
+            data: { title: 'Admin edit' },
+            draft: true,
+        });
+        const { status, body } = await h.call('POST', path(docId, '/publish'), {
+            body: { baseRevision: 1 },
+        });
+        expect(status).toBe(200);
+        expect(publishResponseSchema.parse(body)).toMatchObject({ status: 'published', revision: 1 });
+        const published = (await h.payload.findByID({
+            collection: 'pages',
+            id: docId,
+        }));
+        expect(published._status).toBe('published');
+        expect(published.title).toBe('Admin edit');
+        expect(published.layout.nodes['child00001']?.props).toEqual(title('Live'));
+        const opened = documentResponseSchema.parse((await h.call('GET', path(docId))).body);
+        expect(opened.status).toBe('published');
+        expect(opened.revision).toBe(1);
+    });
+    it('answers 409 for a stale revision, and 404 for a missing document', async () => {
+        const docId = await create();
+        await save(docId, 0, withChild(title('One')));
+        const stale = await h.call('POST', path(docId, '/publish'), { body: { baseRevision: 0 } });
+        expect(stale.status).toBe(409);
+        const missing = await h.call('POST', path(99999, '/publish'), { body: { baseRevision: 0 } });
+        expect(missing.status).toBe(404);
+    });
+});

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

@@ -0,0 +1,16 @@
+import type { Endpoint } from 'payload';
+import type { EndpointEnv } from './context.ts';
+/** The component a form is: its node type in the document. */
+export declare const FORM_TYPE = "buildr/form";
+/** The name of the honeypot input the form renders (`buildr/form`). */
+export declare const HONEYPOT_FIELD = "_hp";
+/** A submission is small; anything larger is refused before it is read. */
+export declare const MAX_BODY_BYTES: number;
+/**
+ * `POST /api/buildr/forms/:collection/:id/:nodeId`: a public form submission (docs/security.md).
+ * What the form accepts is never taken from the request: the schema is derived from the published
+ * document (or, for an inherited layout, its template) by `deriveFormSchema`. Bots are turned away
+ * by the honeypot and the rate limiter; a JSON caller gets JSON, a plain HTML form a `303` back.
+ */
+export declare const formsEndpoint: (env: EndpointEnv) => Endpoint;
+//# sourceMappingURL=forms.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"forms.d.ts","sourceRoot":"","sources":["../../../src/plugin/endpoints/forms.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAkB,MAAM,SAAS,CAAC;AAOxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAGhD,8DAA8D;AAC9D,eAAO,MAAM,SAAS,gBAAgB,CAAC;AACvC,uEAAuE;AACvE,eAAO,MAAM,cAAc,QAAQ,CAAC;AACpC,2EAA2E;AAC3E,eAAO,MAAM,cAAc,QAAY,CAAC;AA2ExC;;;;;GAKG;AACH,eAAO,MAAM,aAAa,QAAS,WAAW,KAAG,QAyH/C,CAAC"}

package/dist/plugin/endpoints/forms.js

@@ -0,0 +1,199 @@
+import { createHash } from 'node:crypto';
+import { deriveFormSchema, MAX_FORM_FIELDS } from '@next-buildr/core';
+import { resolveLayout, TEMPLATES_COLLECTION } from '../../data/resolve-layout.js';
+import { FORM_SUBMISSIONS_COLLECTION } from '../collections/form-submissions.js';
+import { isAllowedRecipient } from '../forms/notify.js';
+import { validateSubmission } from '../forms/validate.js';
+import { readLayout } from '../hooks/read-layout.js';
+import { chooseLocale } from '../locales.js';
+import { fail, json } from './respond.js';
+/** The component a form is: its node type in the document. */
+export const FORM_TYPE = 'buildr/form';
+/** The name of the honeypot input the form renders (`buildr/form`). */
+export const HONEYPOT_FIELD = '_hp';
+/** A submission is small; anything larger is refused before it is read. */
+export const MAX_BODY_BYTES = 64 * 1024;
+const MESSAGES = {
+    unknown: 'This field is not part of the form.',
+    required: 'This field is required.',
+    invalid: 'This value is not valid.',
+    'too-long': 'This value is too long.',
+};
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/** The submitted values of a JSON, urlencoded or multipart body; a file or a repeated name is kept as a value that fails validation. */
+async function readBody(req) {
+    const type = (req.headers.get('content-type') ?? '').toLowerCase();
+    const declared = Number(req.headers.get('content-length') ?? 0);
+    if (Number.isFinite(declared) && declared > MAX_BODY_BYTES) {
+        return { ok: false, response: fail(413, 'The submission is too large.') };
+    }
+    try {
+        if (type.startsWith('application/json')) {
+            const body = await req.json?.();
+            if (!isRecord(body))
+                return { ok: false, response: fail(400, 'The body must be an object.') };
+            return { ok: true, values: body, json: true };
+        }
+        if (type.startsWith('application/x-www-form-urlencoded') ||
+            type.startsWith('multipart/form-data')) {
+            const form = await req.formData?.();
+            if (form === undefined)
+                return { ok: false, response: fail(400, 'The body is not a form.') };
+            const values = {};
+            for (const name of new Set(form.keys())) {
+                const all = form.getAll(name);
+                values[name] = all.length === 1 && typeof all[0] === 'string' ? all[0] : all;
+            }
+            return { ok: true, values, json: false };
+        }
+    }
+    catch {
+        return { ok: false, response: fail(400, 'The body could not be read.') };
+    }
+    return { ok: false, response: fail(415, 'The content type must be a form or JSON.') };
+}
+/** The visitor's address, hashed with the server secret: enough to rate-limit, not to identify. */
+function ipHashOf(req) {
+    const forwarded = req.headers.get('x-forwarded-for')?.split(',')[0]?.trim();
+    const ip = forwarded || req.headers.get('x-real-ip') || 'unknown';
+    return createHash('sha256').update(`${req.payload.secret}:${ip}`).digest('hex').slice(0, 32);
+}
+/** Back to the page the form was on (same origin only, so the redirect can never leave the site). */
+function backTo(req, result) {
+    let location = '/';
+    const referer = req.headers.get('referer');
+    if (referer !== null) {
+        try {
+            const target = new URL(referer);
+            if (target.origin === new URL(req.url ?? 'http://localhost').origin) {
+                target.searchParams.set('buildr-form', result);
+                location = `${target.pathname}${target.search}`;
+            }
+        }
+        catch {
+            // An unparseable referer goes to the home page.
+        }
+    }
+    return new Response(null, { status: 303, headers: { location } });
+}
+const singleLine = (value) => String(value).replace(/\s*[\r\n]+\s*/g, ' / ');
+/**
+ * `POST /api/buildr/forms/:collection/:id/:nodeId`: a public form submission (docs/security.md).
+ * What the form accepts is never taken from the request: the schema is derived from the published
+ * document (or, for an inherited layout, its template) by `deriveFormSchema`. Bots are turned away
+ * by the honeypot and the rate limiter; a JSON caller gets JSON, a plain HTML form a `303` back.
+ */
+export const formsEndpoint = (env) => ({
+    path: '/buildr/forms/:collection/:id/:nodeId',
+    method: 'post',
+    handler: async (req) => {
+        const collection = req.routeParams?.['collection'];
+        const id = req.routeParams?.['id'];
+        const nodeId = req.routeParams?.['nodeId'];
+        if (typeof collection !== 'string' || typeof id !== 'string' || typeof nodeId !== 'string') {
+            return fail(400, 'A collection, an id and a node are required.');
+        }
+        const own = env.options.collections[collection];
+        const isTemplate = collection === TEMPLATES_COLLECTION;
+        if ((own === undefined && !isTemplate) || req.payload.collections[collection] === undefined) {
+            return fail(404, 'The form was not found.');
+        }
+        const locale = chooseLocale(req, req.searchParams?.get('locale'));
+        if (!locale.ok)
+            return locale.response;
+        const ipHash = ipHashOf(req);
+        const limited = await env.rateLimiter?.hit(`${ipHash}:${collection}:${id}:${nodeId}`);
+        if (limited !== undefined && !limited.allowed) {
+            const response = fail(429, 'Too many submissions. Try again later.');
+            response.headers.set('retry-after', String(limited.retryAfterSeconds));
+            return response;
+        }
+        const body = await readBody(req);
+        if (!body.ok)
+            return body.response;
+        const wantsJson = body.json || (req.headers.get('accept') ?? '').includes('application/json');
+        const done = (result) => (wantsJson ? undefined : backTo(req, result));
+        // A person never sees the honeypot: a bot that filled it in is answered as if it had succeeded.
+        const trap = body.values[HONEYPOT_FIELD];
+        const { [HONEYPOT_FIELD]: _trap, ...values } = body.values;
+        if (trap !== undefined && !(typeof trap === 'string' && trap === '')) {
+            return done('sent') ?? json({ ok: true });
+        }
+        if (Object.keys(values).length > MAX_FORM_FIELDS)
+            return fail(422, 'Too many fields.');
+        // Only the published state is public: a draft, or a document never published, has no form.
+        let stored;
+        try {
+            stored = (await req.payload.findByID({
+                collection,
+                id,
+                draft: false,
+                depth: 0,
+                overrideAccess: true,
+            }));
+        }
+        catch {
+            return fail(404, 'The form was not found.');
+        }
+        if (stored['_status'] !== 'published')
+            return fail(404, 'The form was not found.');
+        const layout = isTemplate
+            ? stored['layout']
+            : (await resolveLayout({
+                payload: req.payload,
+                collection,
+                doc: stored,
+                contextName: own?.context ?? collection,
+                draft: false,
+                overrideAccess: true,
+            })).layout;
+        const read = readLayout(layout, env.options);
+        const form = read.ok && Object.hasOwn(read.doc.nodes, nodeId) ? read.doc.nodes[nodeId] : undefined;
+        if (!read.ok ||
+            form === undefined ||
+            form.type !== FORM_TYPE ||
+            env.options.registry === undefined) {
+            return fail(404, 'The form was not found.');
+        }
+        const { schema } = deriveFormSchema(read.doc, env.options.registry.meta, nodeId);
+        const result = validateSubmission(schema, values);
+        if (!result.ok) {
+            if (!wantsJson)
+                return backTo(req, 'invalid');
+            const errors = {};
+            const codes = {};
+            for (const error of result.errors) {
+                errors[error.field] = MESSAGES[error.code];
+                codes[error.field] = error.code;
+            }
+            return json({ errors, codes }, 422);
+        }
+        await req.payload.create({
+            collection: FORM_SUBMISSIONS_COLLECTION,
+            data: {
+                form: { collection, documentId: id, nodeId },
+                data: result.data,
+                locale: locale.locale ?? null,
+                meta: { userAgent: (req.headers.get('user-agent') ?? '').slice(0, 300), ipHash },
+            },
+            overrideAccess: true,
+        });
+        const recipients = env.options.forms.notifyTo.filter((address) => isAllowedRecipient(address, env.options.forms.notifyAllowlist));
+        if (recipients.length > 0) {
+            try {
+                await req.payload.sendEmail({
+                    to: recipients.join(', '),
+                    subject: `New form submission (${collection}/${id})`,
+                    text: Object.entries(result.data)
+                        .map(([name, value]) => `${name}: ${singleLine(value)}`)
+                        .join('\n'),
+                });
+            }
+            catch (error) {
+                // The submission is stored; a mail server that is down does not lose it or fail the visitor.
+                req.payload.logger.error({ err: error, msg: 'buildr: the form notification was not sent' });
+            }
+        }
+        return done('sent') ?? json({ ok: true });
+    },
+});

package/dist/plugin/endpoints/forms.test.d.ts

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

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

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