@stacksjs/email 0.70.23 → 0.70.26

package/dist/src/drivers/index.d.ts

@@ -0,0 +1,6 @@
+export * as log from './log';
+export * as mailgun from './mailgun';
+export * as mailtrap from './mailtrap';
+export * as nodemailer from './nodemailer';
+export * as sendgrid from './sendgrid';
+export * as ses from './ses';

package/dist/src/drivers/log.d.ts

@@ -0,0 +1,30 @@
+import { BaseEmailDriver } from './base';
+import type { EmailMessage, EmailResult } from '@stacksjs/types';
+import type { TemplateOptions } from '../template';
+declare const captured: CapturedEmail[];
+/**
+ * Local-only email driver that never opens a network socket. Renders
+ * the message to disk so devs can inspect it (and tests can read it),
+ * and remembers the last N sends in-memory so tests can assert against
+ * them without scraping log output.
+ *
+ * Pick this driver when:
+ *   - running tests (no SMTP credentials, deterministic output)
+ *   - local development (no AWS/SendGrid setup, no mailbox spam)
+ *   - CI smoke tests where we want to assert "an email was sent"
+ *
+ * In production, use `ses` / `sendgrid` / `mailgun` / `smtp` instead.
+ */
+declare interface CapturedEmail extends EmailMessage {
+  sentAt: Date
+  rendered?: { html?: string, text?: string }
+}
+export declare class LogEmailDriver extends BaseEmailDriver {
+  name: string;
+  send(message: EmailMessage, options?: TemplateOptions): Promise<EmailResult>;
+  static captured(): readonly CapturedEmail[];
+  static reset(): void;
+}
+// Convenience export to mirror the other drivers' module shape — the
+// drivers/index.ts re-exports each driver namespace (`export * as log`).
+export default LogEmailDriver;

package/dist/src/drivers/mailgun.d.ts

@@ -0,0 +1,7 @@
+import { BaseEmailDriver } from './base';
+import type { EmailMessage, EmailResult } from '@stacksjs/types';
+import type { TemplateOptions } from '../template';
+export declare class MailgunDriver extends BaseEmailDriver {
+  name: string;
+  send(message: EmailMessage, options?: TemplateOptions): Promise<EmailResult>;
+}

package/dist/src/drivers/mailtrap.d.ts

@@ -0,0 +1,8 @@
+import { BaseEmailDriver } from './base';
+import type { EmailMessage, EmailResult } from '@stacksjs/types';
+import type { TemplateOptions } from '../template';
+export declare class MailtrapDriver extends BaseEmailDriver {
+  name: string;
+  send(message: EmailMessage, options?: TemplateOptions): Promise<EmailResult>;
+}
+export default MailtrapDriver;

package/dist/src/drivers/nodemailer.d.ts

@@ -0,0 +1,3 @@
+export declare class NodemailerDriver {
+  send(): Promise<void>;
+}

package/dist/src/drivers/sendgrid.d.ts

@@ -0,0 +1,8 @@
+import { BaseEmailDriver } from './base';
+import type { EmailMessage, EmailResult } from '@stacksjs/types';
+import type { TemplateOptions } from '../template';
+export declare class SendGridDriver extends BaseEmailDriver {
+  name: string;
+  send(message: EmailMessage, options?: TemplateOptions): Promise<EmailResult>;
+}
+export default SendGridDriver;

package/dist/src/drivers/ses.d.ts

@@ -0,0 +1,9 @@
+import { BaseEmailDriver } from './base';
+import type { EmailMessage, EmailResult } from '@stacksjs/types';
+import type { TemplateOptions } from '../template';
+export declare class SESDriver extends BaseEmailDriver {
+  name: string;
+  send(message: EmailMessage, options?: TemplateOptions): Promise<EmailResult>;
+  protected formatAddresses(addresses: string | string[] | { address: string, name?: string }[] | undefined): string[];
+}
+export default SESDriver;

package/dist/src/email.d.ts

