@maestro-js/mail 1.0.0-alpha.0

package/dist/index.d.ts

@@ -0,0 +1,478 @@
+import { Iso } from 'iso-fns2';
+import { Queue } from '@maestro-js/queue';
+import { Log } from '@maestro-js/log';
+
+type MailAddress = string | {
+    name?: string;
+    email: string;
+};
+type MailContent = {
+    text: string;
+} | {
+    html: string;
+};
+interface MailAttachment {
+    /** Base64 encoded string */
+    content: string;
+    filename: string;
+    type?: string;
+    disposition?: string;
+    contentId?: string;
+}
+interface MailHeaders {
+    listUnsubscribePost?: string;
+    listUnsubscribe?: string;
+    replyTo?: MailAddress;
+}
+interface MailEnvelope {
+    to: MailAddress | MailAddress[];
+    from?: MailAddress;
+    cc?: MailAddress | MailAddress[];
+    bcc?: MailAddress | MailAddress[];
+    attachments?: MailAttachment[];
+    subject: string | null;
+    content: MailContent;
+    headers?: MailHeaders;
+    category?: string | null;
+    extras?: Record<string, string | null>;
+}
+type MailEventType = 'delivery' | 'softBounce' | 'bounce' | 'suspension' | 'unsubscribe' | 'open' | 'spamComplaint' | 'click' | 'reject';
+interface MailEvent {
+    eventId: string;
+    /** a combination of email, event, and messageId should be unique  */
+    event: MailEventType;
+    email: string;
+    messageId: string;
+    timestamp: number;
+    category: string | null;
+    extras: Record<string, string>;
+    driverName: string;
+}
+interface MailDriver {
+    send(envelope: MailEnvelope): Promise<{
+        success: boolean;
+        driverName: string;
+        messages: {
+            id: string;
+            email: string;
+        }[];
+    }>;
+}
+type MailLogMessage = ({
+    type: 'event';
+} & MailEvent) | {
+    type: 'envelope';
+    driverName: string;
+    messageId: string;
+    to: {
+        name?: string;
+        email: string;
+    };
+    from: {
+        name?: string;
+        email: string;
+    };
+    attachments: MailAttachment[];
+    subject: string | null;
+    content: MailContent;
+    headers: MailHeaders;
+    category: string | null;
+    extras: Record<string, string>;
+    mailable: string | null;
+};
+
+type EmailData = string | {
+    name?: string;
+    email: string;
+};
+type Response$1 = {
+    statusCode: number;
+    headers: {
+        'x-message-id': string;
+    };
+};
+interface SendGrid {
+    send(data: {
+        to?: EmailData | EmailData[];
+        cc?: EmailData | EmailData[];
+        bcc?: EmailData | EmailData[];
+        from: EmailData;
+        subject?: string;
+        attachments?: {
+            content: string;
+            filename: string;
+            type?: string;
+            disposition?: string;
+            contentId?: string;
+        }[];
+        category?: string;
+        customArgs?: {
+            [key: string]: any;
+        };
+    } & ({
+        text: string;
+    } | {
+        html: string;
+    }), isMultiple?: boolean, cb?: (err: unknown, result: [Response$1, {}]) => void): Promise<[Response$1, {}]>;
+}
+interface SendGridWebhookEvent {
+    timestamp: number;
+    category?: string | string[];
+    sg_event_id: string;
+    sg_message_id: string;
+    event: 'processed' | 'dropped' | 'delivered' | 'bounce' | 'open' | 'click' | 'spamreport' | 'unsubscribe' | 'group_unsubscribe' | 'group_resubscribe';
+    __extraKeys__?: string;
+    email: string;
+}
+interface SendGridMailDriver extends MailDriver {
+    toMailEvent(mtEvent: SendGridWebhookEvent): MailEvent | null;
+}
+declare function sendGridMailDriver(sendGrid: SendGrid): SendGridMailDriver;
+
+type Address = {
+    name?: string;
+    email: string;
+};
+type Response = {
+    success: true;
+    message_ids: string[];
+};
+interface MailTrap {
+    send(data: {
+        to: Address[];
+        cc?: Address[];
+        bcc?: Address[];
+        from: Address;
+        subject: string;
+        text?: string;
+        html?: string;
+        attachments?: {
+            content: string;
+            filename: string;
+            type?: string;
+            disposition?: string;
+            contentId?: string;
+        }[];
+        category?: string;
+        custom_variables?: Record<string, string | number | boolean>;
+    } & ({
+        text?: string;
+    } | {
+        html?: string;
+    })): Promise<Response>;
+}
+interface MailTrapWebhookEvent {
+    email: string;
+    timestamp: number;
+    category?: string;
+    event_id: string;
+    message_id: string;
+    custom_variables?: Record<string, string>;
+    event: 'delivery' | 'soft_bounce' | 'bounce' | 'suspension' | 'unsubscribe' | 'open' | 'spam_complaint' | 'click' | 'reject';
+}
+interface MailTrapMailDriver extends MailDriver {
+    toMailEvent(mtEvent: MailTrapWebhookEvent): MailEvent;
+}
+declare function mailTrapMailDriver(mailTrap: MailTrap): MailTrapMailDriver;
+
+interface SesWebhookEvent {
+    eventId: string;
+    eventType: 'Bounce' | 'Complaint' | 'Delivery' | 'Reject' | 'Open' | 'Click' | 'Subscription';
+    mail: {
+        messageId: string;
+        timestamp: string;
+        destination: string[];
+        tags?: Record<string, string[]>;
+    };
+    delivery?: {
+        timestamp: string;
+    };
+    open?: {
+        timestamp: string;
+    };
+    click?: {
+        timestamp: string;
+    };
+    bounce?: {
+        bouncedRecipients: {
+            emailAddress: string;
+        }[];
+        timestamp: string;
+    };
+    complaint?: {
+        complainedRecipients: {
+            emailAddress: string;
+        }[];
+        timestamp: string;
+    };
+}
+interface SesClientAdapter {
+    send(command: {
+        input: {
+            RawMessage: {
+                Data: Buffer;
+            };
+            Destinations?: string[];
+            ConfigurationSetName?: string;
+        };
+    }): Promise<{
+        MessageId?: string;
+    }>;
+}
+interface SesMailDriver extends MailDriver {
+    toMailEvent(event: SesWebhookEvent): MailEvent | null;
+}
+declare function sesMailDriver(ses: SesClientAdapter, configurationSetName: string): SesMailDriver;
+
+interface IcsAttachmentOptions {
+    filename?: string;
+    start: Iso.Instant | Iso.ZonedDateTime | Iso.DateTime;
+    end: Iso.Instant | Iso.ZonedDateTime | Iso.DateTime | Iso.Duration;
+    title?: string;
+    description?: string;
+    location?: string;
+    geo?: {
+        lat: number;
+        lon: number;
+    };
+    url?: string;
+    status?: 'TENTATIVE' | 'CONFIRMED' | 'CANCELLED';
+    busyStatus?: 'FREE' | 'BUSY' | 'TENTATIVE' | 'OOF';
+    organizer?: {
+        name?: string;
+        email?: string;
+        dir?: string;
+    };
+    attendees?: {
+        name?: string;
+        email?: string;
+        dir?: string;
+        rsvp?: boolean;
+        partstat?: 'NEEDS-ACTION' | 'ACCEPTED' | 'DECLINED' | 'TENTATIVE' | 'DELEGATED' | 'COMPLETED' | 'IN-PROCESS';
+        role?: 'CHAIR' | 'REQ-PARTICIPANT' | 'OPT-PARTICIPANT' | 'NON-PARTICIPANT';
+    }[];
+    categories?: string[];
+    productId?: string;
+    uid?: string;
+    method?: string;
+    recurrenceRule?: string;
+    sequence?: number;
+    calName?: string;
+    classification?: 'PUBLIC' | 'PRIVATE' | 'CONFIDENTIAL' | string;
+    created?: Iso.Instant;
+    lastModified?: Iso.Instant;
+    htmlContent?: string;
+    alarms?: {
+        action?: 'audio' | 'display' | 'email' | 'procedure';
+        description?: string;
+        summary?: string;
+        duration?: Iso.Duration;
+        trigger?: Iso.Duration;
+        repeat?: number;
+        attachType?: string;
+        attach?: string;
+    }[];
+}
+declare function icsAttachment(options: IcsAttachmentOptions): MailAttachment;
+
+declare function stubMailDriver({ logger }?: {
+    logger?: Log.LogFunctions<[MailEnvelope]>;
+}): MailDriver;
+
+declare const EMPTY_ENVELOPE: unique symbol;
+declare function create(config: Mail.Provider.MailServiceConfig): Mail.MailService;
+/**
+ * A mailable encapsulates generating content for a particular type of email.
+ * Mailables can input "args" which effect the generated content.
+ * Mailables are first "rendered" by passing in input args. Then the mailable can
+ * be send, queued, or sent later.
+ */
+declare function mailable<Args extends Record<string, any>>(name: string, fn: Mail.MailableRenderFunction<Args>): {
+    /**
+     * Prepares the mailable with the renderArgs so that the mailable
+     * can be sent.
+     */
+    render(renderArgs: Args): {
+        content: () => Promise<MailContent>;
+        send: () => Promise<void>;
+        queue: () => Promise<void>;
+        later: (scheduledDate: Iso.Instant) => Promise<void>;
+        provider: (key: Mail.Provider.Key) => {
+            content: () => Promise<MailContent>;
+            send: () => Promise<void>;
+            queue: () => Promise<void>;
+            later: (scheduledDate: Iso.Instant) => Promise<void>;
+        };
+    };
+};
+declare function provider(key: Mail.Provider.Key): {
+    send: (envelope: Mail.Envelope) => Promise<{
+        messages: {
+            id: string;
+            email: string;
+        }[];
+        success: boolean;
+    }>;
+    later: (envelope: Mail.Envelope, scheduledDate: Iso.Instant) => void;
+    queue: (envelope: Mail.Envelope) => void;
+};
+/**
+ * Driver-based email sending with queued delivery, scheduled sending, and reusable mailable templates.
+ *
+ * Each mail service wraps a driver (SendGrid, SES, MailTrap, Stub) behind a unified `send()` call.
+ * Queue integration lets you offload delivery with `queue()` or schedule it with `later()`.
+ * Mailables encapsulate data fetching and envelope generation so the same template can be sent
+ * from anywhere — and when queued, data is fetched at send time, not enqueue time.
+ *
+ * @example
+ * ```ts
+ * // Send an order confirmation immediately
+ * await Mail.send({
+ *   to: 'alice@example.com',
+ *   subject: 'Order #1042 Confirmed',
+ *   content: { html: '<h1>Thank you for your order!</h1>' }
+ * })
+ *
+ * // Queue a password reset for async delivery
+ * Mail.queue({ to: 'bob@example.com', subject: 'Reset Password', content: { html: '...' } })
+ *
+ * // Register and use a mailable template
+ * const Welcome = Mail.mailable('Welcome', async (args: { userId: string }) => {
+ *   const user = await db.query('SELECT * FROM users WHERE id = ?', [args.userId])
+ *   return { to: user.email, subject: 'Welcome!', content: { html: `<h1>Hi ${user.name}!</h1>` } }
+ * })
+ * await Welcome.render({ userId: '456' }).queue()
+ * ```
+ */
+declare namespace Mail {
+    /** Email recipient or sender — either a plain email string or an object with optional display name */
+    type Address = MailAddress;
+    /** Email body — either `{ text: string }` for plain text or `{ html: string }` for HTML */
+    type Content = MailContent;
+    /** File attachment with base64-encoded content, filename, optional MIME type and disposition */
+    type Attachment = MailAttachment;
+    /** Email headers: `listUnsubscribe`, `listUnsubscribePost`, and `replyTo` */
+    type Headers = MailHeaders;
+    /** Complete email message: recipients, subject, content, optional attachments, headers, category, and extras */
+    type Envelope = MailEnvelope;
+    /** Union of normalized event types: `'delivery'`, `'bounce'`, `'open'`, `'click'`, `'unsubscribe'`, etc. */
+    type EventType = MailEventType;
+    /** Normalized webhook event with eventId, event type, email, messageId, timestamp, and extras */
+    type Event = MailEvent;
+    /** Driver interface — implements `send(envelope)` returning `{ success, driverName, messages }` */
+    type Driver = MailDriver;
+    /** Render function for a mailable — takes args and returns an envelope or `EMPTY_ENVELOPE` to skip */
+    type MailableRenderFunction<Args extends Record<string, any>> = (args: Args) => Promise<Mail.Envelope | typeof EMPTY_ENVELOPE> | Mail.Envelope | typeof EMPTY_ENVELOPE;
+    /** Structured log entry — either an envelope record or a webhook event record */
+    type LogMessage = MailLogMessage;
+    namespace Provider {
+        /**
+         * Configuration for creating a mail service instance.
+         *
+         * Requires a driver, instance name (used for queue naming), a default sender address,
+         * a logger for structured envelope records, and a queue service for async delivery.
+         *
+         * @example
+         * ```ts
+         * Mail.Provider.create({
+         *   driver: Mail.drivers.sendGrid(sendGridMail),
+         *   name: 'default',
+         *   globalFrom: { email: 'orders@mystore.com', name: 'MyStore' },
+         *   logger: mailLogger,
+         *   queueService: Queue.provider('default')
+         * })
+         * ```
+         */
+        interface MailServiceConfig {
+            /** The mail driver instance (SendGrid, SES, MailTrap, or Stub) */
+            driver: Driver;
+            /** Instance name, used for queue naming (`Maestro.Mail.{name}` and `Maestro.Mailable.{name}`) */
+            name: string;
+            /** Default sender address — overridden by `envelope.from` when provided */
+            globalFrom: MailAddress;
+            /** Logger for recording sent envelopes and webhook events */
+            logger: Log.Logger<[MailLogMessage]>;
+            /** Queue service for {@link queue} and {@link later} delivery */
+            queueService: Queue.QueueService;
+            /** Optional callback invoked when a send fails, before the error is rethrown */
+            onMessageSendFailure?(envelope: Envelope, error: unknown): unknown;
+        }
+        type Key = keyof Keys;
+        interface Keys {
+            default: unknown;
+        }
+    }
+    /**
+     * Mail service instance providing immediate, queued, and scheduled email delivery.
+     *
+     * Use {@link send} for immediate delivery within the current process, {@link queue} to
+     * offload to the job queue, or {@link later} to schedule for a future date. Internal
+     * methods {@link sendMailable} and {@link queueMailable} are used by the mailable
+     * system and are not typically called directly.
+     *
+     * @example
+     * ```ts
+     * await Mail.send({ to: 'alice@example.com', subject: 'Order Confirmed', content: { html: '...' } })
+     * Mail.queue({ to: 'bob@example.com', subject: 'Password Reset', content: { html: '...' } })
+     * ```
+     */
+    interface MailService {
+        /** Sends an email immediately using the configured driver and returns message IDs */
+        send(envelope: Envelope): Promise<{
+            messages: {
+                id: string;
+                email: string;
+            }[];
+            success: boolean;
+        }>;
+        /** Enqueues an email for immediate processing by the queue worker */
+        queue(envelope: Envelope): void;
+        /** Enqueues an email for delivery at the specified future date */
+        later(envelope: Mail.Envelope, scheduledDate: Iso.Instant): void;
+        /** Sends a mailable by name, resolving it from the global mailable registry */
+        sendMailable(input: {
+            mailableName: string;
+            renderArgs: Record<string, any>;
+        }): Promise<void>;
+        /** Enqueues a mailable for async or scheduled processing */
+        queueMailable(input: {
+            mailableName: string;
+            renderArgs: Record<string, any>;
+        }, options: {
+            scheduledDate: Iso.Instant | null;
+        }): Promise<void>;
+    }
+}
+/**
+ * Driver-based email sending with queued delivery, scheduled sending, and mailable templates.
+ * Call `Mail.Provider.create()` with a driver and register it, or use the default instance directly.
+ */
+declare const Mail: {
+    provider: typeof provider;
+    drivers: {
+        sendGrid: typeof sendGridMailDriver;
+        mailTrap: typeof mailTrapMailDriver;
+        ses: typeof sesMailDriver;
+        stub: typeof stubMailDriver;
+    };
+    attachments: {
+        ics: typeof icsAttachment;
+    };
+    send: (envelope: Mail.Envelope) => Promise<{
+        messages: {
+            id: string;
+            email: string;
+        }[];
+        success: boolean;
+    }>;
+    later: (envelope: Mail.Envelope, scheduledDate: Iso.Instant) => void;
+    queue: (envelope: Mail.Envelope) => void;
+    EMPTY_ENVELOPE: typeof EMPTY_ENVELOPE;
+    mailable: typeof mailable;
+    Provider: {
+        create: typeof create;
+        register: (name: Mail.Provider.Key, item: Mail.MailService) => void;
+    };
+};
+
+export { Mail };