npm package: @sinequa/atomic
Description: <div align="center">
Latest version: 0.0.139

<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>