Reference / @getenginex/sdk / EnginexClientOptions
EnginexClientOptions
Options of createEnginexClient.
Properties
autoRefresh?
optionalautoRefresh?: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?
optionalbaseUrl?: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?
optionalfetch?: {(input,init?):Promise<Response>; (input,init?):Promise<Response>; }
fetch implementation. Default: globalThis.fetch.
Call Signature
(
input,init?):Promise<Response>
Parameters
input
URL | RequestInfo
init?
RequestInit
Returns
Promise<Response>
Call Signature
(
input,init?):Promise<Response>
Parameters
input
string | URL | Request
init?
RequestInit
Returns
Promise<Response>
hooks?
optionalhooks?: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?
optionallocale?:string
Language sent in Accept-Language, e.g. pt-BR.
onAccessTokenRejected?
optionalonAccessTokenRejected?: () =>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
createEnginexClient({ sessionOwner: 'app', tokenStore: appStore, onAccessTokenRejected: () => authStore.refresh() })onSessionChange?
optionalonSessionChange?: (session) =>void
Called when the session changes (login, refresh, logout, another tab).
Parameters
session
Returns
void
onSessionExpired?
optionalonSessionExpired?: () =>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?
optionalonValidationIssue?: (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
Returns
void
sessionOwner?
optionalsessionOwner?:"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 thetokenStoreitself. The SDK only reads thetokenStoreto sign the requests and buildsession.get(): it never renews (autoRefreshbecomesfalse), andauth.login/auth.logoutreject withCONFIGURATION_ERRORwithout a request. A 401 reaches the caller unrepaired; to renew, useonAccessTokenRejected. Exception: if the app already swapped the token in thetokenStorewhile 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
createEnginexClient({ sessionOwner: 'app', tokenStore: appStore, onAccessTokenRejected: () => authStore.refresh() })tenantHost?
optionaltenantHost?: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?
optionaltimeoutMs?: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?
optionaltokenStore?:TokenStore
Where to keep the tokens. Default: memoryTokenStore.
validation?
optionalvalidation?: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?
optionalwebSocket?: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?
optionalwsUrl?: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.