@avelonjs/resend 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryan Yannelli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,79 @@
+# @avelonjs/resend
+
+`@avelonjs/resend` is the Resend mail driver for Avelon. It sends transport-neutral `MailMessage` values over HTTP and maps malformed recipients to `Invalid`. Reach for this package when you want transactional mail without importing the Resend SDK in application code.
+
+## Installation
+
+```sh
+bun add @avelonjs/resend
+```
+
+```sh
+export RESEND_API_KEY=re_your_key
+export RESEND_FROM=mailer@example.test
+```
+
+## Basic Usage
+
+```ts
+import { createResendMail } from '@avelonjs/resend'
+
+const mail = createResendMail()
+
+await mail.send({
+  to: 'reader@example.test',
+  subject: 'Welcome',
+  text: 'Your account is ready.',
+  html: '<p>Your account is ready.</p>',
+})
+```
+
+## Capabilities
+
+| Capability  | Value  | Notes                                                     |
+| ----------- | ------ | --------------------------------------------------------- |
+| `templates` | `true` | `sendTemplate()` posts a hosted template id and variables |
+
+## Hosted Templates
+
+```ts
+import { createResendMail } from '@avelonjs/resend'
+
+const mail = createResendMail()
+await mail.sendTemplate('welcome-message', ['reader@example.test'], { actorName: 'Morgan' })
+```
+
+## Method Reference
+
+| Method                    | Signature                                                                                                                   | Description                                   |
+| ------------------------- | --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
+| `createResendMail`        | `(options?: ResendMailOptions) => ResendMail`                                                                               | Constructs a Resend HTTP mail driver.         |
+| `resendMailCapabilities`  | `{ templates: true }`                                                                                                       | Exact capability declaration for the Resend driver. |
+| `ResendMailOptions`       | `interface`                                                                                                                 | API key, endpoint, instance, and default sender. |
+| `ResendMail.send`         | `(message: MailMessage) => Promise<MailReceipt>`                                                                            | Sends one transactional message.              |
+| `ResendMail.sendTemplate` | `(template: string, to: string \| readonly string[], variables: Readonly<Record<string, unknown>>) => Promise<MailReceipt>` | Sends a hosted template.                      |
+| `ResendMail.raw`          | `() => { endpoint: string }`                                                                                                | Returns the API root at the vendor boundary.  |
+| `ResendMail.sent`         | `readonly MailMessage[]`                                                                                                    | Copies of messages this driver accepted.      |
+| `ResendMail.reset`        | `() => void`                                                                                                                | Clears recorded messages between tests.       |
+| `LocalResendServer.start` | `() => Promise<string>`                                                                                                     | Starts a Resend-shaped HTTP fixture.          |
+| `LocalResendServer.reset` | `() => void`                                                                                                                | Clears accepted fixture messages.             |
+| `LocalResendServer.stop`  | `() => Promise<void>`                                                                                                       | Stops the fixture listener.                   |
+| `LocalResendServer.url`   | `string`                                                                                                                    | Base API URL after `start()`.                 |
+| `LocalResendServer.sent`  | `readonly MailMessage[]`                                                                                                    | Messages the fixture accepted, in send order. |
+
+## Testing
+
+Run the shared mail conformance suite against `LocalResendServer` when `RESEND_API_KEY` is absent. Live Resend verification requires a real API key and is fail-closed in this environment.
+
+```ts
+import { mailSuite } from '@avelonjs/conformance/suites'
+import { createResendMail, LocalResendServer } from '@avelonjs/resend'
+
+const server = new LocalResendServer()
+const endpoint = await server.start()
+
+mailSuite({
+  name: 'resend local fixture',
+  create: () => createResendMail({ endpoint, defaultFrom: 'mailer@example.test' }),
+})
+```

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@avelonjs/resend",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Resend HTTP mail driver for Avelon.",
+  "license": "MIT",
+  "author": "Ryan Yannelli <ryanyannelli@gmail.com>",
+  "homepage": "https://github.com/yannelli/avelon",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yannelli/avelon.git",
+    "directory": "packages/resend"
+  },
+  "bugs": {
+    "url": "https://github.com/yannelli/avelon/issues"
+  },
+  "keywords": [
+    "avelon",
+    "typescript",
+    "resend",
+    "email"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@avelonjs/core": "workspace:*"
+  },
+  "devDependencies": {
+    "@avelonjs/conformance": "workspace:*",
+    "@types/bun": "1.3.14",
+    "typescript": "5.9.3"
+  },
+  "engines": {
+    "bun": ">=1.3.14"
+  }
+}

