@materializecms/server 0.2.0 → 0.4.0

package/src/app.js

@@ -8,6 +8,7 @@ import { Readable } from 'node:stream';
 import { getConnInfo } from '@hono/node-server/conninfo';
 import { describeCollection, prepare, SLUG_PATTERN, slugify, titleOf, validate, } from '@materializecms/core';
 import { documentSlots, isLocaleCode, mergeTranslation, nodeSlots, untranslatedIds, withLocales, } from '@materializecms/core/i18n';
+import { senderDomain } from '@materializecms/core/mail';
 import { normalizeTheme, sameDesign } from '@materializecms/core/page';
 import { addMove, normalizePath } from '@materializecms/core/seo';
 import { TRACKING_PATTERNS, trackingBlocks } from '@materializecms/core/tracking';
@@ -27,9 +28,10 @@ import { AiError, complete, EMPTY_AI, isReady, publicAi, runTurn, translateTexts
 import { folderEntries, tarGz } from './archive.js';
 import { createBackups, DEFAULT_BACKUPS } from './backups.js';
 import { createFonts, FONT_FILE, FONT_ID } from './fonts.js';
-import { isConfigured, publicMail, sendMail, submissionText } from './mail.js';
+import { checkSenderDomain, explainMailError, isConfigured, publicMail, sendMail, submissionText, } from './mail.js';
 import { createMcpServer } from './mcp.js';
 import { createMediaFiles, fileBody, MAX_UPLOAD, MediaError, mediaUrl } from './media.js';
+import { DEFAULT_OFFSITE, newRecoveryKey, runOffsite, testOffsite, } from './offsite.js';
 import { hashPassword, verifyPassword } from './password.js';
 import { fetchPublicFile, RemoteError, remoteFetch } from './remote.js';
 import { statusPage } from './status-page.js';
@@ -203,8 +205,61 @@ export function createApp(base) {
         });
     };
     const backupFailed = (error) => console.error('Materialize: backup not made', error);
