@materializecms/server 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -4,6 +4,12 @@ Ogni versione, dalla più recente. Le novità in arrivo si scrivono sotto «Pros
 
 ## Prossima versione
 
+## 0.7.0 — 2026-11-06
+
+- **Tour del pannello**: la prima volta che entri, un tour mostra il pannello una zona alla volta, come quello dell'editor. Si rifà dal menu del profilo (**Tour del pannello**) o cercando «tour» con ⌘K.
+- **Newsletter**: raccogli iscritti dal sito con doppia conferma via email, importali da Mailchimp o Brevo, scrivi la newsletter da zero, da un articolo o con l'AI dagli ultimi articoli, provala su di te e mandala subito o a un'ora stabilita. Ogni email ha il link per disiscriversi; per ogni invio vedi aperture e clic. Nuova voce **Newsletter** nella barra laterale.
+- Le sezioni «Invito → Newsletter» e «Footer → Con iscrizione» della libreria hanno un modulo vero, collegato alla newsletter.
+- **Pannello in inglese, prima parte**: ognuno può scegliere l'inglese nel profilo (o nella pagina di accesso); per ora sono tradotti accesso, barra laterale, panoramica e profilo. Finché la traduzione non è completa il pannello parte in italiano per tutti.
 ## 0.6.0 — 2026-11-06
 
 - **Panoramica rinnovata**: si apre su quello che c'è da fare (documenti da pubblicare, il rilascio in preparazione, la prossima uscita programmata, i messaggi nuovi), con un riepilogo in una frase, le ultime modifiche e il sito a colpo d'occhio.

package/README.md

@@ -1,3 +1,5 @@
+<img src="https://raw.githubusercontent.com/materializecms/materialize/main/docs/assets/logo-icon.svg" alt="Materialize" width="48" height="48">
+
 # @materializecms/server
 
 Il server di Materialize: API, accessi, media, backup, aggiornamenti dal pannello e server MCP.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@materializecms/server",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Il server di Materialize: API, accessi, media, backup, aggiornamenti dal pannello e server MCP.",
   "type": "module",
   "license": "MIT",
