@t4h.framework/smtp 0.7.6 → 0.7.9

package/.ai/skills/framework-smtp/SKILL.md

@@ -1,283 +1,104 @@
 ---
 name: framework-smtp
 description: >-
-  Guides correct use of @t4h.framework/smtp in T4H Framework workflows: SMTP
-  send-email activity (SmtpSendEmailActivity), SmtpSendEmailClaim, reconciler-bound
-  Smtp client, recipients/cc/bcc normalization, HTML bodies, Binary attachments,
-  and SmtpSendEmailOutput. Use when sending email from workflows, wiring SMTP
-  claim providers, testing email activities, implementing SmtpSendEmailClaim,
-  or working in packages/smtp.
+  Guides the use of @t4h.framework/smtp to send email from a T4H Framework
+  workflow: the Smtp client and its send() method, the default from, to/cc/bcc
+  recipients, HTML bodies, Binary attachments, SmtpSendEmailOutput.messageId,
+  and how to test with TestWorkflowEnvironment and mockClaim of
+  SmtpSendEmailClaim. Use when a workflow must send an email, a notification
+  or a report with an attachment, or when someone asks for nodemailer, an SMTP
+  transport or an smtp:// connection string in a workflow.
 ---
 
 # @t4h.framework/smtp
 
-SMTP activity, claim, and a reconciler-aware client for sending email inside workflows. Package path: `framework/packages/smtp`. Peer dependency: `@t4h.framework/core` (for `SyncActivity`, `Claim`, `History`, `Binary`, `SerializableClass`).
+## Send an email
 
