Package Exports
- @altus4/sdk
- @altus4/sdk/package.json
Readme
Altus 4 | TypeScript SDK
A comprehensive TypeScript SDK for the Altus 4 AI-Enhanced MySQL Full-Text Search Engine. This SDK provides type-safe access to search analytics, database management, and AI-powered insights.
Overview
Altus 4 enhances MySQL's native FULLTEXT search capabilities with AI-powered optimizations, semantic understanding, and advanced analytics. This SDK enables developers to integrate these capabilities into their applications with full TypeScript support and modern development practices.
Features
- Complete Authentication - JWT-based authentication with automatic token management
- API Key Management - Create, update, revoke, and monitor API keys with tiered permissions
- Database Connections - Manage MySQL connections with schema discovery and health monitoring
- Analytics & Insights - Access search trends, performance metrics, and AI-generated insights
- System Management - Health checks, migration status, and system monitoring
- Type Safety - Full TypeScript support with comprehensive type definitions
- Modular Design - Use individual services or the unified SDK interface
- Utility Functions - Built-in validation, formatting, and date helpers
Installation
npm install @altus4/sdk
Quick Start
import { Altus4SDK } from '@altus4/sdk';
// Initialize the SDK
const altus4 = new Altus4SDK({
baseURL: 'https://api.altus4.com/api/v1',
});
// Authenticate user
const loginResult = await altus4.login('user@example.com', 'password');
if (loginResult.success) {
console.log('Welcome', loginResult.user?.name);
// Create an API key for service-to-service authentication
const apiKey = await altus4.apiKeys.createApiKey({
name: 'Dashboard Integration',
environment: 'test',
permissions: ['search', 'analytics'],
rateLimitTier: 'free',
});
// Get analytics dashboard data
const dashboard = await altus4.analytics.getDashboardAnalytics({
period: 'week',
});
}
Architecture
The SDK is organized into modular services with a clean separation of concerns:
sdk/
├── types/ # TypeScript type definitions and interfaces
├── client/ # Base HTTP client and configuration
├── services/ # Individual API service classes
│ ├── auth.service.ts
│ ├── api-keys.service.ts
│ ├── database.service.ts
│ ├── analytics.service.ts
│ └── management.service.ts
├── utils/ # Validation, formatting, and utility functions
└── index.ts # Main SDK export and unified interface
API Reference
Authentication Service
The AuthService handles user authentication, registration, and profile management.
Methods
handleLogin(credentials: LoginRequest): Promise
Authenticate a user with email and password.
const result = await altus4.auth.handleLogin({
email: 'user@example.com',
password: 'password123',
});
if (result.success) {
console.log('User authenticated:', result.user);
console.log('Token expires in:', result.expiresIn, 'seconds');
}
handleRegister(userData: RegisterRequest): Promise
Register a new user account.
const result = await altus4.auth.handleRegister({
name: 'John Doe',
email: 'john@example.com',
password: 'securePassword123',
role: 'user', // Optional: 'user' | 'admin'
});
getCurrentUser(): Promise<{success: boolean; user?: User; error?: any}>
Get the current authenticated user's profile.
const userResponse = await altus4.auth.getCurrentUser();
if (userResponse.success) {
console.log('Current user:', userResponse.user);
}
updateProfile(updates: UpdateProfileRequest): Promise<{success: boolean; user?: User; error?: any}>
Update the authenticated user's profile.
await altus4.auth.updateProfile({
name: 'John Smith',
email: 'john.smith@example.com',
});
isAuthenticated(): boolean
Check if the user is currently authenticated.
if (altus4.auth.isAuthenticated()) {
// User is authenticated
}
Cookie-based authentication (recommended)
Starting with the recent patch, the SDK supports a cookie-based refresh flow which is the recommended configuration for browser-based client apps.
Why use cookie-based refresh?
The refresh token is stored as an HttpOnly, Secure cookie by your backend. This prevents JavaScript from reading the refresh token (stronger XSS protection).
The SDK keeps a short-lived access token in memory and automatically calls the refresh endpoint to obtain a new access token when needed.
No sensitive tokens are persisted to
localStorage
by default in this flow.
Backend requirements
On successful login, your server should set a refresh token cookie using
Set-Cookie
with attributes:HttpOnly; Secure; SameSite=Lax
(orStrict
as appropriate).Provide a POST
/auth/refresh
endpoint which reads the refresh cookie and returns a fresh access token JSON:{ token: string, expiresIn: number }
.Implement POST
/auth/logout
to clear the refresh cookie.
Client integration (SPA)
On app startup you can call
sdk.auth.restoreSession()
(SDK exposes this helper) which calls/auth/refresh
with credentials included and populates the SDK's in-memory access token if successful. A higher-level helpersdk.auth.initializeAuthState()
will attempt restore and then fetch the current user profile — useful during app bootstrap.The SDK's
BaseClient
automatically retries requests that receive 401 by calling/auth/refresh
and retrying the original request when a new access token is returned.
Simple example (app bootstrap):
import { Altus4SDK } from '@altus4/sdk';
const sdk = new Altus4SDK({ baseURL: '/api' });
async function bootstrapApp() {
// Try to restore session from HttpOnly refresh cookie
const restored = await sdk.auth.restoreSession();
// Or use initializeAuthState() which also fetches user profile if restored
// const restoredFull = await sdk.auth.initializeAuthState();
if (restored && sdk.auth.isAuthenticated()) {
router.replace('/dashboard');
} else {
router.replace('/login');
}
mountApp();
}
bootstrapApp();
Migration note
- If you previously relied on
localStorage
persistence, switch your backend to issue a refresh cookie and callsdk.auth.restoreSession()
orsdk.auth.initializeAuthState()
on app startup. The SDK still falls back tolocalStorage
when available to preserve backward compatibility with older consumers, but cookie-based refresh is recommended for new deployments.
API Keys Service
The ApiKeysService manages API keys for service-to-service authentication.
Methods
createApiKey(keyData: CreateApiKeyRequest): Promise<ApiResponse<{ apiKey: ApiKey; secretKey: string }>>
Create a new API key with specified permissions and rate limiting.
const keyResponse = await altus4.apiKeys.createApiKey({
name: 'Production API Key',
environment: 'live',
permissions: ['search', 'analytics'],
rateLimitTier: 'pro',
expiresAt: '2024-12-31',
});
listApiKeys(): Promise<ApiResponse<ApiKey[]>>
List all API keys for the authenticated user.
const keys = await altus4.apiKeys.listApiKeys();
keys.data?.forEach(key => {
console.log(`${key.name}: ${key.isActive ? 'active' : 'inactive'}`);
});
getApiKey(keyId: string): Promise<ApiResponse
Get details for a specific API key.
const key = await altus4.apiKeys.getApiKey('key-id-123');
updateApiKey(keyId: string, updates: UpdateApiKeyRequest): Promise<ApiResponse
Update an existing API key's settings.
await altus4.apiKeys.updateApiKey('key-id-123', {
name: 'Updated Key Name',
permissions: ['search', 'analytics', 'admin'],
rateLimitTier: 'enterprise',
});
revokeApiKey(keyId: string): Promise<ApiResponse
Revoke an API key, making it immediately invalid.
await altus4.apiKeys.revokeApiKey('key-id-123');
getApiKeyUsage(keyId: string): Promise<ApiResponse
Get usage statistics for an API key.
const usage = await altus4.apiKeys.getApiKeyUsage('key-id-123');
console.log('Requests this month:', usage.data?.requestsThisMonth);
console.log('Quota used / limit:', usage.data?.quotaUsed, '/', usage.data?.quotaLimit);
Database Service
The DatabaseService manages MySQL database connections and schema discovery.
Methods
addDatabaseConnection(connectionData: AddDatabaseConnectionRequest): Promise<ApiResponse
Add a new database connection configuration.
const connection = await altus4.database.addDatabaseConnection({
name: 'Production Database',
host: 'db.example.com',
port: 3306,
database: 'myapp_production',
username: 'readonly_user',
password: 'secure_password',
ssl: true,
});
listDatabaseConnections(): Promise<ApiResponse<DatabaseConnection[]>>
List all configured database connections.
const connections = await altus4.database.listDatabaseConnections();
getDatabaseConnection(connectionId: string): Promise<ApiResponse
Get details for a specific database connection.
const connection = await altus4.database.getDatabaseConnection('conn-123');
updateDatabaseConnection(connectionId: string, updates: UpdateDatabaseConnectionRequest): Promise<ApiResponse
Update a database connection's configuration.
await altus4.database.updateDatabaseConnection('conn-123', {
name: 'Updated Connection Name',
ssl: true,
});
removeDatabaseConnection(connectionId: string): Promise<ApiResponse<{success: boolean}>>
Remove a database connection configuration.
await altus4.database.removeDatabaseConnection('conn-123');
testDatabaseConnection(connectionId: string): Promise<ApiResponse
Test connectivity to a configured database.
const test = await altus4.database.testDatabaseConnection('conn-123');
if (test.data?.connected) {
console.log('Database connection successful');
}
getDatabaseSchema(connectionId: string): Promise<ApiResponse<TableSchema[]>>
Discover the schema for a connected database.
const schema = await altus4.database.getDatabaseSchema('conn-123');
schema.data?.forEach(table => {
console.log(`Table: ${table.table} (${table.estimatedRows} rows)`);
});
Analytics Service
The AnalyticsService provides access to search analytics and AI-powered insights.
Methods
getDashboardAnalytics(request: { period: 'day' | 'week' | 'month' | 'year' }): Promise<ApiResponse
Get comprehensive dashboard analytics data.
const dashboard = await altus4.analytics.getDashboardAnalytics({
period: 'month',
startDate: '2024-01-01',
endDate: '2024-01-31',
});
console.log('Total searches:', dashboard.data?.totalSearches);
console.log('Average response time:', dashboard.data?.averageResponseTime);
getTrends(request: { period: 'day' | 'week' | 'month' | 'year'; startDate?: string; endDate?: string }): Promise<ApiResponse
Get search trend analysis and patterns.
const trends = await altus4.analytics.getSearchTrends({
period: 'week',
});
getSearchHistory(query?: AnalyticsQuery): Promise<ApiResponse<any[]>>
Get detailed search history with pagination.
const history = await altus4.analytics.getSearchHistory({
limit: 50,
offset: 0,
startDate: '2024-01-01',
endDate: '2024-01-31',
});
getInsights(request: { period: 'day' | 'week' | 'month' | 'year'; startDate?: string; endDate?: string }): Promise<ApiResponse
Get AI-generated insights and recommendations.
const insights = await altus4.analytics.getInsights({ period: 'month' });
insights.data?.insights.forEach(insight => {
console.log(insight.title, '-', insight.description);
});
Management Service
The ManagementService provides system health checks and management operations.
Methods
getSystemHealth(): Promise<ApiResponse
Check overall system health and status.
const health = await altus4.management.getSystemHealth();
console.log('System status:', health.data?.status);
console.log('Uptime:', health.data?.uptime);
testConnection(): Promise<ApiResponse
Test API connectivity and authentication.
const test = await altus4.management.testConnection();
if (test.data?.connected) {
console.log('API connection successful');
}
getMigrationStatus(): Promise<ApiResponse
Check migration status for new authentication system.
const status = await altus4.management.getMigrationStatus();
if (!status.data?.hasMigrated) {
console.log('Migration needed:', status.data?.recommendedAction);
}
setupInitialApiKey(): Promise<ApiResponse
Create initial API key for new users (requires JWT authentication).
const initialKey = await altus4.management.setupInitialApiKey();
console.log('Initial API key created:', initialKey.data?.key);
Utility Functions
The SDK includes comprehensive utility functions for common operations.
Validation
import { validateEmail, validatePassword, validateApiKeyCreation } from './sdk/utils';
// Email validation
const isValidEmail = validateEmail('user@example.com');
// Password strength validation
const passwordValidation = validatePassword('myPassword123!');
if (!passwordValidation.isValid) {
console.log('Password errors:', passwordValidation.errors);
}
// API key creation validation
const keyValidation = validateApiKeyCreation({
name: 'Test Key',
environment: 'test',
permissions: ['search'],
});
Formatting
import {
formatNumber, // 1,234,567
formatCompactNumber, // 1.23M
formatResponseTime, // 250ms / 1.50s
formatRelativeTime, // 1 hour ago
getRateLimitInfo, // { limit, name, description }
} from './sdk/utils';
console.log(formatNumber(1234567)); // "1,234,567"
console.log(formatCompactNumber(2500000)); // "2.50M"
console.log(formatResponseTime(1500)); // "1.50s"
const oneHourAgo = new Date(Date.now() - 3600000);
console.log(formatRelativeTime(oneHourAgo)); // "1 hour ago"
const rateLimitInfo = getRateLimitInfo('pro');
console.log(rateLimitInfo.description); // "10,000 requests per hour"
Date Utilities
import { getDateRangeForPeriod, formatDateForQuery } from './sdk/utils';
// Get date range for analytics periods
const monthRange = getDateRangeForPeriod('month');
console.log(monthRange); // { startDate: "YYYY-MM-DD", endDate: "YYYY-MM-DD" }
// Format dates for API queries
const queryDate = formatDateForQuery(new Date()); // "YYYY-MM-DD"
Error Handling
The SDK provides consistent error handling patterns across all services:
try {
const result = await altus4.auth.handleLogin({
email: 'user@example.com',
password: 'wrongpassword',
});
if (!result.success) {
// Handle API errors
console.error('Login failed:', result.error?.message);
console.error('Error code:', result.error?.code);
}
} catch (error) {
// Handle network or other errors
console.error('Request failed:', error);
}
Common Error Codes
The SDK normalizes network errors and forwards server error bodies as-is. Common codes in ErrorCode
:
VALIDATION_ERROR
AUTHENTICATION_ERROR
AUTHORIZATION_ERROR
NOT_FOUND
RATE_LIMIT_EXCEEDED
INTERNAL_ERROR
NETWORK_ERROR
DATABASE_ERROR
Advanced Usage
Individual Service Usage
import { AuthService, ApiKeysService } from './sdk';
// Use services independently
const auth = new AuthService({
baseURL: 'https://api.altus4.com/api/v1',
});
const apiKeys = new ApiKeysService({
baseURL: 'https://api.altus4.com/api/v1',
});
const loginResult = await auth.handleLogin(credentials);
const keys = await apiKeys.listApiKeys();
Custom Configuration
const altus4 = new Altus4SDK({
baseURL: 'https://custom-api.example.com/api/v1',
timeout: 60000, // 60 seconds
headers: {
'X-Custom-Header': 'value',
},
});
Token Management
// Manual token management
altus4.setToken('your-jwt-token', 3600); // 1 hour expiry
// Check authentication status
if (altus4.isAuthenticated()) {
console.log('User is authenticated');
}
// Automatic token refresh
const refreshed = await altus4.refreshTokenIfNeeded();
if (!refreshed) {
// Redirect to login or handle re-authentication
console.log('Token refresh failed, re-authentication required');
}
// Clear authentication
altus4.clearToken();
Type Definitions
The SDK is fully typed with comprehensive TypeScript definitions under src/types
and re-exported from the package entry. Refer to those files for authoritative type shapes (e.g., ApiResponse
, User
, ApiKey
, Analytics*
, Database*
, Management*
).
Browser and Node.js Compatibility
The SDK is compatible with:
- Browsers: Chrome 70+, Firefox 65+, Safari 12+, Edge 79+
- Node.js: 14.0+
- TypeScript: 4.0+
Development
Building the SDK
# Install dependencies
npm install
# Build TypeScript to JavaScript
npm run build
# Run type checking
npm run typecheck
# Development mode with watch
npm run dev
Testing
# Run unit tests
npm test
# Run tests with coverage
npm run test:coverage
# Run tests in watch mode
npm run test:watch
Configuration
Environment Variables
For development, you can set default configuration via environment variables:
ALTUS4_API_URL=https://api.altus4.com/api/v1
ALTUS4_TIMEOUT=30000
Configuration File
Create a configuration file for shared settings:
// altus4.config.ts
export const altus4Config = {
baseURL: process.env.ALTUS4_API_URL || 'http://localhost:3000/api/v1',
timeout: 30000,
retryAttempts: 3,
};
// Use in your application
const altus4 = new Altus4SDK(altus4Config);
Best Practices
- Error Handling: Always check the
success
property of API responses - Token Management: Implement automatic token refresh for long-running applications
- Rate Limiting: Respect rate limits and implement backoff strategies
- Security: Never log or expose API keys or JWT tokens
- Validation: Use the built-in validation utilities before making API calls
- Caching: Cache frequently accessed data to reduce API calls
- Monitoring: Track API usage and response times for performance optimization
Support
For issues, questions, or contributions:
- Check the existing documentation and type definitions
- Review the parent Altus 4 API documentation
- Follow the established code patterns and conventions
- Ensure all changes maintain TypeScript compatibility
- Add appropriate error handling and validation
License
This SDK is licensed under the Apache License, Version 2.0. See the included LICENSE file for the full terms.