@igniter-js/mail 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,510 @@
+import { StandardSchemaV1, IgniterLogger, IgniterJobQueueAdapter, JobQueueConfig, JobLimiter, IgniterError } from '@igniter-js/core';
+import { ReactElement } from 'react';
+
+/**
+ * Parameters used by a mail adapter to send an email.
+ */
+interface MailAdapterSendParams {
+    /** Recipient email address. */
+    to: string;
+    /** Email subject. */
+    subject: string;
+    /** HTML body. */
+    html: string;
+    /** Plain-text body. */
+    text: string;
+    /** Optional provider-level scheduled send date. */
+    scheduledAt?: Date;
+}
+/**
+ * Adapter interface used by {@link IgniterMail}.
+ *
+ * Adapters will eventually be imported from `@igniter-js/mail/adapters`.
+ */
+interface MailAdapter {
+    /** Sends an email using the underlying provider. */
+    send: (params: MailAdapterSendParams) => Promise<void>;
+}
+
+/**
+ * Email template definition used by {@link IgniterMail}.
+ */
+interface IgniterMailTemplate<TSchema extends StandardSchemaV1> {
+    /** Default subject for the template (can be overridden per-send). */
+    subject: string;
+    /** Schema used to validate and infer template payload. */
+    schema: TSchema;
+    /** React Email component renderer. */
+    render: (data: StandardSchemaV1.InferInput<TSchema>) => ReactElement;
+}
+/**
+ * Extracts the valid template keys from a template map.
+ */
+type MailTemplateKey<TTemplates extends object> = {
+    [K in keyof TTemplates]: TTemplates[K] extends IgniterMailTemplate<any> ? K : never;
+}[keyof TTemplates] & string;
+/**
+ * Extracts the payload type from a template.
+ */
+type MailTemplatePayload<TTemplate> = TTemplate extends IgniterMailTemplate<infer TSchema> ? StandardSchemaV1.InferInput<TSchema> : never;
+
+/**
+ * Type inference helper exposed by the runtime instance.
+ */
+type IgniterMailInfer<TTemplates extends object> = {
+    /** Union of valid template keys. */
+    readonly Templates: MailTemplateKey<TTemplates>;
+    /** Payloads by template. */
+    readonly Payloads: {
+        [K in MailTemplateKey<TTemplates>]: MailTemplatePayload<TTemplates[K]>;
+    };
+    /**
+     * Union of valid `mail.send()` inputs.
+     * Useful for type-level consumption.
+     */
+    readonly SendInput: {
+        [K in MailTemplateKey<TTemplates>]: IgniterMailSendParams<TTemplates, K>;
+    }[MailTemplateKey<TTemplates>];
+    /**
+     * Tuple form of `mail.schedule()` inputs.
+     */
+    readonly ScheduleInput: [
+        {
+            [K in MailTemplateKey<TTemplates>]: IgniterMailSendParams<TTemplates, K>;
+        }[MailTemplateKey<TTemplates>],
+        Date
+    ];
+};
+/**
+ * Queue options used when scheduling or enqueuing send jobs.
+ */
+type IgniterMailQueueOptions = {
+    /** Namespace used to compose the job id (default: "mail"). */
+    namespace?: string;
+    /** Task key used to compose the job id (default: "send"). */
+    task?: string;
+    /** Human-readable job name (default: "send"). */
+    name?: string;
+    /** Queue config for this job. */
+    queue?: JobQueueConfig;
+    /** Number of retry attempts on failure. */
+    attempts?: number;
+    /** Job priority (higher value = higher priority). */
+    priority?: number;
+    /** Remove job after completion. */
+    removeOnComplete?: boolean | number;
+    /** Remove job after failure. */
+    removeOnFail?: boolean | number;
+    /** Additional metadata. */
+    metadata?: Record<string, any>;
+    /** Optional rate limiter config. */
+    limiter?: JobLimiter;
+};
+/**
+ * Normalized queue configuration consumed by the runtime.
+ */
+type IgniterMailQueueConfig = {
+    /** Queue adapter instance. */
+    adapter: IgniterJobQueueAdapter<any>;
+    /** Fully qualified job id. */
+    id: string;
+    /** Optional queue options. */
+    options?: IgniterMailQueueOptions;
+};
+/**
+ * Parameters required to send an email using a template.
+ */
+interface IgniterMailSendParams<TTemplates extends object, TSelectedTemplate extends MailTemplateKey<TTemplates>> {
+    /** Recipient email address. */
+    to: string;
+    /** Optional subject override. */
+    subject?: string;
+    /** Template key. */
+    template: TSelectedTemplate;
+    /** Template payload (validated using StandardSchema when provided). */
+    data: MailTemplatePayload<TTemplates[TSelectedTemplate]>;
+}
+/**
+ * Hooks invoked by the runtime.
+ */
+interface IgniterMailHooks<TTemplates extends object> {
+    /** Invoked before rendering/sending. */
+    onSendStarted?: (params: IgniterMailSendParams<TTemplates, any>) => Promise<void>;
+    /** Invoked when sending fails. */
+    onSendError?: (params: IgniterMailSendParams<TTemplates, any>, error: Error) => Promise<void>;
+    /** Invoked after a successful send. */
+    onSendSuccess?: (params: IgniterMailSendParams<TTemplates, any>) => Promise<void>;
+}
+/**
+ * Options used to initialize {@link IgniterMail}.
+ */
+interface IgniterMailOptions<TTemplates extends object = Record<string, IgniterMailTemplate<any>>> extends IgniterMailHooks<TTemplates> {
+    /** Default FROM address used by the adapter. */
+    from: string;
+    /** Adapter implementation. */
+    adapter: MailAdapter;
+    /** Template registry. */
+    templates: TTemplates;
+    /** Optional logger used for debug/info/error logging. */
+    logger?: IgniterLogger;
+    /** Optional queue configuration for asynchronous delivery. */
+    queue?: IgniterMailQueueConfig;
+}
+/**
+ * Legacy initializer options.
+ *
+ * Kept for backwards compatibility with older integrations.
+ */
+interface LegacyIgniterMailOptions<TTemplates extends object = Record<string, IgniterMailTemplate<any>>> extends IgniterMailHooks<TTemplates> {
+    /** Provider secret/token. */
+    secret: string;
+    /** Default FROM address. */
+    from: string;
+    /** Adapter factory. */
+    adapter: (options: LegacyIgniterMailOptions<any>) => MailAdapter;
+    /** Template registry. */
+    templates: TTemplates;
+}
+/**
+ * Public interface implemented by {@link IgniterMail}.
+ */
+interface IIgniterMail<TTemplates extends object> {
+    /**
+     * Type inference helper.
+     * Access via `typeof mail.$Infer` (type-level only).
+     */
+    readonly $Infer: IgniterMailInfer<TTemplates>;
+    /** Sends an email immediately. */
+    send: <TSelectedTemplate extends MailTemplateKey<TTemplates>>(params: IgniterMailSendParams<TTemplates, TSelectedTemplate>) => Promise<void>;
+    /** Schedules an email for a future date (queue if configured, otherwise setTimeout). */
+    schedule: <TSelectedTemplate extends MailTemplateKey<TTemplates>>(params: IgniterMailSendParams<TTemplates, TSelectedTemplate>, date: Date) => Promise<void>;
+}
+/**
+ * Helper for creating a passthrough `StandardSchemaV1` validator.
+ */
+declare function createPassthroughSchema(): StandardSchemaV1;
+
+/**
+ * Postmark adapter builder.
+ *
+ * Notes:
+ * - This implementation uses `fetch` (no SDK dependency).
+ * - Designed to be extracted to `@igniter-js/mail/adapters/postmark`.
+ */
+declare class PostmarkMailAdapterBuilder {
+    private secret?;
+    private from?;
+    /** Creates a new builder instance. */
+    static create(): PostmarkMailAdapterBuilder;
+    /** Sets the Postmark Server Token. */
+    withSecret(secret: string): this;
+    /** Sets the default FROM address used when sending emails via Postmark. */
+    withFrom(from: string): this;
+    /** Builds the adapter instance. */
+    build(): MailAdapter;
+}
+/**
+ * Legacy adapter factory.
+ */
+declare const postmarkAdapter: (options: LegacyIgniterMailOptions) => MailAdapter;
+
+declare class ResendMailAdapterBuilder {
+    private secret?;
+    private from?;
+    /** Creates a new builder instance. */
+    static create(): ResendMailAdapterBuilder;
+    /** Sets the Resend API key. */
+    withSecret(secret: string): this;
+    /** Sets the default FROM address used when sending emails via Resend. */
+    withFrom(from: string): this;
+    /** Builds the adapter instance. */
+    build(): MailAdapter;
+}
+/**
+ * Legacy adapter factory.
+ */
+declare const resendAdapter: (options: LegacyIgniterMailOptions) => MailAdapter;
+
+/**
+ * SendGrid adapter builder.
+ *
+ * Notes:
+ * - This implementation uses `fetch` (no SDK dependency).
+ * - Designed to be extracted to `@igniter-js/mail/adapters/sendgrid`.
+ */
+declare class SendGridMailAdapterBuilder {
+    private secret?;
+    private from?;
+    /** Creates a new builder instance. */
+    static create(): SendGridMailAdapterBuilder;
+    /** Sets the SendGrid API key. */
+    withSecret(secret: string): this;
+    /** Sets the default FROM address used when sending emails via SendGrid. */
+    withFrom(from: string): this;
+    /** Builds the adapter instance. */
+    build(): MailAdapter;
+}
+/**
+ * Legacy adapter factory.
+ */
+declare const sendgridAdapter: (options: LegacyIgniterMailOptions) => MailAdapter;
+
+declare class SmtpMailAdapterBuilder {
+    private secret?;
+    private from?;
+    /** Creates a new builder instance. */
+    static create(): SmtpMailAdapterBuilder;
+    /** Sets the SMTP connection URL (e.g. `smtps://user:pass@host:port`). */
+    withSecret(secret: string): this;
+    /** Sets the default FROM address used when sending emails via SMTP. */
+    withFrom(from: string): this;
+    /** Builds the adapter instance. */
+    build(): MailAdapter;
+}
+/**
+ * Legacy adapter factory.
+ */
+declare const smtpAdapter: (options: LegacyIgniterMailOptions) => MailAdapter;
+
+/**
+ * In-memory message captured by {@link TestMailAdapter}.
+ */
+type TestMailMessage = MailAdapterSendParams & {
+    /** Timestamp when `send()` was called. */
+    at: Date;
+};
+/**
+ * A test-focused adapter that captures emails in memory.
+ *
+ * Why this exists:
+ * - Allows unit tests to assert subjects/recipients/content without hitting a real provider.
+ * - Can optionally log the send operation for local debugging.
+ *
+ * This adapter is intentionally dependency-free so it can live in `@igniter-js/mail/adapters`.
+ */
+type TestMailAdapter = MailAdapter & {
+    /** Captured sent messages, in order. */
+    readonly sent: TestMailMessage[];
+    /** Clears captured messages. */
+    reset: () => void;
+    /** Returns the last captured message (if any). */
+    last: () => TestMailMessage | undefined;
+};
+type CreateTestMailAdapterOptions = {
+    /** Optional logger; defaults to `console`. */
+    logger?: Pick<IgniterLogger, 'info'>;
+    /** Whether to suppress logs. Default: `false`. */
+    silent?: boolean;
+};
+/**
+ * Creates a {@link TestMailAdapter}.
+ */
+declare function createTestMailAdapter(options?: CreateTestMailAdapterOptions): TestMailAdapter;
+
+/**
+ * Webhook adapter builder.
+ *
+ * This adapter posts the email payload to an arbitrary HTTP endpoint.
+ *
+ * Why this exists:
+ * - Useful for low-code automation (Make/Zapier/n8n) or custom internal relays.
+ * - Dependency-free (uses `fetch`).
+ * - Easy to extract as `@igniter-js/mail/adapters/webhook`.
+ */
+declare class WebhookMailAdapterBuilder {
+    private url?;
+    private from?;
+    /** Creates a new builder instance. */
+    static create(): WebhookMailAdapterBuilder;
+    /**
+     * Sets the webhook URL.
+     *
+     * Note: when using `IgniterMailBuilder.withAdapter('webhook', secret)`, the `secret`
+     * is treated as the webhook URL.
+     */
+    withUrl(url: string): this;
+    /** Sets the default FROM address. */
+    withFrom(from: string): this;
+    /** Builds the adapter instance. */
+    build(): MailAdapter;
+}
+/**
+ * Legacy adapter factory.
+ */
+declare const webhookAdapter: (options: LegacyIgniterMailOptions) => MailAdapter;
+
+/**
+ * Builder for {@link IgniterMail}.
+ *
+ * This API is designed to remain stable when extracted to `@igniter-js/mail`.
+ */
+declare class IgniterMailBuilder<TTemplates extends object = Record<never, never>> {
+    private readonly factory;
+    private from?;
+    private adapter?;
+    private templates;
+    private logger?;
+    private queue?;
+    private onSendStarted?;
+    private onSendError?;
+    private onSendSuccess?;
+    private constructor();
+    /**
+     * Creates a new builder.
+     */
+    static create(factory: (options: IgniterMailOptions<any>) => IIgniterMail<any>): IgniterMailBuilder<Record<never, never>>;
+    /** Sets the default FROM address. */
+    withFrom(from: string): this;
+    /** Attaches a logger instance. */
+    withLogger(logger: IgniterLogger): this;
+    /**
+     * Enables queue delivery.
+     *
+     * If configured, `IgniterMail.schedule()` will enqueue jobs instead of using `setTimeout`.
+     */
+    withQueue(adapter: IgniterJobQueueAdapter<any>, options?: IgniterMailQueueOptions): this;
+    /**
+     * Configures the adapter.
+     *
+     * - Use an adapter instance for full control.
+     * - Or pass a provider key + secret for built-in adapters.
+     */
+    withAdapter(adapter: MailAdapter): this;
+    withAdapter(provider: string, secret: string): this;
+    /**
+     * Registers a template.
+     */
+    addTemplate<TKey extends string, TTemplate extends IgniterMailTemplate<any>>(key: TKey, template: TTemplate): IgniterMailBuilder<TTemplates & Record<TKey, TTemplate>>;
+    /** Hook invoked before sending. */
+    withOnSendStarted(onSendStarted: (params: IgniterMailSendParams<Record<string, IgniterMailTemplate<any>>, any>) => Promise<void>): this;
+    /** Hook invoked on error. */
+    withOnSendError(onSendError: (params: IgniterMailSendParams<Record<string, IgniterMailTemplate<any>>, any>, error: Error) => Promise<void>): this;
+    /** Hook invoked on success. */
+    withOnSendSuccess(onSendSuccess: (params: IgniterMailSendParams<Record<string, IgniterMailTemplate<any>>, any>) => Promise<void>): this;
+    /**
+     * Builds the {@link IgniterMail} instance.
+     */
+    build(): IIgniterMail<TTemplates>;
+}
+
+/**
+ * Builder for {@link IgniterMailTemplate}.
+ */
+declare class MailTemplateBuilder<TSchema extends StandardSchemaV1 = StandardSchemaV1> {
+    private subject?;
+    private schema?;
+    private render?;
+    /** Creates a new builder instance. */
+    static create(): MailTemplateBuilder<any>;
+    /** Sets the default subject for the template. */
+    withSubject(subject: string): this;
+    /** Attaches the schema used to validate and infer payload types. */
+    withSchema<TNextSchema extends StandardSchemaV1>(schema: TNextSchema): MailTemplateBuilder<TNextSchema>;
+    /** Sets the React Email render function for the template. */
+    withRender(render: (data: StandardSchemaV1.InferInput<TSchema>) => ReactElement): this;
+    /** Builds the template definition. */
+    build(): IgniterMailTemplate<TSchema>;
+}
+
+/**
+ * Mail runtime for Igniter.js.
+ *
+ * This class is designed to be extracted into the `@igniter-js/mail` package.
+ */
+declare class IgniterMail<TTemplates extends object> implements IIgniterMail<TTemplates> {
+    private static instance;
+    private readonly adapter;
+    private readonly templates;
+    private readonly logger?;
+    private readonly queue?;
+    private queueJobRegistered;
+    private queueJobRegistering?;
+    private readonly options;
+    /**
+     * Type inference helper.
+     * Access via `typeof mail.$Infer` (type-level only).
+     */
+    readonly $Infer: IgniterMailInfer<TTemplates>;
+    constructor(options: IgniterMailOptions<TTemplates>);
+    private ensureQueueJobRegistered;
+    private validateTemplateData;
+    /**
+     * Sends an email immediately.
+     */
+    send<TSelectedTemplate extends MailTemplateKey<TTemplates>>(params: IgniterMailSendParams<TTemplates, TSelectedTemplate>): Promise<void>;
+    /**
+     * Schedules an email for a future date.
+     *
+     * If a queue is configured, this method enqueues a job.
+     * Otherwise, it uses a best-effort `setTimeout`.
+     */
+    schedule<TSelectedTemplate extends MailTemplateKey<TTemplates>>(params: IgniterMailSendParams<TTemplates, TSelectedTemplate>, date: Date): Promise<void>;
+    private onSendStarted;
+    private onSendError;
+    private onSendSuccess;
+    /** Helper to declare adapter factories. */
+    static adapter: <TOptions>(adapter: (options: TOptions) => MailAdapter) => (options: TOptions) => MailAdapter;
+    /** Helper to declare templates with inferred payload types. */
+    static template: <TSchema extends StandardSchemaV1>(template: IgniterMailTemplate<TSchema>) => IgniterMailTemplate<TSchema>;
+    /**
+     * Creates a new builder instance.
+     */
+    static create: () => IgniterMailBuilder<Record<never, never>>;
+    /**
+     * Initializes (singleton) instance.
+     *
+     * Prefer using {@link IgniterMail.create} for new code.
+     */
+    static initialize: <TEmailTemplates extends object>(options: IgniterMailOptions<TEmailTemplates> | LegacyIgniterMailOptions<TEmailTemplates>) => IgniterMail<TEmailTemplates>;
+}
+
+/**
+ * Known error codes thrown by `@igniter-js/mail` runtime.
+ */
+type IgniterMailErrorCode = 'MAIL_PROVIDER_FROM_REQUIRED' | 'MAIL_PROVIDER_ADAPTER_REQUIRED' | 'MAIL_PROVIDER_ADAPTER_SECRET_REQUIRED' | 'MAIL_PROVIDER_ADAPTER_NOT_FOUND' | 'MAIL_PROVIDER_TEMPLATES_REQUIRED' | 'MAIL_PROVIDER_TEMPLATE_NOT_FOUND' | 'MAIL_PROVIDER_TEMPLATE_DATA_INVALID' | 'MAIL_PROVIDER_SCHEDULE_DATE_INVALID' | 'MAIL_PROVIDER_SEND_FAILED' | 'MAIL_PROVIDER_SCHEDULE_FAILED' | 'MAIL_ADAPTER_CONFIGURATION_INVALID' | 'MAIL_TEMPLATE_CONFIGURATION_INVALID';
+/**
+ * Payload used to create an {@link IgniterMailError}.
+ */
+type IgniterMailErrorPayload = {
+    /** Machine-readable error code. */
+    code: IgniterMailErrorCode;
+    /** Human-readable message. */
+    message: string;
+    /** Optional HTTP status code when surfacing errors through HTTP boundaries. */
+    statusCode?: number;
+    /** Optional original cause. */
+    cause?: unknown;
+    /** Extra diagnostic details (e.g. schema issues). */
+    details?: unknown;
+    /** Arbitrary metadata for debugging. */
+    metadata?: Record<string, unknown>;
+    /** Optional logger used by IgniterError. */
+    logger?: IgniterLogger;
+};
+/**
+ * Typed error used by the `IgniterMail` runtime.
+ *
+ * This is designed to be stable for extraction into `@igniter-js/mail`.
+ */
+declare class IgniterMailError extends IgniterError {
+    readonly code: IgniterMailErrorCode;
+    constructor(payload: IgniterMailErrorPayload);
+    /**
+     * Type guard utility.
+     */
+    static is(error: unknown): error is IgniterMailError;
+}
+
+/**
+ * Resolves a legacy adapter factory by key.
+ */
+declare const getAdapter: (adapter: string) => (options: LegacyIgniterMailOptions) => MailAdapter;
+
+/**
+ * Validates an unknown input using `StandardSchemaV1` when the schema provides `~standard.validate`.
+ *
+ * If the schema does not provide a validator, this function returns the input as-is.
+ */
+declare function validateStandardSchemaInput<TSchema extends StandardSchemaV1>(schema: TSchema, input: unknown): Promise<StandardSchemaV1.InferInput<TSchema>>;
+
+export { type CreateTestMailAdapterOptions, type IIgniterMail, IgniterMail, IgniterMailBuilder, IgniterMailError, type IgniterMailErrorCode, type IgniterMailErrorPayload, type IgniterMailHooks, type IgniterMailInfer, type IgniterMailOptions, type IgniterMailQueueConfig, type IgniterMailQueueOptions, type IgniterMailSendParams, type IgniterMailTemplate, type LegacyIgniterMailOptions, type MailAdapter, type MailAdapterSendParams, MailTemplateBuilder, type MailTemplateKey, type MailTemplatePayload, PostmarkMailAdapterBuilder, ResendMailAdapterBuilder, SendGridMailAdapterBuilder, SmtpMailAdapterBuilder, type TestMailAdapter, type TestMailMessage, WebhookMailAdapterBuilder, createPassthroughSchema, createTestMailAdapter, getAdapter, postmarkAdapter, resendAdapter, sendgridAdapter, smtpAdapter, validateStandardSchemaInput, webhookAdapter };