@next-buildr/payload 0.0.0-stage → 2.0.1

package/dist/adapter/adapter.test.d.ts

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

package/dist/adapter/adapter.test.d.ts.map

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

package/dist/adapter/adapter.test.js

@@ -0,0 +1,282 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { createEmptyDocument } from '@next-buildr/core';
+import { describe, expect, it } from 'vitest';
+import { createPayloadAdapter, createPayloadCanvasDataSource } from './index.js';
+/** A `fetch` that answers from `routes` (`"GET /path"`), recording what it was asked. */
+function fakeFetch(routes) {
+    const calls = [];
+    const fetch = (async (input, init = {}) => {
+        const url = new URL(input, 'http://site.test');
+        const method = init.method ?? 'GET';
+        calls.push({
+            method,
+            url,
+            body: typeof init.body === 'string'
+                ? JSON.parse(init.body)
+                : init.body instanceof FormData
+                    ? init.body
+                    : undefined,
+            headers: (init.headers ?? {}),
+        });
+        const route = routes[`${method} ${url.pathname}`];
+        if (route === undefined)
+            throw new Error(`unexpected ${method} ${url.pathname}`);
+        const answer = route();
+        if (answer instanceof Error)
+            throw answer;
+        return new Response(answer.body === undefined ? '' : JSON.stringify(answer.body), {
+            status: answer.status,
+        });
+    });
+    return { fetch, calls };
+}
+const REF = { collection: 'pages', id: 7 };
+const doc = createEmptyDocument();
+const documentBody = {
+    ref: { collection: 'pages', id: 7 },
+    title: 'Home',
+    slug: 'home',
+    status: 'draft',
+    updatedAt: '2026-01-01T00:00:00.000Z',
+    revision: 3,
+    document: doc,
+    contextRef: 'pages:7',
+    previewPath: '/home',
+    layoutSource: 'document',
+    layoutRef: 'pages:1',
+};
+describe('createPayloadAdapter', () => {
+    it('reads the session, with the languages of the site', async () => {
+        const { fetch, calls } = fakeFetch({
+            'GET /api/buildr/session': () => ({
+                status: 200,
+                body: {
+                    user: { id: 5 },
+                    permissions: { canEdit: true, canPublish: false, canUnlockTemplates: false },
+                    limits: { maxNodes: 10, maxBytes: 10 },
+                    locales: {
+                        locales: ['pl', 'en'],
+                        default: 'pl',
+                        fallback: true,
+                        intl: { pl: 'Polski', en: 'English' },
+                    },
+                },
+            }),
+        });
+        const adapter = createPayloadAdapter({ baseUrl: '/api/', fetch });
+        expect(await adapter.getSession(REF)).toEqual({
+            userId: '5',
+            canEdit: true,
+            canPublish: false,
+            locales: {
+                locales: ['pl', 'en'],
+                default: 'pl',
+                fallback: true,
+                intl: { pl: 'Polski', en: 'English' },
+            },
+        });
+        await adapter.getSession(REF);
+        expect(calls).toHaveLength(1);
+        expect(calls[0]?.url.pathname).toBe('/api/buildr/session');
+    });
+    it('loads and validates a document; a broken one rejects', async () => {
+        const good = fakeFetch({
+            'GET /api/buildr/documents/pages/7': () => ({ status: 200, body: documentBody }),
+        });
+        const loaded = await createPayloadAdapter({ baseUrl: '/api', fetch: good.fetch }).load(REF);
+        expect(loaded).toMatchObject({ title: 'Home', slug: 'home', status: 'draft', revision: 3 });
+        expect(good.calls[0]?.url.searchParams.get('draft')).toBe('1');
+        const bad = fakeFetch({
+            'GET /api/buildr/documents/pages/7': () => ({
+                status: 200,
+                body: { ...documentBody, document: { nope: true } },
+            }),
+        });
+        await expect(createPayloadAdapter({ baseUrl: '/api', fetch: bad.fetch }).load(REF)).rejects.toThrow(/not valid/);
+    });
+    it('maps 409 and 422 of a save onto results, and everything else onto a rejection', async () => {
+        let answer = {
+            status: 200,
+            body: { revision: 4, updatedAt: 'now' },
+        };
+        const { fetch, calls } = fakeFetch({ 'PUT /api/buildr/documents/pages/7': () => answer });
+        const adapter = createPayloadAdapter({ baseUrl: '/api', fetch });
+        const request = { document: doc, baseRevision: 3, autosave: true };
+        expect(await adapter.save(REF, request)).toEqual({ ok: true, revision: 4, updatedAt: 'now' });
+        expect(calls[0]?.body).toEqual(request);
+        expect(calls[0]?.headers['content-type']).toBe('application/json');
+        answer = { status: 409, body: { currentRevision: 9 } };
+        expect(await adapter.save(REF, request)).toEqual({
+            ok: false,
+            kind: 'conflict',
+            currentRevision: 9,
+        });
+        const diagnostics = [{ code: 'x', message: 'bad', severity: 'error' }];
+        answer = { status: 422, body: { diagnostics } };
+        expect(await adapter.save(REF, request)).toEqual({ ok: false, kind: 'invalid', diagnostics });
+        for (const status of [401, 403, 404, 500]) {
+            answer = { status, body: { error: 'nope' } };
+            await expect(adapter.save(REF, request)).rejects.toMatchObject({ status, message: 'nope' });
+        }
+        answer = { status: 200, body: { unexpected: true } };
+        await expect(adapter.save(REF, request)).rejects.toThrow(/contract/);
+    });
+    it('rejects when there is no network', async () => {
+        const { fetch } = fakeFetch({
+            'PUT /api/buildr/documents/pages/7': () => new TypeError('offline'),
+        });
+        await expect(createPayloadAdapter({ baseUrl: '/api', fetch }).save(REF, {
+            document: doc,
+            baseRevision: 0,
+            autosave: false,
+        })).rejects.toMatchObject({ name: 'AdapterError', message: 'offline' });
+    });
+    it('reads only the revision, with who saved it', async () => {
+        const { fetch, calls } = fakeFetch({
+            'GET /api/buildr/documents/pages/7/revision': () => ({
+                status: 200,
+                body: { revision: 4, updatedAt: 'u', updatedBy: 'agent@example.com' },
+            }),
+        });
+        expect(await createPayloadAdapter({ baseUrl: '/api', fetch }).getRevision?.(REF)).toEqual({
+            revision: 4,
+            updatedAt: 'u',
+            updatedBy: 'agent@example.com',
+        });
+        expect(calls).toHaveLength(1);
+    });
+    it('publishes with the same result mapping', async () => {
+        const { fetch } = fakeFetch({
+            'POST /api/buildr/documents/pages/7/publish': () => ({
+                status: 200,
+                body: { status: 'published', publishedAt: 'p', revision: 5, updatedAt: 'u' },
+            }),
+        });
+        expect(await createPayloadAdapter({ baseUrl: '/api', fetch }).publish(REF, { baseRevision: 4 })).toEqual({
+            ok: true,
+            revision: 5,
+            updatedAt: 'u',
+        });
+    });
+    it('builds the data context from the sample, the language and the session', async () => {
+        const { fetch, calls } = fakeFetch({
+            'GET /api/buildr/session': () => ({
+                status: 200,
+                body: {
+                    user: { id: 1 },
+                    permissions: { canEdit: true, canPublish: true, canUnlockTemplates: true },
+                    limits: { maxNodes: 1, maxBytes: 1 },
+                    locales: {
+                        locales: ['pl', 'en'],
+                        default: 'pl',
+                        fallback: false,
+                        intl: { pl: 'Polski', en: 'English' },
+                    },
+                },
+            }),
+            'GET /api/buildr/data/context': () => ({
+                status: 200,
+                body: { scopes: { page: { title: 'T' } } },
+            }),
+        });
+        const adapter = createPayloadAdapter({ baseUrl: '/api', fetch, timeZone: 'Europe/Warsaw' });
+        const context = await adapter.getContext(REF, { sampleId: '12' });
+        expect(context).toMatchObject({
+            scopes: { page: { title: 'T' } },
+            locale: 'pl',
+            timeZone: 'Europe/Warsaw',
+            mode: 'canvas',
+            locales: { default: 'pl', fallback: false },
+        });
+        const query = calls.at(-1)?.url.searchParams;
+        expect(query?.get('id')).toBe('12');
+        expect(query?.get('collection')).toBe('pages');
+        await adapter.getContext(REF, { sampleId: 'posts:5' });
+        const qualified = calls.at(-1)?.url.searchParams;
+        expect(qualified?.get('collection')).toBe('posts');
+        expect(qualified?.get('id')).toBe('5');
+        expect(query?.get('locale')).toBe('pl');
+    });
+    it('searches media with a cursor and a type, and uploads with the alt', async () => {
+        const asset = { id: 'm1', url: '/m1.png', mimeType: 'image/png', alt: 'One' };
+        const { fetch, calls } = fakeFetch({
+            'GET /api/buildr/media': () => ({
+                status: 200,
+                body: { items: [asset], page: 2, totalPages: 3 },
+            }),
+            'POST /api/buildr/media': () => ({ status: 201, body: asset }),
+        });
+        const adapter = createPayloadAdapter({ baseUrl: '/api', fetch });
+        const found = await adapter.media.search({
+            text: 'cat',
+            cursor: '2',
+            mimeTypes: ['image/png', 'image/jpeg'],
+        });
+        expect(found).toEqual({ items: [asset], nextCursor: '3' });
+        const query = calls[0]?.url.searchParams;
+        expect([query?.get('search'), query?.get('type'), query?.get('page')]).toEqual([
+            'cat',
+            'image',
+            '2',
+        ]);
+        const uploaded = await adapter.media.upload?.(new File(['x'], 'a.png', { type: 'image/png' }), 'One');
+        expect(uploaded).toEqual(asset);
+        const form = calls[1]?.body;
+        expect(form.get('alt')).toBe('One');
+        expect(form.get('file').name).toBe('a.png');
+        expect(calls[1]?.headers['content-type']).toBeUndefined();
+    });
+    it('lists samples, and links to the preview and the admin', async () => {
+        const { fetch } = fakeFetch({
+            'GET /api/buildr/samples/pages': () => ({
+                status: 200,
+                body: { items: [{ id: '1', title: 'A' }] },
+            }),
+        });
+        const adapter = createPayloadAdapter({ baseUrl: '/api', fetch });
+        expect(await adapter.listSamples?.(REF)).toEqual([{ id: 'pages:1', label: 'A' }]);
+        expect(adapter.previewUrl(REF, { draft: true })).toBe('/buildr/preview?collection=pages&id=7&draft=1');
+        expect(adapter.previewUrl(REF)).toBe('/buildr/preview?collection=pages&id=7');
+        expect(adapter.cmsUrl?.(REF)).toBe('/admin/collections/pages/7');
+    });
+});
+describe('createPayloadCanvasDataSource', () => {
+    const spec = { source: 'posts', limit: 5, page: 1 };
+    const ctx = { locale: 'en', mode: 'canvas' };
+    it('runs queries and media through the builder API', async () => {
+        const result = { items: [{ id: '1' }], total: 1, page: 1, totalPages: 1 };
+        const { fetch, calls } = fakeFetch({
+            'POST /api/buildr/data/query': () => ({ status: 200, body: result }),
+            'POST /api/buildr/data/media': () => ({
+                status: 200,
+                body: { m1: { id: 'm1', url: '/m1.png', mimeType: 'image/png' } },
+            }),
+        });
+        const source = createPayloadCanvasDataSource({ baseUrl: '/api', fetch });
+        expect(await source.query(spec, ctx)).toEqual(result);
+        expect(calls[0]?.body).toEqual({ spec, locale: 'en' });
+        expect(Object.keys(await source.getMedia(['m1', 'm1'], ctx))).toEqual(['m1']);
+        expect(calls[1]?.body).toEqual({ ids: ['m1'], locale: 'en' });
+        expect(await source.getMedia([], ctx)).toEqual({});
+        expect(calls).toHaveLength(2);
+    });
+    it('rejects with the reason the server gave', async () => {
+        const { fetch } = fakeFetch({
+            'POST /api/buildr/data/query': () => ({
+                status: 422,
+                body: { error: 'The collection "x" cannot be queried.' },
+            }),
+        });
+        await expect(createPayloadCanvasDataSource({ baseUrl: '/api', fetch }).query(spec, ctx)).rejects.toThrow(/cannot be queried/);
+    });
+});
+describe('the adapter boundary', () => {
+    it('never imports payload, @payloadcms or next', () => {
+        const dir = import.meta.dirname;
+        const forbidden = /from\s+['"](payload|@payloadcms\/[^'"]*|next|next\/[^'"]*|@next-buildr\/next)['"]/;
+        for (const file of readdirSync(dir).filter((name) => name.endsWith('.ts') && !name.endsWith('.test.ts'))) {
+            expect(readFileSync(join(dir, file), 'utf8'), file).not.toMatch(forbidden);
+        }
+    });
+});

