ApiClient class

A generic HTTP client to interact with the service API. Uses isomorphic fetch approach that works in both browser and Node.js environments without external dependencies when native fetch is available.

Constructors

ApiClient(ApiClientConfig)

Creates a new HTTP client.

Methods

delete<T>(string, RequestOptions)

Makes a DELETE request.

dispose()

Close this transport to new requests without cancelling in-flight requests. Already-dispatched requests may finish, but refresh/retry continuations cannot send another request after disposal. Calling this more than once has no additional effect.

get<T>(string, RequestOptions)

Makes a GET request.

post<T>(string, any, RequestOptions)

Makes a POST request.

put<T>(string, any, RequestOptions)

Makes a PUT request.

requestRaw(string, { allowProxyPath?: boolean, body?: BodyInit | null, headers?: Record<string, string>, method?: string, signal?: AbortSignal, skipAuth?: boolean, timeout?: number })

Makes a raw HTTP request with streaming support and returns the Response object. Does not parse the response body - allows caller to handle streaming responses.

setAccessTokenCallback(() => string | Promise<string | null> | null)

Sets or updates the access token callback function. This allows attaching a token provider after the ApiClient has been initialized.

setAccessTokenProviderAsync(() => Promise<string | null>)

Installs a dedicated asynchronous access-token provider. When present, this supersedes the access-token callback in the send path, allowing the auth layer to refresh the token before the request is sent (proactive, refresh-before-send). The ApiClient stays auth-agnostic: it only awaits the returned Promise<string | null> and never inspects token expiry.

The provider is skipped (falling back to the access-token callback) when an explicit Authorization header is pinned or skipRetryOn401 is set, so auth/token endpoint self-calls never trigger a proactive refresh.

setAuthExhaustedCallback(() => void)

Sets the callback invoked when a retry after refresh also returns 401.

setReactiveNetFiredCallback(() => void)

Sets a callback invoked whenever the reactive 401 refresh-retry net fires. Intended as a health/telemetry signal: with the proactive refresh-before- send path in place, this should fire rarely (only for failures the skew margin cannot predict), so a rising rate indicates a proactive-path regression.

setRefreshCallback(() => Promise<void>)

Sets or updates the refresh callback function. This allows attaching a refresh handler after the ApiClient has been initialized.

Constructor Details

ApiClient(ApiClientConfig)

Creates a new HTTP client.

new ApiClient(config: ApiClientConfig)

Parameters

config
ApiClientConfig

Client configuration. A non-empty publishableKey is required.

Method Details

delete<T>(string, RequestOptions)

Makes a DELETE request.

function delete<T>(path: string, options?: RequestOptions): Promise<T>

Parameters

path

string

The API endpoint path.

options
RequestOptions

Optional fetch request options.

Returns

Promise<T>

A promise that resolves with the response data.

dispose()

Close this transport to new requests without cancelling in-flight requests. Already-dispatched requests may finish, but refresh/retry continuations cannot send another request after disposal. Calling this more than once has no additional effect.

function dispose()

get<T>(string, RequestOptions)

Makes a GET request.

function get<T>(path: string, options?: RequestOptions): Promise<T>

Parameters

path

string

The API endpoint path.

options
RequestOptions

Optional fetch request options.

Returns

Promise<T>

A promise that resolves with the response data.

post<T>(string, any, RequestOptions)

Makes a POST request.

function post<T>(path: string, data?: any, options?: RequestOptions): Promise<T>

Parameters

path

string

The API endpoint path.

data

any

The request body.

options
RequestOptions

Optional fetch request options.

Returns

Promise<T>

A promise that resolves with the response data.

put<T>(string, any, RequestOptions)

Makes a PUT request.

function put<T>(path: string, data?: any, options?: RequestOptions): Promise<T>

Parameters

path

string

The API endpoint path.

data

any

The request body.

options
RequestOptions

Optional fetch request options.

Returns

Promise<T>

A promise that resolves with the response data.

requestRaw(string, { allowProxyPath?: boolean, body?: BodyInit | null, headers?: Record<string, string>, method?: string, signal?: AbortSignal, skipAuth?: boolean, timeout?: number })

Makes a raw HTTP request with streaming support and returns the Response object. Does not parse the response body - allows caller to handle streaming responses.

function requestRaw(path: string, options?: { allowProxyPath?: boolean, body?: BodyInit | null, headers?: Record<string, string>, method?: string, signal?: AbortSignal, skipAuth?: boolean, timeout?: number }): Promise<Response>

Parameters

path

string

The API endpoint path.

options

{ allowProxyPath?: boolean, body?: BodyInit | null, headers?: Record<string, string>, method?: string, signal?: AbortSignal, skipAuth?: boolean, timeout?: number }

Request options including streaming body support.

Returns

Promise<Response>

A promise that resolves with the raw Response object.

setAccessTokenCallback(() => string | Promise<string | null> | null)

Sets or updates the access token callback function. This allows attaching a token provider after the ApiClient has been initialized.

function setAccessTokenCallback(callback: () => string | Promise<string | null> | null)

Parameters

callback

() => string | Promise<string | null> | null

Function returning or resolving the current token or null.

setAccessTokenProviderAsync(() => Promise<string | null>)

Installs a dedicated asynchronous access-token provider. When present, this supersedes the access-token callback in the send path, allowing the auth layer to refresh the token before the request is sent (proactive, refresh-before-send). The ApiClient stays auth-agnostic: it only awaits the returned Promise<string | null> and never inspects token expiry.

The provider is skipped (falling back to the access-token callback) when an explicit Authorization header is pinned or skipRetryOn401 is set, so auth/token endpoint self-calls never trigger a proactive refresh.

function setAccessTokenProviderAsync(provider: () => Promise<string | null>)

Parameters

provider

() => Promise<string | null>

Async function returning the current access token, or null.

setAuthExhaustedCallback(() => void)

Sets the callback invoked when a retry after refresh also returns 401.

function setAuthExhaustedCallback(callback: () => void)

Parameters

callback

() => void

Function called when auth is exhausted

setReactiveNetFiredCallback(() => void)

Sets a callback invoked whenever the reactive 401 refresh-retry net fires. Intended as a health/telemetry signal: with the proactive refresh-before- send path in place, this should fire rarely (only for failures the skew margin cannot predict), so a rising rate indicates a proactive-path regression.

function setReactiveNetFiredCallback(callback: () => void)

Parameters

callback

() => void

Function called when the reactive net is invoked.

setRefreshCallback(() => Promise<void>)

Sets or updates the refresh callback function. This allows attaching a refresh handler after the ApiClient has been initialized.

function setRefreshCallback(callback: () => Promise<void>)

Parameters

callback

() => Promise<void>

Function that performs token refresh