-    setTimeout(() => void autoBackup().catch(backupFailed), 60_000).unref?.();
-    setInterval(() => void autoBackup().catch(backupFailed), 60 * 60_000).unref?.();
+    // ---------- the copy outside the server (S3, WebDAV) ----------
+    const offsiteSettings = async () => ({
+        ...DEFAULT_OFFSITE,
+        ...(await settings.get('offsite')),
+    });
+    let offsiteRunning = false;
+    /** One run; the outcome is kept, and administrators hear by email the first time it fails. */
+    const offsiteRun = async (fresh) => {
+        if (offsiteRunning)
+            throw new ApiError(409, 'offsite_running', 'A copy is already being made');
+        offsiteRunning = true;
+        const before = await settings.get('offsite-status');
+        let status;
+        try {
+            status = await runOffsite(await offsiteSettings(), backups, ctx.config().media.dir, fresh);
+        }
+        catch (error) {
+            status = { at: new Date().toISOString(), ok: false, message: error.message };
+            if (before?.ok !== false)
+                for (const admin of (await auth.listUsers()).filter((u) => u.role === 'admin'))
+                    await mailNotice(admin.email, 'Backup fuori dal server non riuscito', [
+                        `La copia dei backup di ${ctx.config().site.name} fuori dal server non è riuscita: ${status.message}`,
+                        'Controlla in Impostazioni → Sicurezza → Backup. Ti scriviamo di nuovo solo quando torna a funzionare e si ferma di nuovo.',
+                    ]);
+        }
+        finally {
+            offsiteRunning = false;
+        }
+        await settings.set('offsite-status', status);
+        await activityLog.record({
+            userId: null,
+            userName: '',
+            action: status.ok ? 'backup.offsite' : 'backup.offsite_failed',
+            target: status.database ?? '',
+            detail: status.ok ? { media: status.media, fonts: status.fonts } : { message: status.message },
+            ip: null,
+        });
+        return status;
+    };
+    /** After the daily copy: once a day, unless the last run failed (then every hour until it works). */
+    const autoOffsite = async () => {
+        const s = await offsiteSettings();
+        if (s.kind === 'off' || !s.key || offsiteRunning)
+            return;
+        const last = await settings.get('offsite-status');
+        if (last?.ok && Date.now() - new Date(last.at).getTime() < 23 * 60 * 60_000)
+            return;
+        await offsiteRun(false);
+    };
+    const nightly = async () => {
+        await autoBackup().catch(backupFailed);
+        await autoOffsite().catch((error) => console.error('Materialize: offsite copy not made', error));
+    };
+    setTimeout(() => void nightly(), 60_000).unref?.();
+    setInterval(() => void nightly(), 60 * 60_000).unref?.();
     const updateSettings = async () => ({
         ...DEFAULT_UPDATES,
         ...(await settings.get('updates')),
@@ -980,7 +1035,35 @@ export function createApp(base) {
                         id: 'backups',
                         status: 'ok',
                         title: 'Backup del database ogni giorno',
-                        detail: `Ultima copia ${new Intl.RelativeTimeFormat('it', { numeric: 'auto' }).format(-Math.round(age / 3_600_000), 'hour')}, immagini comprese; ne restano ${b.keep}. Per una copia fuori dal server, scarica l’archivio completo.`,
+                        detail: `Ultima copia ${new Intl.RelativeTimeFormat('it', { numeric: 'auto' }).format(-Math.round(age / 3_600_000), 'hour')}, immagini comprese; ne restano ${b.keep}.`,
+                    });
+        }
+        {
+            const o = await offsiteSettings();
+            const status = await settings.get('offsite-status');
+            checks.push(o.kind === 'off' || !o.key
+                ? {
+                    id: 'offsite',
+                    status: 'warn',
+                    title: 'I backup restano sul server',
+                    detail: 'Se il server si rompe, si perdono anche le copie. Attiva la copia fuori dal server (S3 o WebDAV), oppure scarica ogni tanto l’archivio completo.',
+                    action: 'backups',
+                }
+                : status && !status.ok
+                    ? {
+                        id: 'offsite',
+                        status: 'bad',
+                        title: 'La copia fuori dal server non riesce',
+                        detail: status.message ?? 'Controlla il collegamento.',
+                        action: 'backups',
+                    }
+                    : {
+                        id: 'offsite',
+                        status: 'ok',
+                        title: 'Copia cifrata fuori dal server',
+                        detail: status
+                            ? `Ultima copia ${new Intl.RelativeTimeFormat('it', { numeric: 'auto' }).format(-Math.round((Date.now() - new Date(status.at).getTime()) / 3_600_000), 'hour')}, su ${o.kind === 's3' ? 'S3' : 'WebDAV'}.`
+                            : 'La prima copia parte entro un’ora.',
                     });
         }
         const tokens = await activityLog.tokens();
@@ -1047,6 +1130,100 @@ export function createApp(base) {
         await record(c, 'settings.backups', '', input);
         return c.json(await backupState());
     });
