@asgard-js/core 0.0.31 → 0.0.32-canary.0

package/README.md

@@ -220,23 +220,15 @@ The core package includes comprehensive tests using Vitest.
 
 ```sh
 # Run tests once
-npm test
-# or
 yarn test:core
 
 # Run tests in watch mode
-npm run test:watch
-# or
 yarn test:core:watch
 
 # Run tests with UI
-npm run test:ui
-# or
 yarn test:core:ui
 
 # Run tests with coverage
-npm run test:coverage
-# or
 yarn test:core:coverage
 ```
 
@@ -305,7 +297,7 @@ yarn build:core
 yarn watch:core
 ```
 
-Setup your npm release token:
+Setup your npm registry token for yarn publishing:
 
 ```sh
 cd ~/

package/eslint.config.cjs

@@ -0,0 +1,22 @@
+const baseConfig = require('../../eslint.config.cjs');
+
+module.exports = [
+  ...baseConfig,
+  {
+    files: ['**/*.json'],
+    rules: {
+      '@nx/dependency-checks': [
+        'error',
+        {
+          ignoredFiles: [
+            '{projectRoot}/eslint.config.{js,cjs,mjs}',
+            '{projectRoot}/vite.config.{js,ts,mjs,mts}',
+          ],
+        },
+      ],
+    },
+    languageOptions: {
+      parser: require('jsonc-eslint-parser'),
+    },
+  },
+];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asgard-js/core",
-  "version": "0.0.31",
+  "version": "0.0.32-canary.0",
   "dependencies": {
     "@microsoft/fetch-event-source": "^2.0.1",
     "rxjs": "^7.8.1"

package/src/constants/enum.ts

@@ -0,0 +1,32 @@
+export enum FetchSseAction {
+  RESET_CHANNEL = 'RESET_CHANNEL',
+  NONE = 'NONE',
+}
+
+export enum EventType {
+  INIT = 'asgard.run.init',
+  PROCESS = 'asgard.process',
+  PROCESS_START = 'asgard.process.start',
+  PROCESS_COMPLETE = 'asgard.process.complete',
+  MESSAGE = 'asgard.message',
+  MESSAGE_START = 'asgard.message.start',
+  MESSAGE_DELTA = 'asgard.message.delta',
+  MESSAGE_COMPLETE = 'asgard.message.complete',
+  TOOL_CALL = 'asgard.tool_call',
+  TOOL_CALL_START = 'asgard.tool_call.start',
+  TOOL_CALL_COMPLETE = 'asgard.tool_call.complete',
+  DONE = 'asgard.run.done',
+  ERROR = 'asgard.run.error',
+}
+
+export enum MessageTemplateType {
+  TEXT = 'TEXT',
+  HINT = 'HINT',
+  BUTTON = 'BUTTON',
+  IMAGE = 'IMAGE',
+  VIDEO = 'VIDEO',
+  AUDIO = 'AUDIO',
+  LOCATION = 'LOCATION',
+  CAROUSEL = 'CAROUSEL',
+  CHART = 'CHART',
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+export type { Subscription } from 'rxjs';
+
+export type * from 'src/types';
+
+export * from 'src/constants/enum';
+
+export { default as AsgardServiceClient } from 'src/lib/client';
+
+export { default as Channel } from 'src/lib/channel';
+
+export { default as Conversation } from 'src/lib/conversation';

package/src/lib/channel.ts

@@ -0,0 +1,152 @@
+import { BehaviorSubject, combineLatest, map, Subscription } from 'rxjs';
+import {
+  ChannelConfig,
+  ChannelStates,
+  FetchSseOptions,
+  FetchSsePayload,
+  IAsgardServiceClient,
+  ObserverOrNext,
+} from 'src/types';
+import { FetchSseAction } from 'src/constants/enum';
+import Conversation from './conversation';
+
+export default class Channel {
+  private client: IAsgardServiceClient;
+
+  public customChannelId: string;
+  public customMessageId?: string;
+
+  private isConnecting$: BehaviorSubject<boolean>;
+  private conversation$: BehaviorSubject<Conversation>;
+  private statesObserver?: ObserverOrNext<ChannelStates>;
+  private statesSubscription?: Subscription;
+
+  private constructor(config: ChannelConfig) {
+    if (!config.client) {
+      throw new Error('client must be required');
+    }
+
+    if (!config.customChannelId) {
+      throw new Error('customChannelId must be required');
+    }
+
+    this.client = config.client;
+    this.customChannelId = config.customChannelId;
+    this.customMessageId = config.customMessageId;
+
+    this.isConnecting$ = new BehaviorSubject(false);
+    this.conversation$ = new BehaviorSubject(config.conversation);
+    this.statesObserver = config.statesObserver;
+  }
+
+  public static async reset(
+    config: ChannelConfig,
+    payload?: Pick<FetchSsePayload, 'text' | 'payload'>,
+    options?: FetchSseOptions
+  ): Promise<Channel> {
+    const channel = new Channel(config);
+
+    try {
+      channel.subscribe();
+
+      await channel.resetChannel(payload, options);
+
+      return channel;
+    } catch (error) {
+      channel.close();
+
+      throw error;
+    }
+  }
+
+  private subscribe(): void {
+    this.statesSubscription = combineLatest([
+      this.isConnecting$,
+      this.conversation$,
+    ])
+      .pipe(
+        map(([isConnecting, conversation]) => ({
+          isConnecting,
+          conversation,
+        }))
+      )
+      .subscribe(this.statesObserver);
+  }
+
+  private fetchSse(
+    payload: FetchSsePayload,
+    options?: FetchSseOptions
+  ): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.isConnecting$.next(true);
+
+      this.client.fetchSse(payload, {
+        onSseStart: options?.onSseStart,
+        onSseMessage: (response) => {
+          options?.onSseMessage?.(response);
+          this.conversation$.next(this.conversation$.value.onMessage(response));
+        },
+        onSseError: (err) => {
+          options?.onSseError?.(err);
+          this.isConnecting$.next(false);
+          reject(err);
+        },
+        onSseCompleted: () => {
+          options?.onSseCompleted?.();
+          this.isConnecting$.next(false);
+          resolve();
+        },
+      });
+    });
+  }
+
+  private resetChannel(
+    payload?: Pick<FetchSsePayload, 'text' | 'payload'>,
+    options?: FetchSseOptions
+  ): Promise<void> {
+    return this.fetchSse(
+      {
+        action: FetchSseAction.RESET_CHANNEL,
+        customChannelId: this.customChannelId,
+        customMessageId: this.customMessageId,
+        text: payload?.text || '',
+        payload: payload?.payload,
+      },
+      options
+    );
+  }
+
+  public sendMessage(
+    payload: Pick<FetchSsePayload, 'customMessageId' | 'text' | 'payload'>,
+    options?: FetchSseOptions
+  ): Promise<void> {
+    const text = payload.text.trim();
+    const messageId = payload.customMessageId ?? crypto.randomUUID();
+
+    this.conversation$.next(
+      this.conversation$.value.pushMessage({
+        type: 'user',
+        messageId,
+        text,
+        time: new Date(),
+      })
+    );
+
+    return this.fetchSse(
+      {
+        action: FetchSseAction.NONE,
+        customChannelId: this.customChannelId,
+        customMessageId: messageId,
+        payload: payload?.payload,
+        text,
+      },
+      options
+    );
+  }
+
+  public close(): void {
+    this.isConnecting$.complete();
+    this.conversation$.complete();
+    this.statesSubscription?.unsubscribe();
+  }
+}

