@bernierllc/chat-suite 1.0.0

package/.eslintrc.js

@@ -0,0 +1,26 @@
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+
+module.exports = {
+  parser: '@typescript-eslint/parser',
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended'
+  ],
+  parserOptions: {
+    ecmaVersion: 2020,
+    sourceType: 'module',
+    project: './tsconfig.json'
+  },
+  rules: {
+    '@typescript-eslint/explicit-module-boundary-types': 'error',
+    '@typescript-eslint/no-explicit-any': 'error',
+    '@typescript-eslint/no-unused-vars': 'error',
+    'no-console': 'off'
+  }
+};

package/README.md

@@ -0,0 +1,542 @@
+# @bernierllc/chat-suite
+
+Comprehensive chat orchestration suite with AI-powered routing and multi-provider support.
+
+## Installation
+
+```bash
+npm install @bernierllc/chat-suite
+```
+
+## Overview
+
+The Chat Suite provides a unified interface for orchestrating multiple chat providers (ChatKit, Slack, Discord, Teams) with AI-powered routing, analytics, and NeverHub integration. It handles cross-platform message bridging, user management, health monitoring, and intelligent message routing.
+
+## Features
+
+- **Multi-Provider Orchestration** - Unified interface for multiple chat platforms
+- **AI-Powered Routing** - Intelligent message routing based on intent analysis
+- **Cross-Platform Bridging** - Seamless message flow between platforms
+- **User Management** - Unified user identity across all platforms
+- **Health Monitoring** - Real-time health status of all providers
+- **NeverHub Integration** - Service discovery and event orchestration
+- **Analytics Integration** - Comprehensive usage metrics and insights
+- **Graceful Degradation** - Works with minimal configuration
+
+## Quick Start
+
+### Minimal Configuration (ChatKit Only)
+
+```typescript
+import { ChatSuite } from '@bernierllc/chat-suite';
+
+const chatSuite = new ChatSuite({
+  providers: {
+    chatkit: {
+      enabled: true,
+      priority: 1,
+      config: {
+        serviceName: 'chatkit-adapter'
+      }
+    }
+  }
+});
+
+await chatSuite.initialize();
+
+// Send a message
+const result = await chatSuite.sendMessage('chatkit', {
+  content: 'Hello from the chat suite!',
+  userId: 'user123'
+});
+
+console.log('Message sent:', result.data?.messageId);
+```
+
+### Full Configuration (Multiple Providers)
+
+```typescript
+import { ChatSuite } from '@bernierllc/chat-suite';
+
+const chatSuite = new ChatSuite({
+  enabled: true,
+
+  providers: {
+    chatkit: {
+      enabled: true,
+      priority: 1,
+      config: {
+        serviceName: 'chatkit-adapter',
+        features: ['streaming', 'attachments', 'threads']
+      }
+    },
+    slack: {
+      enabled: true,
+      priority: 2,
+      config: {
+        serviceName: 'chat-integration-slack',
+        channels: ['#general', '#dev']
+      }
+    }
+  },
+
+  aiRouting: {
+    enabled: true,
+    serviceName: 'chat-ai-router',
+    fallbackToHuman: true,
+    intentThreshold: 0.8
+  },
+
+  analytics: {
+    enabled: true,
+    serviceName: 'chat-analytics',
+    metricsInterval: 60000
+  },
+
+  neverhub: {
+    enabled: true,
+    serviceName: 'chat-suite',
+    capabilities: [
+      { type: 'chat', name: 'multi-provider-chat', version: '1.0.0' },
+      { type: 'orchestration', name: 'chat-orchestration', version: '1.0.0' }
+    ],
+    dependencies: ['chat-provider-*', 'chat-ai-router', 'chat-analytics']
+  }
+});
+
+await chatSuite.initialize();
+```
+
+## Core Concepts
+
+### Providers
+
+Providers are chat platform adapters that implement a common interface:
+
+- **ChatKit** (Required) - Primary chat provider using `@bernierllc/chatkit-adapter`
+- **Slack** (Optional) - Requires `@bernierllc/chat-integration-slack`
+- **Discord** (Optional) - Requires `@bernierllc/chat-integration-discord`
+- **Teams** (Optional) - Requires `@bernierllc/chat-integration-teams`
+
+### Priority System
+
+Providers are assigned priorities (1 = highest). Messages are routed to the highest priority available provider unless specified otherwise.
+
+### Message Orchestration
+
+The suite coordinates messages across providers, handling:
+- Message queueing and delivery
+- Cross-platform bridging
+- Retry logic with exponential backoff
+- Error handling and recovery
+
+## API Reference
+
+### ChatSuite
+
+Main orchestration class.
+
+#### `constructor(config?: Partial<ChatSuiteConfig>)`
+
+Create a new chat suite instance.
+
+```typescript
+const suite = new ChatSuite({
+  providers: {
+    chatkit: { enabled: true, priority: 1, config: {} }
+  }
+});
+```
+
+#### `async initialize(): Promise<SuiteInitResult>`
+
+Initialize the chat suite and all enabled providers.
+
+```typescript
+const result = await suite.initialize();
+console.log('Initialized providers:', result.providersInitialized);
+```
+
+#### `async sendMessage(providerType, message): Promise<SuiteResult<ProviderMessageResult>>`
+
+Send a message through a specific provider.
+
+```typescript
+const result = await suite.sendMessage('chatkit', {
+  content: 'Hello!',
+  userId: 'user123',
+  channelId: 'channel456'
+});
+```
+
+#### `async broadcastMessage(config): Promise<SuiteResult<ProviderMessageResult[]>>`
+
+Broadcast a message to multiple providers.
+
+```typescript
+const result = await suite.broadcastMessage({
+  content: 'Important announcement!',
+  platforms: ['chatkit', 'slack'],
+  channels: ['#announcements'],
+  priority: MessagePriority.HIGH
+});
+```
+
+#### `async getHealth(): Promise<ChatSuiteHealth>`
+
+Get health status of all providers.
+
+```typescript
+const health = await suite.getHealth();
+console.log('Suite status:', health.status);
+console.log('Provider health:', health.providers);
+```
+
+#### `getUserManager(): UserManager`
+
+Get the user manager for cross-platform user management.
+
+```typescript
+const userManager = suite.getUserManager();
+
+userManager.registerUser({
+  provider: 'chatkit',
+  platformUserId: 'chatkit123',
+  displayName: 'John Doe',
+  email: 'john@example.com'
+});
+```
+
+#### `getConfigManager(): ConfigManager`
+
+Get the configuration manager.
+
+```typescript
+const configManager = suite.getConfigManager();
+
+configManager.updateConfig({
+  analytics: { enabled: false }
+});
+```
+
+#### `async shutdown(): Promise<void>`
+
+Shutdown the chat suite and all providers.
+
+```typescript
+await suite.shutdown();
+```
+
+### UserManager
+
+Cross-platform user identity management.
+
+```typescript
+const userManager = suite.getUserManager();
+
+// Register a user
+const result = userManager.registerUser({
+  provider: 'chatkit',
+  platformUserId: 'chatkit123',
+  displayName: 'Alice',
+  email: 'alice@example.com'
+});
+
+const unifiedId = result.data?.unifiedId;
+
+// Link another platform
+userManager.linkPlatform(unifiedId!, 'slack', 'slack456');
+
+// Get unified ID from platform ID
+const id = userManager.getUnifiedId('chatkit', 'chatkit123');
+
+// Search users
+const users = userManager.searchUsers('Alice');
+```
+
+## Usage Examples
+
+### Basic Chat Operations
+
+```typescript
+import { ChatSuite, MessagePriority } from '@bernierllc/chat-suite';
+
+const suite = new ChatSuite();
+await suite.initialize();
+
+// Send a simple message
+await suite.sendMessage('chatkit', {
+  content: 'Hello, world!',
+  userId: 'user123'
+});
+
+// Send a message with attachments
+await suite.sendMessage('chatkit', {
+  content: 'Check out this file',
+  userId: 'user123',
+  attachments: [{
+    filename: 'document.pdf',
+    contentType: 'application/pdf',
+    data: fileBuffer,
+    size: fileBuffer.length
+  }]
+});
+
+// Broadcast to multiple platforms
+await suite.broadcastMessage({
+  content: 'System maintenance tonight at 10 PM',
+  platforms: ['chatkit', 'slack'],
+  priority: MessagePriority.URGENT
+});
+```
+
+### User Management
+
+```typescript
+const userManager = suite.getUserManager();
+
+// Register users from different platforms
+userManager.registerUser({
+  provider: 'chatkit',
+  platformUserId: 'chatkit123',
+  displayName: 'Alice',
+  email: 'alice@example.com'
+});
+
+userManager.registerUser({
+  provider: 'slack',
+  platformUserId: 'slack456',
+  displayName: 'Bob',
+  email: 'bob@example.com'
+});
+
+// Link platforms for the same user
+const aliceId = userManager.getUnifiedId('chatkit', 'chatkit123');
+userManager.linkPlatform(aliceId!, 'slack', 'slackAlice');
+
+// Search for users
+const results = userManager.searchUsers('alice@example.com');
+```
+
+### Health Monitoring
+
+```typescript
+// Get overall health
+const health = await suite.getHealth();
+
+console.log('Suite Status:', health.status);
+console.log('ChatKit Health:', health.providers.chatkit);
+
+// Check specific provider
+const providerManager = suite.getProviderManager();
+const chatkit = providerManager.getProvider('chatkit');
+
+if (chatkit) {
+  const providerHealth = await chatkit.getHealth();
+  console.log('ChatKit Latency:', providerHealth.latency);
+  console.log('Error Count:', providerHealth.errorCount);
+}
+```
+
+### Configuration Management
+
+```typescript
+const configManager = suite.getConfigManager();
+
+// Update configuration
+configManager.updateConfig({
+  analytics: { enabled: false },
+  aiRouting: {
+    enabled: true,
+    intentThreshold: 0.9
+  }
+});
+
+// Get current config
+const config = configManager.getConfig();
+
+// Export configuration
+const json = configManager.toJSON();
+
+// Load configuration
+configManager.fromJSON(json);
+```
+
+## External Provider Integration
+
+The suite supports optional external providers. To enable them:
+
+### Slack Integration
+
+```bash
+npm install @bernierllc/chat-integration-slack
+```
+
+```typescript
+import { ChatSuite } from '@bernierllc/chat-suite';
+// When available: import { SlackProvider } from '@bernierllc/chat-integration-slack';
+
+const suite = new ChatSuite({
+  providers: {
+    chatkit: { enabled: true, priority: 1, config: {} },
+    slack: {
+      enabled: true,
+      priority: 2,
+      config: {
+        token: process.env.SLACK_BOT_TOKEN,
+        channels: ['#general', '#dev']
+      }
+    }
+  }
+});
+```
+
+### Discord Integration
+
+```bash
+npm install @bernierllc/chat-integration-discord
+```
+
+```typescript
+// When available: import { DiscordProvider } from '@bernierllc/chat-integration-discord';
+
+const suite = new ChatSuite({
+  providers: {
+    chatkit: { enabled: true, priority: 1, config: {} },
+    discord: {
+      enabled: true,
+      priority: 3,
+      config: {
+        token: process.env.DISCORD_BOT_TOKEN,
+        guilds: ['123456789012345678']
+      }
+    }
+  }
+});
+```
+
+### Teams Integration
+
+```bash
+npm install @bernierllc/chat-integration-teams
+```
+
+```typescript
+// When available: import { TeamsProvider } from '@bernierllc/chat-integration-teams';
+
+const suite = new ChatSuite({
+  providers: {
+    chatkit: { enabled: true, priority: 1, config: {} },
+    teams: {
+      enabled: true,
+      priority: 4,
+      config: {
+        tenantId: process.env.TEAMS_TENANT_ID,
+        clientId: process.env.TEAMS_CLIENT_ID,
+        clientSecret: process.env.TEAMS_CLIENT_SECRET
+      }
+    }
+  }
+});
+```
+
+## NeverHub Integration
+
+The suite integrates with NeverHub for service discovery and event orchestration:
+
+```typescript
+const suite = new ChatSuite({
+  neverhub: {
+    enabled: true,
+    serviceName: 'chat-suite',
+    capabilities: [
+      { type: 'chat', name: 'multi-provider-chat', version: '1.0.0' },
+      { type: 'orchestration', name: 'chat-orchestration', version: '1.0.0' }
+    ],
+    dependencies: ['chat-provider-*', 'chat-ai-router', 'chat-analytics']
+  }
+});
+
+await suite.initialize();
+
+// NeverHub will automatically:
+// - Register the chat suite as a service
+// - Discover available chat providers
+// - Publish message events
+// - Subscribe to relevant events
+// - Report health status
+```
+
+## Integration Status
+
+- **Logger**: Not applicable (suite-level component, uses console logging)
+- **Docs-Suite**: Ready - All types and APIs documented with JSDoc
+- **NeverHub**: Integrated - Full service discovery, event publishing, and health monitoring
+
+## TypeScript Support
+
+Full TypeScript support with strict type checking:
+
+```typescript
+import {
+  ChatSuite,
+  ChatSuiteConfig,
+  MessagePriority,
+  ProviderType,
+  SuiteResult
+} from '@bernierllc/chat-suite';
+
+const config: ChatSuiteConfig = {
+  enabled: true,
+  providers: {
+    chatkit: {
+      enabled: true,
+      priority: 1,
+      config: {}
+    }
+  }
+};
+
+const suite = new ChatSuite(config);
+```
+
+## Error Handling
+
+All operations return structured results:
+
+```typescript
+const result = await suite.sendMessage('chatkit', {
+  content: 'Test message'
+});
+
+if (!result.success) {
+  console.error('Message failed:', result.error);
+} else {
+  console.log('Message sent:', result.data?.messageId);
+}
+```
+
+## Dependencies
+
+### Required
+- `@bernierllc/neverhub-adapter` - NeverHub integration
+- `@bernierllc/chatkit-adapter` - ChatKit provider
+- `@bernierllc/chat-ai-router` - AI routing (optional feature)
+- `@bernierllc/chat-analytics` - Analytics (optional feature)
+- `zod` - Configuration validation
+
+### Optional (Peer Dependencies)
+- `@bernierllc/chat-integration-slack` - Slack integration
+- `@bernierllc/chat-integration-discord` - Discord integration
+- `@bernierllc/chat-integration-teams` - Teams integration
+
+## License
+
+Copyright (c) 2025 Bernier LLC. All rights reserved.
+
+## See Also
+
+- [@bernierllc/chatkit-adapter](../chatkit-adapter) - ChatKit provider implementation
+- [@bernierllc/chat-ai-router](../chat-ai-router) - AI-powered message routing
+- [@bernierllc/chat-analytics](../chat-analytics) - Chat analytics and insights
+- [@bernierllc/neverhub-adapter](../../core/neverhub-adapter) - NeverHub integration