@robota-sdk/agent-provider 3.0.0-beta.64

package/src/openai/loggers/console-payload-logger.ts

@@ -0,0 +1,94 @@
+import type { IPayloadLogger, IPayloadLoggerOptions } from '../interfaces/payload-logger';
+import type { IOpenAILogData } from '../types/api-types';
+import { SilentLogger, type ILogger } from '@robota-sdk/agent-core';
+import { sanitizeOpenAILogData } from './sanitize-openai-log-data';
+
+/**
+ * Console-based payload logger for browser environments
+ *
+ * This logger outputs API request/response payloads to the browser console
+ * using structured logging. It's designed specifically for browser environments
+ * and development/debugging scenarios.
+ *
+ * @example
+ * ```typescript
+ * import { ConsolePayloadLogger } from '@robota-sdk/agent-provider/openai/loggers';
+ *
+ * const logger = new ConsolePayloadLogger({
+ *   enabled: true,
+ *   includeTimestamp: true
+ * });
+ *
+ * const provider = new OpenAIProvider({
+ *   client: openaiClient,
+ *   payloadLogger: logger
+ * });
+ * ```
+ */
+export class ConsolePayloadLogger implements IPayloadLogger {
+  private readonly enabled: boolean;
+  private readonly includeTimestamp: boolean;
+  private readonly logger: ILogger;
+
+  constructor(options: IPayloadLoggerOptions = {}) {
+    this.enabled = options.enabled ?? true;
+    this.includeTimestamp = options.includeTimestamp ?? true;
+    this.logger = options.logger || SilentLogger;
+  }
+
+  /**
+   * Check if logging is enabled
+   */
+  isEnabled(): boolean {
+    return this.enabled;
+  }
+
+  /**
+   * Log API payload to browser console
+   * @param payload - The API request payload
+   * @param type - Type of request ('chat' or 'stream')
+   */
+  async logPayload(payload: IOpenAILogData, type: 'chat' | 'stream' = 'chat'): Promise<void> {
+    if (!this.enabled) {
+      return;
+    }
+
+    try {
+      const sanitizedPayload = sanitizeOpenAILogData(payload);
+
+      // Use structured console logging for better browser developer tools integration
+      const title = `[OpenAI ${type.toUpperCase()}] API Payload`;
+      const timeInfo = this.includeTimestamp ? ` (${sanitizedPayload.timestamp})` : '';
+
+      // Group related log entries for better organization
+      this.logger.group?.(`${title}${timeInfo}`);
+
+      // Log different aspects with appropriate console methods
+      this.logger.info('📋 Request Details:', {
+        model: payload.model,
+        messagesCount: payload.messagesCount,
+        hasTools: payload.hasTools,
+        temperature: payload.temperature,
+        maxTokens: payload.maxTokens,
+      });
+
+      this.logger.debug('🔍 Full Payload:', { type, provider: 'openai', ...sanitizedPayload });
+
+      this.logger.groupEnd?.();
+    } catch (error) {
+      // Don't throw errors - just log them and continue
+      // This ensures that API logging failures don't break the main functionality
+      this.logger.error(
+        '[ConsolePayloadLogger] Failed to log payload:',
+        error instanceof Error ? error.message : 'Unknown error',
+      );
+    }
+  }
+
+  /**
+   * Sanitize payload to remove sensitive information
+   * @param payload - Raw payload object
+   * @returns Sanitized payload
+   */
+  // Sanitization intentionally lives in ./sanitize-openai-log-data.ts (SSOT utility).
+}

package/src/openai/loggers/console.ts

@@ -0,0 +1,9 @@
+/**
+ * Browser console-based payload logger
+ *
+ * @example
+ * ```typescript
+ * import { ConsolePayloadLogger } from '@robota-sdk/agent-provider/openai/loggers';
+ * ```
+ */
+export { ConsolePayloadLogger } from './console-payload-logger';

package/src/openai/loggers/file-payload-logger.test.ts