package/src/lib/client.spec.ts

@@ -0,0 +1,150 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import AsgardServiceClient from './client';
+import { ClientConfig } from '../types/client';
+
+describe('AsgardServiceClient', () => {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let consoleSpy: any;
+
+  beforeEach(() => {
+    // eslint-disable-next-line @typescript-eslint/no-empty-function
+    consoleSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    consoleSpy.mockRestore();
+  });
+
+  describe('constructor', () => {
+    it('should throw error when neither endpoint nor botProviderEndpoint is provided', () => {
+      const config = {
+        apiKey: 'test-key',
+      } as any; // Use 'as any' to bypass TypeScript checking for testing runtime behavior
+
+      expect(() => new AsgardServiceClient(config)).toThrow(
+        'Either endpoint or botProviderEndpoint must be provided'
+      );
+    });
+
+    it('should derive endpoint from botProviderEndpoint when only botProviderEndpoint is provided', () => {
+      const config: ClientConfig = {
+        botProviderEndpoint: 'https://api.example.com/bot-provider/bp-123',
+        apiKey: 'test-key',
+      };
+
+      const client = new AsgardServiceClient(config);
+      
+      // Access private endpoint field for testing
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      expect((client as any).endpoint).toBe('https://api.example.com/bot-provider/bp-123/message/sse');
+      expect(consoleSpy).not.toHaveBeenCalled();
+    });
+
+    it('should use provided endpoint when only endpoint is provided', () => {
+      const config: ClientConfig = {
+        endpoint: 'https://api.example.com/custom/sse',
+        apiKey: 'test-key',
+      };
+
+      const client = new AsgardServiceClient(config);
+      
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      expect((client as any).endpoint).toBe('https://api.example.com/custom/sse');
+      expect(consoleSpy).not.toHaveBeenCalled();
+    });
+
+    it('should use provided endpoint and warn about deprecation when debugMode is enabled', () => {
+      const config: ClientConfig = {
+        endpoint: 'https://api.example.com/custom/sse',
+        apiKey: 'test-key',
+        debugMode: true,
+      };
+
+      const client = new AsgardServiceClient(config);
+      
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      expect((client as any).endpoint).toBe('https://api.example.com/custom/sse');
+      expect(consoleSpy).toHaveBeenCalledWith(
+        '[AsgardServiceClient] The "endpoint" option is deprecated and will be removed in the next major version. ' +
+        'Please use "botProviderEndpoint" instead. The SSE endpoint will be automatically derived as "${botProviderEndpoint}/message/sse".'
+      );
+    });
+
+    it('should use provided endpoint without warning when debugMode is disabled', () => {
+      const config: ClientConfig = {
+        endpoint: 'https://api.example.com/custom/sse',
+        apiKey: 'test-key',
+        debugMode: false,
+      };
+
+      const client = new AsgardServiceClient(config);
+      
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      expect((client as any).endpoint).toBe('https://api.example.com/custom/sse');
+      expect(consoleSpy).not.toHaveBeenCalled();
+    });
+
+    it('should prioritize endpoint over botProviderEndpoint when both are provided', () => {
+      const config: ClientConfig = {
+        endpoint: 'https://api.example.com/custom/sse',
+        botProviderEndpoint: 'https://api.example.com/bot-provider/bp-123',
+        apiKey: 'test-key',
+        debugMode: true,
+      };
+
+      const client = new AsgardServiceClient(config);
+      
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      expect((client as any).endpoint).toBe('https://api.example.com/custom/sse');
+      expect(consoleSpy).toHaveBeenCalledWith(
+        '[AsgardServiceClient] The "endpoint" option is deprecated and will be removed in the next major version. ' +
+        'Please use "botProviderEndpoint" instead. The SSE endpoint will be automatically derived as "${botProviderEndpoint}/message/sse".'
+      );
+    });
+
+    it('should correctly set other configuration properties', () => {
+      const transformSsePayload = vi.fn();
+      const config: ClientConfig = {
+        botProviderEndpoint: 'https://api.example.com/bot-provider/bp-123',
+        apiKey: 'test-key',
+        debugMode: true,
+        transformSsePayload,
+      };
+
+      const client = new AsgardServiceClient(config);
+      
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      expect((client as any).apiKey).toBe('test-key');
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      expect((client as any).debugMode).toBe(true);
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      expect((client as any).transformSsePayload).toBe(transformSsePayload);
+    });
+
+    it('should handle trailing slash in botProviderEndpoint correctly', () => {
+      const config: ClientConfig = {
+        botProviderEndpoint: 'https://api.example.com/bot-provider/bp-123/',
+        apiKey: 'test-key',
+      };
+
+      const client = new AsgardServiceClient(config);
+      
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      expect((client as any).endpoint).toBe('https://api.example.com/bot-provider/bp-123/message/sse');
+      expect(consoleSpy).not.toHaveBeenCalled();
+    });
+
+    it('should handle multiple trailing slashes in botProviderEndpoint', () => {
+      const config: ClientConfig = {
+        botProviderEndpoint: 'https://api.example.com/bot-provider/bp-123///',
+        apiKey: 'test-key',
+      };
+
+      const client = new AsgardServiceClient(config);
+      
+      // Should remove all trailing slashes
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      expect((client as any).endpoint).toBe('https://api.example.com/bot-provider/bp-123/message/sse');
+    });
+  });
+});

