@sinequa/atomic 2.4.0 → 2.5.0

package/README.md

@@ -1,406 +1,406 @@
-<div align="center">
-
-<img src="https://img.shields.io/npm/v/@sinequa/atomic?style=for-the-badge&color=0ea5e9&label=@sinequa%2Fatomic" alt="npm version" />
-<img src="https://img.shields.io/badge/TypeScript-7.x-3178c6?style=for-the-badge&logo=typescript&logoColor=white" alt="TypeScript" />
-<img src="https://img.shields.io/badge/ESM-ready-f59e0b?style=for-the-badge" alt="ESM" />
-<img src="https://img.shields.io/badge/SPFx-ready-0078d4?style=for-the-badge&logo=microsoftsharepoint&logoColor=white" alt="SPFx" />
-
-<br /><br />
-
-# `@sinequa/atomic`
-
-**The TypeScript-first SDK for the Sinequa REST API.**  
-Authentication, search, aggregations, datasets, preview — everything typed, tree-shakable, zero runtime dependencies.  
-SPFx-ready via the `@sinequa/atomic/spfx` subpath export.
-
-[Docs](./docs/index.mdx) · [Get started](./docs/start/index.mdx) · [Reference](./docs/reference/index.mdx)
-
-</div>
-
----
-
-## Installation
-
-```bash
-npm install @sinequa/atomic
-```
-
-> Requires **Node ≥ 18** or any modern browser. Ships as ESM (`atomic.js`) and CJS (`atomic.cjs`) with full `.d.ts` declarations.
-
-For **SharePoint Framework** web parts, `@microsoft/sp-http` is an optional peer dependency — install it only if you need it:
-
-```bash
-npm install @microsoft/sp-http --save-peer
-```
-
----
-
-## At a glance
-
-```typescript
-import { setGlobalConfig, isAuthenticated, login, fetchQuery } from '@sinequa/atomic';
-
-setGlobalConfig({ app: 'my-app', backendUrl: 'https://my-sinequa-server.example.com' });
-
-if (!isAuthenticated()) {
-  await login({ username: 'alice', password: 's3cr3t' });
-}
-
-// A query is a plain object; only `name` — the query web service — is required.
-const result = await fetchQuery({ name: '<your-query>', text: 'knowledge management', pageSize: 10 });
-
-// One round-trip: the documents are in `records`, the facet counts in `aggregations`.
-// Check `$error` before concluding anything from an empty `records`.
-const { records, aggregations, $error } = result;
-```
-
-`fetchAggregation(aggregation, query)` is for **paging** an aggregation you already received — it
-takes the `Aggregation` object off `result.aggregations` and the same query, as two positional
-arguments. See [Aggregations](./docs/search/aggregations.mdx).
-
----
-
-## SharePoint Framework (SPFx)
-
-In an SPFx web part, all HTTP requests must go through the `AadHttpClient` so the Azure AD bearer
-token is attached automatically. Import from the `./spfx` subpath and call
-`initializeAadHttpClient` once during web part initialization:
-
-```typescript
-import { initializeAadHttpClient, fetchQuery } from '@sinequa/atomic/spfx';
-import { AadHttpClient } from '@microsoft/sp-http';
-
-// In your web part's onInit():
-const client = await this.context.aadHttpClientFactory
-  .getClient('https://my-sinequa-server.example.com');
-initializeAadHttpClient(client);
-
-// All subsequent API calls route through AadHttpClient automatically:
-const results = await fetchQuery({ name: '<your-query>', text: 'knowledge management' });
-```
-
-Call `initializeAadHttpClient(null)` to detach the client (e.g. in `onDispose`).
-
-> The `./spfx` subpath re-exports everything from `@sinequa/atomic` and adds
-> `initializeAadHttpClient`, `aadHttpClientManager`, `createSpfxHttpAdapter`, `AadHttpClientLike`
-> and `AadHttpResponseLike`. `initializeAadHttpClient` registers the client globally for the free
-> functions; `createSpfxHttpAdapter(aadHttpClient)` is the same transport as an `httpAdapter` for
-> `createAtomicClient`. Standard (non-SPFx) consumers use `@sinequa/atomic` directly — no changes
-> needed. See [SPFx](./docs/integration/spfx.mdx).
-
----
-
-## Modules
-
-### Client (experimental)
-
-`createAtomicClient(config)` returns an isolated client — its own configuration, session and event
-subscribers — exposing `client.config`, `client.configure()`, `client.initializeConfig()`,
-`client.auth`, `client.http` and `client.api` (the typed endpoints, e.g.
-`client.api.query.search(query)`). Several clients can target different backends from the same page,
-and each takes its transport and auth knobs as configuration (`httpAdapter`, and
-`auth: { fetch, storage, logger }`), which removes the need for module mocks in tests.
-
-```typescript
-import { createAtomicClient } from '@sinequa/atomic';
-
-const client = createAtomicClient({ app: 'myapp', backendUrl: 'https://backend' });
-client.auth.on('unauthorized', () => client.auth.login());
-const results = await client.http.post('api/v1/search.query', { text: 'hello' });
-```
-
-The free functions below keep working unchanged: they run on a default client whose configuration
-**is** `globalConfig`, and `getDefaultClient()` hands back that very instance — useful from code
-that cannot receive one (a distributed web component, a plugin).
-See [The client](./docs/core/client.mdx) and [Multiple backends](./docs/integration/multiple-backends.mdx).
-
-### Authentication
-
-Full auth lifecycle — from first handshake to logout.
-
-| Export | Description |
-|---|---|
-| `isAuthenticated()` | Synchronous. `true` when a CSRF token is stored **or** a token-less session was recorded (ambient SSO issues no client token) |
-| `hasSession()` | Asks the server when nothing is stored, and never redirects — unlike `login()` |
-| `login(credentials?)` | Login — switches on the resolved `authMode` (credentials / SSO / OAuth / SAML / bearer / unknown) |
-| `logout()` | Clears session, returns the server's `redirectUrl` |
-| `clearSessionTokens()` | Drops the local session (tokens, token-less flag) and emits `authenticated: false`, without a server round-trip |
-| `detectAuthMode(config, preLogin?)` | Pure resolution of the `AuthMode` from config + server pre-login (no I/O) |
-| `getToken()` / `setToken(token)` | Read/write the stored CSRF token |
-| `requestWebTokenSession(credentials?)` | POSTs `security.webtoken`. The JWT lands in a cookie; the returned (and stored) value is the **CSRF token**. Omit the credentials to use the configured bearer token |
-| `getCsrfToken()` | CSRF token for mutating requests |
-| `deleteWebTokenCookie()` | Explicitly removes the web token cookie |
-| `onAuthEvent(event, handler)` | Typed subscription to the auth lifecycle (`authenticated`, `unauthorized`, `requestFailed`, `tokenRefreshed`, `loggedOut`) — returns the unsubscribe function |
-| `tryAutoAuthentication()` | Probes a protected endpoint for server-side auto-authentication (OIDC, IIS Negotiate) — used by `login()` in `sso`, `unknown` and `bearer` modes. Never throws |
-| `isRedirectPending()` | Whether an OAuth/SAML redirect is in flight and has not established a session yet |
-| `tryOAuthAuthentication()` / `trySAMLAuthentication()` | Redirect to the configured identity provider (with a one-shot redirect-loop guard) |
-| `emitAuthenticatedEvent(bool)` | Dispatches the DOM `'authenticated'` CustomEvent (on `document`, bubbles to `window`) |
-
-> `getJWToken` is **`@deprecated`**: it is an alias of `requestWebTokenSession`, renamed because the
-> old name suggested it returned the JWT. It will be removed in the next major.
-
-The authentication layer is configurable via `setGlobalConfig({ auth: { … } })` (`AuthOptions`):
-`timeoutMs`, `probeEndpoint`, injectable `storage`/`logger`/`fetch`, the requests' `credentials`
-mode, and `recoverFromUnauthorized` — the hook that re-establishes a session after a 401 and gets
-the request replayed once. See [Authentication](./docs/auth/index.mdx) and
-[Handling 401](./docs/auth/handling-401.mdx).
-
-```typescript
-import { isAuthenticated, login, logout } from '@sinequa/atomic';
-
-if (!isAuthenticated()) {
-  // Auto-resolve: reuse an existing session if any, otherwise follow the resolved
-  // `authMode` — in `unknown` mode, probe for SSO then fall back to the credentials form.
-  const ok = await login();
-
-  // — or — explicit credentials, which bypass mode detection entirely.
-  const okWithCredentials = await login({ username: 'alice', password: 's3cr3t' });
-}
-
-const redirectUrl = await logout();
-```
-
-#### Auth mode (`AuthMode`) — **2.0**
-
-`globalConfig.authMode` is the **single source of truth** for the authentication method. It is a
-typed discriminated union — no more juggling overlapping booleans:
-
-```typescript
-import { AuthMode, globalConfig, setGlobalConfig } from '@sinequa/atomic';
-
-setGlobalConfig({ authMode: AuthMode.credentials() });        // username/password form
-setGlobalConfig({ authMode: AuthMode.sso() });                // browser/proxy-injected auth
-setGlobalConfig({ authMode: AuthMode.oauth('my-provider') }); // redirect to an OAuth provider
-setGlobalConfig({ authMode: AuthMode.saml('my-provider') });  // redirect to a SAML provider
-setGlobalConfig({ authMode: AuthMode.bearer(token) });        // server-to-server bearer token
-setGlobalConfig({ authMode: AuthMode.unknown() });            // try SSO, then fall back to credentials
-
-// `login()` and `detectAuthMode()` branch on `authMode.kind`. Every key of `globalConfig` is
-// optional, so read it through `?.` — the default is `AuthMode.unknown()`.
-const kind = globalConfig.authMode?.kind; // 'credentials' | 'sso' | 'oauth' | 'saml' | 'bearer' | 'unknown'
-```
-
-> **Migrating from 1.x:** the booleans `useCredentials` / `useSSO` / `useSAML` are now
-> **`@deprecated` read-only getters** derived from `authMode`. Reading them still works, and writing
-> them through `setGlobalConfig({ useSSO: true })` is translated into the matching `authMode` — so
-> existing code keeps working. Prefer `authMode.kind` (and the `AuthMode.*` constructors) in new code.
-> Full upgrade notes: [Migrating from 1.x](./docs/reference/migrating-from-1x.mdx).
-
----
-
-### Web API — v1
-
-Every Sinequa v1 endpoint has a typed wrapper.
-
-```typescript
-import {
-  fetchApp,
-  fetchAppPreLogin,
-  fetchQuery,
-  fetchBulkQuery,
-  fetchAggregation,
-  fetchDataset,
-  fetchPreview,
-  fetchPrincipal,
-  fetchSimilarDocuments,
-  fetchSponsoredLinks,
-  fetchSuggest,
-  fetchTextChunks,
-  fetchUserSettings,
-  fetchLabels,
-  fetchQueryExport,
-  fetchQueryIntent,
-  searchPrincipals,
-} from '@sinequa/atomic';
-```
-
-Auditing is not a `fetch*` function: use `Audit.notify(...)`, plus the record decorators
-`addAuditAdditionalInfo`, `addSessionId` and `addUrl`. See [Audit](./docs/integration/audit.mdx).
-
-### Web API — v2
-
-```typescript
-import {
-  fetchUserProfile,
-  fetchVersion,
-  fetchChangePassword,
-  fetchSendPasswordResetEmail,
-} from '@sinequa/atomic';
-```
-
-The full endpoint list — with the `client.api` method and the free function for each — is in
-[Endpoints](./docs/reference/endpoints.mdx).
-
----
-
-### Helpers
-
-Utilities for transforming Sinequa data structures.
-
-```typescript
-import {
-  getMetadata,           // metadata of an article as `string[]` (splits comma-separated values)
-  getMetadataWithValues, // same, as `{ display, value }[]`
-  makeColumn,
-  extraColumns,
-  resolveToColumnName,
-  resultPages,
-  escapeExpr,
-  guid,
-  isObject,
-} from '@sinequa/atomic';
-```
-
-More in [Helpers](./docs/reference/helpers.mdx).
-
-#### Filter builder
-
-Build structured `query.filters` without hand-writing filter objects. Combinators ignore falsy
-operands and collapse trivial cases (0 → `undefined`, 1 → the operand itself), so filters compose
-cleanly from optional UI state:
-
-```typescript
-import { filter, fetchQuery } from '@sinequa/atomic';
-
-const filters = filter.and(
-  filter.gt('size', 1000),
-  filter.or(
-    filter.eq('treepath', '/HR/*'),
-    filter.in('authors', ['alice', 'bob']),
-  ),
-  onlyRecent && filter.between('modified', '2024-01-01', '2024-12-31'),
-);
-
-await fetchQuery({ name: '<your-query>', text: 'report', filters });
-```
-
-Leaf operators: `eq` · `neq` · `gt` · `gte` · `lt` · `lte` · `like` · `contains` · `regex` · `isNull` · `isNotNull` · `in` · `between`. Combinators: `and` · `or` · `not`.
-
-`filter.distribution(field, item.value)` handles the one case the leaf operators cannot: a
-**distribution** aggregation item (a date or size bucket), whose `value` is an expression the server
-built rather than a value. Passing it to `filter.eq` makes the backend answer
-`500 — "Field type error"`. See [Filters](./docs/search/filters.mdx).
-
----
-
-### Utilities
-
-```typescript
-import {
-  bisect,
-  sysLang,                     // resolves `all[fr]tous[de]alle` against a locale
-  getRelativeDate,             // and `getOffsetFromDates`
-  getQueryParamsFromUrl,       // and `getUrlParamsFromQueryParams`, `getFiltersFromUrl`, …
-  addConcepts,                 // and `getConcepts`, `parseText`, `rewriteText`, `removeConcept(s)`
-  notify,
-  configureLogger,             // and the `debug` / `info` / `warn` / `error` bindings, `LogLevel`
-} from '@sinequa/atomic';
-```
-
-> The library's verbosity is set with `configureLogger({ level: LogLevel.DEBUG })`, **not** through
-> a configuration key. See [Logging](./docs/integration/logging.mdx) and
-> [URL state](./docs/search/url-state.mdx).
-
----
-
-## Types
-
-The package re-exports every Sinequa domain type so you never need to cast:
-
-```typescript
-import type {
-  CCApp, CCQuery, CCColumn, CCIndex,
-  Aggregation, AggregationItem, ListAggregation, TreeAggregation,
-  Filter, SimpleFilter, InFilter, BetweenFilter, ExprFilter, NullFilter, NotNullFilter,
-  AuthMode, AuthModeKind,
-  PreviewData,
-  Principal,
-  AuditEvent, AuditRecord,
-  TextChunk,
-} from '@sinequa/atomic';
-```
-
-Which type comes back from which call: [Type map](./docs/reference/types-map.mdx).
-
----
-
-## Configuration
-
-Set the backend URL before making any API call (required when the Sinequa server is not
-same-origin). `setGlobalConfig` performs a shallow merge into `globalConfig`:
-
-```typescript
-import { setGlobalConfig, globalConfig, AuthMode } from '@sinequa/atomic';
-
-setGlobalConfig({
-  app: 'my-app',
-  backendUrl: 'https://my-sinequa-server.example.com',
-  authMode: AuthMode.unknown(), // optional — defaults to `unknown`
-});
-
-// read it back — every key is optional on `globalConfig`, so `?.` is required
-console.log(globalConfig.backendUrl, globalConfig.authMode?.kind);
-```
-
-Call `initializeAppConfig()` once at bootstrap: it fills in `backendUrl`/`app` from the browser URL
-when they were not provided, then resolves the `authMode` from the server's pre-login response.
-
-> `appInitializerFn` is a **`@deprecated`** alias of `initializeAppConfig` — use the latter.
-
-Three declared keys are read by nothing, and setting them has no effect: `logLevel` (set the level
-with `configureLogger({ level })`), `loginPath` (routing is yours — use `recoverFromUnauthorized` or
-the `unauthorized` event) and `createRoutes`. Every key, with its default:
-[Configuration keys](./docs/reference/config-keys.mdx).
-
----
-
-## Testing
-
-```bash
-npm test                    # vitest, watch mode
-npm test -- --watch=false   # single run (what CI does)
-```
-
-`--ui` is not available out of the box: `@vitest/ui` is an optional peer of vitest and is not
-installed here — `npm i -D @vitest/ui` first.
-
-Coverage is deepest on authentication (`AuthMode` detection, OAuth, SAML, credentials, tokens,
-401 recovery) and on the HTTP helpers. On the endpoints it is targeted rather than exhaustive —
-`fetchQuery`, `fetchAggregation`, `fetchPrincipal`, `searchPrincipals`, `fetchApp` and the
-document-upload containers. Also covered: the filter builder, metadata parsing, column resolution,
-pagination, date utilities and the SQL value helper.
-
-Injecting `fetch`, `storage` and `logger` through the configuration is what lets a test avoid module
-mocks — see [Testing](./docs/integration/testing.mdx).
-
----
-
-## Development
-
-```bash
-npm run build        # production build (vite + tsc)
-npm run watch        # rebuild on change
-npm run dev:pack     # build + pack locally
-```
-
----
-
-## Contributing
-
-1. All tests must pass.
-2. Lint with [Biome](https://biomejs.dev/) — `npx @biomejs/biome check --write .`
-3. Follow [Conventional Commits](https://www.conventionalcommits.org/).
-4. Any change touching `src/` needs a **changeset** in the same commit (`npm run changeset`, then
-   `npm run changeset:status` to check) — the `changeset-check` CI job blocks the merge without one.
-   Add `#skip-changeset` to the MR title for a change that does not touch the published library.
-   Full guide, with examples: [`docs/CONTRIBUTING-changesets.md`](./docs/CONTRIBUTING-changesets.md).
-5. New public API → add tests + JSDoc, and export it from `src/index.ts` (a helper that is written
-   and tested but not re-exported from the barrel is not part of the public API).
-
----
-
-<div align="center">
-
-Built for the [Sinequa](https://www.sinequa.com/) ecosystem · [Report an issue](https://gitlab.chapsvision.in/sinequa/rnd/sba-atomic-js/-/issues)
-
-</div>
+<div align="center">
+
+<img src="https://img.shields.io/npm/v/@sinequa/atomic?style=for-the-badge&color=0ea5e9&label=@sinequa%2Fatomic" alt="npm version" />
+<img src="https://img.shields.io/badge/TypeScript-7.x-3178c6?style=for-the-badge&logo=typescript&logoColor=white" alt="TypeScript" />
+<img src="https://img.shields.io/badge/ESM-ready-f59e0b?style=for-the-badge" alt="ESM" />
+<img src="https://img.shields.io/badge/SPFx-ready-0078d4?style=for-the-badge&logo=microsoftsharepoint&logoColor=white" alt="SPFx" />
+
+<br /><br />
+
+# `@sinequa/atomic`
+
+**The TypeScript-first SDK for the Sinequa REST API.**  
+Authentication, search, aggregations, datasets, preview — everything typed, tree-shakable, zero runtime dependencies.  
+SPFx-ready via the `@sinequa/atomic/spfx` subpath export.
+
+[Docs](./docs/index.mdx) · [Get started](./docs/start/index.mdx) · [Reference](./docs/reference/index.mdx)
+
+</div>
+
+---
+
+## Installation
+
+```bash
+npm install @sinequa/atomic
+```
+
+> Requires **Node ≥ 18** or any modern browser. Ships as ESM (`atomic.js`) and CJS (`atomic.cjs`) with full `.d.ts` declarations.
+
+For **SharePoint Framework** web parts, `@microsoft/sp-http` is an optional peer dependency — install it only if you need it:
+
+```bash
+npm install @microsoft/sp-http --save-peer
+```
+
+---
+
+## At a glance
+
+```typescript
+import { setGlobalConfig, isAuthenticated, login, fetchQuery } from '@sinequa/atomic';
+
+setGlobalConfig({ app: 'my-app', backendUrl: 'https://my-sinequa-server.example.com' });
+
+if (!isAuthenticated()) {
+  await login({ username: 'alice', password: 's3cr3t' });
+}
+
+// A query is a plain object; only `name` — the query web service — is required.
+const result = await fetchQuery({ name: '<your-query>', text: 'knowledge management', pageSize: 10 });
+
+// One round-trip: the documents are in `records`, the facet counts in `aggregations`.
+// Check `$error` before concluding anything from an empty `records`.
+const { records, aggregations, $error } = result;
+```
+
+`fetchAggregation(aggregation, query)` is for **paging** an aggregation you already received — it
+takes the `Aggregation` object off `result.aggregations` and the same query, as two positional
+arguments. See [Aggregations](./docs/search/aggregations.mdx).
+
+---
+
+## SharePoint Framework (SPFx)
+
+In an SPFx web part, all HTTP requests must go through the `AadHttpClient` so the Azure AD bearer
+token is attached automatically. Import from the `./spfx` subpath and call
+`initializeAadHttpClient` once during web part initialization:
+
+```typescript
+import { initializeAadHttpClient, fetchQuery } from '@sinequa/atomic/spfx';
+import { AadHttpClient } from '@microsoft/sp-http';
+
+// In your web part's onInit():
+const client = await this.context.aadHttpClientFactory
+  .getClient('https://my-sinequa-server.example.com');
+initializeAadHttpClient(client);
+
+// All subsequent API calls route through AadHttpClient automatically:
+const results = await fetchQuery({ name: '<your-query>', text: 'knowledge management' });
+```
+
+Call `initializeAadHttpClient(null)` to detach the client (e.g. in `onDispose`).
+
+> The `./spfx` subpath re-exports everything from `@sinequa/atomic` and adds
+> `initializeAadHttpClient`, `aadHttpClientManager`, `createSpfxHttpAdapter`, `AadHttpClientLike`
+> and `AadHttpResponseLike`. `initializeAadHttpClient` registers the client globally for the free
+> functions; `createSpfxHttpAdapter(aadHttpClient)` is the same transport as an `httpAdapter` for
+> `createAtomicClient`. Standard (non-SPFx) consumers use `@sinequa/atomic` directly — no changes
+> needed. See [SPFx](./docs/integration/spfx.mdx).
+
+---
+
+## Modules
+
+### Client (experimental)
+
+`createAtomicClient(config)` returns an isolated client — its own configuration, session and event
+subscribers — exposing `client.config`, `client.configure()`, `client.initializeConfig()`,
+`client.auth`, `client.http` and `client.api` (the typed endpoints, e.g.
+`client.api.query.search(query)`). Several clients can target different backends from the same page,
+and each takes its transport and auth knobs as configuration (`httpAdapter`, and
+`auth: { fetch, storage, logger }`), which removes the need for module mocks in tests.
+
+```typescript
+import { createAtomicClient } from '@sinequa/atomic';
+
+const client = createAtomicClient({ app: 'myapp', backendUrl: 'https://backend' });
+client.auth.on('unauthorized', () => client.auth.login());
+const results = await client.http.post('api/v1/search.query', { text: 'hello' });
+```
+
+The free functions below keep working unchanged: they run on a default client whose configuration
+**is** `globalConfig`, and `getDefaultClient()` hands back that very instance — useful from code
+that cannot receive one (a distributed web component, a plugin).
+See [The client](./docs/core/client.mdx) and [Multiple backends](./docs/integration/multiple-backends.mdx).
+
+### Authentication
+
+Full auth lifecycle — from first handshake to logout.
+
+| Export | Description |
+|---|---|
+| `isAuthenticated()` | Synchronous. `true` when a CSRF token is stored **or** a token-less session was recorded (ambient SSO issues no client token) |
+| `hasSession()` | Asks the server when nothing is stored, and never redirects — unlike `login()` |
+| `login(credentials?)` | Login — switches on the resolved `authMode` (credentials / SSO / OAuth / SAML / bearer / unknown) |
+| `logout()` | Clears session, returns the server's `redirectUrl` |
+| `clearSessionTokens()` | Drops the local session (tokens, token-less flag) and emits `authenticated: false`, without a server round-trip |
+| `detectAuthMode(config, preLogin?)` | Pure resolution of the `AuthMode` from config + server pre-login (no I/O) |
+| `getToken()` / `setToken(token)` | Read/write the stored CSRF token |
+| `requestWebTokenSession(credentials?)` | POSTs `security.webtoken`. The JWT lands in a cookie; the returned (and stored) value is the **CSRF token**. Omit the credentials to use the configured bearer token |
+| `getCsrfToken()` | CSRF token for mutating requests |
+| `deleteWebTokenCookie()` | Explicitly removes the web token cookie |
+| `onAuthEvent(event, handler)` | Typed subscription to the auth lifecycle (`authenticated`, `unauthorized`, `requestFailed`, `tokenRefreshed`, `loggedOut`) — returns the unsubscribe function |
+| `tryAutoAuthentication()` | Probes a protected endpoint for server-side auto-authentication (OIDC, IIS Negotiate) — used by `login()` in `sso`, `unknown` and `bearer` modes. Never throws |
+| `isRedirectPending()` | Whether an OAuth/SAML redirect is in flight and has not established a session yet |
+| `tryOAuthAuthentication()` / `trySAMLAuthentication()` | Redirect to the configured identity provider (with a one-shot redirect-loop guard) |
+| `emitAuthenticatedEvent(bool)` | Dispatches the DOM `'authenticated'` CustomEvent (on `document`, bubbles to `window`) |
+
+> `getJWToken` is **`@deprecated`**: it is an alias of `requestWebTokenSession`, renamed because the
+> old name suggested it returned the JWT. It will be removed in the next major.
+
+The authentication layer is configurable via `setGlobalConfig({ auth: { … } })` (`AuthOptions`):
+`timeoutMs`, `probeEndpoint`, injectable `storage`/`logger`/`fetch`, the requests' `credentials`
+mode, and `recoverFromUnauthorized` — the hook that re-establishes a session after a 401 and gets
+the request replayed once. See [Authentication](./docs/auth/index.mdx) and
+[Handling 401](./docs/auth/handling-401.mdx).
+
+```typescript
+import { isAuthenticated, login, logout } from '@sinequa/atomic';
+
+if (!isAuthenticated()) {
+  // Auto-resolve: reuse an existing session if any, otherwise follow the resolved
+  // `authMode` — in `unknown` mode, probe for SSO then fall back to the credentials form.
+  const ok = await login();
+
+  // — or — explicit credentials, which bypass mode detection entirely.
+  const okWithCredentials = await login({ username: 'alice', password: 's3cr3t' });
+}
+
+const redirectUrl = await logout();
+```
+
+#### Auth mode (`AuthMode`) — **2.0**
+
+`globalConfig.authMode` is the **single source of truth** for the authentication method. It is a
+typed discriminated union — no more juggling overlapping booleans:
+
+```typescript
+import { AuthMode, globalConfig, setGlobalConfig } from '@sinequa/atomic';
+
+setGlobalConfig({ authMode: AuthMode.credentials() });        // username/password form
+setGlobalConfig({ authMode: AuthMode.sso() });                // browser/proxy-injected auth
+setGlobalConfig({ authMode: AuthMode.oauth('my-provider') }); // redirect to an OAuth provider
+setGlobalConfig({ authMode: AuthMode.saml('my-provider') });  // redirect to a SAML provider
+setGlobalConfig({ authMode: AuthMode.bearer(token) });        // server-to-server bearer token
+setGlobalConfig({ authMode: AuthMode.unknown() });            // try SSO, then fall back to credentials
+
+// `login()` and `detectAuthMode()` branch on `authMode.kind`. Every key of `globalConfig` is
+// optional, so read it through `?.` — the default is `AuthMode.unknown()`.
+const kind = globalConfig.authMode?.kind; // 'credentials' | 'sso' | 'oauth' | 'saml' | 'bearer' | 'unknown'
+```
+
+> **Migrating from 1.x:** the booleans `useCredentials` / `useSSO` / `useSAML` are now
+> **`@deprecated` read-only getters** derived from `authMode`. Reading them still works, and writing
+> them through `setGlobalConfig({ useSSO: true })` is translated into the matching `authMode` — so
+> existing code keeps working. Prefer `authMode.kind` (and the `AuthMode.*` constructors) in new code.
+> Full upgrade notes: [Migrating from 1.x](./docs/reference/migrating-from-1x.mdx).
+
+---
+
+### Web API — v1
+
+Every Sinequa v1 endpoint has a typed wrapper.
+
+```typescript
+import {
+  fetchApp,
+  fetchAppPreLogin,
+  fetchQuery,
+  fetchBulkQuery,
+  fetchAggregation,
+  fetchDataset,
+  fetchPreview,
+  fetchPrincipal,
+  fetchSimilarDocuments,
+  fetchSponsoredLinks,
+  fetchSuggest,
+  fetchTextChunks,
+  fetchUserSettings,
+  fetchLabels,
+  fetchQueryExport,
+  fetchQueryIntent,
+  searchPrincipals,
+} from '@sinequa/atomic';
+```
+
+Auditing is not a `fetch*` function: use `Audit.notify(...)`, plus the record decorators
+`addAuditAdditionalInfo`, `addSessionId` and `addUrl`. See [Audit](./docs/integration/audit.mdx).
+
+### Web API — v2
+
+```typescript
+import {
+  fetchUserProfile,
+  fetchVersion,
+  fetchChangePassword,
+  fetchSendPasswordResetEmail,
+} from '@sinequa/atomic';
+```
+
+The full endpoint list — with the `client.api` method and the free function for each — is in
+[Endpoints](./docs/reference/endpoints.mdx).
+
+---
+
+### Helpers
+
+Utilities for transforming Sinequa data structures.
+
+```typescript
+import {
+  getMetadata,           // metadata of an article as `string[]` (splits comma-separated values)
+  getMetadataWithValues, // same, as `{ display, value }[]`
+  makeColumn,
+  extraColumns,
+  resolveToColumnName,
+  resultPages,
+  escapeExpr,
+  guid,
+  isObject,
+} from '@sinequa/atomic';
+```
+
+More in [Helpers](./docs/reference/helpers.mdx).
+
+#### Filter builder
+
+Build structured `query.filters` without hand-writing filter objects. Combinators ignore falsy
+operands and collapse trivial cases (0 → `undefined`, 1 → the operand itself), so filters compose
+cleanly from optional UI state:
+
+```typescript
+import { filter, fetchQuery } from '@sinequa/atomic';
+
+const filters = filter.and(
+  filter.gt('size', 1000),
+  filter.or(
+    filter.eq('treepath', '/HR/*'),
+    filter.in('authors', ['alice', 'bob']),
+  ),
+  onlyRecent && filter.between('modified', '2024-01-01', '2024-12-31'),
+);
+
+await fetchQuery({ name: '<your-query>', text: 'report', filters });
+```
+
+Leaf operators: `eq` · `neq` · `gt` · `gte` · `lt` · `lte` · `like` · `contains` · `regex` · `isNull` · `isNotNull` · `in` · `between`. Combinators: `and` · `or` · `not`.
+
+`filter.distribution(field, item.value)` handles the one case the leaf operators cannot: a
+**distribution** aggregation item (a date or size bucket), whose `value` is an expression the server
+built rather than a value. Passing it to `filter.eq` makes the backend answer
+`500 — "Field type error"`. See [Filters](./docs/search/filters.mdx).
+
+---
+
+### Utilities
+
+```typescript
+import {
+  bisect,
+  sysLang,                     // resolves `all[fr]tous[de]alle` against a locale
+  getRelativeDate,             // and `getOffsetFromDates`
+  getQueryParamsFromUrl,       // and `getUrlParamsFromQueryParams`, `getFiltersFromUrl`, …
+  addConcepts,                 // and `getConcepts`, `parseText`, `rewriteText`, `removeConcept(s)`
+  notify,
+  configureLogger,             // and the `debug` / `info` / `warn` / `error` bindings, `LogLevel`
+} from '@sinequa/atomic';
+```
+
+> The library's verbosity is set with `configureLogger({ level: LogLevel.DEBUG })`, **not** through
+> a configuration key. See [Logging](./docs/integration/logging.mdx) and
+> [URL state](./docs/search/url-state.mdx).
+
+---
+
+## Types
+
+The package re-exports every Sinequa domain type so you never need to cast:
+
+```typescript
+import type {
+  CCApp, CCQuery, CCColumn, CCIndex,
+  Aggregation, AggregationItem, ListAggregation, TreeAggregation,
+  Filter, SimpleFilter, InFilter, BetweenFilter, ExprFilter, NullFilter, NotNullFilter,
+  AuthMode, AuthModeKind,
+  PreviewData,
+  Principal,
+  AuditEvent, AuditRecord,
+  TextChunk,
+} from '@sinequa/atomic';
+```
+
+Which type comes back from which call: [Type map](./docs/reference/types-map.mdx).
+
+---
+
+## Configuration
+
+Set the backend URL before making any API call (required when the Sinequa server is not
+same-origin). `setGlobalConfig` performs a shallow merge into `globalConfig`:
+
+```typescript
+import { setGlobalConfig, globalConfig, AuthMode } from '@sinequa/atomic';
+
+setGlobalConfig({
+  app: 'my-app',
+  backendUrl: 'https://my-sinequa-server.example.com',
+  authMode: AuthMode.unknown(), // optional — defaults to `unknown`
+});
+
+// read it back — every key is optional on `globalConfig`, so `?.` is required
+console.log(globalConfig.backendUrl, globalConfig.authMode?.kind);
+```
+
+Call `initializeAppConfig()` once at bootstrap: it fills in `backendUrl`/`app` from the browser URL
+when they were not provided, then resolves the `authMode` from the server's pre-login response.
+
+> `appInitializerFn` is a **`@deprecated`** alias of `initializeAppConfig` — use the latter.
+
+Three declared keys are read by nothing, and setting them has no effect: `logLevel` (set the level
+with `configureLogger({ level })`), `loginPath` (routing is yours — use `recoverFromUnauthorized` or
+the `unauthorized` event) and `createRoutes`. Every key, with its default:
+[Configuration keys](./docs/reference/config-keys.mdx).
+
+---
+
+## Testing
+
+```bash
+npm test                    # vitest, watch mode
+npm test -- --watch=false   # single run (what CI does)
+```
+
+`--ui` is not available out of the box: `@vitest/ui` is an optional peer of vitest and is not
+installed here — `npm i -D @vitest/ui` first.
+
+Coverage is deepest on authentication (`AuthMode` detection, OAuth, SAML, credentials, tokens,
+401 recovery) and on the HTTP helpers. On the endpoints it is targeted rather than exhaustive —
+`fetchQuery`, `fetchAggregation`, `fetchPrincipal`, `searchPrincipals`, `fetchApp` and the
+document-upload containers. Also covered: the filter builder, metadata parsing, column resolution,
+pagination, date utilities and the SQL value helper.
+
+Injecting `fetch`, `storage` and `logger` through the configuration is what lets a test avoid module
+mocks — see [Testing](./docs/integration/testing.mdx).
+
+---
+
+## Development
+
+```bash
+npm run build        # production build (vite + tsc)
+npm run watch        # rebuild on change
+npm run dev:pack     # build + pack locally
+```
+
+---
+
+## Contributing
+
+1. All tests must pass.
+2. Lint with [Biome](https://biomejs.dev/) — `npx @biomejs/biome check --write .`
+3. Follow [Conventional Commits](https://www.conventionalcommits.org/).
+4. Any change touching `src/` needs a **changeset** in the same commit (`npm run changeset`, then
+   `npm run changeset:status` to check) — the `changeset-check` CI job blocks the merge without one.
+   Add `#skip-changeset` to the MR title for a change that does not touch the published library.
+   Full guide, with examples: [`CONTRIBUTING-changesets.md`](./CONTRIBUTING-changesets.md).
+5. New public API → add tests + JSDoc, and export it from `src/index.ts` (a helper that is written
+   and tested but not re-exported from the barrel is not part of the public API).
+
+---
+
+<div align="center">
+
+Built for the [Sinequa](https://www.sinequa.com/) ecosystem · [Report an issue](https://gitlab.chapsvision.in/sinequa/rnd/sba-atomic-js/-/issues)
+
+</div>