@ketd/gemini-cli-sdk 0.3.4 → 0.3.5

package/dist/index.d.ts

@@ -1,11 +1,118 @@
 import { EventEmitter } from 'events';
 import { EventEmitter as EventEmitter$1 } from 'node:events';
 
+/**
+ * Logger utility for Gemini CLI SDK
+ *
+ * Provides a configurable logging interface that can be customized by SDK consumers.
+ * By default, logs go to console. Users can provide their own logger implementation.
+ */
+/**
+ * Log level enumeration
+ */
+declare enum LogLevel {
+    DEBUG = 0,
+    INFO = 1,
+    WARN = 2,
+    ERROR = 3,
+    SILENT = 4
+}
+/**
+ * Logger interface that SDK consumers can implement
+ */
+interface Logger {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+/**
+ * Logger configuration options
+ */
+interface LoggerOptions {
+    /** Custom logger implementation */
+    logger?: Logger;
+    /** Minimum log level to output (default: INFO, or DEBUG if debug=true) */
+    level?: LogLevel;
+    /** Prefix for all log messages (e.g., '[GeminiSDK]') */
+    prefix?: string;
+}
+/**
+ * Silent logger that outputs nothing
+ */
+declare const silentLogger: Logger;
+/**
+ * SDK Logger class
+ *
+ * Wraps a logger implementation with level filtering and prefix support.
+ *
+ * @example
+ * ```typescript
+ * // Use default console logger
+ * const logger = new SDKLogger({ level: LogLevel.DEBUG });
+ *
+ * // Use custom logger
+ * const logger = new SDKLogger({
+ *   logger: myCustomLogger,
+ *   prefix: '[MyApp]',
+ * });
+ *
+ * logger.debug('Debug message');
+ * logger.error('Error occurred', { details: '...' });
+ * ```
+ */
+declare class SDKLogger implements Logger {
+    private logger;
+    private level;
+    private prefix;
+    constructor(options?: LoggerOptions);
+    /**
+     * Update logger configuration
+     */
+    configure(options: Partial<LoggerOptions>): void;
+    /**
+     * Set log level
+     */
+    setLevel(level: LogLevel): void;
+    /**
+     * Set custom logger implementation
+     */
+    setLogger(logger: Logger): void;
+    private formatMessage;
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+}
+/**
+ * Global SDK logger instance
+ *
+ * Used internally by SDK components. Can be configured by SDK consumers.
+ *
+ * @example
+ * ```typescript
+ * import { sdkLogger, LogLevel } from '@google/gemini-cli-sdk';
+ *
+ * // Configure global logger
+ * sdkLogger.setLevel(LogLevel.DEBUG);
+ * sdkLogger.setLogger(myCustomLogger);
+ * ```
+ */
+declare const sdkLogger: SDKLogger;
+/**
+ * Create a component-specific logger
+ *
+ * @param component - Component name for the prefix (e.g., 'GeminiStreamClient')
+ * @param options - Logger options
+ */
+declare function createLogger(component: string, options?: LoggerOptions): SDKLogger;
+
 /**
  * Type definitions for Gemini CLI SDK
  *
  * Based on Gemini CLI v0.21.0+ interface specification
  */
+
 /**
  * Gemini CLI configuration options
  */
@@ -95,6 +202,21 @@ interface GeminiOptions {
      * If not provided, falls back to Gemini CLI's built-in approval mechanism
      */
     onPermissionRequest?: (request: ToolPermissionRequest) => Promise<ToolPermissionDecision>;
+    /**
+     * Custom logger implementation
+     * If not provided, uses console with [GeminiSDK] prefix
+     * Set to silentLogger to disable all logging
+     *
+     * @example
+     * ```typescript
+     * import { silentLogger } from '@google/gemini-cli-sdk';
+     *
+     * const stream = query('Hello', {
+     *   logger: silentLogger, // Disable all logging
+     * });
+     * ```
+     */
+    logger?: Logger;
 }
 /**
  * Tool permission request
@@ -578,6 +700,21 @@ interface GeminiStreamOptions {
      * @example '/path/to/session-2025-01-01T12-00-abc123.json'
      */
     resumeSessionFilePath?: string;
+    /**
+     * Custom logger implementation
+     * If not provided, uses console with [GeminiStreamClient] prefix
+     * Set to silentLogger to disable all logging
+     *
+     * @example
+     * ```typescript
+     * import { silentLogger, GeminiStreamClient } from '@google/gemini-cli-sdk';
+     *
+     * const client = new GeminiStreamClient({
+     *   logger: silentLogger, // Disable all logging
+     * });
+     * ```
+     */
+    logger?: Logger;
 }
 
 /**
@@ -742,6 +879,7 @@ declare class GeminiStreamClient extends EventEmitter$1 {
     private initEvent;
     private initTimeout;
     private tempSettingsPath;
+    private logger;
     constructor(options: GeminiStreamOptions);
     /**
      * Start the Gemini CLI process
@@ -896,4 +1034,4 @@ declare function formatDuration(ms: number): string;
  */
 declare function formatTokens(tokens: number): string;
 