package/src/lib/client.ts

@@ -0,0 +1,141 @@
+import {
+  ClientConfig,
+  IAsgardServiceClient,
+  FetchSsePayload,
+  FetchSseOptions,
+  SseResponse,
+  SseEvents,
+} from 'src/types';
+import { createSseObservable } from './create-sse-observable';
+import { concatMap, delay, of, retry, Subject, takeUntil } from 'rxjs';
+import { EventType } from 'src/constants/enum';
+import { EventEmitter } from './event-emitter';
+
+export default class AsgardServiceClient implements IAsgardServiceClient {
+  private apiKey?: string;
+  private endpoint!: string;
+  private debugMode?: boolean;
+  private destroy$ = new Subject<void>();
+  private sseEmitter = new EventEmitter<SseEvents>();
+  private transformSsePayload?: (payload: FetchSsePayload) => FetchSsePayload;
+
+  constructor(config: ClientConfig) {
+    // Validate that either endpoint or botProviderEndpoint is provided
+    if (!config.endpoint && !config.botProviderEndpoint) {
+      throw new Error('Either endpoint or botProviderEndpoint must be provided');
+    }
+
+    this.apiKey = config.apiKey;
+    this.debugMode = config.debugMode;
+    this.transformSsePayload = config.transformSsePayload;
+
+    // Handle endpoint derivation and deprecation
+    if (!config.endpoint && config.botProviderEndpoint) {
+      // Derive endpoint from botProviderEndpoint (new recommended way)
+      // Handle trailing slashes to prevent double slashes
+      const baseEndpoint = config.botProviderEndpoint.replace(/\/+$/, '');
+      this.endpoint = `${baseEndpoint}/message/sse`;
+    } else if (config.endpoint) {
+      // Use provided endpoint but warn about deprecation
+      this.endpoint = config.endpoint;
+      if (this.debugMode) {
+        // eslint-disable-next-line no-console
+        console.warn(
+          '[AsgardServiceClient] The "endpoint" option is deprecated and will be removed in the next major version. ' +
+          `Please use "botProviderEndpoint" instead. The SSE endpoint will be automatically derived as "\${botProviderEndpoint}/message/sse".`
+        );
+      }
+    }
+  }
+
+  on<K extends keyof SseEvents>(event: K, listener: SseEvents[K]): void {
+    this.sseEmitter.remove(event);
+    this.sseEmitter.on(event, listener);
+  }
+
+  handleEvent(response: SseResponse<EventType>): void {
+    switch (response.eventType) {
+      case EventType.INIT:
+        this.sseEmitter.emit(
+          EventType.INIT,
+          response as SseResponse<EventType.INIT>
+        );
+
+        break;
+      case EventType.PROCESS_START:
+      case EventType.PROCESS_COMPLETE:
+        this.sseEmitter.emit(
+          EventType.PROCESS,
+          response as Parameters<SseEvents[EventType.PROCESS]>[0]
+        );
+
+        break;
+      case EventType.MESSAGE_START:
+      case EventType.MESSAGE_DELTA:
+      case EventType.MESSAGE_COMPLETE:
+        this.sseEmitter.emit(
+          EventType.MESSAGE,
+          response as Parameters<SseEvents[EventType.MESSAGE]>[0]
+        );
+
+        break;
+      case EventType.TOOL_CALL_START:
+      case EventType.TOOL_CALL_COMPLETE:
+        this.sseEmitter.emit(
+          EventType.TOOL_CALL,
+          response as Parameters<SseEvents[EventType.TOOL_CALL]>[0]
+        );
+
+        break;
+      case EventType.DONE:
+        this.sseEmitter.emit(
+          EventType.DONE,
+          response as SseResponse<EventType.DONE>
+        );
+
+        break;
+      case EventType.ERROR:
+        this.sseEmitter.emit(
+          EventType.ERROR,
+          response as SseResponse<EventType.ERROR>
+        );
+
+        break;
+      default:
+        break;
+    }
+  }
+
+  fetchSse(payload: FetchSsePayload, options?: FetchSseOptions): void {
+    options?.onSseStart?.();
+
+    createSseObservable({
+      apiKey: this.apiKey,
+      endpoint: this.endpoint,
+      debugMode: this.debugMode,
+      payload: this.transformSsePayload?.(payload) ?? payload,
+    })
+      .pipe(
+        concatMap((event) => of(event).pipe(delay(options?.delayTime ?? 50))),
+        takeUntil(this.destroy$),
+        retry(3)
+      )
+      .subscribe({
+        next: (response) => {
+          options?.onSseMessage?.(response);
+          this.handleEvent(response);
+        },
+        error: (error) => {
+          options?.onSseError?.(error);
+        },
+        complete: () => {
+          options?.onSseCompleted?.();
+        },
+      });
+  }
+
+  close(): void {
+    this.destroy$.next();
+    this.destroy$.complete();
+  }
+}

