@t4h.framework/http 0.2.0 → 0.3.1

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

@@ -0,0 +1,402 @@
+---
+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.
+---
+
+# @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,
+  HttpRequestActivity,
+  AbstractHttpRequestActivity,
+  HttpClientRequestClaim,
+  HttpAuth,
+  OAuth2,
+  OAuth2ClientCredentials,
+  OAuth2GrantResourceOwnerPassword,
+  Body,
+  Response,
+  type HttpRequestActivityInput,
+  type HttpRequestActivityOutput,
+  type HttpClientRequestClaimInput,
+  type HttpClientRequestClaimOutput,
+} from '@t4h.framework/http'
+```
+
+## 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
+}
+```
+
+Dev: register a concrete `HttpClientRequestClaim` in the runtime (or mock in tests via `Claim.run`).
+
+### FileSystemClaim (required by activities)
+
+`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`.
+
+### 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`.
+
+---
+
+## 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)`.
+
+### AbstractHttpRequestActivity (custom activities)
+
+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
+
+```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
+  }
+}
+```
+
+Static helpers (for tests or advanced form building):
+
+- `AbstractHttpRequestActivity.getContent(body)`
+- `AbstractHttpRequestActivity.append(form, input, currentKey?)`
+- `AbstractHttpRequestActivity.getFormData(input)`
+
+---
+
+## 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 (`examples/basic/src/workflows/simple.ts`):
+
+```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`).
+
+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
+
+Run package tests: `yarn test` in `packages/http` (Vitest).
+
+### 1. Unit-test activity `run` with mocked claims
+
+Pattern from `AbstractHttpRequestActivity.spec.ts`:
+
+```typescript
+import { Claim } from '@t4h.framework/core'
+import { FileSystemClaim } from '@t4h.framework/fs'
+import { Readable } from 'node:stream'
+import { HttpClientRequestClaim } from '@t4h.framework/http'
+
+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
+
+Pattern from `HttpClient.spec.ts`:
+
+```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
+  }
+}
+
+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
+
+Use `WorkflowTesting.run` with explicit claim providers and spies on mock implementations:
+
+```typescript
+import { WorkflowTesting } from '@t4h.framework/core/testing'
+import { HttpClientRequestClaim, type HttpClientRequestClaimInput } from '@t4h.framework/http'
+
+const mockRequest = vi.fn().mockResolvedValue({ status: 200, headers: {}, body: Readable.from('{}') })
+
+await WorkflowTesting.run(workflow, input, {
+  claims: [
+    { provide: HttpClientRequestClaim, value: { request: mockRequest } as HttpClientRequestClaim },
+    { provide: FileSystemClaim, value: mockFs },
+  ],
+})
+```
+
+Inspect `mockRequest.mock.calls` for URLs, methods, and bodies. See **framework-core** skill for `WorkflowTesting` options.
+
+---
+
+## Checklist for agents
+
+1. Prefer **`http` / `HttpClient`** in workflows unless you need a typed custom activity.
+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__`.
+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`.

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.2.0",
+  "version": "0.3.1",
   "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.2.0",
-    "@t4h.framework/core": "^0.2.0",
-    "@t4h.framework/fs": "^0.2.0",
+    "@t4h.framework/cache": "^0.4.0",
+    "@t4h.framework/core": "^0.7.0",
+    "@t4h.framework/fs": "^0.4.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.2.0",
-    "@t4h.framework/core": "^0.2.0",
-    "@t4h.framework/fs": "^0.2.0"
+    "@t4h.framework/cache": "^0.4.0",
+    "@t4h.framework/core": "^0.7.0",
+    "@t4h.framework/fs": "^0.4.0"
   },
   "packageManager": "yarn@4.12.0",
   "engines": {