@sinequa/atomic 1.0.1 → 1.1.0

package/README.md

@@ -1,219 +1,219 @@
-<div align="center">
-
-# @sinequa/atomic
-
-![npm](https://img.shields.io/npm/v/@sinequa/atomic.svg)
-![license](https://img.shields.io/npm/l/@sinequa/atomic.svg)
-![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue)
-
-**A comprehensive TypeScript library for building modern search applications with [Sinequa](https://www.sinequa.com/)**
-
-[Documentation](https://sinequa.github.io/sba-mint/atomic/intro) • [Changelog](./changelogs) • [API Reference](https://sinequa.github.io/sba-mint/atomic/api/app)
-
-</div>
-
----
-
-## 📦 Installation
-
-```bash
-npm install @sinequa/atomic
-```
-
-## 🚀 Quick Start
-
-```typescript
-import { 
-  fetchQuery, 
-  fetchAggregation, 
-  isAuthenticated, 
-  login 
-} from '@sinequa/atomic';
-
-// Check authentication status
-if (!isAuthenticated()) {
-  await login({ username: 'user', password: 'pass' });
-}
-
-// Perform a search query
-const results = await fetchQuery({ 
-  query: 'example search',
-  pageSize: 10 
-});
-
-// Fetch aggregation data
-const aggregations = await fetchAggregation({
-  aggregation: 'category',
-  query: 'example'
-});
-```
-
-## ✨ Key Features
-
-### 🔐 Authentication & Security
-
-- **OAuth & SAML Support**: Seamless integration with enterprise authentication providers
-- **JWT Token Management**: Automatic token handling and refresh
-- **CSRF Protection**: Built-in security measures
-- **Credential-Based Authentication**: Direct username/password authentication
-- **User Session Management**: Complete login/logout flow with user impersonation controls
-
-### 🌐 Web API Integration
-
-- **Type-Safe API Calls**: Strongly-typed interfaces for all Sinequa APIs
-- **Comprehensive Endpoints**: Support for search, aggregations, datasets, preview, and more
-- **Error Handling**: Robust error management with fallback mechanisms
-- **Response Processing**: Automatic parsing and validation of API responses
-
-### 🛠️ Utilities & Helpers
-
-- **Metadata Processing**: Parse and extract metadata with value pairs
-- **Column Management**: Generate engine-specific column configurations
-- **Date Utilities**: Advanced date formatting and manipulation
-- **Query Parameters**: URL query string handling
-- **Logger**: Structured logging with multiple levels
-- **Notification System**: User notification management
-
-### 📊 Data Management
-
-- **Aggregation Handling**: Visual selection tracking and data aggregation
-- **Filter Configuration**: Configurable included/excluded filters
-- **Type Definitions**: Complete TypeScript types for all data structures
-- **Password Management**: Expired and forgotten password flows
-
-## 📚 Core Modules
-
-### Authentication
-
-```typescript
-import { 
-  login, 
-  logout, 
-  isAuthenticated,
-  getToken,
-  setToken,
-  tryOAuthAuthentication,
-  trySAMLAuthentication 
-} from '@sinequa/atomic';
-```
-
-### Web APIs
-
-```typescript
-import { 
-  fetchApp,
-  fetchQuery,
-  fetchAggregation,
-  fetchDatasets,
-  fetchPreview,
-  fetchPrincipal,
-  fetchSimilarDocuments,
-  fetchSponsoredLinks,
-  fetchSuggest,
-  fetchUserSettings
-} from '@sinequa/atomic';
-```
-
-### Helpers
-
-```typescript
-import { 
-  getMetadata,
-  getMetadataWithValues,
-  makeColumn,
-  resolveToColumnName,
-  escapeExpr,
-  guid,
-  isObject,
-  isString
-} from '@sinequa/atomic';
-```
-
-### Utilities
-
-```typescript
-import { 
-  bisect,
-  formatDate,
-  parseDate,
-  logger,
-  queryParamsToString,
-  syslang
-} from '@sinequa/atomic';
-```
-
-## 🔄 Recent Updates (v0.0.125 - v0.0.129)
-
-### 🎉 New Features
-
-- ✅ Credential-based authentication with automatic SSO bypass
-- ✅ Enhanced metadata parsing with comma-separated string support
-- ✅ Forgotten password and expired password handling
-- ✅ Visual selection tracking for aggregation items
-- ✅ Configurable filter bar with inclusion/exclusion options
-
-### 🔒 Security Enhancements
-
-- 🛡️ Fixed user impersonation vulnerability during credential-based login
-- 🔐 JWT tokens now correctly reflect actual user identity
-
-### 🐛 Bug Fixes & Improvements
-
-- ⚡ Enhanced error handling with fallback message fields
-- 📝 Improved type safety across all modules
-- 🧪 Added 560+ new test cases for better reliability
-- 🗂️ Reorganized test structure for better maintainability
-
-### 📖 Documentation
-
-- 📚 Comprehensive JSDoc examples for all major functions
-- 📝 Enhanced inline code documentation
-- 🔗 API reference documentation
-
-[View Full Changelog](./changelogs/CHANGELOG_v0.0.124_to_v0.0.129.md)
-
-## 🧪 Testing
-
-This package includes comprehensive test coverage with 560+ test cases:
-
-```bash
-npm test
-```
-
-Test coverage includes:
-
-- Authentication flows (OAuth, SAML, credentials)
-- API endpoint integration
-- Error handling scenarios
-- Metadata parsing and processing
-- Date utilities and formatters
-
-## 📖 Documentation
-
-- **Getting Started**: [Introduction Guide](https://sinequa.github.io/sba-mint/atomic/intro)
-- **API Reference**: [Complete API Documentation](https://sinequa.github.io/sba-mint/atomic/api)
-- **Authentication**: [Auth Documentation](https://sinequa.github.io/sba-mint/atomic/authentication)
-- **Examples**: Check the `/docs` folder for detailed examples
-
-## 🤝 Contributing
-
-We welcome contributions! Please ensure:
-
-- ✅ All tests pass
-- ✅ Code follows the existing style (Biome linting)
-- ✅ New features include tests and documentation
-- ✅ Commit messages follow conventional commits
-
-## 📄 License
-
-This project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for details.
-
----
-
-<div align="center">
-
-**Built with ❤️ for the Sinequa Community**
-
-[Documentation](https://sinequa.github.io/sba-mint/atomic/intro) • [Report Bug](https://github.com/Product/sba-atomic-js/issues) • [Request Feature](https://github.com/Product/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-5.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/npm/l/@sinequa/atomic?style=for-the-badge&color=22c55e" alt="MIT License" />
+
+<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.
+
+[Docs](https://sinequa.github.io/sba-mint/atomic/intro) · [API Reference](https://sinequa.github.io/sba-mint/atomic/api/app)
+
+</div>
+
+---
+
+## Installation
+
+```bash
+npm install @sinequa/atomic
+```
+
+> Requires **Node ≥ 18** or any modern browser. Ships as ESM (`atomic.js`) and CJS (`atomic.umd.cjs`) with full `.d.ts` declarations.
+
+---
+
+## At a glance
+
+```typescript
+import { login, isAuthenticated, fetchQuery, fetchAggregation } from '@sinequa/atomic';
+
+if (!isAuthenticated()) {
+  await login({ username: 'alice', password: 's3cr3t' });
+}
+
+const results = await fetchQuery({ query: 'knowledge management', pageSize: 10 });
+const facets  = await fetchAggregation({ aggregation: 'company', query: 'knowledge management' });
+```
+
+---
+
+## Modules
+
+### Authentication
+
+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 |
+| `logout()` | Clears session, returns the server's `redirectUrl` |
+| `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 |
+| `deleteWebTokenCookie()` | Explicitly removes the web token cookie |
+
+```typescript
+import { isAuthenticated, login, logout } from '@sinequa/atomic';
+
+if (!isAuthenticated()) {
+  // SSO (OAuth/SAML) — provider resolved from server config
+  const ok = await login();
+
+  // — or — credential-based login, bypasses SSO
+  const ok = await login({ username: 'alice', password: 's3cr3t' });
+}
+
+const redirectUrl = await logout();
+```
+
+---
+
+### Web API — v1
+
+Every Sinequa v1 endpoint has a typed wrapper.
+
+```typescript
+import {
+  fetchApp,
+  fetchQuery,
+  fetchAggregation,
+  fetchDataset,
+  fetchPreview,
+  fetchPrincipal,
+  fetchSimilarDocuments,
+  fetchSponsoredLinks,
+  fetchSuggest,
+  fetchTextChunk,
+  fetchUserSettings,
+  fetchAudit,
+  fetchLabels,
+  fetchQueryExport,
+  fetchQueryIntent,
+} from '@sinequa/atomic';
+```
+
+### Web API — v2
+
+```typescript
+import {
+  fetchUserProfile,
+  fetchVersion,
+  fetchChangePassword,
+  fetchForgotPassword,
+} from '@sinequa/atomic';
+```
+
+---
+
+### Helpers
+
+Utilities for transforming Sinequa data structures.
+
+```typescript
+import {
+  getMetadata,
+  getMetadataWithValues, // parses comma-separated metadata strings
+  makeColumn,
+  resolveToColumnName,
+  escapeExpr,
+  guid,
+  isObject,
+} from '@sinequa/atomic';
+```
+
+---
+
+### Utilities
+
+```typescript
+import {
+  bisect,
+  formatDate,
+  parseDate,
+  logger,
+  queryParamsToString,
+  toSQL,
+  syslang,
+} from '@sinequa/atomic';
+```
+
+---
+
+## 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,
+  PreviewData,
+  Principal,
+  AuditEvent, AuditRecord,
+  TextChunk,
+} from '@sinequa/atomic';
+```
+
+---
+
+## Configuration
+
+Set a base URL before making any API call (required when the Sinequa server is not same-origin):
+
+```typescript
+import { setConfig } from '@sinequa/atomic';
+
+setConfig({ url: 'https://my-sinequa-server.example.com' });
+```
+
+---
+
+## Testing
+
+```bash
+npm test          # run vitest (560+ test cases)
+npm test -- --ui  # interactive UI
+```
+
+Coverage spans authentication flows (OAuth, SAML, credentials), all API endpoints, error handling, metadata parsing, date utilities, and SQL helpers.
+
+---
+
+## 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. New public API → add tests + JSDoc.
+
+---
+
+## License
+
+MIT — see [LICENSE](./LICENSE).
+
+---
+
+<div align="center">
+
+Built for the [Sinequa](https://www.sinequa.com/) ecosystem · [Report an issue](https://github.com/Product/sba-atomic-js/issues)
+
+</div>