package/src/lib/conversation.ts

@@ -0,0 +1,120 @@
+import { EventType } from 'src/constants/enum';
+import { ConversationMessage, SseResponse } from 'src/types';
+
+interface IConversation {
+  messages: Map<string, ConversationMessage> | null;
+}
+
+export default class Conversation implements IConversation {
+  public messages: Map<string, ConversationMessage> | null = null;
+
+  constructor({ messages }: IConversation) {
+    this.messages = messages;
+  }
+
+  pushMessage(message: ConversationMessage): Conversation {
+    const messages = new Map(this.messages);
+    messages.set(message.messageId, message);
+
+    return new Conversation({ messages });
+  }
+
+  onMessage(response: SseResponse<EventType>): Conversation {
+    switch (response.eventType) {
+      case EventType.MESSAGE_START:
+        return this.onMessageStart(
+          response as SseResponse<EventType.MESSAGE_START>
+        );
+      case EventType.MESSAGE_DELTA:
+        return this.onMessageDelta(
+          response as SseResponse<EventType.MESSAGE_DELTA>
+        );
+      case EventType.MESSAGE_COMPLETE:
+        return this.onMessageComplete(
+          response as SseResponse<EventType.MESSAGE_COMPLETE>
+        );
+      case EventType.ERROR:
+        return this.onMessageError(response as SseResponse<EventType.ERROR>);
+      default:
+        return this;
+    }
+  }
+
+  onMessageStart(response: SseResponse<EventType.MESSAGE_START>): Conversation {
+    const message = response.fact.messageStart.message;
+    const messages = new Map(this.messages);
+
+    messages.set(message.messageId, {
+      type: 'bot',
+      eventType: EventType.MESSAGE_START,
+      isTyping: true,
+      typingText: '',
+      messageId: message.messageId,
+      message,
+      time: new Date(),
+    });
+
+    return new Conversation({ messages });
+  }
+
+  onMessageDelta(response: SseResponse<EventType.MESSAGE_DELTA>): Conversation {
+    const message = response.fact.messageDelta.message;
+
+    const messages = new Map(this.messages);
+
+    const currentMessage = messages.get(message.messageId);
+
+    if (currentMessage?.type !== 'bot') return this;
+
+    const typingText = `${currentMessage?.typingText ?? ''}${message.text}`;
+
+    messages.set(message.messageId, {
+      type: 'bot',
+      eventType: EventType.MESSAGE_DELTA,
+      isTyping: true,
+      typingText,
+      messageId: message.messageId,
+      message,
+      time: new Date(),
+    });
+
+    return new Conversation({ messages });
+  }
+
+  onMessageComplete(
+    response: SseResponse<EventType.MESSAGE_COMPLETE>
+  ): Conversation {
+    const message = response.fact.messageComplete.message;
+
+    const messages = new Map(this.messages);
+
+    messages.set(message.messageId, {
+      type: 'bot',
+      eventType: EventType.MESSAGE_COMPLETE,
+      isTyping: false,
+      typingText: null,
+      messageId: message.messageId,
+      message,
+      time: new Date(),
+    });
+
+    return new Conversation({ messages });
+  }
+
+  onMessageError(response: SseResponse<EventType.ERROR>): Conversation {
+    const messageId = crypto.randomUUID();
+    const error = response.fact.runError.error;
+
+    const messages = new Map(this.messages);
+
+    messages.set(messageId, {
+      type: 'error',
+      eventType: EventType.ERROR,
+      messageId,
+      error,
+      time: new Date(),
+    });
+
+    return new Conversation({ messages });
+  }
+}