@@ -0,0 +1,39 @@
+import type { EmailMessage, EmailResult } from '@stacksjs/types';
+import type { Message } from './types';
+export declare const mail: Mail;
+/** Result returned by email handler callbacks */
+declare interface EmailHandlerResult {
+  message: string
+}
+/** Configuration for the sender address */
+declare interface EmailFromAddress {
+  name: string
+  address: string
+}
+/** Configuration for the Mail singleton */
+declare interface MailConfig {
+  defaultDriver?: string
+}
+/**
+ * Email notification class for defining email notifications
+ */
+export declare class Email {
+  name: string;
+  subject: string;
+  to: string | string[];
+  from?: EmailFromAddress;
+  template: string;
+  handle?: () => Promise<EmailHandlerResult>;
+  onError?: (error: Error) => Promise<EmailHandlerResult>;
+  onSuccess?: () => void;
+  constructor(options: Message);
+  send(to?: string | string[]): Promise<EmailHandlerResult>;
+}
+declare class Mail {
+  constructor(options?: MailConfig);
+  send(message: EmailMessage): Promise<EmailResult>;
+  use(driver: string): Mail;
+  queue(message: EmailMessage): Promise<void>;
+  later(delaySeconds: number, message: EmailMessage): Promise<void>;
+  queueOn(queueName: string, message: EmailMessage): Promise<void>;
+}

package/dist/src/index.d.ts

@@ -0,0 +1,5 @@
+export * from './drivers';
+export * from './email';
+export * from './mailable';
+export * from './template';
+export * from './types';

package/dist/src/mailable.d.ts

@@ -0,0 +1,81 @@
+import type { EmailAddress, EmailAttachment, EmailResult } from '@stacksjs/types';
+/**
+ * Options accepted by {@link Mailable.send} — currently allows scoping
+ * the send to a specific driver registered on the Mail singleton (e.g.
+ * `'log'` to swallow the email in a test, `'ses'` to force production
+ * delivery during a one-off backfill).
+ */
+export declare interface MailableSendOptions {
+  driver?: string
+}
+/**
+ * Internal stash for template rendering — populated by {@link Mailable.template}
+ * and consumed in {@link Mailable.send} after `build()` resolves.
+ */
+declare interface TemplateRef {
+  name: string
+  props: Record<string, unknown>
+}
+/**
+ * Allowed recipient input — accepts a single address, an array of addresses,
+ * or already-shaped {@link EmailAddress} objects. Strings are treated as
+ * `address` only (no display name).
+ */
+export type MailableAddressInput = string | string[] | EmailAddress | EmailAddress[];
+/**
+ * Laravel-style class-based email definition. Subclass `Mailable`,
+ * implement `build()`, and call `.send()` to dispatch.
+ *
+ * Compared to the existing function-form `Email` / direct `mail.send()`
+ * APIs this gives you:
+ *  - encapsulation of recipient/subject/body building per email type
+ *  - chainable, immutable-feeling fluent setters
+ *  - a single hook (`build`) where view-model -> message translation happens
+ *  - automatic STX template rendering via the existing `template()` helper
+ *
+ * The class still ultimately routes through the same `mail` singleton, so
+ * configured drivers, queueing, and `from` defaults all behave identically.
+ *
+ * @example
+ * ```ts
+ * import { Mailable } from '@stacksjs/email'
+ *
+ * export default class WelcomeMail extends Mailable {
+ *   constructor(private user: { name: string, email: string }) { super() }
+ *
+ *   build() {
+ *     return this
+ *       .to(this.user.email)
+ *       .subject('Welcome!')
+ *       .template('welcome', { name: this.user.name })
+ *   }
+ * }
+ *
+ * await new WelcomeMail(user).send()
+ * ```
+ */
+export declare abstract class Mailable {
+  protected _to: string[] | EmailAddress[];
+  protected _cc: string[] | EmailAddress[];
+  protected _bcc: string[] | EmailAddress[];
+  protected _replyTo?: EmailAddress;
+  protected _from?: EmailAddress;
+  protected _subject?: string;
+  protected _text?: string;
+  protected _html?: string;
+  protected _template?: TemplateRef;
+  protected _attachments: EmailAttachment[];
+  abstract build(): this | Promise<this>;
+  to(address: MailableAddressInput): this;
+  cc(address: MailableAddressInput): this;
+  bcc(address: MailableAddressInput): this;
+  replyTo(address: string | EmailAddress): this;
+  from(addr: EmailAddress): this;
+  subject(s: string): this;
+  text(body: string): this;
+  html(body: string): this;
+  template(name: string, props?: Record<string, unknown>): this;
+  attach(path: string, name?: string): this;
+  attachData(buffer: Uint8Array | string, name: string, mime?: string): this;
+  send(options?: MailableSendOptions): Promise<EmailResult>;
+}

