@btravstack/http-client
@btravstack/http-client
Classes
HttpCancelled
Defined in: packages/http-client/src/contracts.ts:64
The caller cancelled and the connection was destroyed.
Extends
TaggedErrorInstance<"HttpCancelled", { }>
Constructors
Constructor
new HttpCancelled(args): HttpCancelled;Defined in: node_modules/.pnpm/unthrown@5.12.1/node_modules/unthrown/dist/index.d.mts:2386
Parameters
| Parameter | Type |
|---|---|
args | void |
Returns
Inherited from
TaggedError("HttpCancelled").constructor
Properties
HttpClient
Defined in: packages/http-client/src/contracts.ts:100
One policy-bound outbound client per application graph.
Extends
PortInstance<"HttpClient",HttpClientService>
Constructors
Constructor
new HttpClient(): HttpClient;Defined in: packages/di/dist/index.d.mts:15
Returns
Inherited from
Port("HttpClient")<HttpClientService>.constructor
Properties
| Property | Modifier | Type | Inherited from | Defined in |
|---|---|---|---|---|
[ID] | readonly | "HttpClient" | Port("HttpClient").[ID] | packages/di/dist/index.d.mts:11 |
[SERVICE] | readonly | HttpClientService | Port("HttpClient").[SERVICE] | packages/di/dist/index.d.mts:12 |
portId | static readonly | "HttpClient" | Port("HttpClient").portId | packages/di/dist/index.d.mts:16 |
HttpDeadlineExceeded
Defined in: packages/http-client/src/contracts.ts:62
The whole-operation deadline expired and the connection was destroyed.
Extends
TaggedErrorInstance<"HttpDeadlineExceeded", { }>
Constructors
Constructor
new HttpDeadlineExceeded(args): HttpDeadlineExceeded;Defined in: node_modules/.pnpm/unthrown@5.12.1/node_modules/unthrown/dist/index.d.mts:2386
Parameters
| Parameter | Type |
|---|---|
args | void |
Returns
Inherited from
TaggedError("HttpDeadlineExceeded").constructor
Properties
HttpDestinationForbidden
Defined in: packages/http-client/src/contracts.ts:50
At least one resolved address, or a literal address, was private or reserved without approval.
Extends
TaggedErrorInstance<"HttpDestinationForbidden", { }>
Constructors
Constructor
new HttpDestinationForbidden(args): HttpDestinationForbidden;Defined in: node_modules/.pnpm/unthrown@5.12.1/node_modules/unthrown/dist/index.d.mts:2386
Parameters
| Parameter | Type |
|---|---|
args | void |
Returns
Inherited from
TaggedError("HttpDestinationForbidden").constructor
Properties
HttpEncodingRefused
Defined in: packages/http-client/src/contracts.ts:56
The remote server ignored the identity-only encoding requirement.
Extends
TaggedErrorInstance<"HttpEncodingRefused", { }>
Constructors
Constructor
new HttpEncodingRefused(args): HttpEncodingRefused;Defined in: node_modules/.pnpm/unthrown@5.12.1/node_modules/unthrown/dist/index.d.mts:2386
Parameters
| Parameter | Type |
|---|---|
args | void |
Returns
Inherited from
TaggedError("HttpEncodingRefused").constructor
Properties
HttpPolicyInvalid
Defined in: packages/http-client/src/contracts.ts:37
Invalid application policy; contains no input URLs.
Extends
TaggedErrorInstance<"HttpPolicyInvalid", {field: |"origins"|"maxResponseBytes"|"deadlineMs"|"tlsIdentities"|"privateOrigins"; }>
Constructors
Constructor
new HttpPolicyInvalid(args): HttpPolicyInvalid;Defined in: node_modules/.pnpm/unthrown@5.12.1/node_modules/unthrown/dist/index.d.mts:2386
Parameters
| Parameter | Type |
|---|---|
args | object & object |
Returns
Inherited from
TaggedError("HttpPolicyInvalid")<{ readonly field: | "origins" | "maxResponseBytes" | "deadlineMs" | "tlsIdentities" | "privateOrigins"; }>.constructor
Properties
| Property | Modifier | Type | Inherited from | Defined in |
|---|---|---|---|---|
_tag | readonly | "HttpPolicyInvalid" | TaggedError("HttpPolicyInvalid")._tag | node_modules/.pnpm/unthrown@5.12.1/node_modules/unthrown/dist/index.d.mts:2363 |
cause? | public | unknown | TaggedError("HttpPolicyInvalid").cause | node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es2022.error.d.ts:24 |
field | readonly | | "origins" | "maxResponseBytes" | "deadlineMs" | "tlsIdentities" | "privateOrigins" | TaggedError("HttpPolicyInvalid").field | packages/http-client/src/contracts.ts:38 |
message | public | string | TaggedError("HttpPolicyInvalid").message | node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1075 |
name | public | string | TaggedError("HttpPolicyInvalid").name | node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1074 |
stack? | public | string | TaggedError("HttpPolicyInvalid").stack | node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1076 |
HttpPolicyRejected
Defined in: packages/http-client/src/contracts.ts:46
The request was refused before transmission.
Extends
TaggedErrorInstance<"HttpPolicyRejected", {reason:"url"|"scheme"|"credentials"|"origin"|"headers"|"request"; }>
Constructors
Constructor
new HttpPolicyRejected(args): HttpPolicyRejected;Defined in: node_modules/.pnpm/unthrown@5.12.1/node_modules/unthrown/dist/index.d.mts:2386
Parameters
| Parameter | Type |
|---|---|
args | object & object |
Returns
Inherited from
TaggedError("HttpPolicyRejected")<{ readonly reason: "url" | "scheme" | "credentials" | "origin" | "headers" | "request"; }>.constructor
Properties
| Property | Modifier | Type | Inherited from | Defined in |
|---|---|---|---|---|
_tag | readonly | "HttpPolicyRejected" | TaggedError("HttpPolicyRejected")._tag | node_modules/.pnpm/unthrown@5.12.1/node_modules/unthrown/dist/index.d.mts:2363 |
cause? | public | unknown | TaggedError("HttpPolicyRejected").cause | node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es2022.error.d.ts:24 |
message | public | string | TaggedError("HttpPolicyRejected").message | node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1075 |
name | public | string | TaggedError("HttpPolicyRejected").name | node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1074 |
reason | readonly | "url" | "scheme" | "credentials" | "origin" | "headers" | "request" | TaggedError("HttpPolicyRejected").reason | packages/http-client/src/contracts.ts:47 |
stack? | public | string | TaggedError("HttpPolicyRejected").stack | node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1076 |
HttpRedirectRefused
Defined in: packages/http-client/src/contracts.ts:52
A redirect response is never followed. Location is deliberately omitted.
Extends
TaggedErrorInstance<"HttpRedirectRefused", {status:number; }>
Constructors
Constructor
new HttpRedirectRefused(args): HttpRedirectRefused;Defined in: node_modules/.pnpm/unthrown@5.12.1/node_modules/unthrown/dist/index.d.mts:2386
Parameters
| Parameter | Type |
|---|---|
args | object & object |
Returns
Inherited from
TaggedError("HttpRedirectRefused")<{ readonly status: number; }>.constructor
Properties
| Property | Modifier | Type | Inherited from | Defined in |
|---|---|---|---|---|
_tag | readonly | "HttpRedirectRefused" | TaggedError("HttpRedirectRefused")._tag | node_modules/.pnpm/unthrown@5.12.1/node_modules/unthrown/dist/index.d.mts:2363 |
cause? | public | unknown | TaggedError("HttpRedirectRefused").cause | node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es2022.error.d.ts:24 |
message | public | string | TaggedError("HttpRedirectRefused").message | node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1075 |
name | public | string | TaggedError("HttpRedirectRefused").name | node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1074 |
stack? | public | string | TaggedError("HttpRedirectRefused").stack | node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1076 |
status | readonly | number | TaggedError("HttpRedirectRefused").status | packages/http-client/src/contracts.ts:53 |
HttpResponseTooLarge
Defined in: packages/http-client/src/contracts.ts:58
Streaming bytes exceeded the application limit.
Extends
TaggedErrorInstance<"HttpResponseTooLarge", {limit:number; }>
Constructors
Constructor
new HttpResponseTooLarge(args): HttpResponseTooLarge;Defined in: node_modules/.pnpm/unthrown@5.12.1/node_modules/unthrown/dist/index.d.mts:2386
Parameters
| Parameter | Type |
|---|---|
args | object & object |
Returns
Inherited from
TaggedError("HttpResponseTooLarge")<{ readonly limit: number; }>.constructor
Properties
| Property | Modifier | Type | Inherited from | Defined in |
|---|---|---|---|---|
_tag | readonly | "HttpResponseTooLarge" | TaggedError("HttpResponseTooLarge")._tag | node_modules/.pnpm/unthrown@5.12.1/node_modules/unthrown/dist/index.d.mts:2363 |
cause? | public | unknown | TaggedError("HttpResponseTooLarge").cause | node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es2022.error.d.ts:24 |
limit | readonly | number | TaggedError("HttpResponseTooLarge").limit | packages/http-client/src/contracts.ts:59 |
message | public | string | TaggedError("HttpResponseTooLarge").message | node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1075 |
name | public | string | TaggedError("HttpResponseTooLarge").name | node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1074 |
stack? | public | string | TaggedError("HttpResponseTooLarge").stack | node_modules/.pnpm/typescript@6.0.3/node_modules/typescript/lib/lib.es5.d.ts:1076 |
HttpUnavailable
Defined in: packages/http-client/src/contracts.ts:66
DNS, TLS, connection or response framing failed. No raw cause or URL is retained.
Extends
TaggedErrorInstance<"HttpUnavailable", { }>
Constructors
Constructor
new HttpUnavailable(args): HttpUnavailable;Defined in: node_modules/.pnpm/unthrown@5.12.1/node_modules/unthrown/dist/index.d.mts:2386
Parameters
| Parameter | Type |
|---|---|
args | void |
Returns
Inherited from
TaggedError("HttpUnavailable").constructor
Properties
Type Aliases
HttpClientService
type HttpClientService = object;Defined in: packages/http-client/src/contracts.ts:96
The outbound capability an application injects.
Properties
| Property | Modifier | Type | Defined in |
|---|---|---|---|
request | readonly | (request) => AsyncResult<HttpResponse, HttpFailure> | packages/http-client/src/contracts.ts:97 |
HttpFailure
type HttpFailure =
| HttpPolicyRejected
| HttpDestinationForbidden
| HttpRedirectRefused
| HttpEncodingRefused
| HttpResponseTooLarge
| HttpDeadlineExceeded
| HttpCancelled
| HttpUnavailable;Defined in: packages/http-client/src/contracts.ts:68
All modeled failures of an outbound request.
HttpPolicy
type HttpPolicy = object;Defined in: packages/http-client/src/contracts.ts:24
Application-owned approvals. Tenant configuration must never supply or extend this policy.
Properties
| Property | Modifier | Type | Description | Defined in |
|---|---|---|---|---|
deadlineMs | readonly | number | Whole-operation budget in milliseconds, including DNS, TLS, headers and body. | packages/http-client/src/contracts.ts:34 |
maxResponseBytes | readonly | number | Maximum complete response body bytes. Only identity encoding is supported. | packages/http-client/src/contracts.ts:32 |
origins | readonly | readonly string[] | Exact HTTPS origins, including non-default ports. Snapshotted when the client is built. | packages/http-client/src/contracts.ts:26 |
privateOrigins? | readonly | readonly HttpPrivateOrigin[] | Deployment-owned private CIDRs per approved origin; omitted origins remain public-only. | packages/http-client/src/contracts.ts:30 |
tlsIdentities? | readonly | readonly HttpTlsBinding[] | Exact-origin client identities. Sources are captured at construction; credentials may rotate. | packages/http-client/src/contracts.ts:28 |
HttpPrivateOrigin
type HttpPrivateOrigin = object;Defined in: packages/http-client/src/contracts.ts:18
Private network approval for one exact HTTPS origin. Only RFC 1918 and IPv6 unique-local CIDRs are accepted.
Properties
| Property | Modifier | Type | Defined in |
|---|---|---|---|
cidrs | readonly | readonly string[] | packages/http-client/src/contracts.ts:20 |
origin | readonly | string | packages/http-client/src/contracts.ts:19 |
HttpRequest
type HttpRequest = object;Defined in: packages/http-client/src/contracts.ts:78
Deliberately narrow request; no agent, proxy, resolver, TLS or redirect overrides.
Properties
| Property | Modifier | Type | Defined in |
|---|---|---|---|
body? | readonly | string | Uint8Array | packages/http-client/src/contracts.ts:82 |
headers? | readonly | Readonly<Record<string, string>> | packages/http-client/src/contracts.ts:81 |
method? | readonly | "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE" | "OPTIONS" | packages/http-client/src/contracts.ts:80 |
signal? | readonly | AbortSignal | packages/http-client/src/contracts.ts:83 |
url | readonly | string | URL | packages/http-client/src/contracts.ts:79 |
HttpResponse
type HttpResponse = object;Defined in: packages/http-client/src/contracts.ts:90
A complete body within the policy limit; HTTP error statuses remain ordinary responses.
Properties
| Property | Modifier | Type | Defined in |
|---|---|---|---|
body | readonly | Uint8Array | packages/http-client/src/contracts.ts:93 |
headers | readonly | Readonly<Record<string, string>> | packages/http-client/src/contracts.ts:92 |
status | readonly | number | packages/http-client/src/contracts.ts:91 |
HttpTlsBinding
type HttpTlsBinding = object;Defined in: packages/http-client/src/contracts.ts:11
An identity bound to one approved origin. The trusted source is read for every connection.
Properties
| Property | Modifier | Type | Description | Defined in |
|---|---|---|---|---|
credentials | readonly | () => HttpTlsIdentity | Read an atomic credential snapshot from an application-owned secret cache; may throw on failure. | packages/http-client/src/contracts.ts:14 |
origin | readonly | string | - | packages/http-client/src/contracts.ts:12 |
HttpTlsIdentity
type HttpTlsIdentity = object;Defined in: packages/http-client/src/contracts.ts:5
PEM client identity supplied by the application's secret store.
Properties
| Property | Modifier | Type | Defined in |
|---|---|---|---|
cert | readonly | string | packages/http-client/src/contracts.ts:6 |
key | readonly | string | packages/http-client/src/contracts.ts:7 |
passphrase? | readonly | string | packages/http-client/src/contracts.ts:8 |
Functions
createHttpClient()
function createHttpClient(input): Result<HttpClientService, HttpPolicyInvalid>;Defined in: packages/http-client/src/client.ts:200
Build once at the application boundary. Origins and limits are copied, never read from the caller again.
Parameters
| Parameter | Type |
|---|---|
input | HttpPolicy |
Returns
Result<HttpClientService, HttpPolicyInvalid>
httpClient()
function httpClient<Id>(policy): Module<HttpClient, HttpPolicyInvalid, PortInstance<Id, HttpPolicy>>;Defined in: packages/http-client/src/provider.ts:8
Provide an observed outbound capability from an application-owned policy port.
Type Parameters
| Type Parameter |
|---|
Id extends string |
Parameters
| Parameter | Type |
|---|---|
policy | PortClassOf<Id, HttpPolicy> |
Returns
Module<HttpClient, HttpPolicyInvalid, PortInstance<Id, HttpPolicy>>
httpClientFetch()
function httpClientFetch(client): (input, init?) => Promise<Response>;Defined in: packages/http-client/src/fetch.ts:9
Adapt this boundary to the platform fetch protocol (including openid-client's customFetch). Unsupported Request objects, streaming bodies and fetch transport overrides are refused. This is the edge where Result failures reject for the upstream fetch consumer.
Parameters
| Parameter | Type |
|---|---|
client | HttpClientService |
Returns
(input, init?) => Promise<Response>