@dsbot-channel/mail 0.0.0-stage → 0.7.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zerodegress
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/assets/skill.md

@@ -0,0 +1,21 @@
+### mail transport
+
+| Field | Default | Meaning |
+| --- | --- | --- |
+| `imap.host` / `imap.port` / `imap.user` / `imap.password` | required | the mailbox the link reads; `password` is a credential reference |
+| `imap.secure` | `true` | TLS to the mailbox; `false` reads plaintext |
+| `imap.mailbox` | `INBOX` | folder to poll |
+| `imap.pollMs` | `30000` | how often the folder is read |
+| `smtp.host` / `smtp.port` / `smtp.user` / `smtp.password` | required | where an answer is sent; `password` is a credential reference |
+| `smtp.secure` | `true` | `true`, `false` or `starttls` |
+| `from` | required | the address answers are sent from |
+| `signature` | off | text appended after the answer |
+| `listUnsubscribe` | off | `List-Unsubscribe` value on an answer |
+| `bots` | `[]` | senders counted as bot speech |
+| `lists` | `[]` | addresses that count as lists when the headers do not name one |
+| `maxAttachmentBytes` | `10485760` | largest attachment recorded; larger ones are dropped with a warning |
+
+A thread is a room keyed by its root: `mail:<thread-root>`; the root is the first `References` entry, else `In-Reply-To`, else the message's own `Message-ID`. An answer carries `In-Reply-To` and the whole `References` chain; a list message answers the list, a direct message answers its sender. HTML is read as text with scripts, styles and images dropped; an attachment is not passed to the model, only its name, type and size are recorded. The IMAP and SMTP links run through `imapflow` and `nodemailer`; the fields do not depend on them.
+
+`@dsbot-channel/mail` supplies this transport: mount it after `@dsbot-channel/core`, then write these fields under `transport` in this plugin's own `config`, beside `channel` and `botName`; `kind` is not written. Each entry is one instance, so the same package mounts twice with two different `channel` values. Without `@dsbot-channel/core` the plugin stays pending on `dsbot-channel.registry`.
+

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: dsbot-channel-mail
+      name: '@dsbot-channel/mail'

package/dist/adapter.d.ts

@@ -0,0 +1,72 @@
+import type { AdapterStatus, CapabilitySet } from '@dsbot-channel/core/adapter-status.js';
+import type { AdapterHandle, AdapterPorts, ChannelAdapter, SendInput, SendResult } from '@dsbot-channel/core/contract.js';
+import type { MailTransport } from './transport.js';
+export interface MailConfig {
+    channel: string;
+    botName: string;
+    from: string;
+    imap: {
+        host: string;
+        port: number;
+        secure: boolean;
+        user: string;
+        password: string;
+        mailbox: string;
+        pollMs: number;
+    };
+    smtp: {
+        host: string;
+        port: number;
+        secure: boolean | 'starttls';
+        user: string;
+        password: string;
+    };
+    signature?: string | undefined;
+    listUnsubscribe?: string | undefined;
+    bots: readonly string[];
+    lists: readonly string[];
+    maxAttachmentBytes?: number | undefined;
+}
+export interface MailOptions {
+    warn?: ((message: string) => void) | undefined;
+    now?: (() => number) | undefined;
+    transport?: MailTransport | undefined;
+}
+interface Origin {
+    subject: string;
+    messageId: string;
+    references: string;
+}
+/** A reply is plain text with the headers that hold the thread together. */
+export declare function composeReply(input: {
+    from: string;
+    to: string;
+    subject: string;
+    messageId: string;
+    origin?: Origin | undefined;
+    text: string;
+    signature?: string | undefined;
+    listUnsubscribe?: string | undefined;
+    date: Date;
+}): {
+    data: string;
+    messageId: string;
+};
+export declare class MailAdapter implements ChannelAdapter {
+    #private;
+    readonly kind = "mail";
+    readonly capabilities: CapabilitySet;
+    readonly guidance: {
+        peer: string;
+        group: string;
+    };
+    constructor(config: MailConfig, options?: MailOptions);
+    checkConfig(): void;
+    checkSessionKey(key: string): string | undefined;
+    checkTarget(target: string): string | undefined;
+    describeTargets(): string;
+    status(): AdapterStatus;
+    start(ports: AdapterPorts): Promise<AdapterHandle>;
+    send(input: SendInput): Promise<SendResult>;
+}
+export {};

package/dist/adapter.js