package/dist/src/template.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Render an email template with optional layout
+ *
+ * Supports both .stx and .html templates. When a .stx template
+ * is found, it uses the STX engine for rendering (with directives,
+ * server scripts, etc.). When an .html template is found, it uses
+ * simple {{ variable }} replacement with layout wrapping.
+ *
+ * .stx templates are preferred over .html when both exist.
+ *
+ * @example
+ * ```typescript
+ * // STX template (resources/emails/welcome.stx)
+ * const { html, text } = await template('welcome', {
+ *   variables: { userName: 'John' }
+ * })
+ *
+ * // HTML template with layout
+ * const { html, text } = await template('notification', {
+ *   layout: 'base',
+ *   variables: { message: 'Hello' }
+ * })
+ *
+ * // Without layout (HTML templates only)
+ * const { html, text } = await template('simple', {
+ *   layout: false
+ * })
+ * ```
+ */
+export declare function template(templateName: string, options?: TemplateOptions): Promise<TemplateResult>;
+/**
+ * Render a raw HTML string with variables (no file loading)
+ */
+export declare function renderHtml(htmlContent: string, variables?: TemplateVariables): TemplateResult;
+/**
+ * Check if a template exists (.stx or .html)
+ */
+export declare function templateExists(templateName: string): boolean;
+/**
+ * List available templates (.stx and .html)
+ */
+export declare function listTemplates(): string[];
+export declare interface TemplateResult {
+  html: string
+  text: string
+}
+export declare interface TemplateOptions {
+  variables?: TemplateVariables
+  layout?: string | false
+  subject?: string
+}
+/** Allowed types for email template variable values */
+export type TemplateVariableValue = string | number | boolean | undefined | null;
+/** Map of variable names to their values for template replacement */
+export type TemplateVariables = Record<string, TemplateVariableValue>;

package/dist/{types.d.ts → src/types.d.ts}

@@ -1,13 +1,13 @@
 export declare interface Message {
   name: string
   subject: string
-  to: string
+  to: string | string[]
   from?: {
     name: string
     address: string
   }
   template: string
-  handle?: () => Promise<{ message: string }> 
+  handle?: () => Promise<{ message: string }>
   onError?: (error: Error) => Promise<{ message: string }>
   onSuccess?: () => void
 }
@@ -34,4 +34,4 @@ export declare interface EmailParams {
   from: string
   subject: string
   html: string
-}
+}

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "@stacksjs/email",
   "type": "module",
-  "version": "0.70.23",
+  "version": "0.70.26",
   "description": "The Stacks Email integration. Painlessly create & manage your inboxes, templates, and send emails.",
   "author": "Chris Breuer",
-  "contributors": ["Chris Breuer <chris@stacksjs.org>"],
+  "contributors": [
+    "Chris Breuer <chris@stacksjs.com>"
+  ],
   "license": "MIT",
   "funding": "https://github.com/sponsors/chrisbbreuer",
   "homepage": "https://github.com/stacksjs/stacks/tree/main/storage/framework/core/email#readme",
@@ -16,31 +18,45 @@
   "bugs": {
     "url": "https://github.com/stacksjs/stacks/issues"
   },
-  "keywords": ["email", "ses", "aws", "stacks", "emailjs", "mailgun"],
+  "keywords": [
+    "email",
+    "ses",
+    "aws",
+    "stacks",
+    "emailjs",
+    "mailgun"
+  ],
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
       "import": "./dist/index.js"
     },
     "./*": {
+      "bun": "./src/*",
       "import": "./dist/*"
     }
   },
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
-  "files": ["README.md", "dist"],
+  "files": [
+    "README.md",
+    "dist"
+  ],
   "scripts": {
     "build": "bun build.ts",
     "build:inbound": "bun build-inbound.ts",
     "typecheck": "bun tsc --noEmit",
     "prepublishOnly": "bun run build"
   },
+  "dependencies": {
+    "@stacksjs/ts-cloud": "^0.2.15"
+  },
   "devDependencies": {
-    "@stacksjs/cli": "0.70.22",
-    "@stacksjs/config": "0.70.22",
-    "@stacksjs/development": "0.70.22",
-    "@stacksjs/error-handling": "0.70.22",
-    "@stacksjs/types": "0.70.22",
-    "aws-sdk": "^2.1692.0",
-    "vue-email": "^0.8.11"
+    "@stacksjs/cli": "0.70.23",
+    "@stacksjs/config": "0.70.23",
+    "better-dx": "^0.2.12",
+    "@stacksjs/error-handling": "0.70.23",
+    "@stacksjs/types": "0.70.23"
   }
 }

