http.ts
Source: sdks/typescript/packages/sdk/src/http.ts. Back to the TypeScript SDK reference index.
This page is generated by tools/docs/gen_sdk_reference.py from the SDK sources and the OpenAPI text folders. Do not edit it by hand: change the source and regenerate.
Type alias FetchLike
Signature of a fetch function: URL and init in, Response out.
Definition: (input: string, init?: RequestInit) => Promise<Response>.
Type alias HttpMethod
GET, POST, PUT, PATCH or DELETE.
Definition: "GET" \| "POST" \| "PUT" \| "PATCH" \| "DELETE".
Type alias QueryValue
Value of a query parameter; null and undefined are left out and an array repeats the parameter.
Definition: string \| number \| boolean \| null \| undefined \| string[].
Interface ClientOptions
Options of the HTTP client: base URL, credentials, dev mode headers, retries, timeout and fetch.
Fields:
| Name | Type | Required | Description |
|---|---|---|---|
baseUrl | string | yes | Control Plane base URL, for example <control-plane-url> (without /v1). |
apiKey | string | no | Tenant API key, sent as X-API-Key. |
token | string | (() => string | Promise<string>) | no | OIDC bearer token (string or async provider for refresh). |
tenant | string | no | Dev mode tenant slug, sent as X-Dev-Tenant (only honored when the server runs with EAI_AUTH_DEV=1). |
devUser | string | no | Dev mode user id, sent as X-Dev-User. |
devRoles | string[] | no | Dev mode roles, sent as X-Dev-Roles. |
project | string | no | Identifier of the project the results are restricted to. |
environment | "dev" | "test" | "staging" | "prod" | (string & {}) | no | Environment (dev, test, staging, prod or another name), sent as X-Environment. |
locale | Locale | no | Language of the messages, en (default) or fr, also sent as Accept-Language. |
fetch | FetchLike | no | fetch implementation to use; defaults to the global fetch. |
retries | number | no | Number of retries on 429, 5xx and network errors (default 2). |
retryBaseDelayMs | number | no | Base delay of the exponential backoff in ms (default 300). |
retryMaxDelayMs | number | no | Maximum delay between retries in ms (default 20000). |
timeoutMs | number | no | Per request timeout in ms (default 60000, 0 disables). |
headers | Record<string | no | Extra headers sent with every request. |
sleep | (ms: number) => Promise<void> | no | Sleep function used between retries (injectable for tests). |
Interface RequestOptions
Options of one request: path parameters, query, body, headers, idempotency key, trace, signal and response type.
Fields:
| Name | Type | Required | Description |
|---|---|---|---|
params | Record<string | no | Values of the {name} placeholders of the route. |
query | Record<string | no | Query string parameters; undefined and null values are left out, arrays repeat the parameter. |
body | unknown | no | Body of the request: sent as JSON, or as is for FormData, Blob, ArrayBuffer and URLSearchParams. |
headers | Record<string | no | Headers of the event, string values. The trace context is added. |
idempotencyKey | string | no | Idempotency-Key of a POST; a random one is generated when missing. |
traceparent | string | no | W3C traceparent header to send; a new one is generated when missing. |
signal | AbortSignal | no | AbortSignal that cancels the request. |
responseType | "json" | "text" | "binary" | "stream" | no | Response handling: json (default), text, binary, stream (raw Response). |
noRetry | boolean | no | Disable retries for this call. |
Interface ApiResponse
Decoded body of a response with its HTTP status, headers and request id.
Fields:
| Name | Type | Required | Description |
|---|---|---|---|
data | T | yes | Decoded body of the response. |
status | number | yes | HTTP status of the response. |
headers | Headers | yes | Headers of the event, string values. The trace context is added. |
requestId | string | undefined | yes | Value of the x-request-id response header. |
Class HttpClient
HTTP transport of the SDK: builds the URL and headers, retries 429, 5xx and network errors, and maps errors to typed classes.
Attributes:
| Name | Type | Required | Description |
|---|---|---|---|
baseUrl | string | yes | Base URL without its trailing slashes. |
locale | Locale | yes | Language of the messages and of Accept-Language. |
Constructor HttpClient
new HttpClient(opts: ClientOptions)
Checks the base URL and the fetch implementation; throws missing_base_url, no_fetch or TypeError on a bad URL.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
opts | ClientOptions | yes | Per call options (query, idempotency key, traceparent, headers). |
HttpClient.headers
async headers(method: HttpMethod, o: RequestOptions): Promise<Record<string, string>>
Builds the headers of a request: Accept, Accept-Language, traceparent, credentials, dev mode, project, environment and Idempotency-Key on POST.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
method | HttpMethod | yes | HTTP method; a POST gets an Idempotency-Key. | |
o | RequestOptions | yes | Per call options (idempotency key, traceparent, headers). |
Returns: Promise<Record<string, string>>. The headers, those of the request options last.
HttpClient.raw
async raw(method: HttpMethod, template: string, o: RequestOptions = {}): Promise<ApiResponse<T>>
Performs a request and returns the decoded body with status and headers.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
method | HttpMethod | yes | HTTP method of the request. | |
template | string | yes | Route relative to the base URL, with {name} placeholders filled from params. | |
o | RequestOptions | {} | no | Per call options (idempotency key, traceparent, headers). |
Returns: Promise<ApiResponse<T>>. Body, status, headers and request id; throws the typed EaiError on an error status.
Raises: EaiError.
HttpClient.request
async request(method: HttpMethod, template: string, o: RequestOptions = {}): Promise<T>
Performs a request and returns only the decoded body.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
method | HttpMethod | yes | HTTP method of the request. | |
template | string | yes | Route relative to the base URL, with {name} placeholders filled from params. | |
o | RequestOptions | {} | no | Per call options (idempotency key, traceparent, headers). |
Returns: Promise<T>. Decoded body of the response.
HttpClient.toJSON
toJSON(): Record<string, unknown>
Never exposes the API key or token (console.log, JSON.stringify, util.inspect).
This element takes no parameter.
Returns: Record<string, unknown>. Base URL, locale and the masked API key and token.
HttpClient.transfer
async transfer(url: string, init: RequestInit): Promise<Response>
Transfer to or from a presigned storage URL: the configured fetch, without any platform credential.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
url | string | yes | Presigned storage URL. | |
init | RequestInit | yes | fetch options of the transfer (method, body, headers); redirects are not followed. |
Returns: Promise<Response>. The response; a status of 300 or more throws storage_transfer_failed.
Raises: EaiError.
HttpClient.url
url(template: string, params?: Record<string, string | number>, query?: Record<string, QueryValue>): string
Builds the full URL of a route.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
template | string | yes | Route relative to the base URL, with {name} placeholders. | |
params | Record<string, string | number> | no | Extra fields merged into the request. | |
query | Record<string, QueryValue> | no | Query string parameters of the route. |
Returns: string. Base URL, filled path and query string.
Functions
isLocalHost
isLocalHost(host: string): boolean
True for localhost, 127.0.0.1 and ::1.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
host | string | yes | Host name to check, case insensitive. |
Returns: boolean. True for a local host.
validateBaseUrl
validateBaseUrl(raw: string): URL
Throws unless the URL is https, or http on a local host, without embedded credentials.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
raw | string | yes | Return an ApiResponse (data, status, headers) instead of the decoded body. |
Returns: URL. The parsed URL; throws TypeError otherwise.
Raises: TypeError.
validateWsUrl
validateWsUrl(raw: string): string
Throws unless the URL is wss, or ws on a local host.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
raw | string | yes | Return an ApiResponse (data, status, headers) instead of the decoded body. |
Returns: string. The URL unchanged; throws TypeError otherwise.
Raises: TypeError.
generateTraceparent
generateTraceparent(): string
W3C trace context header value: version 00, random trace id and parent id, sampled.
This element takes no parameter.
Returns: string. A header value of the form 00-<trace id>-<parent id>-01.
generateId
generateId(): string
RFC 4122 version 4 identifier, used for Idempotency-Key.
This element takes no parameter.
Returns: string. A random UUID string.
parseRetryAfter
parseRetryAfter(value: string | null, now = Date.now()): number | undefined
Parses Retry-After (seconds or HTTP date) into milliseconds.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
value | string | null | yes | Value of the Retry-After header. | |
now | Date.now() | no | Current time in milliseconds, used for an HTTP date (default Date.now()). |
Returns: number \| undefined. Delay in milliseconds, at least 0, or undefined when the value is missing or unreadable.
fillPath
fillPath(template: string, params: Record<string, string | number> = {}): string
Fills {name} placeholders. The {path} placeholder keeps its slashes.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
template | string | yes | Route with {name} placeholders; a missing value throws TypeError. | |
params | Record<string, string | number> | {} | no | Extra fields merged into the request. |
Returns: string. The route with the values URL encoded.
Raises: TypeError.
buildQuery
buildQuery(query: Record<string, QueryValue> = {}): string
Builds a query string from a map, leaving out null and undefined and repeating array values.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
query | Record<string, QueryValue> | {} | no | Query string parameters of the route. |
Returns: string. The query string starting with ?, or an empty string.