@materializecms/server 0.0.0-stage → 0.2.0

package/src/tools.js

@@ -0,0 +1,474 @@
+import { buildSection, LIBRARY } from '@materializecms/core/library';
+import { cloneNode, collapseComponents, collapseGlobals, expandComponents, expandGlobals, findNode, insertNode, newId, plainText, removeNode, updateNode, } from '@materializecms/core/page';
+import { z } from 'zod';
+/** An answer the model can act on: what went wrong, in words. */
+export class ToolError extends Error {
+}
+const tool = (def) => def;
+/** How the page model works, for a model that is about to edit one. */
+export const PAGE_GUIDE = `Pages are trees of nodes. The top level holds sections (type "frame"); sections hold frames, texts, images, buttons, icons, videos, scenes and form inputs.
+Every node has an "id" (keep existing ids; new nodes may omit it, one is assigned) and a "type".
+
+Common properties:
+- Layout of a frame: layout "col" | "row" | "grid", cols (grid columns), gap (px), align "start"|"center"|"end"|"stretch", justify "start"|"center"|"end"|"between", wrap.
+- Size: width "fill"|"hug"|"fixed" with fixedW, maxW, h (px or "60vh"), minH (percent of screen height, sections), padX/padY (px), size "xs"|"s"|"m"|"l" (a section's vertical padding).
+- Look: bg (theme token or CSS color), scheme "default"|"surface"|"inverse"|"accent" (a section's color scheme), radius (px | "btn" | "card"), border, shadow "none"|"sm"|"lg", gradient, bgImage {src, alt}, bgDim 0-1.
+- Text ("text"): text (plain) or runs [{t, b?, i?, href?}], style "display"|"h1"|"h2"|"h3"|"body"|"small"|"eyebrow"|"logo"|"button", tag "h1".."h4"|"p" (HTML element, defaults from style), color, talign "left"|"center"|"right", fontSize, weight, upper, italic.
+- Button ("button"): text, href, variant "primary"|"secondary"|"ghost", newTab.
+- Image ("image"): src (a URL from the media library, e.g. /media/photo.jpg), alt, ratio ("16/9", "1/1"…), fit "cover"|"contain".
+- Icon ("icon"): icon "lucide:arrow-right" style names.
+- Motion: anim "fade"|"up"|"down"|"left"|"right"|"zoom"|"blur"|"reveal"|"pop", animTrig "load"|"scroll", hover "lift"|"grow"|"dim"|"zoomimg".
+- Tablet and mobile changes go in over: {tablet: {...}, mobile: {...}} (only the properties that differ).
+Theme color tokens: bg, surface, text, muted, accent, onAccent, inverse, onInverse, border, line.
+Prefer adding ready-made sections from the library (add_section) and then changing their texts, images and colors: they are designed and responsive. Write content in the site's language.`;
+/** One line per node, indented: what the model reads before editing. */
+export function outline(nodes) {
+    const lines = [];
+    const go = (list, depth) => {
+        for (const n of list) {
+            const bits = [n.type];
+            if (n.name)
+                bits.push(`"${n.name}"`);
+            if (n.global)
+                bits.push('(shared section: changes apply to every page using it)');
+            if (n.component)
+                bits.push('(component copy)');
+            if (n.type === 'frame' && n.layout)
+                bits.push(`layout=${n.layout}${n.cols ? ` cols=${n.cols}` : ''}`);
+            if (n.style)
+                bits.push(`style=${n.style}`);
+            const text = plainText(n);
+            if (text)
+                bits.push(JSON.stringify(text.length > 90 ? `${text.slice(0, 90)}…` : text));
+            if (n.src)
+                bits.push(`src=${n.src}`);
+            if (n.href)
+                bits.push(`href=${n.href}`);
+            if (n.bind)
+                bits.push(`list of ${n.bind.collection}`);
+            if (n.field)
+                bits.push(`shows field ${n.field}`);
+            if (n.hidden)
+                bits.push('hidden');
+            lines.push(`${'  '.repeat(depth)}- [${n.id}] ${bits.join(' ')}`);
+            if (n.children?.length)
+                go(n.children, depth + 1);
+        }
+    };
+    go(nodes, 0);
+    return lines.length ? lines.join('\n') : '(empty page)';
+}
+/** New nodes get ids where they lack one; the rest stay as they are. */
+function withIds(n) {
+    return { ...n, id: typeof n.id === 'string' && n.id ? n.id : newId(), children: n.children?.map(withIds) };
+}
+const nodeShape = z.looseObject({ type: z.string(), id: z.string().optional() });
+const operation = z.discriminatedUnion('op', [
+    z.object({
+        op: z.literal('add_section'),
+        key: z.string().describe('Library section, e.g. "hero.split" (see list_library)'),
+        index: z.number().int().optional().describe('Position among the sections; default: at the end'),
+    }),
+    z.object({
+        op: z.literal('insert'),
+        parentId: z.string().nullable().describe('Container to insert into; null for a new section on the page'),
+        index: z.number().int().optional().describe('Position among its children; default: at the end'),
+        node: nodeShape.describe('The new node, with its children'),
+    }),
+    z.object({
+        op: z.literal('update'),
+        nodeId: z.string(),
+        props: z.record(z.string(), z.unknown()).describe('Properties to set; null removes one'),
+    }),
+    z.object({ op: z.literal('replace'), nodeId: z.string(), node: nodeShape }),
+    z.object({ op: z.literal('remove'), nodeId: z.string() }),
+    z.object({
+        op: z.literal('move'),
+        nodeId: z.string(),
+        parentId: z.string().nullable(),
+        index: z.number().int(),
+    }),
+    z.object({ op: z.literal('duplicate'), nodeId: z.string() }),
+]);
+/** Applies edits to a page tree; stops at the first that cannot apply, saying which and why. */
+export function applyOperations(nodes, ops, brand) {
+    let tree = nodes;
+    for (const [i, op] of ops.entries()) {
+        const fail = (why) => {
+            throw new ToolError(`Operation ${i + 1} (${op.op}): ${why}. Nothing was changed.`);
+        };
+        const need = (id) => findNode(tree, id) ?? fail(`there is no node "${id}"`);
+        switch (op.op) {
+            case 'add_section': {
+                if (!LIBRARY.some((c) => c.variants.some((v) => v.key === op.key)))
+                    fail(`no library section "${op.key}"`);
+                tree = insertNode(tree, null, op.index ?? tree.length, buildSection(op.key, brand));
+                break;
+            }
+            case 'insert': {
+                if (op.parentId)
+                    need(op.parentId);
+                const parent = op.parentId ? findNode(tree, op.parentId)?.node : null;
+                if (parent && parent.type !== 'frame')
+                    fail('only frames can hold other nodes');
+                const count = parent ? (parent.children?.length ?? 0) : tree.length;
+                tree = insertNode(tree, op.parentId, op.index ?? count, withIds(op.node));
+                break;
+            }
+            case 'update': {
+                need(op.nodeId);
+                tree = updateNode(tree, op.nodeId, (n) => {
+                    const next = { ...n };
+                    for (const [k, v] of Object.entries(op.props)) {
+                        if (k === 'id' || k === 'children')
+                            continue;
+                        if (v === null)
+                            delete next[k];
+                        else
+                            next[k] = v;
+                    }
+                    // Plain text replaces formatted text.
+                    if ('text' in op.props && !('runs' in op.props))
+                        delete next.runs;
+                    return next;
+                });
+                break;
+            }
+            case 'replace': {
+                need(op.nodeId);
+                tree = updateNode(tree, op.nodeId, () => withIds({ ...op.node, id: op.nodeId }));
+                break;
+            }
+            case 'remove':
+                need(op.nodeId);
+                tree = removeNode(tree, op.nodeId);
+                break;
+            case 'move': {
+                const found = need(op.nodeId);
+                if (op.parentId && findNode([found.node], op.parentId))
+                    fail('a node cannot go inside itself');
+                if (op.parentId)
+                    need(op.parentId);
+                tree = insertNode(removeNode(tree, op.nodeId), op.parentId, op.index, found.node);
+                break;
+            }
+            case 'duplicate': {
+                const found = need(op.nodeId);
+                tree = insertNode(tree, found.parent?.id ?? null, found.index + 1, cloneNode(found.node));
+                break;
+            }
+        }
+    }
+    return tree;
+}
+/** The page tools: read the outline and a node, and edit. */
+export function pageTools(options) {
+    const id = options.withId
+        ? { id: z.string().describe('The page document id (from list_entries)') }
+        : {};
+    const idOf = (input) => input.id;
+    return [
+        tool({
+            name: 'get_page',
+            title: 'Leggo la pagina',
+            description: 'The page as an outline: one line per node with its id, type, name and text. Read it before editing, and again after big changes.',
+            input: z.object({ ...id }),
+            readOnly: true,
+            run: async (input) => outline(await (await options.source(idOf(input))).load()),
+        }),
+        tool({
+            name: 'get_node',
+            title: 'Leggo un elemento',
+            description: 'One node with all its properties and children, as JSON: to see its exact design before changing it.',
+            input: z.object({ ...id, nodeId: z.string() }),
+            readOnly: true,
+            run: async (input) => {
+                const found = findNode(await (await options.source(idOf(input))).load(), input.nodeId);
+                if (!found)
+                    throw new ToolError(`There is no node "${input.nodeId}" on this page`);
+                return found.node;
+            },
+        }),
+        tool({
+            name: 'edit_page',
+            title: 'Modifico la pagina',
+            description: `Changes the page with a list of operations, applied in order and saved together (all or nothing): add_section from the library, insert a node, update properties, replace, remove, move, duplicate. Returns the new outline.\n\n${PAGE_GUIDE}`,
+            input: z.object({ ...id, operations: z.array(operation).min(1).max(60) }),
+            run: async (input) => {
+                const page = await options.source(idOf(input));
+                const next = applyOperations(await page.load(), input.operations, await options.brand());
+                await page.save(next);
+                return outline(next);
+            },
+        }),
+    ];
+}
+/** Tools for the whole site: collections and entries, pages by id, theme, media. */
+export function siteTools(call) {
+    let schema = null;
+    const getSchema = async () => (schema ??= await call('GET', '/api/schema'));
+    const pageField = async (doc) => {
+        const def = (await getSchema()).collections.find((c) => c.name === doc.collection);
+        const field = def?.fields.find((f) => f.kind === 'page');
+        if (!field)
+            throw new ToolError(`"${doc.title}" is not a page built on the canvas`);
+        return field.name;
+    };
+    // A page by id, with shared sections and components expanded as in the editor; saving folds them back.
+    const source = async (id) => {
+        if (!id)
+            throw new ToolError('Say which page: its id');
+        const doc = await call('GET', `/api/documents/${encodeURIComponent(id)}`);
+        const name = await pageField(doc);
+        const { globals } = await call('GET', '/api/globals');
+        const { components } = await call('GET', '/api/components');
+        return {
+            load: async () => expandComponents(expandGlobals(Array.isArray(doc.data[name]) ? doc.data[name] : [], globals), components),
+            save: async (nodes) => {
+                const withRefs = collapseComponents(nodes, components);
+                if (JSON.stringify(withRefs.components) !== JSON.stringify(components))
+                    await call('PUT', '/api/components', { components: withRefs.components });
+                const collapsed = collapseGlobals(withRefs.nodes);
+                const merged = { ...globals, ...collapsed.globals };
+                if (JSON.stringify(merged) !== JSON.stringify(globals))
+                    await call('PUT', '/api/globals', { globals: merged });
+                await call('PUT', `/api/documents/${encodeURIComponent(doc.id)}`, {
+                    data: { ...doc.data, [name]: collapsed.nodes },
+                });
+            },
+        };
+    };
+    return [
+        ...contentTools(call, getSchema),
+        ...pageTools({ source, withId: true, brand: async () => (await getSchema()).site.name }),
+    ];
+}
+/**
+ * The editor's assistant: the site tools that make sense next to the open page (no publishing:
+ * the editor has its own button), and page tools working on the page as the editor holds it.
+ */
+export function assistantTools(call, page, brand) {
+    let schema = null;
+    const getSchema = async () => (schema ??= await call('GET', '/api/schema'));
+    const source = async () => ({
+        load: async () => page.nodes,
+        save: async (nodes) => {
+            page.nodes = nodes;
+        },
+    });
+    return [
+        ...contentTools(call, getSchema).filter((t) => t.name !== 'publish_entry' && t.name !== 'unpublish_entry'),
+        ...pageTools({ source, withId: false, brand: async () => brand }),
+    ];
+}
+/** Everything but the page editing: shared with the editor's assistant, which edits the open page itself. */
+export function contentTools(call, getSchema) {
+    return [
+        tool({
+            name: 'get_site',
+            title: 'Guardo il sito',
+            description: 'The site: its name, languages and collections (pages, articles, projects…) with their fields. Start here.',
+            input: z.object({}),
+            readOnly: true,
+            run: async () => {
+                const s = await getSchema();
+                return {
+                    site: s.site,
+                    locales: s.locales,
+                    collections: s.collections.map((c) => ({
+                        name: c.name,
+                        label: c.label,
+                        singleton: c.singleton,
+                        fields: c.fields.map((f) => ({ name: f.name, kind: f.kind, label: f.label })),
+                    })),
+                };
+            },
+        }),
+        tool({
+            name: 'list_entries',
+            title: 'Elenco i contenuti',
+            description: 'Entries of a collection (newest changes first), with id, title, address and whether published.',
+            input: z.object({
+                collection: z.string(),
+                search: z.string().optional().describe('Words in the title'),
+                locale: z.string().optional(),
+                limit: z.number().int().min(1).max(100).optional(),
+                offset: z.number().int().min(0).optional(),
+            }),
+            readOnly: true,
+            run: async (input) => {
+                const q = new URLSearchParams();
+                for (const k of ['search', 'locale', 'limit', 'offset'])
+                    if (input[k] !== undefined)
+                        q.set(k, String(input[k]));
+                return call('GET', `/api/collections/${encodeURIComponent(input.collection)}?${q}`);
+            },
+        }),
+        tool({
+            name: 'get_entry',
+            title: 'Leggo un contenuto',
+            description: 'An entry with all its fields. For pages built on the canvas the page field is long: use get_page to read it as an outline.',
+            input: z.object({ id: z.string() }),
+            readOnly: true,
+            run: async (input) => {
+                const doc = await call('GET', `/api/documents/${encodeURIComponent(input.id)}`);
+                const data = {};
+                for (const [k, v] of Object.entries(doc.data))
+                    data[k] =
+                        Array.isArray(v) && v[0]?.type
+                            ? `(page with ${v.length} sections: use get_page)`
+                            : v;
+                return { ...doc, data };
+            },
+        }),
+        tool({
+            name: 'create_entry',
+            title: 'Creo un contenuto',
+            description: 'A new draft in a collection, with the fields given (see get_site for their names). The address (slug) follows the title when left out. Publish it with publish_entry.',
+            input: z.object({
+                collection: z.string(),
+                data: z.record(z.string(), z.unknown()),
+                locale: z.string().optional(),
+            }),
+            run: async (input) => {
+                const doc = await call('POST', `/api/collections/${encodeURIComponent(input.collection)}`, { data: input.data, locale: input.locale });
+                return { id: doc.id, title: doc.title, url: doc.url, issues: doc.issues };
+            },
+        }),
+        tool({
+            name: 'update_entry',
+            title: 'Modifico un contenuto',
+            description: 'Changes some fields of an entry (the others stay as they are) and saves the draft. Use edit_page for the design of a page.',
+            input: z.object({ id: z.string(), data: z.record(z.string(), z.unknown()) }),
+            run: async (input) => {
+                const doc = await call('GET', `/api/documents/${encodeURIComponent(input.id)}`);
+                const saved = await call('PUT', `/api/documents/${encodeURIComponent(doc.id)}`, {
+                    data: { ...doc.data, ...input.data },
+                });
+                return { id: saved.id, title: saved.title, url: saved.url, issues: saved.issues };
+            },
+        }),
+        tool({
+            name: 'publish_entry',
+            title: 'Pubblico',
+            description: 'Puts the current draft of an entry on the public site.',
+            input: z.object({ id: z.string() }),
+            run: async (input) => {
+                const doc = await call('POST', `/api/documents/${encodeURIComponent(input.id)}/publish`);
+                return { id: doc.id, title: doc.title, url: doc.url, published: true };
+            },
+        }),
+        tool({
+            name: 'unpublish_entry',
+            title: 'Tolgo dal sito',
+            description: 'Takes an entry off the public site; it stays as a draft.',
+            input: z.object({ id: z.string() }),
+            run: async (input) => {
+                const doc = await call('POST', `/api/documents/${encodeURIComponent(input.id)}/unpublish`);
+                return { id: doc.id, title: doc.title, published: false };
+            },
+        }),
+        tool({
+            name: 'list_translations',
+            title: 'Guardo le lingue',
+            description: 'The language versions of an entry (its original and translations, with id and status) and the site languages it is still missing.',
+            input: z.object({ id: z.string() }),
+            readOnly: true,
+            run: (input) => call('GET', `/api/documents/${encodeURIComponent(input.id)}/translations`),
+        }),
+        tool({
+            name: 'translate_entry',
+            title: 'Traduco',
+            description: 'Creates the version of an entry in another site language, as a draft linked to the original. With translate: true the site AI translates every text (and the address); otherwise it is a copy to translate, e.g. with update_entry or edit_page. Menus and footers shared by pages are translated once per language in the editor.',
+            input: z.object({
+                id: z.string(),
+                locale: z.string().describe('A language code from get_site, e.g. "en"'),
+                translate: z.boolean().default(true),
+            }),
+            run: async (input) => {
+                const doc = await call('POST', `/api/documents/${encodeURIComponent(input.id)}/translations`, {
+                    locale: input.locale,
+                    translate: input.translate,
+                });
+                return { id: doc.id, title: doc.title, url: doc.url, locale: input.locale, published: false };
+            },
+        }),
+        tool({
+            name: 'list_library',
+            title: 'Guardo la libreria di sezioni',
+            description: 'Ready-made sections that can be added to a page (edit_page → add_section), by category.',
+            input: z.object({}),
+            readOnly: true,
+            run: async () => LIBRARY.map((c) => ({ category: c.label, sections: c.variants.map((v) => `${v.key} (${v.label})`) })),
+        }),
+        tool({
+            name: 'get_theme',
+            title: 'Leggo il tema',
+            description: 'The design theme: colors (light and dark), fonts, roundness, text styles.',
+            input: z.object({}),
+            readOnly: true,
+            run: async () => (await call('GET', '/api/theme')).theme,
+        }),
+        tool({
+            name: 'update_theme',
+            title: 'Modifico il tema',
+            description: 'Changes the theme: give only what changes, e.g. {"display": "Fraunces", "colors": {"light": {"accent": "#e94f37"}}}. Fonts are Google Fonts names. Applies to the whole site at once.',
+            input: z.object({ patch: z.record(z.string(), z.unknown()) }),
+            run: async (input) => {
+                const { theme } = await call('GET', '/api/theme');
+                return (await call('PUT', '/api/theme', { theme: merge(theme, input.patch) })).theme;
+            },
+        }),
+        tool({
+            name: 'list_media',
+            title: 'Guardo la libreria media',
+            description: 'Images and files already uploaded, with their address (src) to use in pages and fields.',
+            input: z.object({ search: z.string().optional(), limit: z.number().int().min(1).max(100).optional() }),
+            readOnly: true,
+            run: async (input) => {
+                const q = new URLSearchParams({ limit: String(input.limit ?? 40) });
+                if (input.search)
+                    q.set('search', input.search);
+                return call('GET', `/api/media?${q}`);
+            },
+        }),
+        tool({
+            name: 'upload_media_from_url',
+            title: 'Aggiungo un’immagine dal web',
+            description: 'Downloads an image from a public https address into the media library and returns its src. Only use images the site may publish.',
+            input: z.object({ url: z.url(), alt: z.string().max(500).optional() }),
+            run: async (input) => call('POST', '/api/media/from-url', input),
+        }),
+    ];
+}
+/** Deep merge of plain objects: what the patch has wins, the rest stays. */
+function merge(base, patch) {
+    const out = { ...base };
+    for (const [k, v] of Object.entries(patch)) {
+        const b = base[k];
+        out[k] =
+            v && typeof v === 'object' && !Array.isArray(v) && b && typeof b === 'object' && !Array.isArray(b)
+                ? merge(b, v)
+                : v;
+    }
+    return out;
+}
+/**
+ * Calls the API as whoever sent `auth` (cookie or bearer header): in process through the Hono app's
+ * `fetch`, or over the network to a running server at `origin` (`materialize mcp`).
+ */
+export function apiCaller(fetch, auth, origin = 'http://materialize.internal') {
+    return async (method, path, body) => {
+        const res = await fetch(new Request(origin + path, {
+            method,
+            headers: { ...auth, origin, ...(body === undefined ? {} : { 'content-type': 'application/json' }) },
+            body: body === undefined ? undefined : JSON.stringify(body),
+        }));
+        const json = (await res.json().catch(() => null));
+        if (!res.ok) {
+            const issues = json?.error?.issues?.map((i) => `${i.path}: ${i.message}`).join('; ');
+            throw new ToolError(`${json?.error?.message ?? `HTTP ${res.status}`}${issues ? ` (${issues})` : ''}`);
+        }
+        return json;
+    };
+}

