t4h-framework-http

name	t4h-framework-http
description	How to use @t4h.framework/http HttpClient, http singleton, HttpRequestActivityInput, HttpAuth, OAuth2, HttpClientRequestClaim. Use when calling HTTP from workflows or extending OAuth2.

@t4h.framework/http

HttpClient methods go through HttpRequestActivity (History.bind): each call performs an HTTP request via HttpClientRequestClaim and writes the response body through FileSystemClaim for the returned Body.

Dependencies

Install @t4h.framework/cache, @t4h.framework/core, and @t4h.framework/fs together with this package.

Default client: http

http is a singleton Http (extends HttpClient) with empty config. extend(partialConfig) returns a new HttpClient merged with HttpClientConfig.

HttpClientConfig

Field	Purpose
baseUrl	Optional base for new URL(url, baseUrl).
auth	HttpAuth or { username, password } (Basic Authorization header).

HttpClient methods

request(url, config?) merges url, client auth / baseUrl, and HttpRequestActivityInput fields.

get, post, put, patch, delete set method (and body where applicable). get has no body.

HttpRequestActivityInput

Field	Notes
url	Required (path or absolute URL).
baseUrl	Overrides client default when set.
method	Defaults to GET in the activity if omitted.
body	{ json: Serializable }, { text: string }, or { form: nested object } (supports Binary, nesting).
headers	Record<string, string | string[] | undefined>.
auth	Same as HttpClientConfig.auth → Authorization header.
redirect	'follow' | 'manual' | number; default 'follow'.
retry	true (default) or HttpRequestActivityInputRetryOptions (limit, methods, status, backoffLimit, jitter, …).

HttpAuth

Abstract: implement getAuthorizationHeader() (full value, e.g. Bearer …). The base class wires a Claim that includes CacheClaim (used by OAuth2 for token storage).

OAuth2

OAuth2<TConfig extends OAuth2Config> extends HttpAuth, uses HttpClientRequestClaim + CacheClaim. OAuth2Config: tokenUrl, clientId. Default toToken(): POST application/x-www-form-urlencoded from toTokenBody(), JSON response as OAuth2Token, cache key oauth2:token:${clientId}, TTL from expires_in, refresh via refresh_token when present and expired.

Class	Behavior
OAuth2ClientCredentials	grant_type: client_credentials + client_secret.
OAuth2GrantResourceOwnerPassword	grant_type: password + clientSecret, username, password (on top of OAuth2Config).

OAuth2Token: access_token, optional refresh_token, expires_in, token_type.

HttpClientRequestClaim

request(input: HttpClientRequestClaimInput): url is a URL; body: Buffer, FormData, Readable, URLSearchParams, or undefined; headers, redirect, retry. Response: status, headers, body as Readable.

Override toToken() in OAuth2 subclasses when the token endpoint expects something other than form body (then call this.claims.http.request(...)).

Example: force-manual-process

micro-services/force-manual-process/src/workflows/service-tabulate.ts: http.patch with auth. LapisLazuliOAuth2ClientCredentials (extends OAuth2ClientCredentials) overrides toToken() to POST JSON to the token URL and parse OAuth2Token.