@t4h.framework/http 0.3.1 → 0.4.0

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

@@ -1,12 +1,11 @@
 ---
 name: framework-http
 description: >-
-  Guides correct use of @t4h.framework/http in T4H Framework workflows: HTTP
-  activities (HttpRequestActivity, AbstractHttpRequestActivity), claims
-  (HttpClientRequestClaim, FileSystemClaim, CacheClaim for OAuth), the http
-  client, request/response bodies, and auth. Use when implementing or testing
-  HTTP calls in workflows, wiring HTTP claim providers, extending HTTP
-  activities, OAuth2/Basic auth, or working in packages/http.
+  Guides correct use of @t4h.framework/http in T4H Framework workflows: the
+  `http` / `HttpClient` client, claims (HttpClientRequestClaim, FileSystemClaim,
+  CacheClaim for OAuth), request/response bodies, and auth. Use when making or
+  testing HTTP calls in workflows, wiring HTTP claim providers, OAuth2/Basic
+  auth, or working in packages/http.
 ---
 
 # @t4h.framework/http
@@ -19,8 +18,6 @@ Import surface (from `src/http.ts` only — do not reference unexported modules
 import {
   http,
   HttpClient,
-  HttpRequestActivity,
-  AbstractHttpRequestActivity,
   HttpClientRequestClaim,
   HttpAuth,
   OAuth2,
@@ -28,13 +25,15 @@ import {
   OAuth2GrantResourceOwnerPassword,
   Body,
   Response,
-  type HttpRequestActivityInput,
-  type HttpRequestActivityOutput,
   type HttpClientRequestClaimInput,
   type HttpClientRequestClaimOutput,
 } from '@t4h.framework/http'
 ```
 
+> Workflows use the **`http` / `HttpClient`** client. The package also exports
+> the underlying `HttpRequestActivity` / `AbstractHttpRequestActivity`, but
+> workflow code never imports, instantiates, or extends them.
+
 ## Architecture
 
 `Workflow` → `http`/`HttpClient` (`History.bind(HttpRequestActivity)`) → `AbstractHttpRequestActivity.run` → `HttpClientRequestClaim.request` + `FileSystemClaim.write` (response → `Body`/`Response`).
@@ -78,11 +77,11 @@ abstract class HttpClientRequestClaim {
 }
 ```
 
-Dev: register a concrete `HttpClientRequestClaim` in the runtime (or mock in tests via `Claim.run`).
+The runtime provides a concrete implementation; workflow tests mock it (see **Testing** below).
 
-### FileSystemClaim (required by activities)
+### FileSystemClaim (required by the HTTP activity)
 
-`AbstractHttpRequestActivity` persists the response body with `fs.write(\`${uuid}-http-request-activity-response-body.${ext}\`, response.body)`. Extension comes from `content-type` via `mime`, or `.bin` if missing. Tests mock `FileSystemClaim.write` to build a `Binary` for `Body`.
+The HTTP activity persists the response body to `fs` (path `\`${uuid}-http-request-activity-response-body.${ext}\``, extension from `content-type` via `mime`, or `.bin`) and returns it wrapped in a `Body`. So any workflow that makes an HTTP call also needs a `FileSystemClaim` provider; tests mock its `write` to return a `Binary`.
 
 ### CacheClaim (OAuth only)
 
@@ -117,74 +116,21 @@ Invalid body shape throws `Invalid body`.
 
 ---
 
-## Activities
-
-### HttpRequestActivity
-
-Direct use when workflow input matches HTTP config:
-
-```typescript
-import { HttpRequestActivity } from '@t4h.framework/http'
-
-// Inside Claim.run or reconciler context:
-const activity = new HttpRequestActivity()
-const output = await activity.run({
-  url: 'https://api.example.com/data',
-  method: 'GET',
-})
-// Serializable output is HttpRequestActivityOutput; toOutput wraps Response
-```
-
-`toInput` / `toHttpInput` pass input through; `toOutput` returns `new Response(output)`.
+## Making HTTP calls in a workflow
 
-### AbstractHttpRequestActivity (custom activities)
+Always use the ready **`http` / `HttpClient`** helper — it is what the package
+exports for workflows and it drives the underlying HTTP activity through the
+reconciler for you (replay-safe). Never define, extend, or hand-instantiate an
+activity in workflow code.
 
-Extend with **four** type parameters: `TArgs`, `TInput`, `TSerializableOutput`, `TOutput`.
-
-Implement:
-
-- `toInput(...args)` — map workflow args → activity input
-- `toOutput(serializable, ...args)` — map serializable result → workflow return type
-- `protected toHttpInput(input)` — map to `HttpRequestActivityInput`
-- `protected toHttpOutput(output)` — map `HttpRequestActivityOutput` → serializable stored in history
+For a typed result, read the response and map with plain TypeScript:
 
 ```typescript
-import {
-  AbstractHttpRequestActivity,
-  type HttpRequestActivityInput,
-  type HttpRequestActivityOutput,
-} from '@t4h.framework/http'
-import type { Serializable } from '@t4h.framework/core'
-
-class FetchStatusActivity extends AbstractHttpRequestActivity<
-  [endpoint: string],
-  { endpoint: string },
-  { status: number },
-  { status: number }
-> {
-  public async toInput(endpoint: string) {
-    return { endpoint }
-  }
-
-  protected async toHttpInput(input: { endpoint: string }): Promise<HttpRequestActivityInput> {
-    return { url: input.endpoint, method: 'GET' }
-  }
-
-  protected async toHttpOutput(output: HttpRequestActivityOutput): Promise<{ status: number }> {
-    return { status: output.status }
-  }
-
-  public toOutput(output: { status: number }) {
-    return output
-  }
-}
+const res = await http.get(`${environments.SERVICE_URL}/data`)
+const data = await res.body.json<MyType>()
 ```
 
-Static helpers (for tests or advanced form building):
-
-- `AbstractHttpRequestActivity.getContent(body)`
-- `AbstractHttpRequestActivity.append(form, input, currentKey?)`
-- `AbstractHttpRequestActivity.getFormData(input)`
+See **HttpClient and `http`** and **Response and Body** below.
 
 ---
 
@@ -217,7 +163,7 @@ const client = new HttpClient({
 
 Methods: `request(url, config?)`, `get`, `post(url, body, config?)`, `put`, `patch`, `delete`. Per-request `auth` in config merges over client `config.auth`.
 
-Workflow example (`examples/basic/src/workflows/simple.ts`):
+Workflow example:
 
 ```typescript
 import { Workflow } from '@t4h.framework/core'
@@ -254,6 +200,13 @@ await response.body.stream()
 
 `body.json()` throws `Invalid content type` for non-JSON types (e.g. `text/plain`, `text/html`).
 
+`Body` extends `SerializableClass` (`packages/http/src/models/Body.ts`) and is
+persisted through `FileSystemClaim`, so the `Response`/`Body` returned by the
+`http` client **is replay-safe** — it is serialized between reconciler steps and
+rebuilt on replay. You do **not** need a custom activity to "flatten" the body
+into history; read it with `await res.body.json<T>()` in the workflow and
+transform with plain TypeScript.
+
 Serializable shape: `{ binary: ... }` via `toSerializable` / `fromSerializable`.
 
 ---
@@ -308,95 +261,75 @@ Requires `CacheClaim` + `HttpClientRequestClaim` in the runtime.
 
 ## Testing
 
-Run package tests: `yarn test` in `packages/http` (Vitest).
-
-### 1. Unit-test activity `run` with mocked claims
-
-Pattern from `AbstractHttpRequestActivity.spec.ts`:
+Test the **workflow** with `TestWorkflowEnvironment` from
+`@t4h.framework/core/testing`, mocking the two claims the HTTP activity uses:
+`HttpClientRequestClaim` (the network request) and `FileSystemClaim` (where the
+activity persists the response body). See the **framework-workflow-testing** skill
+for the full harness API.
 
 ```typescript
-import { Claim } from '@t4h.framework/core'
-import { FileSystemClaim } from '@t4h.framework/fs'
 import { Readable } from 'node:stream'
+import { Binary } from '@t4h.framework/core'
+import { TestWorkflowEnvironment, mockClaim } from '@t4h.framework/core/testing'
 import { HttpClientRequestClaim } from '@t4h.framework/http'
+import { FileSystemClaim } from '@t4h.framework/fs'
 
-const mockRequest = vi.fn().mockResolvedValue({
-  status: 200,
-  headers: { 'content-type': 'application/json' },
-  body: Readable.from(Buffer.from('{"ok":true}')),
-})
-
-const mockWrite = vi.fn().mockImplementation(async (_path, readable) => {
-  const chunks = await readable.toArray()
-  return new MockBinary(Buffer.concat(chunks), 'application/json')
-})
-
-const result = await Claim.run(
-  [
-    { provide: HttpClientRequestClaim, value: { request: mockRequest } },
-    { provide: FileSystemClaim, value: { write: mockWrite, read: vi.fn() } },
-  ],
-  () => new MyActivity().run(input),
-)
-
-await expect(result.body.json()).resolves.toEqual({ ok: true })
-```
-
-Assert `mockRequest` received `url`, `method`, merged headers, and JSON buffer for `{ json: ... }` bodies.
-
-### 2. Assert HttpClient schedules HttpRequestActivity
+// Minimal Binary the FileSystemClaim mock returns from write().
+class MockBinary extends Binary {
+  public readonly contentType = 'application/json'
+  public readonly contentLength: number
 
-Pattern from `HttpClient.spec.ts`:
+  constructor(private readonly data: Buffer) {
+    super()
+    this.contentLength = data.byteLength
+  }
 
-```typescript
-import { History, PushActivity } from '@t4h.framework/core'
-import { HttpRequestActivity } from '@t4h.framework/http'
-
-async function captureTrigger(fn: () => unknown) {
-  try {
-    await History.run([], fn)
-  } catch (error) {
-    if (error instanceof PushActivity) return error
-    throw error
+  public stream() {
+    return Readable.from(this.data)
   }
 }
 
-const trigger = await captureTrigger(() => http.post('/users', { json: { name: 'Tony' } }))
-expect(trigger.activity.constructor).toBe(HttpRequestActivity)
-expect(trigger.input).toMatchObject({ method: 'POST', body: { json: { name: 'Tony' } } })
-```
-
-### 3. Integration-test workflows with mocked claims
+const body = Buffer.from(JSON.stringify({ ok: true }))
 
-Use `WorkflowTesting.run` with explicit claim providers and spies on mock implementations:
+// mockImplementation (not mockResolvedValue): replay runs the workflow twice, so
+// each call must hand back a fresh, unconsumed stream.
+const mockRequest = vi.fn().mockImplementation(async () => ({
+  status: 200,
+  headers: { 'content-type': 'application/json' },
+  body: Readable.from(body),
+}))
 
-```typescript
-import { WorkflowTesting } from '@t4h.framework/core/testing'
-import { HttpClientRequestClaim, type HttpClientRequestClaimInput } from '@t4h.framework/http'
+const mockWrite = vi.fn().mockImplementation(async () => new MockBinary(body))
 
-const mockRequest = vi.fn().mockResolvedValue({ status: 200, headers: {}, body: Readable.from('{}') })
+const env = TestWorkflowEnvironment.create({ now: 0 })
 
-await WorkflowTesting.run(workflow, input, {
+const output = await env.execute(workflow, input, {
   claims: [
-    { provide: HttpClientRequestClaim, value: { request: mockRequest } as HttpClientRequestClaim },
-    { provide: FileSystemClaim, value: mockFs },
+    mockClaim(HttpClientRequestClaim, { request: mockRequest }),
+    mockClaim(FileSystemClaim, { write: mockWrite, read: vi.fn() }),
   ],
+  env: { SERVICE_URL: 'https://api.example.com' },
 })
+
+// request input carries a URL object
+expect(mockRequest.mock.calls[0][0].url).toEqual(
+  new URL('https://api.example.com/data'),
+)
 ```
 
-Inspect `mockRequest.mock.calls` for URLs, methods, and bodies. See **framework-core** skill for `WorkflowTesting` options.
+Inspect `mockRequest.mock.calls` for URLs, methods, and bodies.
 
 ---
 
 ## Checklist for agents
 
-1. Prefer **`http` / `HttpClient`** in workflows unless you need a typed custom activity.
+1. In workflows, **always** use **`http` / `HttpClient`** — never define or extend an activity. Get typed, replay-safe results with `await res.body.json<T>()` plus plain TypeScript.
 2. Never call `fetch` directly in workflow code if the step must be replayable — use the package APIs.
 3. Ensure runtime provides **`HttpClientRequestClaim`** and **`FileSystemClaim`** (or pass mocks in tests).
 4. Use **`{ json: ... }`**, **`{ text: ... }`**, or **`{ form: ... }`** for bodies — not raw `Buffer` on activity input.
 5. Read responses with **`await response.body.json()`** or **`text()`**; check `status` explicitly (no automatic throw on 4xx/5xx).
 6. For OAuth, wire **`CacheClaim`** and use exported grant classes only.
-7. When adding tests, mirror **`Claim.run`** + claim mocks or **`History.run`** + **`PushActivity`** patterns from `packages/http/src/**/__tests__`.
+7. Test workflows with **`TestWorkflowEnvironment`** + **`mockClaim`**, mocking **`HttpClientRequestClaim`** and **`FileSystemClaim`**; assert on `mockRequest.mock.calls`.
 8. Do not document or import APIs not exported from `@t4h.framework/http`.
 
-See also: `packages/http/README.md`, `examples/basic/src/workflows/simple.ts`.
+See also: `packages/http/README.md`; **framework-workflow-testing** for the test harness.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t4h.framework/http",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "HTTP module for the T4H Framework",
   "homepage": "https://github.com/tech4humans-brasil/framework/tree/main/packages/http",
   "bugs": "https://github.com/tech4humans-brasil/framework/issues",
@@ -38,18 +38,18 @@
     "uuidv7": "^1.1.0"
   },
   "devDependencies": {
-    "@t4h.framework/cache": "^0.4.0",
-    "@t4h.framework/core": "^0.7.0",
-    "@t4h.framework/fs": "^0.4.0",
+    "@t4h.framework/cache": "^0.5.0",
+    "@t4h.framework/core": "^0.8.0",
+    "@t4h.framework/fs": "^0.5.0",
     "@types/type-is": "^1.6.7",
     "@vitest/coverage-v8": "^4.0.18",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },
   "peerDependencies": {
-    "@t4h.framework/cache": "^0.4.0",
-    "@t4h.framework/core": "^0.7.0",
-    "@t4h.framework/fs": "^0.4.0"
+    "@t4h.framework/cache": "^0.5.0",
+    "@t4h.framework/core": "^0.8.0",
+    "@t4h.framework/fs": "^0.5.0"
   },
   "packageManager": "yarn@4.12.0",
   "engines": {