package/dist/adapter/canvas-data-source.d.ts

@@ -0,0 +1,9 @@
+import type { DataSource } from '@next-buildr/core';
+import { type HttpOptions } from './http.ts';
+/**
+ * The `DataSource` of the canvas: queries and media go to the builder API, which answers with the
+ * access of the editing user (drafts included). A refused query (not allowlisted, too broad) rejects
+ * with an `AdapterError` carrying the server's reason.
+ */
+export declare function createPayloadCanvasDataSource(options: HttpOptions): DataSource;
+//# sourceMappingURL=canvas-data-source.d.ts.map

package/dist/adapter/canvas-data-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canvas-data-source.d.ts","sourceRoot":"","sources":["../../src/adapter/canvas-data-source.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAOpD,OAAO,EAA0B,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AAErE;;;;GAIG;AACH,wBAAgB,6BAA6B,CAAC,OAAO,EAAE,WAAW,GAAG,UAAU,CAe9E"}

package/dist/adapter/canvas-data-source.js

@@ -0,0 +1,24 @@
+import { dataMediaResponseSchema, dataQueryResponseSchema, } from '../contract.js';
+import { createHttp, expectBody } from './http.js';
+/**
+ * The `DataSource` of the canvas: queries and media go to the builder API, which answers with the
+ * access of the editing user (drafts included). A refused query (not allowlisted, too broad) rejects
+ * with an `AdapterError` carrying the server's reason.
+ */
+export function createPayloadCanvasDataSource(options) {
+    const http = createHttp(options);
+    return {
+        async query(spec, ctx) {
+            const body = { spec, locale: ctx.locale };
+            const reply = await http.send('POST', '/buildr/data/query', { body });
+            return expectBody(reply, dataQueryResponseSchema);
+        },
+        async getMedia(ids, ctx) {
+            if (ids.length === 0)
+                return {};
+            const body = { ids: [...new Set(ids)], locale: ctx.locale };
+            const reply = await http.send('POST', '/buildr/data/media', { body });
+            return expectBody(reply, dataMediaResponseSchema);
+        },
+    };
+}

