@egain/ai-agent-sdk 0.1.0

package/dist/core/message/Transcript.d.ts

@@ -0,0 +1,373 @@
+/**
+ * # Transcript
+ *
+ * The Transcript feature automatically records all messages sent and received
+ * during a conversation, providing a complete history for display, debugging,
+ * or analytics.
+ *
+ * ## Overview
+ *
+ * Transcript is enabled by default and automatically captures:
+ * - Customer messages (sent)
+ * - Agent responses (received)
+ * - System messages
+ * - Context messages
+ *
+ * ## Quick Start
+ *
+ * Access the transcript through the agent instance:
+ *
+ * ```typescript
+ * // Get all transcript entries
+ * const entries = agent.getTranscript();
+ *
+ * // Get as JSON (for display or storage)
+ * const json = agent.getTranscriptAsJSON();
+ *
+ * // Get transcript size
+ * const count = agent.getTranscriptSize();
+ *
+ * // Clear transcript
+ * agent.clearTranscript();
+ * ```
+ *
+ * ## Configuration
+ *
+ * Configure transcript behavior when creating the agent:
+ *
+ * ```typescript
+ * const agent = new AiAgent({
+ *   id: "agent-id",
+ *   endpoint: "https://your-endpoint.com",
+ *   transcriptConfig: {
+ *     enabled: true,                    // Enable/disable transcript
+ *     excludeRoles: ["heartbeat"],      // Exclude heartbeat messages
+ *     excludePersonas: ["system"]       // Exclude system messages
+ *   }
+ * });
+ * ```
+ *
+ * ## Filtering Entries
+ *
+ * Retrieve filtered transcript entries:
+ *
+ * ```typescript
+ * // Get only received messages
+ * const received = agent.getTranscript({ direction: 'received' });
+ *
+ * // Get messages from a specific time range
+ * const recent = agent.getTranscript({
+ *   fromTimestamp: Date.now() - 3600000  // Last hour
+ * });
+ *
+ * // Get only agent messages
+ * const agentMessages = agent.getTranscript({ persona: 'agent' });
+ * ```
+ *
+ * ## Transcript Events
+ *
+ * Listen for transcript updates in real-time:
+ *
+ * ```typescript
+ * agent.on('transcriptUpdate', (event) => {
+ *   const { entry } = event.payload;
+ *   console.log(`${entry.direction}: ${entry.message.content}`);
+ * });
+ * ```
+ *
+ * ## Use Cases
+ *
+ * - **Chat UI**: Display conversation history
+ * - **Analytics**: Track conversation patterns
+ * - **Debugging**: Review message flow
+ * - **Persistence**: Save conversations to database
+ *
+ * @module Transcript
+ * @category Features
+ */
+import { Message } from './Message.js';
+import { Persona, Role } from './types.js';
+/**
+ * Transcript entry containing a message with metadata.
+ *
+ * Each entry represents a single message in the conversation
+ * with direction and timing information.
+ *
+ * @example
+ * ```typescript
+ * const entry: TranscriptEntry = {
+ *   message: message,
+ *   direction: 'received',
+ *   timestamp: Date.now(),
+ *   sessionId: 'session-123',
+ *   agentId: 'agent-456'
+ * };
+ * ```
+ *
+ * @category Features
+ * @group Transcript
+ */
+export interface TranscriptEntry {
+    /** The message object */
+    message: Message;
+    /** Whether the message was sent or received */
+    direction: 'sent' | 'received';
+    /** Timestamp when the message was recorded */
+    timestamp: number;
+    /** Session ID associated with this message */
+    sessionId?: string | number;
+    /** Agent ID associated with this message */
+    agentId?: string | number;
+}
+/**
+ * Configuration for transcript storage and filtering.
+ *
+ * Use this to control which messages are recorded in the transcript.
+ *
+ * @example
+ * ```typescript
+ * const config: TranscriptConfig = {
+ *   enabled: true,
+ *   excludeRoles: ['heartbeat', 'token'],
+ *   excludePersonas: ['system']
+ * };
+ * ```
+ *
+ * @category Features
+ * @group Transcript
+ */
+export interface TranscriptConfig {
+    /**
+     * Enable or disable transcript storage.
+     * When disabled, no messages are recorded.
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Array of message types to include.
+     * If specified, only these message types are recorded.
+     * If not specified, all message types are included (subject to exclude filters).
+     *
+     * @example ['agent_message', 'customer_message']
+     */
+    includeMessageTypes?: string[];
+    /**
+     * Array of roles to exclude from the transcript.
+     * Messages with these roles will not be recorded.
+     *
+     * @example ['heartbeat', 'token']
+     */
+    excludeRoles?: string[];
+    /**
+     * Array of personas to exclude from the transcript.
+     * Messages from these personas will not be recorded.
+     *
+     * @example ['system']
+     */
+    excludePersonas?: string[];
+}
+/**
+ * Options for filtering transcript entries when retrieving.
+ *
+ * @example
+ * ```typescript
+ * // Get received messages from the last hour
+ * const options: TranscriptOptions = {
+ *   direction: 'received',
+ *   fromTimestamp: Date.now() - 3600000
+ * };
+ * const entries = transcript.getEntries(options);
+ * ```
+ *
+ * @category Features
+ * @group Transcript
+ */
+export interface TranscriptOptions {
+    /**
+     * Filter entries from this timestamp onwards (inclusive)
+     */
+    fromTimestamp?: number;
+    /**
+     * Filter entries up to this timestamp (inclusive)
+     */
+    toTimestamp?: number;
+    /**
+     * Filter by direction: 'sent', 'received', or 'both'
+     */
+    direction?: 'sent' | 'received' | 'both';
+    /**
+     * Filter by message persona (e.g., 'agent', 'customer')
+     */
+    persona?: Persona;
+    /**
+     * Filter by message role (e.g., 'human', 'context')
+     */
+    role?: Role;
+}
+/**
+ * Transcript storage class for managing conversation history.
+ *
+ * The Transcript class provides a complete record of all messages
+ * exchanged during a conversation. It supports filtering, JSON export,
+ * and real-time updates.
+ *
+ * @example Basic usage
+ * ```typescript
+ * const transcript = new Transcript();
+ *
+ * // Add a message
+ * transcript.add(message, 'sent', sessionId, agentId);
+ *
+ * // Get all entries
+ * const entries = transcript.getEntries();
+ *
+ * // Get as JSON for storage
+ * const json = transcript.getEntriesAsJSON();
+ *
+ * // Get entry count
+ * console.log(`${transcript.size()} messages`);
+ *
+ * // Clear all entries
+ * transcript.clear();
+ * ```
+ *
+ * @example With configuration
+ * ```typescript
+ * const transcript = new Transcript({
+ *   enabled: true,
+ *   excludeRoles: ['heartbeat'],  // Don't record heartbeats
+ * });
+ * ```
+ *
+ * @example Filtering entries
+ * ```typescript
+ * // Get only agent responses
+ * const agentResponses = transcript.getEntries({
+ *   direction: 'received',
+ *   persona: 'agent'
+ * });
+ *
+ * // Get messages from the last 5 minutes
+ * const recentMessages = transcript.getEntries({
+ *   fromTimestamp: Date.now() - 300000
+ * });
+ * ```
+ *
+ * @category Features
+ * @group Transcript
+ */
+export declare class Transcript {
+    private entries;
+    private config;
+    /**
+     * Create a new Transcript instance
+     * @param config - Optional configuration for filtering
+     */
+    constructor(config?: TranscriptConfig);
+    /**
+     * Add a message to the transcript.
+     *
+     * Messages are automatically filtered based on configuration.
+     * If the transcript is disabled or the message matches an exclude filter,
+     * it will not be recorded.
+     *
+     * @param message - The message to add
+     * @param direction - Whether the message was 'sent' or 'received'
+     * @param sessionId - Optional session ID for context
+     * @param agentId - Optional agent ID for context
+     *
+     * @example
+     * ```typescript
+     * transcript.add(
+     *   new Message('customer', 'human', 'Hello!'),
+     *   'sent',
+     *   'session-123',
+     *   'agent-456'
+     * );
+     * ```
+     */
+    add(message: Message, direction: 'sent' | 'received', sessionId?: string | number, agentId?: string | number): void;
+    /**
+     * Get transcript entries, optionally filtered.
+     *
+     * @param options - Optional filtering options
+     * @returns Array of transcript entries matching the filter
+     *
+     * @example
+     * ```typescript
+     * // Get all entries
+     * const all = transcript.getEntries();
+     *
+     * // Get only sent messages
+     * const sent = transcript.getEntries({ direction: 'sent' });
+     *
+     * // Get messages from last hour
+     * const recent = transcript.getEntries({
+     *   fromTimestamp: Date.now() - 3600000
+     * });
+     * ```
+     */
+    getEntries(options?: TranscriptOptions): TranscriptEntry[];
+    /**
+     * Get transcript entries as plain JSON-serializable objects.
+     *
+     * Useful for storing transcripts in databases, sending to APIs,
+     * or displaying in UI components.
+     *
+     * @param options - Optional filtering options
+     * @returns Array of plain objects representing transcript entries
+     *
+     * @example
+     * ```typescript
+     * const json = transcript.getEntriesAsJSON();
+     *
+     * // Each entry includes:
+     * // {
+     * //   messageId, persona, role, content, messageData,
+     * //   timestamp, from, to, agentId, sessionId,
+     * //   direction, entryTimestamp
+     * // }
+     *
+     * // Save to database
+     * await db.saveTranscript(json);
+     * ```
+     */
+    getEntriesAsJSON(options?: TranscriptOptions): any[];
+    /**
+     * Get the number of entries in the transcript.
+     * @returns Number of recorded messages
+     */
+    size(): number;
+    /**
+     * Clear all transcript entries.
+     *
+     * This removes all recorded messages. Use with caution as
+     * this action cannot be undone.
+     */
+    clear(): void;
+    /**
+     * Check if a message should be included based on configuration filters
+     * @param message - The message to check
+     * @returns True if message should be included
+     */
+    private shouldInclude;
+    /**
+     * Update transcript configuration at runtime.
+     *
+     * @param config - New configuration options (partial update)
+     *
+     * @example
+     * ```typescript
+     * // Disable transcript temporarily
+     * transcript.updateConfig({ enabled: false });
+     *
+     * // Re-enable with new exclusions
+     * transcript.updateConfig({
+     *   enabled: true,
+     *   excludeRoles: ['heartbeat', 'token']
+     * });
+     * ```
+     */
+    updateConfig(config: Partial<TranscriptConfig>): void;
+}
+//# sourceMappingURL=Transcript.d.ts.map