package/src/lib/create-sse-observable.ts

@@ -0,0 +1,77 @@
+import { Observable } from 'rxjs';
+import {
+  EventSourceMessage,
+  fetchEventSource,
+} from '@microsoft/fetch-event-source';
+import { FetchSsePayload, SseResponse } from 'src/types';
+import { EventType } from 'src/constants/enum';
+
+interface CreateSseObservableOptions {
+  endpoint: string;
+  apiKey?: string;
+  debugMode?: boolean;
+  payload: FetchSsePayload;
+}
+
+export function createSseObservable(
+  options: CreateSseObservableOptions
+): Observable<SseResponse<EventType>> {
+  const { endpoint, apiKey, payload, debugMode } = options;
+
+  return new Observable<SseResponse<EventType>>((subscriber) => {
+    const controller = new AbortController();
+
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+    };
+
+    if (apiKey) {
+      headers['X-API-KEY'] = apiKey;
+    }
+
+    const searchParams = new URLSearchParams();
+
+    if (debugMode) {
+      searchParams.set('is_debug', 'true');
+    }
+
+    const url = new URL(endpoint);
+
+    if (searchParams.toString()) {
+      url.search = searchParams.toString();
+    }
+
+    fetchEventSource(url.toString(), {
+      method: 'POST',
+      headers,
+      body: payload ? JSON.stringify(payload) : undefined,
+      signal: controller.signal,
+      /**
+       * Allow SSE to work when the page is hidden.
+       * https://github.com/Azure/fetch-event-source/issues/17#issuecomment-1525904929
+       */
+      openWhenHidden: true,
+      onopen: async (response) => {
+        if (!response.ok) {
+          subscriber.error(response);
+          controller.abort();
+        }
+      },
+      onmessage: (esm: EventSourceMessage) => {
+        subscriber.next(JSON.parse(esm.data));
+      },
+      onclose: () => {
+        subscriber.complete();
+      },
+      onerror: (err) => {
+        subscriber.error(err);
+        controller.abort();
+        throw err;
+      },
+    });
+
+    return (): void => {
+      controller.abort();
+    };
+  });
+}

package/src/lib/event-emitter.ts

@@ -0,0 +1,30 @@
+import { Listeners } from 'src/types';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export class EventEmitter<Events extends Record<string, any>> {
+  private listeners: Listeners<Events> = {};
+
+  on<K extends keyof Events>(event: K, listener: Events[K]): void {
+    this.listeners = Object.assign({}, this.listeners, {
+      [event]: (this.listeners[event] ?? []).concat(listener),
+    });
+  }
+
+  off<K extends keyof Events>(event: K, listener: Events[K]): void {
+    if (!this.listeners[event]) return;
+
+    this.listeners = Object.assign({}, this.listeners, {
+      [event]: (this.listeners[event] ?? []).filter((l) => l !== listener),
+    });
+  }
+
+  remove<K extends keyof Events>(event: K): void {
+    delete this.listeners[event];
+  }
+
+  emit<K extends keyof Events>(event: K, ...args: Parameters<Events[K]>): void {
+    if (!this.listeners[event]) return;
+
+    this.listeners[event].forEach((listener) => listener(...args));
+  }
+}

package/src/types/channel.ts