@@ -20,9 +20,9 @@
   "dependencies": {
     "@anthropic-ai/sdk": "1.3.0",
     "@hono/node-server": "2.1.5",
-    "@materializecms/admin": "0.6.0",
-    "@materializecms/core": "0.6.0",
-    "@materializecms/db": "0.6.0",
+    "@materializecms/admin": "0.7.0",
+    "@materializecms/core": "0.7.0",
+    "@materializecms/db": "0.7.0",
     "@modelcontextprotocol/sdk": "1.32.2",
     "hono": "4.13.14",
     "htmlparser2": "12.0.0",

package/src/app.d.ts

@@ -31,5 +31,6 @@ export interface ServerContext {
 }
 export declare function createApp(base: ServerContext): Hono<Env, import("hono/types").BlankSchema, "/"> & {
     runSchedules: (now?: Date) => Promise<number>;
+    runNewsletters: (now?: Date, pause?: number) => Promise<number>;
 };
 export {};

package/src/app.js

@@ -9,12 +9,12 @@ 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 { expandComponents, expandGlobals, formDefinition, normalizeTheme, sameDesign, walk, } from '@materializecms/core/page';
-import { addMove, normalizePath } from '@materializecms/core/seo';
+import { expandComponents, expandGlobals, formDefinition, normalizeTheme, richTextHtml, sameDesign, walk, } from '@materializecms/core/page';
+import { addMove, feedCollections, normalizePath } from '@materializecms/core/seo';
 import { TRACKING_PATTERNS, trackingBlocks } from '@materializecms/core/tracking';
 import { DEFAULT_UPDATES, isPatch, } from '@materializecms/core/updates';
 import { VOICE_TONES, voicePrompt } from '@materializecms/core/voice';
-import { createActivityStore, createAuthStore, createCommentStore, createContentStore, createMediaStore, createPreviewLinkStore, createReleaseStore, createScheduleStore, createSettingsStore, createSubmissionStore, EmailTakenError, SlugTakenError, } from '@materializecms/db';
+import { createActivityStore, createAuthStore, createCommentStore, createContentStore, createMediaStore, createNewsletterStore, createPreviewLinkStore, createReleaseStore, createScheduleStore, createSettingsStore, createSubmissionStore, EmailTakenError, SlugTakenError, } from '@materializecms/db';
 import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
 import { Hono } from 'hono';
 import { bodyLimit } from 'hono/body-limit';
@@ -34,6 +34,7 @@ import { fingerprintOf, readSubmission, removeFiles, saveFiles, sendWebhook, spa
 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 { confirmEmail, langOf, linkSignature, newsletterHtml, newsletterText, PIXEL, parseSubscribersCsv, validLink, } from './newsletter.js';
 import { DEFAULT_OFFSITE, newRecoveryKey, runOffsite, testOffsite, } from './offsite.js';
 import { hashPassword, verifyPassword } from './password.js';
 import { fetchPublicFile, RemoteError, remoteFetch } from './remote.js';
@@ -194,6 +195,7 @@ export function createApp(base) {
     const activityLog = createActivityStore(ctx.database.db);
     const schedules = createScheduleStore(ctx.database.db);
     const releases = createReleaseStore(ctx.database.db);
+    const newsletter = createNewsletterStore(ctx.database.db);
     const previewLinks = createPreviewLinkStore(ctx.database.db);
     const backups = createBackups(ctx.database, () => ctx.config().media.dir);
     const backupSettings = async () => ({
@@ -504,7 +506,9 @@ export function createApp(base) {
     app.use('*', secureHeaders());
     // Requests with a bearer token carry no cookie, so a forged form cannot ride on them.
     const checkOrigin = csrf();
-    app.use('/api/*', (c, next) => (bearerOf(c) ? next() : checkOrigin(c, next)));
+    app.use('/api/*', (c, next) => 
+    // Leaving the newsletter with one click from the email app comes with no Origin: the token is the proof.
+    bearerOf(c) || c.req.path.startsWith('/api/newsletter/unsubscribe/') ? next() : checkOrigin(c, next));
     // Answers change with every edit: browsers must not reuse them.
     app.use('/api/*', async (c, next) => {
         await next();
@@ -898,7 +902,7 @@ export function createApp(base) {
     const ACTIVITY_GROUPS = {
         access: ['login.', 'logout', 'session.', 'twofactor.', 'token.', 'security.', 'password.'],
         people: ['user.'],
-        content: ['document.', 'release.', 'site.', 'media.', 'message.'],
+        content: ['document.', 'release.', 'site.', 'newsletter.', 'import.', 'media.', 'message.'],
         settings: ['settings.', 'backup.', 'update.'],
     };
     app.get('/api/activity', requireUser, requireAdmin, async (c) => {
@@ -1357,7 +1361,11 @@ export function createApp(base) {
         return c.json({ ok: true });
     });
     app.patch('/api/auth/me', requireUser, async (c) => {
-        const input = await body(c, z.object({ name: z.string().trim().min(1).max(80) }));
+        const input = await body(c, z.object({
+            name: z.string().trim().min(1).max(80).optional(),
+            /** The panel's language; null: follow the browser. */
+            locale: z.enum(['it', 'en']).nullable().optional(),
+        }));
         return c.json({ user: await auth.updateUser(c.get('user').id, input) });
     });
     /** A changed sign-in address: the old one is told, in case it was not its owner who changed it. */
@@ -2485,6 +2493,12 @@ When done, say in one or two short sentences what you changed. Reply in the pers
         const fingerprint = fingerprintOf(form, data);
         const spam = spamReason(data, elapsed) ??
             ((await submissions.seen(fingerprint, new Date(Date.now() - 86_400_000))) ? 'Messaggio ripetuto' : null);
+        // A signup form: no message, a subscriber waiting to confirm. Spam gets the same answer.
+        if (def?.newsletter) {
+            if (!spam)
+                await signUp(c, def, data, page);
+            return wantsJson ? c.json({ ok: true }) : c.redirect(`${back}#inviato`, 303);
+        }
         const formName = def?.name?.trim() || def?.subject?.trim() || '';
         const saved = await submissions.add({ form, formName, page, data, spam, fingerprint });
         if (files.length)
@@ -3235,6 +3249,505 @@ When done, say in one or two short sentences what you changed. Reply in the pers
         await record(c, 'release.scheduled', release.name, { id: release.id, at: at.toISOString() });
         return c.json(await releaseJson(await loadRelease(release.id)));
     });
+    // ---------- newsletter ----------
+    const escapeHtml = (v) => v.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+    const newsletterSettings = async () => (await settings.get('newsletter')) ?? {};
+    /** The secret that signs tracked links, made the first time it is needed. */
+    const newsletterSecret = async () => {
+        const found = await settings.get('newsletter:secret');
+        if (found)
+            return found;
+        const secret = randomBytes(24).toString('base64url');
+        await settings.set('newsletter:secret', secret);
+        return secret;
+    };
+    /** Where links in newsletters point: the site's address, or the one last used in the panel. */
+    const newsletterOrigin = async (c) => {
+        if (c) {
+            const origin = publicOrigin(c);
+            const current = await newsletterSettings();
+            if (current.origin !== origin)
+                await settings.set('newsletter', { ...current, origin });
+            return origin;
+        }
+        const site = ctx.config().site.url;
+        try {
+            if (site)
+                return new URL(site).origin;
+        }
+        catch { }
+        return (await newsletterSettings()).origin ?? 'http://localhost:4321';
+    };
+    const accentColor = async () => normalizeTheme(await settings.get('theme')).colors.light.accent;
+    const allowSignup = createLimiter(5, 60_000);
+    /** A signup from a form: the email field, a name if there is one, and the confirmation email. */
+    const signUp = async (c, def, data, page) => {
+        const field = def.fields.find((f) => f.kind === 'email') ?? def.fields.find((f) => /mail/i.test(f.name));
+        const email = (field ? data[field.name] : '')?.trim().toLowerCase() ?? '';
+        if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email))
+            return;
+        if (!allowSignup(`${clientIp(c)}:newsletter`))
+            return;
+        const nameField = def.fields.find((f) => f.kind !== 'email' && /^(nome|name|first.?name)$/i.test(f.name));
+        const { subscriber, confirm } = await newsletter.subscribe({
+            email,
+            name: nameField ? data[nameField.name] : '',
+            locale: langOf(c.req.header('accept-language')),
+            source: page || def.name || def.id,
+        });
+        if (!confirm)
+            return;
+        const mail = await settings.get('mail');
+        if (!isConfigured(mail)) {
+            console.warn('Materialize: a newsletter signup waits for confirmation, but email is not set up');
+            return;
+        }
+        const url = `${await newsletterOrigin()}/api/newsletter/confirm/${subscriber.token}`;
+        const message = confirmEmail({
+            site: ctx.config().site.name,
+            url,
+            accent: await accentColor(),
+            locale: subscriber.locale,
+        });
+        await sendMail(mail, { to: email, ...message }).catch((error) => console.error('Materialize: confirmation email not sent', error));
+    };
+    /** A small page for people coming from an email link: no panel, the site's name and a sentence. */
+    const notice = (c, lang, title, text, form) => c.html(`<!doctype html><html lang="${lang}"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta name="robots" content="noindex"><title>${escapeHtml(title)}</title>
+<style>body{margin:0;min-height:100vh;display:grid;place-items:center;background:#f4f4f5;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Helvetica,Arial,sans-serif;color:#18181b}main{max-width:420px;margin:24px;padding:32px;background:#fff;border-radius:14px;box-shadow:0 1px 3px rgba(0,0,0,.08)}h1{margin:0 0 10px;font-size:22px}p{margin:0 0 16px;line-height:1.6;color:#52525b}button{padding:11px 18px;border:0;border-radius:8px;background:#18181b;color:#fff;font:inherit;font-weight:600;cursor:pointer}a{color:inherit}</style></head>
+<body><main><p style="font-weight:700;color:#18181b">${escapeHtml(ctx.config().site.name)}</p><h1>${escapeHtml(title)}</h1><p>${escapeHtml(text)}</p>${form ?? ''}<p><a href="/">${lang === 'it' ? 'Vai al sito' : 'Go to the site'}</a></p></main></body></html>`);
+    app.get('/api/newsletter/confirm/:token', async (c) => {
+        const lang = langOf(c.req.header('accept-language'));
+        const found = await newsletter.confirm(c.req.param('token'));
+        if (!found)
+            return notice(c, lang, lang === 'it' ? 'Link non valido' : 'Link not valid', lang === 'it'
+                ? 'Questo link non funziona più. Iscriviti di nuovo dal sito, se vuoi ricevere la newsletter.'
+                : 'This link no longer works. Sign up again on the site if you want the newsletter.');
+        return notice(c, langOf(found.locale), langOf(found.locale) === 'it' ? 'Iscrizione confermata' : 'Subscription confirmed', langOf(found.locale) === 'it'
+            ? `Da ora riceverai la newsletter di ${ctx.config().site.name} a ${found.email}. Puoi disiscriverti quando vuoi, dal link in fondo a ogni email.`
+            : `From now on you will get the ${ctx.config().site.name} newsletter at ${found.email}. You can unsubscribe whenever you like, from the link at the bottom of every email.`);
+    });
+    // A page with a button, so that link scanners opening the address do not unsubscribe anyone;
+    // email apps' one-click unsubscribe posts to the same address (RFC 8058).
+    app.get('/api/newsletter/unsubscribe/:token', async (c) => {
+        const found = await newsletter.byToken(c.req.param('token'));
+        const lang = langOf(found?.locale ?? c.req.header('accept-language'));
+        if (!found)
+            return notice(c, lang, lang === 'it' ? 'Link non valido' : 'Link not valid', lang === 'it' ? 'Questo link non funziona.' : 'This link does not work.');
+        if (found.status === 'unsubscribed')
+            return notice(c, lang, lang === 'it' ? 'Sei già disiscritto' : 'You are already unsubscribed', lang === 'it'
+                ? `${found.email} non riceve più la newsletter.`
+                : `${found.email} no longer gets the newsletter.`);
+        const send = c.req.query('s') ?? '';
+        return notice(c, lang, lang === 'it' ? 'Disiscriviti dalla newsletter' : 'Unsubscribe from the newsletter', lang === 'it'
+            ? `${found.email} non riceverà più la newsletter di ${ctx.config().site.name}.`
+            : `${found.email} will no longer get the ${ctx.config().site.name} newsletter.`, `<form method="post"><input type="hidden" name="s" value="${escapeHtml(send)}"><p><button type="submit">${lang === 'it' ? 'Disiscrivimi' : 'Unsubscribe me'}</button></p></form>`);
+    });
+    app.post('/api/newsletter/unsubscribe/:token', async (c) => {
+        const found = await newsletter.byToken(c.req.param('token'));
+        const lang = langOf(found?.locale ?? c.req.header('accept-language'));
+        if (!found)
+            return notice(c, lang, lang === 'it' ? 'Link non valido' : 'Link not valid', '');
+        const form = (await c.req.parseBody().catch(() => ({})));
+        const send = typeof form.s === 'string' ? form.s : (c.req.query('s') ?? '');
+        if (found.status !== 'unsubscribed') {
+            await newsletter.unsubscribe(found.id);
+            const sent = send ? await newsletter.send(send) : null;
+            if (sent && sent.subscriberId === found.id)
+                await newsletter.track(sent.id, 'unsubscribe');
+        }
+        return notice(c, lang, lang === 'it' ? 'Fatto: sei disiscritto' : 'Done: you are unsubscribed', lang === 'it'
+            ? 'Non riceverai più la newsletter. Se cambi idea, puoi iscriverti di nuovo dal sito.'
+            : 'You will not get the newsletter any more. If you change your mind, you can sign up again on the site.');
+    });
+    /** Statistics: the picture that tells the email was opened. */
+    app.get('/api/newsletter/o/:send', async (c) => {
+        const id = c.req.param('send').replace(/\.gif$/, '');
+        if ((await newsletterSettings()).tracking !== false && (await newsletter.send(id)))
+            await newsletter.track(id, 'open');
+        return c.body(new Uint8Array(PIXEL), 200, { 'content-type': 'image/gif', 'cache-control': 'no-store' });
+    });
+    /** Statistics: a link followed, then on to where it points (only addresses this site signed). */
+    app.get('/api/newsletter/c/:send', async (c) => {
+        const id = c.req.param('send');
+        const url = c.req.query('u') ?? '';
+        if (!/^https?:\/\//i.test(url) || !validLink(id, url, c.req.query('s') ?? '', await newsletterSecret()))
+            return c.text('Link not valid', 400);
+        if (await newsletter.send(id))
+            await newsletter.track(id, 'click');
+        return c.redirect(url, 302);
+    });
+    // ----- panel: subscribers -----
+    app.get('/api/subscribers', requireUser, async (c) => {
+        const status = c.req.query('status');
+        return c.json(await newsletter.subscribers({
+            status: status === 'pending' || status === 'active' || status === 'unsubscribed' ? status : undefined,
+            search: c.req.query('search') || undefined,
+            limit: Math.min(200, Number(c.req.query('limit') ?? 50)),
+            offset: Number(c.req.query('offset') ?? 0),
+        }));
+    });
+    /** Someone added by hand gets the confirmation email too: consent is theirs to give. */
+    app.post('/api/subscribers', requireUser, requireAdmin, async (c) => {
+        const input = await body(c, z.object({ email: z.email(), name: z.string().trim().max(120).optional() }));
+        const { subscriber, confirm } = await newsletter.subscribe({ ...input, source: 'panel', locale: null });
+        let mailed = false;
+        if (confirm) {
+            const mail = await settings.get('mail');
+            if (isConfigured(mail)) {
+                const url = `${await newsletterOrigin(c)}/api/newsletter/confirm/${subscriber.token}`;
+                await sendMail(mail, {
+                    to: subscriber.email,
+                    ...confirmEmail({
+                        site: ctx.config().site.name,
+                        url,
+                        accent: await accentColor(),
+                        locale: ctx.config().locales.default,
+                    }),
+                });
+                mailed = true;
+            }
+        }
+        await record(c, 'newsletter.subscriber_added', subscriber.email);
+        return c.json({ subscriber, mailed }, 201);
+    });
+    app.delete('/api/subscribers/:id', requireUser, requireAdmin, async (c) => {
+        const found = await newsletter.subscriber(c.req.param('id'));
+        if (!found)
+            throw new ApiError(404, 'not_found', 'Questo iscritto non esiste');
+        await newsletter.removeSubscriber(found.id);
+        await record(c, 'newsletter.subscriber_removed', found.email);
+        return c.body(null, 204);
+    });
+    app.post('/api/subscribers/import', requireUser, requireAdmin, async (c) => {
+        const input = await body(c, z.object({ csv: z.string().max(5_000_000) }));
+        const rows = parseSubscribersCsv(input.csv);
+        if (!rows.length)
+            throw new ApiError(422, 'no_addresses', 'Nel file non ho trovato indirizzi email');
+        const result = await newsletter.importMany(rows);
+        await record(c, 'newsletter.imported', '', result);
+        return c.json({ found: rows.length, ...result });
+    });
+    app.get('/api/subscribers/export.csv', requireUser, requireAdmin, async (c) => {
+        const cell = (v) => {
+            const safe = /^[=+\-@\t\r]/.test(v) ? `'${v}` : v;
+            return /[",;\n]/.test(safe) ? `"${safe.replace(/"/g, '""')}"` : safe;
+        };
+        const rows = (await newsletter.allSubscribers()).map((s) => [
+            s.email,
+            s.name,
+            s.status,
+            s.source,
+            s.createdAt.toISOString(),
+            s.confirmedAt?.toISOString() ?? '',
+            s.unsubscribedAt?.toISOString() ?? '',
+        ]
+            .map(cell)
+            .join(','));
+        const csv = `email,name,status,source,created,confirmed,unsubscribed\n${rows.join('\n')}\n`;
+        await record(c, 'newsletter.exported', '', { subscribers: rows.length });
+        return c.body(csv, 200, {
+            'content-type': 'text/csv; charset=utf-8',
+            'content-disposition': 'attachment; filename="iscritti.csv"',
+        });
+    });
+    app.get('/api/newsletter/settings', requireUser, async (c) => {
+        const s = await newsletterSettings();
+        return c.json({ footer: s.footer ?? '', tracking: s.tracking !== false });
+    });
+    app.put('/api/newsletter/settings', requireUser, requireAdmin, async (c) => {
+        const input = await body(c, z.object({ footer: z.string().max(1000), tracking: z.boolean() }));
+        await settings.set('newsletter', { ...(await newsletterSettings()), ...input });
+        await record(c, 'settings.newsletter');
+        return c.json(input);
+    });
+    // ----- panel: newsletters -----
+    const newsletterJson = async (n) => ({ ...n, stats: await newsletter.stats(n.id) });
+    const loadNewsletter = async (id) => {
+        const found = await newsletter.get(id);
+        if (!found)
+            throw new ApiError(404, 'not_found', 'Questa newsletter non esiste');
+        return found;
+    };
+    const editable = (n) => {
+        if (n.status === 'sending' || n.status === 'sent')
+            throw new ApiError(409, 'newsletter_sent', 'Questa newsletter è già partita: non si può più cambiare');
+    };
+    const newsletterBody = z.object({
+        subject: z.string().trim().min(1).max(200),
+        preheader: z.string().max(200).default(''),
+        body: z.array(z.record(z.string(), z.unknown())).max(2000).default([]),
+    });
+    app.get('/api/newsletters', requireUser, async (c) => c.json({ newsletters: await Promise.all((await newsletter.list()).map(newsletterJson)) }));
+    app.post('/api/newsletters', requireUser, async (c) => {
+        const input = await body(c, newsletterBody);
+        const created = await newsletter.create({ ...input, user: c.get('user') });
+        await record(c, 'newsletter.created', created.subject);
+        return c.json(await newsletterJson(created), 201);
+    });
+    app.get('/api/newsletters/:id', requireUser, async (c) => c.json(await newsletterJson(await loadNewsletter(c.req.param('id')))));
+    app.put('/api/newsletters/:id', requireUser, async (c) => {
+        const found = await loadNewsletter(c.req.param('id'));
+        editable(found);
+        const input = await body(c, newsletterBody);
+        await newsletter.update(found.id, input);
+        return c.json(await newsletterJson(await loadNewsletter(found.id)));
+    });
+    app.delete('/api/newsletters/:id', requireUser, async (c) => {
+        const found = await loadNewsletter(c.req.param('id'));
+        if (found.status === 'sending')
+            throw new ApiError(409, 'newsletter_sending', 'La newsletter sta partendo: aspetta che finisca');
+        await newsletter.remove(found.id);
+        await record(c, 'newsletter.deleted', found.subject);
+        return c.body(null, 204);
+    });
+    /** The email for one send: links, picture and unsubscribe address made for that person. */
+    const composeNewsletter = async (n, send) => {
+        const origin = await newsletterOrigin();
+        const s = await newsletterSettings();
+        const tracking = !!send && s.tracking !== false;
+        const secret = tracking ? await newsletterSecret() : '';
+        const unsubscribeUrl = send
+            ? `${origin}/api/newsletter/unsubscribe/${send.token}?s=${encodeURIComponent(send.id)}`
+            : `${origin}/api/newsletter/unsubscribe/prova`;
+        const content = {
+            site: ctx.config().site.name,
+            siteUrl: origin,
+            subject: n.subject,
+            preheader: n.preheader,
+            body: n.body,
+            accent: await accentColor(),
+            footer: s.footer ?? '',
+            unsubscribeUrl,
+            locale: send?.locale ?? ctx.config().locales.default,
+            ...(tracking && send
+                ? {
+                    openUrl: `${origin}/api/newsletter/o/${send.id}.gif`,
+                    link: (href) => `${origin}/api/newsletter/c/${send.id}?u=${encodeURIComponent(href)}&s=${linkSignature(send.id, href, secret)}`,
+                }
+                : {}),
+        };
+        return {
+            subject: n.subject,
+            html: newsletterHtml(content),
+            text: newsletterText(content),
+            headers: (send
+                ? { 'List-Unsubscribe': `<${unsubscribeUrl}>`, 'List-Unsubscribe-Post': 'List-Unsubscribe=One-Click' }
+                : {}),
+        };
+    };
+    const readyMail = async () => {
+        const mail = await settings.get('mail');
+        if (!isConfigured(mail))
+            throw new ApiError(400, 'mail_not_configured', 'Per inviare la newsletter serve l’email: Impostazioni → Email');
+        return mail;
+    };
+    /** A try, to the person writing it (or another address): nothing is counted. */
+    app.post('/api/newsletters/:id/test', requireUser, async (c) => {
+        const found = await loadNewsletter(c.req.param('id'));
+        const input = await body(c, z.object({ to: z.email().optional() }));
+        const mail = await readyMail();
+        await newsletterOrigin(c);
+        const message = await composeNewsletter(found, null);
+        await sendMail(mail, { to: input.to ?? c.get('user').email, ...message, subject: `[Prova] ${message.subject}` });
+        return c.json({ ok: true });
+    });
+    app.post('/api/newsletters/:id/send', requireUser, async (c) => {
+        const found = await loadNewsletter(c.req.param('id'));
+        editable(found);
+        await readyMail();
+        await newsletterOrigin(c);
+        const { counts } = await newsletter.subscribers({ limit: 1 });
+        if (!counts.active)
+            throw new ApiError(400, 'no_subscribers', 'Non ci sono ancora iscritti attivi');
+        await newsletter.setStatus(found.id, 'sending', { runAt: new Date(), error: null });
+        await record(c, 'newsletter.sent', found.subject, { subscribers: counts.active });
+        void runNewsletters();
+        return c.json(await newsletterJson(await loadNewsletter(found.id)));
+    });
+    app.put('/api/newsletters/:id/schedule', requireUser, async (c) => {
+        const found = await loadNewsletter(c.req.param('id'));
+        editable(found);
+        const input = await body(c, z.object({ at: z.iso.datetime({ offset: true }).nullable() }));
+        if (input.at === null) {
+            await newsletter.setStatus(found.id, 'draft', { runAt: null });
+            return c.json(await newsletterJson(await loadNewsletter(found.id)));
+        }
+        const at = new Date(input.at);
+        if (at.getTime() <= Date.now() + 30_000)
+            throw new ApiError(400, 'past_time', 'Scegli un momento nel futuro, almeno tra un minuto');
+        await readyMail();
+        await newsletterOrigin(c);
+        await newsletter.setStatus(found.id, 'scheduled', { runAt: at, error: null });
+        await record(c, 'newsletter.scheduled', found.subject, { at: at.toISOString() });
+        return c.json(await newsletterJson(await loadNewsletter(found.id)));
+    });
+    /** An article becomes a newsletter: its title, its summary, its text and a link to read it on the site. */
+    app.post('/api/newsletters/from-document', requireUser, async (c) => {
+        const input = await body(c, z.object({ id: z.string() }));
+        const doc = await loadDocument(input.id);
+        const def = collection(doc.collection);
+        const data = (doc.publishedData ?? doc.data);
+        const fieldOf = (kind) => Object.entries(def.fields).find(([, f]) => f.kind === kind)?.[0];
+        const rich = fieldOf('richText');
+        const summary = Object.entries(def.fields).find(([n, f]) => f.kind === 'text' && /excerpt|summary|sommario|riassunto|descr/i.test(n))?.[0];
+        const seo = (fieldOf('seo') ? data[fieldOf('seo')] : null);
+        const preheader = (summary ? String(data[summary] ?? '') : '') || seo?.description || '';
+        const blocks = rich && Array.isArray(data[rich]) ? [...data[rich]] : [];
+        const url = (() => {
+            try {
+                return publicUrl(def, doc.locale, data);
+            }
+            catch {
+                return null;
+            }
+        })();
+        if (!blocks.length && preheader)
+            blocks.push({ type: 'paragraph', children: [{ text: preheader }] });
+        if (url)
+            blocks.push({
+                type: 'paragraph',
+                children: [
+                    { text: langOf(doc.locale) === 'it' ? 'Leggi sul sito →' : 'Read it on the site →', href: url, bold: true },
+                ],
+            });
+        const created = await newsletter.create({
+            subject: doc.title,
+            preheader: preheader.slice(0, 200),
+            body: blocks,
+            user: c.get('user'),
+        });
+        await record(c, 'newsletter.created', created.subject, { from: doc.id });
+        return c.json(await newsletterJson(created), 201);
+    });
+    /** A draft written by the AI from the latest articles, in the brand voice, with a link to each. */
+    app.post('/api/ai/newsletter', requireUser, async (c) => {
+        const input = await body(c, z.object({ count: z.number().int().min(1).max(10).default(3), note: z.string().max(1000).optional() }));
+        const user = c.get('user');
+        if (!allowAi(user.id))
+            throw new ApiError(429, 'too_many_requests', 'Troppe richieste: aspetta un minuto');
+        const ai = await readyAi();
+        const config = ctx.config();
+        const lang = config.locales.default;
+        const items = [];
+        for (const name of feedCollections(config.collections)) {
+            const def = collection(name);
+            for (const doc of await content.published(name)) {
+                if (doc.locale !== lang)
+                    continue;
+                const data = (doc.publishedData ?? {});
+                let url = null;
+                try {
+                    url = publicUrl(def, lang, data);
+                }
+                catch { }
+                if (!url)
+                    continue;
+                const text = Object.entries(def.fields)
+                    .filter(([, f]) => f.kind === 'text' || f.kind === 'richText')
+                    .map(([n]) => ((f) => (typeof f === 'string' ? f : Array.isArray(f) ? richTextHtml(f).replace(/<[^>]+>/g, ' ') : ''))(data[n]))
+                    .join('\n')
+                    .replace(/\s+/g, ' ')
+                    .slice(0, 2500);
+                items.push({ title: doc.title, url, text, date: (doc.publishedAt ?? doc.updatedAt).getTime() });
+            }
+        }
+        items.sort((a, b) => b.date - a.date);
+        const latest = items.slice(0, input.count);
+        if (!latest.length)
+            throw new ApiError(400, 'no_articles', 'Non ci sono ancora articoli pubblicati da raccontare');
+        const voice = await voiceText();
+        const system = `${voice ? `${voice}\n\n` : ''}You write the email newsletter of the website "${config.site.name}", in ${languageName(lang)}. You get its latest articles; write a short newsletter that makes people want to read them: a subject (at most 70 characters), a preheader (one sentence, at most 120 characters), an opening of one or two sentences, then for each article a heading with its title and two or three sentences on why it is worth reading, ending with a link to it. Use only facts from the articles. Reply with JSON only: {"subject": "...", "preheader": "...", "blocks": [{"type": "paragraph"|"heading", "text": "...", "link": {"text": "...", "href": "..."}?}]}.`;
+        const prompt = `${input.note ? `<note>${input.note}</note>\n` : ''}${latest.map((a) => `<article title="${a.title.replace(/"/g, "'")}" url="${a.url}">\n${a.text}\n</article>`).join('\n')}`;
+        const reply = await complete(ai, { system, prompt }).catch(aiFailed);
+        let parsed;
+        try {
+            parsed = JSON.parse(reply.replace(/^```(?:json)?\s*|\s*```$/g, ''));
+        }
+        catch {
+            throw new ApiError(422, 'ai_failed', 'La risposta dell’AI non era leggibile: riprova');
+        }
+        const known = new Set(latest.map((a) => a.url));
+        const blocks = [];
+        for (const b of parsed.blocks ?? []) {
+            const text = (b.text ?? '').trim();
+            const children = text ? [{ text }] : [];
+            if (b.link?.href && known.has(b.link.href) && b.link.text)
+                children.push({ text: `${text ? ' ' : ''}${b.link.text.trim()}`, href: b.link.href, bold: true });
+            if (!children.length)
+                continue;
+            blocks.push(b.type === 'heading' ? { type: 'heading', level: 2, children } : { type: 'paragraph', children });
+        }
+        const created = await newsletter.create({
+            subject: (parsed.subject ?? '').trim().slice(0, 200) || latest[0]?.title || config.site.name,
+            preheader: (parsed.preheader ?? '').trim().slice(0, 200),
+            body: blocks,
+            user,
+        });
+        await record(c, 'newsletter.created', created.subject, { ai: true });
+        return c.json(await newsletterJson(created), 201);
+    });
+    /**
+     * Sends what is due: scheduled newsletters whose time has come and those a stopped server left
+     * halfway. One email at a time, a short pause between them, so the email service keeps up.
+     */
+    let newslettersRunning = false;
+    const runNewsletters = async (now = new Date(), pause = 120) => {
+        if (newslettersRunning)
+            return 0;
+        newslettersRunning = true;
+        let sent = 0;
+        try {
+            for (const n of await newsletter.due(now)) {
+                const mail = await settings.get('mail');
+                if (!isConfigured(mail)) {
+                    await newsletter.setStatus(n.id, 'failed', { error: 'L’email non è configurata' });
+                    continue;
+                }
+                if (n.status === 'scheduled')
+                    await newsletter.setStatus(n.id, 'sending');
+                await newsletter.prepare(n.id);
+                for (;;) {
+                    const batch = await newsletter.pending(n.id, 50);
+                    if (!batch.length)
+                        break;
+                    for (const item of batch) {
+                        const who = await newsletter.subscriber(item.subscriberId);
+                        if (!who || who.status !== 'active') {
+                            await newsletter.markSend(item.id, 'failed', 'Non più iscritto');
+                            continue;
+                        }
+                        try {
+                            const message = await composeNewsletter(n, { id: item.id, token: who.token, locale: who.locale });
+                            await sendMail(mail, { to: who.email, ...message });
+                            await newsletter.markSend(item.id, 'sent');
+                            sent++;
+                        }
+                        catch (error) {
+                            await newsletter.markSend(item.id, 'failed', error instanceof Error ? error.message.slice(0, 300) : 'Errore');
+                        }
+                        if (pause)
+                            await new Promise((r) => setTimeout(r, pause));
+                    }
+                }
+                const stats = await newsletter.stats(n.id);
+                const allFailed = stats.total > 0 && stats.sent === 0;
+                await newsletter.setStatus(n.id, allFailed ? 'failed' : 'sent', {
+                    sentAt: new Date(),
+                    error: allFailed ? 'Nessun invio riuscito: controlla Impostazioni → Email' : null,
+                });
+            }
+            // Signups never confirmed are dropped after a week.
+            await newsletter.dropUnconfirmed(new Date(now.getTime() - 7 * 86_400_000));
+        }
+        catch (error) {
+            console.error('Materialize: newsletter sending failed', error);
+        }
+        finally {
+            newslettersRunning = false;
+        }
+        return sent;
+    };
+    setInterval(() => void runNewsletters(), 30_000).unref?.();
     // ---------- shared preview links ----------
     const previewJson = (c, link) => {
         const path = `/_materialize/share/${link.token}`;
@@ -3911,5 +4424,5 @@ When done, reply with one short sentence.`;
         return c.json(publicDocument(doc));
     });
     // runSchedules: for the tests, which cannot wait for the clock.
-    return Object.assign(app, { runSchedules });
+    return Object.assign(app, { runSchedules, runNewsletters });
 }

package/src/mail.d.ts

@@ -30,7 +30,9 @@ export declare function sendMail(m: MailSettings, message: {
     to: string;
     subject: string;
     text: string;
+    html?: string;
     replyTo?: string;
+    headers?: Record<string, string>;
 }): 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;

package/src/newsletter.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The newsletter as an email: an HTML version that reads well in every email app (one column,
+ * inline styles, absolute addresses) and a plain text one. With statistics on, a tiny picture
+ * tells when it is opened and links pass through the site, signed so they cannot be bent to
+ * send people elsewhere.
+ */
+type Lang = 'it' | 'en';
+export declare const langOf: (locale: string | null | undefined) => Lang;
+export interface NewsletterContent {
+    site: string;
+    /** The site's public address, for links and pictures. */
+    siteUrl: string;
+    subject: string;
+    preheader: string;
+    body: unknown[];
+    /** The site's accent color, for links and buttons. */
+    accent: string;
+    /** The sender's details, shown at the bottom (often required by law: a postal address). */
+    footer: string;
+    unsubscribeUrl: string;
+    /** Statistics: the picture that tells the email was opened, and each link through the site. */
+    openUrl?: string;
+    link?: (href: string) => string;
+    locale?: string | null;
+}
+export declare function newsletterHtml(c: NewsletterContent): string;
+/** The same newsletter as plain text, for email apps that show no HTML. */
+export declare function newsletterText(c: NewsletterContent): string;
+/** The email that asks a new subscriber to confirm. */
+export declare function confirmEmail(input: {
+    site: string;
+    url: string;
+    accent: string;
+    locale?: string | null;
+}): {
+    subject: string;
+    text: string;
+    html: string;
+};
+/** The signature of a tracked link: without it, the address would redirect anywhere. */
+export declare function linkSignature(sendId: string, url: string, secret: string): string;
+export declare function validLink(sendId: string, url: string, signature: string, secret: string): boolean;
+/** A 1×1 transparent GIF: the "opened" picture. */
+export declare const PIXEL: Buffer<ArrayBuffer>;
+/** Addresses out of a CSV export (Mailchimp, Brevo, a spreadsheet): the email column, and a name if there is one. */
+export declare function parseSubscribersCsv(text: string): {
+    email: string;
+    name?: string;
+}[];
+export {};

package/src/newsletter.js

@@ -0,0 +1,192 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { richTextHtml } from '@materializecms/core/page';
+const WORDS = {
+    it: {
+        unsubscribe: 'Non vuoi più ricevere queste email? Disiscriviti',
+        why: 'Ricevi questa email perché ti sei iscritto alla newsletter di {site}.',
+        confirmSubject: 'Conferma l’iscrizione alla newsletter di {site}',
+        confirmIntro: 'Ciao! Per ricevere la newsletter di {site} conferma il tuo indirizzo:',
+        confirmButton: 'Confermo l’iscrizione',
+        confirmIgnore: 'Se non ti sei iscritto tu, ignora questa email: senza conferma non riceverai niente.',
+        view: 'Apri nel browser',
+    },
+    en: {
+        unsubscribe: 'Don’t want these emails any more? Unsubscribe',
+        why: 'You get this email because you signed up for the {site} newsletter.',
+        confirmSubject: 'Confirm your subscription to the {site} newsletter',
+        confirmIntro: 'Hi! To get the {site} newsletter, confirm your address:',
+        confirmButton: 'Confirm my subscription',
+        confirmIgnore: 'If you did not sign up, ignore this email: without confirming you will get nothing.',
+        view: 'Open in your browser',
+    },
+};
+export const langOf = (locale) => locale?.toLowerCase().startsWith('it') ? 'it' : 'en';
+const say = (lang, key, site) => (WORDS[lang][key] ?? key).replace('{site}', site);
+const esc = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+/** An address on the site made absolute; others stay as they are. */
+const absolute = (href, base) => {
+    try {
+        return new URL(href, `${base.replace(/\/$/, '')}/`).toString();
+    }
+    catch {
+        return href;
+    }
+};
+/** Inline styles: email apps drop style sheets. */
+const STYLE = {
+    p: 'margin:0 0 16px;font-size:16px;line-height:1.6;',
+    h2: 'margin:28px 0 12px;font-size:22px;line-height:1.3;font-weight:700;',
+    h3: 'margin:24px 0 10px;font-size:18px;line-height:1.35;font-weight:700;',
+    h4: 'margin:20px 0 8px;font-size:16px;line-height:1.4;font-weight:700;',
+    ul: 'margin:0 0 16px;padding-left:22px;font-size:16px;line-height:1.6;',
+    li: 'margin:0 0 6px;',
+    blockquote: 'margin:0 0 16px;padding:4px 0 4px 16px;border-left:3px solid #d4d4d8;color:#52525b;font-style:italic;',
+    figure: 'margin:0 0 16px;',
+    img: 'display:block;max-width:100%;height:auto;border:0;border-radius:8px;',
+};
+export function newsletterHtml(c) {
+    const lang = langOf(c.locale);
+    let body = richTextHtml(c.body);
+    body = body.replace(/(src|href)="([^"]*)"/g, (_, attr, value) => {
+        const raw = value.replace(/&amp;/g, '&');
+        const abs = absolute(raw, c.siteUrl);
+        const out = attr === 'href' && c.link && /^https?:/i.test(abs) ? c.link(abs) : abs;
+        return `${attr}="${esc(out)}"`;
+    });
+    body = body.replace(/<(p|h2|h3|h4|ul|li|blockquote|figure|img)(\s|>)/g, (_, tag, after) => {
+        return `<${tag} style="${STYLE[tag]}"${after}`;
+    });
+    body = body.replace(/<a /g, `<a style="color:${esc(c.accent)};text-decoration:underline;" `);
+    body = body.replace(/ loading="lazy" decoding="async"/g, '');
+    const footer = c.footer.trim() ? `<p style="margin:0 0 8px;">${esc(c.footer.trim()).replace(/\n/g, '<br>')}</p>` : '';
+    return `<!doctype html>
+<html lang="${lang}">
+<head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${esc(c.subject)}</title></head>
+<body style="margin:0;padding:0;background:#f4f4f5;">
+<div style="display:none;max-height:0;overflow:hidden;opacity:0;">${esc(c.preheader)}</div>
+<table role="presentation" width="100%" cellpadding="0" cellspacing="0" style="background:#f4f4f5;">
+<tr><td align="center" style="padding:32px 16px;">
+<table role="presentation" width="100%" cellpadding="0" cellspacing="0" style="max-width:600px;background:#ffffff;border-radius:12px;">
+<tr><td style="padding:28px 32px 8px;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Helvetica,Arial,sans-serif;font-size:14px;font-weight:700;color:#18181b;">${esc(c.site)}</td></tr>
+<tr><td style="padding:8px 32px 24px;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Helvetica,Arial,sans-serif;color:#18181b;">
+<h1 style="margin:0 0 20px;font-size:26px;line-height:1.25;font-weight:700;">${esc(c.subject)}</h1>
+${body}
+</td></tr>
+</table>
+<table role="presentation" width="100%" cellpadding="0" cellspacing="0" style="max-width:600px;">
+<tr><td style="padding:20px 32px;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Helvetica,Arial,sans-serif;font-size:12px;line-height:1.6;color:#71717a;text-align:center;">
+${footer}<p style="margin:0 0 8px;">${esc(say(lang, 'why', c.site))}</p>
+<p style="margin:0;"><a href="${esc(c.unsubscribeUrl)}" style="color:#71717a;text-decoration:underline;">${esc(say(lang, 'unsubscribe', c.site))}</a></p>
+</td></tr>
+</table>
+</td></tr>
+</table>
+${c.openUrl ? `<img src="${esc(c.openUrl)}" width="1" height="1" alt="" style="display:block;border:0;width:1px;height:1px;">` : ''}
+</body>
+</html>`;
+}
+/** The same newsletter as plain text, for email apps that show no HTML. */
+export function newsletterText(c) {
+    const lang = langOf(c.locale);
+    const lines = [c.subject, ''];
+    const runs = (b) => (b.children ?? [])
+        .map((r) => (r.href ? `${r.text ?? ''} (${absolute(r.href, c.siteUrl)})` : (r.text ?? '')))
+        .join('');
+    for (const b of c.body) {
+        if (b.type === 'image')
+            continue;
+        const text = runs(b).trim();
+        if (!text)
+            continue;
+        if (b.type === 'listItem')
+            lines.push(`- ${text}`);
+        else if (b.type === 'heading')
+            lines.push('', text.toUpperCase(), '');
+        else
+            lines.push(text, '');
+    }
+    lines.push('—', ...(c.footer.trim() ? [c.footer.trim()] : []), say(lang, 'why', c.site));
+    lines.push(`${say(lang, 'unsubscribe', c.site)}: ${c.unsubscribeUrl}`);
+    return lines.join('\n');
+}
+/** The email that asks a new subscriber to confirm. */
+export function confirmEmail(input) {
+    const lang = langOf(input.locale);
+    const subject = say(lang, 'confirmSubject', input.site);
+    const text = [say(lang, 'confirmIntro', input.site), '', input.url, '', say(lang, 'confirmIgnore', input.site)].join('\n');
+    const html = `<!doctype html><html lang="${lang}"><body style="margin:0;padding:32px 16px;background:#f4f4f5;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Helvetica,Arial,sans-serif;color:#18181b;">
+<table role="presentation" width="100%" cellpadding="0" cellspacing="0" style="max-width:520px;margin:0 auto;background:#ffffff;border-radius:12px;"><tr><td style="padding:28px 32px;">
+<p style="margin:0 0 20px;font-size:16px;line-height:1.6;">${esc(say(lang, 'confirmIntro', input.site))}</p>
+<p style="margin:0 0 24px;"><a href="${esc(input.url)}" style="display:inline-block;padding:12px 20px;border-radius:8px;background:${esc(input.accent)};color:#ffffff;font-weight:600;text-decoration:none;">${esc(say(lang, 'confirmButton', input.site))}</a></p>
+<p style="margin:0;font-size:13px;line-height:1.6;color:#71717a;">${esc(say(lang, 'confirmIgnore', input.site))}</p>
+</td></tr></table></body></html>`;
+    return { subject, text, html };
+}
+/** The signature of a tracked link: without it, the address would redirect anywhere. */
+export function linkSignature(sendId, url, secret) {
+    return createHmac('sha256', secret).update(`${sendId}\n${url}`).digest('base64url').slice(0, 22);
+}
+export function validLink(sendId, url, signature, secret) {
+    const expected = Buffer.from(linkSignature(sendId, url, secret));
+    const given = Buffer.from(signature);
+    return expected.length === given.length && timingSafeEqual(expected, given);
+}
+/** A 1×1 transparent GIF: the "opened" picture. */
+export const PIXEL = Buffer.from('R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7', 'base64');
+/** Addresses out of a CSV export (Mailchimp, Brevo, a spreadsheet): the email column, and a name if there is one. */
+export function parseSubscribersCsv(text) {
+    const lines = text
+        .replace(/^/, '')
+        .split(/\r?\n/)
+        .filter((l) => l.trim());
+    if (!lines.length)
+        return [];
+    const sep = [';', ',', '\t'].sort((a, b) => (lines[0]?.split(b).length ?? 0) - (lines[0]?.split(a).length ?? 0))[0] ?? ',';
+    const cells = (l) => {
+        const out = [];
+        let cur = '';
+        let quoted = false;
+        for (let i = 0; i < l.length; i++) {
+            const ch = l[i];
+            if (ch === '"') {
+                if (quoted && l[i + 1] === '"') {
+                    cur += '"';
+                    i++;
+                }
+                else
+                    quoted = !quoted;
+            }
+            else if (ch === sep && !quoted) {
+                out.push(cur);
+                cur = '';
+            }
+            else
+                cur += ch;
+        }
+        out.push(cur);
+        return out.map((c) => c.trim());
+    };
+    const head = cells(lines[0] ?? '').map((h) => h.toLowerCase());
+    const isEmail = (v) => /^[^\s@,;]+@[^\s@,;]+\.[^\s@,;]+$/.test(v);
+    let emailCol = head.findIndex((h) => /e-?mail/.test(h));
+    const nameCol = head.findIndex((h) => /^(name|nome|first name|nome e cognome|full name)$/.test(h));
+    let rows = lines.slice(1);
+    // No header: the column holding addresses, from the first line on.
+    if (emailCol < 0) {
+        emailCol = cells(lines[0] ?? '').findIndex(isEmail);
+        rows = lines;
+    }
+    if (emailCol < 0)
+        return [];
+    const seen = new Set();
+    const out = [];
+    for (const l of rows) {
+        const c = cells(l);
+        const email = (c[emailCol] ?? '').toLowerCase();
+        if (!isEmail(email) || seen.has(email))
+            continue;
+        seen.add(email);
+        out.push({ email, ...(nameCol >= 0 && c[nameCol] ? { name: c[nameCol] } : {}) });
+    }
+    return out;
+}