@@ -0,0 +1,244 @@
+import { NO_MEDIA, buildListenerHealth, buildStatus } from '@dsbot-channel/core/adapter-status.js';
+import { ConfigError } from '@dsbot-channel/core/config.js';
+import { ChannelStats, countersOf } from '@dsbot-channel/core/channel-stats.js';
+import { parseMail } from './mime.js';
+import { mapMail, newMessageId, replyHeadersOf } from './mapping.js';
+import { ImapSmtpTransport } from './transport.js';
+const ORIGINS_MAX = 200;
+const DELIVERED_MAX = 1024;
+const CAPABILITIES = {
+    text: true,
+    image: NO_MEDIA,
+    file: NO_MEDIA,
+    voice: NO_MEDIA,
+    recall: false,
+    history: { group: false, private: false },
+    mention: false,
+    reply: false,
+    stream: false,
+    outbound: true,
+};
+/** A reply is plain text with the headers that hold the thread together. */
+export function composeReply(input) {
+    const headers = [
+        `From: ${input.from}`,
+        `To: ${input.to}`,
+        `Subject: ${input.subject}`,
+        `Date: ${input.date.toUTCString()}`,
+        `Message-ID: ${input.messageId}`,
+        ...(input.origin === undefined ? [] : [`In-Reply-To: <${input.origin.messageId}>`, `References: ${input.origin.references}`]),
+        'MIME-Version: 1.0',
+        'Content-Type: text/plain; charset=utf-8',
+        'Content-Transfer-Encoding: 8bit',
+        ...(input.listUnsubscribe === undefined ? [] : [`List-Unsubscribe: <${input.listUnsubscribe}>`]),
+    ];
+    const body = input.signature === undefined ? input.text : `${input.text}\n\n-- \n${input.signature}`;
+    return { data: `${headers.join('\r\n')}\r\n\r\n${body.replace(/\r?\n/g, '\r\n')}\r\n`, messageId: input.messageId };
+}
+export class MailAdapter {
+    kind = 'mail';
+    capabilities = CAPABILITIES;
+    guidance = {
+        peer: 'Mail is a letter: answer in plain text, keep it short, and never quote a whole thread.',
+        group: 'A mailing list is a room: answer in plain text to the list, and do not answer your own mail.',
+    };
+    #config;
+    #warn;
+    #now;
+    #stats = new ChannelStats();
+    #origins = new Map();
+    #delivered = new Map();
+    #transport;
+    #cursor;
+    #timer;
+    #polling = false;
+    #stopped = false;
+    #lastPollAt = null;
+    constructor(config, options = {}) {
+        this.#config = config;
+        this.#warn = options.warn ?? (() => undefined);
+        this.#now = options.now ?? Date.now;
+        this.#transport = options.transport;
+    }
+    checkConfig() {
+        if (this.#config.from.length === 0)
+            this.#fail('transport.from is required', ['transport', 'from']);
+        if (this.#config.imap.pollMs < 1000)
+            this.#fail('transport.imap.pollMs must be at least 1000', ['transport', 'imap', 'pollMs']);
+    }
+    checkSessionKey(key) {
+        if (!key.startsWith('mail:') || key.length <= 'mail:'.length)
+            return 'a mail session key reads "mail:<thread-root>"';
+        return undefined;
+    }
+    checkTarget(target) {
+        return /^[^@\s]+@[^@\s]+$/.test(target) ? undefined : 'a mail reply target is one address';
+    }
+    describeTargets() {
+        return '<user@host>';
+    }
+    status() {
+        const snapshot = this.#stats.snapshot();
+        const counters = countersOf(snapshot);
+        return buildStatus({
+            channel: this.#config.channel,
+            account: this.#config.imap.user,
+            bot: this.#config.botName,
+            health: buildListenerHealth({
+                listenState: this.#stopped ? 'stopped' : this.#lastPollAt === null ? 'stopped' : 'listening',
+                boundPort: null,
+                lastAuthenticatedAt: snapshot.lastAuthenticatedAt,
+                queueDepth: 0,
+            }),
+            counters,
+            capabilities: this.capabilities,
+            attributes: { stableMessageId: true },
+            quota: { softLimit: 0, hardLimit: 0 },
+            sampledAt: this.#now(),
+            queueDepth: 0,
+        });
+    }
+    async start(ports) {
+        const imapPassword = await ports.resolveSecret(this.#config.imap.password);
+        if (imapPassword === undefined)
+            this.#fail(`credential "${this.#config.imap.password}" did not resolve`, ['transport', 'imap', 'password']);
+        const smtpPassword = await ports.resolveSecret(this.#config.smtp.password);
+        if (smtpPassword === undefined)
+            this.#fail(`credential "${this.#config.smtp.password}" did not resolve`, ['transport', 'smtp', 'password']);
+        if (this.#transport === undefined) {
+            this.#transport = new ImapSmtpTransport({ ...this.#config.imap, password: imapPassword }, { ...this.#config.smtp, password: smtpPassword });
+        }
+        this.#timer = setInterval(() => {
+            void this.#poll(ports);
+        }, this.#config.imap.pollMs);
+        this.#timer.unref?.();
+        void this.#poll(ports);
+        return {
+            stop: async () => {
+                this.#stopped = true;
+                if (this.#timer !== undefined)
+                    clearInterval(this.#timer);
+                this.#timer = undefined;
+                await this.#transport?.close();
+                this.#stats.closed();
+            },
+        };
+    }
+    async send(input) {
+        const transport = this.#transport;
+        if (transport === undefined)
+            return { ok: false, code: 'no_url', reason: 'the mail link is not running', retryable: false };
+        if (!/^[^@\s]+@[^@\s]+$/.test(input.target)) {
+            return { ok: false, code: 'no_url', reason: `"${input.target}" is not a mail address`, retryable: false };
+        }
+        const origin = this.#origins.get(input.inReplyTo ?? '');
+        const subject = origin === undefined ? `Re: ${input.body.split('\n')[0]?.slice(0, 60) ?? ''}` : `${origin.subject}`;
+        const data = composeReply({
+            from: this.#config.from,
+            to: input.target,
+            subject,
+            messageId: newMessageId(this.#config.from),
+            origin,
+            text: input.body,
+            signature: this.#config.signature,
+            listUnsubscribe: this.#config.listUnsubscribe,
+            date: new Date(this.#now()),
+        });
+        try {
+            await transport.send({ from: this.#config.from, to: [input.target] }, Buffer.from(data.data));
+            return { ok: true, messageId: data.messageId, duplicate: false };
+        }
+        catch (error) {
+            const code = error.code;
+            const mapped = code === 'EAUTH' || code === 'EAUTHENTICATION' ? 'credential' : code === 'ETIMEDOUT' ? 'timeout' : 'unreachable';
+            this.#stats.sendFailed(mapped);
+            return { ok: false, code: mapped, reason: String(error), retryable: mapped !== 'credential' };
+        }
+    }
+    async #poll(ports) {
+        if (this.#polling || this.#stopped || this.#transport === undefined)
+            return;
+        this.#polling = true;
+        try {
+            const mailbox = this.#config.imap.mailbox;
+            const batch = await this.#transport.fetch(mailbox, this.#cursor);
+            this.#lastPollAt = this.#now();
+            this.#stats.authenticated();
+            if (this.#cursor === undefined) {
+                this.#cursor = { uidValidity: batch.uidValidity, uid: batch.maxUid };
+                return;
+            }
+            for (const item of batch.messages) {
+                if (this.#stopped)
+                    break;
+                let message = undefined;
+                let mail = undefined;
+                try {
+                    mail = parseMail(item.raw, this.#config.maxAttachmentBytes);
+                    message = mapMail({
+                        mail,
+                        config: { channel: this.#config.channel, from: this.#config.from, bots: this.#config.bots, lists: this.#config.lists },
+                        receivedAt: this.#now(),
+                    });
+                }
+                catch (error) {
+                    this.#stats.rejected(`mail ${item.uid} could not be read: ${String(error)}`);
+                    this.#warn(`dsbot-channel: mail ${item.uid} could not be read and was skipped: ${String(error)}`);
+                    this.#cursor = { uidValidity: batch.uidValidity, uid: item.uid };
+                    continue;
+                }
+                if (this.#delivered.has(message.requestId)) {
+                    this.#cursor = { uidValidity: batch.uidValidity, uid: item.uid };
+                    continue;
+                }
+                if (mail.attachments.length > 0) {
+                    this.#warn(`dsbot-channel: mail ${message.requestId} carries ${mail.attachments.length} attachment(s) that are not delivered`);
+                }
+                this.#remember(message.requestId, mail);
+                this.#stats.event(`mail.${message.source.scope}`);
+                const verdict = await ports.onMessage(message);
+                if (!verdict.ok && verdict.code === 'busy') {
+                    this.#warn(`dsbot-channel: mail ${message.requestId} was not taken while busy; it stays for the next poll`);
+                    break;
+                }
+                this.#delivered.set(message.requestId, true);
+                while (this.#delivered.size > DELIVERED_MAX) {
+                    const oldest = this.#delivered.keys().next();
+                    if (oldest.done === true)
+                        break;
+                    this.#delivered.delete(oldest.value);
+                }
+                if (verdict.ok) {
+                    await this.#transport.markSeen(mailbox, [item.uid]).catch((error) => {
+                        this.#warn(`dsbot-channel: mail ${message.requestId} was taken but could not be marked seen: ${String(error)}`);
+                    });
+                }
+                this.#cursor = { uidValidity: batch.uidValidity, uid: item.uid };
+            }
+        }
+        catch (error) {
+            this.#stats.rejected(`poll failed: ${String(error)}`);
+            this.#warn(`dsbot-channel: mail poll failed: ${String(error)}`);
+        }
+        finally {
+            this.#polling = false;
+        }
+    }
+    #remember(requestId, mail) {
+        const headers = replyHeadersOf(mail);
+        this.#origins.set(requestId, {
+            subject: headers.subject,
+            messageId: headers.inReplyTo ?? '',
+            references: headers.references ?? '',
+        });
+        while (this.#origins.size > ORIGINS_MAX) {
+            const oldest = this.#origins.keys().next();
+            if (oldest.done === true)
+                break;
+            this.#origins.delete(oldest.value);
+        }
+    }
+    #fail(message, path) {
+        throw new ConfigError(message, path);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,107 @@
+import type { AdapterFactory, AdapterMount } from '@dsbot-channel/core/adapter-registry.js';
+import { MailAdapter } from './adapter.js';
+import type { MailConfig } from './adapter.js';
+/** Reads the mail block; every named field is checked, so a typo fails at mount. */
+export declare function parseMailConfig(mount: AdapterMount): MailConfig;
+export declare const createMailAdapter: AdapterFactory;
+export { MailAdapter };
+export type { MailConfig };
+export declare const Config: import("@deepseek-ai/schemastery").default<Schemastery.ObjectS<NoInfer<{
+    channel: import("@deepseek-ai/schemastery").default<string, string, "plain">;
+    botName: import("@deepseek-ai/schemastery").default<string, string, "plain">;
+    anchor: import("@deepseek-ai/schemastery").default<string, string, "plain">;
+    session: import("@deepseek-ai/schemastery").default<string, string, "plain">;
+    model: import("@deepseek-ai/schemastery").default<string, string, "plain">;
+    reply: import("@deepseek-ai/schemastery").default<any, any, "plain">;
+    turn: import("@deepseek-ai/schemastery").default<any, any, "plain">;
+    delivery: import("@deepseek-ai/schemastery").default<any, any, "plain">;
+    policy: import("@deepseek-ai/schemastery").default<any, any, "plain">;
+    pipeline: import("@deepseek-ai/schemastery").default<any, any, "plain">;
+    events: import("@deepseek-ai/schemastery").default<any, any, "plain">;
+    status: import("@deepseek-ai/schemastery").default<boolean, boolean, "plain">;
+    transport: import("@deepseek-ai/schemastery").default<any, any, "plain">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    channel: import("@deepseek-ai/schemastery").default<string, string, "plain">;
+    botName: import("@deepseek-ai/schemastery").default<string, string, "plain">;
+    anchor: import("@deepseek-ai/schemastery").default<string, string, "plain">;
+    session: import("@deepseek-ai/schemastery").default<string, string, "plain">;
+    model: import("@deepseek-ai/schemastery").default<string, string, "plain">;
+    reply: import("@deepseek-ai/schemastery").default<any, any, "plain">;
+    turn: import("@deepseek-ai/schemastery").default<any, any, "plain">;
+    delivery: import("@deepseek-ai/schemastery").default<any, any, "plain">;
+    policy: import("@deepseek-ai/schemastery").default<any, any, "plain">;
+    pipeline: import("@deepseek-ai/schemastery").default<any, any, "plain">;
+    events: import("@deepseek-ai/schemastery").default<any, any, "plain">;
+    status: import("@deepseek-ai/schemastery").default<boolean, boolean, "plain">;
+    transport: import("@deepseek-ai/schemastery").default<any, any, "plain">;
+}>>, "plain">;
+export declare const apply: (ctx: import("@deepseek-ai/cordis").Context, config?: Record<string, unknown>) => void;
+export declare const plugin: {
+    name: string;
+    inject: string[];
+    Config: import("@deepseek-ai/schemastery").default<Schemastery.ObjectS<NoInfer<{
+        channel: import("@deepseek-ai/schemastery").default<string, string, "plain">;
+        botName: import("@deepseek-ai/schemastery").default<string, string, "plain">;
+        anchor: import("@deepseek-ai/schemastery").default<string, string, "plain">;
+        session: import("@deepseek-ai/schemastery").default<string, string, "plain">;
+        model: import("@deepseek-ai/schemastery").default<string, string, "plain">;
+        reply: import("@deepseek-ai/schemastery").default<any, any, "plain">;
+        turn: import("@deepseek-ai/schemastery").default<any, any, "plain">;
+        delivery: import("@deepseek-ai/schemastery").default<any, any, "plain">;
+        policy: import("@deepseek-ai/schemastery").default<any, any, "plain">;
+        pipeline: import("@deepseek-ai/schemastery").default<any, any, "plain">;
+        events: import("@deepseek-ai/schemastery").default<any, any, "plain">;
+        status: import("@deepseek-ai/schemastery").default<boolean, boolean, "plain">;
+        transport: import("@deepseek-ai/schemastery").default<any, any, "plain">;
+    }>>, Schemastery.ObjectT<NoInfer<{
+        channel: import("@deepseek-ai/schemastery").default<string, string, "plain">;
+        botName: import("@deepseek-ai/schemastery").default<string, string, "plain">;
+        anchor: import("@deepseek-ai/schemastery").default<string, string, "plain">;
+        session: import("@deepseek-ai/schemastery").default<string, string, "plain">;
+        model: import("@deepseek-ai/schemastery").default<string, string, "plain">;
+        reply: import("@deepseek-ai/schemastery").default<any, any, "plain">;
+        turn: import("@deepseek-ai/schemastery").default<any, any, "plain">;
+        delivery: import("@deepseek-ai/schemastery").default<any, any, "plain">;
+        policy: import("@deepseek-ai/schemastery").default<any, any, "plain">;
+        pipeline: import("@deepseek-ai/schemastery").default<any, any, "plain">;
+        events: import("@deepseek-ai/schemastery").default<any, any, "plain">;
+        status: import("@deepseek-ai/schemastery").default<boolean, boolean, "plain">;
+        transport: import("@deepseek-ai/schemastery").default<any, any, "plain">;
+    }>>, "plain">;
+    apply: (ctx: import("@deepseek-ai/cordis").Context, config?: Record<string, unknown>) => void;
+};
+declare const _default: {
+    name: string;
+    inject: string[];
+    Config: import("@deepseek-ai/schemastery").default<Schemastery.ObjectS<NoInfer<{
+        channel: import("@deepseek-ai/schemastery").default<string, string, "plain">;
+        botName: import("@deepseek-ai/schemastery").default<string, string, "plain">;
+        anchor: import("@deepseek-ai/schemastery").default<string, string, "plain">;
+        session: import("@deepseek-ai/schemastery").default<string, string, "plain">;
+        model: import("@deepseek-ai/schemastery").default<string, string, "plain">;
+        reply: import("@deepseek-ai/schemastery").default<any, any, "plain">;
+        turn: import("@deepseek-ai/schemastery").default<any, any, "plain">;
+        delivery: import("@deepseek-ai/schemastery").default<any, any, "plain">;
+        policy: import("@deepseek-ai/schemastery").default<any, any, "plain">;
+        pipeline: import("@deepseek-ai/schemastery").default<any, any, "plain">;
+        events: import("@deepseek-ai/schemastery").default<any, any, "plain">;
+        status: import("@deepseek-ai/schemastery").default<boolean, boolean, "plain">;
+        transport: import("@deepseek-ai/schemastery").default<any, any, "plain">;
+    }>>, Schemastery.ObjectT<NoInfer<{
+        channel: import("@deepseek-ai/schemastery").default<string, string, "plain">;
+        botName: import("@deepseek-ai/schemastery").default<string, string, "plain">;
+        anchor: import("@deepseek-ai/schemastery").default<string, string, "plain">;
+        session: import("@deepseek-ai/schemastery").default<string, string, "plain">;
+        model: import("@deepseek-ai/schemastery").default<string, string, "plain">;
+        reply: import("@deepseek-ai/schemastery").default<any, any, "plain">;
+        turn: import("@deepseek-ai/schemastery").default<any, any, "plain">;
+        delivery: import("@deepseek-ai/schemastery").default<any, any, "plain">;
+        policy: import("@deepseek-ai/schemastery").default<any, any, "plain">;
+        pipeline: import("@deepseek-ai/schemastery").default<any, any, "plain">;
+        events: import("@deepseek-ai/schemastery").default<any, any, "plain">;
+        status: import("@deepseek-ai/schemastery").default<boolean, boolean, "plain">;
+        transport: import("@deepseek-ai/schemastery").default<any, any, "plain">;
+    }>>, "plain">;
+    apply: (ctx: import("@deepseek-ai/cordis").Context, config?: Record<string, unknown>) => void;
+};
+export default _default;

package/dist/index.js

@@ -0,0 +1,116 @@
+import { makeAdapterPlugin } from '@dsbot-channel/core/adapter-plugin.js';
+import { ConfigError } from '@dsbot-channel/core/config.js';
+import { MailAdapter } from './adapter.js';
+const FIELDS = new Set([
+    'imap',
+    'smtp',
+    'from',
+    'signature',
+    'listUnsubscribe',
+    'bots',
+    'lists',
+    'maxAttachmentBytes',
+]);
+function refuse(message, path = ['transport']) {
+    throw new ConfigError(message, path);
+}
+function block(value, name) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        refuse(`transport.${name} must be a mapping`, ['transport', name]);
+    }
+    return value;
+}
+function host(value, name) {
+    if (typeof value !== 'string' || value.length === 0)
+        refuse(`transport.${name}.host is required`, ['transport', name, 'host']);
+    return value;
+}
+function port(value, name) {
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 1 || value > 65535) {
+        refuse(`transport.${name}.port must be a whole number between 1 and 65535`, ['transport', name, 'port']);
+    }
+    return value;
+}
+function user(value, name) {
+    if (typeof value !== 'string' || value.length === 0)
+        refuse(`transport.${name}.user is required`, ['transport', name, 'user']);
+    return value;
+}
+function strings(value, name) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        refuse(`transport.${name} must be a list of names`, ['transport', name]);
+    return value.map((one, index) => {
+        if (typeof one !== 'string' || one.length === 0)
+            refuse(`transport.${name}[${index}] must be a non-empty string`, ['transport', name, index]);
+        return one;
+    });
+}
+/** Reads the mail block; every named field is checked, so a typo fails at mount. */
+export function parseMailConfig(mount) {
+    const raw = mount.transport;
+    const unknown = Object.keys(raw).filter((key) => !FIELDS.has(key));
+    if (unknown.length > 0)
+        refuse(`transport names a field this adapter does not read: ${unknown.join(', ')}`);
+    const imap = block(raw.imap, 'imap');
+    const smtp = block(raw.smtp, 'smtp');
+    const from = raw.from;
+    if (typeof from !== 'string' || !/^[^@\s]+@[^@\s]+$/.test(from)) {
+        refuse(`transport.from must be one mail address: ${String(from)}`, ['transport', 'from']);
+    }
+    const smtpSecure = smtp.secure;
+    if (smtpSecure !== undefined && typeof smtpSecure !== 'boolean' && smtpSecure !== 'starttls') {
+        refuse('transport.smtp.secure must be true, false or "starttls"', ['transport', 'smtp', 'secure']);
+    }
+    const imapSecure = imap.secure;
+    if (imapSecure !== undefined && typeof imapSecure !== 'boolean') {
+        refuse('transport.imap.secure must be true or false', ['transport', 'imap', 'secure']);
+    }
+    const pollMs = imap.pollMs;
+    if (pollMs !== undefined && (typeof pollMs !== 'number' || !Number.isInteger(pollMs) || pollMs < 1000)) {
+        refuse(`transport.imap.pollMs must be a whole number of milliseconds, at least 1000: ${String(pollMs)}`, ['transport', 'imap', 'pollMs']);
+    }
+    const maxAttachmentBytes = raw.maxAttachmentBytes;
+    if (maxAttachmentBytes !== undefined && (typeof maxAttachmentBytes !== 'number' || maxAttachmentBytes < 0)) {
+        refuse('transport.maxAttachmentBytes must be a positive number', ['transport', 'maxAttachmentBytes']);
+    }
+    return {
+        channel: mount.channel,
+        botName: mount.botName,
+        from,
+        imap: {
+            host: host(imap.host, 'imap'),
+            port: port(imap.port, 'imap'),
+            secure: imap.secure !== false,
+            user: user(imap.user, 'imap'),
+            password: user(imap.password, 'imap'),
+            mailbox: typeof imap.mailbox === 'string' && imap.mailbox.length > 0 ? imap.mailbox : 'INBOX',
+            pollMs: typeof pollMs === 'number' ? pollMs : 30_000,
+        },
+        smtp: {
+            host: host(smtp.host, 'smtp'),
+            port: port(smtp.port, 'smtp'),
+            secure: smtpSecure === undefined ? true : smtpSecure,
+            user: user(smtp.user, 'smtp'),
+            password: user(smtp.password, 'smtp'),
+        },
+        ...(typeof raw.signature === 'string' ? { signature: raw.signature } : {}),
+        ...(typeof raw.listUnsubscribe === 'string' ? { listUnsubscribe: raw.listUnsubscribe } : {}),
+        bots: strings(raw.bots, 'bots'),
+        lists: strings(raw.lists, 'lists'),
+        ...(typeof maxAttachmentBytes === 'number' ? { maxAttachmentBytes } : {}),
+    };
+}
+export const createMailAdapter = (mount, options) => new MailAdapter(parseMailConfig(mount), options);
+export { MailAdapter };
+const adapter = makeAdapterPlugin({
+    name: 'dsbot-channel/mail',
+    kind: 'mail',
+    factory: createMailAdapter,
+    check: parseMailConfig,
+});
+export const Config = adapter.Config;
+export const apply = adapter.apply;
+export const plugin = adapter.plugin;
+export default adapter.plugin;

package/dist/mapping.d.ts

@@ -0,0 +1,35 @@
+import type { InboundMessage } from '@dsbot-channel/core/contract.js';
+import type { ParsedMail } from './mime.js';
+export interface MailView {
+    channel: string;
+    from: string;
+    bots: readonly string[];
+    lists: readonly string[];
+}
+export declare const SESSION_MAX = 128;
+export declare const MAIL_ID_MAX = 256;
+export declare const REFERENCES_MAX = 20;
+/** The thread a message belongs to: the first reference, else the parent, else the message itself. */
+export declare function threadRootOf(mail: ParsedMail): string;
+/** The message id core carries: no angle brackets, bounded, and stable for a redelivery. */
+export declare function messageIdOf(mail: ParsedMail): string;
+/** The address a reply goes to: the list when one is named, the sender otherwise. */
+export declare function replyAddressOf(mail: ParsedMail, lists: readonly string[]): string;
+/** A list is a room: it names itself in the headers, or the profile lists its address. */
+export declare function isList(mail: ParsedMail, lists: readonly string[]): boolean;
+export interface MailMappingInput {
+    mail: ParsedMail;
+    config: MailView;
+    receivedAt: number;
+}
+/** One mail on the wire becomes one inbound event. */
+export declare function mapMail(input: MailMappingInput): InboundMessage;
+export interface ReplyHeaders {
+    subject: string;
+    inReplyTo?: string;
+    references?: string;
+}
+/** The headers a reply carries so the thread stays one chain. */
+export declare function replyHeadersOf(mail: ParsedMail): ReplyHeaders;
+/** A fresh message id on the configured domain. */
+export declare function newMessageId(from: string): string;

package/dist/mapping.js

@@ -0,0 +1,104 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { addressOf, cleanId } from './mime.js';
+export const SESSION_MAX = 128;
+export const MAIL_ID_MAX = 256;
+export const REFERENCES_MAX = 20;
+function hashOf(value, length = 32) {
+    return createHash('sha256').update(value).digest('hex').slice(0, length);
+}
+/** The thread a message belongs to: the first reference, else the parent, else the message itself. */
+export function threadRootOf(mail) {
+    const root = cleanId(mail.references[0]) || cleanId(mail.inReplyTo) || cleanId(mail.messageId);
+    return root === '' ? hashOf(`${addressOf(mail.from)}|${mail.subject}|${mail.date ?? 0}`, 16) : root;
+}
+/** The message id core carries: no angle brackets, bounded, and stable for a redelivery. */
+export function messageIdOf(mail) {
+    const cleaned = cleanId(mail.messageId);
+    if (cleaned === '')
+        return hashOf(`${addressOf(mail.from)}|${mail.subject}|${mail.date ?? 0}|${mail.text.slice(0, 64)}`);
+    return cleaned.length > MAIL_ID_MAX ? hashOf(cleaned) : cleaned;
+}
+/** The address a reply goes to: the list when one is named, the sender otherwise. */
+export function replyAddressOf(mail, lists) {
+    const listPost = mail.headers['list-post']?.[0];
+    const posted = listPost === undefined ? undefined : /<mailto:([^>]+)>/i.exec(listPost)?.[1];
+    if (posted !== undefined && posted.trim() !== '')
+        return posted.trim();
+    const replyTo = cleanId(mail.headers['reply-to']?.[0]);
+    if (replyTo !== '')
+        return addressOf(replyTo);
+    const from = addressOf(mail.from);
+    const listed = lists.find((one) => one.toLowerCase() === from.toLowerCase());
+    return listed ?? from;
+}
+/** A list is a room: it names itself in the headers, or the profile lists its address. */
+export function isList(mail, lists) {
+    if (mail.headers['list-post'] !== undefined || mail.headers['list-id'] !== undefined)
+        return true;
+    const from = addressOf(mail.from).toLowerCase();
+    return lists.some((one) => one.toLowerCase() === from);
+}
+function attachmentMeta(attachments) {
+    return attachments.map((one) => ({ name: one.name, type: one.type, size: one.size }));
+}
+/** One mail on the wire becomes one inbound event. */
+export function mapMail(input) {
+    const { mail, config } = input;
+    const messageId = messageIdOf(mail);
+    const root = threadRootOf(mail);
+    const sessionBase = `mail:${root}`;
+    const sessionKey = sessionBase.length > SESSION_MAX ? `mail:${hashOf(root, 32)}` : sessionBase;
+    const list = isList(mail, config.lists);
+    const target = replyAddressOf(mail, config.lists);
+    const from = addressOf(mail.from);
+    const isBot = config.bots.some((one) => one.toLowerCase() === from.toLowerCase());
+    const references = mail.references.map((one) => cleanId(one)).filter((one) => one !== '').slice(0, REFERENCES_MAX);
+    return {
+        eventKey: `mail:${hashOf(messageId, 32)}`,
+        kind: 'message',
+        event: { postType: 'mail', type: list ? 'list' : 'direct' },
+        sessionKey,
+        replyTarget: target,
+        requestId: messageId,
+        chainId: sessionKey,
+        source: {
+            kind: 'mail',
+            instance: config.channel,
+            peer: list ? target : from,
+            scope: list ? 'group' : 'c2c',
+        },
+        author: { senderId: from, kind: isBot ? 'bot' : 'person', personId: null },
+        rawText: mail.text,
+        body: { text: mail.text, media: [], replyTo: cleanId(mail.inReplyTo) || null },
+        transport: {
+            messageId,
+            timestamp: mail.date ?? input.receivedAt,
+            mentioned: { self: false, others: false, all: false },
+            isReply: mail.inReplyTo !== undefined,
+            signature: null,
+        },
+        declared: { nickname: mail.from, avatar: '' },
+        adapter: {
+            subject: mail.subject,
+            messageId,
+            references,
+            ...(list ? { list: target } : {}),
+            ...(mail.attachments.length === 0 ? {} : { attachments: attachmentMeta(mail.attachments) }),
+        },
+        receivedAt: input.receivedAt,
+    };
+}
+/** The headers a reply carries so the thread stays one chain. */
+export function replyHeadersOf(mail) {
+    const subject = /^re:/i.test(mail.subject.trim()) ? mail.subject.trim() : `Re: ${mail.subject.trim()}`;
+    const messageId = cleanId(mail.messageId);
+    if (messageId === '')
+        return { subject };
+    const chain = [...mail.references.map((one) => cleanId(one)).filter((one) => one !== ''), messageId].join(' ');
+    return { subject, inReplyTo: messageId, references: chain };
+}
+/** A fresh message id on the configured domain. */
+export function newMessageId(from) {
+    const domain = from.includes('@') ? from.slice(from.indexOf('@') + 1) : 'localhost';
+    return `<${randomUUID()}@${domain}>`;
+}

package/dist/mime.d.ts

@@ -0,0 +1,54 @@
+export interface MailHeaders {
+    [key: string]: string[];
+}
+export interface MailPart {
+    headers: MailHeaders;
+    contentType: string;
+    body: Buffer;
+}
+export interface MailAttachment {
+    name: string;
+    type: string;
+    size: number;
+    handle: string;
+}
+export interface ParsedMail {
+    headers: MailHeaders;
+    from: string;
+    to: readonly string[];
+    subject: string;
+    messageId: string;
+    inReplyTo?: string;
+    references: readonly string[];
+    date?: number;
+    text: string;
+    attachments: readonly MailAttachment[];
+}
+export declare const MAX_ATTACHMENT_BYTES: number;
+/** Splits a raw message into unfolded headers and the body; lower-cases the names. */
+export declare function splitMessage(raw: string): {
+    headers: MailHeaders;
+    body: string;
+};
+export declare function header(headers: MailHeaders, name: string): string | undefined;
+/** Decodes RFC 2047 words such as `=?utf-8?B?...?=`. */
+export declare function decodeWords(value: string): string;
+/** Decodes a transfer encoding; an unknown one is read as-is. */
+export declare function decodeBody(body: string, encoding: string): Buffer;
+export declare function contentTypeOf(headers: MailHeaders): string;
+export declare function boundaryOf(headers: MailHeaders): string | undefined;
+export declare function dispositionOf(headers: MailHeaders): string;
+export declare function fileNameOf(headers: MailHeaders): string | undefined;
+/** Splits a multipart body into its parts, keeping each part's own headers. */
+export declare function splitParts(body: string, boundary: string): MailPart[];
+/** Reads an html body as plain text: no scripts, no images, no tags. */
+export declare function htmlToText(html: string): string;
+export declare function charsetOf(headers: MailHeaders): BufferEncoding;
+/** Picks the readable body: plain text wins over html, and inline images never count. */
+export declare function chooseBody(part: MailPart, depth?: number): string;
+/** Reads the headers a thread and a reply need, then the body and attachments. */
+export declare function parseMail(input: Buffer | string, maxAttachmentBytes?: number): ParsedMail;
+/** The address inside angle brackets, without them. */
+export declare function cleanId(value: string | undefined): string;
+/** The address part of `Name <user@host>`. */
+export declare function addressOf(value: string): string;

package/dist/mime.js

@@ -0,0 +1,269 @@
+import { createHash } from 'node:crypto';
+export const MAX_ATTACHMENT_BYTES = 10 * 1024 * 1024;
+/** Splits a raw message into unfolded headers and the body; lower-cases the names. */
+export function splitMessage(raw) {
+    const lines = raw.split(/\r?\n/);
+    const headers = {};
+    let index = 0;
+    let current;
+    for (; index < lines.length; index += 1) {
+        const line = lines[index] ?? '';
+        if (line === '') {
+            index += 1;
+            break;
+        }
+        if (/^[ \t]/.test(line) && current !== undefined) {
+            const list = headers[current];
+            if (list !== undefined && list.length > 0)
+                list[list.length - 1] = `${list[list.length - 1]} ${line.trim()}`;
+            continue;
+        }
+        const colon = line.indexOf(':');
+        if (colon <= 0)
+            continue;
+        const name = line.slice(0, colon).trim().toLowerCase();
+        const value = line.slice(colon + 1).trim();
+        current = name;
+        if (headers[name] === undefined)
+            headers[name] = [];
+        headers[name].push(value);
+    }
+    return { headers, body: lines.slice(index).join('\n') };
+}
+export function header(headers, name) {
+    return headers[name.toLowerCase()]?.[0];
+}
+/** Decodes RFC 2047 words such as `=?utf-8?B?...?=`. */
+export function decodeWords(value) {
+    return value.replace(/=\?([^?]+)\?([BbQq])\?([^?]*)\?=/g, (_whole, charset, encoding, payload) => {
+        try {
+            const bytes = encoding.toUpperCase() === 'B'
+                ? Buffer.from(payload, 'base64')
+                : Buffer.from(payload
+                    .replace(/_/g, ' ')
+                    .replace(/=([0-9A-Fa-f]{2})/g, (_match, hex) => String.fromCharCode(Number.parseInt(hex, 16))), 'binary');
+            return bytes.toString(charsetName(charset));
+        }
+        catch {
+            return payload;
+        }
+    });
+}
+function charsetName(charset) {
+    const name = charset.toLowerCase();
+    if (name.includes('utf-8'))
+        return 'utf8';
+    if (name.includes('iso-8859-1') || name.includes('latin1'))
+        return 'latin1';
+    if (name.includes('ascii'))
+        return 'ascii';
+    return 'utf8';
+}
+/** Decodes a transfer encoding; an unknown one is read as-is. */
+export function decodeBody(body, encoding) {
+    const name = encoding.trim().toLowerCase();
+    if (name === 'base64')
+        return Buffer.from(body.replace(/\s+/g, ''), 'base64');
+    if (name === 'quoted-printable') {
+        const cleaned = body.replace(/=\r?\n/g, '');
+        const bytes = [];
+        for (let index = 0; index < cleaned.length; index += 1) {
+            const char = cleaned[index];
+            if (char === '=') {
+                const hex = cleaned.slice(index + 1, index + 3);
+                if (/^[0-9A-Fa-f]{2}$/.test(hex)) {
+                    bytes.push(Number.parseInt(hex, 16));
+                    index += 2;
+                    continue;
+                }
+            }
+            bytes.push(char.charCodeAt(0));
+        }
+        return Buffer.from(bytes);
+    }
+    return Buffer.from(body, 'binary');
+}
+export function contentTypeOf(headers) {
+    return (header(headers, 'content-type') ?? 'text/plain').trim();
+}
+export function boundaryOf(headers) {
+    const matched = /boundary="?([^";]+)"?/i.exec(contentTypeOf(headers));
+    return matched?.[1];
+}
+export function dispositionOf(headers) {
+    return (header(headers, 'content-disposition') ?? '').trim().toLowerCase();
+}
+export function fileNameOf(headers) {
+    const disposition = dispositionOf(headers);
+    const fromDisposition = /filename\*?=(?:utf-8'')?"?([^";]+)"?/i.exec(disposition);
+    if (fromDisposition !== null)
+        return decodeWords(fromDisposition[1]);
+    const fromType = /name="?([^";]+)"?/i.exec(contentTypeOf(headers));
+    return fromType === null ? undefined : decodeWords(fromType[1]);
+}
+/** Splits a multipart body into its parts, keeping each part's own headers. */
+export function splitParts(body, boundary) {
+    const marker = `--${boundary}`;
+    const parts = [];
+    const segments = body.split(marker);
+    for (const segment of segments.slice(1)) {
+        if (segment.startsWith('--'))
+            break;
+        const trimmed = segment.replace(/^\r?\n/, '');
+        const { headers, body: content } = splitMessage(trimmed);
+        parts.push({
+            headers,
+            contentType: contentTypeOf(headers),
+            body: decodeBody(content, header(headers, 'content-transfer-encoding') ?? '7bit'),
+        });
+    }
+    return parts;
+}
+const ENTITIES = {
+    amp: '&',
+    lt: '<',
+    gt: '>',
+    quot: '"',
+    apos: "'",
+    nbsp: ' ',
+    ndash: '–',
+    mdash: '—',
+    hellip: '…',
+};
+/** Reads an html body as plain text: no scripts, no images, no tags. */
+export function htmlToText(html) {
+    return html
+        .replace(/<!--[\s\S]*?-->/g, ' ')
+        .replace(/<(script|style|head)\b[\s\S]*?<\/\1>/gi, ' ')
+        .replace(/<img\b[^>]*>/gi, ' ')
+        .replace(/<br\s*\/?>/gi, '\n')
+        .replace(/<\/(p|div|li|tr|h[1-6]|blockquote|pre)>/gi, '\n')
+        .replace(/<[^>]+>/g, ' ')
+        .replace(/&#(\d+);/g, (_whole, code) => String.fromCodePoint(Number(code)))
+        .replace(/&#x([0-9a-f]+);/gi, (_whole, code) => String.fromCodePoint(Number.parseInt(code, 16)))
+        .replace(/&([a-z]+);/gi, (whole, name) => ENTITIES[name.toLowerCase()] ?? whole)
+        .replace(/[ \t]+/g, ' ')
+        .replace(/\s*\n\s*/g, '\n')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+}
+export function charsetOf(headers) {
+    const matched = /charset="?([^";]+)"?/i.exec(contentTypeOf(headers));
+    return matched === null ? 'utf8' : charsetName(matched[1]);
+}
+function textOf(part) {
+    const type = part.contentType.toLowerCase();
+    const body = part.body.toString(charsetOf(part.headers));
+    if (type.startsWith('text/html'))
+        return htmlToText(body);
+    return body;
+}
+function isText(part) {
+    const type = part.contentType.toLowerCase();
+    return type.startsWith('text/plain') || type.startsWith('text/html');
+}
+function isAttachment(part) {
+    return dispositionOf(part.headers).startsWith('attachment') || fileNameOf(part.headers) !== undefined;
+}
+/** Picks the readable body: plain text wins over html, and inline images never count. */
+export function chooseBody(part, depth = 0) {
+    if (depth > 8)
+        return '';
+    const type = part.contentType.toLowerCase();
+    if (type.startsWith('multipart/')) {
+        const boundary = boundaryOf(part.headers);
+        if (boundary === undefined)
+            return '';
+        const children = splitParts(part.body.toString('binary'), boundary);
+        if (type.startsWith('multipart/alternative')) {
+            const plain = children.find((one) => one.contentType.toLowerCase().startsWith('text/plain'));
+            if (plain !== undefined)
+                return textOf(plain);
+            const html = children.find((one) => one.contentType.toLowerCase().startsWith('text/html'));
+            return html === undefined ? '' : textOf(html);
+        }
+        if (type.startsWith('multipart/related')) {
+            const first = children.find((one) => !isAttachment(one));
+            return first === undefined ? '' : chooseBody(first, depth + 1);
+        }
+        const text = children.find((one) => isText(one) && !isAttachment(one));
+        if (text !== undefined)
+            return textOf(text);
+        for (const child of children) {
+            if (isAttachment(child))
+                continue;
+            const nested = chooseBody(child, depth + 1);
+            if (nested !== '')
+                return nested;
+        }
+        return '';
+    }
+    return isText(part) ? textOf(part) : '';
+}
+function attachmentsOf(part, depth = 0) {
+    if (depth > 8)
+        return [];
+    const type = part.contentType.toLowerCase();
+    if (type.startsWith('multipart/')) {
+        const boundary = boundaryOf(part.headers);
+        if (boundary === undefined)
+            return [];
+        return splitParts(part.body.toString('binary'), boundary).flatMap((child) => attachmentsOf(child, depth + 1));
+    }
+    if (!isAttachment(part))
+        return [];
+    const name = fileNameOf(part.headers) ?? 'attachment';
+    const size = part.body.length;
+    return [
+        {
+            name,
+            type: type.split(';')[0] ?? 'application/octet-stream',
+            size,
+            handle: `mail:${createHash('sha256').update(part.body).digest('hex').slice(0, 16)}`,
+        },
+    ];
+}
+/** Reads the headers a thread and a reply need, then the body and attachments. */
+export function parseMail(input, maxAttachmentBytes = MAX_ATTACHMENT_BYTES) {
+    const raw = Buffer.isBuffer(input) ? input.toString('latin1') : input;
+    const root = splitMessage(raw);
+    const top = { headers: root.headers, contentType: contentTypeOf(root.headers), body: Buffer.from(root.body, 'binary') };
+    const text = chooseBody(top).trimEnd();
+    const attachments = attachmentsOf(top).filter((one) => one.size <= maxAttachmentBytes);
+    const references = (header(root.headers, 'references') ?? '')
+        .split(/\s+/)
+        .map((one) => one.trim())
+        .filter((one) => one.length > 0);
+    const messageId = cleanId(header(root.headers, 'message-id'));
+    const inReplyTo = cleanId(header(root.headers, 'in-reply-to'));
+    const date = Date.parse(header(root.headers, 'date') ?? '');
+    const from = decodeWords(header(root.headers, 'from') ?? '');
+    const to = (header(root.headers, 'to') ?? '')
+        .split(',')
+        .map((one) => decodeWords(one).trim())
+        .filter((one) => one.length > 0);
+    return {
+        headers: root.headers,
+        from,
+        to,
+        subject: decodeWords(header(root.headers, 'subject') ?? ''),
+        messageId,
+        ...(inReplyTo === undefined ? {} : { inReplyTo }),
+        references,
+        ...(Number.isFinite(date) ? { date } : {}),
+        text,
+        attachments,
+    };
+}
+/** The address inside angle brackets, without them. */
+export function cleanId(value) {
+    if (value === undefined)
+        return '';
+    const matched = /<([^>]+)>/.exec(value);
+    return matched === null ? value.trim() : matched[1].trim();
+}
+/** The address part of `Name <user@host>`. */
+export function addressOf(value) {
+    const matched = /<([^>]+)>/.exec(value);
+    return matched === null ? value.trim() : matched[1].trim();
+}