+    /** What the panel may see: no passwords, no secret key, no recovery key. */
+    const offsiteState = async () => {
+        const s = await offsiteSettings();
+        return {
+            kind: s.kind,
+            keep: s.keep,
+            hasKey: !!s.key,
+            s3: s.s3 ? { ...s.s3, secretAccessKey: '', hasSecret: !!s.s3.secretAccessKey } : undefined,
+            webdav: s.webdav ? { ...s.webdav, password: '', hasSecret: !!s.webdav.password } : undefined,
+            status: (await settings.get('offsite-status')) ?? null,
+            running: offsiteRunning,
+        };
+    };
+    const s3Input = z.object({
+        endpoint: z.url({ protocol: /^https?$/ }).max(300),
+        region: z.string().trim().max(60),
+        bucket: z.string().trim().min(1).max(200),
+        prefix: z.string().trim().max(200).optional(),
+        accessKeyId: z.string().trim().min(1).max(200),
+        // Empty: keep the saved one.
+        secretAccessKey: z.string().max(500),
+    });
+    const webdavInput = z.object({
+        url: z.url({ protocol: /^https?$/ }).max(500),
+        user: z.string().trim().max(200),
+        password: z.string().max(500),
+    });
+    const offsiteInput = z.object({
+        kind: z.enum(['off', 's3', 'webdav']),
+        keep: z.number().int().min(1).max(365),
+        s3: s3Input.optional(),
+        webdav: webdavInput.optional(),
+    });
+    /** The settings as sent, with the saved secrets where the panel left them empty. */
+    const withSecrets = (input, saved) => {
+        if (input.kind === 's3' && !input.s3)
+            throw new ApiError(400, 'missing_s3', 'S3 settings are missing');
+        if (input.kind === 'webdav' && !input.webdav)
+            throw new ApiError(400, 'missing_webdav', 'WebDAV settings are missing');
+        return {
+            kind: input.kind,
+            keep: input.keep,
+            key: saved.key,
+            s3: input.s3
+                ? { ...input.s3, secretAccessKey: input.s3.secretAccessKey || saved.s3?.secretAccessKey || '' }
+                : saved.s3,
+            webdav: input.webdav
+                ? { ...input.webdav, password: input.webdav.password || saved.webdav?.password || '' }
+                : saved.webdav,
+        };
+    };
+    app.get('/api/backups/offsite', requireUser, requireSession, requireAdmin, async (c) => c.json(await offsiteState()));
+    /** Saves where the copy goes; the first time, makes the recovery key and returns it, once. */
+    app.put('/api/backups/offsite', requireUser, requireSession, requireAdmin, async (c) => {
+        const next = withSecrets(await body(c, offsiteInput), await offsiteSettings());
+        let shown;
+        if (next.kind !== 'off' && !next.key)
+            next.key = shown = newRecoveryKey();
+        await settings.set('offsite', next, c.get('user').id);
+        await record(c, 'settings.offsite', next.kind);
+        return c.json({ ...(await offsiteState()), recoveryKey: shown });
+    });
+    app.post('/api/backups/offsite/test', requireUser, requireSession, requireAdmin, async (c) => {
+        try {
+            await testOffsite(withSecrets(await body(c, offsiteInput), await offsiteSettings()));
+            return c.json({ ok: true });
+        }
+        catch (error) {
+            if (error instanceof ApiError)
+                throw error;
+            return c.json({ ok: false, message: error.message });
+        }
+    });
+    /** "Esegui ora": a fresh copy of the database and whatever is missing, in the background. */
+    app.post('/api/backups/offsite/run', requireUser, requireSession, requireAdmin, async (c) => {
+        const s = await offsiteSettings();
+        if (s.kind === 'off' || !s.key)
+            throw new ApiError(409, 'offsite_off', 'The copy outside the server is off');
+        if (offsiteRunning)
+            throw new ApiError(409, 'offsite_running', 'A copy is already being made');
+        void offsiteRun(true).catch((error) => console.error('Materialize: offsite copy not made', error));
+        await record(c, 'backup.offsite_started');
+        return c.json(await offsiteState(), 202);
+    });
+    /** The recovery key again, for an administrator who confirms their password. */
+    app.post('/api/backups/offsite/key', requireUser, requireSession, requireAdmin, async (c) => {
+        const input = await body(c, z.object({ password: z.string().min(1).max(500) }));
+        await checkPassword(c.get('user').id, input.password);
+        const s = await offsiteSettings();
+        if (!s.key)
+            throw new ApiError(404, 'no_key', 'There is no recovery key yet');
+        await record(c, 'backup.key_shown');
+        return c.json({ recoveryKey: s.key });
+    });
     app.post('/api/backups', requireUser, requireSession, requireAdmin, async (c) => {
         if (!backups.available())
             throw new ApiError(409, 'backups_unavailable', 'The database is hosted: its provider keeps the backups');
@@ -1527,6 +1704,7 @@ export function createApp(base) {
                 pass: z.string().max(500).nullable().optional(),
                 from: z.string().max(200),
                 to: z.string().max(200),
+                provider: z.string().max(40).optional(),
             }),
         }));
         const before = await settings.get('mail');