-export { type ControlInputMessage, type ControlSubtype, type ErrorEvent, ExitCode, GeminiClient, type GeminiOptions, GeminiSDKError, GeminiStreamClient, type GeminiStreamOptions, type HooksConfiguration, type InitEvent, type InterruptControl, type JsonInputMessage, JsonInputMessageType, type JsonStreamEvent, JsonStreamEventType, type MCPServerConfig, type MCPServersConfig, type MessageEvent, ProcessStatus, type QueryResult, type ResultEvent, type ResumeSessionControl, type StreamStats, type ThoughtEvent, type ToolPermissionDecision, type ToolPermissionRequest, type ToolResultEvent, type ToolUseEvent, type TruncateHistoryControl, type UserInputMessage, findGeminiCLI, formatDuration, formatTokens, getApiKey, query, validateApiKey, validateModel };
+export { type ControlInputMessage, type ControlSubtype, type ErrorEvent, ExitCode, GeminiClient, type GeminiOptions, GeminiSDKError, GeminiStreamClient, type GeminiStreamOptions, type HooksConfiguration, type InitEvent, type InterruptControl, type JsonInputMessage, JsonInputMessageType, type JsonStreamEvent, JsonStreamEventType, LogLevel, type Logger, type LoggerOptions, type MCPServerConfig, type MCPServersConfig, type MessageEvent, ProcessStatus, type QueryResult, type ResultEvent, type ResumeSessionControl, SDKLogger, type StreamStats, type ThoughtEvent, type ToolPermissionDecision, type ToolPermissionRequest, type ToolResultEvent, type ToolUseEvent, type TruncateHistoryControl, type UserInputMessage, createLogger, findGeminiCLI, formatDuration, formatTokens, getApiKey, query, sdkLogger, silentLogger, validateApiKey, validateModel };

package/dist/index.js

@@ -53,6 +53,101 @@ var JsonInputMessageType = /* @__PURE__ */ ((JsonInputMessageType2) => {
   return JsonInputMessageType2;
 })(JsonInputMessageType || {});
 
