@t4h.framework/http 0.3.0 → 0.4.0

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

@@ -0,0 +1,335 @@
+---
+name: framework-http
+description: >-
+  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
+
+HTTP activities, claims, and a reconciler-aware client for workflows. Package path: `framework/packages/http`. Peer dependencies: `@t4h.framework/core`, `@t4h.framework/fs`, `@t4h.framework/cache` (OAuth).
+
+Import surface (from `src/http.ts` only — do not reference unexported modules such as `src/errors/HttpError.ts`):
+
+```typescript
+import {
+  http,
+  HttpClient,
+  HttpClientRequestClaim,
+  HttpAuth,
+  OAuth2,
+  OAuth2ClientCredentials,
+  OAuth2GrantResourceOwnerPassword,
+  Body,
+  Response,
+  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`).
+
+---
+
+## Claims
+
+### HttpClientRequestClaim (required for HTTP)
+
+Runtime must register an implementation:
+
+```typescript
+{ provide: HttpClientRequestClaim, value: new MyHttpClientRequestClaimImpl() }
+```
+
+Contract:
+
+```typescript
+abstract class HttpClientRequestClaim {
+  abstract request(
+    input: HttpClientRequestClaimInput,
+  ): HttpClientRequestClaimOutput | Promise<HttpClientRequestClaimOutput>
+}
+
+// HttpClientRequestClaimInput
+{
+  url: URL
+  method: HttpMethod // required on claim input
+  body: Buffer | FormData | Readable | URLSearchParams | undefined
+  headers: Record<string, string | string[] | undefined>
+  redirect: 'follow' | 'manual' | number
+  retry: boolean | HttpRequestActivityInputRetryOptions
+}
+
+// HttpClientRequestClaimOutput
+{
+  status: number
+  headers: Record<string, string | string[] | undefined>
+  body: Readable
+}
+```
+
+The runtime provides a concrete implementation; workflow tests mock it (see **Testing** below).
+
+### FileSystemClaim (required by the HTTP activity)
+
+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)
+
+`HttpAuth` / `OAuth2` use `CacheClaim` for token caching. OAuth2 stores tokens at `oauth2:token:${clientId}` with TTL derived from `expires_in` (90% of lifetime).
+
+---
+
+## HttpRequestActivityInput
+
+Shared by activities and `HttpClient` config (minus `url` / `baseUrl` on client methods):
+
+| Field | Type | Default / notes |
+|-------|------|-----------------|
+| `url` | `string` | Resolved with `new URL(url, baseUrl)` |
+| `baseUrl` | `string?` | Optional base for relative paths |
+| `method` | `HttpMethod?` | `'GET'` |
+| `body` | `{ json }` \| `{ text }` \| `{ form }` | See below |
+| `headers` | `Record<...>?` | Merged with body-derived headers; `auth` sets `Authorization` and overrides a custom `Authorization` header |
+| `auth` | `HttpAuth` \| `{ username, password }` | Basic auth object or subclass with `getAuthorizationHeader()` |
+| `retry` | `boolean` \| retry options | `true` |
+| `redirect` | `'follow' \| 'manual' \| number` | `'follow'` |
+
+**Body shapes** (handled in `AbstractHttpRequestActivity.getContent`):
+
+- `{ json: Serializable }` → `application/json` + `Content-Length`
+- `{ text: string }` → `text/plain` + `Content-Length`
+- `{ form: HttpRequestActivityInputBodyFormData }` → `FormData` (nested keys as `parent[key]`; `Binary` fields get generated filenames; `undefined` / `null` skipped)
+
+Invalid body shape throws `Invalid body`.
+
+**Form values:** `string | number | boolean | null | undefined | Binary | nested object | readonly array of nested form data`.
+
+---
+
+## Making HTTP calls in a workflow
+
+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.
+
+For a typed result, read the response and map with plain TypeScript:
+
+```typescript
+const res = await http.get(`${environments.SERVICE_URL}/data`)
+const data = await res.body.json<MyType>()
+```
+
+See **HttpClient and `http`** and **Response and Body** below.
+
+---
+
+## HttpClient and `http`
+
+`HttpClient` wraps `HttpRequestActivity` via `History.bind`. Calls inside a workflow are **reconciler-driven** (replay-safe); they throw `PushActivity` when history needs a new step.
+
+```typescript
+import { http } from '@t4h.framework/http'
+
+// GET
+const response = await http.get('https://api.example.com/users')
+const users = await response.body.json()
+
+// POST JSON
+await http.post('https://api.example.com/users', {
+  json: { name: 'John', email: 'john@example.com' },
+})
+
+// Base URL client (does not mutate singleton)
+const api = http.extend({ baseUrl: 'https://api.example.com' })
+const list = await api.get('/users')
+
+// Instance with default auth
+const client = new HttpClient({
+  baseUrl: 'https://api.example.com',
+  auth: { username: 'user', password: 'pass' },
+})
+```
+
+Methods: `request(url, config?)`, `get`, `post(url, body, config?)`, `put`, `patch`, `delete`. Per-request `auth` in config merges over client `config.auth`.
+
+Workflow example:
+
+```typescript
+import { Workflow } from '@t4h.framework/core'
+import { http } from '@t4h.framework/http'
+
+export const simple = new Workflow({ id: 'simple' }, async () => {
+  await http.post('https://example.com/webhook', {
+    json: { status: 'ok' },
+  })
+})
+```
+
+---
+
+## Response and Body
+
+`HttpRequestActivity` exposes `Response`:
+
+```typescript
+response.status   // number
+response.headers  // Record<string, string | string[] | undefined>
+response.body     // Body instance
+```
+
+`Body` (backed by `Binary` from filesystem claim):
+
+```typescript
+response.body.contentType
+response.body.contentLength
+await response.body.text()
+await response.body.json<T>()  // only if content-type matches */json or */*+json
+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`.
+
+---
+
+## Authentication
+
+### Basic (inline)
+
+```typescript
+await http.get('https://api.example.com/data', {
+  auth: { username: 'user', password: 'pass' },
+})
+```
+
+### Custom HttpAuth
+
+Subclass `HttpAuth` (extends `SerializableClass`), implement `getAuthorizationHeader()`, and optional `toSerializable` / `fromSerializable` for workflow persistence.
+
+### OAuth2 client credentials
+
+```typescript
+import { http, OAuth2ClientCredentials } from '@t4h.framework/http'
+
+const auth = new OAuth2ClientCredentials({
+  tokenUrl: 'https://auth.example.com/token',
+  clientId: 'my-client-id',
+  clientSecret: 'my-client-secret',
+})
+
+await http.get('https://api.example.com/data', { auth })
+```
+
+### OAuth2 resource owner password
+
+```typescript
+import { OAuth2GrantResourceOwnerPassword } from '@t4h.framework/http'
+
+const auth = new OAuth2GrantResourceOwnerPassword({
+  tokenUrl: 'https://auth.example.com/token',
+  clientId: 'my-client-id',
+  clientSecret: 'my-client-secret',
+  username: 'user',
+  password: 'pass',
+})
+```
+
+OAuth2 flow: POST `application/x-www-form-urlencoded` to `tokenUrl` via `HttpClientRequestClaim`; cache token; refresh with `grant_type=refresh_token` when expired if `refresh_token` present; header format `${token_type} ${access_token}`.
+
+Requires `CacheClaim` + `HttpClientRequestClaim` in the runtime.
+
+---
+
+## Testing
+
+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 { 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'
+
+// Minimal Binary the FileSystemClaim mock returns from write().
+class MockBinary extends Binary {
+  public readonly contentType = 'application/json'
+  public readonly contentLength: number
+
+  constructor(private readonly data: Buffer) {
+    super()
+    this.contentLength = data.byteLength
+  }
+
+  public stream() {
+    return Readable.from(this.data)
+  }
+}
+
+const body = Buffer.from(JSON.stringify({ ok: true }))
+
+// 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),
+}))
+
+const mockWrite = vi.fn().mockImplementation(async () => new MockBinary(body))
+
+const env = TestWorkflowEnvironment.create({ now: 0 })
+
+const output = await env.execute(workflow, input, {
+  claims: [
+    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.
+
+---
+
+## Checklist for agents
+
+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. 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`; **framework-workflow-testing** for the test harness.

package/dist/models/HttpAuth.d.ts

@@ -1,6 +1,5 @@
 import { CacheClaim } from '@t4h.framework/cache';
-import { Claim } from '@t4h.framework/core';
-import { SerializableClass } from '../../../core/dist/models/SerializableHelper.js';
+import { Claim, SerializableClass } from '@t4h.framework/core';
 declare const HTTP_AUTH_CLAIMS_KEY: unique symbol;
 export declare abstract class HttpAuth extends SerializableClass {
     readonly [HTTP_AUTH_CLAIMS_KEY]: Claim<{

package/dist/models/HttpAuth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HttpAuth.d.ts","sourceRoot":"","sources":["../../src/models/HttpAuth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACjD,OAAO,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAA;AAE3C,OAAO,EAAE,iBAAiB,EAAE,MAAM,iDAAiD,CAAA;AAEnF,QAAA,MAAM,oBAAoB,eAA6B,CAAA;AAEvD,8BAAsB,QAAS,SAAQ,iBAAiB;IACtD,SAAgB,CAAC,oBAAoB,CAAC;;OAEpC;aAEc,sBAAsB,IAAI,OAAO,CAAC,MAAM,CAAC;CAC1D"}
+{"version":3,"file":"HttpAuth.d.ts","sourceRoot":"","sources":["../../src/models/HttpAuth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACjD,OAAO,EAAE,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAE9D,QAAA,MAAM,oBAAoB,eAA6B,CAAA;AAEvD,8BAAsB,QAAS,SAAQ,iBAAiB;IACtD,SAAgB,CAAC,oBAAoB,CAAC;;OAEpC;aAEc,sBAAsB,IAAI,OAAO,CAAC,MAAM,CAAC;CAC1D"}

package/dist/models/HttpAuth.js

@@ -1,6 +1,5 @@
 import { CacheClaim } from '@t4h.framework/cache';
-import { Claim } from '@t4h.framework/core';
-import { SerializableClass } from '../../../core/dist/models/SerializableHelper.js';
+import { Claim, SerializableClass } from '@t4h.framework/core';
 const HTTP_AUTH_CLAIMS_KEY = Symbol('http-auth-claims');
 export class HttpAuth extends SerializableClass {
     [HTTP_AUTH_CLAIMS_KEY] = new Claim({

package/dist/models/HttpAuth.js.map

@@ -1 +1 @@
-{"version":3,"file":"HttpAuth.js","sourceRoot":"","sources":["../../src/models/HttpAuth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACjD,OAAO,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAA;AAE3C,OAAO,EAAE,iBAAiB,EAAE,MAAM,iDAAiD,CAAA;AAEnF,MAAM,oBAAoB,GAAG,MAAM,CAAC,kBAAkB,CAAC,CAAA;AAEvD,MAAM,OAAgB,QAAS,SAAQ,iBAAiB;IACtC,CAAC,oBAAoB,CAAC,GAAG,IAAI,KAAK,CAAC;QACjD,KAAK,EAAE,UAAU;KAClB,CAAC,CAAA;CAGH"}
+{"version":3,"file":"HttpAuth.js","sourceRoot":"","sources":["../../src/models/HttpAuth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACjD,OAAO,EAAE,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAE9D,MAAM,oBAAoB,GAAG,MAAM,CAAC,kBAAkB,CAAC,CAAA;AAEvD,MAAM,OAAgB,QAAS,SAAQ,iBAAiB;IACtC,CAAC,oBAAoB,CAAC,GAAG,IAAI,KAAK,CAAC;QACjD,KAAK,EAAE,UAAU;KAClB,CAAC,CAAA;CAGH"}

package/dist/testing/index.d.ts

@@ -0,0 +1,3 @@
+import { HttpClientRequestClaim } from '../models/HttpClientRequestClaim.js';
+export declare function mockHttpClaim(implementation?: Partial<HttpClientRequestClaim>): import("@t4h.framework/core").ClaimProvider<HttpClientRequestClaim>;
+//# 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":"AAIA,OAAO,EACL,sBAAsB,EAEvB,MAAM,qCAAqC,CAAA;AAE5C,wBAAgB,aAAa,CAC3B,cAAc,GAAE,OAAO,CAAC,sBAAsB,CAAM,uEAYrD"}

package/dist/testing/index.js

@@ -0,0 +1,15 @@
+import { Readable } from 'node:stream';
+import { mockClaim } from '@t4h.framework/core/testing';
+import { HttpClientRequestClaim, } from '../models/HttpClientRequestClaim.js';
+export function mockHttpClaim(implementation = {}) {
+    const defaultResponse = {
+        status: 200,
+        headers: { 'content-type': 'application/json' },
+        body: Readable.from(Buffer.from('{}')),
+    };
+    return mockClaim(HttpClientRequestClaim, {
+        request: async () => defaultResponse,
+        ...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,QAAQ,EAAE,MAAM,aAAa,CAAA;AAEtC,OAAO,EAAE,SAAS,EAAE,MAAM,6BAA6B,CAAA;AAEvD,OAAO,EACL,sBAAsB,GAEvB,MAAM,qCAAqC,CAAA;AAE5C,MAAM,UAAU,aAAa,CAC3B,iBAAkD,EAAE;IAEpD,MAAM,eAAe,GAAiC;QACpD,MAAM,EAAE,GAAG;QACX,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;QAC/C,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;KACvC,CAAA;IAED,OAAO,SAAS,CAAC,sBAAsB,EAAE;QACvC,OAAO,EAAE,KAAK,IAAI,EAAE,CAAC,eAAe;QACpC,GAAG,cAAc;KAClB,CAAC,CAAA;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t4h.framework/http",
-  "version": "0.3.0",
+  "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",
@@ -20,7 +20,8 @@
   "types": "./dist/http.d.ts",
   "files": [
     "dist",
-    "LICENSE"
+    "LICENSE",
+    ".ai"
   ],
   "scripts": {
     "build": "tsc --project tsconfig.build.json",
@@ -37,18 +38,18 @@
     "uuidv7": "^1.1.0"
   },
   "devDependencies": {
-    "@t4h.framework/cache": "^0.3.0",
-    "@t4h.framework/core": "^0.3.0",
-    "@t4h.framework/fs": "^0.3.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.3.0",
-    "@t4h.framework/core": "^0.3.0",
-    "@t4h.framework/fs": "^0.3.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": {