-Import surface (the package entry; its `exports` map has only `.`, so `tsc` rejects a deep import):
-
-```typescript
-import {
-  Smtp,
-  SmtpSendEmailActivity,
-  SmtpSendEmailClaim,
-  SmtpSendEmailOutput,
-  type SmtpOptions,
-  type SmtpSendEmailActivityOptions,
-  type SmtpSendEmailActivityInput,
-  type SmtpSendEmailActivityAttachment,
-  type ISmtpSendEmailOutput,
-} from '@t4h.framework/smtp'
-```
-
-Node `>=22`. See [README.md](../../../README.md) for a short overview (note: README may say `sendEmail` on the claim; the actual method is **`send`**).
-
----
-
-## Architecture
-
-`Workflow` → `Smtp.send` (`History.bind(SmtpSendEmailActivity)`) → `SmtpSendEmailActivity.toInput` / `run` → `SmtpSendEmailClaim.send` → `SmtpSendEmailOutput`.
-
-```
-┌─────────────┐     send()      ┌────────────────────────┐     run()     ┌─────────────────────┐
-│    Smtp     │ ──────────────► │ SmtpSendEmailActivity  │ ────────────► │ SmtpSendEmailClaim  │
-│ (client)    │  reconciler     │ (SyncActivity)         │  Claim.smtp   │ (runtime impl)      │
-└─────────────┘                 └────────────────────────┘               └─────────────────────┘
-```
-
-`@t4h.framework/core/no-io-in-workflow` rejects `nodemailer` and raw sockets in a workflow. Use `Smtp`.
-
----
-
-## SmtpSendEmailClaim (required for delivery)
-
-Abstract dependency; the **runtime** must register a concrete implementation:
-
-```typescript
-{ provide: SmtpSendEmailClaim, value: new MySmtpSendEmailClaimImpl() }
-```
-
-Contract (from source):
-
-```typescript
-abstract class SmtpSendEmailClaim {
-  abstract send(
-    input: SmtpSendEmailActivityInput,
-  ): ISmtpSendEmailOutput | Promise<ISmtpSendEmailOutput>
-}
-
-type ISmtpSendEmailOutput = { messageId: string }
-```
-
-`SmtpSendEmailActivity.run` passes the full **`SmtpSendEmailActivityInput`** payload to `claim.send` (sync or async).
-
----
-
-## Send options and payload
-
-The exported `SmtpSendEmailActivity` — driven by `smtp.send` or directly via
-`History.reconciler(SmtpSendEmailActivity, smtp, content)` — is replay-safe and
-delegates to `SmtpSendEmailClaim.send`, returning a `SmtpSendEmailOutput`. Its
-input shapes:
-
-### SmtpSendEmailActivityOptions (what `smtp.send` accepts)
-
-| Field | Type | Required | Notes |
-|-------|------|----------|-------|
-| `to` | `string \| readonly string[]` | yes | Normalized to `readonly string[]` in input |
-| `subject` | `string` | yes | |
-| `html` | `string` | yes | HTML body |
-| `from` | `string?` | no | Overrides `smtp.options.from` |
-| `cc` | `string \| readonly string[]?` | no | String → single-element array |
-| `bcc` | `string \| readonly string[]?` | no | String → single-element array |
-| `attachments` | `readonly SmtpSendEmailActivityAttachment[]?` | no | Passed through unchanged |
-
-### SmtpSendEmailActivityInput (claim / activity payload)
-
-| Field | Type | Notes |
-|-------|------|-------|
-| `connectionString` | `Secret` | From `smtp.connectionString`; the host reads the value when it sends |
-| `from` | `string?` | `content.from ?? smtp.options.from` |
-| `to` | `readonly string[]` | Always an array after `toInput` |
-| `cc` | `readonly string[]?` | Omitted if not set |
-| `bcc` | `readonly string[]?` | Omitted if not set |
-| `subject` | `string` | |
-| `html` | `string` | |
-| `attachments` | `readonly SmtpSendEmailActivityAttachment[]?` | |
-
-### Attachments
-
-```typescript
-import type { Binary } from '@t4h.framework/core'
-
-type SmtpSendEmailActivityAttachment = {
-  filename: string
-  content: Binary
-}
-```
-
-Use framework `Binary` instances (e.g. from an HTTP `response.body`).
-
----
-
-## Smtp client
-
-High-level API: holds `connectionString` and optional default `from`, extends `SerializableClass` for workflow persistence. `connectionString` is typed `Secret` (a string is a `tsc` error): pass the `EnvDesign` entry declared `type: Secret`, because the URL `smtp://user:pass@host:587` carries the password.
-
-```typescript
-const smtp = new Smtp(environments.SMTP_URL, {
-  from: 'noreply@example.com',
-})
-
-const result = await smtp.send({
-  to: 'recipient@example.com',
-  subject: 'Hello',
-  html: '<p>Hello world</p>',
-})
-
-result.messageId // string — via SmtpSendEmailOutput
-```
-
-- `send(options)` returns a promise of `SmtpSendEmailOutput` when history/reconciler completes (same pattern as `http` client).
-- Default `from`: set on `Smtp` constructor options; per-send `from` in `send()` wins over `smtp.options.from`.
-- `toSerializable()` / `fromSerializable()` restore `connectionString` and `options` (see `Smtp.spec.ts`).
-
-### Multiple recipients, cc, bcc
-
-```typescript
-await smtp.send({
-  to: ['alice@example.com', 'bob@example.com'],
-  cc: 'manager@example.com',
-  bcc: ['audit@example.com'],
-  subject: 'Team Update',
-  html: '<p>Weekly report.</p>',
-})
-```
-
-### Using the exported activity directly via `History.reconciler`
-
-Prefer `smtp.send` in workflows. When you need the exported activity directly,
-drive the **shipped** `SmtpSendEmailActivity` through `History.reconciler` — a
-ready, replay-safe helper. `@t4h.framework/core/no-framework-activity-in-app` rejects `new` and `extends` on it:
-
-```typescript
-import { History } from '@t4h.framework/core'
-import { Smtp, SmtpSendEmailActivity } from '@t4h.framework/smtp'
-
-const smtp = new Smtp(environments.SMTP_URL) // Secret
-const result = await History.reconciler(SmtpSendEmailActivity, smtp, {
-  to: 'user@example.com',
-  subject: 'Subject',
-  html: '<p>Body</p>',
-})
-```
-
----
-
-## SmtpSendEmailOutput
-
-```typescript
-class SmtpSendEmailOutput {
-  constructor(public readonly raw: ISmtpSendEmailOutput)
-  get messageId(): string
-}
-```
-
-Activity and `Smtp.send` surface this type, not the raw `{ messageId }` object.
-
----
-
-## Workflow example
+1. Declare the connection string as a `Secret` in the `EnvDesign` in
+   `src/constants/environments.ts`. The URL (`smtp://user:pass@host:587`)
+   carries the password.
+2. Create one `Smtp` client and call `send` in the workflow body.
 
 ```typescript
 // src/constants/environments.ts
 import { EnvDesign, Secret } from '@t4h.framework/core'
 
 export const environments = EnvDesign({
-  SMTP_CONNECTION_STRING: { type: Secret }, // carries the password
-  SMTP_FROM: { type: String },
+  SMTP_URL: { type: Secret },
 })
 ```
 
 ```typescript
-import { App, Workflow } from '@t4h.framework/core'
-import { http } from '@t4h.framework/http'
+import { Workflow } from '@t4h.framework/core'
 import { Smtp } from '@t4h.framework/smtp'
 import Type from 'typebox'
 
-import { environments } from './constants/environments.js'
-
-const smtp = new Smtp(environments.SMTP_CONNECTION_STRING)
-
-export default new App({
-  id: 'email',
-  workflows: [
-    new Workflow({ id: 'send-email', schema: Type.String() }, async input => {
-      const response = await http.get('https://picsum.photos/300/200')
-
-      await smtp.send({
-        from: environments.SMTP_FROM,
-        to: input,
-        subject: 'Hello World!',
-        html: '<p>...</p>',
-        attachments: [{ filename: 'image.png', content: response.body.binary }],
-      })
-    }),
-  ],
-})
+import { environments } from '../constants/environments.js'
+
+export const sendReport = new Workflow(
+  { id: 'send-report', schema: Type.Object({ email: Type.String() }) },
+  async input => {
+    const smtp = new Smtp(environments.SMTP_URL, {
+      from: 'noreply@example.com',
+    })
+
+    const result = await smtp.send({
+      to: input.email,
+      subject: 'Report',
+      html: '<p>See attached.</p>',
+      attachments: [{ filename: 'report.pdf', content: reportBinary }],
+    })
+
+    return { messageId: result.messageId }
+  },
+)
 ```
 
