@redhat-cloud-services/ai-client-common 0.3.0 → 0.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@redhat-cloud-services/ai-client-common",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "type": "commonjs",
   "main": "./src/index.js",
   "types": "./src/index.d.ts",
@@ -8,4 +8,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}

package/src/{index.ts → index.d.ts}

@@ -1 +1,2 @@
 export * from './lib/ai-client-common';
+//# sourceMappingURL=index.d.ts.map

package/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../packages/ai-client-common/src/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC"}

package/src/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./lib/ai-client-common"), exports);
+//# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../packages/ai-client-common/src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,yDAAuC"}

package/src/lib/ai-client-common.d.ts

@@ -0,0 +1,249 @@
+/**
+ * Generic interface for custom fetch implementation that must be injected into AI clients.
+ * Mirrors exactly the native browser fetch interface for maximum compatibility.
+ */
+export interface IFetchFunction {
+    (input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+}
+/**
+ * Base configuration interface for all AI clients
+ */
+export interface IBaseClientConfig<TChunk = unknown> {
+    /**
+     * The base URL for the API
+     */
+    baseUrl: string;
+    /**
+     * Custom fetch implementation for making HTTP requests
+     * Must include authentication headers (Bearer token) if needed
+     */
+    fetchFunction: IFetchFunction;
+    /**
+     * Default streaming handler for the client
+     * Used when sendMessage is called with stream=true but no streamingHandler provided
+     * Individual requests can override this by providing their own streamingHandler
+     */
+    defaultStreamingHandler?: IStreamingHandler<TChunk>;
+}
+/**
+ * Standard request options that can be passed to individual client methods
+ */
+export interface IRequestOptions {
+    /**
+     * Custom headers for this specific request
+     */
+    headers?: Record<string, string>;
+    /**
+     * AbortSignal to cancel the request
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Common interface that all AI clients must implement
+ * Provides a standardized way to interact with different AI services
+ */
+export interface IAIClient<AP extends Record<string, unknown> = Record<string, unknown>> {
+    /**
+     * Initialize the client and return the initial conversation ID
+     * This method is called once when the client is first used by a state manager
+     * @returns Promise that resolves to the initial conversation ID
+     */
+    init(): Promise<string>;
+    /**
+     * Send a message to the AI service
+     * @param conversationId - The conversation ID to send the message to
+     * @param message - The message content to send
+     * @param options - Optional configuration for the request
+     * @returns Promise that resolves to the AI's response
+     */
+    sendMessage<TChunk = unknown>(conversationId: string, message: string, options?: ISendMessageOptions<TChunk>): Promise<TChunk | IMessageResponse<AP> | void>;
+    /**
+     * Get the default streaming handler for this client (if any)
+     * @returns The default streaming handler or undefined if not configured
+     */
+    getDefaultStreamingHandler?<TChunk = unknown>(): IStreamingHandler<TChunk> | undefined;
+    /**
+     * Get the conversation history for a specific conversation
+     * @param conversationId - The conversation ID to retrieve history for
+     * @param options - Optional request configuration
+     * @returns Promise that resolves to the conversation history
+     */
+    getConversationHistory(conversationId: string, options?: IRequestOptions): Promise<IConversationHistoryResponse<AP>>;
+    /**
+     * Perform a health check on the AI service
+     * @param options - Optional request configuration
+     * @returns Promise that resolves to health status information
+     */
+    healthCheck(options?: IRequestOptions): Promise<unknown>;
+    /**
+     * Get the current status of the AI service
+     * @param options - Optional request configuration
+     * @returns Promise that resolves to service status information
+     */
+    getServiceStatus?(options?: IRequestOptions): Promise<unknown>;
+}
+/**
+ * Base error class for all AI client errors
+ */
+export declare class AIClientError extends Error {
+    status: number;
+    statusText: string;
+    data?: unknown | undefined;
+    constructor(status: number, statusText: string, message: string, data?: unknown | undefined);
+}
+/**
+ * Validation error class for 422 responses
+ */
+export interface IValidationError {
+    loc: (string | number)[];
+    msg: string;
+    type: string;
+}
+export declare class AIClientValidationError extends AIClientError {
+    validationErrors: IValidationError[];
+    constructor(validationErrors: IValidationError[]);
+}
+/**
+ * Common utility types used across AI clients
+ */
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+/**
+ * Standard API response wrapper that many AI services use
+ */
+export interface IAPIResponse<T = unknown> {
+    data?: T;
+    error?: string;
+    status?: number;
+}
+/**
+ * Generic streaming handler interface for AI clients that support streaming
+ */
+export interface IStreamingHandler<TChunk = unknown> {
+    /**
+     * Handle a single chunk of streaming data
+     */
+    onChunk(chunk: TChunk, afterChunk?: (chunk: TChunk) => void): void;
+    /**
+     * Called when the stream starts
+     */
+    onStart?(conversationId?: string, messageId?: string): void;
+    /**
+     * Called when the stream completes successfully
+     */
+    onComplete?(finalChunk: TChunk): void;
+    /**
+     * Called when an error occurs during streaming
+     */
+    onError?(error: Error): void;
+    /**
+     * Called when the stream is aborted
+     */
+    onAbort?(): void;
+}
+/**
+ * Streaming request options for clients that support streaming
+ */
+export interface IStreamingRequestOptions<TChunk = unknown> extends IRequestOptions {
+    /**
+     * The streaming handler to process the response
+     */
+    streamingHandler: IStreamingHandler<TChunk>;
+}
+/**
+ * Standard message response for non-streaming requests
+ */
+export interface IMessageResponse<AP extends Record<string, unknown> = Record<string, unknown>> {
+    /**
+     * Unique identifier for the message
+     */
+    messageId: string;
+    /**
+     * The response answer/text
+     */
+    answer: string;
+    /**
+     * Conversation identifier this message belongs to
+     */
+    conversationId: string;
+    /**
+     * Timestamp when the message was created
+     */
+    createdAt?: string;
+    /**
+     * Additional attributes specific to the AI client
+     */
+    additionalAttributes?: AP;
+}
+/**
+ * Source citation information for AI responses
+ */
+export interface IAnswerSource {
+    /**
+     * URL to the source content
+     */
+    link?: string | null;
+    /**
+     * Title of the source content
+     */
+    title?: string | null;
+    /**
+     * Relevance score of the source
+     */
+    score?: number | null;
+    /**
+     * Text snippet from the source
+     */
+    snippet?: string | null;
+}
+/**
+ * Single message in conversation history
+ */
+export interface IConversationHistoryMessage<T extends Record<string, unknown> = Record<string, unknown>> {
+    /**
+     * Unique identifier for the message
+     */
+    message_id: string;
+    /**
+     * When the message was received
+     */
+    received_at: string;
+    /**
+     * The user's input/question
+     */
+    input: string;
+    /**
+     * When the AI response was created
+     */
+    created_at: string;
+    /**
+     * The AI's answer
+     */
+    answer: string;
+    /**
+     * Sources used to generate the answer
+     */
+    sources: IAnswerSource[];
+    /**
+     * Additional data associated with the message
+     */
+    additionalData?: T;
+}
+/**
+ * Response type for conversation history requests
+ */
+export type IConversationHistoryResponse<T extends Record<string, unknown> = Record<string, unknown>> = IConversationHistoryMessage<T>[] | null;
+export interface IErrorMessageResponse {
+    error: any;
+}
+/**
+ * Options for sending messages, supporting both streaming and non-streaming modes
+ */
+export interface ISendMessageOptions<TChunk = unknown> extends IRequestOptions {
+    /**
+     * Whether to use streaming mode for the response
+     * When true, the client's default streaming handler will be used
+     */
+    stream?: boolean;
+    afterChunk?: (chunk: TChunk) => void;
+}
+//# sourceMappingURL=ai-client-common.d.ts.map

package/src/lib/ai-client-common.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-client-common.d.ts","sourceRoot":"","sources":["../../../../../packages/ai-client-common/src/lib/ai-client-common.ts"],"names":[],"mappings":"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"}

package/src/lib/ai-client-common.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AIClientValidationError = exports.AIClientError = void 0;
+/**
+ * Base error class for all AI client errors
+ */
+class AIClientError extends Error {
+    constructor(status, statusText, message, data) {
+        super(message);
+        this.status = status;
+        this.statusText = statusText;
+        this.data = data;
+        this.name = 'AIClientError';
+    }
+}
+exports.AIClientError = AIClientError;
+class AIClientValidationError extends AIClientError {
+    constructor(validationErrors) {
+        super(422, 'Validation Error', 'Request validation failed', validationErrors);
+        this.validationErrors = validationErrors;
+        this.name = 'AIClientValidationError';
+    }
+}
+exports.AIClientValidationError = AIClientValidationError;
+//# sourceMappingURL=ai-client-common.js.map

package/src/lib/ai-client-common.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-client-common.js","sourceRoot":"","sources":["../../../../../packages/ai-client-common/src/lib/ai-client-common.ts"],"names":[],"mappings":";;;AAuGA;;GAEG;AACH,MAAa,aAAc,SAAQ,KAAK;IACtC,YACS,MAAc,EACd,UAAkB,EACzB,OAAe,EACR,IAAc;QAErB,KAAK,CAAC,OAAO,CAAC,CAAC;QALR,WAAM,GAAN,MAAM,CAAQ;QACd,eAAU,GAAV,UAAU,CAAQ;QAElB,SAAI,GAAJ,IAAI,CAAU;QAGrB,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF;AAVD,sCAUC;AAWD,MAAa,uBAAwB,SAAQ,aAAa;IACxD,YAAmB,gBAAoC;QACrD,KAAK,CAAC,GAAG,EAAE,kBAAkB,EAAE,2BAA2B,EAAE,gBAAgB,CAAC,CAAC;QAD7D,qBAAgB,GAAhB,gBAAgB,CAAoB;QAErD,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;IACxC,CAAC;CACF;AALD,0DAKC"}

package/.eslintrc.json

@@ -1,32 +0,0 @@
-{
-  "extends": ["../../.eslintrc.json"],
-  "ignorePatterns": ["!**/*"],
-  "overrides": [
-    {
-      "files": ["*.ts", "*.tsx", "*.js", "*.jsx"],
-      "rules": {}
-    },
-    {
-      "files": ["*.ts", "*.tsx"],
-      "rules": {}
-    },
-    {
-      "files": ["*.js", "*.jsx"],
-      "rules": {}
-    },
-    {
-      "files": ["*.json"],
-      "parser": "jsonc-eslint-parser",
-      "rules": {
-        "@nx/dependency-checks": [
-          "error",
-          {
-            "ignoredFiles": [
-              "{projectRoot}/eslint.config.{js,cjs,mjs,ts,cts,mts}"
-            ]
-          }
-        ]
-      }
-    }
-  ]
-}

package/jest.config.ts

@@ -1,10 +0,0 @@
-export default {
-  displayName: 'ai-client-common',
-  preset: '../../jest.preset.js',
-  testEnvironment: 'node',
-  transform: {
-    '^.+\\.[tj]s$': ['ts-jest', { tsconfig: '<rootDir>/tsconfig.spec.json' }],
-  },
-  moduleFileExtensions: ['ts', 'js', 'html'],
-  coverageDirectory: '../../coverage/packages/ai-client-common',
-};

package/project.json

@@ -1,34 +0,0 @@
-{
-  "name": "ai-client-common",
-  "$schema": "../../node_modules/nx/schemas/project-schema.json",
-  "sourceRoot": "packages/ai-client-common/src",
-  "projectType": "library",
-  "release": {
-    "version": {
-      "manifestRootsToUpdate": ["dist/{projectRoot}"],
-      "currentVersionResolver": "git-tag",
-      "fallbackCurrentVersionResolver": "disk"
-    }
-  },
-  "tags": [],
-  "targets": {
-    "build": {
-      "executor": "@nx/js:tsc",
-      "outputs": ["{options.outputPath}"],
-      "options": {
-        "outputPath": "dist/packages/ai-client-common",
-        "main": "packages/ai-client-common/src/index.ts",
-        "tsConfig": "packages/ai-client-common/tsconfig.lib.json",
-        "assets": ["packages/ai-client-common/*.md"]
-      }
-    },
-    "test": {
-      "executor": "@nx/jest:jest",
-      "outputs": ["{workspaceRoot}/coverage/{projectRoot}"],
-      "options": {
-        "jestConfig": "packages/ai-client-common/jest.config.ts"
-      }
-    }
-
-  }
-}

package/src/lib/ai-client-common.spec.ts

@@ -1,460 +0,0 @@
-import {
-  AIClientError,
-  AIClientValidationError,
-  IValidationError,
-  IBaseClientConfig,
-  IRequestOptions,
-  IAIClient,
-  IStreamingHandler,
-  IStreamingRequestOptions,
-  IAPIResponse,
-  IFetchFunction,
-  HttpMethod,
-  IMessageResponse,
-  ISendMessageOptions,
-  IConversationHistoryResponse,
-} from './ai-client-common';
-
-
-type AdditionalAttributesTest = {
-  foo?: string;
-  bar?: number;
-}
-
-describe('ai-client-common', () => {
-  describe('AIClientError', () => {
-    it('should create error with all properties', () => {
-      const error = new AIClientError(404, 'Not Found', 'Resource not found', { id: '123' });
-      
-      expect(error.name).toBe('AIClientError');
-      expect(error.message).toBe('Resource not found');
-      expect(error.status).toBe(404);
-      expect(error.statusText).toBe('Not Found');
-      expect(error.data).toEqual({ id: '123' });
-      expect(error instanceof Error).toBe(true);
-    });
-
-    it('should create error without optional data', () => {
-      const error = new AIClientError(500, 'Internal Server Error', 'Something went wrong');
-      
-      expect(error.name).toBe('AIClientError');
-      expect(error.message).toBe('Something went wrong');
-      expect(error.status).toBe(500);
-      expect(error.statusText).toBe('Internal Server Error');
-      expect(error.data).toBeUndefined();
-    });
-
-    it('should be instanceof Error and AIClientError', () => {
-      const error = new AIClientError(400, 'Bad Request', 'Invalid input');
-      
-      expect(error instanceof Error).toBe(true);
-      expect(error instanceof AIClientError).toBe(true);
-    });
-  });
-
-  describe('AIClientValidationError', () => {
-    it('should create validation error with validation details', () => {
-      const validationErrors: IValidationError[] = [
-        { loc: ['field1'], msg: 'Field is required', type: 'missing' },
-        { loc: ['field2', 0], msg: 'Invalid type', type: 'type_error' }
-      ];
-      
-      const error = new AIClientValidationError(validationErrors);
-      
-      expect(error.name).toBe('AIClientValidationError');
-      expect(error.message).toBe('Request validation failed');
-      expect(error.status).toBe(422);
-      expect(error.statusText).toBe('Validation Error');
-      expect(error.data).toEqual(validationErrors);
-      expect(error.validationErrors).toEqual(validationErrors);
-    });
-
-    it('should be instanceof Error, AIClientError, and AIClientValidationError', () => {
-      const validationErrors: IValidationError[] = [
-        { loc: ['test'], msg: 'Test error', type: 'test' }
-      ];
-      const error = new AIClientValidationError(validationErrors);
-      
-      expect(error instanceof Error).toBe(true);
-      expect(error instanceof AIClientError).toBe(true);
-      expect(error instanceof AIClientValidationError).toBe(true);
-    });
-
-    it('should handle empty validation errors array', () => {
-      const error = new AIClientValidationError([]);
-      
-      expect(error.validationErrors).toEqual([]);
-      expect(error.data).toEqual([]);
-    });
-  });
-
-  describe('Type Definitions', () => {
-    it('should accept valid HttpMethod values', () => {
-      const methods: HttpMethod[] = ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'];
-      
-      methods.forEach(method => {
-        expect(typeof method).toBe('string');
-        expect(['GET', 'POST', 'PUT', 'DELETE', 'PATCH']).toContain(method);
-      });
-    });
-
-    it('should validate IValidationError structure', () => {
-      const validationError: IValidationError = {
-        loc: ['field', 'subfield'],
-        msg: 'Error message',
-        type: 'validation_error'
-      };
-      
-      expect(Array.isArray(validationError.loc)).toBe(true);
-      expect(typeof validationError.msg).toBe('string');
-      expect(typeof validationError.type).toBe('string');
-    });
-
-    it('should validate IAPIResponse structure', () => {
-      const response: IAPIResponse<{ test: string }> = {
-        data: { test: 'value' },
-        error: 'No error',
-        status: 200
-      };
-      
-      expect(response.data).toEqual({ test: 'value' });
-      expect(response.error).toBe('No error');
-      expect(response.status).toBe(200);
-    });
-
-    it('should validate IBaseClientConfig structure without default handler', () => {
-      const mockFetch: IFetchFunction = async (input, init) => {
-        void input; void init; // Mark parameters as used for linting
-        return new Response('{}', { status: 200 });
-      };
-      
-      const config: IBaseClientConfig = {
-        baseUrl: 'https://api.example.com',
-        fetchFunction: mockFetch
-      };
-      
-      expect(typeof config.baseUrl).toBe('string');
-      expect(typeof config.fetchFunction).toBe('function');
-      expect(config.defaultStreamingHandler).toBeUndefined();
-    });
-
-    it('should validate IBaseClientConfig structure with default handler', () => {
-      const mockFetch: IFetchFunction = async (input, init) => {
-        void input; void init; // Mark parameters as used for linting
-        return new Response('{}', { status: 200 });
-      };
-      
-      const mockHandler: IStreamingHandler<string> = {
-        onChunk: (chunk: string) => { void chunk; /* process */ }
-      };
-      
-      const config: IBaseClientConfig<string> = {
-        baseUrl: 'https://api.example.com',
-        fetchFunction: mockFetch,
-        defaultStreamingHandler: mockHandler
-      };
-      
-      expect(typeof config.baseUrl).toBe('string');
-      expect(typeof config.fetchFunction).toBe('function');
-      expect(typeof config.defaultStreamingHandler).toBe('object');
-      expect(typeof config.defaultStreamingHandler?.onChunk).toBe('function');
-    });
-
-    it('should validate IRequestOptions structure', () => {
-      const options: IRequestOptions = {
-        headers: { 'Authorization': 'Bearer token' },
-        signal: new AbortController().signal
-      };
-      
-      expect(typeof options.headers).toBe('object');
-      expect(options.signal instanceof AbortSignal).toBe(true);
-    });
-
-    it('should validate IMessageResponse structure', () => {
-      const messageResponse: IMessageResponse = {
-        messageId: 'msg-123',
-        answer: 'Hello world',
-        conversationId: 'conv-456',
-        createdAt: '2024-01-01T10:00:00Z',
-        additionalAttributes: {
-          model: 'gpt-4',
-          tokens: 50
-        }
-      };
-      
-      expect(typeof messageResponse.messageId).toBe('string');
-      expect(typeof messageResponse.answer).toBe('string');
-      expect(typeof messageResponse.conversationId).toBe('string');
-      expect(typeof messageResponse.createdAt).toBe('string');
-      expect(typeof messageResponse.additionalAttributes).toBe('object');
-    });
-
-    it('should validate ISendMessageOptions structure for non-streaming', () => {
-      const options: ISendMessageOptions = {
-        headers: { 'Content-Type': 'application/json' },
-        signal: new AbortController().signal,
-        stream: false
-      };
-      
-      expect(typeof options.headers).toBe('object');
-      expect(options.signal instanceof AbortSignal).toBe(true);
-      expect(options.stream).toBe(false);
-    });
-
-    it('should validate ISendMessageOptions structure for streaming', () => {
-      const options: ISendMessageOptions = {
-        headers: { 'Accept': 'text/stream' },
-        stream: true
-      };
-      
-      expect(typeof options.headers).toBe('object');
-      expect(options.stream).toBe(true);
-    });
-  });
-
-  describe('Interface Compliance', () => {
-    it('should allow proper IAIClient implementation', () => {
-      class TestClient implements IAIClient<Record<string, unknown>> {
-        async init(): Promise<string> {
-          return 'test-conversation-id';
-        }
-
-        async sendMessage(
-          conversationId: string, 
-          message: string, 
-          options?: ISendMessageOptions
-        ): Promise<IMessageResponse | void> {
-          void conversationId; void message; void options; // Mark parameters as used for linting
-          if (options?.stream) {
-            return; // Streaming mode returns void
-          }
-          return {
-            messageId: 'msg-123',
-            answer: 'Response content',
-            conversationId: 'conv-456'
-          };
-        }
-        
-        getDefaultStreamingHandler<TChunk = unknown>(): IStreamingHandler<TChunk> | undefined {
-          return undefined; // No default handler for this test client
-        }
-
-        async getConversationHistory<T extends AdditionalAttributesTest>(
-          conversationId: string, 
-          options?: IRequestOptions
-        ): Promise<IConversationHistoryResponse<T>> {
-          void conversationId; void options; // Mark parameters as used for linting
-          return [];
-        }
-        
-        async healthCheck(options?: IRequestOptions): Promise<unknown> {
-          void options; // Mark parameter as used for linting
-          return { status: 'healthy' };
-        }
-        
-        async getServiceStatus(options?: IRequestOptions): Promise<unknown> {
-          void options; // Mark parameter as used for linting
-          return { status: 'running' };
-        }
-      }
-      
-      const client = new TestClient();
-      expect(typeof client.sendMessage).toBe('function');
-      expect(typeof client.healthCheck).toBe('function');
-      expect(typeof client.getServiceStatus).toBe('function');
-    });
-
-    it('should handle sendMessage in non-streaming mode', async () => {
-      class TestClient implements IAIClient {
-        async init(): Promise<string> {
-          return 'test-conversation-id';
-        }
-
-        async sendMessage(
-          conversationId: string, 
-          message: string, 
-          options?: ISendMessageOptions
-        ): Promise<IMessageResponse | void> {
-          void options; // Mark parameter as used for linting
-          return {
-            messageId: 'msg-123',
-            answer: `Response to: ${message}`,
-            conversationId
-          };
-        }
-        
-        getDefaultStreamingHandler<TChunk = unknown>(): IStreamingHandler<TChunk> | undefined {
-          return undefined;
-        }
-
-        async getConversationHistory<T extends AdditionalAttributesTest>(
-          conversationId: string, 
-          options?: IRequestOptions
-        ): Promise<IConversationHistoryResponse<T>> {
-          void conversationId; void options; // Mark parameters as used for linting
-          return [];
-        }
-        
-        async healthCheck(): Promise<unknown> {
-          return { status: 'healthy' };
-        }
-      }
-      
-      const client = new TestClient();
-      const response = await client.sendMessage('conv-123', 'Hello AI');
-      
-      expect(response).toBeDefined();
-      if (response) {
-        expect(response.messageId).toBe('msg-123');
-        expect(response.answer).toBe('Response to: Hello AI');
-        expect(response.conversationId).toBe('conv-123');
-      }
-    });
-
-    it('should handle sendMessage in streaming mode', async () => {
-      let chunks: string[] = [];
-      
-      const mockHandler: IStreamingHandler<string> = {
-        onChunk: (chunk: string) => { chunks.push(chunk); },
-        onStart: () => { chunks = []; },
-        onComplete: () => { /* complete */ }
-      };
-      
-      class TestClient implements IAIClient {
-        private defaultHandler: IStreamingHandler<string> = mockHandler;
-
-        async init(): Promise<string> {
-          return 'test-conversation-id';
-        }
-        
-        async sendMessage(
-          conversationId: string, 
-          message: string, 
-          options?: ISendMessageOptions
-        ): Promise<IMessageResponse | void> {
-          if (options?.stream && this.defaultHandler) {
-            // Simulate streaming response using default handler
-            this.defaultHandler.onStart?.(conversationId, 'msg-456');
-            this.defaultHandler.onChunk('Hello');
-            this.defaultHandler.onChunk(' world');
-            this.defaultHandler.onComplete?.('Hello world');
-            return; // Streaming returns void
-          }
-          return {
-            messageId: 'msg-456',
-            answer: 'Non-streaming response',
-            conversationId
-          };
-        }
-        
-        getDefaultStreamingHandler<TChunk = unknown>(): IStreamingHandler<TChunk> | undefined {
-          return this.defaultHandler as IStreamingHandler<TChunk>;
-        }
-
-        async getConversationHistory<T extends AdditionalAttributesTest>(
-          conversationId: string, 
-          options?: IRequestOptions
-        ): Promise<IConversationHistoryResponse<T>> {
-          void conversationId; void options; // Mark parameters as used for linting
-          return [];
-        }
-        
-        async healthCheck(): Promise<unknown> {
-          return { status: 'healthy' };
-        }
-      }
-      
-      const client = new TestClient();
-      
-      const response = await client.sendMessage('conv-123', 'Hello AI', {
-        stream: true
-      });
-      
-      expect(response).toBeUndefined(); // Streaming returns void
-      expect(chunks).toEqual(['Hello', ' world']);
-    });
-
-    // TODO: Add integration tests for default streaming handler functionality
-    // Complex TypeScript generics make testing challenging - will be covered in real implementations
-
-    it('should allow proper IStreamingHandler implementation', () => {
-      class TestStreamingHandler implements IStreamingHandler<string> {
-        onChunk(chunk: string): void {
-          void chunk; // Mark parameter as used for linting
-          // Process chunk
-        }
-        
-        onStart(conversationId?: string, messageId?: string): void {
-          void conversationId; void messageId; // Mark parameters as used for linting
-          // Handle start
-        }
-        
-        onComplete(finalChunk: string): void {
-          void finalChunk; // Mark parameter as used for linting
-          // Handle completion
-        }
-        
-        onError(error: Error): void {
-          void error; // Mark parameter as used for linting
-          // Handle error
-        }
-        
-        onAbort(): void {
-          // Handle abort
-        }
-      }
-      
-      const handler = new TestStreamingHandler();
-      expect(typeof handler.onChunk).toBe('function');
-      expect(typeof handler.onStart).toBe('function');
-      expect(typeof handler.onComplete).toBe('function');
-      expect(typeof handler.onError).toBe('function');
-      expect(typeof handler.onAbort).toBe('function');
-    });
-
-    it('should validate IStreamingRequestOptions structure', () => {
-      const mockHandler: IStreamingHandler<string> = {
-        onChunk: (chunk: string) => { void chunk; /* process */ }
-      };
-      
-      const options: IStreamingRequestOptions<string> = {
-        headers: { 'Accept': 'text/stream' },
-        signal: new AbortController().signal,
-        streamingHandler: mockHandler
-      };
-      
-      expect(typeof options.headers).toBe('object');
-      expect(options.signal instanceof AbortSignal).toBe(true);
-      expect(typeof options.streamingHandler).toBe('object');
-      expect(typeof options.streamingHandler.onChunk).toBe('function');
-    });
-  });
-
-  describe('IFetchFunction Interface', () => {
-    it('should match native fetch signature', async () => {
-      const mockFetch: IFetchFunction = async (input, init) => {
-        void input; void init; // Mark parameters as used for linting
-        return new Response('{"success": true}', { 
-          status: 200,
-          headers: { 'Content-Type': 'application/json' }
-        });
-      };
-      
-      // Test with URL string
-      const response1 = await mockFetch('https://api.example.com/test');
-      expect(response1.status).toBe(200);
-      
-      // Test with Request object
-      const request = new Request('https://api.example.com/test', { method: 'POST' });
-      const response2 = await mockFetch(request);
-      expect(response2.status).toBe(200);
-      
-      // Test with RequestInit options
-      const response3 = await mockFetch('https://api.example.com/test', {
-        method: 'PUT',
-        headers: { 'Content-Type': 'application/json' }
-      });
-      expect(response3.status).toBe(200);
-    });
-  });
-});

package/src/lib/ai-client-common.ts

@@ -1,301 +0,0 @@
-/**
- * Generic interface for custom fetch implementation that must be injected into AI clients.
- * Mirrors exactly the native browser fetch interface for maximum compatibility.
- */
-export interface IFetchFunction {
-  (input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
-}
-
-/**
- * Base configuration interface for all AI clients
- */
-export interface IBaseClientConfig<TChunk = unknown> {
-  /**
-   * The base URL for the API
-   */
-  baseUrl: string;
-
-  /**
-   * Custom fetch implementation for making HTTP requests
-   * Must include authentication headers (Bearer token) if needed
-   */
-  fetchFunction: IFetchFunction;
-
-  /**
-   * Default streaming handler for the client
-   * Used when sendMessage is called with stream=true but no streamingHandler provided
-   * Individual requests can override this by providing their own streamingHandler
-   */
-  defaultStreamingHandler?: IStreamingHandler<TChunk>;
-}
-
-/**
- * Standard request options that can be passed to individual client methods
- */
-export interface IRequestOptions {
-  /**
-   * Custom headers for this specific request
-   */
-  headers?: Record<string, string>;
-
-  /**
-   * AbortSignal to cancel the request
-   */
-  signal?: AbortSignal;
-}
-
-/**
- * Common interface that all AI clients must implement
- * Provides a standardized way to interact with different AI services
- */
-export interface IAIClient<AP extends Record<string, unknown> = Record<string, unknown>> {
-  /**
-   * Initialize the client and return the initial conversation ID
-   * This method is called once when the client is first used by a state manager
-   * @returns Promise that resolves to the initial conversation ID
-   */
-  init(): Promise<string>;
-
-  /**
-   * Send a message to the AI service
-   * @param conversationId - The conversation ID to send the message to
-   * @param message - The message content to send
-   * @param options - Optional configuration for the request
-   * @returns Promise that resolves to the AI's response
-   */
-  sendMessage<TChunk = unknown>(
-    conversationId: string, 
-    message: string, 
-    options?: ISendMessageOptions<TChunk>
-  ): Promise<TChunk | IMessageResponse<AP> | void>;
-
-  /**
-   * Get the default streaming handler for this client (if any)
-   * @returns The default streaming handler or undefined if not configured
-   */
-  getDefaultStreamingHandler?<TChunk = unknown>(): IStreamingHandler<TChunk> | undefined;
-
-  /**
-   * Get the conversation history for a specific conversation
-   * @param conversationId - The conversation ID to retrieve history for
-   * @param options - Optional request configuration
-   * @returns Promise that resolves to the conversation history
-   */
-  getConversationHistory(
-    conversationId: string, 
-    options?: IRequestOptions
-  ): Promise<IConversationHistoryResponse<AP>>;
-
-  /** 
-   * Perform a health check on the AI service
-   * @param options - Optional request configuration
-   * @returns Promise that resolves to health status information
-   */
-  healthCheck(options?: IRequestOptions): Promise<unknown>;
-
-  /**
-   * Get the current status of the AI service
-   * @param options - Optional request configuration  
-   * @returns Promise that resolves to service status information
-   */
-  getServiceStatus?(options?: IRequestOptions): Promise<unknown>;
-}
-
-/**
- * Base error class for all AI client errors
- */
-export class AIClientError extends Error {
-  constructor(
-    public status: number,
-    public statusText: string,
-    message: string,
-    public data?: unknown
-  ) {
-    super(message);
-    this.name = 'AIClientError';
-  }
-}
-
-/**
- * Validation error class for 422 responses
- */
-export interface IValidationError {
-  loc: (string | number)[];
-  msg: string;
-  type: string;
-}
-
-export class AIClientValidationError extends AIClientError {
-  constructor(public validationErrors: IValidationError[]) {
-    super(422, 'Validation Error', 'Request validation failed', validationErrors);
-    this.name = 'AIClientValidationError';
-  }
-}
-
-/**
- * Common utility types used across AI clients
- */
-export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
-
-/**
- * Standard API response wrapper that many AI services use
- */
-export interface IAPIResponse<T = unknown> {
-  data?: T;
-  error?: string;
-  status?: number;
-}
-
-/**
- * Generic streaming handler interface for AI clients that support streaming
- */
-export interface IStreamingHandler<TChunk = unknown> {
-  /**
-   * Handle a single chunk of streaming data
-   */
-  onChunk(chunk: TChunk, afterChunk?: (chunk: TChunk) => void): void;
-
-  /**
-   * Called when the stream starts
-   */
-  onStart?(conversationId?: string, messageId?: string): void;
-
-  /**
-   * Called when the stream completes successfully
-   */
-  onComplete?(finalChunk: TChunk): void;
-
-  /**
-   * Called when an error occurs during streaming
-   */
-  onError?(error: Error): void;
-
-  /**
-   * Called when the stream is aborted
-   */
-  onAbort?(): void;
-}
-
-/**
- * Streaming request options for clients that support streaming
- */
-export interface IStreamingRequestOptions<TChunk = unknown> extends IRequestOptions {
-  /**
-   * The streaming handler to process the response
-   */
-  streamingHandler: IStreamingHandler<TChunk>;
-}
-
-/**
- * Standard message response for non-streaming requests
- */
-export interface IMessageResponse<AP extends Record<string, unknown> = Record<string, unknown>> {
-  /**
-   * Unique identifier for the message
-   */
-  messageId: string;
-  
-  /**
-   * The response answer/text
-   */
-  answer: string;
-  
-  /**
-   * Conversation identifier this message belongs to
-   */
-  conversationId: string;
-  
-  /**
-   * Timestamp when the message was created
-   */
-  createdAt?: string;
-  /**
-   * Additional attributes specific to the AI client
-   */
-  additionalAttributes?: AP;
-}
-
-/**
- * Source citation information for AI responses
- */
-export interface IAnswerSource {
-  /**
-   * URL to the source content
-   */
-  link?: string | null;
-  
-  /**
-   * Title of the source content
-   */
-  title?: string | null;
-  
-  /**
-   * Relevance score of the source
-   */
-  score?: number | null;
-  
-  /**
-   * Text snippet from the source
-   */
-  snippet?: string | null;
-}
-
-/**
- * Single message in conversation history
- */
-export interface IConversationHistoryMessage<T extends Record<string, unknown> = Record<string, unknown>> {
-  /**
-   * Unique identifier for the message
-   */
-  message_id: string;
-  
-  /**
-   * When the message was received
-   */
-  received_at: string;
-  
-  /**
-   * The user's input/question
-   */
-  input: string;
-  
-  /**
-   * When the AI response was created
-   */
-  created_at: string;
-  
-  /**
-   * The AI's answer
-   */
-  answer: string;
-  
-  /**
-   * Sources used to generate the answer
-   */
-  sources: IAnswerSource[];
-  /**
-   * Additional data associated with the message
-   */
-  additionalData?: T;
-}
-
-/**
- * Response type for conversation history requests
- */
-export type IConversationHistoryResponse<T extends Record<string, unknown> = Record<string, unknown>> = IConversationHistoryMessage<T>[] | null;
-
-export interface IErrorMessageResponse {
-  error: any;
-}
-
-/**
- * Options for sending messages, supporting both streaming and non-streaming modes
- */
-export interface ISendMessageOptions<TChunk = unknown> extends IRequestOptions {
-  /**
-   * Whether to use streaming mode for the response
-   * When true, the client's default streaming handler will be used
-   */
-  stream?: boolean;
-  afterChunk?: (chunk: TChunk) => void;
-}

package/tsconfig.json

@@ -1,23 +0,0 @@
-{
-  "extends": "../../tsconfig.json",
-  "compilerOptions": {
-    "module": "commonjs",
-    "forceConsistentCasingInFileNames": true,
-    "strict": true,
-    "importHelpers": false,
-    "noImplicitOverride": true,
-    "noImplicitReturns": true,
-    "noFallthroughCasesInSwitch": true,
-    "noPropertyAccessFromIndexSignature": true
-  },
-  "files": [],
-  "include": [],
-  "references": [
-    {
-      "path": "./tsconfig.lib.json"
-    },
-    {
-      "path": "./tsconfig.spec.json"
-    }
-  ]
-}

package/tsconfig.lib.json

@@ -1,12 +0,0 @@
-{
-  "extends": "./tsconfig.json",
-  "compilerOptions": {
-    "outDir": "../../dist/out-tsc",
-    "declaration": true,
-    "declarationMap": true,
-    "module": "commonjs",
-    "types": ["node"]
-  },
-  "include": ["src/**/*.ts"],
-  "exclude": ["jest.config.ts", "src/**/*.spec.ts", "src/**/*.test.ts"]
-}

package/tsconfig.spec.json

@@ -1,15 +0,0 @@
-{
-  "extends": "./tsconfig.json",
-  "compilerOptions": {
-    "outDir": "../../dist/out-tsc",
-    "module": "commonjs",
-    "moduleResolution": "node10",
-    "types": ["jest", "node"]
-  },
-  "include": [
-    "jest.config.ts",
-    "src/**/*.test.ts",
-    "src/**/*.spec.ts",
-    "src/**/*.d.ts"
-  ]
-}