@geekity/cms 0.3.0 → 0.4.0

package/dist/mail/service.d.ts

@@ -0,0 +1,156 @@
+import type { ResolvedConfig } from '../config.ts';
+import type { ThemeSource } from '../web/themes.ts';
+import type { MailAddress, MailProvider, MailProviderName } from './provider.ts';
+import type { MailTemplates } from './templates.ts';
+/**
+ * The one door out of this CMS for email.
+ *
+ * Every feature that emails — a password reset (TASK-54), a moderation notice
+ * (TASK-55), a contact form (TASK-56) — calls {@link MailService.send} and
+ * nothing else. What carries the message, whether the site is configured to
+ * send at all, how many times a refusal is worth trying again and where the
+ * attempts are written down are all decided here, once.
+ *
+ * Three things follow from that, and they are the whole design:
+ *
+ * - **A site with no mail configuration still works.** `send` resolves
+ *   successfully, having sent nothing and said so in the log. A feature that
+ *   emails is not a feature that breaks without a mail account.
+ * - **Nothing is decided at boot.** The settings and `data/mail.json` are read
+ *   per send, so a key pasted into the settings screen sends the next message
+ *   and a provider switched there takes effect at once, neither needing a
+ *   restart — the same way every other setting behaves under decision-9.
+ * - **Sending is off the request.** Messages go on one queue, one at a time,
+ *   and a refusal is tried again after a growing wait. A caller that wants the
+ *   answer — the Send test email button — awaits the promise; a caller that
+ *   does not simply drops it.
+ */
+/** How many times a message is tried before the service gives up. */
+export declare const DEFAULT_MAIL_ATTEMPTS = 3;
+/** How long to wait before attempt `n + 1`: 2s, then 8s, then 18s. */
+export declare function defaultMailBackoffMs(attempt: number): number;
+/** Where the service says what it did and what it could not do. `console` will do. */
+export interface MailLogger {
+    /** One line per message that went, and one per message that was not sent. */
+    info(message: string): void;
+    /** One line per attempt that failed, and one when the service gives up. */
+    warn(message: string): void;
+}
+/** Anything that can be addressed: an address, or one with a name on it. */
+export type MailRecipient = string | MailAddress;
+/** What {@link MailService.send} takes: a template, and who to send it to. */
+export interface TemplateMail {
+    /** Who it goes to. One address or several. */
+    to: MailRecipient | readonly MailRecipient[];
+    /** Which message under `mail/` in the theme to render. */
+    template: string;
+    /**
+     * The subject, when the caller would rather decide it than let the
+     * template's `.subject.njk` do it.
+     */
+    subject?: string | undefined;
+    /** What the template renders against, on top of `site` and `baseUrl`. */
+    data?: Record<string, unknown> | undefined;
+    /** Where a reply goes, when it is not the site's own reply-to setting. */
+    replyTo?: MailRecipient | undefined;
+}
+/** What {@link MailService.sendRaw} takes: a message the caller built itself. */
+export interface RawMail {
+    /** Who it goes to. */
+    to: MailRecipient | readonly MailRecipient[];
+    /** The subject line. */
+    subject: string;
+    /** The plain text body. */
+    text: string;
+    /** The HTML twin, when there is one. */
+    html?: string | undefined;
+    /** Where a reply goes, when it is not the site's own reply-to setting. */
+    replyTo?: MailRecipient | undefined;
+}
+/** What became of one message. Never throws; this is the whole answer. */
+export interface MailResult {
+    /**
+     * Whether the caller may carry on. True for a message that went **and** for
+     * one a site with no mail configuration never sent: neither is a failure of
+     * the thing that asked for it.
+     */
+    readonly ok: boolean;
+    /** Whether it was never sent because the site sends no mail. */
+    readonly skipped: boolean;
+    /** Which provider carried it, or `none`. */
+    readonly provider: MailProviderName;
+    /** Who it was addressed to. */
+    readonly to: readonly string[];
+    /** The subject that was sent, after the template and the caller had their say. */
+    readonly subject: string;
+    /** How many attempts it took, or 0 when nothing was attempted. */
+    readonly attempts: number;
+    /** The id the provider gave it, which is what finds it in their logs. */
+    readonly messageId?: string | undefined;
+    /** Why it did not go, when it did not. */
+    readonly error?: string | undefined;
+}
+/** What {@link createMailService} needs. */
+export interface CreateMailServiceOptions {
+    /**
+     * Config after defaults: the base URL, the content directory the settings
+     * are read from, the data directory the credentials are in, the theme
+     * directory the messages are looked up in, and whether templates are cached.
+     */
+    config: Pick<ResolvedConfig, 'baseUrl' | 'contentDir' | 'dataDir' | 'themesDir' | 'watch'>;
+    /**
+     * A provider named by the site, which wins outright over the settings and
+     * `data/mail.json` — the way a `commentChecker` in the config wins over the
+     * Akismet key. {@link createMemoryMailProvider} is what a test names here.
+     */
+    provider?: MailProvider | undefined;
+    /** The messages. Defaults to the theme's, packaged theme behind it. */
+    templates?: MailTemplates | undefined;
+    /**
+     * Which theme the messages come from, when this service builds its own
+     * templates. Defaults to one over the config's themes directory and the
+     * site's `theme` setting; `createCms` hands in the one the pages use, so a
+     * site has a single answer to which theme it is running.
+     */
+    themes?: ThemeSource | undefined;
+    /** Where attempts are logged. Defaults to `console`. */
+    logger?: MailLogger | undefined;
+    /** How many times one message is tried. Defaults to {@link DEFAULT_MAIL_ATTEMPTS}. */
+    attempts?: number | undefined;
+    /**
+     * How long to wait before attempt `n + 1`. Defaults to
+     * {@link defaultMailBackoffMs}; a test hands in something instant.
+     */
+    backoffMs?: ((attempt: number) => number) | undefined;
+    /** How the wait is taken. Defaults to a timer; a test hands in a stub. */
+    wait?: ((ms: number) => Promise<void>) | undefined;
+}
+/** Sends a site's email, or explains in the log why it did not. */
+export interface MailService {
+    /**
+     * Whether anything would actually be sent: a provider named in the config,
+     * or a provider chosen in the settings whose credential is in
+     * `data/mail.json`. Read per call, so it changes the moment the file does.
+     */
+    configured(): boolean;
+    /** Which provider would carry the next message, or `none`. */
+    providerName(): MailProviderName;
+    /** The From line the next message would carry. */
+    from(): MailAddress;
+    /**
+     * Render a message from the theme and queue it.
+     *
+     * The promise resolves when the message has been sent, or given up on, or
+     * skipped — a caller that wants to report the outcome awaits it, and one
+     * that does not drops it with `void`. It never rejects: a failure is a
+     * result with `ok: false` and the provider's own words in `error`.
+     */
+    send(message: TemplateMail): Promise<MailResult>;
+    /** The same, for a caller that built the message itself and wants no template. */
+    sendRaw(message: RawMail): Promise<MailResult>;
+    /** Resolve once every queued message has finished, however it finished. */
+    settled(): Promise<void>;
+}
+/** Build the mail service for one site. */
+export declare function createMailService(options: CreateMailServiceOptions): MailService;
+//# sourceMappingURL=service.d.ts.map