-Connection strings are opaque to the package; dev implementation expects URL form with credentials in the authority (e.g. `smtp://user:pass@host:587`, `smtps://...`).
-
----
-
-## Testing
-
-Run package tests: `yarn test` in `packages/smtp` (Vitest).
-
-Test the **workflow** with `TestWorkflowEnvironment` from
-`@t4h.framework/core/testing`, mocking `SmtpSendEmailClaim` — the single claim
-the send activity resolves. See the **framework-workflow-testing** skill for the
-harness API.
+## Traps
+
+- The method is `send`, on the client and on `SmtpSendEmailClaim`. There is no
+  `sendEmail`.
+- `new Smtp(...)` takes a `Secret`. A string literal or a `String` env entry is
+  a type error.
+- Create the client in the workflow body. A test that imports the module has
+  no env, so a key read at module top level throws `No env storage`.
+- The body field is `html`. There is no `text` field.
+- An attachment `content` is a `Binary` (from `sftp.get`, an HTTP body, `write`
+  of `@t4h.framework/fs`). Never build a `Binary` by hand; see the
+  `framework-fs` skill.
+- A `from` in `send` wins over the client default. Without both, `from` is
+  `undefined` and the claim decides.
+- `@t4h.framework/core/no-io-in-workflow` rejects `nodemailer` in a workflow.
+  Do not call an SMTP library; use `Smtp`.
+- Do not `new` or `extend` `SmtpSendEmailActivity`
+  (`@t4h.framework/core/no-framework-activity-in-app`). Use `smtp.send`.
+- The runtime must provide `SmtpSendEmailClaim`.
+
+## Test
+
+Mock `SmtpSendEmailClaim` with its `send` method. The mock receives the
+normalized input: `to`, `cc` and `bcc` are always arrays.
 
 ```typescript
 import { TestWorkflowEnvironment, mockClaim } from '@t4h.framework/core/testing'
 import { SmtpSendEmailClaim } from '@t4h.framework/smtp'
+import { expect, vi } from 'vitest'
 
-const mockSend = vi.fn().mockImplementation(async () => ({ messageId: 'msg-123' }))
+const send = vi.fn().mockResolvedValue({ messageId: 'msg-123' })
 
 const env = TestWorkflowEnvironment.create({ now: 0 })
 
 await env.execute(workflow, input, {
-  claims: [mockClaim(SmtpSendEmailClaim, { send: mockSend })],
-  env: { SMTP_CONNECTION_STRING: 'smtp://user:pass@smtp.example.com:587' },
+  claims: [mockClaim(SmtpSendEmailClaim, { send })],
+  env: { SMTP_URL: 'smtp://user:pass@smtp.example.com:587' },
 })
 
-// `send` receives the normalized activity input (single `to` becomes an array, etc.)
-expect(mockSend.mock.calls[0][0]).toMatchObject({
-  to: ['recipient@example.com'],
-  subject: 'Test',
-  html: '<p>Hello</p>',
-})
+expect(send.mock.calls[0][0]).toMatchObject({ to: ['recipient@example.com'] })
 ```
 