package/dist/transport.d.ts

@@ -0,0 +1,55 @@
+export interface ImapSettings {
+    host: string;
+    port: number;
+    secure: boolean;
+    user: string;
+    password: string;
+    mailbox: string;
+}
+export interface SmtpSettings {
+    host: string;
+    port: number;
+    secure: boolean | 'starttls';
+    user?: string | undefined;
+    password?: string | undefined;
+}
+export interface Cursor {
+    uidValidity: number;
+    uid: number;
+}
+export interface FetchedMail {
+    uid: number;
+    raw: Buffer;
+}
+/** The wire layers behind one interface, so a test can stand in for both protocols. */
+export interface MailTransport {
+    fetch(mailbox: string, cursor: Cursor | undefined): Promise<{
+        uidValidity: number;
+        maxUid: number;
+        messages: FetchedMail[];
+    }>;
+    markSeen(mailbox: string, uids: readonly number[]): Promise<void>;
+    append(mailbox: string, raw: Buffer): Promise<void>;
+    send(envelope: {
+        from: string;
+        to: readonly string[];
+    }, raw: Buffer): Promise<void>;
+    close(): Promise<void>;
+}
+/** Reads with imapflow and writes with nodemailer; the MIME layer stays core's own. */
+export declare class ImapSmtpTransport implements MailTransport {
+    #private;
+    constructor(imap: ImapSettings, smtp: SmtpSettings);
+    fetch(mailbox: string, cursor: Cursor | undefined): Promise<{
+        uidValidity: number;
+        maxUid: number;
+        messages: FetchedMail[];
+    }>;
+    markSeen(mailbox: string, uids: readonly number[]): Promise<void>;
+    append(mailbox: string, raw: Buffer): Promise<void>;
+    send(envelope: {
+        from: string;
+        to: readonly string[];
+    }, raw: Buffer): Promise<void>;
+    close(): Promise<void>;
+}

