@t4h.framework/smtp 0.3.0 → 0.5.0

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

@@ -0,0 +1,282 @@
+---
+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.
+---
+
+# @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).
+
+---
+
+## 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` | `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 an HTTP `response.body`).
+
+---
+
+## 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>',
+})
+```
+
+### 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. Never define or extend your own activity:
+
+```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>',
+})
+```
+
+Runs inside a workflow (the runtime, or `TestWorkflowEnvironment` in tests, provides the reconciler context).
+
+---
+
+## 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
+
+```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).
+
+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.
+
+```typescript
+import { TestWorkflowEnvironment, mockClaim } from '@t4h.framework/core/testing'
+import { SmtpSendEmailClaim } from '@t4h.framework/smtp'
+
+const mockSend = vi.fn().mockImplementation(async () => ({ 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' },
+})
+
+// `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>',
+})
+```
+
+---
+
+## 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`) — never define or extend your own activity.
+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. Test workflows with **`TestWorkflowEnvironment`** + **`mockClaim(SmtpSendEmailClaim, { send })`**; assert on the mock's `mock.calls`.
+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`; **framework-workflow-testing** for the test harness.

package/dist/testing/index.d.ts

@@ -0,0 +1,3 @@
+import { SmtpSendEmailClaim } from '../models/SmtpSendEmailClaim.js';
+export declare function mockSmtpClaim(implementation?: Partial<SmtpSendEmailClaim>): import("@t4h.framework/core").ClaimProvider<SmtpSendEmailClaim>;
+//# sourceMappingURL=index.d.ts.map

package/dist/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAA;AAEpE,wBAAgB,aAAa,CAC3B,cAAc,GAAE,OAAO,CAAC,kBAAkB,CAAM,mEAMjD"}

package/dist/testing/index.js

@@ -0,0 +1,9 @@
+import { mockClaim } from '@t4h.framework/core/testing';
+import { SmtpSendEmailClaim } from '../models/SmtpSendEmailClaim.js';
+export function mockSmtpClaim(implementation = {}) {
+    return mockClaim(SmtpSendEmailClaim, {
+        send: async () => ({ messageId: 'mock-message-id' }),
+        ...implementation,
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/testing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAA;AAEvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAA;AAEpE,MAAM,UAAU,aAAa,CAC3B,iBAA8C,EAAE;IAEhD,OAAO,SAAS,CAAC,kBAAkB,EAAE;QACnC,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,EAAE,SAAS,EAAE,iBAAiB,EAAE,CAAC;QACpD,GAAG,cAAc;KAClB,CAAC,CAAA;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t4h.framework/smtp",
-  "version": "0.3.0",
+  "version": "0.5.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.8.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },
   "peerDependencies": {
-    "@t4h.framework/core": "^0.3.0"
+    "@t4h.framework/core": "^0.8.0"
   },
   "packageManager": "yarn@4.12.0",
   "engines": {