@ketd/gemini-cli-sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,408 @@
+import { EventEmitter } from 'events';
+
+/**
+ * Type definitions for Gemini CLI SDK
+ *
+ * Based on Gemini CLI v0.21.0+ interface specification
+ */
+/**
+ * Gemini CLI configuration options
+ */
+interface GeminiOptions {
+    /**
+     * Path to Gemini CLI executable
+     * @example 'node_modules/@google/gemini-cli/bundle/gemini.js'
+     */
+    pathToGeminiCLI: string;
+    /**
+     * Google AI API Key
+     * Can also be set via GOOGLE_API_KEY environment variable
+     */
+    apiKey?: string;
+    /**
+     * Model name
+     * @default 'gemini-2.0-flash-exp'
+     * @example 'gemini-2.0-flash-exp', 'gemini-1.5-pro'
+     */
+    model?: string;
+    /**
+     * Working directory for CLI execution
+     * @default process.cwd()
+     */
+    cwd?: string;
+    /**
+     * System prompt (not directly supported by CLI, needs workaround)
+     */
+    systemPrompt?: string;
+    /**
+     * Approval mode for tool execution
+     * - default: Prompt for approval
+     * - auto_edit: Auto-approve edit tools
+     * - yolo: Auto-approve all tools
+     * @default 'default'
+     */
+    approvalMode?: 'default' | 'auto_edit' | 'yolo';
+    /**
+     * List of tools that can run without confirmation
+     * @example ['read', 'write', 'bash']
+     */
+    allowedTools?: string[];
+    /**
+     * List of allowed MCP server names
+     */
+    allowedMcpServerNames?: string[];
+    /**
+     * Enable debug mode
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Session ID to resume
+     * Use 'latest' to resume the most recent session
+     */
+    resumeSessionId?: string;
+    /**
+     * Enable sandbox mode
+     * @default false
+     */
+    sandbox?: boolean;
+    /**
+     * Additional directories to include in workspace
+     */
+    includeDirectories?: string[];
+    /**
+     * Custom environment variables
+     */
+    env?: Record<string, string>;
+    /**
+     * Timeout in milliseconds
+     * @default undefined (no timeout)
+     */
+    timeout?: number;
+}
+/**
+ * JSON Stream Event Types
+ *
+ * Based on: @google/gemini-cli/packages/core/src/output/types.ts
+ */
+declare enum JsonStreamEventType {
+    /** Session initialization */
+    INIT = "init",
+    /** Message content (user/assistant) */
+    MESSAGE = "message",
+    /** Tool call request */
+    TOOL_USE = "tool_use",
+    /** Tool execution result */
+    TOOL_RESULT = "tool_result",
+    /** Error event */
+    ERROR = "error",
+    /** Final result */
+    RESULT = "result"
+}
+/**
+ * Base event interface
+ */
+interface BaseJsonStreamEvent {
+    type: JsonStreamEventType;
+    timestamp: string;
+}
+/**
+ * Session initialization event
+ */
+interface InitEvent extends BaseJsonStreamEvent {
+    type: JsonStreamEventType.INIT;
+    session_id: string;
+    model: string;
+}
+/**
+ * Message event
+ */
+interface MessageEvent extends BaseJsonStreamEvent {
+    type: JsonStreamEventType.MESSAGE;
+    role: 'user' | 'assistant';
+    content: string;
+    delta?: boolean;
+}
+/**
+ * Tool call event
+ */
+interface ToolUseEvent extends BaseJsonStreamEvent {
+    type: JsonStreamEventType.TOOL_USE;
+    tool_name: string;
+    tool_id: string;
+    parameters: Record<string, unknown>;
+}
+/**
+ * Tool execution result event
+ */
+interface ToolResultEvent extends BaseJsonStreamEvent {
+    type: JsonStreamEventType.TOOL_RESULT;
+    tool_id: string;
+    status: 'success' | 'error';
+    output?: string;
+    error?: {
+        type: string;
+        message: string;
+    };
+}
+/**
+ * Error event
+ */
+interface ErrorEvent extends BaseJsonStreamEvent {
+    type: JsonStreamEventType.ERROR;
+    severity: 'warning' | 'error';
+    message: string;
+}
+/**
+ * Stream statistics
+ */
+interface StreamStats {
+    total_tokens: number;
+    input_tokens: number;
+    output_tokens: number;
+    duration_ms: number;
+    tool_calls: number;
+}
+/**
+ * Final result event
+ */
+interface ResultEvent extends BaseJsonStreamEvent {
+    type: JsonStreamEventType.RESULT;
+    status: 'success' | 'error';
+    error?: {
+        type: string;
+        message: string;
+    };
+    stats?: StreamStats;
+}
+/**
+ * Union type of all JSON stream events
+ */
+type JsonStreamEvent = InitEvent | MessageEvent | ToolUseEvent | ToolResultEvent | ErrorEvent | ResultEvent;
+/**
+ * Gemini CLI exit codes
+ */
+declare enum ExitCode {
+    /** Success */
+    SUCCESS = 0,
+    /** General error */
+    GENERAL_ERROR = 1,
+    /** Configuration error */
+    CONFIG_ERROR = 2,
+    /** User interrupted (Ctrl+C) */
+    USER_INTERRUPTED = 130
+}
+/**
+ * CLI process status
+ */
+declare enum ProcessStatus {
+    /** Not started */
+    IDLE = "idle",
+    /** Running */
+    RUNNING = "running",
+    /** Completed successfully */
+    COMPLETED = "completed",
+    /** Cancelled by user */
+    CANCELLED = "cancelled",
+    /** Error occurred */
+    ERROR = "error"
+}
+/**
+ * Gemini SDK Error
+ */
+declare class GeminiSDKError extends Error {
+    code?: ExitCode | undefined;
+    details?: unknown | undefined;
+    constructor(message: string, code?: ExitCode | undefined, details?: unknown | undefined);
+}
+/**
+ * Query result (accumulated from stream)
+ */
+interface QueryResult {
+    /** Session ID */
+    sessionId: string;
+    /** Model used */
+    model: string;
+    /** Full assistant response text */
+    response: string;
+    /** Tool calls made during the query */
+    toolCalls: Array<{
+        tool_name: string;
+        tool_id: string;
+        parameters: Record<string, unknown>;
+        result?: {
+            status: 'success' | 'error';
+            output?: string;
+            error?: {
+                type: string;
+                message: string;
+            };
+        };
+    }>;
+    /** Final statistics */
+    stats?: StreamStats;
+    /** Final status */
+    status: 'success' | 'error';
+    /** Error if status is 'error' */
+    error?: {
+        type: string;
+        message: string;
+    };
+}
+
+/**
+ * Core query function for Gemini CLI SDK
+ *
+ * Spawns Gemini CLI as subprocess and streams JSON events
+ */
+
+/**
+ * Query Gemini CLI and stream JSON events
+ *
+ * @param prompt - User prompt
+ * @param options - Gemini configuration options
+ * @returns AsyncGenerator<JsonStreamEvent> - Stream of JSON events
+ *
+ * @example
+ * ```typescript
+ * import { query } from '@google/gemini-cli-sdk';
+ *
+ * const stream = query('Hello, Gemini!', {
+ *   pathToGeminiCLI: './node_modules/@google/gemini-cli/bundle/gemini.js',
+ *   apiKey: process.env.GOOGLE_API_KEY,
+ *   model: 'gemini-2.0-flash-exp',
+ * });
+ *
+ * for await (const event of stream) {
+ *   if (event.type === 'message' && event.role === 'assistant' && event.delta) {
+ *     process.stdout.write(event.content);
+ *   }
+ * }
+ * ```
+ */
+declare function query(prompt: string, options: GeminiOptions): AsyncGenerator<JsonStreamEvent>;
+
+/**
+ * Gemini CLI Client
+ *
+ * High-level client for interacting with Gemini CLI
+ */
+
+/**
+ * Gemini CLI Client
+ *
+ * Provides a high-level API for interacting with Gemini CLI
+ *
+ * @example
+ * ```typescript
+ * import { GeminiClient } from '@google/gemini-cli-sdk';
+ *
+ * const client = new GeminiClient({
+ *   pathToGeminiCLI: './node_modules/@google/gemini-cli/bundle/gemini.js',
+ *   apiKey: process.env.GOOGLE_API_KEY,
+ *   model: 'gemini-2.0-flash-exp',
+ * });
+ *
+ * // Stream events
+ * for await (const event of client.stream('Hello, Gemini!')) {
+ *   if (event.type === 'message' && event.role === 'assistant' && event.delta) {
+ *     process.stdout.write(event.content);
+ *   }
+ * }
+ *
+ * // Or get complete result
+ * const result = await client.query('Explain TypeScript generics');
+ * console.log(result.response);
+ * ```
+ */
+declare class GeminiClient extends EventEmitter {
+    private options;
+    private status;
+    private currentSessionId;
+    constructor(options: GeminiOptions);
+    /**
+     * Stream events from Gemini CLI
+     *
+     * @param prompt - User prompt
+     * @returns AsyncGenerator<JsonStreamEvent> - Stream of JSON events
+     */
+    stream(prompt: string): AsyncGenerator<JsonStreamEvent>;
+    /**
+     * Query Gemini CLI and return complete result
+     *
+     * @param prompt - User prompt
+     * @returns Promise<QueryResult> - Complete query result
+     */
+    query(prompt: string): Promise<QueryResult>;
+    /**
+     * Get current process status
+     */
+    getStatus(): ProcessStatus;
+    /**
+     * Get current session ID
+     */
+    getSessionId(): string | null;
+    /**
+     * Update options
+     */
+    setOptions(options: Partial<GeminiOptions>): void;
+    /**
+     * Get current options
+     */
+    getOptions(): Readonly<GeminiOptions>;
+}
+
+/**
+ * Utility functions for Gemini CLI SDK
+ */
+/**
+ * Find Gemini CLI executable path
+ *
+ * Searches in common locations:
+ * 1. node_modules/@google/gemini-cli/bundle/gemini.js
+ * 2. Custom path from environment variable
+ * 3. Global installation
+ *
+ * @param cwd - Current working directory
+ * @returns string - Path to Gemini CLI executable
+ * @throws Error if Gemini CLI is not found
+ */
+declare function findGeminiCLI(cwd?: string): string;
+/**
+ * Validate API key
+ *
+ * @param apiKey - API key to validate
+ * @returns boolean - True if valid
+ */
+declare function validateApiKey(apiKey?: string): boolean;
+/**
+ * Get API key from environment or options
+ *
+ * @param apiKey - Optional API key from options
+ * @returns string - API key
+ * @throws Error if API key is not found
+ */
+declare function getApiKey(apiKey?: string): string;
+/**
+ * Parse model name and validate
+ *
+ * @param model - Model name
+ * @returns string - Validated model name
+ */
+declare function validateModel(model?: string): string;
+/**
+ * Format duration in milliseconds to human-readable string
+ *
+ * @param ms - Duration in milliseconds
+ * @returns string - Formatted duration
+ */
+declare function formatDuration(ms: number): string;
+/**
+ * Format token count with commas
+ *
+ * @param tokens - Token count
+ * @returns string - Formatted token count
+ */
+declare function formatTokens(tokens: number): string;
+
+export { type ErrorEvent, ExitCode, GeminiClient, type GeminiOptions, GeminiSDKError, type InitEvent, type JsonStreamEvent, JsonStreamEventType, type MessageEvent, ProcessStatus, type QueryResult, type ResultEvent, type StreamStats, type ToolResultEvent, type ToolUseEvent, findGeminiCLI, formatDuration, formatTokens, getApiKey, query, validateApiKey, validateModel };