@@ -1549,18 +1727,45 @@ export function createApp(base) {
             });
         }
         catch (error) {
-            throw new ApiError(422, 'mail_failed', error instanceof Error ? error.message : 'Sending failed');
+            // What went wrong and what to do, in words: a blocked port, a wrong password, an unverified sender…
+            return c.json({ ok: false, to, ...(await explainMailError(error, mail)) });
         }
         return c.json({ ok: true, to });
     });
+    /** The sender's domain as mail servers see it: SPF, DKIM, DMARC. */
+    app.post('/api/mail/domain', requireUser, requireSession, requireAdmin, async (c) => {
+        const input = await body(c, z.object({ from: z.string().max(200), provider: z.string().max(40).optional() }));
+        const domain = senderDomain(input.from);
+        if (!domain)
+            throw new ApiError(422, 'no_domain', 'Write the sender first, for example sito@example.com');
+        return c.json({ domain, checks: await checkSenderDomain(domain, input.provider) });
+    });
     // A form on the site: the message is kept, and sent by email when email is set up.
     // ---------- AI: settings, text actions and the editor's assistant ----------
     const aiSettings = async () => ({ ...EMPTY_AI, ...(await settings.get('ai')) });
+    const thisMonth = () => new Date().toISOString().slice(0, 7);
+    const monthUsage = async () => {
+        const saved = await settings.get('ai-usage');
+        const month = thisMonth();
+        return saved?.month === month ? saved : { month, requests: 0, input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+    };
+    // One write at a time: the steps of a turn and parallel requests all count.
+    let usageWrites = Promise.resolve();
+    const countUsage = (u) => {
+        usageWrites = usageWrites
+            .then(async () => {
+            const total = await monthUsage();
+            for (const k of ['requests', 'input', 'output', 'cacheRead', 'cacheWrite'])
+                total[k] += u[k];
+            await settings.set('ai-usage', total);
+        })
+            .catch((error) => console.error(error));
+    };
     const readyAi = async () => {
         const ai = await aiSettings();
         if (!isReady(ai))
             throw new ApiError(400, 'ai_not_configured', 'L’AI non è configurata: Impostazioni → AI e MCP');
-        return ai;
+        return { ...ai, onUsage: countUsage };
     };
     const aiFailed = (error) => {
         if (error instanceof AiError)
@@ -1570,7 +1775,7 @@ export function createApp(base) {
     const allowAi = createLimiter(40, 60_000);
     app.get('/api/ai', requireUser, async (c) => {
         const ai = await aiSettings();
-        return c.json(c.get('user').role === 'admin' ? { ai: publicAi(ai) } : { ai: { ready: isReady(ai) } });
+        return c.json(c.get('user').role === 'admin' ? { ai: publicAi(ai), usage: await monthUsage() } : { ai: { ready: isReady(ai) } });
     });
     app.put('/api/ai', requireUser, requireSession, requireAdmin, async (c) => {
         const input = await body(c, z.object({
@@ -1580,6 +1785,7 @@ export function createApp(base) {
                 apiKey: z.string().max(500).nullable().optional(),
                 baseUrl: z.union([z.url().max(500), z.literal('')]),
                 model: z.string().trim().max(120),
+                fastModel: z.string().trim().max(120).default(''),
             }),
         }));
         const before = await aiSettings();
@@ -1591,13 +1797,16 @@ export function createApp(base) {
     });
     app.post('/api/ai/test', requireUser, requireSession, requireAdmin, async (c) => {
         const ai = await readyAi();
-        const reply = await complete(ai, { system: 'Answer with one short word.', prompt: 'Say: ok' }).catch(aiFailed);
+        const probe = { system: 'Answer with one short word.', prompt: 'Say: ok' };
+        // Both models: a wrong name for the quick actions shows up here, not at the first ✨.
+        const reply = await complete(ai, probe).catch(aiFailed);
+        await complete(ai, { ...probe, fast: true }).catch(aiFailed);
         return c.json({ ok: true, reply });
     });
     const TEXT_ACTIONS = {
         rewrite: 'Rewrite it so it reads better: same meaning, similar length.',
-        shorten: 'Make it shorter, keeping what matters.',
-        expand: 'Make it a little longer and richer, without inventing facts.',
+        shorten: 'Make it shorter, keeping what matters most.',
+        expand: 'Make it longer and richer, without inventing facts.',
         fix: 'Fix spelling, grammar and punctuation only; change nothing else.',
         formal: 'Make the tone more formal and professional.',
         friendly: 'Make the tone warmer and more conversational.',
@@ -1614,6 +1823,10 @@ export function createApp(base) {
             src: z.string().max(1000).optional(),
             /** The site's language, for texts written from scratch. */
             locale: z.string().max(20).optional(),
+            /** rich: the text is rich text as lines of markup (richTextMarkup), and so is the reply. */
+            format: z.enum(['plain', 'rich']).default('plain'),
+            /** The most characters the field takes. */
+            max: z.number().int().positive().max(100_000).optional(),
         }));
         if (!allowAi(c.get('user').id))
             throw new ApiError(429, 'too_many_requests', 'Troppe richieste: aspetta un minuto');
@@ -1626,9 +1839,14 @@ export function createApp(base) {
             if (!file)
                 throw new ApiError(400, 'no_image', 'Scegli prima un’immagine della libreria');
             const data = (await readFile(file.path)).toString('base64');
+            // The text already there may credit the photographer or the source: that part stays.
+            const current = input.text.trim()
+                ? `\n\nThe current alternative text is:\n<text>\n${input.text}\n</text>\nWrite in its language. If it credits a photographer, an author or a source (such as "photo by … on Unsplash"), keep that credit at the end, in the same form.`
+                : '';
             const text = await complete(ai, {
                 system,
-                prompt: `Write the alternative text (alt) for this image on a website, in the language with code "${lang}": one sentence, at most 125 characters, describing what matters for someone who cannot see it. No "image of".`,
+                fast: true,
+                prompt: `Write the alternative text (alt) for this image on a website, in the language with code "${lang}"${current ? ' unless said otherwise below' : ''}: one sentence, at most 125 characters (besides any credit), describing what matters for someone who cannot see it. No "image of".${current}`,
                 image: { data, mime: 'image/jpeg' },
             }).catch(aiFailed);
             return c.json({ text });
@@ -1640,7 +1858,37 @@ export function createApp(base) {
             : input.action === 'custom'
                 ? (input.instruction ?? 'Improve it.')
                 : TEXT_ACTIONS[input.action];
-        const text = await complete(ai, { system, prompt: `${task}\n\n<text>\n${input.text}\n</text>` }).catch(aiFailed);
+        const rich = input.format === 'rich'
+            ? '\n\nThe text is markup, one block per line: <p>, <h2>, <h3>, <h4>, <blockquote>, <li>, with <b>, <i> and numbered links (<a1>…</a1>) inside, and <img1>, <img2>… for images. Reply in the same markup: you may change, merge, split or add blocks; keep each link around the matching words and every image line.'
+            : '';
+        // Shorter and longer by how much: as words, small models barely touch a short text or
+        // multiply it. A length in characters (the words alone, without markup) they follow.
+        const length = input.text.replace(/<[^>]+>/g, '').length;
+        let max = input.max;
+        let target = '';
+        if (input.action === 'shorten') {
+            target = `\n\nThe text has ${length} characters: aim for about ${Math.round(length * 0.65)}.`;
+            max = Math.min(max ?? Number.POSITIVE_INFINITY, Math.round(length * 0.8));
+        }
+        else if (input.action === 'expand')
+            target = `\n\nThe text has ${length} characters: aim for about ${Math.round(length * 1.5)}, never more than ${length * 2}.`;
+        const limit = max ? `\n\nThe result must be at most ${max} characters, spaces included.` : '';
+        let text = await complete(ai, {
+            system,
+            fast: true,
+            prompt: `${task}${target}${limit}${rich}\n\n<text>\n${input.text}\n</text>`,
+        }).catch(aiFailed);
+        // Models count characters loosely: another pass when the result is too long, then one on the
+        // main model when the quick one still does not get there (a small model may return the text as is).
+        for (const fast of [true, false]) {
+            if (!max || input.format !== 'plain' || text.length <= max)
+                break;
+            text = await complete(ai, {
+                system,
+                fast,
+                prompt: `Shorten this text to at most ${max} characters, spaces included (it has ${text.length}), keeping its meaning and tone.\n\n<text>\n${text}\n</text>`,
+            }).catch(aiFailed);
+        }
         return c.json({ text });
     });
     /** Conversations with the assistant, per person and chat, kept for two hours in memory. */
@@ -1657,6 +1905,14 @@ export function createApp(base) {
                 url: z.string().max(500).nullish(),
             }),
             selected: z.array(z.string().max(100)).max(50).optional(),
+            /** Reference pictures (a screenshot, a mockup, a sketch), already made smaller by the panel. */
+            images: z
+                .array(z.object({
+                mime: z.enum(['image/png', 'image/jpeg', 'image/webp']),
+                data: z.base64().max(4_000_000),
+            }))
+                .max(4)
+                .default([]),
         }));
         const user = c.get('user');
         if (!allowAi(user.id))