package/dist/transport.js

@@ -0,0 +1,67 @@
+import { ImapFlow } from 'imapflow';
+import nodemailer from 'nodemailer';
+/** Reads with imapflow and writes with nodemailer; the MIME layer stays core's own. */
+export class ImapSmtpTransport {
+    #imap;
+    #smtp;
+    constructor(imap, smtp) {
+        this.#imap = new ImapFlow({
+            host: imap.host,
+            port: imap.port,
+            secure: imap.secure,
+            auth: { user: imap.user, pass: imap.password },
+            logger: false,
+        });
+        this.#smtp = nodemailer.createTransport({
+            host: smtp.host,
+            port: smtp.port,
+            secure: smtp.secure === true,
+            ...(smtp.secure === 'starttls' ? { requireTLS: true } : {}),
+            ...(smtp.user === undefined ? {} : { auth: { user: smtp.user, pass: smtp.password } }),
+        });
+    }
+    async fetch(mailbox, cursor) {
+        const lock = await this.#imap.getMailboxLock(mailbox);
+        try {
+            const opened = this.#imap.mailbox;
+            const uidValidity = Number(opened === false ? 0 : opened.uidValidity);
+            const maxUid = opened === false ? 0 : Math.max(0, Number(opened.uidNext) - 1);
+            if (cursor === undefined)
+                return { uidValidity, maxUid, messages: [] };
+            const start = cursor.uidValidity === uidValidity && cursor.uid > 0 ? cursor.uid + 1 : maxUid + 1;
+            const messages = [];
+            for await (const message of this.#imap.fetch(`${start}:*`, { uid: true, source: true })) {
+                const source = message.source;
+                if (source === undefined)
+                    continue;
+                messages.push({ uid: Number(message.uid), raw: Buffer.from(source) });
+            }
+            messages.sort((left, right) => left.uid - right.uid);
+            return { uidValidity, maxUid, messages };
+        }
+        finally {
+            lock.release();
+        }
+    }
+    async markSeen(mailbox, uids) {
+        if (uids.length === 0)
+            return;
+        const lock = await this.#imap.getMailboxLock(mailbox);
+        try {
+            await this.#imap.messageFlagsAdd([...uids], ['\\Seen'], { uid: true });
+        }
+        finally {
+            lock.release();
+        }
+    }
+    async append(mailbox, raw) {
+        await this.#imap.append(mailbox, raw, ['\\Seen']);
+    }
+    async send(envelope, raw) {
+        await this.#smtp.sendMail({ envelope: { from: envelope.from, to: [...envelope.to] }, raw });
+    }
+    async close() {
+        this.#smtp.close();
+        await this.#imap.logout().catch(() => undefined);
+    }
+}

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@dsbot-channel/mail",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.7.1",
+  "description": "Email transport for dsbot-channel.",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./*.js": {
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    },
+    "./package.json": "./package.json",
+    "./cordis.patch.yml": "./cordis.patch.yml"
+  },
+  "files": [
+    "dist",
+    "assets",
+    "cordis.patch.yml",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "dependencies": {
+    "imapflow": "2.10.2",
+    "nodemailer": "10.3.1",
+    "@dsbot-channel/core": "^0.7.1"
+  },
+  "devDependencies": {
+    "@types/node": "~22.20.5",
+    "typescript": "~5.9.3"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "scripts": {
+    "build": "pnpm clean && tsc -p tsconfig.build.json",
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "typecheck": "tsc -p tsconfig.build.json --noEmit",
+    "verify:dist": "node ../../scripts/verify-dist.mjs packages/mail"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.