package/dist/adapter/document-adapter.d.ts

@@ -0,0 +1,20 @@
+import type { DocumentAdapter } from '@next-buildr/editor';
+import { type HttpOptions } from './http.ts';
+export interface PayloadAdapterOptions extends HttpOptions {
+    /** The language the editor is showing now; defaults to the site's default language. */
+    readonly locale?: (() => string | undefined) | undefined;
+    /** The IANA time zone of the site's dates (default: the browser's). */
+    readonly timeZone?: string | undefined;
+    /** The route the site uses to open a draft (`routes.preview` of the plugin; default `/buildr/preview`). */
+    readonly previewRoute?: string | undefined;
+    /** Payload's admin route (default `/admin`); `cmsUrl` links into it. */
+    readonly adminRoute?: string | undefined;
+}
+/**
+ * The `DocumentAdapter` of the editor (docs/editor.md#persistence-pb-087) over the builder API of
+ * the Payload plugin. Responses are checked against the contract; a document is parsed with core's
+ * `parseDocument`. A refused save (`409`, `422`) is a result; anything the adapter could not tell
+ * (no network, `5xx`, `401`, `403`, `404`) rejects with an `AdapterError`, which the editor retries.
+ */
+export declare function createPayloadAdapter(options: PayloadAdapterOptions): DocumentAdapter;
+//# sourceMappingURL=document-adapter.d.ts.map

