@sinequa/atomic 0.0.123 → 0.0.129

package/README.md

@@ -1,67 +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)
 
-A modern TypeScript package designed for use with [Sinequa](https://www.sinequa.com/), providing web API helpers, authentication, configurations, and utilities.
+</div>
 
 ---
 
-## Table of Contents
+## 📦 Installation
 
-- [Features](#features)
-- [Installation](#installation)
-- [Usage](#usage)
-- [Documentation](#documentation)
-- [License](#license)
+```bash
+npm install @sinequa/atomic
+```
 
----
+## 🚀 Quick Start
 
-## Features
+```typescript
+import { 
+  fetchQuery, 
+  fetchAggregation, 
+  isAuthenticated, 
+  login 
+} from '@sinequa/atomic';
 
-- **Web API Helpers**: Simplify API calls with helpers for aggregations, datasets, preview, principal, query, and more.
-- **Authentication**: Easy-to-use authentication utilities (OAuth, SAML, JWT, CSRF, etc.).
-- **Configurations**: Centralized and type-safe configuration management.
-- **Helpers & Utilities**: Includes bisect, date, logger, syslang, and more.
-- **Type Definitions**: Strongly-typed interfaces for API endpoints and data structures.
-- ...and many more functions to help you build with Sinequa.
+// Check authentication status
+if (!isAuthenticated()) {
+  await login({ username: 'user', password: 'pass' });
+}
 
-Explore the full feature set in the [online documentation](https://sinequa.github.io/sba-mint/atomic/intro).
+// 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
 
-## Installation
+### 🔐 Authentication & Security
 
-```sh
-npm install @sinequa/atomic
+- **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';
+```
 
-## Usage
+### Helpers
+
+```typescript
+import { 
+  getMetadata,
+  getMetadataWithValues,
+  makeColumn,
+  resolveToColumnName,
+  escapeExpr,
+  guid,
+  isObject,
+  isString
+} from '@sinequa/atomic';
+```
 
-Import and use helpers in your TypeScript project:
+### Utilities
+
+```typescript
+import { 
+  bisect,
+  formatDate,
+  parseDate,
+  logger,
+  queryParamsToString,
+  syslang
+} from '@sinequa/atomic';
+```
 
-```ts
-import { fetchQuery, fetchAggregation, isAuthenticated } from '@sinequa/atomic';
+## 🔄 Recent Updates (v0.0.125 - v0.0.129)
 
-// Example: Fetch data
-const data = await fetchQuery({ query: 'example' });
+### 🎉 New Features
 
-// Example: Check authentication
-if (isAuthenticated()) {
-  // ...
-}
+- ✅ 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:
 
-## Documentation
+- Authentication flows (OAuth, SAML, credentials)
+- API endpoint integration
+- Error handling scenarios
+- Metadata parsing and processing
+- Date utilities and formatters
 
-Comprehensive documentation is available in the [Atomic Documentation Portal](https://sinequa.github.io/sba-mint/atomic/intro).
+## 📖 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
 
-## License
+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>