----
-
-## Implementing SmtpSendEmailClaim
-
-1. Subclass `SmtpSendEmailClaim` and implement **`send(input: SmtpSendEmailActivityInput)`**.
-2. Read `connectionString`, `from`, `to`, `cc`, `bcc`, `subject`, `html`, `attachments` from `input` (arrays already normalized).
-3. Return `{ messageId: string }` (or a Promise thereof). `messageId` is what workflows expose via `SmtpSendEmailOutput.messageId`.
-4. For attachments, consume `Binary` via `.stream()`, `.contentType`, etc.
-5. Register: `{ provide: SmtpSendEmailClaim, value: new MyClaim() }`.
-
----
-
-## Checklist for agents
-
-1. In workflows, use **`Smtp` + `smtp.send()`** (or `History.reconciler` with the exported `SmtpSendEmailActivity`).
-2. Ensure runtime provides **`SmtpSendEmailClaim`** (or a mock in tests).
-3. Set default **`from`** on `new Smtp(connectionString, { from })` or per-send; per-send wins.
-4. Test workflows with **`TestWorkflowEnvironment`** + **`mockClaim(SmtpSendEmailClaim, { send })`**; assert on the mock's `mock.calls`.
-5. For core workflow/reconciler concepts, use the **framework-core** skill (`@t4h.framework/core`).
+## Reference
 
-See also: `packages/smtp/README.md`; **framework-workflow-testing** for the test harness.
+- Guide: https://tech4humans-brasil.github.io/framework/smtp/
+- Secrets: https://tech4humans-brasil.github.io/framework/core/environment
+- Workflow testing: https://tech4humans-brasil.github.io/framework/core/testing
+- Types: `node_modules/@t4h.framework/smtp/dist/smtp.d.ts`

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @t4h.framework/smtp
 