@@ -0,0 +1,238 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import * as fs from 'fs';
+import { FilePayloadLogger } from './file-payload-logger';
+import type { ILogger } from '@robota-sdk/agent-core';
+import type { IOpenAILogData } from '../types/api-types';
+
+// Mock fs module
+vi.mock('fs', () => {
+  return {
+    existsSync: vi.fn(),
+    mkdirSync: vi.fn(),
+    promises: {
+      writeFile: vi.fn(),
+    },
+  };
+});
+
+function createMockLogger(): ILogger {
+  return {
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    debug: vi.fn(),
+    log: vi.fn(),
+  };
+}
+
+function createSamplePayload(): IOpenAILogData {
+  return {
+    model: 'gpt-4',
+    messagesCount: 3,
+    hasTools: true,
+    temperature: 0.7,
+    maxTokens: 1000,
+    timestamp: '2026-01-01T00:00:00.000Z',
+  };
+}
+
+describe('FilePayloadLogger', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    // Default: directory exists
+    vi.mocked(fs.existsSync).mockReturnValue(true);
+    vi.mocked(fs.promises.writeFile).mockResolvedValue(undefined);
+  });
+
+  describe('constructor', () => {
+    it('should create logger with required logDir option', () => {
+      const logger = new FilePayloadLogger({ logDir: '/tmp/logs' });
+      expect(logger.isEnabled()).toBe(true);
+    });
+
+    it('should default to enabled when not specified', () => {
+      const logger = new FilePayloadLogger({ logDir: '/tmp/logs' });
+      expect(logger.isEnabled()).toBe(true);
+    });
+
+    it('should respect enabled false option', () => {
+      const logger = new FilePayloadLogger({ logDir: '/tmp/logs', enabled: false });
+      expect(logger.isEnabled()).toBe(false);
+    });
+
+    it('should create log directory if it does not exist and enabled', () => {
+      vi.mocked(fs.existsSync).mockReturnValue(false);
+      new FilePayloadLogger({ logDir: '/tmp/logs' });
+
+      expect(fs.mkdirSync).toHaveBeenCalledWith('/tmp/logs', { recursive: true });
+    });
+
+    it('should not create log directory when disabled', () => {
+      vi.mocked(fs.existsSync).mockReturnValue(false);
+      new FilePayloadLogger({ logDir: '/tmp/logs', enabled: false });
+
+      expect(fs.mkdirSync).not.toHaveBeenCalled();
+    });
+
+    it('should not create log directory if it already exists', () => {
+      vi.mocked(fs.existsSync).mockReturnValue(true);
+      new FilePayloadLogger({ logDir: '/tmp/logs' });
+
+      expect(fs.mkdirSync).not.toHaveBeenCalled();
+    });
+
+    it('should handle directory creation error gracefully', () => {
+      const mockLogger = createMockLogger();
+      vi.mocked(fs.existsSync).mockReturnValue(false);
+      vi.mocked(fs.mkdirSync).mockImplementation(() => {
+        throw new Error('Permission denied');
+      });
+
+      // Should not throw
+      const logger = new FilePayloadLogger({ logDir: '/root/logs', logger: mockLogger });
+      expect(logger.isEnabled()).toBe(true);
+      expect(mockLogger.error).toHaveBeenCalledWith(
+        expect.stringContaining('[FilePayloadLogger]'),
+        expect.objectContaining({ error: 'Permission denied' }),
+      );
+    });
+  });
+
+  describe('isEnabled', () => {
+    it('should return true when enabled', () => {
+      const logger = new FilePayloadLogger({ logDir: '/tmp/logs', enabled: true });
+      expect(logger.isEnabled()).toBe(true);
+    });
+
+    it('should return false when disabled', () => {
+      const logger = new FilePayloadLogger({ logDir: '/tmp/logs', enabled: false });
+      expect(logger.isEnabled()).toBe(false);
+    });
+  });
+
+  describe('logPayload', () => {
+    it('should write payload to a JSON file', async () => {
+      const logger = new FilePayloadLogger({ logDir: '/tmp/logs' });
+      const payload = createSamplePayload();
+
+      await logger.logPayload(payload, 'chat');
+
+      expect(fs.promises.writeFile).toHaveBeenCalledWith(
+        expect.stringContaining('/tmp/logs/openai-chat-'),
+        expect.any(String),
+        'utf8',
+      );
+    });
+
+    it('should write valid JSON content', async () => {
+      const logger = new FilePayloadLogger({ logDir: '/tmp/logs' });
+      const payload = createSamplePayload();
+
+      await logger.logPayload(payload, 'chat');
+
+      const writeCall = vi.mocked(fs.promises.writeFile).mock.calls[0];
+      const content = writeCall[1] as string;
+      const parsed = JSON.parse(content);
+
+      expect(parsed.type).toBe('chat');
+      expect(parsed.provider).toBe('openai');
+      expect(parsed.payload.model).toBe('gpt-4');
+      expect(parsed.timestamp).toBeDefined();
+    });
+
+    it('should use stream type in filename when type is stream', async () => {
+      const logger = new FilePayloadLogger({ logDir: '/tmp/logs' });
+      const payload = createSamplePayload();
+
+      await logger.logPayload(payload, 'stream');
+
+      const writeCall = vi.mocked(fs.promises.writeFile).mock.calls[0];
+      const filepath = writeCall[0] as string;
+      expect(filepath).toContain('openai-stream-');
+    });
+
+    it('should include timestamp in filename when includeTimestamp is true', async () => {
+      const logger = new FilePayloadLogger({
+        logDir: '/tmp/logs',
+        includeTimestamp: true,
+      });
+      const payload = createSamplePayload();
+
+      await logger.logPayload(payload, 'chat');
+
+      const writeCall = vi.mocked(fs.promises.writeFile).mock.calls[0];
+      const filepath = writeCall[0] as string;
+      // Timestamp format replaces : and . with -
+      expect(filepath).toMatch(/openai-chat-\d{4}-\d{2}-\d{2}T/);
+    });
+
+    it('should use Date.now() in filename when includeTimestamp is false', async () => {
+      const logger = new FilePayloadLogger({
+        logDir: '/tmp/logs',
+        includeTimestamp: false,
+      });
+      const payload = createSamplePayload();
+
+      await logger.logPayload(payload, 'chat');
+
+      const writeCall = vi.mocked(fs.promises.writeFile).mock.calls[0];
+      const filepath = writeCall[0] as string;
+      // Should contain a numeric timestamp
+      expect(filepath).toMatch(/openai-chat-\d+\.json$/);
+    });
+
+    it('should skip logging when disabled', async () => {
+      const logger = new FilePayloadLogger({ logDir: '/tmp/logs', enabled: false });
+      const payload = createSamplePayload();
+
+      await logger.logPayload(payload, 'chat');
+
+      expect(fs.promises.writeFile).not.toHaveBeenCalled();
+    });
+
+    it('should not throw on write error and log the error', async () => {
+      const mockLogger = createMockLogger();
+      vi.mocked(fs.promises.writeFile).mockRejectedValue(new Error('Disk full'));
+
+      const logger = new FilePayloadLogger({ logDir: '/tmp/logs', logger: mockLogger });
+      const payload = createSamplePayload();
+
+      // Should not throw
+      await expect(logger.logPayload(payload, 'chat')).resolves.toBeUndefined();
+      expect(mockLogger.error).toHaveBeenCalledWith(
+        expect.stringContaining('[FilePayloadLogger]'),
+        expect.objectContaining({ error: 'Disk full' }),
+      );
+    });
+
+    it('should sanitize payload before writing', async () => {
+      const logger = new FilePayloadLogger({ logDir: '/tmp/logs' });
+      const payload = createSamplePayload();
+
+      await logger.logPayload(payload, 'chat');
+
+      const writeCall = vi.mocked(fs.promises.writeFile).mock.calls[0];
+      const content = writeCall[1] as string;
+      const parsed = JSON.parse(content);
+
+      // Verify the payload is a sanitized copy
+      expect(parsed.payload).toEqual(
+        expect.objectContaining({
+          model: 'gpt-4',
+          messagesCount: 3,
+        }),
+      );
+    });
+
+    it('should default type to chat', async () => {
+      const logger = new FilePayloadLogger({ logDir: '/tmp/logs' });
+      const payload = createSamplePayload();
+
+      await logger.logPayload(payload, 'chat');
+
+      const writeCall = vi.mocked(fs.promises.writeFile).mock.calls[0];
+      const filepath = writeCall[0] as string;
+      expect(filepath).toContain('openai-chat-');
+    });
+  });
+});

