JSPM

@altus4/sdk

0.2.0
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 11
  • Score
    100M100P100Q17281F
  • License Apache-2.0

Official TypeScript SDK for Altus 4 - AI-Enhanced MySQL Full-Text Search Engine

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
}

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 (or Strict 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 helper sdk.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 call sdk.auth.restoreSession() or sdk.auth.initializeAuthState() on app startup. The SDK still falls back to localStorage 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

  1. Error Handling: Always check the success property of API responses
  2. Token Management: Implement automatic token refresh for long-running applications
  3. Rate Limiting: Respect rate limits and implement backoff strategies
  4. Security: Never log or expose API keys or JWT tokens
  5. Validation: Use the built-in validation utilities before making API calls
  6. Caching: Cache frequently accessed data to reduce API calls
  7. Monitoring: Track API usage and response times for performance optimization

Support

For issues, questions, or contributions:

  1. Check the existing documentation and type definitions
  2. Review the parent Altus 4 API documentation
  3. Follow the established code patterns and conventions
  4. Ensure all changes maintain TypeScript compatibility
  5. 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.