@@ -1682,17 +1938,24 @@ export function createApp(base) {
             auth.cookie = cookie;
         const tools = assistantTools(apiCaller(app.fetch, auth), page, ctx.config().site.name);
         const limited = await contentOnly(user);
-        const system = `You are the assistant inside Materialize, the visual editor of the website "${ctx.config().site.name}". The person (${user.name}) is editing the page "${input.page.title}" (collection ${input.page.collection}${input.page.url ? `, address ${input.page.url}` : ''}).
+        // The instructions stay the same for the whole conversation: the model's earlier reasoning is
+        // tied to them (a change is refused) and they are read from the prompt cache. What changes
+        // from turn to turn, the page and what is selected, goes with each message instead.
+        const system = `You are the assistant inside Materialize, the visual editor of the website "${ctx.config().site.name}". The person (${user.name}) is editing a page; each of their messages starts with a <context> note on the page and on what is selected on the canvas.
 Use the tools to look at the page (get_page, get_node) and change it (edit_page). Your changes go into the editor, where the person sees them at once and can undo them; they are not published.
 Read the page before changing it. Make the changes asked, consistent with the design already there (theme colors and text styles, spacing, the look of nearby sections); prefer the section library for new sections. Keep ids of existing nodes.
-${limited ? 'This person may change only contents (texts, links, images, alt texts), not the layout or the design: do not add, remove or move nodes, and do not change styles.\n' : ''}When done, say in one or two short sentences what you changed. Reply in the person's language. If something cannot be done with the tools, say so.
-${input.selected?.length ? `Selected on the canvas: ${input.selected.join(', ')} (what "this" refers to).` : ''}`;
+${limited ? 'This person may change only contents (texts, links, images, alt texts), not the layout or the design: do not add, remove or move nodes, and do not change styles.\n' : ''}Pictures the person attaches are references (a site they like, a mockup, a sketch): take their layout, hierarchy and mood, and build it with this site's sections, theme and texts; never copy their brand, logos or texts, and do not put the pictures on the page.
+When done, say in one or two short sentences what you changed. Reply in the person's language. If something cannot be done with the tools, say so.`;
+        const context = `<context>Page "${input.page.title}" (collection ${input.page.collection}${input.page.url ? `, address ${input.page.url}` : ''}). ${input.selected?.length
+            ? `Selected on the canvas: ${input.selected.join(', ')} (what "this" refers to).`
+            : 'Nothing selected on the canvas.'}</context>`;
         return streamSSE(c, async (stream) => {
             const send = (data) => stream.writeSSE({ data: JSON.stringify(data) });
             try {
                 const reply = await runTurn(ai, conv, {
                     system,
-                    text: input.message,
+                    text: `${context}\n\n${input.message}`,
+                    images: input.images,
                     tools,
                     onEvent: (e) => void send(e),
                 });
@@ -2044,7 +2307,13 @@ ${input.selected?.length ? `Selected on the canvas: ${input.selected.join(', ')}
     });
     app.get('/api/documents/:id/revisions', requireUser, async (c) => {
         const existing = await loadDocument(c.req.param('id'));
-        return c.json({ items: await content.revisions(existing.id) });
+        // Who made each version, by name; null for a person removed since (and for versions with no author).
+        const names = new Map((await auth.listUsers()).map((u) => [u.id, u.name]));
+        const items = (await content.revisions(existing.id)).map((r) => ({
+            ...r,
+            authorName: r.authorId ? (names.get(r.authorId) ?? null) : null,
+        }));
+        return c.json({ items });
     });
     app.post('/api/documents/:id/revisions/:revision/restore', requireUser, async (c) => {
         const existing = await loadDocument(c.req.param('id'));

package/src/index.d.ts

@@ -9,6 +9,7 @@ export { restoreMedia } from './backups.ts';
 export { createFonts, type FontInfo, type Fonts } from './fonts.ts';
 export { createMcpServer, registerTools } from './mcp.ts';
 export { createMediaFiles, type MediaFiles } from './media.ts';
+export { decryptTree, type OffsiteSettings, parseRecoveryKey } from './offsite.ts';
 export { hashPassword, verifyPassword } from './password.ts';
 export { apiCaller, siteTools } from './tools.ts';
 /** Serves the public site: every request outside /api, /admin and /media goes here. */

package/src/index.js

@@ -10,6 +10,7 @@ export { restoreMedia } from './backups.js';
 export { createFonts } from './fonts.js';
 export { createMcpServer, registerTools } from './mcp.js';
 export { createMediaFiles } from './media.js';
+export { decryptTree, parseRecoveryKey } from './offsite.js';
 export { hashPassword, verifyPassword } from './password.js';
 export { apiCaller, siteTools } from './tools.js';
 const OWN = /^\/(api|admin|media|fonts|mcp)(\/|\?|$)/;

package/src/mail.d.ts

@@ -10,6 +10,8 @@ export interface MailSettings {
     from: string;
     /** Where messages from the site's forms arrive. */
     to: string;
+    /** The provider chosen in the panel (core/mail.ts), or empty for "another one". */
+    provider?: string;
 }
 export declare const EMPTY_MAIL: MailSettings;
 export declare function isConfigured(m: MailSettings | null): m is MailSettings;
@@ -21,6 +23,7 @@ export declare function publicMail(m: MailSettings | null): {
     user: string;
     from: string;
     to: string;
+    provider?: string;
     hasPassword: boolean;
 };
 export declare function sendMail(m: MailSettings, message: {
@@ -31,3 +34,27 @@ export declare function sendMail(m: MailSettings, message: {
 }): Promise<void>;
 /** A message from a site form as plain text: one "Label: value" per field. */
 export declare function submissionText(page: string, data: Record<string, string>): string;
+/** Whether the server answers on a port at all: the way to tell a blocked port from a wrong setting. */
+export declare function portOpen(host: string, port: number, timeout?: number): Promise<boolean>;
+export interface MailProblem {
+    message: string;
+    /** What to do about it. */
+    hint?: string;
+}
+/**
+ * A sending error from nodemailer, explained: wrong server name, a port the hosting blocks (then
+ * the ports that do answer), security that does not match the port, credentials refused, a sender
+ * the provider has not verified, a limit reached.
+ */
+export declare function explainMailError(error: unknown, m: MailSettings): Promise<MailProblem>;
+export interface DomainCheck {
+    id: 'spf' | 'dkim' | 'dmarc';
+    state: 'ok' | 'warn' | 'bad' | 'info';
+    title: string;
+    detail: string;
+}
+/**
+ * What mail servers check before trusting a message from this domain. Without SPF and DKIM the
+ * messages tend to end in spam; Gmail and Yahoo also ask for DMARC from whoever sends a lot.
+ */
+export declare function checkSenderDomain(domain: string, providerId?: string): Promise<DomainCheck[]>;