@astermind/cybernetic-chatbot-client 1.0.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 AsterMind Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,667 @@
+# @astermind/cybernetic-chatbot-client
+
+Offline-capable AI chatbot client with local RAG fallback and agentic capabilities for [AsterMind](https://astermind.ai).
+
+[![npm version](https://img.shields.io/npm/v/@astermind/cybernetic-chatbot-client.svg)](https://www.npmjs.com/package/@astermind/cybernetic-chatbot-client)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)](https://www.typescriptlang.org/)
+
+## What is Cybernetic Chatbot Client?
+
+Cybernetic Chatbot Client is the official JavaScript SDK for integrating [AsterMind](https://astermind.ai) AI chatbot capabilities into your web applications. It provides a robust, offline-first architecture that ensures your users always get answers, even when disconnected from the server.
+
+## Key Features
+
+- **Offline-First Architecture** - IndexedDB caching with TF-IDF local search
+- **SSE Streaming** - Real-time token-by-token responses
+- **Session Management** - Multi-turn conversation continuity
+- **Configurable Retry Logic** - Exponential backoff with customizable settings
+- **Connection Status Monitoring** - Real-time online/offline detection
+- **Maintenance Mode Support** - Graceful degradation per ADR-200
+- **Agentic Capabilities** - Intent classification and DOM automation (full bundle)
+- **Tree-Shakeable** - Import only what you need
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Licensing](#licensing)
+- [Configuration](#configuration)
+- [Features](#features)
+  - [Offline-First Architecture](#offline-first-architecture)
+  - [Streaming Responses](#streaming-responses)
+  - [Session Management](#session-management)
+  - [Agentic Capabilities](#agentic-capabilities)
+  - [Maintenance Mode Support](#maintenance-mode-support)
+- [Bundle Options](#bundle-options)
+- [API Reference](#api-reference)
+- [Browser Support](#browser-support)
+- [Integration with Cybernetic Chatbot Backend](#integration-with-cybernetic-chatbot-backend)
+- [License](#license)
+
+## Installation
+
+### npm / yarn / pnpm
+
+```bash
+npm install @astermind/cybernetic-chatbot-client
+```
+
+```bash
+yarn add @astermind/cybernetic-chatbot-client
+```
+
+```bash
+pnpm add @astermind/cybernetic-chatbot-client
+```
+
+### CDN (Script Tag)
+
+```html
+<!-- Core bundle -->
+<script src="https://unpkg.com/@astermind/cybernetic-chatbot-client/dist/cybernetic-chatbot-client.umd.js"></script>
+
+<!-- Or full bundle with agentic capabilities -->
+<script src="https://unpkg.com/@astermind/cybernetic-chatbot-client/dist/cybernetic-chatbot-client-full.umd.js"></script>
+```
+
+## Quick Start
+
+> **Note:** No license key is required for development. See [Licensing](#licensing) for production requirements.
+
+### Basic Usage
+
+```typescript
+import { CyberneticClient } from '@astermind/cybernetic-chatbot-client';
+
+const client = new CyberneticClient({
+  apiUrl: 'https://api.astermind.ai',
+  apiKey: 'am_your_api_key',
+  // licenseKey: 'your-license-key',  // Optional in development, required in production
+  fallback: {
+    enabled: true,
+    cacheOnConnect: true
+  },
+  onStatusChange: (status) => {
+    console.log('Connection status:', status);
+  }
+});
+
+// Simple question
+const response = await client.ask('What is AsterMind?');
+console.log(response.reply);
+
+// With streaming
+await client.askStream('Tell me about RAG', {
+  onToken: (token) => process.stdout.write(token),
+  onSources: (sources) => console.log('Sources:', sources),
+  onComplete: (response) => console.log('\nDone:', response.sessionId)
+});
+```
+
+### Script Tag Integration
+
+```html
+<script
+  src="https://unpkg.com/@astermind/cybernetic-chatbot-client/dist/cybernetic-chatbot-client.umd.js"
+  data-astermind-key="am_your_api_key"
+  data-astermind-url="https://api.astermind.ai"
+></script>
+```
+
+### Global Config Object
+
+```html
+<script>
+  window.astermindConfig = {
+    apiUrl: 'https://api.astermind.ai',
+    apiKey: 'am_your_api_key',
+    fallback: { enabled: true }
+  };
+</script>
+<script src="https://unpkg.com/@astermind/cybernetic-chatbot-client/dist/cybernetic-chatbot-client.umd.js"></script>
+```
+
+## Licensing
+
+**Free for Development** — This package is free to use during development and testing. No license key is required for local development environments.
+
+**License Required for Production** — A valid license key is required for production deployments. Without a license, chatbot responses in production will include a visible license notice. Licenses are available at [https://astermind.ai](https://astermind.ai).
+
+### License Products
+
+| Product | Feature Flag | Included With |
+|---------|--------------|---------------|
+| **Cybernetic Chatbot Client** | `cybernetic-chatbot-client` | Cybernetic Chatbot purchase |
+| **Agentic Add-On** | `agentic` | Separate Agentic Add-On purchase |
+
+- **Cybernetic Chatbot**: Includes the `cybernetic-chatbot-client` feature, enabling all core client functionality (API communication, offline caching, streaming, session management).
+- **Agentic Add-On**: Requires a separate purchase. Enables the `agentic` feature for intent classification and DOM automation capabilities.
+
+### Applying Your License Key
+
+Add your license key to the client configuration:
+
+```typescript
+import { CyberneticClient } from '@astermind/cybernetic-chatbot-client';
+
+const client = new CyberneticClient({
+  apiUrl: 'https://api.astermind.ai',
+  apiKey: 'am_your_api_key',
+  licenseKey: 'eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...'  // Your license key (JWT)
+});
+```
+
+For script tag integration:
+
+```html
+<script>
+  window.astermindConfig = {
+    apiUrl: 'https://api.astermind.ai',
+    apiKey: 'am_your_api_key',
+    licenseKey: 'eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...'
+  };
+</script>
+<script src="https://unpkg.com/@astermind/cybernetic-chatbot-client/dist/cybernetic-chatbot-client.umd.js"></script>
+```
+
+### Enforcement Behavior
+
+The license system uses environment-aware enforcement:
+
+| Environment | Detection | License Required? | Behavior |
+|-------------|-----------|-------------------|----------|
+| **Development** | `localhost`, `127.0.0.1`, `.local`, `.dev`, dev ports (3000, 5173, 8080, etc.) | **No** | Free to use. Console warnings only. |
+| **Production** | All other URLs | **Yes** | License warning appended to responses if missing/invalid. |
+
+**Development Mode** (free, soft enforcement):
+- **No license key required** — develop and test without any restrictions
+- Console warnings are logged when license is missing, expired, or invalid (for awareness)
+- Console warnings when using features not included in your license
+- All functionality works normally — responses are returned unchanged
+
+**Production Mode** (license required, hard enforcement):
+- A valid license key is required for production use
+- Without a valid license, chatbot responses include a visible notice:
+
+  *"⚠️ License Notice: Your AsterMind license key needs to be updated. Please contact support@astermind.ai or visit https://astermind.ai/license to renew your license."*
+
+- With a valid license, responses are returned normally without any modifications
+
+### Checking License Status
+
+```typescript
+// Get current status including license state
+const status = client.getStatus();
+console.log(status.license);
+// {
+//   status: 'valid' | 'invalid' | 'expired' | 'missing' | 'eval',
+//   payload: { plan, features, exp, ... },
+//   daysRemaining: 30,
+//   inGracePeriod: false
+// }
+
+// Get license manager for advanced operations
+const license = client.getLicenseManager();
+
+// Check if license is valid
+license.isValid();
+
+// Check specific features
+license.hasFeature('cybernetic-chatbot-client');
+license.hasFeature('agentic');
+
+// Get human-readable status
+license.getStatusMessage();
+// "License valid (30 days remaining)"
+```
+
+### Feature Validation
+
+The client automatically validates features:
+
+- **Client feature** (`cybernetic-chatbot-client`): Checked on client initialization
+- **Agentic feature** (`agentic`): Checked only when agentic capabilities are used
+
+If a required feature is missing, the console displays:
+- Current license plan
+- Available features in your license
+- The missing feature name
+- Link to upgrade at https://astermind.ai/license
+
+### Obtaining a License
+
+1. Visit [https://astermind.ai](https://astermind.ai)
+2. Purchase **Cybernetic Chatbot** for core client functionality
+3. Optionally purchase the **Agentic Add-On** for DOM automation features
+4. Your license key (JWT token) will be provided in your account dashboard
+5. Add the license key to your client configuration
+
+For licensing questions, contact support@astermind.ai.
+
+## Configuration
+
+### Full Configuration Interface
+
+```typescript
+interface CyberneticConfig {
+  /** Backend API URL (required) */
+  apiUrl: string;
+
+  /** API key for authentication - must start with 'am_' (required) */
+  apiKey: string;
+
+  /** License key (JWT token) from https://astermind.ai */
+  licenseKey?: string;
+
+  /** Fallback/offline configuration */
+  fallback?: {
+    /** Enable offline fallback (default: true) */
+    enabled?: boolean;
+
+    /** Cache max age in milliseconds (default: 86400000 = 24 hours) */
+    cacheMaxAge?: number;
+
+    /** Sync documents on connect (default: true) */
+    cacheOnConnect?: boolean;
+
+    /** Storage type (default: 'indexeddb') */
+    cacheStorage?: 'indexeddb' | 'localstorage';
+  };
+
+  /** Retry configuration */
+  retry?: {
+    /** Max retries before fallback (default: 2) */
+    maxRetries?: number;
+
+    /** Initial delay in ms (default: 1000) */
+    initialDelay?: number;
+
+    /** Use exponential backoff (default: true) */
+    exponentialBackoff?: boolean;
+  };
+
+  /** Event callbacks */
+  onStatusChange?: (status: ConnectionStatus) => void;
+  onError?: (error: CyberneticError) => void;
+
+  /** Agentic capabilities configuration (requires full bundle) */
+  agentic?: AgenticConfig;
+}
+
+type ConnectionStatus = 'online' | 'offline' | 'connecting' | 'error';
+```
+
+### Agentic Configuration
+
+```typescript
+interface AgenticConfig {
+  /** Enable agentic DOM interactions (default: false) */
+  enabled: boolean;
+
+  /** Confidence threshold for action execution (default: 0.8) */
+  confidenceThreshold?: number;
+
+  /** Allowed DOM actions */
+  allowedActions?: ('click' | 'fill' | 'scroll' | 'navigate' | 'select')[];
+
+  /** Require user confirmation before actions (default: true) */
+  requireConfirmation?: boolean;
+
+  /** Maximum actions per conversation turn (default: 5) */
+  maxActionsPerTurn?: number;
+
+  /** CSS selectors to never interact with */
+  blockedSelectors?: string[];
+
+  /** Only allow actions within these selectors */
+  allowedSelectors?: string[];
+}
+```
+
+## Features
+
+### Offline-First Architecture
+
+The client uses IndexedDB for local caching and TF-IDF for similarity search, enabling offline functionality:
+
+```typescript
+const client = new CyberneticClient({
+  apiUrl: 'https://api.astermind.ai',
+  apiKey: 'am_your_api_key',
+  fallback: {
+    enabled: true,
+    cacheOnConnect: true,    // Cache responses for offline use
+    cacheMaxAge: 86400000,   // 24 hours
+    cacheStorage: 'indexeddb'
+  }
+});
+
+// Check connection status
+const status = client.getStatus();
+console.log(status.connection); // 'online' | 'offline' | 'connecting'
+console.log(status.cache);      // { documentCount, lastSyncAt, cacheSize, isStale }
+
+// Response includes offline indicator
+const response = await client.ask('cached question');
+if (response.offline) {
+  console.log('Response from local cache');
+  console.log('Confidence:', response.confidence); // 'medium' or 'low' when offline
+}
+
+// Manually sync cache
+await client.syncCache();
+
+// Clear cache
+await client.clearCache();
+```
+
+**Cache Validation**: The server controls cache retention via `cacheRetentionHours` (default: 168 hours / 7 days). The client respects this setting and marks responses as stale when appropriate.
+
+### Streaming Responses
+
+Real-time token streaming via Server-Sent Events (SSE):
+
+```typescript
+await client.askStream('Explain quantum computing', {
+  onToken: (token) => {
+    // Called for each token as it arrives
+    document.getElementById('output').textContent += token;
+  },
+  onSources: (sources) => {
+    // Called when sources are available
+    console.log('Sources:', sources);
+  },
+  onComplete: (response) => {
+    // Called when streaming is complete
+    console.log('Session ID:', response.sessionId);
+  },
+  onError: (error) => {
+    // Called on error
+    console.error('Error:', error.message);
+  }
+});
+```
+
+### Session Management
+
+Maintain conversation context across multiple turns:
+
+```typescript
+// First message establishes session
+const response1 = await client.ask('Hello!');
+const sessionId = response1.sessionId;
+
+// Continue conversation with session ID
+const response2 = await client.ask('Tell me more', { sessionId });
+const response3 = await client.ask('Can you clarify?', { sessionId });
+
+// Optionally pass page context
+const response = await client.ask('Help me with this page', {
+  sessionId,
+  context: {
+    currentPage: '/products/widget',
+    pageTitle: 'Widget Product Page'
+  }
+});
+```
+
+### Agentic Capabilities
+
+The full bundle includes intent classification and DOM automation:
+
+```typescript
+import {
+  CyberneticClient,
+  CyberneticAgent,
+  CyberneticIntentClassifier
+} from '@astermind/cybernetic-chatbot-client/full';
+
+const client = new CyberneticClient({
+  apiUrl: 'https://api.astermind.ai',
+  apiKey: 'am_your_api_key',
+  agentic: {
+    enabled: true,
+    confidenceThreshold: 0.8,
+    requireConfirmation: true,
+    allowedActions: ['click', 'fill', 'navigate', 'scroll'],
+    blockedSelectors: ['.admin-panel', '#dangerous-button'],
+    maxActionsPerTurn: 5
+  }
+});
+
+// Smart ask - checks for action intent first, then falls back to RAG
+const result = await client.smartAsk('Take me to the settings page');
+
+if (result.action) {
+  // Action detected
+  console.log('Action:', result.action.type, result.action.target);
+  console.log('Confidence:', result.action.confidence);
+
+  // If requireConfirmation is true, action is returned but not executed
+  // Your UI can show a confirmation dialog, then execute:
+  if (userConfirmed) {
+    const actionResult = await client.executeAction(result.action);
+    console.log('Result:', actionResult.message);
+  }
+} else if (result.response) {
+  // Standard RAG response
+  console.log('Reply:', result.response.reply);
+}
+```
+
+#### Supported Action Types
+
+| Action | Description | Example Phrases |
+|--------|-------------|-----------------|
+| `navigate` | Navigate to URL/route | "go to settings", "take me to dashboard" |
+| `fillForm` | Fill form input fields | "search for products", "enter my email" |
+| `clickElement` | Click buttons/links | "click submit", "press the save button" |
+| `scroll` | Scroll to element/position | "scroll to top", "jump to pricing section" |
+| `highlight` | Highlight elements | "show me the login button" |
+| `triggerModal` | Open modal dialogs | "open help modal", "show settings dialog" |
+| `custom` | Custom action handlers | "export data", "refresh dashboard" |
+
+#### Intent Classification
+
+The classifier uses a hybrid approach with regex patterns and Jaccard similarity for fuzzy matching:
+
+```typescript
+import { CyberneticIntentClassifier } from '@astermind/cybernetic-chatbot-client/full';
+
+const classifier = new CyberneticIntentClassifier({
+  enabled: true,
+  confidenceThreshold: 0.8,
+  siteMap: [
+    { path: '/settings', name: 'Settings', aliases: ['preferences', 'config'] },
+    { path: '/dashboard', name: 'Dashboard', aliases: ['home', 'main'] }
+  ]
+});
+
+const intent = classifier.classify('take me to the settings page');
+// { action: { type: 'navigate', target: '/settings', confidence: 0.92 }, ... }
+```
+
+#### Security Features
+
+- **Selector Sanitization**: Removes potentially dangerous characters from CSS selectors
+- **URL Validation**: Blocks `javascript:` and `data:` URLs
+- **Blocked Selectors**: Configure selectors that should never be interacted with
+- **Allowed Selectors**: Optionally whitelist specific selectors
+- **Rate Limiting**: Maximum actions per minute (default: 5)
+- **Confirmation Flow**: Optional user approval before action execution
+
+### Maintenance Mode Support
+
+The client handles backend maintenance mode gracefully (per ADR-200):
+
+```typescript
+// Check if maintenance mode is active
+if (client.isMaintenanceMode()) {
+  const message = client.getMaintenanceMessage();
+  console.log('Maintenance:', message);
+}
+
+// Get full system status
+const status = client.getStatus();
+console.log(status.systemSettings);
+// {
+//   maintenanceMode: boolean,
+//   maintenanceMessage?: string,
+//   cacheRetentionHours: number,
+//   forceOfflineClients: boolean
+// }
+```
+
+When maintenance mode is active:
+- The client automatically uses cached data
+- New requests are served from local RAG
+- `response.offline` will be `true`
+- `response.degradedReason` will indicate maintenance mode
+
+## Bundle Options
+
+| Entry Point | Import Path | Description | Size (minified) |
+|-------------|-------------|-------------|-----------------|
+| Core | `@astermind/cybernetic-chatbot-client` | Client, caching, local RAG | ~15KB |
+| Full | `@astermind/cybernetic-chatbot-client/full` | Core + agentic capabilities | ~25KB |
+
+### Tree-Shakeable Imports
+
+```typescript
+// Import only core client (smaller bundle)
+import { CyberneticClient } from '@astermind/cybernetic-chatbot-client';
+
+// Import agentic features when needed
+import {
+  CyberneticClient,
+  CyberneticAgent,
+  CyberneticIntentClassifier
+} from '@astermind/cybernetic-chatbot-client/full';
+```
+
+## API Reference
+
+### CyberneticClient
+
+```typescript
+class CyberneticClient {
+  constructor(config: CyberneticConfig);
+
+  // Core methods
+  ask(message: string, options?: AskOptions): Promise<CyberneticResponse>;
+  askStream(message: string, callbacks: StreamCallbacks, options?: AskOptions): Promise<void>;
+
+  // Agentic methods (requires agentic config and license)
+  smartAsk(message: string, options?: AskOptions): Promise<SmartAskResult>;
+  classifyIntent(message: string): IntentClassification | null;
+  executeAction(action: AgentAction): Promise<ActionResult>;
+  isAgenticEnabled(): boolean;
+
+  // Status methods (includes license state)
+  getStatus(): { connection: ConnectionStatus; cache: CacheStatus; lastError: CyberneticError | null; systemSettings: SystemSettings | null; license: LicenseState | null };
+  checkConnection(): Promise<boolean>;
+  checkSystemStatus(): Promise<SystemSettings>;
+  isMaintenanceMode(): boolean;
+  getMaintenanceMessage(): string | undefined;
+  isCacheValid(): boolean;
+
+  // License methods
+  getLicenseManager(): LicenseManager;
+
+  // Cache methods
+  syncCache(): Promise<void>;
+  clearCache(): Promise<void>;
+}
+```
+
+### Response Types
+
+```typescript
+interface CyberneticResponse {
+  reply: string;
+  confidence: 'high' | 'medium' | 'low' | 'none';
+  sources: Source[];
+  offline: boolean;
+  sessionId?: string;
+  retryAfter?: number;
+  degradedReason?: string;
+}
+
+interface Source {
+  title: string;
+  snippet: string;
+  relevance: number;
+  documentId?: string;
+}
+
+interface StreamCallbacks {
+  onToken?: (token: string) => void;
+  onSources?: (sources: Source[]) => void;
+  onComplete?: (response: CyberneticResponse) => void;
+  onError?: (error: CyberneticError) => void;
+}
+
+interface CyberneticError {
+  code: 'NETWORK_ERROR' | 'AUTH_ERROR' | 'RATE_LIMIT' | 'SERVER_ERROR' | 'CACHE_ERROR' | 'LOCAL_RAG_ERROR';
+  message: string;
+  retryAfter?: number;
+}
+
+interface LicenseState {
+  status: 'valid' | 'invalid' | 'expired' | 'missing' | 'eval';
+  payload: LicensePayload | null;
+  error?: string;
+  inGracePeriod: boolean;
+  daysRemaining: number | null;
+}
+
+interface LicensePayload {
+  iss: string;          // Issuer
+  sub: string;          // Subject (license ID)
+  aud: string;          // Audience (product)
+  iat: number;          // Issued at
+  exp: number;          // Expiration
+  plan: 'free' | 'pro' | 'business' | 'enterprise' | 'eval';
+  org?: string;         // Organization
+  seats: number;        // Number of seats
+  features: string[];   // Enabled features
+  graceUntil?: number;  // Grace period end
+  licenseVersion: number;
+}
+```
+
+## Browser Support
+
+| Browser | Version | Notes |
+|---------|---------|-------|
+| Chrome | 80+ | Full support |
+| Firefox | 75+ | Full support |
+| Safari | 13.1+ | Full support |
+| Edge | 80+ | Full support |
+
+Requires IndexedDB support for offline caching.
+
+## Integration with Cybernetic Chatbot Backend
+
+This client is designed to work with the AsterMind Cybernetic Chatbot backend. The following endpoints are used:
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/external/chat` | POST | Send message, get complete response |
+| `/api/external/chat/stream` | POST | Send message, get SSE streaming response |
+| `/api/external/docs` | GET | Fetch documents for offline caching |
+| `/api/external/status` | GET | Check API status, quota, and system settings |
+| `/api/external/health` | GET | Health check (no auth required) |
+
+**Authentication**: All authenticated endpoints require an `X-API-Key` header with a valid API key (prefixed with `am_`).
+
+**Rate Limiting**: The backend enforces rate limits. The client handles 429 responses gracefully and includes `retryAfter` in responses when applicable.
+
+## Links
+
+- [AsterMind Website](https://astermind.ai)
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.