@t4h.framework/smtp 0.3.0 → 0.4.0

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

@@ -0,0 +1,354 @@
+---
+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 or examples/email.
+---
+
+# @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`).
+
+Import surface (from `src/smtp.ts` only — do not reference unexported modules):
+
+```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)      │
+└─────────────┘                 └────────────────────────┘               └─────────────────────┘
+```
+
+Never call nodemailer or raw SMTP sockets directly in workflow code if the step must be replayable — use `Smtp` / `SmtpSendEmailActivity`.
+
+---
+
+## 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).
+
+---
+
+## SmtpSendEmailActivity
+
+`SyncActivity` with args `[smtp: Smtp, content: SmtpSendEmailActivityOptions]`.
+
+| Method | Role |
+|--------|------|
+| `toInput(smtp, content)` | Builds serializable `SmtpSendEmailActivityInput` |
+| `run(payload)` | `this.claims.smtp.send(payload)` |
+| `toOutput(raw)` | `new SmtpSendEmailOutput(raw)` |
+
+Claim wiring (private `Claim` with key `smtp` → `SmtpSendEmailClaim`).
+
+### SmtpSendEmailActivityOptions (designer / `Smtp.send`)
+
+| 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` | `string` | From `smtp.connectionString` |
+| `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 HTTP `response.body.binary` in `examples/email`).
+
+---
+
+## Smtp client
+
+High-level API: holds `connectionString` and optional default `from`, extends `SerializableClass` for workflow persistence.
+
+```typescript
+const smtp = new Smtp('smtp://user:pass@smtp.example.com:587', {
+  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>',
+})
+```
+
+### Invoking the activity directly
+
+Prefer `smtp.send` in workflows. For low-level control:
+
+```typescript
+import { History } from '@t4h.framework/core'
+import { Smtp, SmtpSendEmailActivity } from '@t4h.framework/smtp'
+
+const smtp = new Smtp(connectionString)
+const result = await History.reconciler(SmtpSendEmailActivity, smtp, {
+  to: 'user@example.com',
+  subject: 'Subject',
+  html: '<p>Body</p>',
+})
+```
+
+Must run inside `History.run` (workflow runtime or test harness).
+
+---
+
+## 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
+
+From `examples/email/src/main.tsx`:
+
+```typescript
+import { App, EnvDesign, Workflow } from '@t4h.framework/core'
+import { http } from '@t4h.framework/http'
+import { Smtp } from '@t4h.framework/smtp'
+import Type from 'typebox'
+
+const env = EnvDesign({
+  SMTP_CONNECTION_STRING: { type: String },
+  SMTP_FROM: { type: String },
+})
+
+const smtp = new Smtp(env.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: env.SMTP_FROM,
+        to: input,
+        subject: 'Hello World!',
+        html: '<p>...</p>',
+        attachments: [{ filename: 'image.png', content: response.body.binary }],
+      })
+    }),
+  ],
+})
+```
+
+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).
+
+### 1. Unit-test `toInput` / `run` / `toOutput`
+
+Pattern from `SmtpSendEmailActivity.spec.ts`:
+
+```typescript
+import { Claim } from '@t4h.framework/core'
+import { vi } from 'vitest'
+import {
+  Smtp,
+  SmtpSendEmailActivity,
+  SmtpSendEmailClaim,
+  type SmtpSendEmailActivityInput,
+} from '@t4h.framework/smtp'
+
+const mockSend = vi.fn().mockReturnValue({ messageId: 'msg-123' })
+
+Claim.run(
+  [{ provide: SmtpSendEmailClaim, value: { send: mockSend } as SmtpSendEmailClaim }],
+  () => {
+    const activity = Reflect.construct(SmtpSendEmailActivity, [])
+    const input: SmtpSendEmailActivityInput = {
+      connectionString: 'smtp://user:pass@smtp.example.com:587',
+      from: 'sender@example.com',
+      subject: 'Test',
+      html: '<p>Hello</p>',
+      to: ['recipient@example.com'],
+    }
+    const output = activity.run(input)
+    expect(mockSend).toHaveBeenCalledWith(input)
+    expect(output).toEqual({ messageId: 'msg-123' })
+  },
+)
+```
+
+Use `mockResolvedValue` when testing async `send` implementations.
+
+Assert `toInput` normalization: single `to` → array; `content.from` over `smtp.options.from`; `cc`/`bcc` string → array; attachments reference equality.
+
+### 2. Assert `Smtp.send` schedules `SmtpSendEmailActivity`
+
+Pattern from `Smtp.spec.ts`:
+
+```typescript
+import { History, PushActivity, type Activity } from '@t4h.framework/core'
+import { Smtp, SmtpSendEmailActivity } from '@t4h.framework/smtp'
+
+async function captureReconcilerTrigger(fn: () => unknown) {
+  try {
+    await History.run([], fn)
+  } catch (error) {
+    if (error instanceof PushActivity) return error as PushActivity<Activity>
+    throw error
+  }
+}
+
+const client = new Smtp(connectionString, { from: 'noreply@example.com' })
+const trigger = await captureReconcilerTrigger(() =>
+  client.send({ to: 'a@example.com', subject: 'Test', html: '<p>Hi</p>' }),
+)
+
+expect(trigger.activity.constructor).toBe(SmtpSendEmailActivity)
+expect(trigger.input).toEqual({
+  connectionString,
+  from: 'noreply@example.com',
+  subject: 'Test',
+  html: '<p>Hi</p>',
+  to: ['a@example.com'],
+  cc: undefined,
+  bcc: undefined,
+  attachments: undefined,
+})
+```
+
+### 3. Replay with history
+
+```typescript
+import { History } from '@t4h.framework/core'
+import { Smtp, SmtpSendEmailOutput } from '@t4h.framework/smtp'
+
+const result = await History.run(
+  [{ output: { messageId: '<msg-123@example.com>' }, type: 'sync' }],
+  () =>
+    client.send({
+      to: 'user@example.com',
+      subject: 'Subject',
+      html: '<p>Body</p>',
+    }),
+)
+
+expect(result).toBeInstanceOf(SmtpSendEmailOutput)
+expect(result.messageId).toBe('<msg-123@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. Prefer **`Smtp` + `smtp.send()`** in workflows unless a custom typed activity is required.
+2. Ensure runtime provides **`SmtpSendEmailClaim`** (or a mock in tests).
+3. Use **`html`** for the message body; required fields on send options are **`to`**, **`subject`**, **`html`**.
+4. Set default **`from`** on `new Smtp(connectionString, { from })` or per-send; per-send wins.
+5. Pass **`Binary`** for attachment `content`, not raw `Buffer` in activity options.
+6. Expect **`SmtpSendEmailOutput`** from `send`, not a plain object — use `.messageId`.
+7. When testing, mirror **`Claim.run`** + mock `send`, or **`History.run`** + **`PushActivity`** from `packages/smtp/src/**/__tests__`.
+8. Do not document or import APIs not exported from `@t4h.framework/smtp`.
+9. For core workflow/reconciler concepts, use the **framework-core** skill (`@t4h.framework/core`).
+
+See also: `packages/smtp/README.md`, `examples/email/src/main.tsx`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t4h.framework/smtp",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "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",
@@ -20,7 +20,8 @@
   "types": "./dist/smtp.d.ts",
   "files": [
     "dist",
-    "LICENSE"
+    "LICENSE",
+    ".ai"
   ],
   "scripts": {
     "build": "tsc --project tsconfig.build.json",
@@ -29,15 +30,13 @@
     "test": "vitest run",
     "test:watch": "vitest"
   },
-  "dependencies": {
-    "@t4h.framework/core": "^0.3.0"
-  },
   "devDependencies": {
+    "@t4h.framework/core": "^0.6.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },
   "peerDependencies": {
-    "@t4h.framework/core": "^0.3.0"
+    "@t4h.framework/core": "^0.6.0"
   },
   "packageManager": "yarn@4.12.0",
   "engines": {