package/dist/base.d.ts

@@ -1,130 +0,0 @@
-import type { EmailDriver, EmailDriverConfig, EmailMessage, EmailResult, RenderOptions } from '@stacksjs/types';
-
-export declare abstract class BaseEmailDriver implements EmailDriver {
-  public abstract name: string
-  protected config: Required<EmailDriverConfig>
-
-  constructor(config?: EmailDriverConfig) {
-    this.config = {
-      maxRetries: config?.maxRetries || 3,
-      retryTimeout: config?.retryTimeout || 1000,
-      ...config,
-    }
-  }
-
-  public configure(config: EmailDriverConfig): void {
-    this.config = { ...this.config, ...config }
-  }
-
-  public abstract send(message: EmailMessage, options?: RenderOptions): Promise<EmailResult>
-
-  protected validateMessage(message: EmailMessage): boolean {
-    if (!message.from?.address) {
-      throw new Error('Email sender address is required')
-    }
-
-    if (!message.to || (Array.isArray(message.to) && message.to.length === 0)) {
-      throw new Error('At least one recipient is required')
-    }
-
-    if (!message.subject) {
-      throw new Error('Email subject is required')
-    }
-
-    return true
-  }
-
-  protected formatAddresses(addresses: string | string[] | EmailAddress[] | undefined): string[] {
-    if (!addresses)
-      return []
-
-    if (typeof addresses === 'string') {
-      return [addresses]
-    }
-
-    return addresses.map((addr) => {
-      if (typeof addr === 'string')
-        return addr
-      return addr.name ? `${addr.name} <${addr.address}>` : addr.address
-    })
-  }
-
-  protected async handleError(error: unknown, message: EmailMessage): Promise<EmailResult> {
-    const err = error instanceof Error ? error : new Error(String(error))
-
-    log.error(`[${this.name}] Email sending failed`, {
-      error: err.message,
-      stack: err.stack,
-      to: message.to,
-      subject: message.subject,
-    })
-
-    let result: EmailResult = {
-      message: `Email sending failed: ${err.message}`,
-      success: false,
-      provider: this.name,
-    }
-
-    if (message.onError) {
-      const customResult = message.onError(err)
-      const handlerResult = customResult instanceof Promise
-        ? await customResult
-        : customResult
-
-      result = {
-        ...result,
-        ...handlerResult,
-        success: false,
-        provider: this.name,
-      }
-    }
-
-    return result
-  }
-
-  protected async handleSuccess(message: EmailMessage, messageId?: string): Promise<EmailResult> {
-    let result: EmailResult = {
-      message: 'Email sent successfully',
-      success: true,
-      provider: this.name,
-      messageId,
-    }
-
-    try {
-      if (message.handle) {
-        const customResult = message.handle()
-        const handlerResult = customResult instanceof Promise
-          ? await customResult
-          : customResult
-
-        result = {
-          ...result,
-          ...handlerResult,
-          success: true,
-          provider: this.name,
-          messageId,
-        }
-      }
-
-      if (message.onSuccess) {
-        const successResult = message.onSuccess()
-        const handlerResult = successResult instanceof Promise
-          ? await successResult
-          : successResult
-
-        result = {
-          ...result,
-          ...handlerResult,
-          success: true,
-          provider: this.name,
-          messageId,
-        }
-      }
-    }
-    catch (error) {
-      return this.handleError(error, message)
-    }
-
-    return result
-  }
-}

package/dist/config.d.ts

@@ -1,3 +0,0 @@
-export declare const email: typeof notification.email;
-
-export default email;

package/dist/email.d.ts

@@ -1,2 +0,0 @@
-declare const driver: unknown;
-export declare const mail: Mail;

package/dist/index.d.ts

@@ -1,3 +0,0 @@
-export * from './drivers'
-export * from './email'
-export * from './types'

package/dist/mailgun.d.ts