+## 0.7.9
+
+### Patch Changes
+
+- [#276](https://github.com/tech4humans-brasil/framework/pull/276) [`7b38934`](https://github.com/tech4humans-brasil/framework/commit/7b38934e8f9207c98c33afcd76e3a7a4da7e8b14) Thanks [@gusteycamargo](https://github.com/gusteycamargo)! - The `framework-smtp` skill creates the `Smtp` client in the workflow body. A
+  read of `environments` at the top of the module throws `No env storage`. The
+  test sample imports `expect` and `vi` from `vitest`.
+
+## 0.7.8
+
+## 0.7.7
+
+### Patch Changes
+
+- [#257](https://github.com/tech4humans-brasil/framework/pull/257) [`586bfb4`](https://github.com/tech4humans-brasil/framework/commit/586bfb4663f4a478527ee0c8db360603f034d615) Thanks [@gusteycamargo](https://github.com/gusteycamargo)! - The smtp README is now short and links to the site. The docs page now has the testing and runtime sections, and the README no longer names a `sendEmail` claim method: the method is `send`.
+
 ## 0.7.6
 
 ### Patch Changes

package/README.md

@@ -1,47 +1,20 @@
 # @t4h.framework/smtp
 
-SMTP activity, claim, and a high-level client for sending emails within workflows.
+Sends email from a T4H Framework workflow. Each send is a durable step, so a
+replay does not send the message again.
 
-## Claim
+## Install
 
-### SmtpSendEmailClaim
-
-Abstract dependency for sending emails via SMTP. The runtime must provide a concrete implementation.
-
-```typescript
-import { SmtpSendEmailClaim } from '@t4h.framework/smtp'
-
-// the runtime provides this:
-// { provide: SmtpSendEmailClaim, value: new MySmtpSendEmailClaimImpl() }
-```
-
-### Interface
-
-```typescript
-abstract class SmtpSendEmailClaim {
-  public abstract sendEmail(
-    input: SmtpSendEmailActivityInput,
-  ): ISmtpSendEmailOutput | Promise<ISmtpSendEmailOutput>
-}
-```
-
-## Activity
-
-### SmtpSendEmailActivity
-
-A `SyncActivity` that sends an email and returns a `SmtpSendEmailOutput`. Internally it uses `SmtpSendEmailClaim` to perform the delivery.
-
-```typescript
-import { SmtpSendEmailActivity } from '@t4h.framework/smtp'
+```bash
+npm install @t4h.framework/smtp
 ```
 
-## Smtp
+Peer dependency: `@t4h.framework/core`.
 
-High-level SMTP client that wraps `SmtpSendEmailActivity` behind a simple API. Instantiated with a connection string and optional defaults.
+## Usage
 
-### Basic usage
-
-The connection string `smtp://user:pass@host:587` carries the password, so the constructor takes a `Secret` and `tsc` rejects a string. Declare it with `type: Secret` in the `EnvDesign` in `src/constants/environments.ts`:
+The connection string carries the password, so declare it with
+`type: Secret` in the `EnvDesign` in `src/constants/environments.ts`:
 
 ```typescript
 // src/constants/environments.ts
@@ -53,67 +26,27 @@ export const environments = EnvDesign({
 ```
 
 ```typescript
+import { Workflow } from '@t4h.framework/core'
 import { Smtp } from '@t4h.framework/smtp'
 
 import { environments } from './constants/environments.js'
 
-const smtp = new Smtp(environments.SMTP_URL)
-
-const result = await smtp.send({
-  from: 'noreply@example.com',
-  to: 'recipient@example.com',
-  subject: 'Hello',
-  html: '<p>Hello world</p>',
-})
-
-result.messageId // string
-```
-
-### Default sender
-
-```typescript
-const smtp = new Smtp(environments.SMTP_URL, {
-  from: 'noreply@example.com',
-})
-
-const result = await smtp.send({
-  to: 'recipient@example.com',
-  subject: 'Hello',
-  html: '<p>Hello world</p>',
-})
-```
-
-### Multiple recipients, cc, and bcc
+const notify = new Workflow({ id: 'notify' }, async () => {
+  const smtp = new Smtp(environments.SMTP_URL, { from: 'noreply@example.com' })
 
-```typescript
-const result = await smtp.send({
-  to: ['alice@example.com', 'bob@example.com'],
-  cc: 'manager@example.com',
-  bcc: ['audit@example.com'],
-  subject: 'Team Update',
-  html: '<p>Weekly report attached.</p>',
-})
-```
+  const result = await smtp.send({
+    to: 'recipient@example.com',
+    subject: 'Hello',
+    html: '<p>Hello world</p>',
+  })
 
-### Attachments
-
-```typescript
-import type { Binary } from '@t4h.framework/core'
-
-const result = await smtp.send({
-  to: 'recipient@example.com',
-  subject: 'Report',
-  html: '<p>See attached.</p>',
-  attachments: [attachment],
+  return { messageId: result.messageId }
 })
 ```
 
-## Output
-
-The `SmtpSendEmailOutput` object provides access to the sent message identifier:
+Create the `Smtp` client in the workflow body. A test that imports the module
+has no env, so a key read at module top level throws `No env storage`.
 
-```typescript
-const result = await smtp.send({ ... })
+## Documentation
 
-result.messageId // string — the message ID returned by the SMTP server
-```
+https://tech4humans-brasil.github.io/framework/smtp/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t4h.framework/smtp",
-  "version": "0.7.6",
+  "version": "0.7.9",
   "description": "SMTP module for the T4H Framework",
   "homepage": "https://github.com/tech4humans-brasil/framework/tree/main/packages/smtp",
   "bugs": "https://github.com/tech4humans-brasil/framework/issues",
@@ -33,7 +33,7 @@
     "test:watch": "vitest"
   },
   "devDependencies": {
-    "@t4h.framework/core": "^0.20.0",
+    "@t4h.framework/core": "^0.21.2",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },