@sinequa/atomic 2.0.0 → 2.0.2

package/README.md

@@ -52,8 +52,10 @@ Full auth lifecycle — from first handshake to logout.
 | Export | Description |
 |---|---|
 | `isAuthenticated()` | Returns `true` when a valid token is present |
-| `login(credentials?)` | Login — handles OAuth, SAML and credential flows automatically |
+| `login(credentials?)` | Login — switches on the resolved `authMode` (credentials / SSO / OAuth / SAML / bearer) |
 | `logout()` | Clears session, returns the server's `redirectUrl` |
+| `clearSessionTokens()` | Drops the in-memory/stored session tokens 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 |
 | `getJWToken(credentials?)` | Fetches a JWT from the server, returns the CSRF token |
 | `getCsrfToken()` | CSRF token for mutating requests |
@@ -63,7 +65,8 @@ Full auth lifecycle — from first handshake to logout.
 import { isAuthenticated, login, logout } from '@sinequa/atomic';
 
 if (!isAuthenticated()) {
-  // SSO (OAuth/SAML) — provider resolved from server config
+  // Auto-resolve: reuse an existing session if any, otherwise try SSO and
+  // fall back to the credentials form. Provider resolved from server config.
   const ok = await login();
 
   // — or — credential-based login, bypasses SSO
@@ -73,6 +76,30 @@ if (!isAuthenticated()) {
 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, 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`:
+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.
+
 ---
 
 ### Web API — v1
@@ -128,6 +155,29 @@ import {
 } from '@sinequa/atomic';
 ```
 
+#### 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: '_query', text: 'report', filters });
+```
+
+Leaf operators: `eq` · `neq` · `gt` · `gte` · `lt` · `lte` · `like` · `contains` · `regex` · `isNull` · `isNotNull` · `in` · `between`. Combinators: `and` · `or` · `not`.
+
 ---
 
 ### Utilities
@@ -154,7 +204,8 @@ The package re-exports every Sinequa domain type so you never need to cast:
 import type {
   CCApp, CCQuery, CCColumn, CCIndex,
   Aggregation, AggregationItem, ListAggregation, TreeAggregation,
-  Filter, SimpleFilter, InFilter, BetweenFilter,
+  Filter, SimpleFilter, InFilter, BetweenFilter, ExprFilter, NullFilter, NotNullFilter,
+  AuthMode, AuthModeKind,
   PreviewData,
   Principal,
   AuditEvent, AuditRecord,
@@ -166,24 +217,35 @@ import type {
 
 ## Configuration
 
-Set a base URL before making any API call (required when the Sinequa server is not same-origin):
+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 { setConfig } from '@sinequa/atomic';
+import { setGlobalConfig, globalConfig, AuthMode } from '@sinequa/atomic';
 
-setConfig({ url: 'https://my-sinequa-server.example.com' });
+setGlobalConfig({
+  app: 'my-app',
+  backendUrl: 'https://my-sinequa-server.example.com',
+  authMode: AuthMode.unknown(), // optional — defaults to `unknown`
+});
+
+// read it back
+console.log(globalConfig.backendUrl, globalConfig.authMode.kind);
 ```
 
+> `appInitializerFn` is also exported as an alias of `initializeAppConfig()`, which resolves the
+> `authMode` from the server pre-login response during app bootstrap.
+
 ---
 
 ## Testing
 
 ```bash
-npm test          # run vitest (560+ test cases)
+npm test          # run vitest (274 test cases across 24 files)
 npm test -- --ui  # interactive UI
 ```
 
-Coverage spans authentication flows (OAuth, SAML, credentials), all API endpoints, error handling, metadata parsing, date utilities, and SQL helpers.
+Coverage spans authentication flows (`AuthMode` detection, OAuth, SAML, credentials), all API endpoints, error handling, the filter builder, metadata parsing, date utilities, and SQL helpers.
 
 ---