package/dist/mail/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../src/mail/service.ts"],"names":[],"mappings":"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"}

package/dist/mail/service.js

@@ -0,0 +1,265 @@
+import { readSiteSettings } from '../admin/settings.js';
+import { createThemeSource } from '../web/themes.js';
+import { createBrevoProvider } from './brevo.js';
+import { readMailCredentials } from './credentials.js';
+import { createSmtpProvider } from './smtp.js';
+import { createMailTemplates } from './templates.js';
+/**
+ * The one door out of this CMS for email.
+ *
+ * Every feature that emails — a password reset (TASK-54), a moderation notice
+ * (TASK-55), a contact form (TASK-56) — calls {@link MailService.send} and
+ * nothing else. What carries the message, whether the site is configured to
+ * send at all, how many times a refusal is worth trying again and where the
+ * attempts are written down are all decided here, once.
+ *
+ * Three things follow from that, and they are the whole design:
+ *
+ * - **A site with no mail configuration still works.** `send` resolves
+ *   successfully, having sent nothing and said so in the log. A feature that
+ *   emails is not a feature that breaks without a mail account.
+ * - **Nothing is decided at boot.** The settings and `data/mail.json` are read
+ *   per send, so a key pasted into the settings screen sends the next message
+ *   and a provider switched there takes effect at once, neither needing a
+ *   restart — the same way every other setting behaves under decision-9.
+ * - **Sending is off the request.** Messages go on one queue, one at a time,
+ *   and a refusal is tried again after a growing wait. A caller that wants the
+ *   answer — the Send test email button — awaits the promise; a caller that
+ *   does not simply drops it.
+ */
+/** How many times a message is tried before the service gives up. */
+export const DEFAULT_MAIL_ATTEMPTS = 3;
+/** How long to wait before attempt `n + 1`: 2s, then 8s, then 18s. */
+export function defaultMailBackoffMs(attempt) {
+    return attempt * attempt * 2000;
+}
+/** Build the mail service for one site. */
+export function createMailService(options) {
+    const { config } = options;
+    const logger = options.logger ?? console;
+    const attempts = Math.max(1, options.attempts ?? DEFAULT_MAIL_ATTEMPTS);
+    const backoffMs = options.backoffMs ?? defaultMailBackoffMs;
+    const wait = options.wait ??
+        ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const templates = options.templates ??
+        createMailTemplates({
+            themes: options.themes ??
+                createThemeSource({
+                    themesDir: config.themesDir,
+                    chosen: () => readSiteSettings(config.contentDir).theme,
+                }),
+            baseUrl: config.baseUrl,
+            noCache: config.watch,
+        });
+    // Messages are chained rather than sent at once, and the chain never
+    // rejects: one provider that hangs delays the next message and nothing else.
+    let chain = Promise.resolve();
+    function enqueue(task) {
+        const result = chain.then(task);
+        chain = result.then(ignore, ignore);
+        return result;
+    }
+    /**
+     * The provider that would carry the next message, built from the file as it
+     * reads now, or `undefined` when the site sends no mail.
+     *
+     * Built per send rather than held: it is how a credential saved on the
+     * settings screen reaches the very next message, and how one removed stops
+     * the one after it.
+     */
+    function provider() {
+        if (options.provider !== undefined)
+            return options.provider;
+        const settings = readSiteSettings(config.contentDir);
+        const credentials = readMailCredentials(config.dataDir);
+        if (settings.mailProvider === 'brevo' && credentials.brevo !== undefined) {
+            return createBrevoProvider({ apiKey: credentials.brevo.apiKey });
+        }
+        if (settings.mailProvider === 'smtp' && credentials.smtp !== undefined) {
+            return createSmtpProvider(credentials.smtp);
+        }
+        return undefined;
+    }
+    /** The From line, as the settings say it now. */
+    function from(settings) {
+        const address = settings.mailFromAddress === '' ? fallbackAddress(config.baseUrl) : settings.mailFromAddress;
+        const name = settings.mailFromName === '' ? settings.title : settings.mailFromName;
+        return name === '' ? { address } : { name, address };
+    }
+    /** Try one message until it goes or the site runs out of patience. */
+    async function deliver(carrier, message) {
+        const to = message.to.map((recipient) => recipient.address);
+        const where = `"${message.subject}" to ${to.join(', ')} via ${carrier.name}`;
+        let lastError = '';
+        for (let attempt = 1; attempt <= attempts; attempt += 1) {
+            const which = `attempt ${String(attempt)} of ${String(attempts)}`;
+            try {
+                const delivery = await carrier.deliver(message);
+                logger.info(`Sent ${where} (${which}): ${delivery.messageId ?? 'no message id'}`);
+                return {
+                    ok: true,
+                    skipped: false,
+                    provider: carrier.name,
+                    to,
+                    subject: message.subject,
+                    attempts: attempt,
+                    ...(delivery.messageId === undefined ? {} : { messageId: delivery.messageId }),
+                };
+            }
+            catch (thrown) {
+                lastError = messageOf(thrown);
+                logger.warn(`Could not send ${where} (${which}): ${lastError}`);
+                if (attempt < attempts)
+                    await wait(backoffMs(attempt));
+            }
+        }
+        logger.warn(`Gave up sending ${where} after ${String(attempts)} attempts: ${lastError}`);
+        return {
+            ok: false,
+            skipped: false,
+            provider: carrier.name,
+            to,
+            subject: message.subject,
+            attempts,
+            error: lastError,
+        };
+    }
+    /**
+     * The one path both `send` and `sendRaw` take: settle the provider, build
+     * the message, and queue it.
+     *
+     * `build` runs inside the queue rather than before it, so a template read is
+     * one of the things that is serialised — and so a template edited while a
+     * message is waiting is the one that goes out.
+     */
+    function queue(to, replyTo, build) {
+        const recipients = addressesOf(to);
+        const carrier = provider();
+        if (carrier === undefined) {
+            // Not a failure. A site with no mail account is a site whose password
+            // resets are done from the shell and whose moderation happens on the
+            // Comments screen, and neither of those should throw here.
+            logger.info(`No mail is configured, so a message to ${recipients
+                .map((recipient) => recipient.address)
+                .join(', ')} was not sent.`);
+            return Promise.resolve({
+                ok: true,
+                skipped: true,
+                provider: 'none',
+                to: recipients.map((recipient) => recipient.address),
+                subject: '',
+                attempts: 0,
+            });
+        }
+        return enqueue(async () => {
+            const settings = readSiteSettings(config.contentDir);
+            let body;
+            try {
+                body = build(settings);
+            }
+            catch (thrown) {
+                // A template that will not render is a mistake in this site's own
+                // files, not a provider that refused: there is nothing to retry, and
+                // the message names the file to fix.
+                const error = messageOf(thrown);
+                logger.warn(`Could not build a message for ${recipients.map((r) => r.address).join(', ')}: ${error}`);
+                return {
+                    ok: false,
+                    skipped: false,
+                    provider: carrier.name,
+                    to: recipients.map((recipient) => recipient.address),
+                    subject: '',
+                    attempts: 0,
+                    error,
+                };
+            }
+            const answerTo = replyTo === undefined ? replyToIn(settings) : addressOf(replyTo);
+            return await deliver(carrier, {
+                from: from(settings),
+                to: recipients,
+                ...(answerTo === undefined ? {} : { replyTo: answerTo }),
+                subject: body.subject,
+                text: body.text,
+                ...(body.html === undefined ? {} : { html: body.html }),
+            });
+        });
+    }
+    return {
+        configured() {
+            return provider() !== undefined;
+        },
+        providerName() {
+            return provider()?.name ?? 'none';
+        },
+        from() {
+            return from(readSiteSettings(config.contentDir));
+        },
+        send(message) {
+            return queue(message.to, message.replyTo, (settings) => {
+                const rendered = templates.render(message.template, {
+                    site: settings,
+                    baseUrl: config.baseUrl,
+                    ...message.data,
+                });
+                return {
+                    // The caller's own subject wins: a reset link's subject is the
+                    // feature's to decide, and a template that offers one is a default.
+                    subject: message.subject ?? (rendered.subject === '' ? '(no subject)' : rendered.subject),
+                    text: rendered.text,
+                    ...(rendered.html === undefined ? {} : { html: rendered.html }),
+                };
+            });
+        },
+        sendRaw(message) {
+            return queue(message.to, message.replyTo, () => ({
+                subject: message.subject,
+                text: message.text,
+                ...(message.html === undefined ? {} : { html: message.html }),
+            }));
+        },
+        async settled() {
+            await chain;
+        },
+    };
+}
+/** Where a reply goes, as the settings say it, or nowhere in particular. */
+function replyToIn(settings) {
+    return settings.mailReplyTo === '' ? undefined : { address: settings.mailReplyTo };
+}
+/**
+ * The address a site sends as when its settings name none: `no-reply@` at the
+ * base URL's host.
+ *
+ * A guess, and a documented one — a provider only accepts a sender it has
+ * verified, so a site that sends anything real fills the field in. It exists
+ * so that a site which has pasted a key but not yet typed an address gets a
+ * message it can read the refusal from, rather than silence.
+ */
+function fallbackAddress(baseUrl) {
+    try {
+        return `no-reply@${new URL(baseUrl).hostname}`;
+    }
+    catch {
+        return 'no-reply@localhost';
+    }
+}
+/** One recipient as an address. */
+function addressOf(recipient) {
+    return typeof recipient === 'string' ? { address: recipient } : recipient;
+}
+/** However the caller spelled the recipients, as a list of addresses. */
+function addressesOf(to) {
+    if (typeof to === 'string')
+        return [{ address: to }];
+    if (Array.isArray(to))
+        return to.map(addressOf);
+    return [addressOf(to)];
+}
+/** What a thrown value has to say for itself. */
+function messageOf(thrown) {
+    return thrown instanceof Error ? thrown.message : String(thrown);
+}
+function ignore() {
+    // A failed send is already logged; the queue carries on regardless.
+}
+//# sourceMappingURL=service.js.map

package/dist/mail/service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../../src/mail/service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAGxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAErD,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAEvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAGrD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,qEAAqE;AACrE,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC;AAEvC,sEAAsE;AACtE,MAAM,UAAU,oBAAoB,CAAC,OAAe;IAClD,OAAO,OAAO,GAAG,OAAO,GAAG,IAAI,CAAC;AAClC,CAAC;AAmID,2CAA2C;AAC3C,MAAM,UAAU,iBAAiB,CAAC,OAAiC;IACjE,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IAC3B,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC;IACzC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,QAAQ,IAAI,qBAAqB,CAAC,CAAC;IACxE,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,oBAAoB,CAAC;IAC5D,MAAM,IAAI,GACR,OAAO,CAAC,IAAI;QACZ,CAAC,CAAC,EAAU,EAAiB,EAAE,CAAC,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;IAErF,MAAM,SAAS,GACb,OAAO,CAAC,SAAS;QACjB,mBAAmB,CAAC;YAClB,MAAM,EACJ,OAAO,CAAC,MAAM;gBACd,iBAAiB,CAAC;oBAChB,SAAS,EAAE,MAAM,CAAC,SAAS;oBAC3B,MAAM,EAAE,GAAG,EAAE,CAAC,gBAAgB,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,KAAK;iBACxD,CAAC;YACJ,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,OAAO,EAAE,MAAM,CAAC,KAAK;SACtB,CAAC,CAAC;IAEL,qEAAqE;IACrE,6EAA6E;IAC7E,IAAI,KAAK,GAAqB,OAAO,CAAC,OAAO,EAAE,CAAC;IAEhD,SAAS,OAAO,CAAI,IAAsB;QACxC,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAChC,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACpC,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;;;;;OAOG;IACH,SAAS,QAAQ;QACf,IAAI,OAAO,CAAC,QAAQ,KAAK,SAAS;YAAE,OAAO,OAAO,CAAC,QAAQ,CAAC;QAE5D,MAAM,QAAQ,GAAG,gBAAgB,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QACrD,MAAM,WAAW,GAAG,mBAAmB,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAExD,IAAI,QAAQ,CAAC,YAAY,KAAK,OAAO,IAAI,WAAW,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YACzE,OAAO,mBAAmB,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;QACnE,CAAC;QACD,IAAI,QAAQ,CAAC,YAAY,KAAK,MAAM,IAAI,WAAW,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YACvE,OAAO,kBAAkB,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;QAC9C,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,iDAAiD;IACjD,SAAS,IAAI,CAAC,QAAsB;QAClC,MAAM,OAAO,GACX,QAAQ,CAAC,eAAe,KAAK,EAAE,CAAC,CAAC,CAAC,eAAe,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,eAAe,CAAC;QAC/F,MAAM,IAAI,GAAG,QAAQ,CAAC,YAAY,KAAK,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,YAAY,CAAC;QACnF,OAAO,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IACvD,CAAC;IAED,sEAAsE;IACtE,KAAK,UAAU,OAAO,CAAC,OAAqB,EAAE,OAAqB;QACjE,MAAM,EAAE,GAAG,OAAO,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QAC5D,MAAM,KAAK,GAAG,IAAI,OAAO,CAAC,OAAO,QAAQ,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,OAAO,CAAC,IAAI,EAAE,CAAC;QAC7E,IAAI,SAAS,GAAG,EAAE,CAAC;QAEnB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,QAAQ,EAAE,OAAO,IAAI,CAAC,EAAE,CAAC;YACxD,MAAM,KAAK,GAAG,WAAW,MAAM,CAAC,OAAO,CAAC,OAAO,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;YAClE,IAAI,CAAC;gBACH,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;gBAChD,MAAM,CAAC,IAAI,CAAC,QAAQ,KAAK,KAAK,KAAK,MAAM,QAAQ,CAAC,SAAS,IAAI,eAAe,EAAE,CAAC,CAAC;gBAClF,OAAO;oBACL,EAAE,EAAE,IAAI;oBACR,OAAO,EAAE,KAAK;oBACd,QAAQ,EAAE,OAAO,CAAC,IAAI;oBACtB,EAAE;oBACF,OAAO,EAAE,OAAO,CAAC,OAAO;oBACxB,QAAQ,EAAE,OAAO;oBACjB,GAAG,CAAC,QAAQ,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,QAAQ,CAAC,SAAS,EAAE,CAAC;iBAC/E,CAAC;YACJ,CAAC;YAAC,OAAO,MAAM,EAAE,CAAC;gBAChB,SAAS,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;gBAC9B,MAAM,CAAC,IAAI,CAAC,kBAAkB,KAAK,KAAK,KAAK,MAAM,SAAS,EAAE,CAAC,CAAC;gBAChE,IAAI,OAAO,GAAG,QAAQ;oBAAE,MAAM,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;YACzD,CAAC;QACH,CAAC;QAED,MAAM,CAAC,IAAI,CAAC,mBAAmB,KAAK,UAAU,MAAM,CAAC,QAAQ,CAAC,cAAc,SAAS,EAAE,CAAC,CAAC;QACzF,OAAO;YACL,EAAE,EAAE,KAAK;YACT,OAAO,EAAE,KAAK;YACd,QAAQ,EAAE,OAAO,CAAC,IAAI;YACtB,EAAE;YACF,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,QAAQ;YACR,KAAK,EAAE,SAAS;SACjB,CAAC;IACJ,CAAC;IAED;;;;;;;OAOG;IACH,SAAS,KAAK,CACZ,EAA4C,EAC5C,OAAkC,EAClC,KAA+F;QAE/F,MAAM,UAAU,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC;QACnC,MAAM,OAAO,GAAG,QAAQ,EAAE,CAAC;QAE3B,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,sEAAsE;YACtE,qEAAqE;YACrE,2DAA2D;YAC3D,MAAM,CAAC,IAAI,CACT,0CAA0C,UAAU;iBACjD,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,OAAO,CAAC;iBACrC,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAC9B,CAAC;YACF,OAAO,OAAO,CAAC,OAAO,CAAC;gBACrB,EAAE,EAAE,IAAI;gBACR,OAAO,EAAE,IAAI;gBACb,QAAQ,EAAE,MAAM;gBAChB,EAAE,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,OAAO,CAAC;gBACpD,OAAO,EAAE,EAAE;gBACX,QAAQ,EAAE,CAAC;aACZ,CAAC,CAAC;QACL,CAAC;QAED,OAAO,OAAO,CAAC,KAAK,IAAI,EAAE;YACxB,MAAM,QAAQ,GAAG,gBAAgB,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;YAErD,IAAI,IAAkE,CAAC;YACvE,IAAI,CAAC;gBACH,IAAI,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC;YACzB,CAAC;YAAC,OAAO,MAAM,EAAE,CAAC;gBAChB,kEAAkE;gBAClE,qEAAqE;gBACrE,qCAAqC;gBACrC,MAAM,KAAK,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;gBAChC,MAAM,CAAC,IAAI,CACT,iCAAiC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,KAAK,EAAE,CACzF,CAAC;gBACF,OAAO;oBACL,EAAE,EAAE,KAAK;oBACT,OAAO,EAAE,KAAK;oBACd,QAAQ,EAAE,OAAO,CAAC,IAAI;oBACtB,EAAE,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,OAAO,CAAC;oBACpD,OAAO,EAAE,EAAE;oBACX,QAAQ,EAAE,CAAC;oBACX,KAAK;iBACN,CAAC;YACJ,CAAC;YAED,MAAM,QAAQ,GAAG,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;YAElF,OAAO,MAAM,OAAO,CAAC,OAAO,EAAE;gBAC5B,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC;gBACpB,EAAE,EAAE,UAAU;gBACd,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;gBACxD,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,GAAG,CAAC,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC;aACxD,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC;IAED,OAAO;QACL,UAAU;YACR,OAAO,QAAQ,EAAE,KAAK,SAAS,CAAC;QAClC,CAAC;QAED,YAAY;YACV,OAAO,QAAQ,EAAE,EAAE,IAAI,IAAI,MAAM,CAAC;QACpC,CAAC;QAED,IAAI;YACF,OAAO,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC;QACnD,CAAC;QAED,IAAI,CAAC,OAAO;YACV,OAAO,KAAK,CAAC,OAAO,CAAC,EAAE,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,EAAE;gBACrD,MAAM,QAAQ,GAAG,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,QAAQ,EAAE;oBAClD,IAAI,EAAE,QAAQ;oBACd,OAAO,EAAE,MAAM,CAAC,OAAO;oBACvB,GAAG,OAAO,CAAC,IAAI;iBAChB,CAAC,CAAC;gBACH,OAAO;oBACL,+DAA+D;oBAC/D,oEAAoE;oBACpE,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,CAAC,QAAQ,CAAC,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC;oBACzF,IAAI,EAAE,QAAQ,CAAC,IAAI;oBACnB,GAAG,CAAC,QAAQ,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAC;iBAChE,CAAC;YACJ,CAAC,CAAC,CAAC;QACL,CAAC;QAED,OAAO,CAAC,OAAO;YACb,OAAO,KAAK,CAAC,OAAO,CAAC,EAAE,EAAE,OAAO,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC;gBAC/C,OAAO,EAAE,OAAO,CAAC,OAAO;gBACxB,IAAI,EAAE,OAAO,CAAC,IAAI;gBAClB,GAAG,CAAC,OAAO,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC;aAC9D,CAAC,CAAC,CAAC;QACN,CAAC;QAED,KAAK,CAAC,OAAO;YACX,MAAM,KAAK,CAAC;QACd,CAAC;KACF,CAAC;AACJ,CAAC;AAED,4EAA4E;AAC5E,SAAS,SAAS,CAAC,QAAsB;IACvC,OAAO,QAAQ,CAAC,WAAW,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,QAAQ,CAAC,WAAW,EAAE,CAAC;AACrF,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,eAAe,CAAC,OAAe;IACtC,IAAI,CAAC;QACH,OAAO,YAAY,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE,CAAC;IACjD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,oBAAoB,CAAC;IAC9B,CAAC;AACH,CAAC;AAED,mCAAmC;AACnC,SAAS,SAAS,CAAC,SAAwB;IACzC,OAAO,OAAO,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;AAC5E,CAAC;AAED,yEAAyE;AACzE,SAAS,WAAW,CAAC,EAA4C;IAC/D,IAAI,OAAO,EAAE,KAAK,QAAQ;QAAE,OAAO,CAAC,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC;IACrD,IAAI,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;QAAE,OAAQ,EAA+B,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IAC9E,OAAO,CAAC,SAAS,CAAC,EAAmB,CAAC,CAAC,CAAC;AAC1C,CAAC;AAED,iDAAiD;AACjD,SAAS,SAAS,CAAC,MAAe;IAChC,OAAO,MAAM,YAAY,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AACnE,CAAC;AAED,SAAS,MAAM;IACb,oEAAoE;AACtE,CAAC"}

