@molecule/api-emails-sendmail 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,266 @@
+<!--
+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-08-04T01:48:04.838Z
+-->
+
+# @molecule/api-emails-sendmail
+
+> **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.
+
+Sendmail email provider for molecule.dev.
+
+Uses the local sendmail command to send emails.
+
+Note: For this to work, your server must have `sendmail` installed and
+configured. The binary path defaults to `/usr/sbin/sendmail`; set the
+`SENDMAIL_PATH` environment variable to use a different binary (e.g.
+`/usr/lib/sendmail`, or an msmtp/mhsendmail shim in containers). The path
+is read once at module load.
+
+## Type
+
+`provider`
+
+## Installation
+
+```bash
+npm install @molecule/api-emails-sendmail @molecule/api-bond @molecule/api-emails nodemailer
+npm install -D @types/nodemailer
+```
+
+## 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>
+}
+```
+
+### Functions
+
+#### `sendMail(message)`
+
+Sends an email using the local sendmail binary via nodemailer.
+
+```typescript
+function sendMail(message: EmailMessage): Promise<EmailSendResult>
+```
+
+- `message` — The email message (to, from, subject, text/html, attachments).
+
+**Returns:** Send result with accepted/rejected addresses and message ID.
+
+### Constants
+
+#### `email` _(deprecated)_
+
+Legacy export - the raw nodemailer transport.
+
+```typescript
+const email: nodemailer.Transporter<SentMessageInfo, Options>
+```
+
+#### `nodemailerTransport`
+
+The underlying nodemailer transport.
+
+The sendmail binary path defaults to `/usr/sbin/sendmail` and can be
+overridden with the `SENDMAIL_PATH` environment variable (e.g.
+`/usr/lib/sendmail`, or an msmtp/mhsendmail shim in containers and tests).
+The path is read once at module load; if the binary is missing, sends fail
+with a `spawn ... ENOENT` error at send time — install sendmail or point
+`SENDMAIL_PATH` at a compatible binary.
+
+```typescript
+const nodemailerTransport: nodemailer.Transporter<SentMessageInfo, Options>
+```
+
+#### `provider`
+
+The sendmail email provider implementing the standard interface.
+
+```typescript
+const provider: EmailTransport
+```
+
+#### `transport` _(deprecated)_
+
+Legacy export - the raw nodemailer transport.
+
+```typescript
+const transport: nodemailer.Transporter<SentMessageInfo, Options>
+```
+
+## 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-sendmail'
+
+export function setupEmailsSendmail(): void {
+  setTransport(provider)
+}
+```
+
+## Injection Notes
+
+### Requirements
+
+Peer dependencies:
+
+- `@molecule/api-bond` ^1.0.1
+- `@molecule/api-emails` ^1.0.1
+
+### Runtime Dependencies
+
+- `@molecule/api-bond`
+- `@molecule/api-emails`
+- `nodemailer`
+
+On success, `sendMail()` resolves with `accepted` set to the envelope
+recipients (sendmail queues the message for all of them once the binary
+exits 0) and `response: 'Messages queued for delivery'`. Failures reject
+with distinct errors: a missing binary is a `spawn ... ENOENT` error
+(install sendmail or set `SENDMAIL_PATH`), a binary that exits non-zero is
+`Sendmail exited with code <n>`, and an envelope address starting with `-`
+is rejected up front with `Invalid envelope addresses.` (argument-injection
+guard) — inspect the message/`code` to tell configuration problems apart
+from delivery problems.
+
+The `accepted`-from-envelope mapping above exists because `@types/nodemailer`
+declares `accepted`/`rejected`/`pending` on `SendmailTransport.SentMessageInfo`
+(and `SESTransport.SentMessageInfo`), but nodemailer's actual sendmail (and
+SES) transports never set them — only the SMTP transports do. Code written
+against the typings type-checks cleanly and reads `undefined`/`[]` at
+runtime. If you upgrade `nodemailer` or `@types/nodemailer`, re-verify this
+against the transport implementations themselves
+(`lib/sendmail-transport/index.js`), not the shipped `.d.ts` — the typings
+are exactly what drifted last time.
+
+## 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@molecule/api-emails-sendmail",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Sendmail email provider for molecule.dev.",
   "type": "module",
   "main": "dist/index.js",
@@ -17,7 +17,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "keywords": [
     "molecule",
@@ -30,15 +31,15 @@
     "nodemailer": "9.0.3"
   },
   "devDependencies": {
-    "@molecule/api-bond": "1.0.0",
+    "@molecule/api-bond": "1.0.1",
     "@types/node": "26.1.2",
     "@types/nodemailer": "8.0.1",
     "typescript": "6.0.3",
     "vitest": "4.1.10"
   },
   "peerDependencies": {
-    "@molecule/api-bond": "^1.0.0",
-    "@molecule/api-emails": "^1.0.0"
+    "@molecule/api-bond": "^1.0.1",
+    "@molecule/api-emails": "^1.0.1"
   },
   "repository": {
     "type": "git",