package/dist/core/message/Transcript.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Transcript.d.ts","sourceRoot":"","sources":["../../../src/core/message/Transcript.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsFG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,eAAe;IAC9B,yBAAyB;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,GAAG,UAAU,CAAC;IAC/B,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,4CAA4C;IAC5C,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAE/B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IAExB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM,CAAC;IAEzC;;OAEG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;OAEG;IACH,IAAI,CAAC,EAAE,IAAI,CAAC;CACb;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,OAAO,CAAyB;IACxC,OAAO,CAAC,MAAM,CAA6B;IAE3C;;;OAGG;gBACS,MAAM,GAAE,gBAAqB;IASzC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,GAAG,CACD,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,MAAM,GAAG,UAAU,EAC9B,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,EAC3B,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GACxB,IAAI;IAqBP;;;;;;;;;;;;;;;;;;;OAmBG;IACH,UAAU,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,eAAe,EAAE;IA+B1D;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,gBAAgB,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,GAAG,EAAE;IAkBpD;;;OAGG;IACH,IAAI,IAAI,MAAM;IAId;;;;;OAKG;IACH,KAAK,IAAI,IAAI;IAIb;;;;OAIG;IACH,OAAO,CAAC,aAAa;IA2BrB;;;;;;;;;;;;;;;;OAgBG;IACH,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,gBAAgB,CAAC,GAAG,IAAI;CActD"}