package/dist/mail/smtp.d.ts

@@ -0,0 +1,39 @@
+import type { MailProvider } from './provider.ts';
+/**
+ * Any SMTP server, as one {@link MailProvider}.
+ *
+ * The other half of the pair Brevo's API is: an account on Fastmail, a relay
+ * on the same machine, Brevo's own SMTP relay, or whatever the host provides.
+ * nodemailer does the protocol; everything here is the two lines of
+ * translation between this package's {@link OutgoingMail} and the shape it
+ * wants.
+ *
+ * A transport is built per message rather than kept open. Sending is rare — a
+ * password reset, a comment notification — and a pooled connection to a server
+ * that has since restarted is a failure that only shows up on the message that
+ * mattered.
+ */
+/** How long a whole SMTP conversation is given. */
+export declare const SMTP_TIMEOUT_MS = 20000;
+/** What {@link createSmtpProvider} needs. Exactly what `data/mail.json` holds. */
+export interface SmtpProviderOptions {
+    /** The server's hostname. */
+    host: string;
+    /** The port: 587 for submission with STARTTLS, 465 for implicit TLS. */
+    port: number;
+    /**
+     * Whether the connection is TLS from the first byte, which is what port 465
+     * means. On 587 this is `false` and the connection is upgraded with
+     * STARTTLS when the server offers it.
+     */
+    secure: boolean;
+    /** The username, or empty for a server that wants no credentials. */
+    user?: string | undefined;
+    /** The password. */
+    password?: string | undefined;
+    /** How long the conversation is given. */
+    timeoutMs?: number | undefined;
+}
+/** A provider that hands each message to an SMTP server. */
+export declare function createSmtpProvider(options: SmtpProviderOptions): MailProvider;
+//# sourceMappingURL=smtp.d.ts.map

package/dist/mail/smtp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"smtp.d.ts","sourceRoot":"","sources":["../../src/mail/smtp.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAA6B,YAAY,EAAgB,MAAM,eAAe,CAAC;AAE3F;;;;;;;;;;;;;GAaG;AAEH,mDAAmD;AACnD,eAAO,MAAM,eAAe,QAAS,CAAC;AAEtC,kFAAkF;AAClF,MAAM,WAAW,mBAAmB;IAClC,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,MAAM,EAAE,OAAO,CAAC;IAChB,qEAAqE;IACrE,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,oBAAoB;IACpB,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAChC;AAED,4DAA4D;AAC5D,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,YAAY,CAoC7E"}

package/dist/mail/smtp.js

@@ -0,0 +1,58 @@
+import nodemailer from 'nodemailer';
+/**
+ * Any SMTP server, as one {@link MailProvider}.
+ *
+ * The other half of the pair Brevo's API is: an account on Fastmail, a relay
+ * on the same machine, Brevo's own SMTP relay, or whatever the host provides.
+ * nodemailer does the protocol; everything here is the two lines of
+ * translation between this package's {@link OutgoingMail} and the shape it
+ * wants.
+ *
+ * A transport is built per message rather than kept open. Sending is rare — a
+ * password reset, a comment notification — and a pooled connection to a server
+ * that has since restarted is a failure that only shows up on the message that
+ * mattered.
+ */
+/** How long a whole SMTP conversation is given. */
+export const SMTP_TIMEOUT_MS = 20_000;
+/** A provider that hands each message to an SMTP server. */
+export function createSmtpProvider(options) {
+    return {
+        name: 'smtp',
+        async deliver(message) {
+            const timeout = options.timeoutMs ?? SMTP_TIMEOUT_MS;
+            const transport = nodemailer.createTransport({
+                host: options.host,
+                port: options.port,
+                secure: options.secure,
+                ...(options.user === undefined || options.user === ''
+                    ? {}
+                    : { auth: { user: options.user, pass: options.password ?? '' } }),
+                connectionTimeout: timeout,
+                greetingTimeout: timeout,
+                socketTimeout: timeout,
+            });
+            try {
+                const sent = await transport.sendMail({
+                    from: address(message.from),
+                    to: message.to.map(address),
+                    ...(message.replyTo === undefined ? {} : { replyTo: address(message.replyTo) }),
+                    subject: message.subject,
+                    text: message.text,
+                    ...(message.html === undefined || message.html === '' ? {} : { html: message.html }),
+                });
+                return { messageId: sent.messageId };
+            }
+            finally {
+                // The transport holds a socket even unpooled; closing it is what keeps
+                // a long-running process from accumulating them.
+                transport.close();
+            }
+        },
+    };
+}
+/** One address as nodemailer wants it. */
+function address(value) {
+    return { name: value.name ?? '', address: value.address };
+}
+//# sourceMappingURL=smtp.js.map