@@ -0,0 +1,50 @@
+import { Observer } from 'rxjs';
+import { EventType } from 'src/constants/enum';
+import Conversation from 'src/lib/conversation';
+import { IAsgardServiceClient } from './client';
+import { ErrorMessage, Message } from './sse-response';
+
+export type ObserverOrNext<T> = Partial<Observer<T>> | ((value: T) => void);
+
+export interface ChannelStates {
+  isConnecting: boolean;
+  conversation: Conversation;
+}
+
+export interface ChannelConfig {
+  client: IAsgardServiceClient;
+  customChannelId: string;
+  customMessageId?: string;
+  conversation: Conversation;
+  statesObserver?: ObserverOrNext<ChannelStates>;
+}
+
+export type ConversationUserMessage = {
+  type: 'user';
+  messageId: string;
+  text: string;
+  time: Date;
+};
+
+export type ConversationBotMessage = {
+  type: 'bot';
+  messageId: string;
+  eventType: EventType;
+  isTyping: boolean;
+  typingText: string | null;
+  message: Message;
+  time: Date;
+};
+
+export type ConversationErrorMessage = {
+  type: 'error';
+  messageId: string;
+  eventType: EventType;
+  error: ErrorMessage;
+  time: Date;
+};
+
+export type ConversationMessage =
+  | ConversationUserMessage
+  | ConversationBotMessage
+  | ConversationErrorMessage;

package/src/types/client.ts

@@ -0,0 +1,89 @@
+import { EventType, FetchSseAction } from 'src/constants/enum';
+import { SseResponse } from './sse-response';
+import { EventHandler } from './event-emitter';
+
+export interface IAsgardServiceClient {
+  fetchSse(payload: FetchSsePayload, options?: FetchSseOptions): void;
+}
+
+export type InitEventHandler = EventHandler<SseResponse<EventType.INIT>>;
+export type MessageEventHandler = EventHandler<
+  SseResponse<
+    | EventType.MESSAGE_START
+    | EventType.MESSAGE_DELTA
+    | EventType.MESSAGE_COMPLETE
+  >
+>;
+export type ProcessEventHandler = EventHandler<
+  SseResponse<EventType.PROCESS_START | EventType.PROCESS_COMPLETE>
+>;
+export type DoneEventHandler = EventHandler<SseResponse<EventType.DONE>>;
+export type ErrorEventHandler = EventHandler<SseResponse<EventType.ERROR>>;
+export type ToolCallEventHandler = EventHandler<
+  SseResponse<EventType.TOOL_CALL_START | EventType.TOOL_CALL_COMPLETE>
+>;
+
+export interface SseHandlers {
+  onRunInit?: InitEventHandler;
+  onMessage?: MessageEventHandler;
+  onToolCall?: ToolCallEventHandler;
+  onProcess?: ProcessEventHandler;
+  onRunDone?: DoneEventHandler;
+  onRunError?: ErrorEventHandler;
+}
+
+export type ClientConfig = SseHandlers & {
+  apiKey?: string;
+  debugMode?: boolean;
+  transformSsePayload?: (payload: FetchSsePayload) => FetchSsePayload;
+} & (
+  | { 
+      /**
+       * @deprecated Use `botProviderEndpoint` instead. This will be removed in the next major version.
+       * If provided, it will be used. Otherwise, it will be automatically derived as `${botProviderEndpoint}/message/sse`
+       */
+      endpoint: string; 
+      /**
+       * Base URL for the bot provider service.
+       * The SSE endpoint will be automatically derived as `${botProviderEndpoint}/message/sse`
+       */
+      botProviderEndpoint?: string; 
+    }
+  | { 
+      /**
+       * Base URL for the bot provider service.
+       * The SSE endpoint will be automatically derived as `${botProviderEndpoint}/message/sse`
+       */
+      botProviderEndpoint: string; 
+      /**
+       * @deprecated Use `botProviderEndpoint` instead. This will be removed in the next major version.
+       * If provided, it will be used. Otherwise, it will be automatically derived as `${botProviderEndpoint}/message/sse`
+       */
+      endpoint?: string; 
+    }
+);
+
+export interface FetchSsePayload {
+  customChannelId: string;
+  customMessageId?: string;
+  text: string;
+  payload?: Record<string, unknown>;
+  action: FetchSseAction;
+}
+
+export interface FetchSseOptions {
+  delayTime?: number;
+  onSseStart?: () => void;
+  onSseMessage?: (response: SseResponse<EventType>) => void;
+  onSseError?: (error: unknown) => void;
+  onSseCompleted?: () => void;
+}
+
+export interface SseEvents {
+  [EventType.INIT]: InitEventHandler;
+  [EventType.PROCESS]: ProcessEventHandler;
+  [EventType.MESSAGE]: MessageEventHandler;
+  [EventType.TOOL_CALL]: ToolCallEventHandler;
+  [EventType.DONE]: DoneEventHandler;
+  [EventType.ERROR]: ErrorEventHandler;
+}

package/src/types/event-emitter.ts

