This version (v0.7) has not been published to npm yet.
Skip to content

Reference / @getenginex/sdk / EnginexClientOptions

EnginexClientOptions ​

Options of createEnginexClient.

Properties ​

autoRefresh? ​

optional autoRefresh?: boolean

Automatic token renewal. Default: true. With false, neither the proactive refresh (before a request, when the access token is close to expiring) nor the reactive one (after a 401) calls POST /auth/refresh: the stored access token is used as is and a 401 reaches the caller unrepaired (auth: 'optional' still retries without a token), without clearing the session or calling onSessionExpired. Use it on server clients (RSC/SSR): renewal is left to the browser or a Route Handler — see Session and tokens. With sessionOwner: 'app', the default becomes false and an explicit true is rejected on creation.


baseUrl? ​

optional baseUrl?: string

Gateway origin. Default '' (same-origin: the app proxies /api to the gateway). Outside the browser it must be absolute, e.g. https://gateway.operator.com. Origin only: the SDK appends /api/v1; a path, query, fragment and credentials in the URL are rejected with CONFIGURATION_ERROR when the client is created.


fetch? ​

optional fetch?: {(input, init?): Promise<Response>; (input, init?): Promise<Response>; }

fetch implementation. Default: globalThis.fetch.

Call Signature ​

(input, init?): Promise<Response>

MDN Reference

Parameters ​
input ​

URL | RequestInfo

init? ​

RequestInit

Returns ​

Promise<Response>

Call Signature ​

(input, init?): Promise<Response>

MDN Reference

Parameters ​
input ​

string | URL | Request

init? ​

RequestInit

Returns ​

Promise<Response>


hooks? ​

optional hooks?: EnginexClientHooks

Observability hooks (logging, metrics, tracing): onRequest/onResponse on each attempt (the initial one and the retry after a renewed 401) and onError once per failed call, with the final error. They never receive headers, tokens, body or the query string — see Extensibility.


locale? ​

optional locale?: string

Language sent in Accept-Language, e.g. pt-BR.


onAccessTokenRejected? ​

optional onAccessTokenRejected?: () => void

Only with sessionOwner: 'app': called when the gateway refuses (401) the current access token on a public call (a 401 for the token: without a code, as the gateway's auth middleware answers, or with TOKEN_EXPIRED/TOKEN_STALE; never a 401 with another code, e.g. INVALID_CREDENTIALS for a wrong current password), so the app can renew the session and store the new tokens in the tokenStore — also on an optional-auth call (e.g. config.get), even when the retry without a token succeeds. It does not fire after client.dispose(). With no arguments, via safeCall (an exception here does not change the call's error). It notifies once per token: a burst of 401s with the same token notifies only once, and a late 401 for a token that was already swapped in the tokenStore does not notify (the request is retried with the current token). A new token that is also refused notifies again. It never fires without a token (the UNAUTHENTICATED before sending). The onError hook remains for observability, one per failed call.

Returns ​

void

Throws ​

CONFIGURATION_ERROR on creation, if given with sessionOwner: 'sdk' (there, use onSessionExpired).

Example ​

ts
createEnginexClient({ sessionOwner: 'app', tokenStore: appStore, onAccessTokenRejected: () => authStore.refresh() })

onSessionChange? ​

optional onSessionChange?: (session) => void

Called when the session changes (login, refresh, logout, another tab).

Parameters ​

session ​

Session

Returns ​

void


onSessionExpired? ​

optional onSessionExpired?: () => void

Called when the session expires and could not be renewed. Only with sessionOwner: 'sdk' (the default): with 'app' the SDK neither renews nor clears the session — see onAccessTokenRejected.

Returns ​

void


onValidationIssue? ​

optional onValidationIssue?: (issue) => void

Called when a response does not match the schema ('warn' mode). Without it, 'warn' mode still warns by default: once per route, via console.warn, with only the route and the field paths — never the response values.

Parameters ​

issue ​

ValidationIssue

Returns ​

void


sessionOwner? ​

optional sessionOwner?: "app" | "sdk"

Who owns the session (stores and renews the tokens). Default: 'sdk'.

  • 'sdk': the SDK stores the tokens on login, renews them (autoRefresh) and clears them on logout or when the renewal is refused (onSessionExpired).
  • 'app': the app already has its own authentication and stores the tokens in the tokenStore itself. The SDK only reads the tokenStore to sign the requests and build session.get(): it never renews (autoRefresh becomes false), and auth.login/auth.logout reject with CONFIGURATION_ERROR without a request. A 401 reaches the caller unrepaired; to renew, use onAccessTokenRejected. Exception: if the app already swapped the token in the tokenStore while the request was in flight, the SDK retries once with the current token (without renewing or storing).

Throws ​

CONFIGURATION_ERROR on creation, with 'app' and autoRefresh: true.

Example ​

ts
createEnginexClient({ sessionOwner: 'app', tokenStore: appStore, onAccessTokenRejected: () => authStore.refresh() })

tenantHost? ​

optional tenantHost?: string

Operator domain (tenant), sent in X-Original-Host. Required outside the browser. In the browser, the header only goes on same-origin calls (default: location.host); on cross-origin calls it is never sent, even with tenantHost, because the gateway's CORS rejects it.


timeoutMs? ​

optional timeoutMs?: number

Timeout in ms per attempt. Default: 20 000. The retry after a 401 (with the renewed token) has its own timeout, as does the refresh.


tokenStore? ​

optional tokenStore?: TokenStore

Where to keep the tokens. Default: memoryTokenStore.


validation? ​

optional validation?: ValidationMode

How to handle responses outside the schema. Default: 'warn' (only the diverging field arrives as it came; a root of another type throws VALIDATION_ERROR). See ValidationMode.


webSocket? ​

optional webSocket?: WebSocketLike

WebSocket implementation for realtime. Default: globalThis.WebSocket (browser, Node 22+). With neither, realtime stays 'unavailable' and subscribe becomes a no-op. Outside the browser, the gateway requires the Origin header of the operator's site, which Node does not send: pass a constructor that adds it (see WebSocketLike).


wsUrl? ​

optional wsUrl?: string

Gateway WebSocket URL for @getenginex/sdk/realtime, e.g. wss://gateway.operator.com/ws. Without it, derived from baseUrl (http→ws, https→wss, + /ws) or, without baseUrl, from the page origin. The SDK appends ?token= with the access token; never include a token here.