package/dist/mail/smtp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"smtp.js","sourceRoot":"","sources":["../../src/mail/smtp.ts"],"names":[],"mappings":"AAAA,OAAO,UAAU,MAAM,YAAY,CAAC;AAIpC;;;;;;;;;;;;;GAaG;AAEH,mDAAmD;AACnD,MAAM,CAAC,MAAM,eAAe,GAAG,MAAM,CAAC;AAsBtC,4DAA4D;AAC5D,MAAM,UAAU,kBAAkB,CAAC,OAA4B;IAC7D,OAAO;QACL,IAAI,EAAE,MAAM;QAEZ,KAAK,CAAC,OAAO,CAAC,OAAqB;YACjC,MAAM,OAAO,GAAG,OAAO,CAAC,SAAS,IAAI,eAAe,CAAC;YACrD,MAAM,SAAS,GAAG,UAAU,CAAC,eAAe,CAAC;gBAC3C,IAAI,EAAE,OAAO,CAAC,IAAI;gBAClB,IAAI,EAAE,OAAO,CAAC,IAAI;gBAClB,MAAM,EAAE,OAAO,CAAC,MAAM;gBACtB,GAAG,CAAC,OAAO,CAAC,IAAI,KAAK,SAAS,IAAI,OAAO,CAAC,IAAI,KAAK,EAAE;oBACnD,CAAC,CAAC,EAAE;oBACJ,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,QAAQ,IAAI,EAAE,EAAE,EAAE,CAAC;gBACnE,iBAAiB,EAAE,OAAO;gBAC1B,eAAe,EAAE,OAAO;gBACxB,aAAa,EAAE,OAAO;aACvB,CAAC,CAAC;YAEH,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,MAAM,SAAS,CAAC,QAAQ,CAAC;oBACpC,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC;oBAC3B,EAAE,EAAE,OAAO,CAAC,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC;oBAC3B,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;oBAC/E,OAAO,EAAE,OAAO,CAAC,OAAO;oBACxB,IAAI,EAAE,OAAO,CAAC,IAAI;oBAClB,GAAG,CAAC,OAAO,CAAC,IAAI,KAAK,SAAS,IAAI,OAAO,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC;iBACrF,CAAC,CAAC;gBAEH,OAAO,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC;YACvC,CAAC;oBAAS,CAAC;gBACT,uEAAuE;gBACvE,iDAAiD;gBACjD,SAAS,CAAC,KAAK,EAAE,CAAC;YACpB,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC;AAED,0CAA0C;AAC1C,SAAS,OAAO,CAAC,KAAkB;IACjC,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,EAAE,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC;AAC5D,CAAC"}

