@astermind/cybernetic-chatbot-client 1.0.6 → 1.0.9

package/README.md

@@ -241,6 +241,86 @@ For licensing questions, contact support@astermind.ai.
 
 ## Configuration
 
+All configuration is done in **your own project**—you never need to modify `node_modules` or the package source code.
+
+### Multi-Method Configuration
+
+The client supports multiple configuration methods with a priority-based fallback chain. This allows you to use the most appropriate method for your hosting environment.
+
+**Priority Order (highest to lowest):**
+
+1. **Constructor config** - Direct configuration passed to `CyberneticClient` or `createClient()`
+2. **Environment variables** - `VITE_ASTERMIND_RAG_API_KEY`, `REACT_APP_ASTERMIND_RAG_API_KEY`, etc.
+3. **SSR-injected config** - `window.__ASTERMIND_CONFIG__` (for server-side rendering)
+4. **Global object** - `window.astermindConfig`
+5. **Script data attributes** - `data-astermind-key`, `data-astermind-url`
+
+#### Environment Variables
+
+For bundled applications (Vite, Create React App, etc.), you can configure the client using environment variables:
+
+**Vite:**
+```env
+VITE_ASTERMIND_RAG_API_KEY=am_your_api_key
+VITE_ASTERMIND_RAG_API_SERVER_URL=https://api.astermind.ai
+```
+
+**Create React App:**
+```env
+REACT_APP_ASTERMIND_RAG_API_KEY=am_your_api_key
+REACT_APP_ASTERMIND_RAG_API_SERVER_URL=https://api.astermind.ai
+```
+
+**Node.js / Server:**
+```env
+ASTERMIND_RAG_API_KEY=am_your_api_key
+ASTERMIND_RAG_API_SERVER_URL=https://api.astermind.ai
+```
+
+#### Auto-Loading Configuration
+
+Use `loadConfig()` to automatically detect configuration from available sources:
+
+```typescript
+import { loadConfig, createClient } from '@astermind/cybernetic-chatbot-client';
+
+// Auto-detect configuration (throws if no API key found)
+const config = loadConfig();
+const client = createClient(config);
+
+// Or suppress errors and handle missing config gracefully
+const config = loadConfig({ throwOnMissingKey: false });
+if (config) {
+  const client = createClient(config);
+} else {
+  console.log('Chatbot not configured');
+}
+```
+
+#### SSR / Runtime Injection
+
+For server-side rendered applications, inject configuration at runtime:
+
+```html
+<!-- In your SSR template -->
+<script>
+  window.__ASTERMIND_CONFIG__ = {
+    apiKey: '<%= process.env.ASTERMIND_RAG_API_KEY %>',
+    apiUrl: '<%= process.env.ASTERMIND_RAG_API_SERVER_URL %>'
+  };
+</script>
+```
+
+#### Configuration Source Debugging
+
+The loaded configuration includes a `_source` field for debugging:
+
+```typescript
+const config = loadConfig();
+console.log(config._source);
+// 'env' | 'vite' | 'window' | 'data-attr' | 'props'
+```
+
 ### Full Configuration Interface
 
 ```typescript
@@ -323,7 +403,7 @@ interface AgenticConfig {
 
 ### Offline-First Architecture
 
-The client uses IndexedDB for local caching and TF-IDF for similarity search, enabling offline functionality:
+The client includes **built-in offline fallback** with IndexedDB caching and TF-IDF local search—no additional setup required. When the server is unreachable, the client automatically serves cached responses:
 
 ```typescript
 const client = new CyberneticClient({

package/dist/config.d.ts

@@ -1,10 +1,45 @@
-import type { CyberneticConfig } from './types.js';
+import type { CyberneticConfig, ConfigOptions } from './types.js';
 /**
  * Validate configuration
  */
 export declare function validateConfig(config: unknown): config is CyberneticConfig;
 /**
- * Load config from window.astermindConfig or script tag data attributes
+ * Load config from Node.js process.env (for bundlers that replace process.env)
  */
-export declare function loadConfig(): CyberneticConfig | null;
+declare function loadFromProcessEnv(): CyberneticConfig | null;
+/**
+ * Load config from Vite's import.meta.env (browser environment)
+ * Note: This only works at build time when Vite replaces the variables
+ */
+declare function loadFromViteEnv(): CyberneticConfig | null;
+/**
+ * Load config from window.astermindConfig global object
+ */
+declare function loadFromGlobalObject(): CyberneticConfig | null;
+/**
+ * Load config from script tag data attributes
+ */
+declare function loadFromScriptAttributes(): CyberneticConfig | null;
+/**
+ * Load config using priority-based fallback chain:
+ * 1. Environment variables (process.env - for bundlers/Node.js)
+ * 2. Vite environment variables (import.meta.env or window.__ASTERMIND_CONFIG__)
+ * 3. Global object (window.astermindConfig)
+ * 4. Script data attributes (data-astermind-key, data-astermind-url)
+ *
+ * @param options - Configuration options
+ * @param options.throwOnMissingKey - If true (default), throws when no API key found. If false, returns null and logs a warning.
+ * @returns Configuration object or null if not found and throwOnMissingKey is false
+ */
+export declare function loadConfig(options?: ConfigOptions): CyberneticConfig | null;
+/**
+ * Export individual loaders for testing and advanced use cases
+ */
+export declare const configLoaders: {
+    loadFromProcessEnv: typeof loadFromProcessEnv;
+    loadFromViteEnv: typeof loadFromViteEnv;
+    loadFromGlobalObject: typeof loadFromGlobalObject;
+    loadFromScriptAttributes: typeof loadFromScriptAttributes;
+};
+export {};
 //# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI,gBAAgB,CAoB1E;AAED;;GAEG;AACH,wBAAgB,UAAU,IAAI,gBAAgB,GAAG,IAAI,CAwBpD"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAKlE;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI,gBAAgB,CAoB1E;AAED;;GAEG;AACH,iBAAS,kBAAkB,IAAI,gBAAgB,GAAG,IAAI,CA+BrD;AAED;;;GAGG;AACH,iBAAS,eAAe,IAAI,gBAAgB,GAAG,IAAI,CAmClD;AAED;;GAEG;AACH,iBAAS,oBAAoB,IAAI,gBAAgB,GAAG,IAAI,CAgBvD;AAED;;GAEG;AACH,iBAAS,wBAAwB,IAAI,gBAAgB,GAAG,IAAI,CAkB3D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,OAAO,GAAE,aAAkB,GAAG,gBAAgB,GAAG,IAAI,CA0C/E;AAED;;GAEG;AACH,eAAO,MAAM,aAAa;;;;;CAKzB,CAAC"}

package/dist/cybernetic-chatbot-client-full.esm.js

@@ -2010,6 +2010,8 @@ class CyberneticClient {
 
 // src/config.ts
 // Configuration loading and validation
+/** Default API URL when not specified */
+const DEFAULT_API_URL = 'https://api.astermind.ai';
 /**
  * Validate configuration
  */
@@ -2030,30 +2032,160 @@ function validateConfig(config) {
     return true;
 }
 /**
- * Load config from window.astermindConfig or script tag data attributes
+ * Load config from Node.js process.env (for bundlers that replace process.env)
  */
-function loadConfig() {
+function loadFromProcessEnv() {
+    // Check if process.env exists (Node.js or bundler-injected)
+    if (typeof process === 'undefined' || !process.env) {
+        return null;
+    }
+    // Check for ASTERMIND_RAG_* env vars (non-prefixed, for Node.js/server environments)
+    const apiKey = process.env.ASTERMIND_RAG_API_KEY;
+    const apiUrl = process.env.ASTERMIND_RAG_API_SERVER_URL;
+    if (apiKey) {
+        return {
+            apiKey,
+            apiUrl: apiUrl || DEFAULT_API_URL,
+            _source: 'env'
+        };
+    }
+    // Check for CRA-style REACT_APP_* env vars
+    const craApiKey = process.env.REACT_APP_ASTERMIND_RAG_API_KEY;
+    const craApiUrl = process.env.REACT_APP_ASTERMIND_RAG_API_SERVER_URL;
+    if (craApiKey) {
+        return {
+            apiKey: craApiKey,
+            apiUrl: craApiUrl || DEFAULT_API_URL,
+            _source: 'env'
+        };
+    }
+    return null;
+}
+/**
+ * Load config from Vite's import.meta.env (browser environment)
+ * Note: This only works at build time when Vite replaces the variables
+ */
+function loadFromViteEnv() {
+    // Check for window.__ASTERMIND_CONFIG__ (SSR-injected config)
+    if (typeof window !== 'undefined') {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const injected = window.__ASTERMIND_CONFIG__;
+        if (injected && typeof injected === 'object' && injected.apiKey) {
+            return {
+                ...injected,
+                apiUrl: injected.apiUrl || DEFAULT_API_URL,
+                _source: 'vite'
+            };
+        }
+    }
+    // Check for Vite's import.meta.env (replaced at build time)
+    // Note: TypeScript doesn't know about import.meta.env, so we use a try-catch
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const importMeta = globalThis.import?.meta?.env;
+        if (importMeta) {
+            const apiKey = importMeta.VITE_ASTERMIND_RAG_API_KEY;
+            const apiUrl = importMeta.VITE_ASTERMIND_RAG_API_SERVER_URL;
+            if (apiKey) {
+                return {
+                    apiKey,
+                    apiUrl: apiUrl || DEFAULT_API_URL,
+                    _source: 'vite'
+                };
+            }
+        }
+    }
+    catch {
+        // import.meta not available in this environment
+    }
+    return null;
+}
+/**
+ * Load config from window.astermindConfig global object
+ */
+function loadFromGlobalObject() {
     if (typeof window === 'undefined') {
         return null;
     }
-    // Check for global config object
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    if (window.astermindConfig) {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const config = window.astermindConfig;
-        validateConfig(config);
-        return config;
+    const globalConfig = window.astermindConfig;
+    if (globalConfig && typeof globalConfig === 'object' && globalConfig.apiKey) {
+        return {
+            ...globalConfig,
+            apiUrl: globalConfig.apiUrl || DEFAULT_API_URL,
+            _source: 'window'
+        };
+    }
+    return null;
+}
+/**
+ * Load config from script tag data attributes
+ */
+function loadFromScriptAttributes() {
+    if (typeof window === 'undefined' || typeof document === 'undefined') {
+        return null;
     }
-    // Check for script tag with data attributes
     const script = document.querySelector('script[data-astermind-key]');
     if (script) {
-        return {
-            apiUrl: script.getAttribute('data-astermind-url') || 'https://api.astermind.ai',
-            apiKey: script.getAttribute('data-astermind-key') || ''
-        };
+        const apiKey = script.getAttribute('data-astermind-key');
+        if (apiKey) {
+            return {
+                apiKey,
+                apiUrl: script.getAttribute('data-astermind-url') || DEFAULT_API_URL,
+                _source: 'data-attr'
+            };
+        }
     }
     return null;
 }
+/**
+ * Load config using priority-based fallback chain:
+ * 1. Environment variables (process.env - for bundlers/Node.js)
+ * 2. Vite environment variables (import.meta.env or window.__ASTERMIND_CONFIG__)
+ * 3. Global object (window.astermindConfig)
+ * 4. Script data attributes (data-astermind-key, data-astermind-url)
+ *
+ * @param options - Configuration options
+ * @param options.throwOnMissingKey - If true (default), throws when no API key found. If false, returns null and logs a warning.
+ * @returns Configuration object or null if not found and throwOnMissingKey is false
+ */
+function loadConfig(options = {}) {
+    const { throwOnMissingKey = true } = options;
+    // Priority 1: Environment variables (Node.js/bundler)
+    const envConfig = loadFromProcessEnv();
+    if (envConfig) {
+        return envConfig;
+    }
+    // Priority 2: Vite environment variables / SSR-injected config
+    const viteConfig = loadFromViteEnv();
+    if (viteConfig) {
+        return viteConfig;
+    }
+    // Priority 3: Global object (window.astermindConfig)
+    const globalConfig = loadFromGlobalObject();
+    if (globalConfig) {
+        validateConfig(globalConfig);
+        return globalConfig;
+    }
+    // Priority 4: Script data attributes
+    const scriptConfig = loadFromScriptAttributes();
+    if (scriptConfig) {
+        return scriptConfig;
+    }
+    // No config found
+    if (throwOnMissingKey) {
+        throw new Error('AsterMind API key is required. Configure using one of these methods:\n' +
+            '  1. Set VITE_ASTERMIND_RAG_API_KEY environment variable (Vite)\n' +
+            '  2. Set REACT_APP_ASTERMIND_RAG_API_KEY environment variable (CRA)\n' +
+            '  3. Set window.astermindConfig = { apiKey: "am_...", apiUrl: "..." }\n' +
+            '  4. Add data-astermind-key attribute to your script tag\n' +
+            '  5. Pass apiKey directly to createClient() or CyberneticClient constructor');
+    }
+    else {
+        console.warn('[AsterMind] No API key found. Chatbot will not function until configured.');
+        return null;
+    }
+}
 
 // src/agentic/CyberneticIntentClassifier.ts
 // Hybrid intent classification for agentic capabilities