geminisdk 0.1.1

package/dist/index.d.mts

@@ -0,0 +1,511 @@
+/**
+ * Type definitions for GeminiSDK TypeScript
+ *
+ * Based on:
+ * - GitHub Copilot SDK types
+ * - Google Gemini CLI implementation
+ */
+type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'error';
+type LogLevel = 'none' | 'error' | 'warning' | 'info' | 'debug' | 'all';
+declare enum Role {
+    USER = "user",
+    ASSISTANT = "assistant",
+    SYSTEM = "system"
+}
+interface GeminiOAuthCredentials {
+    accessToken: string;
+    refreshToken: string;
+    tokenType: string;
+    expiryDate: number;
+}
+interface GeminiModelInfo {
+    id: string;
+    name: string;
+    contextWindow: number;
+    maxOutput: number;
+    inputPrice: number;
+    outputPrice: number;
+    supportsNativeTools: boolean;
+    supportsThinking: boolean;
+}
+interface ModelVisionLimits {
+    supportedMediaTypes?: string[];
+    maxPromptImages?: number;
+    maxPromptImageSize?: number;
+}
+interface ModelLimits {
+    maxPromptTokens?: number;
+    maxContextWindowTokens?: number;
+    vision?: ModelVisionLimits;
+}
+interface ModelSupports {
+    vision: boolean;
+    tools: boolean;
+    thinking: boolean;
+}
+interface ModelCapabilities {
+    supports: ModelSupports;
+    limits: ModelLimits;
+}
+interface ModelInfo {
+    id: string;
+    name: string;
+    capabilities: ModelCapabilities;
+}
+interface ContentPart {
+    text?: string;
+    imageUrl?: string;
+    imageData?: Uint8Array;
+    imageMimeType?: string;
+}
+interface Message {
+    role: Role;
+    content: string | ContentPart[];
+    name?: string;
+    toolCalls?: ToolCall[];
+    toolCallId?: string;
+}
+interface Attachment {
+    type: 'file' | 'image';
+    path?: string;
+    url?: string;
+    data?: string;
+    mimeType?: string;
+}
+interface FunctionCall {
+    name: string;
+    arguments: Record<string, unknown> | string;
+}
+interface ToolCall {
+    id: string;
+    type: 'function';
+    function: FunctionCall;
+}
+interface ToolInvocation {
+    name: string;
+    arguments: Record<string, unknown>;
+    callId: string;
+}
+type ToolResultType = 'success' | 'failure' | 'rejected' | 'denied';
+interface ToolResult {
+    resultType?: ToolResultType;
+    textResultForLlm?: string;
+    binaryResult?: Uint8Array;
+    sessionLog?: string;
+}
+type ToolHandler = (invocation: ToolInvocation) => ToolResult | Promise<ToolResult>;
+interface Tool {
+    name: string;
+    description: string;
+    parameters?: Record<string, unknown>;
+    handler?: ToolHandler;
+}
+interface GenerationConfig {
+    temperature?: number;
+    maxOutputTokens?: number;
+    topP?: number;
+    topK?: number;
+    stopSequences?: string[];
+}
+interface ThinkingConfig {
+    includeThoughts?: boolean;
+    thinkingBudget?: number;
+}
+interface MessageOptions {
+    prompt: string;
+    attachments?: Attachment[];
+    context?: string;
+}
+interface LLMUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
+interface LLMChunk {
+    content: string;
+    reasoningContent?: string;
+    toolCalls?: ToolCall[];
+    usage?: LLMUsage;
+    finishReason?: string;
+}
+interface SessionConfig {
+    sessionId?: string;
+    model?: string;
+    tools?: Tool[];
+    systemMessage?: string;
+    generationConfig?: GenerationConfig;
+    thinkingConfig?: ThinkingConfig;
+    streaming?: boolean;
+}
+interface SessionMetadata {
+    sessionId: string;
+    startTime: string;
+    modifiedTime: string;
+    summary?: string;
+    model: string;
+}
+interface GeminiClientOptions {
+    oauthPath?: string;
+    clientId?: string;
+    clientSecret?: string;
+    baseUrl?: string;
+    timeout?: number;
+    logLevel?: LogLevel;
+    autoRefresh?: boolean;
+}
+declare enum EventType {
+    SESSION_CREATED = "session.created",
+    SESSION_IDLE = "session.idle",
+    SESSION_ERROR = "session.error",
+    ASSISTANT_MESSAGE = "assistant.message",
+    ASSISTANT_MESSAGE_DELTA = "assistant.message_delta",
+    ASSISTANT_REASONING = "assistant.reasoning",
+    ASSISTANT_REASONING_DELTA = "assistant.reasoning_delta",
+    TOOL_CALL = "tool.call",
+    TOOL_RESULT = "tool.result"
+}
+interface SessionEvent {
+    type: EventType;
+    data: unknown;
+    sessionId: string;
+}
+type SessionEventHandler = (event: SessionEvent) => void;
+declare const GEMINI_OAUTH_REDIRECT_URI = "http://localhost:45289";
+declare const GEMINI_OAUTH_BASE_URL = "https://accounts.google.com";
+declare const GEMINI_OAUTH_TOKEN_ENDPOINT = "https://accounts.google.com/o/oauth2/token";
+declare const GEMINI_OAUTH_AUTH_ENDPOINT = "https://accounts.google.com/o/oauth2/v2/auth";
+declare const GEMINI_OAUTH_CLIENT_ID = "681255809395-oo8ft2oprdrnp9e3aqf6av3hmdib135j.apps.googleusercontent.com";
+declare const GEMINI_OAUTH_CLIENT_SECRET = "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";
+declare const GEMINI_OAUTH_SCOPES: string[];
+declare const GEMINI_CODE_ASSIST_ENDPOINT = "https://cloudcode-pa.googleapis.com";
+declare const GEMINI_CODE_ASSIST_API_VERSION = "v1internal";
+declare const GEMINI_DIR = ".gemini";
+declare const GEMINI_CREDENTIAL_FILENAME = "oauth_creds.json";
+declare const GEMINI_ENV_FILENAME = ".env";
+declare const TOKEN_REFRESH_BUFFER_MS: number;
+declare const HTTP_OK = 200;
+declare const HTTP_UNAUTHORIZED = 401;
+declare const HTTP_FORBIDDEN = 403;
+declare const GEMINI_CLI_MODELS: Record<string, GeminiModelInfo>;
+declare function getGeminiCliCredentialPath(customPath?: string): string;
+declare function getGeminiCliEnvPath(customPath?: string): string;
+
+/**
+ * Backend for Gemini CLI / Google Code Assist API.
+ */
+
+interface BackendOptions {
+    timeout?: number;
+    oauthPath?: string;
+    clientId?: string;
+    clientSecret?: string;
+}
+declare class GeminiBackend {
+    private timeout;
+    private oauthManager;
+    private projectId;
+    constructor(options?: BackendOptions);
+    private getAuthHeaders;
+    private prepareMessages;
+    private prepareTools;
+    private ensureProjectId;
+    private onboardForProject;
+    private buildRequestPayload;
+    private parseCompletionResponse;
+    complete(options: {
+        model: string;
+        messages: Message[];
+        generationConfig?: GenerationConfig;
+        thinkingConfig?: ThinkingConfig;
+        tools?: Tool[];
+        extraHeaders?: Record<string, string>;
+    }): Promise<LLMChunk>;
+    private completeWithRetry;
+    completeStreaming(options: {
+        model: string;
+        messages: Message[];
+        generationConfig?: GenerationConfig;
+        thinkingConfig?: ThinkingConfig;
+        tools?: Tool[];
+        extraHeaders?: Record<string, string>;
+    }): AsyncGenerator<LLMChunk, void, unknown>;
+    private completeStreamingWithRetry;
+    private handleHttpError;
+    listModels(): Promise<string[]>;
+    close(): Promise<void>;
+}
+
+/**
+ * GeminiSDK Session - Manages individual conversation sessions.
+ */
+
+declare class GeminiSession {
+    private readonly _sessionId;
+    private readonly _model;
+    private readonly _backend;
+    private _tools;
+    private readonly _toolHandlers;
+    private readonly _systemMessage?;
+    private readonly _generationConfig?;
+    private readonly _thinkingConfig?;
+    private readonly _streaming;
+    private _messages;
+    private readonly _eventHandlers;
+    private _closed;
+    private readonly _startTime;
+    private _modifiedTime;
+    constructor(options: {
+        sessionId: string;
+        model: string;
+        backend: GeminiBackend;
+        tools?: Tool[];
+        systemMessage?: string;
+        generationConfig?: GenerationConfig;
+        thinkingConfig?: ThinkingConfig;
+        streaming?: boolean;
+    });
+    get sessionId(): string;
+    get model(): string;
+    get startTime(): Date;
+    get modifiedTime(): Date;
+    get messages(): Message[];
+    on(handler: SessionEventHandler): () => void;
+    private emit;
+    send(options: MessageOptions): Promise<void>;
+    sendAndWait(options: MessageOptions): Promise<SessionEvent>;
+    private streamResponse;
+    private getResponse;
+    private handleToolCalls;
+    getMessages(): Message[];
+    addTool(tool: Tool): void;
+    removeTool(toolName: string): void;
+    clearHistory(): Promise<void>;
+    destroy(): Promise<void>;
+}
+
+/**
+ * GeminiSDK Client - Main entry point for the Gemini SDK.
+ */
+
+declare class GeminiClient {
+    private _options;
+    private _state;
+    private _backend;
+    private _oauthManager;
+    private _sessions;
+    private _started;
+    private _autoRefreshInterval;
+    constructor(options?: GeminiClientOptions);
+    get options(): GeminiClientOptions;
+    get state(): ConnectionState;
+    start(): Promise<void>;
+    private startAutoRefresh;
+    stop(): Promise<void>;
+    close(): Promise<void>;
+    createSession(config?: SessionConfig): Promise<GeminiSession>;
+    getSession(sessionId: string): Promise<GeminiSession>;
+    listSessions(): Promise<SessionMetadata[]>;
+    deleteSession(sessionId: string): Promise<void>;
+    getState(): ConnectionState;
+    getAuthStatus(): Promise<{
+        authenticated: boolean;
+        tokenType?: string;
+        expiresAt?: number;
+    }>;
+    listModels(): Promise<ModelInfo[]>;
+    refreshAuth(): Promise<void>;
+}
+
+/**
+ * OAuth authentication for Gemini CLI / Code Assist API.
+ */
+
+declare class GeminiOAuthManager {
+    private oauthPath?;
+    private clientId;
+    private clientSecret;
+    private credentials;
+    private refreshLock;
+    private projectId;
+    constructor(oauthPath?: string, clientId?: string, clientSecret?: string);
+    private getCredentialPath;
+    private loadCachedCredentials;
+    private saveCredentials;
+    private refreshAccessToken;
+    private doRefresh;
+    private isTokenValid;
+    invalidateCredentials(): void;
+    ensureAuthenticated(forceRefresh?: boolean): Promise<string>;
+    getCredentials(): Promise<GeminiOAuthCredentials>;
+    getApiEndpoint(): string;
+    getProjectId(): string | null;
+    setProjectId(projectId: string): void;
+    generateAuthUrl(state: string, codeVerifier?: string): string;
+    exchangeCode(code: string, codeVerifier?: string): Promise<GeminiOAuthCredentials>;
+}
+
+/**
+ * GeminiSDK Tools - Tool definition utilities.
+ */
+
+interface ToolDefinitionOptions {
+    name?: string;
+    description?: string;
+    parameters?: Record<string, unknown>;
+}
+/**
+ * Define a tool for use with Gemini models.
+ */
+declare function defineTool<T extends Record<string, unknown>>(options: ToolDefinitionOptions, handler: (args: T) => unknown | Promise<unknown>): Tool;
+/**
+ * Create a tool programmatically.
+ */
+declare function createTool(name: string, description: string, parameters?: Record<string, unknown>, handler?: ToolHandler): Tool;
+/**
+ * Registry for managing tools.
+ */
+declare class ToolRegistry {
+    private tools;
+    private categories;
+    register(tool: Tool, category?: string): void;
+    unregister(name: string): void;
+    get(name: string): Tool | undefined;
+    getAll(): Tool[];
+    getByCategory(category: string): Tool[];
+    listCategories(): string[];
+}
+declare function getDefaultRegistry(): ToolRegistry;
+declare function registerTool(tool: Tool, category?: string): void;
+
+/**
+ * Custom exceptions for GeminiSDK TypeScript
+ */
+interface ErrorDetails {
+    [key: string]: unknown;
+}
+declare class GeminiSDKError extends Error {
+    readonly details: ErrorDetails;
+    constructor(message: string, details?: ErrorDetails);
+}
+declare class AuthenticationError extends GeminiSDKError {
+    constructor(message?: string, details?: ErrorDetails);
+}
+declare class CredentialsNotFoundError extends AuthenticationError {
+    readonly credentialPath: string;
+    constructor(credentialPath: string, message?: string);
+}
+declare class TokenRefreshError extends AuthenticationError {
+    readonly statusCode?: number;
+    readonly responseBody?: string;
+    constructor(message?: string, statusCode?: number, responseBody?: string);
+}
+declare class TokenExpiredError extends AuthenticationError {
+    constructor(message?: string);
+}
+declare class ConnectionError extends GeminiSDKError {
+    readonly endpoint?: string;
+    constructor(message?: string, endpoint?: string, details?: ErrorDetails);
+}
+declare class APIError extends GeminiSDKError {
+    readonly statusCode: number;
+    readonly responseBody?: string;
+    readonly endpoint?: string;
+    constructor(message: string, statusCode: number, responseBody?: string, endpoint?: string);
+}
+declare class RateLimitError extends APIError {
+    readonly retryAfter?: number;
+    constructor(message?: string, statusCode?: number, retryAfter?: number, responseBody?: string);
+}
+declare class QuotaExceededError extends APIError {
+    readonly resetTime?: string;
+    constructor(message?: string, statusCode?: number, resetTime?: string, responseBody?: string);
+}
+declare class PermissionDeniedError extends APIError {
+    constructor(message?: string, statusCode?: number, responseBody?: string);
+}
+declare class NotFoundError extends APIError {
+    readonly resource?: string;
+    constructor(message?: string, statusCode?: number, resource?: string, responseBody?: string);
+}
+declare class SessionError extends GeminiSDKError {
+    readonly sessionId?: string;
+    constructor(message: string, sessionId?: string, details?: ErrorDetails);
+}
+declare class SessionNotFoundError extends SessionError {
+    constructor(sessionId: string);
+}
+declare class SessionClosedError extends SessionError {
+    constructor(sessionId?: string);
+}
+declare class ToolError extends GeminiSDKError {
+    readonly toolName?: string;
+    constructor(message: string, toolName?: string, details?: ErrorDetails);
+}
+declare class ToolNotFoundError extends ToolError {
+    constructor(toolName: string);
+}
+declare class ToolExecutionError extends ToolError {
+    readonly originalError?: Error;
+    constructor(message: string, toolName: string, originalError?: Error);
+}
+declare class ValidationError extends GeminiSDKError {
+    readonly field?: string;
+    readonly value?: unknown;
+    constructor(message: string, field?: string, value?: unknown);
+}
+declare class ConfigurationError extends GeminiSDKError {
+    readonly configKey?: string;
+    constructor(message: string, configKey?: string);
+}
+declare class StreamError extends GeminiSDKError {
+    readonly partialContent?: string;
+    constructor(message: string, partialContent?: string);
+}
+declare class CancellationError extends GeminiSDKError {
+    constructor(message?: string);
+}
+declare class TimeoutError extends GeminiSDKError {
+    readonly timeout?: number;
+    constructor(message?: string, timeout?: number);
+}
+declare class OnboardingError extends GeminiSDKError {
+    readonly tierId?: string;
+    constructor(message?: string, tierId?: string);
+}
+
+/**
+ * GeminiSDK TypeScript - A TypeScript SDK for Google Gemini Code Assist API.
+ *
+ * This SDK provides a high-level interface for interacting with the Gemini
+ * Code Assist API, supporting OAuth authentication, streaming responses,
+ * tool calling, and session management.
+ *
+ * @example
+ * ```typescript
+ * import { GeminiClient, EventType } from 'geminisdk';
+ *
+ * async function main() {
+ *   const client = new GeminiClient();
+ *   await client.start();
+ *
+ *   const session = await client.createSession({
+ *     model: 'gemini-2.5-pro',
+ *     streaming: true,
+ *   });
+ *
+ *   session.on((event) => {
+ *     if (event.type === EventType.ASSISTANT_MESSAGE_DELTA) {
+ *       process.stdout.write((event.data as any).deltaContent);
+ *     }
+ *   });
+ *
+ *   await session.send({ prompt: 'What is TypeScript?' });
+ *   await client.close();
+ * }
+ *
+ * main();
+ * ```
+ */
+declare const VERSION = "0.1.1";
+
+export { APIError, type Attachment, AuthenticationError, CancellationError, ConfigurationError, ConnectionError, type ConnectionState, type ContentPart, CredentialsNotFoundError, EventType, type FunctionCall, GEMINI_CLI_MODELS, GEMINI_CODE_ASSIST_API_VERSION, GEMINI_CODE_ASSIST_ENDPOINT, GEMINI_CREDENTIAL_FILENAME, GEMINI_DIR, GEMINI_ENV_FILENAME, GEMINI_OAUTH_AUTH_ENDPOINT, GEMINI_OAUTH_BASE_URL, GEMINI_OAUTH_CLIENT_ID, GEMINI_OAUTH_CLIENT_SECRET, GEMINI_OAUTH_REDIRECT_URI, GEMINI_OAUTH_SCOPES, GEMINI_OAUTH_TOKEN_ENDPOINT, GeminiBackend, GeminiClient, type GeminiClientOptions, type GeminiModelInfo, type GeminiOAuthCredentials, GeminiOAuthManager, GeminiSDKError, GeminiSession, type GenerationConfig, HTTP_FORBIDDEN, HTTP_OK, HTTP_UNAUTHORIZED, type LLMChunk, type LLMUsage, type LogLevel, type Message, type MessageOptions, type ModelCapabilities, type ModelInfo, type ModelLimits, type ModelSupports, type ModelVisionLimits, NotFoundError, OnboardingError, PermissionDeniedError, QuotaExceededError, RateLimitError, Role, SessionClosedError, type SessionConfig, SessionError, type SessionEvent, type SessionEventHandler, type SessionMetadata, SessionNotFoundError, StreamError, TOKEN_REFRESH_BUFFER_MS, type ThinkingConfig, TimeoutError, TokenExpiredError, TokenRefreshError, type Tool, type ToolCall, ToolError, ToolExecutionError, type ToolHandler, type ToolInvocation, ToolNotFoundError, ToolRegistry, type ToolResult, type ToolResultType, VERSION, ValidationError, createTool, defineTool, getDefaultRegistry, getGeminiCliCredentialPath, getGeminiCliEnvPath, registerTool };