@molecule/api-emails-resend 1.0.0

package/LICENSE

@@ -0,0 +1,115 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship.
+
+      "Contribution" shall mean any work of authorship, including the
+      original version of the Work and any modifications or additions
+      to that Work, that is intentionally submitted to the Licensor for
+      inclusion in the Work by the copyright owner or by an individual or
+      Legal Entity authorized to submit on behalf of the copyright owner.
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      patent license to make, have made, use, offer to sell, sell, import,
+      and otherwise transfer the Work.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file.
+
+   5. Submission of Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.
+
+   8. Limitation of Liability. In no event and under no legal theory shall
+      any Contributor be liable to You for damages.
+
+   9. Accepting Warranty or Additional Liability.
+
+   Copyright 2026 Molecule Dev, Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,396 @@
+<!--
+AUTO-GENERATED — DO NOT EDIT THIS FILE.
+Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
+Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
+To change this document, edit the module-level JSDoc in src/index.ts.
+Generated: 2026-09-04T12:07:53.348Z
+-->
+
+# @molecule/api-emails-resend
+
+> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
+> It is written to be read by coding agents as much as by people, and is generated from this
+> package's source — edit `src/index.ts` JSDoc, not this file.
+
+Resend email provider for molecule.dev.
+
+## Quick Start
+
+```typescript
+import { setTransport } from '@molecule/api-emails'
+import { provider } from '@molecule/api-emails-resend'
+
+setTransport(provider)
+```
+
+## Type
+
+`provider`
+
+## Installation
+
+```bash
+npm install @molecule/api-emails-resend @molecule/api-bond @molecule/api-emails @molecule/api-secrets
+```
+
+## API
+
+### Interfaces
+
+#### `EmailMessage`
+
+Email message options.
+
+```typescript
+interface EmailMessage {
+  /**
+   * Sender address.
+   */
+  from: string | EmailAddress
+  /**
+   * Recipient(s).
+   */
+  to: string | EmailAddress | (string | EmailAddress)[]
+  /**
+   * CC recipient(s).
+   */
+  cc?: string | EmailAddress | (string | EmailAddress)[]
+  /**
+   * BCC recipient(s).
+   */
+  bcc?: string | EmailAddress | (string | EmailAddress)[]
+  /**
+   * Reply-to address.
+   */
+  replyTo?: string | EmailAddress
+  /**
+   * Email subject.
+   */
+  subject: string
+  /**
+   * Plain text body.
+   */
+  text?: string
+  /**
+   * HTML body.
+   */
+  html?: string
+  /**
+   * File attachments.
+   */
+  attachments?: EmailAttachment[]
+  /**
+   * i18n key for the subject (for client-side translation).
+   */
+  subjectKey?: string
+  /**
+   * i18n key for the plain text body (for client-side translation).
+   */
+  textKey?: string
+  /**
+   * i18n key for the HTML body (for client-side translation).
+   */
+  htmlKey?: string
+}
+```
+
+#### `EmailSendResult`
+
+Result of sending an email.
+
+```typescript
+interface EmailSendResult {
+  /**
+   * Whether the email was accepted for delivery.
+   */
+  accepted: string[]
+  /**
+   * Addresses that were rejected.
+   */
+  rejected: string[]
+  /**
+   * Message ID from the provider.
+   */
+  messageId?: string
+  /**
+   * Raw response from the provider.
+   */
+  response?: string
+}
+```
+
+#### `EmailTransport`
+
+Email transport interface.
+
+All email providers must implement this interface.
+
+```typescript
+interface EmailTransport {
+  /**
+   * Sends an email message.
+   * @returns The send result.
+   */
+  sendMail(message: EmailMessage): Promise<EmailSendResult>
+}
+```
+
+#### `ResendAttachment`
+
+One entry of a send request's `attachments[]`, exactly as the Resend REST API
+expects it: base64 `content` plus snake_case metadata.
+
+```typescript
+interface ResendAttachment {
+  /** File content, base64-encoded. */
+  content: string
+  /** File name shown to the recipient; Resend derives the MIME type from it when `content_type` is unset. */
+  filename: string
+  /** MIME type of the file. */
+  content_type?: string
+  /** Content-ID for an inline image referenced as `cid:` in the HTML body. */
+  content_id?: string
+}
+```
+
+#### `ResendClient`
+
+The narrow HTTP client this bond uses to reach Resend.
+
+```typescript
+interface ResendClient {
+  /**
+   * Sends one email via `POST /emails`.
+   * @returns The HTTP status and the message id.
+   */
+  send(request: ResendSendRequest): Promise<ResendSendResponse>
+}
+```
+
+#### `ResendErrorBody`
+
+Resend's JSON error body (`{ statusCode, message, name }`), with every field
+optional because the wire is not trusted.
+
+```typescript
+interface ResendErrorBody {
+  /** HTTP status Resend reports in the body (may be `null`). */
+  statusCode?: number | null
+  /** Human-readable error message. */
+  message?: string
+  /** Machine-readable error name, e.g. `validation_error`, `daily_quota_exceeded`. */
+  name?: string
+}
+```
+
+#### `ResendSendRequest`
+
+Request body for `POST /emails`. Field names are the REST API's own
+(snake_case, e.g. `reply_to`) — NOT the camelCase the official SDK accepts.
+
+```typescript
+interface ResendSendRequest {
+  /** Sender, as a bare address or `Name <address>`. */
+  from: string
+  /** Recipients (Resend accepts at most 50). */
+  to: string[]
+  /** Subject line. */
+  subject: string
+  /** CC recipients. */
+  cc?: string[]
+  /** BCC recipients. */
+  bcc?: string[]
+  /** Reply-To address. */
+  reply_to?: string
+  /** HTML body. */
+  html?: string
+  /** Plain-text body (Resend derives one from `html` when omitted). */
+  text?: string
+  /** File attachments. */
+  attachments?: ResendAttachment[]
+}
+```
+
+#### `ResendSendResponse`
+
+What {@link ResendClient.send} resolves with: the HTTP status of the accepted
+request and the message `id` Resend returned in the response body.
+
+```typescript
+interface ResendSendResponse {
+  /** HTTP status code of the response (2xx). */
+  status: number
+  /** The `id` from the response body, when present. */
+  id?: string
+}
+```
+
+### Classes
+
+#### `ResendApiError`
+
+A non-2xx response from the Resend API.
+
+`status` is the HTTP status, `code` is Resend's machine-readable error `name`
+(e.g. `validation_error`, `rate_limit_exceeded`, `daily_quota_exceeded`) when
+the body carried one, and `body` is the parsed error body. Deliberately NOT
+tagged with `statusCode` / `errorKey`: Resend's status describes OUR request
+to Resend (a 401 is a bad key, a 403 an unverified domain), not the caller's
+request to the app, so the API middleware must fall through to its generic
+500 rather than echo it.
+
+### Functions
+
+#### `getClient()`
+
+Returns the Resend HTTP client. Nothing is configured up front: the API key
+and base URL are read from the environment on every `send()`.
+
+```typescript
+function getClient(): ResendClient
+```
+
+**Returns:** The Resend client.
+
+#### `sendMail(message)`
+
+Sends an email through the Resend API.
+
+```typescript
+function sendMail(message: EmailMessage): Promise<EmailSendResult>
+```
+
+- `message` — The email message (to, from, subject, text/html, attachments).
+
+**Returns:** Send result with accepted addresses, message ID, and status code.
+
+### Constants
+
+#### `emailsResendSecretDefinitions`
+
+Secret definitions required by the Resend email bond.
+
+```typescript
+const emailsResendSecretDefinitions: SecretDefinition[]
+```
+
+#### `provider`
+
+The Resend email provider implementing the standard interface.
+
+```typescript
+const provider: EmailTransport
+```
+
+#### `RESEND_DEFAULT_BASE_URL`
+
+Resend's REST API base URL. Override with `RESEND_BASE_URL`.
+
+```typescript
+const RESEND_DEFAULT_BASE_URL: 'https://api.resend.com'
+```
+
+## Core Interface
+
+Implements `@molecule/api-emails` interface.
+
+## Bond Wiring
+
+Setup function to register this provider with the core interface:
+
+```typescript
+import { setTransport } from '@molecule/api-emails'
+import { provider } from '@molecule/api-emails-resend'
+
+export function setupEmailsResend(): void {
+  setTransport(provider)
+}
+```
+
+## Injection Notes
+
+### Requirements
+
+Peer dependencies:
+
+- `@molecule/api-bond` ^1.0.1
+- `@molecule/api-emails` ^1.0.1
+- `@molecule/api-secrets` ^1.0.1
+
+### Environment Variables
+
+- `RESEND_API_KEY` _(required)_ — Resend API key
+  - Setup: Resend → API Keys → Create API Key (Sending access). Verify your sending domain under Domains first.
+  - Get it here: [https://resend.com/api-keys](https://resend.com/api-keys)
+  - Example: `re_...`
+- `RESEND_FROM` _(optional)_ — Default sender
+  - Setup: Optional default From address on a verified domain, e.g. "Acme <hello@acme.com>".
+  - Get it here: [https://resend.com/domains](https://resend.com/domains)
+  - Example: `Acme <hello@example.com>`
+
+### Runtime Dependencies
+
+- `@molecule/api-bond`
+- `@molecule/api-emails`
+- `@molecule/api-secrets`
+
+- **Zero dependencies — talks to Resend's REST API with the runtime's global
+  `fetch`** (`POST https://api.resend.com/emails`), so every app that installs
+  this bond stays dependency-free; the official `resend` SDK can be swapped in
+  later without changing the bond's interface.
+- **`from` MUST be on a domain you VERIFIED in Resend** (Resend → Domains, DNS
+  records added and checked), or the API rejects the send with a 403
+  `validation_error` ("domain is not verified"). Before any domain is verified
+  the only usable sender is `onboarding@resend.dev` — testing only, and it can
+  deliver ONLY to the account owner's own address. Read the sender from config,
+  never hardcode a placeholder: set `RESEND_FROM` (e.g.
+  `Acme <no-reply@your-verified-domain.com>`) and it is used whenever a
+  message's `from` is empty; if both are missing, `sendMail()` throws a tagged
+  config-missing error naming `RESEND_FROM`.
+- **Configuration is lazy and env-driven**: `RESEND_API_KEY` (and the optional
+  `RESEND_BASE_URL` override for brokers / compatible endpoints) are read on
+  EACH send — never at import time — so a key resolved into `process.env`
+  after import (late secrets resolution via a secrets bond) is honored. If the
+  key is absent at send time, `sendMail()` throws a tagged config-missing
+  error (clean 503 / `config.notConfigured`) naming `RESEND_API_KEY` — never
+  an opaque Resend 401.
+- **There is NO sandbox / test-mode flag in the Resend API** (nothing like
+  SendGrid's `sandboxMode`). Every accepted request is a real send that counts
+  against the account's quota — including sends to the simulation recipients
+  `delivered@resend.dev`, `bounced@resend.dev` and `complained@resend.dev`,
+  which are the supported way to exercise the delivery / bounce / spam paths
+  without emailing a real inbox.
+- **Attachments** are sent base64-encoded inline; Resend caps the whole email
+  at **40 MB after encoding** (larger sends are rejected). Buffer / string
+  content only — a stream attachment throws. A `cid` becomes Resend's
+  `content_id` for inline images (`<img src="cid:...">`).
+- **API errors surface as `ResendApiError`** carrying `status` (HTTP) and
+  `code` (Resend's error name — `validation_error`, `rate_limit_exceeded`,
+  `daily_quota_exceeded`, …). They are deliberately NOT tagged with
+  `statusCode` / `errorKey`, so the API middleware returns its generic 500
+  instead of echoing Resend's status to the caller. On success `accepted`
+  echoes every `to` recipient (Resend returns no per-recipient verdict) and
+  `messageId` is the `id` from the response body.
+
+## E2E Tests
+
+Integration checklist — drive the real UI (live preview, no mocks). The
+sandbox CAPTURES outbound email instead of sending — read each message with
+the `read_activity` tool (filter type 'email'); the verification/reset link
+is in its payload. Never mock the send or modify production code to expose
+it. Adapt each item to this app's actual screens/flows, and check every box
+off one by one. A box you can't check is an integration bug to fix — not a
+skip:
+
+- [ ] Each email-triggering flow (signup verification, password-reset request,
+      invites/notifications the app defines) confirms the send in the UI ("check
+      your inbox") and a message actually reaches the transport.
+- [ ] The password-reset round-trip completes: request a reset → open the
+      captured message → follow its single-use link → set a new password → log
+      in with it (and the old password no longer works).
+- [ ] The message body contains a LINK, never the raw token/secret, and renders
+      with the app's real name/content (no `undefined` placeholders).
+- [ ] Requesting a reset for an unknown email shows the same neutral UI response
+      as a known one (no account-existence oracle).
+- [ ] Account emails go only to the account's own address — no UI or endpoint
+      lets an unauthenticated caller send to an arbitrary address.

package/dist/browser-guard.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=browser-guard.d.ts.map

package/dist/browser-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-guard.d.ts","sourceRoot":"","sources":["../src/browser-guard.ts"],"names":[],"mappings":"AAuBA,OAAO,EAAE,CAAA"}

package/dist/browser-guard.js

@@ -0,0 +1,19 @@
+/**
+ * Browser guard — `@molecule/api-emails-resend` is SERVER-ONLY.
+ *
+ * Generated by scripts/gen-browser-guards.mjs (workspace root) — edit THAT, not this.
+ * Evaluating a server package in a browser bundle is always an import-graph mistake
+ * (node APIs, secrets); without this guard it surfaces as a cryptic downstream crash
+ * ("Buffer is not defined") far from the culprit. Throwing here names the package and
+ * the fix at the exact moment the client bundle evaluates it. jsdom tests and SSR are
+ * unaffected: the throw requires browser globals AND the absence of a node runtime.
+ */
+const g = globalThis;
+if (g.window !== undefined && g.document !== undefined && !g.process?.versions?.node) {
+    throw new Error('@molecule/api-emails-resend is SERVER-ONLY: it was bundled into browser/client code. Import it only ' +
+        'from server code (a server route/function or your API), or dynamic-import it inside ' +
+        'the server handler — never from components or shared client modules, and never ' +
+        'polyfill Buffer/process to silence this.');
+}
+export {};
+//# sourceMappingURL=browser-guard.js.map

package/dist/browser-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-guard.js","sourceRoot":"","sources":["../src/browser-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,CAAC,GAAG,UAIT,CAAA;AACD,IAAI,CAAC,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,CAAC,QAAQ,KAAK,SAAS,IAAI,CAAC,CAAC,CAAC,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IACrF,MAAM,IAAI,KAAK,CACb,sGAAsG;QACpG,sFAAsF;QACtF,iFAAiF;QACjF,0CAA0C,CAC7C,CAAA;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Resend email provider for molecule.dev.
+ *
+ * @see https://resend.com/docs/api-reference/emails/send-email
+ *
+ * @remarks
+ * - **Zero dependencies — talks to Resend's REST API with the runtime's global
+ *   `fetch`** (`POST https://api.resend.com/emails`), so every app that installs
+ *   this bond stays dependency-free; the official `resend` SDK can be swapped in
+ *   later without changing the bond's interface.
+ * - **`from` MUST be on a domain you VERIFIED in Resend** (Resend → Domains, DNS
+ *   records added and checked), or the API rejects the send with a 403
+ *   `validation_error` ("domain is not verified"). Before any domain is verified
+ *   the only usable sender is `onboarding@resend.dev` — testing only, and it can
+ *   deliver ONLY to the account owner's own address. Read the sender from config,
+ *   never hardcode a placeholder: set `RESEND_FROM` (e.g.
+ *   `Acme <no-reply@your-verified-domain.com>`) and it is used whenever a
+ *   message's `from` is empty; if both are missing, `sendMail()` throws a tagged
+ *   config-missing error naming `RESEND_FROM`.
+ * - **Configuration is lazy and env-driven**: `RESEND_API_KEY` (and the optional
+ *   `RESEND_BASE_URL` override for brokers / compatible endpoints) are read on
+ *   EACH send — never at import time — so a key resolved into `process.env`
+ *   after import (late secrets resolution via a secrets bond) is honored. If the
+ *   key is absent at send time, `sendMail()` throws a tagged config-missing
+ *   error (clean 503 / `config.notConfigured`) naming `RESEND_API_KEY` — never
+ *   an opaque Resend 401.
+ * - **There is NO sandbox / test-mode flag in the Resend API** (nothing like
+ *   SendGrid's `sandboxMode`). Every accepted request is a real send that counts
+ *   against the account's quota — including sends to the simulation recipients
+ *   `delivered@resend.dev`, `bounced@resend.dev` and `complained@resend.dev`,
+ *   which are the supported way to exercise the delivery / bounce / spam paths
+ *   without emailing a real inbox.
+ * - **Attachments** are sent base64-encoded inline; Resend caps the whole email
+ *   at **40 MB after encoding** (larger sends are rejected). Buffer / string
+ *   content only — a stream attachment throws. A `cid` becomes Resend's
+ *   `content_id` for inline images (`<img src="cid:...">`).
+ * - **API errors surface as `ResendApiError`** carrying `status` (HTTP) and
+ *   `code` (Resend's error name — `validation_error`, `rate_limit_exceeded`,
+ *   `daily_quota_exceeded`, …). They are deliberately NOT tagged with
+ *   `statusCode` / `errorKey`, so the API middleware returns its generic 500
+ *   instead of echoing Resend's status to the caller. On success `accepted`
+ *   echoes every `to` recipient (Resend returns no per-recipient verdict) and
+ *   `messageId` is the `id` from the response body.
+ *
+ * @example
+ * ```typescript
+ * import { setTransport } from '@molecule/api-emails'
+ * import { provider } from '@molecule/api-emails-resend'
+ *
+ * setTransport(provider)
+ * ```
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './provider.js';
+export * from './secrets.js';
+export * from './sendMail.js';
+export * from './transport.js';
+export * from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,cAAc,eAAe,CAAA;AAC7B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,61 @@
+/**
+ * Resend email provider for molecule.dev.
+ *
+ * @see https://resend.com/docs/api-reference/emails/send-email
+ *
+ * @remarks
+ * - **Zero dependencies — talks to Resend's REST API with the runtime's global
+ *   `fetch`** (`POST https://api.resend.com/emails`), so every app that installs
+ *   this bond stays dependency-free; the official `resend` SDK can be swapped in
+ *   later without changing the bond's interface.
+ * - **`from` MUST be on a domain you VERIFIED in Resend** (Resend → Domains, DNS
+ *   records added and checked), or the API rejects the send with a 403
+ *   `validation_error` ("domain is not verified"). Before any domain is verified
+ *   the only usable sender is `onboarding@resend.dev` — testing only, and it can
+ *   deliver ONLY to the account owner's own address. Read the sender from config,
+ *   never hardcode a placeholder: set `RESEND_FROM` (e.g.
+ *   `Acme <no-reply@your-verified-domain.com>`) and it is used whenever a
+ *   message's `from` is empty; if both are missing, `sendMail()` throws a tagged
+ *   config-missing error naming `RESEND_FROM`.
+ * - **Configuration is lazy and env-driven**: `RESEND_API_KEY` (and the optional
+ *   `RESEND_BASE_URL` override for brokers / compatible endpoints) are read on
+ *   EACH send — never at import time — so a key resolved into `process.env`
+ *   after import (late secrets resolution via a secrets bond) is honored. If the
+ *   key is absent at send time, `sendMail()` throws a tagged config-missing
+ *   error (clean 503 / `config.notConfigured`) naming `RESEND_API_KEY` — never
+ *   an opaque Resend 401.
+ * - **There is NO sandbox / test-mode flag in the Resend API** (nothing like
+ *   SendGrid's `sandboxMode`). Every accepted request is a real send that counts
+ *   against the account's quota — including sends to the simulation recipients
+ *   `delivered@resend.dev`, `bounced@resend.dev` and `complained@resend.dev`,
+ *   which are the supported way to exercise the delivery / bounce / spam paths
+ *   without emailing a real inbox.
+ * - **Attachments** are sent base64-encoded inline; Resend caps the whole email
+ *   at **40 MB after encoding** (larger sends are rejected). Buffer / string
+ *   content only — a stream attachment throws. A `cid` becomes Resend's
+ *   `content_id` for inline images (`<img src="cid:...">`).
+ * - **API errors surface as `ResendApiError`** carrying `status` (HTTP) and
+ *   `code` (Resend's error name — `validation_error`, `rate_limit_exceeded`,
+ *   `daily_quota_exceeded`, …). They are deliberately NOT tagged with
+ *   `statusCode` / `errorKey`, so the API middleware returns its generic 500
+ *   instead of echoing Resend's status to the caller. On success `accepted`
+ *   echoes every `to` recipient (Resend returns no per-recipient verdict) and
+ *   `messageId` is the `id` from the response body.
+ *
+ * @example
+ * ```typescript
+ * import { setTransport } from '@molecule/api-emails'
+ * import { provider } from '@molecule/api-emails-resend'
+ *
+ * setTransport(provider)
+ * ```
+ *
+ * @module
+ */
+export * from './browser-guard.js';
+export * from './provider.js';
+export * from './secrets.js';
+export * from './sendMail.js';
+export * from './transport.js';
+export * from './types.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH,cAAc,oBAAoB,CAAA;AAClC,cAAc,eAAe,CAAA;AAC7B,cAAc,cAAc,CAAA;AAC5B,cAAc,eAAe,CAAA;AAC7B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,YAAY,CAAA"}

package/dist/provider.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Resend provider implementation.
+ *
+ * @module
+ */
+import type { EmailTransport } from '@molecule/api-emails';
+/**
+ * The Resend email provider implementing the standard interface.
+ */
+export declare const provider: EmailTransport;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAI1D;;GAEG;AACH,eAAO,MAAM,QAAQ,EAAE,cAEtB,CAAA"}

package/dist/provider.js

@@ -0,0 +1,13 @@
+/**
+ * Resend provider implementation.
+ *
+ * @module
+ */
+import { sendMail } from './sendMail.js';
+/**
+ * The Resend email provider implementing the standard interface.
+ */
+export const provider = {
+    sendMail,
+};
+//# sourceMappingURL=provider.js.map

package/dist/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAExC;;GAEG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAmB;IACtC,QAAQ;CACT,CAAA"}

package/dist/secrets.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Resend secret definitions — self-registered at import time so the
+ * runtime secrets registry (`@molecule/api-secrets`) can drive boot-time
+ * configuration reports and actionable "not configured" errors.
+ *
+ * Content is derived MECHANICALLY from this package's mlcl registry secrets
+ * entry (label/instructions/setupUrl/example) via the fleet formula, so
+ * packages sharing a key register byte-identical definitions and
+ * registration order never matters.
+ *
+ * @module
+ */
+import type { SecretDefinition } from '@molecule/api-secrets';
+/** Secret definitions required by the Resend email bond. */
+export declare const emailsResendSecretDefinitions: SecretDefinition[];
+//# sourceMappingURL=secrets.d.ts.map

package/dist/secrets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.d.ts","sourceRoot":"","sources":["../src/secrets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAG7D,4DAA4D;AAC5D,eAAO,MAAM,6BAA6B,EAAE,gBAAgB,EAgB3D,CAAA"}

package/dist/secrets.js

@@ -0,0 +1,32 @@
+/**
+ * Resend secret definitions — self-registered at import time so the
+ * runtime secrets registry (`@molecule/api-secrets`) can drive boot-time
+ * configuration reports and actionable "not configured" errors.
+ *
+ * Content is derived MECHANICALLY from this package's mlcl registry secrets
+ * entry (label/instructions/setupUrl/example) via the fleet formula, so
+ * packages sharing a key register byte-identical definitions and
+ * registration order never matters.
+ *
+ * @module
+ */
+import { registerSecrets } from '@molecule/api-secrets';
+/** Secret definitions required by the Resend email bond. */
+export const emailsResendSecretDefinitions = [
+    {
+        key: 'RESEND_API_KEY',
+        description: 'Resend API key — Resend → API Keys → Create API Key (Sending access is enough).',
+        helpUrl: 'https://resend.com/api-keys',
+        required: true,
+        example: 're_....',
+    },
+    {
+        key: 'RESEND_FROM',
+        description: 'Resend default sender — Optional. A from address on a domain verified in Resend → Domains; used when a message has no from address.',
+        helpUrl: 'https://resend.com/domains',
+        required: false,
+        example: 'Acme <no-reply@example.com>',
+    },
+];
+registerSecrets(emailsResendSecretDefinitions);
+//# sourceMappingURL=secrets.js.map

package/dist/secrets.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secrets.js","sourceRoot":"","sources":["../src/secrets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAEvD,4DAA4D;AAC5D,MAAM,CAAC,MAAM,6BAA6B,GAAuB;IAC/D;QACE,GAAG,EAAE,gBAAgB;QACrB,WAAW,EAAE,iFAAiF;QAC9F,OAAO,EAAE,6BAA6B;QACtC,QAAQ,EAAE,IAAI;QACd,OAAO,EAAE,SAAS;KACnB;IACD;QACE,GAAG,EAAE,aAAa;QAClB,WAAW,EACT,qIAAqI;QACvI,OAAO,EAAE,4BAA4B;QACrC,QAAQ,EAAE,KAAK;QACf,OAAO,EAAE,6BAA6B;KACvC;CACF,CAAA;AAED,eAAe,CAAC,6BAA6B,CAAC,CAAA"}

package/dist/sendMail.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Resend email sending functionality.
+ *
+ * @module
+ */
+import type { EmailMessage, EmailSendResult } from '@molecule/api-emails';
+/**
+ * Sends an email through the Resend API.
+ *
+ * @param message - The email message (to, from, subject, text/html, attachments).
+ * @returns Send result with accepted addresses, message ID, and status code.
+ */
+export declare const sendMail: (message: EmailMessage) => Promise<EmailSendResult>;
+//# sourceMappingURL=sendMail.d.ts.map

package/dist/sendMail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sendMail.d.ts","sourceRoot":"","sources":["../src/sendMail.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAGV,YAAY,EACZ,eAAe,EAChB,MAAM,sBAAsB,CAAA;AAgG7B;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,GAAU,SAAS,YAAY,KAAG,OAAO,CAAC,eAAe,CA0C7E,CAAA"}

package/dist/sendMail.js

@@ -0,0 +1,143 @@
+/**
+ * Resend email sending functionality.
+ *
+ * @module
+ */
+import { getLogger } from '@molecule/api-bond';
+import { configNotConfiguredError } from '@molecule/api-secrets';
+import { getClient } from './transport.js';
+const logger = getLogger();
+/** Display-name characters RFC 5322 allows unquoted (atext plus space). */
+const UNQUOTED_NAME = /^[A-Za-z0-9 !#$%&'*+\-/=?^_`{|}~.]*$/;
+/**
+ * Format one address the way Resend expects: a bare address, or
+ * `Name <address>`. The display name is quoted when it holds characters that
+ * would otherwise parse as address syntax (`,`, `<`, `"`, non-ASCII), and any
+ * CR/LF in it is collapsed so a display name can never inject a header.
+ * @param addr - A string email address or an `EmailAddress` object with name and address.
+ * @returns The address string for the request body.
+ */
+function formatAddress(addr) {
+    if (typeof addr === 'string')
+        return addr;
+    const name = addr.name?.replace(/[\r\n]+/g, ' ').trim();
+    if (!name)
+        return addr.address;
+    const display = UNQUOTED_NAME.test(name) ? name : `"${name.replace(/(["\\])/g, '\\$1')}"`;
+    return `${display} <${addr.address}>`;
+}
+/**
+ * Normalize a recipient field (single or array) to Resend's list of address strings.
+ * @param field - A single address or array of addresses (string or `EmailAddress`).
+ * @returns The formatted address strings.
+ */
+function toList(field) {
+    return (Array.isArray(field) ? field : [field]).map(formatAddress);
+}
+/**
+ * Extract plain email strings from a recipient field.
+ * @param field - A single address or array of addresses (string or `EmailAddress`).
+ * @returns An array of plain email strings.
+ */
+function extractEmails(field) {
+    return (Array.isArray(field) ? field : [field]).map((a) => typeof a === 'string' ? a : a.address);
+}
+/**
+ * Resolve the sender: the message's own `from` when it names an address,
+ * otherwise the `RESEND_FROM` default. Neither → a tagged config-missing error,
+ * because Resend refuses a send whose `from` is not on a verified domain and
+ * the fix is configuration, not code.
+ * @param from - The message's `from` field.
+ * @returns The sender string for the request body.
+ * @throws {Error} A tagged config-missing error (503 / `config.notConfigured`) naming `RESEND_FROM`.
+ */
+function resolveFrom(from) {
+    if (from !== undefined) {
+        const address = typeof from === 'string' ? from : from.address;
+        if (address.trim())
+            return formatAddress(from);
+    }
+    const fallback = process.env.RESEND_FROM?.trim();
+    if (fallback)
+        return fallback;
+    throw configNotConfiguredError('RESEND_FROM', 'email sending');
+}
+/**
+ * Convert molecule attachments to Resend's attachment format (base64 content).
+ * @param attachments - The molecule email attachments to convert.
+ * @returns The Resend-format attachments.
+ * @throws {Error} When an attachment's content is a stream.
+ */
+function toResendAttachments(attachments) {
+    return attachments.map((att) => {
+        let content;
+        if (Buffer.isBuffer(att.content)) {
+            content = att.content.toString('base64');
+        }
+        else if (typeof att.content === 'string') {
+            const encoding = att.encoding && Buffer.isEncoding(att.encoding) ? att.encoding : 'utf-8';
+            content = Buffer.from(att.content, encoding).toString('base64');
+        }
+        else {
+            throw new Error('Stream attachments are not supported by the Resend provider');
+        }
+        return {
+            content,
+            filename: att.filename,
+            ...(att.contentType ? { content_type: att.contentType } : {}),
+            ...(att.cid ? { content_id: att.cid } : {}),
+        };
+    });
+}
+/**
+ * Sends an email through the Resend API.
+ *
+ * @param message - The email message (to, from, subject, text/html, attachments).
+ * @returns Send result with accepted addresses, message ID, and status code.
+ */
+export const sendMail = async (message) => {
+    if (!process.env.RESEND_API_KEY) {
+        // Tagged config-missing error → the API middleware returns a clean 503 +
+        // 'config.notConfigured', and the message carries the registered
+        // definition's description + setup URL. Without this guard the request
+        // would go out unauthenticated and the caller would get an opaque Resend
+        // 401 that reads like a bad key rather than a missing one.
+        throw configNotConfiguredError('RESEND_API_KEY', 'email sending');
+    }
+    // Also outside the try: a missing sender is a config condition to surface
+    // as-is, not an error to log.
+    const from = resolveFrom(message.from);
+    try {
+        const request = {
+            from,
+            to: toList(message.to),
+            subject: message.subject,
+            ...(message.text ? { text: message.text } : {}),
+            ...(message.html ? { html: message.html } : {}),
+        };
+        const cc = message.cc ? toList(message.cc) : [];
+        if (cc.length)
+            request.cc = cc;
+        const bcc = message.bcc ? toList(message.bcc) : [];
+        if (bcc.length)
+            request.bcc = bcc;
+        if (message.replyTo)
+            request.reply_to = formatAddress(message.replyTo);
+        if (message.attachments?.length)
+            request.attachments = toResendAttachments(message.attachments);
+        // The client reads the API key / base URL from the environment on each
+        // send (honors late-resolved secrets).
+        const { status, id } = await getClient().send(request);
+        return {
+            accepted: extractEmails(message.to),
+            rejected: [],
+            messageId: id,
+            response: String(status),
+        };
+    }
+    catch (error) {
+        logger.error('Resend sendMail error:', error);
+        throw error;
+    }
+};
+//# sourceMappingURL=sendMail.js.map

package/dist/sendMail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sendMail.js","sourceRoot":"","sources":["../src/sendMail.ts"],"names":[],"mappings":"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"}

package/dist/transport.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Resend HTTP client — a thin `fetch` wrapper around `POST /emails`.
+ *
+ * @module
+ */
+import './secrets.js';
+import type { ResendClient, ResendErrorBody } from './types.js';
+/** Resend's REST API base URL. Override with `RESEND_BASE_URL`. */
+export declare const RESEND_DEFAULT_BASE_URL = "https://api.resend.com";
+/**
+ * A non-2xx response from the Resend API.
+ *
+ * `status` is the HTTP status, `code` is Resend's machine-readable error `name`
+ * (e.g. `validation_error`, `rate_limit_exceeded`, `daily_quota_exceeded`) when
+ * the body carried one, and `body` is the parsed error body. Deliberately NOT
+ * tagged with `statusCode` / `errorKey`: Resend's status describes OUR request
+ * to Resend (a 401 is a bad key, a 403 an unverified domain), not the caller's
+ * request to the app, so the API middleware must fall through to its generic
+ * 500 rather than echo it.
+ */
+export declare class ResendApiError extends Error {
+    /** HTTP status of the Resend response. */
+    readonly status: number;
+    /** Resend's error name from the body, when present. */
+    readonly code: string | undefined;
+    /** The parsed error body, when the response was JSON. */
+    readonly body: ResendErrorBody | undefined;
+    /**
+     * Builds the error from a non-2xx Resend response.
+     * @param status - HTTP status of the response.
+     * @param body - The parsed error body, if the response was JSON.
+     * @param rawBody - The raw response text (used in the message when the body was not JSON).
+     */
+    constructor(status: number, body: ResendErrorBody | undefined, rawBody: string);
+}
+/**
+ * Returns the Resend HTTP client. Nothing is configured up front: the API key
+ * and base URL are read from the environment on every `send()`.
+ *
+ * @returns The Resend client.
+ */
+export declare const getClient: () => ResendClient;
+//# sourceMappingURL=transport.d.ts.map

package/dist/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,cAAc,CAAA;AAIrB,OAAO,KAAK,EACV,YAAY,EACZ,eAAe,EAGhB,MAAM,YAAY,CAAA;AAEnB,mEAAmE;AACnE,eAAO,MAAM,uBAAuB,2BAA2B,CAAA;AAE/D;;;;;;;;;;GAUG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,0CAA0C;IAC1C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,uDAAuD;IACvD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;IACjC,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,eAAe,GAAG,SAAS,CAAA;IAE1C;;;;;OAKG;gBACS,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM;CAQ/E;AAsFD;;;;;GAKG;AACH,eAAO,MAAM,SAAS,QAAO,YAAsB,CAAA"}

package/dist/transport.js

@@ -0,0 +1,129 @@
+/**
+ * Resend HTTP client — a thin `fetch` wrapper around `POST /emails`.
+ *
+ * @module
+ */
+// Side-effect import: registers this bond's secret definitions so the
+// runtime registry is populated even when transport.js is imported directly
+// (not through the package barrel).
+import './secrets.js';
+import { configNotConfiguredError } from '@molecule/api-secrets';
+/** Resend's REST API base URL. Override with `RESEND_BASE_URL`. */
+export const RESEND_DEFAULT_BASE_URL = 'https://api.resend.com';
+/**
+ * A non-2xx response from the Resend API.
+ *
+ * `status` is the HTTP status, `code` is Resend's machine-readable error `name`
+ * (e.g. `validation_error`, `rate_limit_exceeded`, `daily_quota_exceeded`) when
+ * the body carried one, and `body` is the parsed error body. Deliberately NOT
+ * tagged with `statusCode` / `errorKey`: Resend's status describes OUR request
+ * to Resend (a 401 is a bad key, a 403 an unverified domain), not the caller's
+ * request to the app, so the API middleware must fall through to its generic
+ * 500 rather than echo it.
+ */
+export class ResendApiError extends Error {
+    /** HTTP status of the Resend response. */
+    status;
+    /** Resend's error name from the body, when present. */
+    code;
+    /** The parsed error body, when the response was JSON. */
+    body;
+    /**
+     * Builds the error from a non-2xx Resend response.
+     * @param status - HTTP status of the response.
+     * @param body - The parsed error body, if the response was JSON.
+     * @param rawBody - The raw response text (used in the message when the body was not JSON).
+     */
+    constructor(status, body, rawBody) {
+        const detail = body?.message ?? (rawBody.trim() || 'no response body');
+        super(`Resend API error ${status}${body?.name ? ` (${body.name})` : ''}: ${detail}`);
+        this.name = 'ResendApiError';
+        this.status = status;
+        this.code = body?.name;
+        this.body = body;
+    }
+}
+/**
+ * Whether a value is a non-null object (a JSON object on the wire).
+ * @param value - The parsed value.
+ * @returns `true` for a plain object.
+ */
+const isRecord = (value) => typeof value === 'object' && value !== null;
+/**
+ * Parses a response body as JSON, tolerating an empty or non-JSON body.
+ * @param text - The raw response text.
+ * @returns The parsed value, or `undefined` when the body is empty or not JSON.
+ */
+const parseJson = (text) => {
+    if (!text)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch (_error) {
+        // Intentional: a non-JSON body (an HTML gateway page, plain text) is
+        // reported by the caller via the raw text, so there is nothing to log here.
+        return undefined;
+    }
+};
+/**
+ * Narrows a parsed error response to Resend's `{ statusCode, message, name }` shape.
+ * @param parsed - The parsed response body.
+ * @returns The error body, or `undefined` when the body was not a JSON object.
+ */
+const toErrorBody = (parsed) => {
+    if (!isRecord(parsed))
+        return undefined;
+    return {
+        statusCode: typeof parsed.statusCode === 'number' ? parsed.statusCode : null,
+        message: typeof parsed.message === 'string' ? parsed.message : undefined,
+        name: typeof parsed.name === 'string' ? parsed.name : undefined,
+    };
+};
+/**
+ * Resolves the API base URL from the environment on each call (late secrets
+ * resolution is honored), trimming any trailing slash.
+ * @returns The base URL without a trailing slash.
+ */
+const resolveBaseUrl = () => (process.env.RESEND_BASE_URL || RESEND_DEFAULT_BASE_URL).replace(/\/+$/, '');
+/**
+ * The shared client. Environment is read INSIDE `send()` — never at import
+ * time — so a `RESEND_API_KEY` / `RESEND_BASE_URL` resolved into `process.env`
+ * after this module is imported (a secrets bond resolving at startup) is the
+ * value used on the next send.
+ */
+const client = {
+    async send(request) {
+        const apiKey = process.env.RESEND_API_KEY;
+        if (!apiKey) {
+            // Tagged config-missing error → clean 503 + 'config.notConfigured'
+            // instead of an opaque Resend 401 from an unauthenticated request.
+            throw configNotConfiguredError('RESEND_API_KEY', 'email sending');
+        }
+        const response = await fetch(`${resolveBaseUrl()}/emails`, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${apiKey}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(request),
+        });
+        const text = await response.text();
+        const parsed = parseJson(text);
+        if (!response.ok) {
+            throw new ResendApiError(response.status, toErrorBody(parsed), text);
+        }
+        return {
+            status: response.status,
+            id: isRecord(parsed) && typeof parsed.id === 'string' ? parsed.id : undefined,
+        };
+    },
+};
+/**
+ * Returns the Resend HTTP client. Nothing is configured up front: the API key
+ * and base URL are read from the environment on every `send()`.
+ *
+ * @returns The Resend client.
+ */
+export const getClient = () => client;
+//# sourceMappingURL=transport.js.map

package/dist/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Type definitions for the Resend email provider.
+ *
+ * @module
+ */
+export type { EmailMessage, EmailSendResult, EmailTransport } from '@molecule/api-emails';
+/**
+ * One entry of a send request's `attachments[]`, exactly as the Resend REST API
+ * expects it: base64 `content` plus snake_case metadata.
+ */
+export interface ResendAttachment {
+    /** File content, base64-encoded. */
+    content: string;
+    /** File name shown to the recipient; Resend derives the MIME type from it when `content_type` is unset. */
+    filename: string;
+    /** MIME type of the file. */
+    content_type?: string;
+    /** Content-ID for an inline image referenced as `cid:` in the HTML body. */
+    content_id?: string;
+}
+/**
+ * Request body for `POST /emails`. Field names are the REST API's own
+ * (snake_case, e.g. `reply_to`) — NOT the camelCase the official SDK accepts.
+ */
+export interface ResendSendRequest {
+    /** Sender, as a bare address or `Name <address>`. */
+    from: string;
+    /** Recipients (Resend accepts at most 50). */
+    to: string[];
+    /** Subject line. */
+    subject: string;
+    /** CC recipients. */
+    cc?: string[];
+    /** BCC recipients. */
+    bcc?: string[];
+    /** Reply-To address. */
+    reply_to?: string;
+    /** HTML body. */
+    html?: string;
+    /** Plain-text body (Resend derives one from `html` when omitted). */
+    text?: string;
+    /** File attachments. */
+    attachments?: ResendAttachment[];
+}
+/**
+ * What {@link ResendClient.send} resolves with: the HTTP status of the accepted
+ * request and the message `id` Resend returned in the response body.
+ */
+export interface ResendSendResponse {
+    /** HTTP status code of the response (2xx). */
+    status: number;
+    /** The `id` from the response body, when present. */
+    id?: string;
+}
+/**
+ * Resend's JSON error body (`{ statusCode, message, name }`), with every field
+ * optional because the wire is not trusted.
+ */
+export interface ResendErrorBody {
+    /** HTTP status Resend reports in the body (may be `null`). */
+    statusCode?: number | null;
+    /** Human-readable error message. */
+    message?: string;
+    /** Machine-readable error name, e.g. `validation_error`, `daily_quota_exceeded`. */
+    name?: string;
+}
+/**
+ * The narrow HTTP client this bond uses to reach Resend.
+ */
+export interface ResendClient {
+    /**
+     * Sends one email via `POST /emails`.
+     * @returns The HTTP status and the message id.
+     */
+    send(request: ResendSendRequest): Promise<ResendSendResponse>;
+}
+declare global {
+    namespace NodeJS {
+        /**
+         * Process Env interface.
+         */
+        interface ProcessEnv {
+            /**
+             * The key used for Resend's API.
+             */
+            RESEND_API_KEY?: string;
+            /**
+             * Optional default sender (`Name <address>` or a bare address on a
+             * domain verified in Resend), used when a message's `from` is empty.
+             */
+            RESEND_FROM?: string;
+            /**
+             * Optional base URL override for the Resend API (e.g. a credential
+             * broker or a Resend-compatible endpoint). When unset, the API's
+             * default `https://api.resend.com` is used.
+             */
+            RESEND_BASE_URL?: string;
+        }
+    }
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAEzF;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAA;IACf,2GAA2G;IAC3G,QAAQ,EAAE,MAAM,CAAA;IAChB,6BAA6B;IAC7B,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,4EAA4E;IAC5E,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAA;IACZ,8CAA8C;IAC9C,EAAE,EAAE,MAAM,EAAE,CAAA;IACZ,oBAAoB;IACpB,OAAO,EAAE,MAAM,CAAA;IACf,qBAAqB;IACrB,EAAE,CAAC,EAAE,MAAM,EAAE,CAAA;IACb,sBAAsB;IACtB,GAAG,CAAC,EAAE,MAAM,EAAE,CAAA;IACd,wBAAwB;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,iBAAiB;IACjB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,qEAAqE;IACrE,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,wBAAwB;IACxB,WAAW,CAAC,EAAE,gBAAgB,EAAE,CAAA;CACjC;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAA;IACd,qDAAqD;IACrD,EAAE,CAAC,EAAE,MAAM,CAAA;CACZ;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,8DAA8D;IAC9D,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,oCAAoC;IACpC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,oFAAoF;IACpF,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,IAAI,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAA;CAC9D;AAED,OAAO,CAAC,MAAM,CAAC;IAEb,UAAU,MAAM,CAAC;QACf;;WAEG;QACH,UAAiB,UAAU;YACzB;;eAEG;YACH,cAAc,CAAC,EAAE,MAAM,CAAA;YAEvB;;;eAGG;YACH,WAAW,CAAC,EAAE,MAAM,CAAA;YAEpB;;;;eAIG;YACH,eAAe,CAAC,EAAE,MAAM,CAAA;SACzB;KACF;CACF"}

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * Type definitions for the Resend email provider.
+ *
+ * @module
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@molecule/api-emails-resend",
+  "version": "1.0.0",
+  "description": "Resend email provider for molecule.dev.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "molecule",
+    "email",
+    "resend"
+  ],
+  "license": "Apache-2.0",
+  "author": "Molecule Dev, Inc. (https://molecule.dev)",
+  "devDependencies": {
+    "@molecule/api-bond": "1.0.1",
+    "@types/node": "26.1.2",
+    "typescript": "6.0.3",
+    "vitest": "4.1.10"
+  },
+  "peerDependencies": {
+    "@molecule/api-bond": "^1.0.1",
+    "@molecule/api-emails": "^1.0.1",
+    "@molecule/api-secrets": "^1.0.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/molecule-dev/molecule.git",
+    "directory": "packages/api/bonds/emails/resend"
+  },
+  "homepage": "https://github.com/molecule-dev/molecule/tree/main/packages/api/bonds/emails/resend",
+  "bugs": "https://github.com/molecule-dev/molecule/issues",
+  "publishConfig": {
+    "access": "public"
+  }
+}