@t4h.framework/smtp 0.4.0 → 0.6.0

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

@@ -6,7 +6,7 @@ description: >-
   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.
+  or working in packages/smtp.
 ---
 
 # @t4h.framework/smtp
@@ -72,19 +72,14 @@ type ISmtpSendEmailOutput = { messageId: string }
 
 ---
 
-## SmtpSendEmailActivity
+## Send options and payload
 
-`SyncActivity` with args `[smtp: Smtp, content: SmtpSendEmailActivityOptions]`.
+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:
 
-| 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`)
+### SmtpSendEmailActivityOptions (what `smtp.send` accepts)
 
 | Field | Type | Required | Notes |
 |-------|------|----------|-------|
@@ -120,7 +115,7 @@ type SmtpSendEmailActivityAttachment = {
 }
 ```
 
-Use framework `Binary` instances (e.g. from HTTP `response.body.binary` in `examples/email`).
+Use framework `Binary` instances (e.g. from an HTTP `response.body`).
 
 ---
 
@@ -158,9 +153,11 @@ await smtp.send({
 })
 ```
 
-### Invoking the activity directly
+### Using the exported activity directly via `History.reconciler`
 
-Prefer `smtp.send` in workflows. For low-level control:
+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'
@@ -174,7 +171,7 @@ const result = await History.reconciler(SmtpSendEmailActivity, smtp, {
 })
 ```
 
-Must run inside `History.run` (workflow runtime or test harness).
+Runs inside a workflow (the runtime, or `TestWorkflowEnvironment` in tests, provides the reconciler context).
 
 ---
 
@@ -193,8 +190,6 @@ 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'
@@ -234,99 +229,32 @@ Connection strings are opaque to the package; dev implementation expects URL for
 
 Run package tests: `yarn test` in `packages/smtp` (Vitest).
 
-### 1. Unit-test `toInput` / `run` / `toOutput`
-
-Pattern from `SmtpSendEmailActivity.spec.ts`:
+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 { 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.
+import { TestWorkflowEnvironment, mockClaim } from '@t4h.framework/core/testing'
+import { SmtpSendEmailClaim } from '@t4h.framework/smtp'
 
-### 2. Assert `Smtp.send` schedules `SmtpSendEmailActivity`
+const mockSend = vi.fn().mockImplementation(async () => ({ messageId: 'msg-123' }))
 
-Pattern from `Smtp.spec.ts`:
+const env = TestWorkflowEnvironment.create({ now: 0 })
 
-```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>' }),
-)
+await env.execute(workflow, input, {
+  claims: [mockClaim(SmtpSendEmailClaim, { send: mockSend })],
+  env: { SMTP_CONNECTION_STRING: 'smtp://user:pass@smtp.example.com:587' },
+})
 
-expect(trigger.activity.constructor).toBe(SmtpSendEmailActivity)
-expect(trigger.input).toEqual({
-  connectionString,
-  from: 'noreply@example.com',
+// `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>Hi</p>',
-  to: ['a@example.com'],
-  cc: undefined,
-  bcc: undefined,
-  attachments: undefined,
+  html: '<p>Hello</p>',
 })
 ```
 
-### 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
@@ -341,14 +269,14 @@ expect(result.messageId).toBe('<msg-123@example.com>')
 
 ## Checklist for agents
 
-1. Prefer **`Smtp` + `smtp.send()`** in workflows unless a custom typed activity is required.
+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. When testing, mirror **`Claim.run`** + mock `send`, or **`History.run`** + **`PushActivity`** from `packages/smtp/src/**/__tests__`.
+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`, `examples/email/src/main.tsx`.
+See also: `packages/smtp/README.md`; **framework-workflow-testing** for the test harness.

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# @t4h.framework/smtp
+
+## 0.6.0
+
+### Minor Changes
+
+- Updated dependencies [[`8098041`](https://github.com/tech4humans-brasil/framework/commit/80980419d59a987378b7c94372ee2f7b7dcc00f5)]:
+  - @t4h.framework/core@0.10.0
+
+## 0.5.0
+
+### Minor Changes
+
+- Update history to satisfies core contract ([`30b3d38`](https://github.com/tech4humans-brasil/framework/commit/30b3d38bfd631990e4c4f740344910d5958ddfb9))
+
+### Patch Changes
+
+- Update skills ([`6d7e7bc`](https://github.com/tech4humans-brasil/framework/commit/6d7e7bca0c780a9c53a0c9e5aa0a865c5af67959))
+
+## 0.4.0
+
+### Patch Changes
+
+- Internal dependency updates
+
+## 0.3.0
+
+### Minor Changes
+
+- Implements smtp activity ([`ca20afd`](https://github.com/tech4humans-brasil/framework/commit/ca20afdfc324a1004e77ef1881c049e7f97f0eff))
+- Adds type to history item ([#47](https://github.com/tech4humans-brasil/framework/pull/47))
+- Adds .ai/skills in packages ([#88](https://github.com/tech4humans-brasil/framework/pull/88))
+
+### Patch Changes
+
+- Update package metadata and author information across multiple packages ([`2ca73df`](https://github.com/tech4humans-brasil/framework/commit/2ca73df42dc63c86ed44717b50d5402fca45b4e7))
+- Improve repository info ([`1fad92d`](https://github.com/tech4humans-brasil/framework/commit/1fad92d959b804189fd1486d047115995ac81eb0))
+- Up repo coverage ([`24c057c`](https://github.com/tech4humans-brasil/framework/commit/24c057c470d0829ea9a1e1f71011b6eff408180c))
+- Fix resolve module resolution issues in check-types ([`c97a0d2`](https://github.com/tech4humans-brasil/framework/commit/c97a0d2747f38e561cc5c7d592b20de0459bc1ee))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t4h.framework/smtp",
-  "version": "0.4.0",
+  "version": "0.6.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",
@@ -31,12 +31,12 @@
     "test:watch": "vitest"
   },
   "devDependencies": {
-    "@t4h.framework/core": "^0.6.0",
+    "@t4h.framework/core": "^0.10.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },
   "peerDependencies": {
-    "@t4h.framework/core": "^0.6.0"
+    "@t4h.framework/core": "^0.10.0"
   },
   "packageManager": "yarn@4.12.0",
   "engines": {