package/src/totp.d.ts

@@ -0,0 +1,13 @@
+/** A new secret: 160 random bits, in the base32 the apps read. */
+export declare const newSecret: () => string;
+export declare const stepAt: (time?: number) => number;
+export declare function codeAt(secret: string, step: number): string;
+/**
+ * The time step a code belongs to, or null. One step either side is accepted (a phone's clock
+ * may be a little off); steps up to `after` are refused, so a code cannot be used twice.
+ */
+export declare function verifyCode(secret: string, code: string, after?: number | null, now?: number): number | null;
+/** What the app scans: the account and the site's name, so people can tell their codes apart. */
+export declare function otpauthUri(secret: string, account: string, issuer: string): string;
+/** Ten one-time recovery codes, for when the phone is lost: "k7f2-9qxm". */
+export declare function recoveryCodes(count?: number): string[];

package/src/totp.js

@@ -0,0 +1,79 @@
+import { createHmac, randomBytes, randomInt, timingSafeEqual } from 'node:crypto';
+/**
+ * Two-step verification with an authenticator app (Google Authenticator, 1Password, Authy…):
+ * time-based one-time passwords as in RFC 6238, 6 digits every 30 seconds, from Node's crypto.
+ */
+const ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ234567';
+const PERIOD = 30;
+function base32(bytes) {
+    let bits = 0;
+    let value = 0;
+    let out = '';
+    for (const byte of bytes) {
+        value = (value << 8) | byte;
+        bits += 8;
+        while (bits >= 5) {
+            out += ALPHABET[(value >>> (bits - 5)) & 31];
+            bits -= 5;
+        }
+    }
+    if (bits > 0)
+        out += ALPHABET[(value << (5 - bits)) & 31];
+    return out;
+}
+function fromBase32(text) {
+    let bits = 0;
+    let value = 0;
+    const out = [];
+    for (const char of text.replace(/=+$/, '').toUpperCase()) {
+        const index = ALPHABET.indexOf(char);
+        if (index < 0)
+            continue;
+        value = (value << 5) | index;
+        bits += 5;
+        if (bits >= 8) {
+            out.push((value >>> (bits - 8)) & 255);
+            bits -= 8;
+        }
+    }
+    return Buffer.from(out);
+}
+/** A new secret: 160 random bits, in the base32 the apps read. */
+export const newSecret = () => base32(randomBytes(20));
+export const stepAt = (time = Date.now()) => Math.floor(time / 1000 / PERIOD);
+export function codeAt(secret, step) {
+    const counter = Buffer.alloc(8);
+    counter.writeBigUInt64BE(BigInt(step));
+    const hmac = createHmac('sha1', fromBase32(secret)).update(counter).digest();
+    const offset = hmac[hmac.length - 1] & 15;
+    const binary = hmac.readUInt32BE(offset) & 0x7fffffff;
+    return String(binary % 1_000_000).padStart(6, '0');
+}
+/**
+ * The time step a code belongs to, or null. One step either side is accepted (a phone's clock
+ * may be a little off); steps up to `after` are refused, so a code cannot be used twice.
+ */
+export function verifyCode(secret, code, after = null, now = Date.now()) {
+    const clean = code.replace(/\s/g, '');
+    if (!/^\d{6}$/.test(clean))
+        return null;
+    const current = stepAt(now);
+    for (const step of [current, current - 1, current + 1]) {
+        if (after !== null && step <= after)
+            continue;
+        if (timingSafeEqual(Buffer.from(codeAt(secret, step)), Buffer.from(clean)))
+            return step;
+    }
+    return null;
+}
+/** What the app scans: the account and the site's name, so people can tell their codes apart. */
+export function otpauthUri(secret, account, issuer) {
+    const label = encodeURIComponent(`${issuer}:${account}`);
+    return `otpauth://totp/${label}?secret=${secret}&issuer=${encodeURIComponent(issuer)}&algorithm=SHA1&digits=6&period=${PERIOD}`;
+}
+/** Ten one-time recovery codes, for when the phone is lost: "k7f2-9qxm". */
+export function recoveryCodes(count = 10) {
+    const chars = 'abcdefghjkmnpqrstuvwxyz23456789';
+    const part = () => Array.from({ length: 4 }, () => chars[randomInt(chars.length)]).join('');
+    return Array.from({ length: count }, () => `${part()}-${part()}`);
+}