@@ -0,0 +1,8 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+export type EventHandler<Args, Return = void> = Args extends any[]
+  ? (...args: Args) => Return
+  : (arg: Args) => Return;
+
+export type Listeners<Events extends Record<string, any>> = {
+  [K in keyof Events]?: Array<Events[K]>;
+};

package/src/types/index.ts

@@ -0,0 +1,4 @@
+export type * from './client';
+export type * from './channel';
+export type * from './sse-response';
+export type * from './event-emitter';

package/src/types/sse-response.ts

@@ -0,0 +1,176 @@
+import { EventType, MessageTemplateType } from 'src/constants/enum';
+
+export interface MessageTemplate {
+  quickReplies: { text: string }[];
+}
+
+export interface TextMessageTemplate extends MessageTemplate {
+  type: MessageTemplateType.TEXT;
+  text: string;
+}
+
+export interface HintMessageTemplate extends MessageTemplate {
+  type: MessageTemplateType.HINT;
+  text: string;
+}
+
+export interface ImageMessageTemplate extends MessageTemplate {
+  type: MessageTemplateType.IMAGE;
+  originalContentUrl: string;
+  previewImageUrl: string;
+}
+
+export interface VideoMessageTemplate extends MessageTemplate {
+  type: MessageTemplateType.VIDEO;
+  originalContentUrl: string;
+  previewImageUrl: string;
+  duration: number;
+}
+
+export interface AudioMessageTemplate extends MessageTemplate {
+  type: MessageTemplateType.AUDIO;
+  originalContentUrl: string;
+  duration: number;
+}
+
+export interface LocationMessageTemplate extends MessageTemplate {
+  type: MessageTemplateType.LOCATION;
+  title: string;
+  text: string;
+  latitude: number;
+  longitude: number;
+}
+
+export interface ChartMessageTemplate extends MessageTemplate {
+  type: MessageTemplateType.CHART;
+  title: string;
+  text: string;
+  chartOptions: {
+    type: string;
+    title: string;
+    spec: Record<string, unknown>;
+  }[];
+  defaultChart: string;
+  quickReplies: { text: string }[];
+}
+
+export type ButtonAction =
+  | {
+      type: 'message' | 'MESSAGE';
+      text: string;
+      uri?: null;
+    }
+  | {
+      type: 'uri' | 'URI';
+      text?: null;
+      uri: string;
+      target?: '_blank' | '_self' | '_parent' | '_top';
+    }
+  | {
+      type: 'emit' | 'EMIT';
+      payload: any;
+    };
+
+export interface ButtonMessageTemplate extends MessageTemplate {
+  type: MessageTemplateType.BUTTON;
+  title: string;
+  text: string;
+  thumbnailImageUrl: string;
+  imageAspectRatio: 'rectangle' | 'square';
+  imageSize: 'cover' | 'contain';
+  imageBackgroundColor: string;
+  defaultAction: ButtonAction;
+  buttons: { label: string; action: ButtonAction }[];
+}
+
+export interface CarouselMessageTemplate extends MessageTemplate {
+  type: MessageTemplateType.CAROUSEL;
+  columns: Omit<ButtonMessageTemplate, 'type' | 'quickReplies'>[];
+}
+
+export interface Message<Payload = unknown> {
+  messageId: string;
+  replyToCustomMessageId: string;
+  text: string;
+  payload: Payload | null;
+  isDebug: boolean;
+  idx: number;
+  template:
+    | TextMessageTemplate
+    | HintMessageTemplate
+    | ButtonMessageTemplate
+    | ImageMessageTemplate
+    | VideoMessageTemplate
+    | AudioMessageTemplate
+    | LocationMessageTemplate
+    | CarouselMessageTemplate
+    | ChartMessageTemplate;
+}
+
+export type IsEqual<A, B, DataType> = A extends B
+  ? B extends A
+    ? DataType
+    : null
+  : null;
+
+export interface MessageEventData {
+  message: Message;
+}
+
+export interface ErrorMessage {
+  message: string;
+  code: string;
+  inner: string;
+  location: {
+    namespace: string;
+    workflowName: string;
+    processorName: string;
+    processorType: string;
+  };
+}
+
+export interface ErrorEventData {
+  error: ErrorMessage;
+}
+
+export interface ToolCallBaseEventData {
+  processId: string;
+  callSeq: number;
+  toolCall: {
+    toolsetName: string;
+    toolName: string;
+    parameter: Record<string, unknown>;
+  };
+}
+
+export interface ToolCallCompleteEventData extends ToolCallBaseEventData {
+  toolCallResult: Record<string, unknown>;
+}
+
+export interface Fact<Type extends EventType> {
+  runInit: null;
+  runDone: null;
+  runError: IsEqual<Type, EventType.ERROR, ErrorEventData>;
+  messageStart: IsEqual<Type, EventType.MESSAGE_START, MessageEventData>;
+  messageDelta: IsEqual<Type, EventType.MESSAGE_DELTA, MessageEventData>;
+  messageComplete: IsEqual<Type, EventType.MESSAGE_COMPLETE, MessageEventData>;
+  toolCallStart: IsEqual<
+    Type,
+    EventType.TOOL_CALL_START,
+    ToolCallBaseEventData
+  >;
+  toolCallComplete: IsEqual<
+    Type,
+    EventType.TOOL_CALL_COMPLETE,
+    ToolCallCompleteEventData
+  >;
+}
+
+export interface SseResponse<Type extends EventType> {
+  eventType: Type;
+  requestId: string;
+  namespace: string;
+  botProviderName: string;
+  customChannelId: string;
+  fact: Fact<Type>;
+}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "files": [],
+  "include": [],
+  "references": [
+    {
+      "path": "./tsconfig.lib.json"
+    },
+    {
+      "path": "./tsconfig.spec.json"
+    }
+  ]
+}

