@nuntly/better-email 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,686 @@
+import { User } from 'better-auth';
+
+type EmailType = 'verification-email' | 'reset-password' | 'change-email-verification' | 'delete-account-verification' | 'magic-link' | 'verification-otp' | 'organization-invitation' | 'two-factor-otp';
+interface EmailTag {
+    name: string;
+    value: string;
+}
+interface EmailMessage {
+    to: string;
+    subject: string;
+    html: string;
+    text: string;
+    tags?: EmailTag[];
+}
+interface EmailSendResponse {
+    messageId?: string;
+}
+interface EmailProvider {
+    send(message: EmailMessage): Promise<EmailSendResponse | void>;
+}
+interface VerificationEmailContext {
+    type: 'verification-email';
+    user: User;
+    url: string;
+    token: string;
+}
+interface ResetPasswordContext {
+    type: 'reset-password';
+    user: User;
+    url: string;
+    token: string;
+}
+interface ChangeEmailVerificationContext {
+    type: 'change-email-verification';
+    user: User;
+    newEmail: string;
+    url: string;
+    token: string;
+}
+interface DeleteAccountVerificationContext {
+    type: 'delete-account-verification';
+    user: User;
+    url: string;
+    token: string;
+}
+interface MagicLinkContext {
+    type: 'magic-link';
+    email: string;
+    url: string;
+    token: string;
+}
+interface VerificationOTPContext {
+    type: 'verification-otp';
+    email: string;
+    otp: string;
+    otpType: 'sign-in' | 'email-verification' | 'forget-password';
+}
+interface OrganizationInvitationContext {
+    type: 'organization-invitation';
+    id: string;
+    role: string;
+    email: string;
+    organization: {
+        id: string;
+        name: string;
+        slug?: string;
+        logo?: string | null;
+        metadata?: string | null;
+        createdAt: Date;
+    };
+    invitation: {
+        id: string;
+        email: string;
+        status: string;
+        organizationId: string;
+        role: string;
+        inviterId: string;
+        expiresAt: Date;
+    };
+    inviter: {
+        id: string;
+        organizationId: string;
+        userId: string;
+        role: string;
+        createdAt: Date;
+        user: User;
+    };
+}
+interface TwoFactorOTPContext {
+    type: 'two-factor-otp';
+    user: User & {
+        twoFactorEnabled?: boolean;
+    };
+    otp: string;
+}
+type EmailContext = VerificationEmailContext | ResetPasswordContext | ChangeEmailVerificationContext | DeleteAccountVerificationContext | MagicLinkContext | VerificationOTPContext | OrganizationInvitationContext | TwoFactorOTPContext;
+/** Extracts the context interface for a given email type from the `EmailContext` union. */
+type EmailContextFor<T extends EmailType> = Extract<EmailContext, {
+    type: T;
+}>;
+/** Context fields for a given email type, without the `type` discriminator. Useful for typing callback data and template props. */
+type EmailProps<T extends EmailType> = Omit<EmailContextFor<T>, 'type'>;
+interface RenderedEmail {
+    subject: string;
+    html: string;
+    text: string;
+}
+interface EmailTemplateRenderer {
+    render(context: EmailContext): Promise<RenderedEmail>;
+}
+type SendEmailResult = {
+    success: true;
+    skipped?: false;
+    messageId?: string;
+} | {
+    success: true;
+    skipped: true;
+} | {
+    success: false;
+    error: Error;
+};
+interface BetterEmailOptions {
+    provider: EmailProvider;
+    templateRenderer: EmailTemplateRenderer;
+    defaultTags?: EmailTag[];
+    tags?: Partial<Record<EmailType, EmailTag[]>>;
+    onBeforeSend?: (context: EmailContext, message: EmailMessage) => Promise<boolean | void>;
+    onAfterSend?: (context: EmailContext, message: EmailMessage) => Promise<void>;
+    onSendError?: (context: EmailContext, message: EmailMessage, error: Error) => Promise<void>;
+}
+
+declare function sendEmail(options: BetterEmailOptions, context: EmailContext): Promise<SendEmailResult>;
+
+/**
+ * Logs emails to the console instead of sending them.
+ * Useful for development and testing.
+ *
+ * ```ts
+ * const provider = new ConsoleProvider();
+ * ```
+ */
+declare class ConsoleProvider implements EmailProvider {
+    send(message: EmailMessage): Promise<void>;
+}
+
+interface MailgunProviderOptions {
+    /** Mailgun API key. */
+    apiKey: string;
+    /** Mailgun sending domain (e.g. `"mg.example.com"`). */
+    domain: string;
+    /** Default sender address (e.g. `"Acme <noreply@acme.com>"`). */
+    from: string;
+    /** Override the Mailgun API base URL. Defaults to `https://api.mailgun.net`. Use `https://api.eu.mailgun.net` for EU region. */
+    baseUrl?: string;
+    /** Request timeout in milliseconds. Defaults to `30_000` (30 s). */
+    timeout?: number;
+}
+/**
+ * Sends emails via the Mailgun REST API.
+ *
+ * ```ts
+ * const provider = new MailgunProvider({
+ *   apiKey: process.env.MAILGUN_API_KEY!,
+ *   domain: 'mg.example.com',
+ *   from: 'Acme <noreply@acme.com>',
+ * });
+ * ```
+ */
+declare class MailgunProvider implements EmailProvider {
+    private apiKey;
+    private domain;
+    private from;
+    private baseUrl;
+    private timeout;
+    constructor(options: MailgunProviderOptions);
+    send(message: EmailMessage): Promise<{
+        messageId?: string;
+    }>;
+}
+
+interface NuntlyProviderOptions {
+    /** Nuntly API key. */
+    apiKey: string;
+    /** Default sender address (e.g. `"Acme <noreply@acme.com>"`). */
+    from: string;
+    /** Override the Nuntly API base URL. Defaults to `https://api.nuntly.com`. */
+    baseUrl?: string;
+    /** Request timeout in milliseconds. Defaults to `30_000` (30 s). */
+    timeout?: number;
+}
+/**
+ * Sends emails via the Nuntly REST API.
+ *
+ * ```ts
+ * const provider = new NuntlyProvider({
+ *   apiKey: process.env.NUNTLY_API_KEY!,
+ *   from: 'Acme <noreply@acme.com>',
+ * });
+ * ```
+ */
+declare class NuntlyProvider implements EmailProvider {
+    private apiKey;
+    private from;
+    private baseUrl;
+    private timeout;
+    constructor(options: NuntlyProviderOptions);
+    send(message: EmailMessage): Promise<{
+        messageId?: string;
+    }>;
+}
+
+interface PostmarkProviderOptions {
+    /** Postmark server API token. */
+    serverToken: string;
+    /** Default sender address (e.g. `"Acme <noreply@acme.com>"`). */
+    from: string;
+    /** Postmark message stream ID (e.g. `"outbound"` or a custom transactional stream). */
+    messageStream?: string;
+    /** Override the Postmark API base URL. Defaults to `https://api.postmarkapp.com`. */
+    baseUrl?: string;
+    /** Request timeout in milliseconds. Defaults to `30_000` (30 s). */
+    timeout?: number;
+}
+/**
+ * Sends emails via the Postmark REST API.
+ *
+ * ```ts
+ * const provider = new PostmarkProvider({
+ *   serverToken: process.env.POSTMARK_SERVER_TOKEN!,
+ *   from: 'Acme <noreply@acme.com>',
+ * });
+ * ```
+ */
+declare class PostmarkProvider implements EmailProvider {
+    private serverToken;
+    private from;
+    private messageStream;
+    private baseUrl;
+    private timeout;
+    constructor(options: PostmarkProviderOptions);
+    send(message: EmailMessage): Promise<{
+        messageId?: string;
+    }>;
+}
+
+interface ResendProviderOptions {
+    /** Resend API key. */
+    apiKey: string;
+    /** Default sender address (e.g. `"Acme <noreply@acme.com>"`). */
+    from: string;
+    /** Override the Resend API base URL. Defaults to `https://api.resend.com`. */
+    baseUrl?: string;
+    /** Request timeout in milliseconds. Defaults to `30_000` (30 s). */
+    timeout?: number;
+}
+/**
+ * Sends emails via the Resend REST API.
+ *
+ * ```ts
+ * const provider = new ResendProvider({
+ *   apiKey: process.env.RESEND_API_KEY!,
+ *   from: 'Acme <noreply@acme.com>',
+ * });
+ * ```
+ */
+declare class ResendProvider implements EmailProvider {
+    private apiKey;
+    private from;
+    private baseUrl;
+    private timeout;
+    constructor(options: ResendProviderOptions);
+    send(message: EmailMessage): Promise<{
+        messageId?: string;
+    }>;
+}
+
+interface SESProviderOptions {
+    /**
+     * An `SESv2Client` instance from `@aws-sdk/client-sesv2`.
+     *
+     * ```ts
+     * import { SESv2Client } from '@aws-sdk/client-sesv2';
+     * const client = new SESv2Client({ region: 'us-east-1' });
+     * ```
+     */
+    client: {
+        send(command: unknown): Promise<unknown>;
+    };
+    /**
+     * The `SendEmailCommand` class from `@aws-sdk/client-sesv2`.
+     *
+     * ```ts
+     * import { SendEmailCommand } from '@aws-sdk/client-sesv2';
+     * ```
+     */
+    SendEmailCommand: new (input: unknown) => unknown;
+    /** Default sender address (e.g. `"Acme <noreply@acme.com>"`). */
+    from: string;
+    /** SES configuration set name for tracking. */
+    configurationSetName?: string;
+}
+/**
+ * Sends emails via AWS SES v2.
+ *
+ * Accepts an `SESv2Client` instance and the `SendEmailCommand` class.
+ * The provider handles building the full SES payload internally.
+ *
+ * ```ts
+ * import { SESv2Client, SendEmailCommand } from '@aws-sdk/client-sesv2';
+ *
+ * const provider = new SESProvider({
+ *   client: new SESv2Client({ region: 'us-east-1' }),
+ *   SendEmailCommand,
+ *   from: 'Acme <noreply@acme.com>',
+ * });
+ * ```
+ */
+declare class SESProvider implements EmailProvider {
+    private client;
+    private SendEmailCommand;
+    private from;
+    private configurationSetName;
+    constructor(options: SESProviderOptions);
+    send(message: EmailMessage): Promise<{
+        messageId?: string;
+    }>;
+}
+
+interface SMTPProviderOptions {
+    /**
+     * A nodemailer transporter instance.
+     *
+     * ```ts
+     * import nodemailer from 'nodemailer';
+     *
+     * const transporter = nodemailer.createTransport({
+     *   host: 'smtp.example.com',
+     *   port: 587,
+     *   auth: { user: 'user', pass: 'pass' },
+     * });
+     * ```
+     */
+    transporter: {
+        sendMail(options: Record<string, unknown>): Promise<unknown>;
+    };
+    /** Default sender address (e.g. `"Acme <noreply@acme.com>"`). */
+    from: string;
+}
+/**
+ * Sends emails via SMTP using a nodemailer transporter.
+ *
+ * Accepts a pre-configured transporter instance.
+ * The provider handles message formatting internally.
+ *
+ * ```ts
+ * import nodemailer from 'nodemailer';
+ *
+ * const provider = new SMTPProvider({
+ *   transporter: nodemailer.createTransport({
+ *     host: 'smtp.example.com',
+ *     port: 587,
+ *     auth: { user: 'user', pass: 'pass' },
+ *   }),
+ *   from: 'Acme <noreply@acme.com>',
+ * });
+ * ```
+ */
+declare class SMTPProvider implements EmailProvider {
+    private transporter;
+    private from;
+    constructor(options: SMTPProviderOptions);
+    send(message: EmailMessage): Promise<{
+        messageId?: string;
+    }>;
+}
+
+declare class DefaultTemplateRenderer implements EmailTemplateRenderer {
+    render(context: EmailContext): Promise<RenderedEmail>;
+}
+
+interface MJMLRenderedTemplate {
+    subject: string;
+    mjml: string;
+    text: string;
+}
+interface MJMLRendererOptions {
+    /**
+     * The `mjml` compile function.
+     *
+     * ```ts
+     * import mjml2html from 'mjml';
+     *
+     * const renderer = new MJMLRenderer({
+     *   compile: (mjmlString) => mjml2html(mjmlString).html,
+     *   templates: { ... },
+     * });
+     * ```
+     */
+    compile: (mjml: string) => string;
+    /**
+     * Map of email type to a function returning `{ subject, mjml, text }`.
+     * Each function receives the typed context for its email type.
+     *
+     * TypeScript enforces that a `'magic-link'` template receives `MagicLinkContext`,
+     * a `'verification-email'` template receives `VerificationEmailContext`, etc.
+     *
+     * ```ts
+     * templates: {
+     *   'verification-email': (ctx) => ({
+     *     subject: 'Verify your email',
+     *     mjml: `
+     *       <mjml>
+     *         <mj-body>
+     *           <mj-section>
+     *             <mj-column>
+     *               <mj-text>Click <a href="${ctx.url}">here</a> to verify.</mj-text>
+     *             </mj-column>
+     *           </mj-section>
+     *         </mj-body>
+     *       </mjml>
+     *     `,
+     *     text: `Verify your email: ${ctx.url}`,
+     *   }),
+     * }
+     * ```
+     */
+    templates: {
+        [K in EmailType]?: (context: EmailContextFor<K>) => MJMLRenderedTemplate;
+    };
+    /**
+     * Optional fallback renderer for email types without a template.
+     */
+    fallback?: EmailTemplateRenderer;
+}
+declare class MJMLRenderer implements EmailTemplateRenderer {
+    private options;
+    constructor(options: MJMLRendererOptions);
+    render(context: EmailContext): Promise<RenderedEmail>;
+}
+
+interface MustacheRenderedTemplate {
+    subject: string;
+    template: string;
+    text: string;
+}
+interface MustacheRendererOptions {
+    /**
+     * The mustache render function.
+     *
+     * ```ts
+     * import Mustache from 'mustache';
+     *
+     * const renderer = new MustacheRenderer({
+     *   render: (template, data) => Mustache.render(template, data),
+     *   templates: { ... },
+     * });
+     * ```
+     */
+    render: (template: string, data: Record<string, unknown>) => string;
+    /**
+     * Map of email type to a function returning `{ subject, template, text }`.
+     * Each function receives the typed context for its email type.
+     *
+     * TypeScript enforces that a `'magic-link'` template receives `MagicLinkContext`,
+     * a `'verification-email'` template receives `VerificationEmailContext`, etc.
+     *
+     * ```ts
+     * templates: {
+     *   'verification-email': (ctx) => ({
+     *     subject: 'Verify your email',
+     *     template: `
+     *       <html>
+     *         <body>
+     *           <p>Click <a href="{{url}}">here</a> to verify.</p>
+     *         </body>
+     *       </html>
+     *     `,
+     *     text: `Verify your email: ${ctx.url}`,
+     *   }),
+     * }
+     * ```
+     */
+    templates: {
+        [K in EmailType]?: (context: EmailContextFor<K>) => MustacheRenderedTemplate;
+    };
+    /**
+     * Optional fallback renderer for email types without a template.
+     */
+    fallback?: EmailTemplateRenderer;
+}
+declare class MustacheRenderer implements EmailTemplateRenderer {
+    private options;
+    constructor(options: MustacheRendererOptions);
+    render(context: EmailContext): Promise<RenderedEmail>;
+}
+
+interface ReactEmailRendererOptions {
+    /**
+     * The `render` function from `@react-email/render`.
+     *
+     * ```ts
+     * import { render } from '@react-email/render';
+     * ```
+     */
+    render: (element: any, options?: {
+        plainText?: boolean;
+    }) => Promise<string>;
+    /**
+     * `React.createElement` from `react`.
+     *
+     * ```ts
+     * import { createElement } from 'react';
+     * ```
+     */
+    createElement: (component: any, props: any) => any;
+    /**
+     * Map of email type to React Email component.
+     * Each component receives the typed context for its email type as props.
+     *
+     * TypeScript enforces that a `'magic-link'` template accepts `MagicLinkContext` props,
+     * a `'verification-email'` template accepts `VerificationEmailContext` props, etc.
+     *
+     * ```ts
+     * templates: {
+     *   'verification-email': VerificationEmail,
+     *   'reset-password': ResetPasswordEmail,
+     * }
+     * ```
+     */
+    templates: {
+        [K in EmailType]?: (props: EmailContextFor<K>) => any;
+    };
+    /**
+     * Map of email type to subject line (string or function).
+     * When using a function, the context is narrowed to the specific email type.
+     *
+     * ```ts
+     * subjects: {
+     *   'verification-email': 'Verify your email',
+     *   'reset-password': (ctx) => `Reset password for ${ctx.user.name}`,
+     * }
+     * ```
+     */
+    subjects: {
+        [K in EmailType]?: string | ((context: EmailContextFor<K>) => string);
+    };
+    /**
+     * Optional: Custom plain text renderer. If not provided, uses `render(element, { plainText: true })`.
+     *
+     * You can use `renderToPlainText` from `@react-email/render` for more control:
+     *
+     * ```ts
+     * import { render, renderToPlainText } from '@react-email/render';
+     *
+     * const renderer = new ReactEmailRenderer({
+     *   render,
+     *   renderPlainText: renderToPlainText,
+     *   // ...
+     * });
+     * ```
+     */
+    renderPlainText?: (element: any) => Promise<string> | string;
+    /**
+     * Optional fallback renderer for email types without a template.
+     */
+    fallback?: EmailTemplateRenderer;
+}
+declare class ReactEmailRenderer implements EmailTemplateRenderer {
+    private options;
+    constructor(options: ReactEmailRendererOptions);
+    render(context: EmailContext): Promise<RenderedEmail>;
+}
+
+interface ReactMJMLRendererOptions {
+    /**
+     * The `render` function from `@faire/mjml-react`.
+     *
+     * ```ts
+     * import { render } from '@faire/mjml-react';
+     *
+     * const renderer = new ReactMJMLRenderer({
+     *   render: (element) => render(element),
+     *   createElement,
+     *   templates: { ... },
+     *   subjects: { ... },
+     * });
+     * ```
+     */
+    render: (element: any) => {
+        html: string;
+        errors: any[];
+    };
+    /**
+     * `React.createElement` from `react`.
+     *
+     * ```ts
+     * import { createElement } from 'react';
+     * ```
+     */
+    createElement: (component: any, props: any) => any;
+    /**
+     * Map of email type to React component using `@faire/mjml-react` components.
+     * Each component receives the typed context for its email type as props.
+     *
+     * TypeScript enforces that a `'magic-link'` template accepts `MagicLinkContext` props,
+     * a `'verification-email'` template accepts `VerificationEmailContext` props, etc.
+     *
+     * ```ts
+     * import { Mjml, MjmlBody, MjmlSection, MjmlColumn, MjmlText } from '@faire/mjml-react';
+     *
+     * function VerificationEmail({ url }: { url: string }) {
+     *   return (
+     *     <Mjml>
+     *       <MjmlBody>
+     *         <MjmlSection>
+     *           <MjmlColumn>
+     *             <MjmlText>Click <a href={url}>here</a> to verify.</MjmlText>
+     *           </MjmlColumn>
+     *         </MjmlSection>
+     *       </MjmlBody>
+     *     </Mjml>
+     *   );
+     * }
+     * ```
+     */
+    templates: {
+        [K in EmailType]?: (props: EmailContextFor<K>) => any;
+    };
+    /**
+     * Map of email type to subject line (string or function).
+     * When using a function, the context is narrowed to the specific email type.
+     */
+    subjects: {
+        [K in EmailType]?: string | ((context: EmailContextFor<K>) => string);
+    };
+    /**
+     * Optional fallback renderer for email types without a template.
+     */
+    fallback?: EmailTemplateRenderer;
+}
+declare class ReactMJMLRenderer implements EmailTemplateRenderer {
+    private options;
+    constructor(options: ReactMJMLRendererOptions);
+    render(context: EmailContext): Promise<RenderedEmail>;
+    /**
+     * Converts HTML to plain text with basic formatting preservation.
+     * Handles line breaks, links, lists, and common block elements.
+     */
+    private htmlToPlainText;
+}
+
+declare const betterEmail: (options: BetterEmailOptions) => {
+    id: "better-email";
+    helpers: {
+        changeEmail: (data: EmailProps<"change-email-verification">) => Promise<void>;
+        deleteAccount: (data: EmailProps<"delete-account-verification">) => Promise<void>;
+        magicLink: (data: EmailProps<"magic-link">) => Promise<void>;
+        otp: (data: Omit<EmailProps<"verification-otp">, "otpType"> & {
+            type: VerificationOTPContext["otpType"];
+        }) => Promise<void>;
+        invitation: (data: EmailProps<"organization-invitation">) => Promise<void>;
+        twoFactor: (data: EmailProps<"two-factor-otp">) => Promise<void>;
+    };
+    init(): {
+        options: {
+            emailVerification: {
+                sendVerificationEmail: (data: EmailProps<"verification-email">) => Promise<void>;
+            };
+            emailAndPassword: {
+                enabled: true;
+                sendResetPassword: (data: EmailProps<"reset-password">) => Promise<void>;
+            };
+        };
+    };
+};
+declare function betterEmailChangeEmail(options: BetterEmailOptions): (data: EmailProps<"change-email-verification">) => Promise<void>;
+declare function betterEmailDeleteAccount(options: BetterEmailOptions): (data: EmailProps<"delete-account-verification">) => Promise<void>;
+declare function betterEmailMagicLink(options: BetterEmailOptions): (data: EmailProps<"magic-link">) => Promise<void>;
+declare function betterEmailOTP(options: BetterEmailOptions): (data: Omit<EmailProps<"verification-otp">, "otpType"> & {
+    type: VerificationOTPContext["otpType"];
+}) => Promise<void>;
+declare function betterEmailInvitation(options: BetterEmailOptions): (data: EmailProps<"organization-invitation">) => Promise<void>;
+declare function betterEmailTwoFactor(options: BetterEmailOptions): (data: EmailProps<"two-factor-otp">) => Promise<void>;
+
+export { ConsoleProvider, DefaultTemplateRenderer, MJMLRenderer, MailgunProvider, MustacheRenderer, NuntlyProvider, PostmarkProvider, ReactEmailRenderer, ReactMJMLRenderer, ResendProvider, SESProvider, SMTPProvider, betterEmail, betterEmailChangeEmail, betterEmailDeleteAccount, betterEmailInvitation, betterEmailMagicLink, betterEmailOTP, betterEmailTwoFactor, sendEmail };
+export type { BetterEmailOptions, ChangeEmailVerificationContext, DeleteAccountVerificationContext, EmailContext, EmailContextFor, EmailMessage, EmailProps, EmailProvider, EmailSendResponse, EmailTag, EmailTemplateRenderer, EmailType, MJMLRenderedTemplate, MJMLRendererOptions, MagicLinkContext, MailgunProviderOptions, MustacheRenderedTemplate, MustacheRendererOptions, NuntlyProviderOptions, OrganizationInvitationContext, PostmarkProviderOptions, ReactEmailRendererOptions, ReactMJMLRendererOptions, RenderedEmail, ResendProviderOptions, ResetPasswordContext, SESProviderOptions, SMTPProviderOptions, SendEmailResult, TwoFactorOTPContext, VerificationEmailContext, VerificationOTPContext };