@@ -1,141 +0,0 @@
-import type { EmailAddress, EmailMessage, EmailResult, RenderOptions } from '@stacksjs/types';
-
-export declare class MailgunDriver extends BaseEmailDriver {
-  public name = 'mailgun'
-  private apiKey: string
-  private domain: string
-  private endpoint: string
-
-  constructor() {
-    super()
-    this.apiKey = config.services.mailgun?.apiKey ?? ''
-    this.domain = config.services.mailgun?.domain ?? ''
-    this.endpoint = config.services.mailgun?.endpoint ?? 'api.mailgun.net'
-  }
-
-  public async send(message: EmailMessage, options?: RenderOptions): Promise<EmailResult> {
-    const logContext = {
-      provider: this.name,
-      to: message.to,
-      subject: message.subject,
-      domain: this.domain,
-    }
-
-    log.info('Sending email via Mailgun...', logContext)
-
-    try {
-      this.validateMessage(message)
-
-      let htmlContent: string | undefined
-      if (message.template) {
-        const templ = await template(message.template, options)
-        if (templ && 'html' in templ) {
-          htmlContent = templ.html
-        }
-      }
-
-      const formData = new FormData()
-      formData.append('from', this.formatMailgunAddress(message.from))
-
-      this.formatMailgunAddresses(message.to).forEach(to => formData.append('to', to))
-
-      if (message.cc)
-        this.formatMailgunAddresses(message.cc).forEach(cc => formData.append('cc', cc))
-
-      if (message.bcc)
-        this.formatMailgunAddresses(message.bcc).forEach(bcc => formData.append('bcc', bcc))
-
-      formData.append('subject', message.subject)
-
-      if (htmlContent) {
-        formData.append('html', htmlContent)
-      }
-
-      if (message.text)
-        formData.append('text', message.text)
-
-      if (message.attachments) {
-        message.attachments.forEach((attachment) => {
-          const content = typeof attachment.content === 'string'
-            ? attachment.content
-            : this.arrayBufferToBase64(attachment.content)
-
-          formData.append('attachment', new Blob([content], { type: attachment.contentType }), attachment.filename)
-        })
-      }
-
-      const response = await this.sendWithRetry(formData)
-      return this.handleSuccess(message, response.id)
-    }
-    catch (error) {
-      return this.handleError(error, message)
-    }
-  }
-
-  private formatMailgunAddress(address: EmailAddress): string {
-    return address.name ? `${address.name} <${address.address}>` : address.address
-  }
-
-  private formatMailgunAddresses(addresses: string | string[] | EmailAddress[] | undefined): string[] {
-    if (!addresses)
-      return []
-
-    if (typeof addresses === 'string')
-      return [addresses]
-
-    return addresses.map((addr) => {
-      if (typeof addr === 'string')
-        return addr
-      return addr.name ? `${addr.name} <${addr.address}>` : addr.address
-    })
-  }
-
-  private arrayBufferToBase64(buffer: Uint8Array): string {
-    let binary = ''
-    const bytes = new Uint8Array(buffer)
-    const len = bytes.byteLength
-
-    for (let i = 0; i < len; i++) {
-      binary += String.fromCharCode(bytes[i])
-    }
-
-    return typeof btoa === 'function'
-      ? btoa(binary)
-      : Buffer.from(binary).toString('base64')
-  }
-
-  private async sendWithRetry(formData: FormData, attempt = 1): Promise<any> {
-    const url = `https:
-    const auth = Buffer.from(`api:${this.apiKey}`).toString('base64')
-
-    try {
-      const response = await fetch(url, {
-        method: 'POST',
-        headers: {
-          Authorization: `Basic ${auth}`,
-        },
-        body: formData,
-      })
-
-      if (!response.ok) {
-        const errorData = await response.json()
-        throw new Error(`Mailgun API error: ${response.status} - ${JSON.stringify(errorData)}`)
-      }
-
-      const data = await response.json()
-      log.info(`[${this.name}] Email sent successfully`, { attempt, messageId: data.id })
-      return data
-    }
-    catch (error) {
-      if (attempt < (config.services.mailgun?.maxRetries ?? 3)) {
-        const retryTimeout = config.services.mailgun?.retryTimeout ?? 1000
-        log.warn(`[${this.name}] Email send failed, retrying (${attempt}/${config.services.mailgun?.maxRetries ?? 3})`)
-        await new Promise(resolve => setTimeout(resolve, retryTimeout))
-        return this.sendWithRetry(formData, attempt + 1)
-      }
-      throw error
-    }
-  }
-}
-
-export default MailgunDriver;