package/src/wordpress.d.ts

@@ -0,0 +1,87 @@
+import type { Media, RichText } from '@materializecms/core';
+import { type PageNode } from '@materializecms/core/page';
+/**
+ * WordPress, read: from a site's REST API (/wp-json, also with an application password for drafts
+ * and private pages) or from its export file (Strumenti → Esporta, WXR). Both become the same
+ * list of items, whatever built them (the block editor, Elementor, WPBakery, Divi…): the REST API
+ * gives each page as WordPress renders it, the export file its stored content without the
+ * page builders' shortcodes.
+ */
+export interface WpItem {
+    sourceId: string;
+    kind: 'post' | 'page';
+    title: string;
+    slug: string;
+    status: 'publish' | 'draft' | 'private' | 'pending' | 'future';
+    /** ISO date and time of publication. */
+    date: string;
+    /** The address on the WordPress site. */
+    link: string;
+    html: string;
+    excerpt: string;
+    featured?: {
+        url: string;
+        alt: string;
+    };
+    categories: string[];
+    tags: string[];
+    author?: string;
+    seo?: {
+        title?: string;
+        description?: string;
+    };
+}
+export interface WpSite {
+    name: string;
+    url: string;
+    items: WpItem[];
+}
+/** What reading needs from the network: the body as text, the status and the headers. */
+export type Fetcher = (url: string) => Promise<{
+    status: number;
+    headers: Headers;
+    text: string;
+}>;
+export declare class WordPressError extends Error {
+}
+/** HTML or entities to plain text: "Ciao &amp; benvenuti" → "Ciao & benvenuti". */
+export declare const plain: (html: string) => string;
+/**
+ * Reads a site through its REST API. `credentials` (user and application password, from the
+ * WordPress profile) also brings drafts and private items. `limit` stops early, to try.
+ */
+export declare function readRest(base: string, fetcher: Fetcher, options?: {
+    limit?: number;
+}): Promise<WpSite>;
+/** Reads the file of Strumenti → Esporta → Tutti i contenuti. */
+export declare function readWxr(xml: string): WpSite;
+/**
+ * Stored content of page builders is made of shortcodes ([vc_row], [et_pb_text]…): the marks go,
+ * the words and images inside them stay. Unknown wrappers too: they show nothing on their own.
+ */
+export declare function withoutShortcodes(html: string): string;
+/**
+ * The main content of a whole published page, as HTML: what a theme or a page builder shows
+ * between its header and its footer. Used when WordPress keeps the page outside its content
+ * (some themes, some page builders), so the API answers empty.
+ */
+export declare function mainContent(html: string): string;
+/** What the conversion needs from the import: where images and links now live. */
+export interface ConvertContext {
+    /** The library image for a WordPress image address, once downloaded. */
+    image: (url: string) => Media | undefined;
+    /** The new address for a link to the old site; other links stay as they are. */
+    link: (href: string) => string;
+}
+/** Every image address in some HTML, the original size first (WordPress adds "-1024x768"). */
+export declare function imagesIn(html: string): string[];
+/** The full-size original of a resized WordPress image: "foto-1024x768.jpg" → "foto.jpg". */
+export declare const originalOf: (url: string) => string;
+/** HTML to Materialize rich text: paragraphs, titles, lists, quotes and images (from the library). */
+export declare function htmlToRichText(html: string, ctx: ConvertContext): RichText;
+/**
+ * HTML to a page on the canvas, plainly laid out: a section for each main title, with its words,
+ * images and buttons in order. The layout of the original is redone afterwards (by hand or with
+ * the assistant); here nothing of the content is lost.
+ */
+export declare function htmlToPage(html: string, title: string, ctx: ConvertContext): PageNode[];