package/dist/adapter/document-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-adapter.d.ts","sourceRoot":"","sources":["../../src/adapter/document-adapter.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EACV,eAAe,EAOhB,MAAM,qBAAqB,CAAC;AAgB7B,OAAO,EAKL,KAAK,WAAW,EAEjB,MAAM,WAAW,CAAC;AAEnB,MAAM,WAAW,qBAAsB,SAAQ,WAAW;IACxD,uFAAuF;IACvF,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,SAAS,CAAC;IACzD,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,2GAA2G;IAC3G,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3C,wEAAwE;IACxE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1C;AAwCD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,qBAAqB,GAAG,eAAe,CA0JpF"}

package/dist/adapter/document-adapter.js

@@ -0,0 +1,183 @@
+import { mediaAssetSchema, parseDocument, } from '@next-buildr/core';
+import { conflictResponseSchema, dataContextResponseSchema, dataSchemaResponseSchema, documentResponseSchema, invalidResponseSchema, mediaListResponseSchema, publishResponseSchema, renameResponseSchema, revisionResponseSchema, samplesResponseSchema, saveResponseSchema, sessionResponseSchema, } from '../contract.js';
+import { AdapterError, createHttp, errorOf, expectBody, } from './http.js';
+const seg = (value) => encodeURIComponent(String(value));
+const documentPath = (ref) => `/buildr/documents/${seg(ref.collection)}/${seg(ref.id)}`;
+/** The server's diagnostics as core's (`details` is JSON on the wire). */
+const diagnosticsOf = (list) => list;
+/** A `409` or `422` of a save/publish is a value; anything else that is not `200` rejects. */
+function refusal(reply) {
+    if (reply.status === 409) {
+        const parsed = conflictResponseSchema.safeParse(reply.body);
+        if (parsed.success) {
+            return { ok: false, kind: 'conflict', currentRevision: parsed.data.currentRevision };
+        }
+    }
+    if (reply.status === 422) {
+        const parsed = invalidResponseSchema.safeParse(reply.body);
+        if (parsed.success) {
+            return { ok: false, kind: 'invalid', diagnostics: diagnosticsOf(parsed.data.diagnostics) };
+        }
+    }
+    return undefined;
+}
+const MIME_TYPES = ['image', 'video', 'audio'];
+/** The one media type all of `mimeTypes` share (`image/*`, `image/png`, ...), if there is one. */
+function mediaType(mimeTypes) {
+    if (mimeTypes === undefined || mimeTypes.length === 0)
+        return undefined;
+    const kinds = new Set(mimeTypes.map((mime) => mime.split('/')[0]));
+    const [only] = [...kinds];
+    return kinds.size === 1 ? MIME_TYPES.find((kind) => kind === only) : undefined;
+}
+/**
+ * The `DocumentAdapter` of the editor (docs/editor.md#persistence-pb-087) over the builder API of
+ * the Payload plugin. Responses are checked against the contract; a document is parsed with core's
+ * `parseDocument`. A refused save (`409`, `422`) is a result; anything the adapter could not tell
+ * (no network, `5xx`, `401`, `403`, `404`) rejects with an `AdapterError`, which the editor retries.
+ */
+export function createPayloadAdapter(options) {
+    const http = createHttp(options);
+    let session;
+    const loadSession = () => {
+        session ??= http
+            .send('GET', '/buildr/session')
+            .then((reply) => expectBody(reply, sessionResponseSchema))
+            .catch((error) => {
+            session = undefined;
+            throw error;
+        });
+        return session;
+    };
+    const localesOf = (current) => current.locales === undefined ? undefined : current.locales;
+    return {
+        async getSession() {
+            const current = await loadSession();
+            const locales = localesOf(current);
+            return {
+                userId: String(current.user.id),
+                canEdit: current.permissions.canEdit,
+                canPublish: current.permissions.canPublish,
+                ...(locales === undefined ? {} : { locales }),
+            };
+        },
+        async load(ref) {
+            const reply = await http.send('GET', documentPath(ref), {
+                query: { draft: '1', locale: options.locale?.() },
+            });
+            const body = expectBody(reply, documentResponseSchema);
+            const parsed = parseDocument(body.document);
+            if (!parsed.ok)
+                throw new AdapterError('The stored document is not valid.', reply.status);
+            return {
+                title: body.title,
+                ...(body.slug === null ? {} : { slug: body.slug }),
+                status: body.status,
+                updatedAt: body.updatedAt,
+                revision: body.revision,
+                document: parsed.value,
+                contextRef: body.contextRef,
+                ...(body.readOnly === true ? { readOnly: true } : {}),
+            };
+        },
+        async getRevision(ref) {
+            const reply = await http.send('GET', `${documentPath(ref)}/revision`);
+            const body = expectBody(reply, revisionResponseSchema);
+            return {
+                revision: body.revision,
+                updatedAt: body.updatedAt,
+                ...(body.updatedBy === undefined ? {} : { updatedBy: body.updatedBy }),
+            };
+        },
+        async save(ref, request) {
+            const reply = await http.send('PUT', documentPath(ref), { body: request });
+            const refused = refusal(reply);
+            if (refused !== undefined)
+                return refused;
+            const body = expectBody(reply, saveResponseSchema);
+            return { ok: true, revision: body.revision, updatedAt: body.updatedAt };
+        },
+        async rename(ref, title) {
+            const reply = await http.send('PATCH', documentPath(ref), { body: { title } });
+            return expectBody(reply, renameResponseSchema);
+        },
+        async publish(ref, request) {
+            const reply = await http.send('POST', `${documentPath(ref)}/publish`, { body: request });
+            const refused = refusal(reply);
+            if (refused !== undefined)
+                return refused;
+            const body = expectBody(reply, publishResponseSchema);
+            return { ok: true, revision: body.revision, updatedAt: body.updatedAt };
+        },
+        async getDataSchema(ref) {
+            const reply = await http.send('GET', `/buildr/data-schema/${seg(ref.collection)}`);
+            return expectBody(reply, dataSchemaResponseSchema);
+        },
+        async getContext(ref, request) {
+            const current = await loadSession();
+            const locales = localesOf(current);
+            const locale = options.locale?.() ?? locales?.default ?? 'en';
+            // A sample is `collection:id` (what `listSamples` returns); a bare id belongs to the document's own collection.
+            const sample = request?.sampleId;
+            const at = sample === undefined ? -1 : sample.indexOf(':');
+            const reply = await http.send('GET', '/buildr/data/context', {
+                query: {
+                    collection: sample !== undefined && at > 0 ? sample.slice(0, at) : ref.collection,
+                    id: sample === undefined ? String(ref.id) : sample.slice(at + 1),
+                    draft: '1',
+                    locale,
+                },
+            });
+            const body = expectBody(reply, dataContextResponseSchema);
+            const fallbackLocales = { default: locale, fallback: false, intl: { [locale]: locale } };
+            return {
+                scopes: body.scopes,
+                locale,
+                locales: locales ?? fallbackLocales,
+                timeZone: options.timeZone ?? Intl.DateTimeFormat().resolvedOptions().timeZone,
+                mode: 'canvas',
+            };
+        },
+        async listSamples(ref) {
+            const reply = await http.send('GET', `/buildr/samples/${seg(ref.collection)}`);
+            const body = expectBody(reply, samplesResponseSchema);
+            // The id is the canvas's `contextRef` (`collection:id`), so choosing a sample needs no translation.
+            return body.items.map((item) => ({ id: `${ref.collection}:${item.id}`, label: item.title }));
+        },
+        media: {
+            async search(query) {
+                const page = query.cursor === undefined ? 1 : Number(query.cursor);
+                const reply = await http.send('GET', '/buildr/media', {
+                    query: {
+                        search: query.text === undefined || query.text === '' ? undefined : query.text,
+                        type: mediaType(query.mimeTypes),
+                        page: String(Number.isInteger(page) && page >= 1 ? page : 1),
+                    },
+                });
+                const body = expectBody(reply, mediaListResponseSchema);
+                return {
+                    items: body.items,
+                    ...(body.page < body.totalPages ? { nextCursor: String(body.page + 1) } : {}),
+                };
+            },
+            async upload(file, alt) {
+                const form = new FormData();
+                form.set('file', file);
+                form.set('alt', alt);
+                const reply = await http.send('POST', '/buildr/media', { body: form });
+                if (reply.status === 422)
+                    throw errorOf(reply);
+                return expectBody(reply, mediaAssetSchema, [201]);
+            },
+        },
+        previewUrl(ref, request) {
+            const query = new URLSearchParams({ collection: ref.collection, id: String(ref.id) });
+            if (request?.draft === true)
+                query.set('draft', '1');
+            return `${options.previewRoute ?? '/buildr/preview'}?${query.toString()}`;
+        },
+        cmsUrl(ref) {
+            return `${(options.adminRoute ?? '/admin').replace(/\/+$/, '')}/collections/${seg(ref.collection)}/${seg(ref.id)}`;
+        },
+    };
+}

