The client surface
Every property and method of an AtomicClient, in one place — config, auth, http, api.
A client is four things bolted onto one context: its configuration, its session, a raw HTTP layer, and the typed API. Nothing else.
@experimental
createAtomicClient, getDefaultClient, AtomicApi and AtomicContext carry the @experimental tag in the
source. The shape may still change before it replaces the free functions. It is nonetheless the voice this
documentation teaches, because it is the only one that supports more than one backend — see
The client.
Creating one
function createAtomicClient(config: AtomicClientConfig): AtomicClient;
function getDefaultClient(): AtomicClient; // the one the free functions useAtomicClientConfig is Partial<AppGlobalConfig> — every configuration key, all optional — minus the three
deprecated booleans (useCredentials, useSSO, useSAML, which are getters on globalConfig and have no
client equivalent), plus two keys of its own:
Prop
Type
Every key is optional, app included: initializeConfig() derives app and backendUrl from the browser URL
(/app/<name>) when they are missing. See Configuration for the keys themselves.
Top level
Prop
Type
client.auth
Prop
Type
The five events
on is the least discoverable part of the surface, so here is the whole of it:
| Event | Payload | Fires when |
|---|---|---|
authenticated | { authenticated: boolean } | A sign-in completes — or fails. Read the payload |
unauthorized | { endpoint, error } | A request came back 401, just before it throws |
requestFailed | { endpoint, status, error } | Any request ended on an error status, 401 included |
tokenRefreshed | { token } | A token was stored, the sliding refresh included — so it is chatty |
loggedOut | {} | logout() completed its local cleanup |
// Returns the unsubscribe. Keep it: a component that forgets it leaks a listener.
const stop = client.auth.on("requestFailed", ({ endpoint, status }) => {
console.warn(`${endpoint} answered ${status}`);
});
stop();A handler that throws is swallowed on purpose: an observer must never break the flow it observes.
Two things on is not for. Recovering a session on a 401 is auth.recoverFromUnauthorized, which also
replays the request — unauthorized only lets you watch it happen
(Handling a 401). And a per-request failure handler is options, not a global
subscription.
Worked examples in all three languages: Session lifecycle for the sign-in state,
Errors for requestFailed. The free-function equivalent is onAuthEvent(name, handler),
subscribing on the default client.
client.http
Five verbs, all generic in the response type, all going through the same authentication, retry and error handling as the typed API.
get<T>(endpoint, params?: URLSearchParams, options?: RequestOptions): Promise<T>;
post<T>(endpoint, body: Record<string, unknown>, options?: RequestOptions): Promise<T>;
put<T>(endpoint, body: Record<string, unknown>, options?: RequestOptions): Promise<T>;
patch<T>(endpoint, body: Record<string, unknown>, options?: RequestOptions): Promise<T>;
del<T>(endpoint, params?: URLSearchParams, options?: DeleteOptions): Promise<T>;del takes DeleteOptions, which is RequestOptions plus a body — a few Sinequa delete endpoints expect
one. Details and RequestOptions in The HTTP layer.
client.api
Twelve namespaces. Each method is the free function of the same name with its trailing context parameter
removed — so client.api.query.search(query) is fetchQuery(query, ctx).
client.api.version is the odd one: a function directly, where every sibling is an object.
Endpoints has the same list with the REST path, the free function and the return type in one table.
Typing a wrapper
AtomicApi and AtomicClient are both exported, so a service can be typed without repeating the shape:
import type { AtomicApi, AtomicClient } from "@sinequa/atomic";
// The whole client, when the wrapper needs auth or configuration too.
export function createSearchService(client: AtomicClient) { /* … */ }
// Just the API, when it does not — narrower, and untestable code cannot creep in.
export function createQueries(api: AtomicApi) { /* … */ }