@sinequa/atomic

A comprehensive TypeScript library for building modern search applications with Sinequa

Documentation • Changelog • API Reference

📦 Installation

npm install @sinequa/atomic

🚀 Quick Start

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

import { 
  login, 
  logout, 
  isAuthenticated,
  getToken,
  setToken,
  tryOAuthAuthentication,
  trySAMLAuthentication 
} from '@sinequa/atomic';

Web APIs

import { 
  fetchApp,
  fetchQuery,
  fetchAggregation,
  fetchDatasets,
  fetchPreview,
  fetchPrincipal,
  fetchSimilarDocuments,
  fetchSponsoredLinks,
  fetchSuggest,
  fetchUserSettings
} from '@sinequa/atomic';

Helpers

import { 
  getMetadata,
  getMetadataWithValues,
  makeColumn,
  resolveToColumnName,
  escapeExpr,
  guid,
  isObject,
  isString
} from '@sinequa/atomic';

Utilities

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

🧪 Testing

This package includes comprehensive test coverage with 560+ test cases:

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
• API Reference: Complete API Documentation
• Authentication: Auth Documentation
• 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 file for details.

Built with ❤️ for the Sinequa Community

Documentation • Report Bug • Request Feature