@cogitator-ai/channels 0.16.0 → 0.18.0

package/dist/channels/email/channel.d.ts

@@ -0,0 +1,256 @@
+import { type RequestListener } from 'node:http';
+import type { Attachment, Channel, ChannelMessage, SendOptions } from '@cogitator-ai/types';
+import { type EmailImapConfig } from './imap.js';
+import { type InboundEmail } from './mime.js';
+import { type EmailWebhookRequest, type EmailWebhookResponse } from './providers.js';
+/** The header the channel puts on every mail it sends, and skips mail that carries it. */
+export declare const EMAIL_LOOP_HEADER = "X-Cogitator";
+/** The largest webhook body the channel's own server takes by default, in bytes. */
+export declare const EMAIL_DEFAULT_MAX_BODY: number;
+/** The largest attachment handed to the agent by default, in bytes. */
+export declare const EMAIL_DEFAULT_MAX_ATTACHMENT: number;
+/** How old a Mailgun signature may be by default, in seconds. */
+export declare const MAILGUN_DEFAULT_MAX_AGE = 300;
+/** Credentials for HTTP basic authentication of a webhook. */
+export interface EmailBasicAuth {
+    username: string;
+    password: string;
+}
+/** Mailgun signs each request of a route with the webhook signing key. */
+export interface MailgunWebhookConfig {
+    provider: 'mailgun';
+    /** The HTTP webhook signing key of the Mailgun account (Settings, Webhooks) */
+    signingKey: string;
+    /** How old a signature may be, in seconds (default 300). Older requests are refused as replays */
+    maxAge?: number;
+}
+/**
+ * Postmark and SendGrid do not sign inbound mail, so the webhook URL carries a secret: basic
+ * authentication (`https://user:password@host/path`) or a `token` query parameter (also taken
+ * from an `X-Webhook-Token` header). At least one is required.
+ */
+export interface SecretWebhookConfig {
+    provider: 'postmark' | 'sendgrid';
+    basicAuth?: EmailBasicAuth;
+    token?: string;
+}
+export type EmailWebhookConfig = (MailgunWebhookConfig | SecretWebhookConfig) & {
+    /**
+     * Run an HTTP server of the channel's own on this port. Without it, mount `handleWebhook` or
+     * `webhookListener()` in a server of yours.
+     */
+    port?: number;
+    /** The path of the channel's own server (default `/email/webhook`) */
+    path?: string;
+    host?: string;
+    /** The largest body taken, in bytes (default 10 MB), larger ones get `413` */
+    maxBody?: number;
+};
+/** A mail as the channel hands it to the transport, in the shape nodemailer takes. */
+export interface OutgoingEmail {
+    from: string | {
+        name: string;
+        address: string;
+    };
+    to: string;
+    subject: string;
+    text: string;
+    html?: string;
+    messageId: string;
+    inReplyTo?: string;
+    references?: string[];
+    headers: Record<string, string>;
+    attachments?: {
+        filename?: string;
+        content?: Buffer;
+        href?: string;
+        contentType?: string;
+    }[];
+}
+/** Anything that sends mail: a nodemailer transporter (SMTP, SES, ...) or one of your own. */
+export interface EmailTransport {
+    sendMail(mail: OutgoingEmail): Promise<unknown>;
+    close?(): void;
+}
+/** An SMTP server the channel sends through with nodemailer. */
+export interface EmailSmtpServer {
+    host: string;
+    /** Default 587, or 465 when `secure` */
+    port?: number;
+    /** TLS from the start, as on port 465 (default: true on port 465). Otherwise STARTTLS */
+    secure?: boolean;
+    auth?: {
+        user: string;
+        pass: string;
+    };
+    /** Further nodemailer SMTP options */
+    options?: Record<string, unknown>;
+}
+export type EmailSmtpConfig = EmailSmtpServer | {
+    transport: EmailTransport;
+};
+/**
+ * How mail is checked against the sender authentication results the receiving side reports
+ * (DKIM, SPF, DMARC): `when-reported` (default) drops mail whose results fail for the `From`
+ * domain and takes mail without results, `required` also drops mail without results, `off`
+ * does not look.
+ */
+export type EmailSenderAuthPolicy = 'required' | 'when-reported' | 'off';
+export interface EmailChannelConfig {
+    /** The bot's address: mail is sent from it, and mail from it is never answered */
+    address: string;
+    /** The display name of the mail it sends */
+    name?: string;
+    /** Other addresses of the bot, also never answered */
+    aliases?: string[];
+    /** How mail is sent */
+    smtp: EmailSmtpConfig;
+    /** Read mail from a mailbox over IMAP */
+    imap?: EmailImapConfig;
+    /** Take mail from a provider's inbound webhook: Mailgun, Postmark or SendGrid */
+    webhook?: EmailWebhookConfig;
+    /**
+     * Who the bot answers: addresses (`ann@example.com`), domains (`example.com`), subdomain
+     * wildcards (`*.example.com`) or `*` for everyone. Default: nobody, which `start()` warns
+     * about, since anyone can send mail and the `From` address can be forged.
+     */
+    allowFrom?: string[];
+    /**
+     * Addresses the gateway gives owner rights, also answered whatever `allowFrom` says. A `From`
+     * can be forged, so their mail reaches the agent only when the sender authentication passes
+     * for their domain, unless `senderAuth` is `off`.
+     */
+    owners?: string[];
+    /** See {@link EmailSenderAuthPolicy}. Default `when-reported` */
+    senderAuth?: EmailSenderAuthPolicy;
+    /**
+     * The authserv-ids (the first word of `Authentication-Results`, such as `mx.google.com`) of
+     * the servers that receive the mail, whose results count over IMAP and Postmark. A sender can
+     * add any header, so without them IMAP mail has no sender authentication at all.
+     */
+    trustedAuthservIds?: string[];
+    /** Start the text of a conversation's first mail with its subject (default true) */
+    includeSubject?: boolean;
+    /** The subject of mail that starts a conversation, such as a reminder (default `Message from <name>`) */
+    subject?: string;
+    /** The largest attachment handed to the agent, in bytes (default 10 MB), larger ones are skipped */
+    maxAttachmentBytes?: number;
+}
+/** `subject` as a reply's subject: with one `Re: `, whatever prefix it had. */
+export declare function replySubject(subject: string): string;
+/** Whether the mail is an automatic one: an auto-reply, a bounce, a list or bulk mailing. */
+export declare function isAutomatedEmail(email: InboundEmail): boolean;
+/**
+ * An email channel: an agent answers mail, in the thread of each mail. Mail comes from a mailbox
+ * over IMAP (`imapflow` and `postal-mime`), or from the inbound webhook of Mailgun, Postmark or
+ * SendGrid, and answers go out over SMTP (`nodemailer`) or any transport given, with
+ * `In-Reply-To` and `References` set, so mail clients keep them in the thread.
+ *
+ * A sender is a conversation partner: `channelId` and `userId` are the sender's address in lower
+ * case, and `topicId` is the thread's first `Message-ID`, so each email thread is a conversation
+ * of its own. Answers are Markdown, sent as HTML with a plain text alternative, and cannot be
+ * edited. Mail from the bot itself, mail that carries the `X-Cogitator` header the channel puts
+ * on what it sends, auto-replies, bounces and bulk mail are never answered.
+ */
+export declare class EmailChannel implements Channel {
+    readonly type = "email";
+    readonly editable = false;
+    readonly nativeMarkdown = true;
+    readonly maxMessageChars: number;
+    private readonly config;
+    private readonly address;
+    private readonly ownAddresses;
+    private readonly owners;
+    private handler;
+    /** Mail handed to the gateway whose handler has not resolved yet, by `Message-ID` */
+    private readonly inFlight;
+    /** Mail of `inFlight` the gateway handed back while it was being taken */
+    private readonly refused;
+    private readonly handled;
+    /** Mailgun signatures seen, with their timestamps, against replays */
+    private readonly signatures;
+    /** The IMAP UID of each mail taken from the mailbox, by `Message-ID`, to mark it unread again */
+    private readonly uids;
+    private readonly threads;
+    /** The latest mail of each thread, by `address|root` */
+    private readonly latest;
+    private transport?;
+    private inbox?;
+    private server?;
+    private running;
+    private stopped;
+    constructor(config: EmailChannelConfig);
+    onMessage(handler: (msg: ChannelMessage) => Promise<void>): void;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /** Looks for unread mail over IMAP now, besides IDLE and the poll timer. */
+    poll(): Promise<void>;
+    /**
+     * Takes back a mail the gateway does not answer because it stops. One it refuses while it is
+     * being handed over stays unread in the mailbox, and its webhook request is answered `503`, so
+     * the provider sends it again. One it dropped after taking it is marked unread again, so the
+     * next start reads it once more, or, when a webhook brought it, only logged.
+     */
+    redeliver(msg: ChannelMessage): Promise<void>;
+    /**
+     * Answers a provider's inbound webhook request: checks its signature or secret, reads the
+     * mail, answers at once and hands the mail to the agent after. Mount it in any HTTP server
+     * with the raw body unparsed. It works before `start()` too and answers `503` once stopped.
+     */
+    handleWebhook(request: EmailWebhookRequest): Promise<EmailWebhookResponse>;
+    /**
+     * A Node request listener that answers webhook requests on any path it is mounted at. Bodies
+     * over `webhook.maxBody` (10 MB by default) are refused with `413`.
+     */
+    webhookListener(): RequestListener;
+    /**
+     * Sends `text` to the address `channelId`. With a `replyTo` of a mail the channel saw, or the
+     * `topicId` of a thread, it answers in that thread (`Re:` subject, `In-Reply-To`,
+     * `References`), and otherwise it starts a new one. Resolves with the new mail's `Message-ID`.
+     */
+    sendText(channelId: string, text: string, options?: SendOptions): Promise<string>;
+    editText(): Promise<void>;
+    /**
+     * Sends a file as an attachment, its caption as the text, in the thread as `sendText` does.
+     * A file needs a `buffer` or an `http(s)` url, which nodemailer downloads.
+     */
+    sendFile(channelId: string, file: Attachment, options?: SendOptions): Promise<string>;
+    sendTyping(): Promise<void>;
+    private parseOptions;
+    private authorized;
+    /**
+     * Checks a Mailgun request's signature, age and token, and reads its mail. The signature is
+     * checked before the mail is read: a form is only split into its fields first, where the
+     * signature is.
+     */
+    private mailgunEmail;
+    /**
+     * Remembers a signature for as long as its timestamp is within the replay window: older ones
+     * are refused as stale anyway. Past `MAX_SIGNATURES` the oldest are forgotten.
+     */
+    private rememberSignature;
+    /** Whether the mail may reach the agent: by its sender, its kind and its authentication. */
+    private admits;
+    /**
+     * The text the agent reads: the new text of the mail, starting with the subject on a thread's
+     * first mail. A command (`/status`) stays first, so the gateway still sees it, and a mail
+     * with only a command as its subject is that command.
+     */
+    private textOf;
+    /**
+     * Hands an inbound mail to the agent when it is one to answer. Resolves `refused` when the
+     * gateway did not take it, so it may come again.
+     */
+    private accept;
+    private fallbackId;
+    private remember;
+    /** The thread a mail to `to` goes in: the mail it answers, or the latest of its topic. */
+    private threadOf;
+    private bodies;
+    private send;
+    private transportOf;
+    private listen;
+}
+/** An email channel that answers mail in its thread. */
+export declare function emailChannel(config: EmailChannelConfig): EmailChannel;
+//# sourceMappingURL=channel.d.ts.map

package/dist/channels/email/channel.d.ts.map

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