package/tsconfig.lib.json

@@ -0,0 +1,28 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "src/*": ["src/*"]
+    },
+    "tsBuildInfoFile": "dist/tsconfig.lib.tsbuildinfo",
+    "emitDeclarationOnly": false,
+    "types": ["node", "vite/client"]
+  },
+  "include": ["src/**/*.ts"],
+  "references": [],
+  "exclude": [
+    "vite.config.ts",
+    "vite.config.mts",
+    "vitest.config.ts",
+    "vitest.config.mts",
+    "src/**/*.test.ts",
+    "src/**/*.spec.ts",
+    "src/**/*.test.tsx",
+    "src/**/*.spec.tsx",
+    "src/**/*.test.js",
+    "src/**/*.spec.js",
+    "src/**/*.test.jsx",
+    "src/**/*.spec.jsx"
+  ]
+}

package/tsconfig.spec.json

@@ -0,0 +1,33 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./out-tsc/vitest",
+    "types": [
+      "vitest/globals",
+      "vitest/importMeta",
+      "vite/client",
+      "node",
+      "vitest"
+    ]
+  },
+  "include": [
+    "vite.config.ts",
+    "vite.config.mts",
+    "vitest.config.ts",
+    "vitest.config.mts",
+    "src/**/*.test.ts",
+    "src/**/*.spec.ts",
+    "src/**/*.test.tsx",
+    "src/**/*.spec.tsx",
+    "src/**/*.test.js",
+    "src/**/*.spec.js",
+    "src/**/*.test.jsx",
+    "src/**/*.spec.jsx",
+    "src/**/*.d.ts"
+  ],
+  "references": [
+    {
+      "path": "./tsconfig.lib.json"
+    }
+  ]
+}

package/vite.config.ts

@@ -0,0 +1,80 @@
+/// <reference types='vitest' />
+import { defineConfig } from 'vite';
+import dts from 'vite-plugin-dts';
+import * as path from 'path';
+
+export default defineConfig({
+  root: __dirname,
+  cacheDir: '../../node_modules/.vite/packages/core',
+  resolve: {
+    alias: {
+      src: path.resolve(__dirname, 'src'),
+    },
+  },
+  plugins: [
+    dts({
+      entryRoot: 'src',
+      tsconfigPath: path.join(__dirname, 'tsconfig.lib.json'),
+    }),
+  ],
+  // Uncomment this if you are using workers.
+  // worker: {
+  //  plugins: [ nxViteTsPaths() ],
+  // },
+  // Configuration for building your library.
+  // See: https://vitejs.dev/guide/build.html#library-mode
+  build: {
+    outDir: './dist',
+    minify: 'esbuild',
+    emptyOutDir: true,
+    reportCompressedSize: true,
+    commonjsOptions: {
+      transformMixedEsModules: true,
+    },
+    lib: {
+      // Could also be a dictionary or array of multiple entry points.
+      entry: 'src/index.ts',
+      name: '@asgard-js/core',
+      fileName: 'index',
+      // Change this to the formats you want to support.
+      // Don't forget to update your package.json as well.
+      // formats: ['es', 'cjs', 'umd'],
+    },
+    rollupOptions: {
+      // External packages that should not be bundled into your library.
+      external: [],
+      output: [
+        {
+          format: 'es',
+          sourcemap: true,
+          dir: 'dist',
+          entryFileNames: 'index.mjs',
+        },
+        {
+          format: 'cjs',
+          sourcemap: true,
+          dir: 'dist',
+          entryFileNames: 'index.cjs',
+        },
+        {
+          format: 'umd',
+          name: '@asgard-js/core',
+          sourcemap: true,
+          dir: 'dist',
+          entryFileNames: 'index.js',
+        },
+      ],
+    },
+  },
+  test: {
+    watch: false,
+    globals: true,
+    environment: 'jsdom',
+    include: ['src/**/*.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}'],
+    reporters: ['default'],
+    coverage: {
+      reportsDirectory: './test-output/vitest/coverage',
+      provider: 'v8',
+    },
+  },
+});