package/dist/adapter/http.d.ts

@@ -0,0 +1,34 @@
+import type { z } from 'zod';
+/**
+ * A call that did not come to an answer the caller can act on: no network, a `5xx`, `401`/`403`/
+ * `404`, a body that breaks the contract. (A `409` or `422` of a save is a value, not this.)
+ */
+export declare class AdapterError extends Error {
+    readonly status: number | undefined;
+    constructor(message: string, status?: number);
+}
+export interface HttpOptions {
+    /** Payload's API root, e.g. `/api` or `https://cms.example.com/api`. */
+    readonly baseUrl: string;
+    /** Defaults to the global `fetch` (looked up per call, so tests can replace it). */
+    readonly fetch?: typeof globalThis.fetch | undefined;
+    /** Cookies travel with a same-origin request by default; use `include` for a cross-origin CMS. */
+    readonly credentials?: 'same-origin' | 'include' | 'omit' | undefined;
+}
+export interface Reply {
+    readonly status: number;
+    readonly body: unknown;
+}
+export interface Http {
+    /** `path` is relative to `baseUrl` (`/buildr/session`). Never rejects for an HTTP status, only for the network. */
+    send(method: 'GET' | 'POST' | 'PUT' | 'PATCH', path: string, init?: {
+        readonly query?: Record<string, string | undefined>;
+        readonly body?: unknown;
+    }): Promise<Reply>;
+}
+export declare function createHttp(options: HttpOptions): Http;
+/** The message of an `{ error }` body, else a generic one. */
+export declare function errorOf(reply: Reply): AdapterError;
+/** The body of a successful reply, checked against the contract; anything else is an `AdapterError`. */
+export declare function expectBody<S extends z.ZodType>(reply: Reply, schema: S, accepted?: readonly number[]): z.infer<S>;
+//# sourceMappingURL=http.d.ts.map