package/dist/mail/templates.d.ts

@@ -0,0 +1,91 @@
+import type { Environment } from 'nunjucks';
+import type { ThemeSource } from '../web/themes.ts';
+/**
+ * What a message looks like before it is addressed: a subject, a plain text
+ * body, and an HTML twin when the theme wrote one.
+ *
+ * Messages are Nunjucks templates under `mail/` in the theme, looked up the
+ * way every other template is — the theme the site has chosen first, the theme
+ * that ships in this package second, file by file. So a theme overrides the
+ * text of one message and keeps the subject and the HTML the package ships,
+ * and one that writes `mail/welcome.txt.njk` has a message the package never
+ * had.
+ *
+ * Three files rather than one, because the three parts of a message have
+ * nothing to do with each other: a subject is one line with no markup, a text
+ * body is what most mail readers show, and the HTML twin is optional
+ * throughout. A message with no `.html.njk` is sent as plain text, which is
+ * the right thing rather than a missing feature.
+ */
+/** One rendered message, ready to be addressed and handed to a provider. */
+export interface RenderedMail {
+    /**
+     * The subject, on one line. Empty when the message has no `.subject.njk`,
+     * in which case the caller's own subject is what is sent.
+     */
+    readonly subject: string;
+    /** The plain text body. Every message has one. */
+    readonly text: string;
+    /** The HTML twin, when the theme wrote one. */
+    readonly html?: string | undefined;
+}
+/** The three templates one message is built from. */
+export interface MailTemplateFiles {
+    /** The subject line. Optional. */
+    readonly subject: string;
+    /** The plain text body. Required. */
+    readonly text: string;
+    /** The HTML twin. Optional. */
+    readonly html: string;
+}
+/** Which files a named message is built from, relative to a theme directory. */
+export declare function mailTemplateFiles(name: string): MailTemplateFiles;
+/** What {@link createMailTemplates} needs. */
+export interface CreateMailTemplatesOptions {
+    /**
+     * Which theme the messages are read from, asked per message.
+     *
+     * A source rather than a directory because mail is part of the theme
+     * (decision-15): a site that changes theme changes the words its password
+     * resets and moderation notices are written in, and the message after the
+     * change should be the new theme's rather than the next boot's.
+     */
+    themes: ThemeSource;
+    /** Public origin, for the `url` and `absoluteUrl` filters. */
+    baseUrl: string;
+    /**
+     * Recompile a template on every render instead of caching it. On while the
+     * content watcher is on, so editing a message in development shows up
+     * without a restart, exactly as editing a layout does.
+     */
+    noCache?: boolean | undefined;
+}
+/** Turns a named message and some data into the three parts of an email. */
+export interface MailTemplates {
+    /**
+     * Render one message.
+     *
+     * Throws when there is no `.txt.njk` for that name anywhere on the search
+     * path — a message with no body is a mistake in the calling code, and
+     * sending an empty one would hide it.
+     */
+    render(name: string, context?: Record<string, unknown>): RenderedMail;
+    /**
+     * The Nunjucks environment the HTML half renders through, for a site that
+     * wants to add its own filters.
+     */
+    readonly environment: Environment;
+    /**
+     * The twin the subject and the text body render through: the same loader and
+     * the same filters, with autoescaping off.
+     *
+     * A plain text body is not HTML. Escaping it turns the `&` between two query
+     * parameters into `&amp;` — which is what a one-click moderation link is
+     * made of (TASK-55) — and an apostrophe in somebody's name into `&#39;`. A
+     * site adding a filter that both halves should have adds it to both.
+     */
+    readonly plainEnvironment: Environment;
+}
+/** Build the mail templates for one site. */
+export declare function createMailTemplates(options: CreateMailTemplatesOptions): MailTemplates;
+//# sourceMappingURL=templates.d.ts.map

package/dist/mail/templates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates.d.ts","sourceRoot":"","sources":["../../src/mail/templates.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAI5C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD;;;;;;;;;;;;;;;;GAgBG;AAEH,4EAA4E;AAC5E,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACpC;AAED,qDAAqD;AACrD,MAAM,WAAW,iBAAiB;IAChC,kCAAkC;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,qCAAqC;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,gFAAgF;AAChF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,CAMjE;AAED,8CAA8C;AAC9C,MAAM,WAAW,0BAA0B;IACzC;;;;;;;OAOG;IACH,MAAM,EAAE,WAAW,CAAC;IACpB,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAC/B;AAED,4EAA4E;AAC5E,MAAM,WAAW,aAAa;IAC5B;;;;;;OAMG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,YAAY,CAAC;IACtE;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC;;;;;;;;OAQG;IACH,QAAQ,CAAC,gBAAgB,EAAE,WAAW,CAAC;CACxC;AAED,6CAA6C;AAC7C,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,0BAA0B,GAAG,aAAa,CAkEtF"}