@courseecho/ai-core-sdk

Foundation SDK for AI widgets - Framework-agnostic core for all AI widget implementations.

Overview

Core foundation providing:

• AI query orchestration
• State management patterns
• Streaming response handling
• Authentication (API key + JWT)
• Configuration management
• CSS styling injection
• Page context detection
• Feedback collection
• Query quota management
• Used by all framework integrations (React, Vue, Angular, jQuery, Node)

Installation

npm install @courseecho/ai-core-sdk

Architecture

Core Components

1. Query Engine - Processes user queries against AI orchestrator
2. State Manager - Reactive state with RxJS patterns
3. Auth Service - Token management and API key exchange
4. Stream Handler - Manages streaming responses with typewriter effects
5. Config Manager - Configuration validation and defaults
6. Feedback System - Tracks user interactions and feedback

API Reference

Configuration Interface

interface WidgetConfig {
  apiKey?: string;                    // API key (auto-exchanges for JWT)
  jwtToken?: string;                  // Direct JWT token
  context?: {
    pageType: string;                 // 'course' | 'lesson' | 'blog' | etc.
    entityId?: string;                // ID of current page entity
    customData?: Record<string, any>; // Additional context
  };
  defaultMinimized?: boolean;          // Start widget minimized
  preChatFormEnabled?: boolean;        // Show form before chat
  goOfflineEnabled?: boolean;          // Enable offline booking mode
  limitExpiredConfig?: {
    offlineForm?: {
      title: string;
      submitEndpoint: string;
    };
    booking?: {
      title: string;
      calendarUrl: string | (() => string);
    };
  };
  wordDelay?: number;                  // Typewriter delay (ms, default 28)
  suggestionsEnabled?: boolean;        // Show suggestions (default true)
  theme?: 'light' | 'dark';           // Theme variant
}

Query Options

interface QueryOptions {
  query: string;                    // User question/prompt
  context?: WidgetConfig['context']; // Optional context override
  userId?: string;                  // Associated user ID
}

interface QueryResponse {
  answer: string;              // AI response
  confidence: number;          // 0-100 confidence score
  sources?: string[];          // Reference sources
  followUpQuestions?: string[]; // Suggested follow-ups
  usage: {
    tokensUsed: number;
    quotaRemaining: number;
    dailyLimit: number;
  };
}

v2.1+ Features

Smart Suggestions

// Auto-detect page context and provide relevant suggestions
const suggestions = await coreSDK.getPageTypeSuggestions({
  pageType: 'course',
  entityId: 'react-101'
});
// Returns: [
//   'How do I get started?',
//   'What are hooks?',
//   'How do I fetch data?'
// ]

Minimize on Load

const config = {
  // ... other config
  defaultMinimized: true
};
// Widget starts in minimized state, click to expand

Pre-Chat Form

const config = {
  // ... other config
  preChatFormEnabled: true
  // Shows form to collect: name, email (optional fields configurable)
};

Go Offline Mode

const config = {
  // ... other config
  goOfflineEnabled: true,
  limitExpiredConfig: {
    offlineForm: {
      title: 'Get in Touch',
      submitEndpoint: '/api/contact-us'
    },
    booking: {
      title: 'Schedule a Call',
      calendarUrl: 'https://calendly.com/courseecho'
    }
  }
};
// When daily limit reached: shows contact form + booking calendar

Keyboard Navigation

Suggestions list supports:

• `` Navigate through suggestions
• `` Select highlighted suggestion
• Esc Close suggestions dropdown

Usage Patterns

Reactive State Management

import { AiCoreSDK } from '@courseecho/ai-core-sdk';

const sdk = new AiCoreSDK(config);

// Subscribe to messages
sdk.messages$.subscribe(messages => {
  console.log('Updated messages:', messages);
});

// Subscribe to loading state
sdk.isLoading$.subscribe(loading => {
  console.log('Loading:', loading);
});

// Subscribe to suggestions
sdk.suggestions$.subscribe(suggestions => {
  console.log('Available suggestions:', suggestions);
});

Query Impact Tracking

// Track query quota usage
sdk.queryUsage$.subscribe(usage => {
  console.log(`Used: ${usage.tokensUsed}/${usage.dailyLimit}`);
  if (usage.quotaRemaining === 0) {
    console.log('Daily limit reached - go offline mode active');
  }
});

Best Practices

1. Configuration Validation - All configs validated at initialization
2. Error Handling - Always wrap queries in try-catch
3. Auth Security - Use environment variables for API keys
4. Streaming - Use streaming for better UX with large responses
5. Context - Always provide relevant pageType and entityId for better suggestions

Framework Integrations

• React: @courseecho/ai-widget-react
• Vue: @courseecho/ai-widget-vue
• Angular: @courseecho/ai-widget-angular
• jQuery: @courseecho/ai-widget-jquery
• Node.js: @courseecho/ai-client-node

Support

• Docs: https://courseecho.com/docs
• Issues: https://github.com/COURSEECHO/courseecho-ai-widget-sdk/issues
• Email: [email protected]

License

MIT 2026 CourseEcho