package/dist/adapter/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/adapter/http.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAG7B;;;GAGG;AACH,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,YAAY,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAI3C;CACF;AAED,MAAM,WAAW,WAAW;IAC1B,wEAAwE;IACxE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,oFAAoF;IACpF,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,GAAG,SAAS,CAAC;IACrD,kGAAkG;IAClG,QAAQ,CAAC,WAAW,CAAC,EAAE,aAAa,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;CACvE;AAED,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,IAAI;IACnB,mHAAmH;IACnH,IAAI,CACF,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,EACxC,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;QAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,GACtF,OAAO,CAAC,KAAK,CAAC,CAAC;CACnB;AAID,wBAAgB,UAAU,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,CAsCrD;AAED,8DAA8D;AAC9D,wBAAgB,OAAO,CAAC,KAAK,EAAE,KAAK,GAAG,YAAY,CAMlD;AAED,wGAAwG;AACxG,wBAAgB,UAAU,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAC5C,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,CAAC,EACT,QAAQ,GAAE,SAAS,MAAM,EAAU,GAClC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAOZ"}

package/dist/adapter/http.js

@@ -0,0 +1,72 @@
+import { errorResponseSchema } from '../contract.js';
+/**
+ * A call that did not come to an answer the caller can act on: no network, a `5xx`, `401`/`403`/
+ * `404`, a body that breaks the contract. (A `409` or `422` of a save is a value, not this.)
+ */
+export class AdapterError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.name = 'AdapterError';
+        this.status = status;
+    }
+}
+const trimEnd = (value) => value.replace(/\/+$/, '');
+export function createHttp(options) {
+    const base = trimEnd(options.baseUrl);
+    return {
+        async send(method, path, init = {}) {
+            const params = new URLSearchParams();
+            for (const [key, value] of Object.entries(init.query ?? {})) {
+                if (value !== undefined)
+                    params.set(key, value);
+            }
+            const search = params.toString();
+            const url = `${base}${path}${search === '' ? '' : `?${search}`}`;
+            const body = init.body;
+            const isForm = typeof FormData !== 'undefined' && body instanceof FormData;
+            let response;
+            try {
+                const doFetch = options.fetch ?? globalThis.fetch;
+                response = await doFetch(url, {
+                    method,
+                    credentials: options.credentials ?? 'same-origin',
+                    headers: body === undefined || isForm ? {} : { 'content-type': 'application/json' },
+                    ...(body === undefined
+                        ? {}
+                        : { body: isForm ? body : JSON.stringify(body) }),
+                });
+            }
+            catch (error) {
+                throw new AdapterError(error instanceof Error ? error.message : 'The request failed.');
+            }
+            const text = await response.text().catch(() => '');
+            let parsed;
+            if (text !== '') {
+                try {
+                    parsed = JSON.parse(text);
+                }
+                catch {
+                    if (response.ok)
+                        throw new AdapterError('The response is not JSON.', response.status);
+                }
+            }
+            return { status: response.status, body: parsed };
+        },
+    };
+}
+/** The message of an `{ error }` body, else a generic one. */
+export function errorOf(reply) {
+    const parsed = errorResponseSchema.safeParse(reply.body);
+    return new AdapterError(parsed.success ? parsed.data.error : `The server answered ${reply.status}.`, reply.status);
+}
+/** The body of a successful reply, checked against the contract; anything else is an `AdapterError`. */
+export function expectBody(reply, schema, accepted = [200]) {
+    if (!accepted.includes(reply.status))
+        throw errorOf(reply);
+    const parsed = schema.safeParse(reply.body);
+    if (!parsed.success) {
+        throw new AdapterError('The response does not match the contract.', reply.status);
+    }
+    return parsed.data;
+}

package/dist/adapter/index.d.ts

@@ -0,0 +1,4 @@
+export { createPayloadCanvasDataSource } from './canvas-data-source.ts';
+export { createPayloadAdapter, type PayloadAdapterOptions } from './document-adapter.ts';
+export { AdapterError, type HttpOptions } from './http.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/adapter/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapter/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,6BAA6B,EAAE,MAAM,yBAAyB,CAAC;AACxE,OAAO,EAAE,oBAAoB,EAAE,KAAK,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AACzF,OAAO,EAAE,YAAY,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC"}