+// src/logger.ts
+var LogLevel = /* @__PURE__ */ ((LogLevel2) => {
+  LogLevel2[LogLevel2["DEBUG"] = 0] = "DEBUG";
+  LogLevel2[LogLevel2["INFO"] = 1] = "INFO";
+  LogLevel2[LogLevel2["WARN"] = 2] = "WARN";
+  LogLevel2[LogLevel2["ERROR"] = 3] = "ERROR";
+  LogLevel2[LogLevel2["SILENT"] = 4] = "SILENT";
+  return LogLevel2;
+})(LogLevel || {});
+var consoleLogger = {
+  debug: (message, ...args) => console.log(message, ...args),
+  info: (message, ...args) => console.log(message, ...args),
+  warn: (message, ...args) => console.warn(message, ...args),
+  error: (message, ...args) => console.error(message, ...args)
+};
+var silentLogger = {
+  debug: () => {
+  },
+  info: () => {
+  },
+  warn: () => {
+  },
+  error: () => {
+  }
+};
+var SDKLogger = class {
+  logger;
+  level;
+  prefix;
+  constructor(options = {}) {
+    this.logger = options.logger || consoleLogger;
+    this.level = options.level ?? 1 /* INFO */;
+    this.prefix = options.prefix || "";
+  }
+  /**
+   * Update logger configuration
+   */
+  configure(options) {
+    if (options.logger !== void 0) {
+      this.logger = options.logger;
+    }
+    if (options.level !== void 0) {
+      this.level = options.level;
+    }
+    if (options.prefix !== void 0) {
+      this.prefix = options.prefix;
+    }
+  }
+  /**
+   * Set log level
+   */
+  setLevel(level) {
+    this.level = level;
+  }
+  /**
+   * Set custom logger implementation
+   */
+  setLogger(logger) {
+    this.logger = logger;
+  }
+  formatMessage(message) {
+    return this.prefix ? `${this.prefix} ${message}` : message;
+  }
+  debug(message, ...args) {
+    if (this.level <= 0 /* DEBUG */) {
+      this.logger.debug(this.formatMessage(message), ...args);
+    }
+  }
+  info(message, ...args) {
+    if (this.level <= 1 /* INFO */) {
+      this.logger.info(this.formatMessage(message), ...args);
+    }
+  }
+  warn(message, ...args) {
+    if (this.level <= 2 /* WARN */) {
+      this.logger.warn(this.formatMessage(message), ...args);
+    }
+  }
+  error(message, ...args) {
+    if (this.level <= 3 /* ERROR */) {
+      this.logger.error(this.formatMessage(message), ...args);
+    }
+  }
+};
+var sdkLogger = new SDKLogger({
+  prefix: "[GeminiSDK]",
+  level: 1 /* INFO */
+});
+function createLogger(component, options = {}) {
+  return new SDKLogger({
+    ...options,
+    prefix: options.prefix || `[${component}]`
+  });
+}
+
 // src/query.ts
 function buildCliArgs(options, prompt) {
   const args = [];
@@ -84,7 +179,7 @@ function buildCliArgs(options, prompt) {
   args.push(prompt);
   return args;
 }
-function buildEnv(options) {
+function buildEnv(options, logger) {
   const env = {
     ...process.env,
     ...options.env
@@ -95,25 +190,19 @@ function buildEnv(options) {
     if (useVertexAI) {
       env.GOOGLE_API_KEY = options.apiKey;
       env.GOOGLE_GENAI_USE_VERTEXAI = "true";
-      if (options.debug) {
-        console.log("[SDK] Vertex AI mode: Setting GOOGLE_API_KEY:", options.apiKey.substring(0, 10) + "...");
-      }
+      logger.debug("Vertex AI mode: Setting GOOGLE_API_KEY:", options.apiKey.substring(0, 10) + "...");
     } else {
       env.GEMINI_API_KEY = options.apiKey;
-      if (options.debug) {
-        console.log("[SDK] Standard mode: Setting GEMINI_API_KEY:", options.apiKey.substring(0, 10) + "...");
-      }
+      logger.debug("Standard mode: Setting GEMINI_API_KEY:", options.apiKey.substring(0, 10) + "...");
     }
   }
   if (!useVertexAI && env.GOOGLE_API_KEY) {
     delete env.GOOGLE_API_KEY;
-    if (options.debug) {
-      console.log("[SDK] Removed GOOGLE_API_KEY from environment (not using Vertex AI)");
-    }
+    logger.debug("Removed GOOGLE_API_KEY from environment (not using Vertex AI)");
   }
   if (options.debug) {
     env.DEBUG = "1";
-    console.log("[SDK] Environment variables set:", {
+    logger.debug("Environment variables set:", {
       GEMINI_API_KEY: env.GEMINI_API_KEY ? "***" : void 0,
       GOOGLE_API_KEY: env.GOOGLE_API_KEY ? "***" : void 0,
       GOOGLE_GENAI_USE_VERTEXAI: env.GOOGLE_GENAI_USE_VERTEXAI,
@@ -123,6 +212,10 @@ function buildEnv(options) {
   return env;
 }
 async function* query(prompt, options) {
+  const logger = createLogger("GeminiSDK", {
+    logger: options.logger,
+    level: options.debug ? 0 /* DEBUG */ : 1 /* INFO */
+  });
   if (!options.pathToGeminiCLI) {
     throw new GeminiSDKError("pathToGeminiCLI is required");
   }
@@ -132,7 +225,7 @@ async function* query(prompt, options) {
     );
   }
   const args = buildCliArgs(options, prompt);
-  const env = buildEnv(options);
+  const env = buildEnv(options, logger);
   const cwd = options.cwd || process.cwd();
   const nodeExecutable = options.pathToNode || "node";
   let geminiProcess;
@@ -148,9 +241,7 @@ async function* query(prompt, options) {
   const stderrChunks = [];
   geminiProcess.stderr?.on("data", (data) => {
     stderrChunks.push(data);
-    if (options.debug) {
-      console.error("[Gemini CLI stderr]:", data.toString());
-    }
+    logger.error("stderr:", data.toString());
   });
   let timeoutId;
   if (options.timeout) {
@@ -170,10 +261,8 @@ async function* query(prompt, options) {
         hasYieldedEvents = true;
         yield event;
       } catch (parseError) {
-        if (options.debug) {
-          console.error("[Gemini SDK] Failed to parse JSON line:", line);
-          console.error("[Gemini SDK] Parse error:", parseError);
-        }
+        logger.debug("Failed to parse JSON line:", line);
+        logger.debug("Parse error:", parseError);
       }
     }
   } catch (error) {
@@ -376,6 +465,10 @@ var GeminiStreamClient = class extends EventEmitter {
   constructor(options) {
     super();
     this.options = options;
+    this.logger = createLogger("GeminiStreamClient", {
+      logger: options.logger,
+      level: options.debug ? 0 /* DEBUG */ : 1 /* INFO */
+    });
     if (!options.pathToGeminiCLI) {
       throw new GeminiSDKError("pathToGeminiCLI is required");
     }
@@ -390,6 +483,7 @@ var GeminiStreamClient = class extends EventEmitter {
   initEvent = null;
   initTimeout = null;
   tempSettingsPath = null;
+  logger;
   /**
    * Start the Gemini CLI process
    */
@@ -433,9 +527,11 @@ var GeminiStreamClient = class extends EventEmitter {
     }
     if (this.process.stderr) {
       this.process.stderr.on("data", (chunk) => {
-        if (this.options.debug) {
-          console.error("[GeminiStreamClient] stderr:", chunk.toString());
+        const message = chunk.toString().trim();
+        if (!message || message.includes("Flushing log events")) {
+          return;
         }
+        this.logger.error("stderr:", message);
       });
     }
     this.emit("started");
@@ -571,11 +667,9 @@ var GeminiStreamClient = class extends EventEmitter {
     if (this.tempSettingsPath) {
       try {
         fs.unlinkSync(this.tempSettingsPath);
-        if (this.options.debug) {
-          console.log("[GeminiStreamClient] Cleaned up temp settings:", this.tempSettingsPath);
-        }
+        this.logger.debug("Cleaned up temp settings:", this.tempSettingsPath);
       } catch (error) {
-        console.error("[GeminiStreamClient] Failed to clean up temp settings:", error);
+        this.logger.error("Failed to clean up temp settings:", error);
       }
       this.tempSettingsPath = null;
     }
@@ -620,9 +714,7 @@ var GeminiStreamClient = class extends EventEmitter {
     }
     if (!fs.existsSync(geminiConfigDir)) {
       fs.mkdirSync(geminiConfigDir, { recursive: true });
-      if (this.options.debug) {
-        console.log("[GeminiStreamClient] Created config directory:", geminiConfigDir);
-      }
+      this.logger.debug("Created config directory:", geminiConfigDir);
     }
     this.tempSettingsPath = path2.join(geminiConfigDir, "settings.json");
     const settings = {};
@@ -637,10 +729,8 @@ var GeminiStreamClient = class extends EventEmitter {
     }
     try {
       fs.writeFileSync(this.tempSettingsPath, JSON.stringify(settings, null, 2), "utf-8");
-      if (this.options.debug) {
-        console.log("[GeminiStreamClient] Wrote settings to:", this.tempSettingsPath);
-        console.log("[GeminiStreamClient] Settings content:", JSON.stringify(settings, null, 2));
-      }
+      this.logger.debug("Wrote settings to:", this.tempSettingsPath);
+      this.logger.debug("Settings content:", JSON.stringify(settings, null, 2));
     } catch (error) {
       throw new GeminiSDKError(`Failed to write settings file: ${error}`);
     }
@@ -658,9 +748,7 @@ var GeminiStreamClient = class extends EventEmitter {
     ];
     if (this.options.resumeSessionFilePath) {
       args.push("--resume-from-file", this.options.resumeSessionFilePath);
-      if (this.options.debug) {
-        console.log("[GeminiStreamClient] Resuming from session file:", this.options.resumeSessionFilePath);
-      }
+      this.logger.debug("Resuming from session file:", this.options.resumeSessionFilePath);
     }
     if (this.options.model) {
       args.push("--model", this.options.model);
@@ -683,28 +771,20 @@ var GeminiStreamClient = class extends EventEmitter {
     };
     if (this.options.apiKey) {
       const useVertexAI = this.options.env?.GOOGLE_GENAI_USE_VERTEXAI === "true";
-      if (this.options.debug) {
-        console.log("[GeminiStreamClient] buildEnv() - API Key prefix:", this.options.apiKey.substring(0, 3));
-        console.log("[GeminiStreamClient] buildEnv() - GOOGLE_GENAI_USE_VERTEXAI:", this.options.env?.GOOGLE_GENAI_USE_VERTEXAI);
-        console.log("[GeminiStreamClient] buildEnv() - useVertexAI:", useVertexAI);
-      }
+      this.logger.debug("buildEnv() - API Key prefix:", this.options.apiKey.substring(0, 3));
+      this.logger.debug("buildEnv() - GOOGLE_GENAI_USE_VERTEXAI:", this.options.env?.GOOGLE_GENAI_USE_VERTEXAI);
+      this.logger.debug("buildEnv() - useVertexAI:", useVertexAI);
       if (useVertexAI) {
         env.GOOGLE_API_KEY = this.options.apiKey;
-        if (this.options.debug) {
-          console.log("[GeminiStreamClient] buildEnv() - Setting GOOGLE_API_KEY for Vertex AI");
-        }
+        this.logger.debug("buildEnv() - Setting GOOGLE_API_KEY for Vertex AI");
       } else {
         env.GEMINI_API_KEY = this.options.apiKey;
-        if (this.options.debug) {
-          console.log("[GeminiStreamClient] buildEnv() - Setting GEMINI_API_KEY for AI Studio");
-        }
+        this.logger.debug("buildEnv() - Setting GEMINI_API_KEY for AI Studio");
       }
     }
-    if (this.options.debug) {
-      console.log("[GeminiStreamClient] buildEnv() - Final env has GOOGLE_API_KEY:", !!env.GOOGLE_API_KEY);
-      console.log("[GeminiStreamClient] buildEnv() - Final env has GEMINI_API_KEY:", !!env.GEMINI_API_KEY);
-      console.log("[GeminiStreamClient] buildEnv() - Final env GOOGLE_GENAI_USE_VERTEXAI:", env.GOOGLE_GENAI_USE_VERTEXAI);
-    }
+    this.logger.debug("buildEnv() - Final env has GOOGLE_API_KEY:", !!env.GOOGLE_API_KEY);
+    this.logger.debug("buildEnv() - Final env has GEMINI_API_KEY:", !!env.GEMINI_API_KEY);
+    this.logger.debug("buildEnv() - Final env GOOGLE_GENAI_USE_VERTEXAI:", env.GOOGLE_GENAI_USE_VERTEXAI);
     return env;
   }
   /**
@@ -715,19 +795,15 @@ var GeminiStreamClient = class extends EventEmitter {
       throw new GeminiSDKError("stdin stream not available");
     }
     const json = JSON.stringify(message);
-    if (this.options.debug) {
-      console.log("[GeminiStreamClient] Writing message to stdin:", json.substring(0, 100));
-    }
+    this.logger.debug("Writing message to stdin:", json.substring(0, 100));
     const success = this.stdinStream.write(json + "\n", (error) => {
       if (error) {
-        console.error("[GeminiStreamClient] Write error:", error);
-      } else if (this.options.debug) {
-        console.log("[GeminiStreamClient] Write callback: message flushed to stdin");
+        this.logger.error("Write error:", error);
+      } else {
+        this.logger.debug("Write callback: message flushed to stdin");
       }
     });
-    if (this.options.debug) {
-      console.log("[GeminiStreamClient] Write success:", success, "Stream writable:", this.stdinStream.writable);
-    }
+    this.logger.debug("Write success:", success, "Stream writable:", this.stdinStream.writable);
   }
   /**
    * Start reading JSONL events from stdout
@@ -742,23 +818,17 @@ var GeminiStreamClient = class extends EventEmitter {
         return;
       }
       if (trimmed.startsWith("[")) {
-        if (this.options.debug) {
-          console.log("[GeminiStreamClient] Skipping debug output:", trimmed.substring(0, 100));
-        }
         return;
       }
       try {
         const event = JSON.parse(trimmed);
         this.handleEvent(event);
       } catch (error) {
-        console.error("[GeminiStreamClient] Failed to parse JSON:", trimmed);
-        console.error("[GeminiStreamClient] Error:", error);
+        this.logger.error("Failed to parse JSON:", trimmed);
+        this.logger.error("Error:", error);
       }
     });
     this.readlineInterface.on("close", () => {
-      if (this.options.debug) {
-        console.log("[GeminiStreamClient] readline interface closed");
-      }
     });
   }
   /**
@@ -800,9 +870,7 @@ var GeminiStreamClient = class extends EventEmitter {
    * Handle process exit
    */
   handleProcessExit(code, signal) {
-    if (this.options.debug) {
-      console.log("[GeminiStreamClient] Process exited:", { code, signal });
-    }
+    this.logger.debug("Process exited:", { code, signal });
     if (code !== 0 && code !== null) {
       this.status = "error" /* ERROR */;
       this.emit("error", new GeminiSDKError(`Process exited with code ${code}`, code));
@@ -821,7 +889,7 @@ var GeminiStreamClient = class extends EventEmitter {
    * Handle process error
    */
   handleProcessError(error) {
-    console.error("[GeminiStreamClient] Process error:", error);
+    this.logger.error("Process error:", error);
     this.status = "error" /* ERROR */;
     this.emit("error", error);
   }
@@ -880,7 +948,7 @@ function validateModel(model) {
     return defaultModel;
   }
   if (!model.startsWith("gemini-")) {
-    console.warn(`Warning: Model name "${model}" does not start with "gemini-"`);
+    sdkLogger.warn(`Warning: Model name "${model}" does not start with "gemini-"`);
   }
   return model;
 }
@@ -899,6 +967,6 @@ function formatTokens(tokens) {
   return tokens.toLocaleString();
 }
 
-export { ExitCode, GeminiClient, GeminiSDKError, GeminiStreamClient, JsonInputMessageType, JsonStreamEventType, ProcessStatus, findGeminiCLI, formatDuration, formatTokens, getApiKey, query, validateApiKey, validateModel };
+export { ExitCode, GeminiClient, GeminiSDKError, GeminiStreamClient, JsonInputMessageType, JsonStreamEventType, LogLevel, ProcessStatus, SDKLogger, createLogger, findGeminiCLI, formatDuration, formatTokens, getApiKey, query, sdkLogger, silentLogger, validateApiKey, validateModel };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map