{"_id":"@altus4/sdk","_rev":"17-e6fa40f9e248c5f8141d71c8bddd0f9b","name":"@altus4/sdk","dist-tags":{"latest":"0.2.0"},"versions":{"0.1.0":{"name":"@altus4/sdk","version":"0.1.0","keywords":["altus4","mysql","fulltext-search","ai","search-engine","analytics","typescript","sdk","api-client","database-search"],"author":{"name":"Altus 4 Team","email":"contact@altus4.com"},"license":"MIT","_id":"@altus4/sdk@0.1.0","maintainers":[{"name":"thavarshan","email":"tjthavarshan@gmail.com"}],"homepage":"https://github.com/altus4/sdk-js#readme","bugs":{"url":"https://github.com/altus4/sdk-js/issues"},"dist":{"shasum":"3eba853b3b15ab8cc1adf9a5a71aee80da74b0b9","tarball":"https://registry.npmjs.org/@altus4/sdk/-/sdk-0.1.0.tgz","fileCount":135,"integrity":"sha512-5uGYuv5I6GGDiFrrpbOMpPCSeDTG/afEd+rkGN1C8iEyDdlvDEj8LvArYbnkvCMrpv5MIvve5CRMgOZdW2gH4A==","signatures":[{"sig":"MEQCIHLwApOtqy9ZIAPq9x0sZiZY2Tv/FGdOgfX/xlBQw0mmAiBzSL9iMQKz/YXVh1mPCjwOA/+I9R0gEnwd3n0rRUPWtg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@altus4%2fsdk@0.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":253525},"main":"dist/index.js","types":"dist/index.d.ts","module":"dist/esm/index.js","engines":{"npm":">=6.0.0","node":">=14.0.0"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/esm/index.js","require":"./dist/index.js"},"./package.json":"./package.json"},"gitHead":"c785278551454afdf32b536c7c2d958447733f27","scripts":{"lint":"eslint \"src/**/*.ts\"","test":"jest","build":"npm run clean && tsc -p tsconfig.json && tsc -p tsconfig.esm.json","clean":"rimraf dist","format":"prettier --write .","prepack":"npm run build","prepare":"husky install","release":"npm run build && npm publish","lint:fix":"eslint \"src/**/*.ts\" --fix","test:all":"npm run test:unit && npm run test:integration","test:unit":"jest --testPathPattern=src","typecheck":"tsc -p tsconfig.json --noEmit","docs:build":"typedoc src/index.ts --out docs","test:watch":"jest --watch","build:watch":"tsc -p tsconfig.json --watch","format:check":"prettier --check .","release:beta":"npm run build && npm publish --tag beta","test:coverage":"jest --coverage && node ./scripts/coverage-summary.js","prepublishOnly":"npm run build && npm run test && npm run lint","test:integration":"jest --config jest.integration.config.js","test:integration:e2e":"jest --config jest.integration.config.js --testPathPattern=e2e","test:integration:auth":"jest --config jest.integration.config.js --testPathPattern=auth","test:coverage:integration":"jest --config jest.integration.config.js --coverage","test:integration:services":"jest --config jest.integration.config.js --testPathPattern=services","test:integration:performance":"jest --config jest.integration.config.js --testPathPattern=performance"},"_npmUser":{"name":"thavarshan","email":"tjthavarshan@gmail.com"},"repository":{"url":"git+https://github.com/altus4/sdk-js.git","type":"git"},"_npmVersion":"10.8.2","description":"Official TypeScript SDK for Altus 4 - AI-Enhanced MySQL Full-Text Search Engine","directories":{},"lint-staged":{"*.{ts,tsx,js,jsx}":["eslint --fix","prettier --write"],"*.{json,md,yml,yaml}":["prettier --write"]},"_nodeVersion":"20.19.5","dependencies":{"axios":"^1.11.0","formlink":"1.3.0"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"_hasShrinkwrap":false,"devDependencies":{"jest":"^29.7.0","husky":"^9.1.7","eslint":"^8.57.1","rimraf":"^5.0.5","ts-jest":"^29.1.2","typedoc":"^0.25.13","prettier":"^3.6.2","typescript":"^5.1.6","@types/jest":"^29.5.12","@types/node":"^20.4.5","lint-staged":"^16.1.5","eslint-config-prettier":"^10.1.8","eslint-plugin-prettier":"^5.5.4","@typescript-eslint/parser":"^8.41.0","eslint-plugin-unused-imports":"^4.2.0","@typescript-eslint/eslint-plugin":"^8.41.0"},"peerDependencies":{"typescript":">=4.0.0"},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.1.0_1757767517193_0.6459147882408607","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@altus4/sdk","version":"0.2.0","description":"Official TypeScript SDK for Altus 4 - AI-Enhanced MySQL Full-Text Search Engine","main":"dist/index.js","module":"dist/esm/index.js","types":"dist/index.d.ts","scripts":{"build":"npm run clean && tsc -p tsconfig.json && tsc -p tsconfig.esm.json","build:watch":"tsc -p tsconfig.json --watch","clean":"rimraf dist","typecheck":"tsc -p tsconfig.json --noEmit","lint":"eslint \"src/**/*.ts\"","lint:fix":"eslint \"src/**/*.ts\" --fix","format":"prettier --write .","format:check":"prettier --check .","prepare":"husky install","prepublishOnly":"npm run build && npm run test && npm run lint","test":"jest","test:unit":"jest --testPathPattern=src","test:integration":"jest --config jest.integration.config.js","test:integration:auth":"jest --config jest.integration.config.js --testPathPattern=auth","test:integration:services":"jest --config jest.integration.config.js --testPathPattern=services","test:integration:e2e":"jest --config jest.integration.config.js --testPathPattern=e2e","test:integration:performance":"jest --config jest.integration.config.js --testPathPattern=performance","test:watch":"jest --watch","test:all":"npm run test:unit && npm run test:integration","test:coverage":"jest --coverage && node ./scripts/coverage-summary.js","test:coverage:integration":"jest --config jest.integration.config.js --coverage","release":"npm run build && npm publish","release:beta":"npm run build && npm publish --tag beta","docs:build":"typedoc src/index.ts --out docs","prepack":"npm run build"},"engines":{"node":">=14.0.0","npm":">=6.0.0"},"repository":{"type":"git","url":"git+https://github.com/altus4/sdk-js.git"},"homepage":"https://github.com/altus4/sdk-js#readme","bugs":{"url":"https://github.com/altus4/sdk-js/issues"},"author":{"name":"Altus 4 Team","email":"contact@altus4.com"},"keywords":["altus4","mysql","fulltext-search","ai","search-engine","analytics","typescript","sdk","api-client","database-search"],"dependencies":{"axios":"^1.11.0","formlink":"1.3.0"},"devDependencies":{"@types/jest":"^29.5.12","@types/node":"^20.4.5","@typescript-eslint/eslint-plugin":"^8.41.0","@typescript-eslint/parser":"^8.41.0","eslint":"^8.57.1","eslint-config-prettier":"^10.1.8","eslint-plugin-prettier":"^5.5.4","eslint-plugin-unused-imports":"^4.2.0","husky":"^9.1.7","jest":"^29.7.0","lint-staged":"^16.1.5","prettier":"^3.6.2","rimraf":"^5.0.5","ts-jest":"^29.1.2","typedoc":"^0.25.13","typescript":"^5.1.6"},"peerDependencies":{"typescript":">=4.0.0"},"lint-staged":{"*.{ts,tsx,js,jsx}":["eslint --fix","prettier --write"],"*.{json,md,yml,yaml}":["prettier --write"]},"exports":{".":{"import":"./dist/esm/index.js","require":"./dist/index.js","types":"./dist/index.d.ts"},"./package.json":"./package.json"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"license":"Apache-2.0","_id":"@altus4/sdk@0.2.0","gitHead":"1e97b2ef17df76773898561c035b39a4cc583152","_nodeVersion":"20.19.5","_npmVersion":"10.8.2","dist":{"integrity":"sha512-Bfwl3UngVvXq8lFQzYn/76SztvRIbeUBs7dXNMwjjkWE/w9RJrafLTPmSDZW4JWlfcwMlI0X1RwHuWz5bk4r2A==","shasum":"2d0e2888ff9b5d45ccc69cf86f211ccfb935fc23","tarball":"https://registry.npmjs.org/@altus4/sdk/-/sdk-0.2.0.tgz","fileCount":135,"unpackedSize":269288,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@altus4%2fsdk@0.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDNrOAUXgLvO7PX8+GU56mT5JIpUARdW1K5SfTHgjbsIgIhAKhG71DiKEFlV9MO+Dn/btEtyFBfnfrqctEurvUOWOac"}]},"_npmUser":{"name":"thavarshan","email":"tjthavarshan@gmail.com"},"directories":{},"maintainers":[{"name":"thavarshan","email":"tjthavarshan@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_0.2.0_1757857797034_0.20098199759908386"},"_hasShrinkwrap":false}},"time":{"created":"2025-09-13T12:45:17.109Z","modified":"2025-09-14T13:49:57.702Z","1.0.0":"2025-09-11T08:26:32.713Z","1.0.1":"2025-09-11T08:31:19.489Z","1.0.2":"2025-09-11T09:42:38.609Z","1.0.3":"2025-09-11T10:20:39.241Z","1.0.4":"2025-09-11T10:38:39.819Z","1.0.5":"2025-09-11T11:10:02.636Z","1.0.6":"2025-09-11T11:15:23.682Z","0.1.0":"2025-09-13T12:45:17.378Z","0.2.0":"2025-09-14T13:49:57.245Z"},"bugs":{"url":"https://github.com/altus4/sdk-js/issues"},"author":{"name":"Altus 4 Team","email":"contact@altus4.com"},"license":"Apache-2.0","homepage":"https://github.com/altus4/sdk-js#readme","keywords":["altus4","mysql","fulltext-search","ai","search-engine","analytics","typescript","sdk","api-client","database-search"],"repository":{"type":"git","url":"git+https://github.com/altus4/sdk-js.git"},"description":"Official TypeScript SDK for Altus 4 - AI-Enhanced MySQL Full-Text Search Engine","maintainers":[{"name":"thavarshan","email":"tjthavarshan@gmail.com"}],"readme":"# Altus 4 | TypeScript SDK\n\nA 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.\n\n## Overview\n\nAltus 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.\n\n## Features\n\n- **Complete Authentication** - JWT-based authentication with automatic token management\n- **API Key Management** - Create, update, revoke, and monitor API keys with tiered permissions\n- **Database Connections** - Manage MySQL connections with schema discovery and health monitoring\n- **Analytics & Insights** - Access search trends, performance metrics, and AI-generated insights\n- **System Management** - Health checks, migration status, and system monitoring\n- **Type Safety** - Full TypeScript support with comprehensive type definitions\n- **Modular Design** - Use individual services or the unified SDK interface\n- **Utility Functions** - Built-in validation, formatting, and date helpers\n\n## Installation\n\n```bash\nnpm install @altus4/sdk\n```\n\n## Quick Start\n\n```typescript\nimport { Altus4SDK } from '@altus4/sdk';\n\n// Initialize the SDK\nconst altus4 = new Altus4SDK({\n  baseURL: 'https://api.altus4.com/api/v1',\n});\n\n// Authenticate user\nconst loginResult = await altus4.login('user@example.com', 'password');\n\nif (loginResult.success) {\n  console.log('Welcome', loginResult.user?.name);\n\n  // Create an API key for service-to-service authentication\n  const apiKey = await altus4.apiKeys.createApiKey({\n    name: 'Dashboard Integration',\n    environment: 'test',\n    permissions: ['search', 'analytics'],\n    rateLimitTier: 'free',\n  });\n\n  // Get analytics dashboard data\n  const dashboard = await altus4.analytics.getDashboardAnalytics({\n    period: 'week',\n  });\n}\n```\n\n## Architecture\n\nThe SDK is organized into modular services with a clean separation of concerns:\n\n```\nsdk/\n├── types/           # TypeScript type definitions and interfaces\n├── client/          # Base HTTP client and configuration\n├── services/        # Individual API service classes\n│   ├── auth.service.ts\n│   ├── api-keys.service.ts\n│   ├── database.service.ts\n│   ├── analytics.service.ts\n│   └── management.service.ts\n├── utils/           # Validation, formatting, and utility functions\n└── index.ts         # Main SDK export and unified interface\n```\n\n## API Reference\n\n### Authentication Service\n\nThe AuthService handles user authentication, registration, and profile management.\n\n#### Methods\n\n**handleLogin(credentials: LoginRequest): Promise<AuthResult>**\n\nAuthenticate a user with email and password.\n\n```typescript\nconst result = await altus4.auth.handleLogin({\n  email: 'user@example.com',\n  password: 'password123',\n});\n\nif (result.success) {\n  console.log('User authenticated:', result.user);\n  console.log('Token expires in:', result.expiresIn, 'seconds');\n}\n```\n\n**handleRegister(userData: RegisterRequest): Promise<AuthResult>**\n\nRegister a new user account.\n\n```typescript\nconst result = await altus4.auth.handleRegister({\n  name: 'John Doe',\n  email: 'john@example.com',\n  password: 'securePassword123',\n  role: 'user', // Optional: 'user' | 'admin'\n});\n```\n\n**getCurrentUser(): Promise<{success: boolean; user?: User; error?: any}>**\n\nGet the current authenticated user's profile.\n\n```typescript\nconst userResponse = await altus4.auth.getCurrentUser();\nif (userResponse.success) {\n  console.log('Current user:', userResponse.user);\n}\n```\n\n**updateProfile(updates: UpdateProfileRequest): Promise<{success: boolean; user?: User; error?: any}>**\n\nUpdate the authenticated user's profile.\n\n```typescript\nawait altus4.auth.updateProfile({\n  name: 'John Smith',\n  email: 'john.smith@example.com',\n});\n```\n\n**isAuthenticated(): boolean**\n\nCheck if the user is currently authenticated.\n\n```typescript\nif (altus4.auth.isAuthenticated()) {\n  // User is authenticated\n}\n```\n\n## Cookie-based authentication (recommended)\n\nStarting with the recent patch, the SDK supports a cookie-based refresh flow which is the recommended configuration for browser-based client apps.\n\nWhy use cookie-based refresh?\n\n- The refresh token is stored as an HttpOnly, Secure cookie by your backend. This prevents JavaScript from reading the refresh token (stronger XSS protection).\n\n- The SDK keeps a short-lived access token in memory and automatically calls the refresh endpoint to obtain a new access token when needed.\n\n- No sensitive tokens are persisted to `localStorage` by default in this flow.\n\nBackend requirements\n\n- On successful login, your server should set a refresh token cookie using `Set-Cookie` with attributes: `HttpOnly; Secure; SameSite=Lax` (or `Strict` as appropriate).\n\n- Provide a POST `/auth/refresh` endpoint which reads the refresh cookie and returns a fresh access token JSON: `{ token: string, expiresIn: number }`.\n\n- Implement POST `/auth/logout` to clear the refresh cookie.\n\nClient integration (SPA)\n\n- 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.\n\n- 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.\n\nSimple example (app bootstrap):\n\n```javascript\nimport { Altus4SDK } from '@altus4/sdk';\n\nconst sdk = new Altus4SDK({ baseURL: '/api' });\n\nasync function bootstrapApp() {\n  // Try to restore session from HttpOnly refresh cookie\n  const restored = await sdk.auth.restoreSession();\n  // Or use initializeAuthState() which also fetches user profile if restored\n  // const restoredFull = await sdk.auth.initializeAuthState();\n\n  if (restored && sdk.auth.isAuthenticated()) {\n    router.replace('/dashboard');\n  } else {\n    router.replace('/login');\n  }\n  mountApp();\n}\n\nbootstrapApp();\n```\n\nMigration note\n\n- 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.\n\n### API Keys Service\n\nThe ApiKeysService manages API keys for service-to-service authentication.\n\n#### Methods\n\n**createApiKey(keyData: CreateApiKeyRequest): Promise<ApiResponse<{ apiKey: ApiKey; secretKey: string }>>**\n\nCreate a new API key with specified permissions and rate limiting.\n\n```typescript\nconst keyResponse = await altus4.apiKeys.createApiKey({\n  name: 'Production API Key',\n  environment: 'live',\n  permissions: ['search', 'analytics'],\n  rateLimitTier: 'pro',\n  expiresAt: '2024-12-31',\n});\n```\n\n**listApiKeys(): Promise<ApiResponse<ApiKey[]>>**\n\nList all API keys for the authenticated user.\n\n```typescript\nconst keys = await altus4.apiKeys.listApiKeys();\nkeys.data?.forEach(key => {\n  console.log(`${key.name}: ${key.isActive ? 'active' : 'inactive'}`);\n});\n```\n\n**getApiKey(keyId: string): Promise<ApiResponse<ApiKey>>**\n\nGet details for a specific API key.\n\n```typescript\nconst key = await altus4.apiKeys.getApiKey('key-id-123');\n```\n\n**updateApiKey(keyId: string, updates: UpdateApiKeyRequest): Promise<ApiResponse<ApiKey>>**\n\nUpdate an existing API key's settings.\n\n```typescript\nawait altus4.apiKeys.updateApiKey('key-id-123', {\n  name: 'Updated Key Name',\n  permissions: ['search', 'analytics', 'admin'],\n  rateLimitTier: 'enterprise',\n});\n```\n\n**revokeApiKey(keyId: string): Promise<ApiResponse<void>>**\n\nRevoke an API key, making it immediately invalid.\n\n```typescript\nawait altus4.apiKeys.revokeApiKey('key-id-123');\n```\n\n**getApiKeyUsage(keyId: string): Promise<ApiResponse<ApiKeyUsage>>**\n\nGet usage statistics for an API key.\n\n```typescript\nconst usage = await altus4.apiKeys.getApiKeyUsage('key-id-123');\nconsole.log('Requests this month:', usage.data?.requestsThisMonth);\nconsole.log('Quota used / limit:', usage.data?.quotaUsed, '/', usage.data?.quotaLimit);\n```\n\n### Database Service\n\nThe DatabaseService manages MySQL database connections and schema discovery.\n\n#### Methods\n\n**addDatabaseConnection(connectionData: AddDatabaseConnectionRequest): Promise<ApiResponse<DatabaseConnection>>**\n\nAdd a new database connection configuration.\n\n```typescript\nconst connection = await altus4.database.addDatabaseConnection({\n  name: 'Production Database',\n  host: 'db.example.com',\n  port: 3306,\n  database: 'myapp_production',\n  username: 'readonly_user',\n  password: 'secure_password',\n  ssl: true,\n});\n```\n\n**listDatabaseConnections(): Promise<ApiResponse<DatabaseConnection[]>>**\n\nList all configured database connections.\n\n```typescript\nconst connections = await altus4.database.listDatabaseConnections();\n```\n\n**getDatabaseConnection(connectionId: string): Promise<ApiResponse<DatabaseConnection>>**\n\nGet details for a specific database connection.\n\n```typescript\nconst connection = await altus4.database.getDatabaseConnection('conn-123');\n```\n\n**updateDatabaseConnection(connectionId: string, updates: UpdateDatabaseConnectionRequest): Promise<ApiResponse<DatabaseConnection>>**\n\nUpdate a database connection's configuration.\n\n```typescript\nawait altus4.database.updateDatabaseConnection('conn-123', {\n  name: 'Updated Connection Name',\n  ssl: true,\n});\n```\n\n**removeDatabaseConnection(connectionId: string): Promise<ApiResponse<{success: boolean}>>**\n\nRemove a database connection configuration.\n\n```typescript\nawait altus4.database.removeDatabaseConnection('conn-123');\n```\n\n**testDatabaseConnection(connectionId: string): Promise<ApiResponse<ConnectionTestResult>>**\n\nTest connectivity to a configured database.\n\n```typescript\nconst test = await altus4.database.testDatabaseConnection('conn-123');\nif (test.data?.connected) {\n  console.log('Database connection successful');\n}\n```\n\n**getDatabaseSchema(connectionId: string): Promise<ApiResponse<TableSchema[]>>**\n\nDiscover the schema for a connected database.\n\n```typescript\nconst schema = await altus4.database.getDatabaseSchema('conn-123');\nschema.data?.forEach(table => {\n  console.log(`Table: ${table.table} (${table.estimatedRows} rows)`);\n});\n```\n\n### Analytics Service\n\nThe AnalyticsService provides access to search analytics and AI-powered insights.\n\n#### Methods\n\n**getDashboardAnalytics(request: { period: 'day' | 'week' | 'month' | 'year' }): Promise<ApiResponse<AnalyticsData>>**\n\nGet comprehensive dashboard analytics data.\n\n```typescript\nconst dashboard = await altus4.analytics.getDashboardAnalytics({\n  period: 'month',\n  startDate: '2024-01-01',\n  endDate: '2024-01-31',\n});\n\nconsole.log('Total searches:', dashboard.data?.totalSearches);\nconsole.log('Average response time:', dashboard.data?.averageResponseTime);\n```\n\n**getTrends(request: { period: 'day' | 'week' | 'month' | 'year'; startDate?: string; endDate?: string }): Promise<ApiResponse<AnalyticsTrends>>**\n\nGet search trend analysis and patterns.\n\n```typescript\nconst trends = await altus4.analytics.getSearchTrends({\n  period: 'week',\n});\n```\n\n<!-- Popular queries endpoint is not currently exposed by the SDK -->\n\n**getSearchHistory(query?: AnalyticsQuery): Promise<ApiResponse<any[]>>**\n\nGet detailed search history with pagination.\n\n```typescript\nconst history = await altus4.analytics.getSearchHistory({\n  limit: 50,\n  offset: 0,\n  startDate: '2024-01-01',\n  endDate: '2024-01-31',\n});\n```\n\n**getInsights(request: { period: 'day' | 'week' | 'month' | 'year'; startDate?: string; endDate?: string }): Promise<ApiResponse<AnalyticsInsights>>**\n\nGet AI-generated insights and recommendations.\n\n```typescript\nconst insights = await altus4.analytics.getInsights({ period: 'month' });\ninsights.data?.insights.forEach(insight => {\n  console.log(insight.title, '-', insight.description);\n});\n```\n\n### Management Service\n\nThe ManagementService provides system health checks and management operations.\n\n#### Methods\n\n**getSystemHealth(): Promise<ApiResponse<SystemStatus>>**\n\nCheck overall system health and status.\n\n```typescript\nconst health = await altus4.management.getSystemHealth();\nconsole.log('System status:', health.data?.status);\nconsole.log('Uptime:', health.data?.uptime);\n```\n\n**testConnection(): Promise<ApiResponse<ConnectionTestResult>>**\n\nTest API connectivity and authentication.\n\n```typescript\nconst test = await altus4.management.testConnection();\nif (test.data?.connected) {\n  console.log('API connection successful');\n}\n```\n\n**getMigrationStatus(): Promise<ApiResponse<MigrationStatus>>**\n\nCheck migration status for new authentication system.\n\n```typescript\nconst status = await altus4.management.getMigrationStatus();\nif (!status.data?.hasMigrated) {\n  console.log('Migration needed:', status.data?.recommendedAction);\n}\n```\n\n**setupInitialApiKey(): Promise<ApiResponse<ApiKey>>**\n\nCreate initial API key for new users (requires JWT authentication).\n\n```typescript\nconst initialKey = await altus4.management.setupInitialApiKey();\nconsole.log('Initial API key created:', initialKey.data?.key);\n```\n\n## Utility Functions\n\nThe SDK includes comprehensive utility functions for common operations.\n\n### Validation\n\n```typescript\nimport { validateEmail, validatePassword, validateApiKeyCreation } from './sdk/utils';\n\n// Email validation\nconst isValidEmail = validateEmail('user@example.com');\n\n// Password strength validation\nconst passwordValidation = validatePassword('myPassword123!');\nif (!passwordValidation.isValid) {\n  console.log('Password errors:', passwordValidation.errors);\n}\n\n// API key creation validation\nconst keyValidation = validateApiKeyCreation({\n  name: 'Test Key',\n  environment: 'test',\n  permissions: ['search'],\n});\n```\n\n### Formatting\n\n```typescript\nimport {\n  formatNumber, // 1,234,567\n  formatCompactNumber, // 1.23M\n  formatResponseTime, // 250ms / 1.50s\n  formatRelativeTime, // 1 hour ago\n  getRateLimitInfo, // { limit, name, description }\n} from './sdk/utils';\n\nconsole.log(formatNumber(1234567)); // \"1,234,567\"\nconsole.log(formatCompactNumber(2500000)); // \"2.50M\"\nconsole.log(formatResponseTime(1500)); // \"1.50s\"\n\nconst oneHourAgo = new Date(Date.now() - 3600000);\nconsole.log(formatRelativeTime(oneHourAgo)); // \"1 hour ago\"\n\nconst rateLimitInfo = getRateLimitInfo('pro');\nconsole.log(rateLimitInfo.description); // \"10,000 requests per hour\"\n```\n\n### Date Utilities\n\n```typescript\nimport { getDateRangeForPeriod, formatDateForQuery } from './sdk/utils';\n\n// Get date range for analytics periods\nconst monthRange = getDateRangeForPeriod('month');\nconsole.log(monthRange); // { startDate: \"YYYY-MM-DD\", endDate: \"YYYY-MM-DD\" }\n\n// Format dates for API queries\nconst queryDate = formatDateForQuery(new Date()); // \"YYYY-MM-DD\"\n```\n\n## Error Handling\n\nThe SDK provides consistent error handling patterns across all services:\n\n```typescript\ntry {\n  const result = await altus4.auth.handleLogin({\n    email: 'user@example.com',\n    password: 'wrongpassword',\n  });\n\n  if (!result.success) {\n    // Handle API errors\n    console.error('Login failed:', result.error?.message);\n    console.error('Error code:', result.error?.code);\n  }\n} catch (error) {\n  // Handle network or other errors\n  console.error('Request failed:', error);\n}\n```\n\n### Common Error Codes\n\nThe SDK normalizes network errors and forwards server error bodies as-is. Common codes in `ErrorCode`:\n\n- `VALIDATION_ERROR`\n- `AUTHENTICATION_ERROR`\n- `AUTHORIZATION_ERROR`\n- `NOT_FOUND`\n- `RATE_LIMIT_EXCEEDED`\n- `INTERNAL_ERROR`\n- `NETWORK_ERROR`\n- `DATABASE_ERROR`\n\n## Advanced Usage\n\n### Individual Service Usage\n\n```typescript\nimport { AuthService, ApiKeysService } from './sdk';\n\n// Use services independently\nconst auth = new AuthService({\n  baseURL: 'https://api.altus4.com/api/v1',\n});\n\nconst apiKeys = new ApiKeysService({\n  baseURL: 'https://api.altus4.com/api/v1',\n});\n\nconst loginResult = await auth.handleLogin(credentials);\nconst keys = await apiKeys.listApiKeys();\n```\n\n### Custom Configuration\n\n```typescript\nconst altus4 = new Altus4SDK({\n  baseURL: 'https://custom-api.example.com/api/v1',\n  timeout: 60000, // 60 seconds\n  headers: {\n    'X-Custom-Header': 'value',\n  },\n});\n```\n\n### Token Management\n\n```typescript\n// Manual token management\naltus4.setToken('your-jwt-token', 3600); // 1 hour expiry\n\n// Check authentication status\nif (altus4.isAuthenticated()) {\n  console.log('User is authenticated');\n}\n\n// Automatic token refresh\nconst refreshed = await altus4.refreshTokenIfNeeded();\nif (!refreshed) {\n  // Redirect to login or handle re-authentication\n  console.log('Token refresh failed, re-authentication required');\n}\n\n// Clear authentication\naltus4.clearToken();\n```\n\n## Type Definitions\n\nThe 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*`).\n\n## Browser and Node.js Compatibility\n\nThe SDK is compatible with:\n\n- **Browsers**: Chrome 70+, Firefox 65+, Safari 12+, Edge 79+\n- **Node.js**: 14.0+\n- **TypeScript**: 4.0+\n\n## Development\n\n### Building the SDK\n\n```bash\n# Install dependencies\nnpm install\n\n# Build TypeScript to JavaScript\nnpm run build\n\n# Run type checking\nnpm run typecheck\n\n# Development mode with watch\nnpm run dev\n```\n\n### Testing\n\n```bash\n# Run unit tests\nnpm test\n\n# Run tests with coverage\nnpm run test:coverage\n\n# Run tests in watch mode\nnpm run test:watch\n```\n\n## Configuration\n\n### Environment Variables\n\nFor development, you can set default configuration via environment variables:\n\n```bash\nALTUS4_API_URL=https://api.altus4.com/api/v1\nALTUS4_TIMEOUT=30000\n```\n\n### Configuration File\n\nCreate a configuration file for shared settings:\n\n```typescript\n// altus4.config.ts\nexport const altus4Config = {\n  baseURL: process.env.ALTUS4_API_URL || 'http://localhost:3000/api/v1',\n  timeout: 30000,\n  retryAttempts: 3,\n};\n\n// Use in your application\nconst altus4 = new Altus4SDK(altus4Config);\n```\n\n## Best Practices\n\n1. **Error Handling**: Always check the `success` property of API responses\n2. **Token Management**: Implement automatic token refresh for long-running applications\n3. **Rate Limiting**: Respect rate limits and implement backoff strategies\n4. **Security**: Never log or expose API keys or JWT tokens\n5. **Validation**: Use the built-in validation utilities before making API calls\n6. **Caching**: Cache frequently accessed data to reduce API calls\n7. **Monitoring**: Track API usage and response times for performance optimization\n\n## Support\n\nFor issues, questions, or contributions:\n\n1. Check the existing documentation and type definitions\n2. Review the parent Altus 4 API documentation\n3. Follow the established code patterns and conventions\n4. Ensure all changes maintain TypeScript compatibility\n5. Add appropriate error handling and validation\n\n## License\n\nThis SDK is licensed under the Apache License, Version 2.0. See the included LICENSE file for the full terms.\n","readmeFilename":"README.md"}