package/src/driver.ts

@@ -0,0 +1,197 @@
+import {
+  Invalid,
+  type MailDriver,
+  type MailMessage,
+  type MailReceipt,
+  type TemplateMailSurface,
+} from '@avelonjs/core'
+
+/** Exact capability declaration for the Resend mail driver. */
+export const resendMailCapabilities = {
+  templates: true,
+} as const
+
+/** Construction options for {@link createResendMail}. */
+export interface ResendMailOptions {
+  /** Resend API key sent as a bearer token. */
+  apiKey?: string
+  /** API root. Defaults to `https://api.resend.com`. */
+  endpoint?: string
+  /** Configured mailer name. */
+  instance?: string
+  /** Sender used when a message omits `from`. */
+  defaultFrom?: string
+}
+
+function addressList(value: string | readonly string[] | undefined): readonly string[] {
+  if (value === undefined) return []
+  return typeof value === 'string' ? [value] : value
+}
+
+function validAddress(address: string): boolean {
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(address)
+}
+
+function validateAddresses(
+  message: Pick<MailMessage, 'to' | 'from' | 'replyTo' | 'cc' | 'bcc'>,
+): void {
+  const fields: readonly [string, readonly string[]][] = [
+    ['to', addressList(message.to)],
+    ['from', addressList(message.from)],
+    ['replyTo', addressList(message.replyTo)],
+    ['cc', addressList(message.cc)],
+    ['bcc', addressList(message.bcc)],
+  ]
+  for (const [field, addresses] of fields) {
+    const malformed = addresses.find((address) => !validAddress(address))
+    if (malformed) {
+      throw new Invalid(`Invalid email address in ${field}.`, {
+        metadata: { fields: { [field]: [`${malformed} is not a valid email address.`] } },
+      })
+    }
+  }
+}
+
+function copyMessage(message: MailMessage, defaultFrom: string): MailMessage {
+  return {
+    to: typeof message.to === 'string' ? message.to : [...message.to],
+    from: message.from ?? defaultFrom,
+    ...(message.replyTo === undefined
+      ? {}
+      : { replyTo: typeof message.replyTo === 'string' ? message.replyTo : [...message.replyTo] }),
+    ...(message.cc === undefined ? {} : { cc: [...message.cc] }),
+    ...(message.bcc === undefined ? {} : { bcc: [...message.bcc] }),
+    subject: message.subject,
+    ...(message.text === undefined ? {} : { text: message.text }),
+    ...(message.html === undefined ? {} : { html: message.html }),
+    ...(message.attachments === undefined
+      ? {}
+      : {
+          attachments: message.attachments.map((attachment) => ({
+            filename: attachment.filename,
+            content: attachment.content.slice(),
+            ...(attachment.contentType === undefined
+              ? {}
+              : { contentType: attachment.contentType }),
+          })),
+        }),
+  }
+}
+
+/**
+ * Resend mail driver.
+ *
+ * Vendor access is HTTP to the Resend emails API. Application code never imports the Resend SDK.
+ */
+export class ResendMail
+  implements MailDriver<typeof resendMailCapabilities, { endpoint: string }>, TemplateMailSurface
+{
+  readonly name = 'resend'
+  readonly instance: string
+  readonly capabilities = resendMailCapabilities
+
+  readonly #apiKey: string
+  readonly #endpoint: string
+  readonly #defaultFrom: string
+  readonly #sent: MailMessage[] = []
+
+  constructor(options: Required<ResendMailOptions>) {
+    this.instance = options.instance
+    this.#apiKey = options.apiKey
+    this.#endpoint = options.endpoint.replace(/\/$/, '')
+    this.#defaultFrom = options.defaultFrom
+  }
+
+  /** Returns copies of messages this driver accepted. */
+  get sent(): readonly MailMessage[] {
+    return this.#sent.map((message) => copyMessage(message, this.#defaultFrom))
+  }
+
+  raw(): { endpoint: string } {
+    return { endpoint: this.#endpoint }
+  }
+
+  /** Clears recorded messages between isolated suite cases. */
+  reset(): void {
+    this.#sent.length = 0
+  }
+
+  async send(message: MailMessage): Promise<MailReceipt> {
+    const normalized = copyMessage(message, this.#defaultFrom)
+    validateAddresses(normalized)
+    const receipt = await this.#post('/emails', {
+      from: normalized.from,
+      to: addressList(normalized.to),
+      cc: addressList(normalized.cc),
+      bcc: addressList(normalized.bcc),
+      reply_to: addressList(normalized.replyTo),
+      subject: normalized.subject,
+      text: normalized.text,
+      html: normalized.html,
+      attachments: normalized.attachments?.map((attachment) => ({
+        filename: attachment.filename,
+        content: Buffer.from(attachment.content).toString('base64'),
+        content_type: attachment.contentType,
+      })),
+    })
+    this.#sent.push(normalized)
+    return {
+      id: receipt,
+      accepted: [
+        ...addressList(normalized.to),
+        ...addressList(normalized.cc),
+        ...addressList(normalized.bcc),
+      ],
+    }
+  }
+
+  async sendTemplate(
+    template: string,
+    to: string | readonly string[],
+    variables: Readonly<Record<string, unknown>>,
+  ): Promise<MailReceipt> {
+    validateAddresses({ to, from: this.#defaultFrom })
+    const recipients = addressList(to)
+    const receipt = await this.#post('/emails', {
+      from: this.#defaultFrom,
+      to: recipients,
+      template,
+      data: variables,
+      subject: template,
+    })
+    this.#sent.push({
+      to: typeof to === 'string' ? to : [...to],
+      from: this.#defaultFrom,
+      subject: template,
+    })
+    return { id: receipt, accepted: [...recipients] }
+  }
+
+  async #post(path: string, body: Record<string, unknown>): Promise<string> {
+    const response = await fetch(`${this.#endpoint}${path}`, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${this.#apiKey}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify(body),
+    })
+    const parsed = (await response.json()) as { id?: string; message?: string }
+    if (!response.ok || typeof parsed.id !== 'string') {
+      throw new Invalid(parsed.message ?? 'Resend rejected the message.', {
+        metadata: { fields: { mail: [parsed.message ?? 'send failed'] } },
+      })
+    }
+    return parsed.id
+  }
+}
+
+/** Creates a Resend mail driver from options or environment defaults. */
+export function createResendMail(options: ResendMailOptions = {}): ResendMail {
+  return new ResendMail({
+    apiKey: options.apiKey ?? process.env.RESEND_API_KEY ?? 're_local_fixture',
+    endpoint: options.endpoint ?? process.env.RESEND_ENDPOINT ?? 'https://api.resend.com',
+    instance: options.instance ?? 'default',
+    defaultFrom: options.defaultFrom ?? process.env.RESEND_FROM ?? 'mailer@example.test',
+  })
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export {
+  createResendMail,
+  ResendMail,
+  resendMailCapabilities,
+  type ResendMailOptions,
+} from './driver'
+export { LocalResendServer } from './local-mail'

package/src/local-mail.ts

@@ -0,0 +1,117 @@
+import type { MailAttachment, MailMessage } from '@avelonjs/core'
+
+interface StoredMail {
+  message: MailMessage
+}
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'Content-Type': 'application/json' },
+  })
+}
+
+/**
+ * Minimal Resend-shaped HTTP fixture for mail conformance.
+ *
+ * Real deployments point {@link createResendMail} at `https://api.resend.com`. This server exists so
+ * envelope and attachment round trips can run without a Resend API key.
+ */
+export class LocalResendServer {
+  readonly #sent: StoredMail[] = []
+  #server: ReturnType<typeof Bun.serve> | undefined
+  #url = ''
+  #nextId = 1
+
+  /** Base API URL, e.g. `http://127.0.0.1:4010`. */
+  get url(): string {
+    return this.#url
+  }
+
+  /** Messages accepted by this fixture, in send order. */
+  get sent(): readonly MailMessage[] {
+    return this.#sent.map((entry) => entry.message)
+  }
+
+  /** Starts the server on an ephemeral port. */
+  async start(): Promise<string> {
+    const self = this
+    this.#server = Bun.serve({
+      port: 0,
+      async fetch(request) {
+        return self.#handle(request)
+      },
+    })
+    this.#url = `http://127.0.0.1:${this.#server.port}`
+    return this.#url
+  }
+
+  /** Clears accepted messages without restarting the listener. */
+  reset(): void {
+    this.#sent.length = 0
+    this.#nextId = 1
+  }
+
+  /** Stops the fixture listener. */
+  async stop(): Promise<void> {
+    this.#server?.stop(true)
+    this.#server = undefined
+    this.reset()
+  }
+
+  async #handle(request: Request): Promise<Response> {
+    const url = new URL(request.url)
+    if (request.method !== 'POST' || url.pathname !== '/emails') {
+      return json({ message: 'not_found' }, 404)
+    }
+
+    const body = (await request.json()) as Record<string, unknown>
+    const id = `re_${this.#nextId++}`
+    const to = asAddressList(body.to)
+    const cc = asAddressList(body.cc)
+    const bcc = asAddressList(body.bcc)
+    const replyTo = asAddressList(body.reply_to)
+    const attachments = asAttachments(body.attachments)
+
+    this.#sent.push({
+      message: {
+        to: to.length === 1 ? (to[0] as string) : to,
+        from: typeof body.from === 'string' ? body.from : undefined,
+        ...(replyTo.length === 0 ? {} : { replyTo: replyTo.length === 1 ? replyTo[0] : replyTo }),
+        ...(cc.length === 0 ? {} : { cc }),
+        ...(bcc.length === 0 ? {} : { bcc }),
+        subject: typeof body.subject === 'string' ? body.subject : String(body.template ?? ''),
+        ...(typeof body.text === 'string' ? { text: body.text } : {}),
+        ...(typeof body.html === 'string' ? { html: body.html } : {}),
+        ...(attachments === undefined ? {} : { attachments }),
+      },
+    })
+
+    return json({ id })
+  }
+}
+
+function asAddressList(value: unknown): string[] {
+  if (typeof value === 'string') return [value]
+  if (!Array.isArray(value)) return []
+  return value.filter((entry): entry is string => typeof entry === 'string')
+}
+
+function asAttachments(value: unknown): readonly MailAttachment[] | undefined {
+  if (!Array.isArray(value)) return undefined
+  return value.flatMap((entry) => {
+    if (typeof entry !== 'object' || entry === null) return []
+    const filename = Reflect.get(entry, 'filename')
+    const content = Reflect.get(entry, 'content')
+    const contentType = Reflect.get(entry, 'content_type')
+    if (typeof filename !== 'string' || typeof content !== 'string') return []
+    const bytes = Buffer.from(content, 'base64')
+    return [
+      {
+        filename,
+        content: new Uint8Array(bytes),
+        ...(typeof contentType === 'string' ? { contentType } : {}),
+      },
+    ]
+  })
+}