echo-ai-sdk-ts 2.2.0 → 2.3.1

package/dist/index.d.mts

@@ -245,6 +245,7 @@ declare class AgentExecutor {
         systemPrompt?: string;
         telemetry?: AgentTelemetry;
     });
+    getMemory(): BaseMemoryStore;
     execute(sessionId: string, userInput: string, maxIterations?: number): Promise<string>;
     /**
      * Forces the LLM to output strictly structured JSON validated against the provided Zod schema.
@@ -609,6 +610,34 @@ declare class KnowledgeBase {
     private embedBatch;
 }
 
+/**
+ * Outcome tracking module for value-based billing.
+ * Tracks successful business results (leads, sales, resolutions) to calculate ROI.
+ */
+interface OutcomeRecord {
+    type: string;
+    valueUsd: number;
+    timestamp: number;
+    metadata?: Record<string, any>;
+}
+declare class OutcomeTracker {
+    private sessionOutcomes;
+    /** Record a successful business outcome for a session. */
+    record(sessionId: string, type: string, valueUsd?: number, metadata?: Record<string, any>): void;
+    /** Get all outcomes for a specific session. */
+    getSessionOutcomes(sessionId: string): OutcomeRecord[];
+    /** Calculate total value generated for a session. */
+    getSessionValue(sessionId: string): number;
+    /** Get global stats for all outcomes. */
+    getGlobalStats(): {
+        totalOutcomes: number;
+        totalValueUsd: number;
+        outcomesByType: Record<string, number>;
+    };
+    /** Reset all stats. */
+    clear(): void;
+}
+
 /**
  * Enterprise Conversation Analytics Engine.
  * Tracks resolution rates, CSAT, response latency, token costs, and top queries.
@@ -636,6 +665,8 @@ interface AnalyticsSnapshot {
     avgResponseTimeMs: number;
     totalTokensUsed: number;
     totalCostUsd: number;
+    totalValueGeneratedUsd: number;
+    roi: number;
     avgTokensPerConversation: number;
     avgCostPerConversation: number;
     topQueries: {
@@ -651,6 +682,8 @@ declare const OPENAI_PRICING: Record<string, {
 declare class ConversationAnalytics {
     private records;
     private queryFrequency;
+    outcomeTracker?: OutcomeTracker;
+    constructor(outcomeTracker?: OutcomeTracker);
     estimateTokens(text: string): number;
     calculateCost(model: string, tokens: number, type?: "input" | "output"): number;
     startConversation(sessionId: string, model?: string): void;
@@ -718,6 +751,39 @@ declare class HandoffManager {
     private dispatchWebhook;
 }
 
+/**
+ * Interface for pluggable session storage (Memory, Redis, File, DB).
+ */
+interface SessionStore {
+    get(sessionId: string): Promise<any | null>;
+    set(sessionId: string, data: any): Promise<void>;
+    delete(sessionId: string): Promise<void>;
+    clear(): Promise<void>;
+}
+/**
+ * Default in-memory session store.
+ */
+declare class MemorySessionStore implements SessionStore {
+    private store;
+    get(sessionId: string): Promise<any | null>;
+    set(sessionId: string, data: any): Promise<void>;
+    delete(sessionId: string): Promise<void>;
+    clear(): Promise<void>;
+}
+/**
+ * Pro-grade local file session store for persistence across restarts.
+ */
+declare class FileSessionStore implements SessionStore {
+    private dir;
+    constructor(dir?: string);
+    private getPath;
+    private ensureDir;
+    get(sessionId: string): Promise<any | null>;
+    set(sessionId: string, data: any): Promise<void>;
+    delete(sessionId: string): Promise<void>;
+    clear(): Promise<void>;
+}
+
 interface SupportBotConfig {
     gateway: AIModelGateway;
     companyName: string;
@@ -728,6 +794,7 @@ interface SupportBotConfig {
     memory?: BaseMemoryStore;
     telemetry?: AgentTelemetry;
     customTools?: ToolContext[];
+    sessionStore?: SessionStore;
     greeting?: string;
     systemPrompt?: string;
     maxIterations?: number;
@@ -747,12 +814,16 @@ declare class CustomerSupportBot {
     private connector?;
     knowledgeBase?: KnowledgeBase;
     analytics: ConversationAnalytics;
+    outcomeTracker: OutcomeTracker;
+    sessionStore: SessionStore;
     handoff?: HandoffManager;
     greeting: string;
     private middlewares;
     constructor(config: SupportBotConfig);
     /** Register a middleware function to run before every chat turn. */
     use(middleware: BotMiddleware): void;
+    /** Record a business outcome for ROI tracking. */
+    trackOutcome(sessionId: string, type: string, valueUsd?: number, metadata?: Record<string, any>): void;
     /** Process a customer message and return the bot's response. */
     chat(sessionId: string, message: string): Promise<string>;
     /** Start tracking analytics for a new session. */
@@ -803,4 +874,63 @@ declare function createChatHandler(bot: CustomerSupportBot): (req: any, res: any
  */
 declare function startChatServer(config: ServerConfig): Promise<void>;
 
-export { AIModelGateway, APIConnector, type APIConnectorConfig, AgentExecutor, AgentIterationLimitError, AgentPipeline, AgentRouter, type AgentTelemetry, type AnalyticsSnapshot, type BaseMemoryStore, BaseProvider, BaseSTTProvider, BaseSpeakerRecognizer, BaseTTSProvider, type BotMiddleware, CachedGateway, ChatAgent, type ChatMessage, ChatMessageSchema, type ChatRequest, ChatRequestSchema, type ChatResponse, ChatResponseSchema, ChatWidget, type ChatWidgetConfig, type ChatWidgetTheme, type ChunkOptions, ConfigurationError, ConversationAnalytics, type ConversationRecord, CustomerSupportBot, EchoAI, EchoVoice, type EscalationTrigger, type FetchResult, type GatewayMiddleware, GatewayRoutingError, type HandoffConfig, type HandoffEvent, HandoffManager, type IdentificationResult, InMemoryStore, KnowledgeBase, type KnowledgeBaseConfig, MemoryVectorStore, OPENAI_PRICING, OpenAITTS, OpenAIWhisperSTT, PromptRegistry, PromptTemplate, PromptVersionError, ProviderDependencyError, type STTOptions, type SearchResult, type ServerConfig, type SpeakerProfile, StructuredOutputError, type SupportBotConfig, type TTSFormat, type TTSOptions, type TTSResult, type TTSVoice, ToolAgent, type ToolContext, ToolExecutionError, type TranscriptionResult, type TranscriptionSegment, type UsageMetrics, UsageMetricsSchema, ValidationError, type VectorEntry, type VerificationResult, VoiceprintStore, applyRequestMiddleware, applyResponseMiddleware, calculatorTool, chunkText, createChatHandler, createTool, dateTimeTool, startChatServer, webSearchTool };
+/**
+ * Base configuration for any channel adapter.
+ */
+interface ChannelConfig {
+    bot: CustomerSupportBot;
+    enabled?: boolean;
+}
+/**
+ * Unified interface for messaging channels (Slack, Telegram, WhatsApp).
+ */
+declare abstract class ChannelAdapter {
+    protected bot: CustomerSupportBot;
+    constructor(config: ChannelConfig);
+    /** Initialize the channel listener/connection. */
+    abstract start(): Promise<void>;
+    /** Stop the channel listener. */
+    abstract stop(): Promise<void>;
+    /**
+     * Normalize incoming messages from different platforms
+     * and route them to the core bot brain.
+     */
+    protected handleMessage(sessionId: string, text: string): Promise<string>;
+}
+
+/**
+ * Pro-grade Slack Adapter (Skeleton).
+ * Standardized interface for Slack Bolt / Webhook integration.
+ */
+interface SlackConfig extends ChannelConfig {
+    signingSecret: string;
+    token: string;
+    appToken?: string;
+}
+declare class SlackAdapter extends ChannelAdapter {
+    constructor(config: SlackConfig);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /** Handler for Slack events (to be used by Express middleware). */
+    handleEvent(event: any): Promise<void>;
+}
+
+/**
+ * Pro-grade Telegram Adapter.
+ * Uses the Telegram Bot API to connect your AI assistant to Telegram.
+ */
+interface TelegramConfig extends ChannelConfig {
+    token: string;
+}
+declare class TelegramAdapter extends ChannelAdapter {
+    private token;
+    private polling;
+    private offset;
+    constructor(config: TelegramConfig);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private runPollingLoop;
+    private sendMessage;
+}
+
+export { AIModelGateway, APIConnector, type APIConnectorConfig, AgentExecutor, AgentIterationLimitError, AgentPipeline, AgentRouter, type AgentTelemetry, type AnalyticsSnapshot, type BaseMemoryStore, BaseProvider, BaseSTTProvider, BaseSpeakerRecognizer, BaseTTSProvider, type BotMiddleware, CachedGateway, ChannelAdapter, type ChannelConfig, ChatAgent, type ChatMessage, ChatMessageSchema, type ChatRequest, ChatRequestSchema, type ChatResponse, ChatResponseSchema, ChatWidget, type ChatWidgetConfig, type ChatWidgetTheme, type ChunkOptions, ConfigurationError, ConversationAnalytics, type ConversationRecord, CustomerSupportBot, EchoAI, EchoVoice, type EscalationTrigger, type FetchResult, FileSessionStore, type GatewayMiddleware, GatewayRoutingError, type HandoffConfig, type HandoffEvent, HandoffManager, type IdentificationResult, InMemoryStore, KnowledgeBase, type KnowledgeBaseConfig, MemorySessionStore, MemoryVectorStore, OPENAI_PRICING, OpenAITTS, OpenAIWhisperSTT, type OutcomeRecord, OutcomeTracker, PromptRegistry, PromptTemplate, PromptVersionError, ProviderDependencyError, type STTOptions, type SearchResult, type ServerConfig, type SessionStore, SlackAdapter, type SlackConfig, type SpeakerProfile, StructuredOutputError, type SupportBotConfig, type TTSFormat, type TTSOptions, type TTSResult, type TTSVoice, TelegramAdapter, type TelegramConfig, ToolAgent, type ToolContext, ToolExecutionError, type TranscriptionResult, type TranscriptionSegment, type UsageMetrics, UsageMetricsSchema, ValidationError, type VectorEntry, type VerificationResult, VoiceprintStore, applyRequestMiddleware, applyResponseMiddleware, calculatorTool, chunkText, createChatHandler, createTool, dateTimeTool, startChatServer, webSearchTool };

package/dist/index.d.ts

@@ -245,6 +245,7 @@ declare class AgentExecutor {
         systemPrompt?: string;
         telemetry?: AgentTelemetry;
     });
+    getMemory(): BaseMemoryStore;
     execute(sessionId: string, userInput: string, maxIterations?: number): Promise<string>;
     /**
      * Forces the LLM to output strictly structured JSON validated against the provided Zod schema.
@@ -609,6 +610,34 @@ declare class KnowledgeBase {
     private embedBatch;
 }
 
+/**
+ * Outcome tracking module for value-based billing.
+ * Tracks successful business results (leads, sales, resolutions) to calculate ROI.
+ */
+interface OutcomeRecord {
+    type: string;
+    valueUsd: number;
+    timestamp: number;
+    metadata?: Record<string, any>;
+}
+declare class OutcomeTracker {
+    private sessionOutcomes;
+    /** Record a successful business outcome for a session. */
+    record(sessionId: string, type: string, valueUsd?: number, metadata?: Record<string, any>): void;
+    /** Get all outcomes for a specific session. */
+    getSessionOutcomes(sessionId: string): OutcomeRecord[];
+    /** Calculate total value generated for a session. */
+    getSessionValue(sessionId: string): number;
+    /** Get global stats for all outcomes. */
+    getGlobalStats(): {
+        totalOutcomes: number;
+        totalValueUsd: number;
+        outcomesByType: Record<string, number>;
+    };
+    /** Reset all stats. */
+    clear(): void;
+}
+
 /**
  * Enterprise Conversation Analytics Engine.
  * Tracks resolution rates, CSAT, response latency, token costs, and top queries.
@@ -636,6 +665,8 @@ interface AnalyticsSnapshot {
     avgResponseTimeMs: number;
     totalTokensUsed: number;
     totalCostUsd: number;
+    totalValueGeneratedUsd: number;
+    roi: number;
     avgTokensPerConversation: number;
     avgCostPerConversation: number;
     topQueries: {
@@ -651,6 +682,8 @@ declare const OPENAI_PRICING: Record<string, {
 declare class ConversationAnalytics {
     private records;
     private queryFrequency;
+    outcomeTracker?: OutcomeTracker;
+    constructor(outcomeTracker?: OutcomeTracker);
     estimateTokens(text: string): number;
     calculateCost(model: string, tokens: number, type?: "input" | "output"): number;
     startConversation(sessionId: string, model?: string): void;
@@ -718,6 +751,39 @@ declare class HandoffManager {
     private dispatchWebhook;
 }
 
+/**
+ * Interface for pluggable session storage (Memory, Redis, File, DB).
+ */
+interface SessionStore {
+    get(sessionId: string): Promise<any | null>;
+    set(sessionId: string, data: any): Promise<void>;
+    delete(sessionId: string): Promise<void>;
+    clear(): Promise<void>;
+}
+/**
+ * Default in-memory session store.
+ */
+declare class MemorySessionStore implements SessionStore {
+    private store;
+    get(sessionId: string): Promise<any | null>;
+    set(sessionId: string, data: any): Promise<void>;
+    delete(sessionId: string): Promise<void>;
+    clear(): Promise<void>;
+}
+/**
+ * Pro-grade local file session store for persistence across restarts.
+ */
+declare class FileSessionStore implements SessionStore {
+    private dir;
+    constructor(dir?: string);
+    private getPath;
+    private ensureDir;
+    get(sessionId: string): Promise<any | null>;
+    set(sessionId: string, data: any): Promise<void>;
+    delete(sessionId: string): Promise<void>;
+    clear(): Promise<void>;
+}
+
 interface SupportBotConfig {
     gateway: AIModelGateway;
     companyName: string;
@@ -728,6 +794,7 @@ interface SupportBotConfig {
     memory?: BaseMemoryStore;
     telemetry?: AgentTelemetry;
     customTools?: ToolContext[];
+    sessionStore?: SessionStore;
     greeting?: string;
     systemPrompt?: string;
     maxIterations?: number;
@@ -747,12 +814,16 @@ declare class CustomerSupportBot {
     private connector?;
     knowledgeBase?: KnowledgeBase;
     analytics: ConversationAnalytics;
+    outcomeTracker: OutcomeTracker;
+    sessionStore: SessionStore;
     handoff?: HandoffManager;
     greeting: string;
     private middlewares;
     constructor(config: SupportBotConfig);
     /** Register a middleware function to run before every chat turn. */
     use(middleware: BotMiddleware): void;
+    /** Record a business outcome for ROI tracking. */
+    trackOutcome(sessionId: string, type: string, valueUsd?: number, metadata?: Record<string, any>): void;
     /** Process a customer message and return the bot's response. */
     chat(sessionId: string, message: string): Promise<string>;
     /** Start tracking analytics for a new session. */
@@ -803,4 +874,63 @@ declare function createChatHandler(bot: CustomerSupportBot): (req: any, res: any
  */
 declare function startChatServer(config: ServerConfig): Promise<void>;
 
-export { AIModelGateway, APIConnector, type APIConnectorConfig, AgentExecutor, AgentIterationLimitError, AgentPipeline, AgentRouter, type AgentTelemetry, type AnalyticsSnapshot, type BaseMemoryStore, BaseProvider, BaseSTTProvider, BaseSpeakerRecognizer, BaseTTSProvider, type BotMiddleware, CachedGateway, ChatAgent, type ChatMessage, ChatMessageSchema, type ChatRequest, ChatRequestSchema, type ChatResponse, ChatResponseSchema, ChatWidget, type ChatWidgetConfig, type ChatWidgetTheme, type ChunkOptions, ConfigurationError, ConversationAnalytics, type ConversationRecord, CustomerSupportBot, EchoAI, EchoVoice, type EscalationTrigger, type FetchResult, type GatewayMiddleware, GatewayRoutingError, type HandoffConfig, type HandoffEvent, HandoffManager, type IdentificationResult, InMemoryStore, KnowledgeBase, type KnowledgeBaseConfig, MemoryVectorStore, OPENAI_PRICING, OpenAITTS, OpenAIWhisperSTT, PromptRegistry, PromptTemplate, PromptVersionError, ProviderDependencyError, type STTOptions, type SearchResult, type ServerConfig, type SpeakerProfile, StructuredOutputError, type SupportBotConfig, type TTSFormat, type TTSOptions, type TTSResult, type TTSVoice, ToolAgent, type ToolContext, ToolExecutionError, type TranscriptionResult, type TranscriptionSegment, type UsageMetrics, UsageMetricsSchema, ValidationError, type VectorEntry, type VerificationResult, VoiceprintStore, applyRequestMiddleware, applyResponseMiddleware, calculatorTool, chunkText, createChatHandler, createTool, dateTimeTool, startChatServer, webSearchTool };
+/**
+ * Base configuration for any channel adapter.
+ */
+interface ChannelConfig {
+    bot: CustomerSupportBot;
+    enabled?: boolean;
+}
+/**
+ * Unified interface for messaging channels (Slack, Telegram, WhatsApp).
+ */
+declare abstract class ChannelAdapter {
+    protected bot: CustomerSupportBot;
+    constructor(config: ChannelConfig);
+    /** Initialize the channel listener/connection. */
+    abstract start(): Promise<void>;
+    /** Stop the channel listener. */
+    abstract stop(): Promise<void>;
+    /**
+     * Normalize incoming messages from different platforms
+     * and route them to the core bot brain.
+     */
+    protected handleMessage(sessionId: string, text: string): Promise<string>;
+}
+
+/**
+ * Pro-grade Slack Adapter (Skeleton).
+ * Standardized interface for Slack Bolt / Webhook integration.
+ */
+interface SlackConfig extends ChannelConfig {
+    signingSecret: string;
+    token: string;
+    appToken?: string;
+}
+declare class SlackAdapter extends ChannelAdapter {
+    constructor(config: SlackConfig);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /** Handler for Slack events (to be used by Express middleware). */
+    handleEvent(event: any): Promise<void>;
+}
+
+/**
+ * Pro-grade Telegram Adapter.
+ * Uses the Telegram Bot API to connect your AI assistant to Telegram.
+ */
+interface TelegramConfig extends ChannelConfig {
+    token: string;
+}
+declare class TelegramAdapter extends ChannelAdapter {
+    private token;
+    private polling;
+    private offset;
+    constructor(config: TelegramConfig);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private runPollingLoop;
+    private sendMessage;
+}
+
+export { AIModelGateway, APIConnector, type APIConnectorConfig, AgentExecutor, AgentIterationLimitError, AgentPipeline, AgentRouter, type AgentTelemetry, type AnalyticsSnapshot, type BaseMemoryStore, BaseProvider, BaseSTTProvider, BaseSpeakerRecognizer, BaseTTSProvider, type BotMiddleware, CachedGateway, ChannelAdapter, type ChannelConfig, ChatAgent, type ChatMessage, ChatMessageSchema, type ChatRequest, ChatRequestSchema, type ChatResponse, ChatResponseSchema, ChatWidget, type ChatWidgetConfig, type ChatWidgetTheme, type ChunkOptions, ConfigurationError, ConversationAnalytics, type ConversationRecord, CustomerSupportBot, EchoAI, EchoVoice, type EscalationTrigger, type FetchResult, FileSessionStore, type GatewayMiddleware, GatewayRoutingError, type HandoffConfig, type HandoffEvent, HandoffManager, type IdentificationResult, InMemoryStore, KnowledgeBase, type KnowledgeBaseConfig, MemorySessionStore, MemoryVectorStore, OPENAI_PRICING, OpenAITTS, OpenAIWhisperSTT, type OutcomeRecord, OutcomeTracker, PromptRegistry, PromptTemplate, PromptVersionError, ProviderDependencyError, type STTOptions, type SearchResult, type ServerConfig, type SessionStore, SlackAdapter, type SlackConfig, type SpeakerProfile, StructuredOutputError, type SupportBotConfig, type TTSFormat, type TTSOptions, type TTSResult, type TTSVoice, TelegramAdapter, type TelegramConfig, ToolAgent, type ToolContext, ToolExecutionError, type TranscriptionResult, type TranscriptionSegment, type UsageMetrics, UsageMetricsSchema, ValidationError, type VectorEntry, type VerificationResult, VoiceprintStore, applyRequestMiddleware, applyResponseMiddleware, calculatorTool, chunkText, createChatHandler, createTool, dateTimeTool, startChatServer, webSearchTool };