package/src/openai/loggers/file-payload-logger.ts

@@ -0,0 +1,112 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import type { IPayloadLogger } from '../interfaces/payload-logger';
+import type { IOpenAILogData } from '../types/api-types';
+import type { ILogger } from '@robota-sdk/agent-core';
+import { SilentLogger } from '@robota-sdk/agent-core';
+import { sanitizeOpenAILogData } from './sanitize-openai-log-data';
+
+/**
+ * File-based payload logger for Node.js environments
+ *
+ * This logger saves API request/response payloads to JSON files on disk.
+ * It's designed specifically for Node.js environments with filesystem access.
+ *
+ * @example
+ * ```typescript
+ * import { FilePayloadLogger } from '@robota-sdk/agent-provider/openai/loggers';
+ *
+ * const logger = new FilePayloadLogger({
+ *   logDir: './logs/api-payloads',
+ *   enabled: true,
+ *   includeTimestamp: true
+ * });
+ *
+ * const provider = new OpenAIProvider({
+ *   client: openaiClient,
+ *   payloadLogger: logger
+ * });
+ * ```
+ */
+export class FilePayloadLogger implements IPayloadLogger {
+  private readonly enabled: boolean;
+  private readonly logDir: string;
+  private readonly includeTimestamp: boolean;
+  private readonly logger: ILogger;
+
+  constructor(options: {
+    logDir: string;
+    enabled?: boolean;
+    includeTimestamp?: boolean;
+    logger?: ILogger;
+  }) {
+    this.enabled = options.enabled ?? true;
+    this.logDir = options.logDir;
+    this.includeTimestamp = options.includeTimestamp ?? true;
+    this.logger = options.logger || SilentLogger;
+
+    if (this.enabled) {
+      this.ensureLogDirectoryExists();
+    }
+  }
+
+  /**
+   * Check if logging is enabled
+   */
+  isEnabled(): boolean {
+    return this.enabled;
+  }
+
+  /**
+   * Log API payload to file
+   * @param payload - The API request payload
+   * @param type - Type of request ('chat' or 'stream')
+   */
+  async logPayload(payload: IOpenAILogData, type: 'chat' | 'stream' = 'chat'): Promise<void> {
+    if (!this.enabled) {
+      return;
+    }
+
+    try {
+      const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+      const filename = this.includeTimestamp
+        ? `openai-${type}-${timestamp}.json`
+        : `openai-${type}-${Date.now()}.json`;
+
+      const filepath = path.join(this.logDir, filename);
+
+      const logData = {
+        timestamp: new Date().toISOString(),
+        type,
+        provider: 'openai',
+        payload: sanitizeOpenAILogData(payload),
+      };
+
+      await fs.promises.writeFile(filepath, JSON.stringify(logData, null, 2), 'utf8');
+
+      // Payload saved successfully (silent operation)
+    } catch (error) {
+      // Don't throw errors - just log them and continue
+      // This ensures that API logging failures don't break the main functionality
+      this.logger.error('[FilePayloadLogger] Failed to save payload log:', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  /**
+   * Ensure log directory exists
+   */
+  private ensureLogDirectoryExists(): void {
+    try {
+      if (!fs.existsSync(this.logDir)) {
+        fs.mkdirSync(this.logDir, { recursive: true });
+      }
+    } catch (error) {
+      this.logger.error('[FilePayloadLogger] Failed to create log directory:', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+  // Sanitization intentionally lives in ./sanitize-openai-log-data.ts (SSOT utility).
+}

package/src/openai/loggers/file.ts

@@ -0,0 +1,9 @@
+/**
+ * Node.js file-based payload logger
+ *
+ * @example
+ * ```typescript
+ * import { FilePayloadLogger } from '@robota-sdk/agent-provider/openai/loggers';
+ * ```
+ */
+export { FilePayloadLogger } from './file-payload-logger';

package/src/openai/loggers/index.ts

@@ -0,0 +1,12 @@
+/**
+ * IPayloadLogger implementations for different environments
+ */
+
+// Interfaces
+export type { IPayloadLogger, IPayloadLoggerOptions } from '../interfaces/payload-logger';
+
+// Node.js implementation
+export { FilePayloadLogger } from './file-payload-logger';
+
+// Browser implementation
+export { ConsolePayloadLogger } from './console-payload-logger';

package/src/openai/loggers/sanitize-openai-log-data.test.ts

@@ -0,0 +1,89 @@
+import { describe, it, expect } from 'vitest';
+import { sanitizeOpenAILogData } from './sanitize-openai-log-data';
+import type { IOpenAILogData } from '../types/api-types';
+
+describe('sanitizeOpenAILogData', () => {
+  it('should return a deep copy of the payload', () => {
+    const payload: IOpenAILogData = {
+      model: 'gpt-4',
+      messagesCount: 3,
+      hasTools: true,
+      temperature: 0.7,
+      maxTokens: 1000,
+      timestamp: '2026-01-01T00:00:00.000Z',
+    };
+
+    const result = sanitizeOpenAILogData(payload);
+
+    expect(result).toEqual(payload);
+    expect(result).not.toBe(payload);
+  });
+
+  it('should not modify the original payload', () => {
+    const payload: IOpenAILogData = {
+      model: 'gpt-4',
+      messagesCount: 5,
+      hasTools: false,
+      timestamp: '2026-01-01T00:00:00.000Z',
+    };
+
+    const result = sanitizeOpenAILogData(payload);
+    result.model = 'gpt-3.5-turbo';
+    result.messagesCount = 999;
+
+    expect(payload.model).toBe('gpt-4');
+    expect(payload.messagesCount).toBe(5);
+  });
+
+  it('should preserve all fields including optional ones', () => {
+    const payload: IOpenAILogData = {
+      model: 'gpt-4o',
+      messagesCount: 1,
+      hasTools: true,
+      temperature: 0.5,
+      maxTokens: 500,
+      timestamp: '2026-03-10T12:00:00.000Z',
+      requestId: 'req-123',
+    };
+
+    const result = sanitizeOpenAILogData(payload);
+
+    expect(result.model).toBe('gpt-4o');
+    expect(result.messagesCount).toBe(1);
+    expect(result.hasTools).toBe(true);
+    expect(result.temperature).toBe(0.5);
+    expect(result.maxTokens).toBe(500);
+    expect(result.timestamp).toBe('2026-03-10T12:00:00.000Z');
+    expect(result.requestId).toBe('req-123');
+  });
+
+  it('should handle payload with undefined optional fields', () => {
+    const payload: IOpenAILogData = {
+      model: 'gpt-4',
+      messagesCount: 2,
+      hasTools: false,
+      timestamp: '2026-01-01T00:00:00.000Z',
+      temperature: undefined,
+      maxTokens: undefined,
+    };
+
+    const result = sanitizeOpenAILogData(payload);
+
+    // JSON.parse(JSON.stringify(...)) strips undefined fields
+    expect(result.model).toBe('gpt-4');
+    expect(result.messagesCount).toBe(2);
+    expect(result.hasTools).toBe(false);
+  });
+
+  it('should handle minimal payload', () => {
+    const payload: IOpenAILogData = {
+      model: 'gpt-3.5-turbo',
+      messagesCount: 0,
+      hasTools: false,
+      timestamp: '',
+    };
+
+    const result = sanitizeOpenAILogData(payload);
+    expect(result).toEqual(payload);
+  });
+});

package/src/openai/loggers/sanitize-openai-log-data.ts

@@ -0,0 +1,14 @@
+import type { IOpenAILogData } from '../types/api-types';
+
+/**
+ * Creates a defensive deep copy of OpenAI log data.
+ * SSOT utility shared by payload loggers.
+ */
+export function sanitizeOpenAILogData(payload: IOpenAILogData): IOpenAILogData {
+  // Create a deep copy to avoid modifying original
+  const sanitized = JSON.parse(JSON.stringify(payload)) as IOpenAILogData;
+
+  // Remove or mask sensitive data if needed.
+  // For now, we keep everything as OpenAI payloads don't contain API keys.
+  return sanitized;
+}

package/src/openai/message-converter.ts

@@ -0,0 +1,22 @@
+import type OpenAI from 'openai';
+import type { IToolSchema, TUniversalMessage } from '@robota-sdk/agent-core';
+import {
+  convertToOpenAICompatibleMessages,
+  convertToOpenAICompatibleTools,
+} from '../shared/openai-compatible/index.js';
+
+/**
+ * Convert TUniversalMessage array to OpenAI chat completion message format.
+ */
+export function convertToOpenAIMessages(
+  messages: TUniversalMessage[],
+): OpenAI.Chat.ChatCompletionMessageParam[] {
+  return convertToOpenAICompatibleMessages(messages);
+}
+
+/**
+ * Convert tool schemas to OpenAI function tool format.
+ */
+export function convertToOpenAITools(tools: IToolSchema[]): OpenAI.Chat.ChatCompletionTool[] {
+  return convertToOpenAICompatibleTools(tools);
+}