geminisdk 0.1.1

package/src/client.ts

@@ -0,0 +1,230 @@
+/**
+ * GeminiSDK Client - Main entry point for the Gemini SDK.
+ */
+
+import { GeminiOAuthManager } from './auth.js';
+import { GeminiBackend } from './backend.js';
+import { SessionNotFoundError } from './exceptions.js';
+import { GeminiSession } from './session.js';
+import {
+  ConnectionState,
+  GEMINI_CLI_MODELS,
+  GeminiClientOptions,
+  ModelInfo,
+  SessionConfig,
+  SessionMetadata,
+} from './types.js';
+
+// Simple UUID generator
+function generateUUID(): string {
+  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+    const r = (Math.random() * 16) | 0;
+    const v = c === 'x' ? r : (r & 0x3) | 0x8;
+    return v.toString(16);
+  });
+}
+
+export class GeminiClient {
+  private _options: GeminiClientOptions;
+  private _state: ConnectionState = 'disconnected';
+  private _backend: GeminiBackend | null = null;
+  private _oauthManager: GeminiOAuthManager | null = null;
+  private _sessions: Map<string, GeminiSession> = new Map();
+  private _started = false;
+  private _autoRefreshInterval: ReturnType<typeof setInterval> | null = null;
+
+  constructor(options: GeminiClientOptions = {}) {
+    this._options = options;
+  }
+
+  get options(): GeminiClientOptions {
+    return this._options;
+  }
+
+  get state(): ConnectionState {
+    return this._state;
+  }
+
+  public async start(): Promise<void> {
+    if (this._started) return;
+
+    this._state = 'connecting';
+
+    try {
+      this._oauthManager = new GeminiOAuthManager(
+        this._options.oauthPath,
+        this._options.clientId,
+        this._options.clientSecret
+      );
+
+      this._backend = new GeminiBackend({
+        timeout: this._options.timeout ?? 720000,
+        oauthPath: this._options.oauthPath,
+        clientId: this._options.clientId,
+        clientSecret: this._options.clientSecret,
+      });
+
+      await this._oauthManager.ensureAuthenticated();
+
+      this._state = 'connected';
+      this._started = true;
+
+      if (this._options.autoRefresh !== false) {
+        this.startAutoRefresh();
+      }
+    } catch (e) {
+      this._state = 'error';
+      throw e;
+    }
+  }
+
+  private startAutoRefresh(): void {
+    if (this._autoRefreshInterval) return;
+
+    this._autoRefreshInterval = setInterval(async () => {
+      try {
+        if (this._oauthManager) {
+          await this._oauthManager.ensureAuthenticated();
+        }
+      } catch (e) {
+        // Ignore background refresh errors
+      }
+    }, 30000);
+  }
+
+  public async stop(): Promise<void> {
+    if (this._autoRefreshInterval) {
+      clearInterval(this._autoRefreshInterval);
+      this._autoRefreshInterval = null;
+    }
+
+    for (const session of this._sessions.values()) {
+      try {
+        await session.destroy();
+      } catch (e) {
+        console.warn('Error destroying session:', e);
+      }
+    }
+    this._sessions.clear();
+
+    if (this._backend) {
+      await this._backend.close();
+      this._backend = null;
+    }
+
+    this._oauthManager = null;
+    this._state = 'disconnected';
+    this._started = false;
+  }
+
+  public async close(): Promise<void> {
+    await this.stop();
+  }
+
+  public async createSession(config: SessionConfig = {}): Promise<GeminiSession> {
+    if (!this._started) {
+      await this.start();
+    }
+
+    if (!this._backend) {
+      throw new Error('Client not connected. Call start() first.');
+    }
+
+    const sessionId = config.sessionId ?? generateUUID();
+    const model = config.model ?? 'gemini-2.5-pro';
+
+    const session = new GeminiSession({
+      sessionId,
+      model,
+      backend: this._backend,
+      tools: config.tools,
+      systemMessage: config.systemMessage,
+      generationConfig: config.generationConfig,
+      thinkingConfig: config.thinkingConfig,
+      streaming: config.streaming ?? true,
+    });
+
+    this._sessions.set(sessionId, session);
+    return session;
+  }
+
+  public async getSession(sessionId: string): Promise<GeminiSession> {
+    const session = this._sessions.get(sessionId);
+    if (!session) {
+      throw new SessionNotFoundError(sessionId);
+    }
+    return session;
+  }
+
+  public async listSessions(): Promise<SessionMetadata[]> {
+    const result: SessionMetadata[] = [];
+    for (const session of this._sessions.values()) {
+      result.push({
+        sessionId: session.sessionId,
+        startTime: session.startTime.toISOString(),
+        modifiedTime: session.modifiedTime.toISOString(),
+        model: session.model,
+      });
+    }
+    return result;
+  }
+
+  public async deleteSession(sessionId: string): Promise<void> {
+    const session = this._sessions.get(sessionId);
+    if (session) {
+      await session.destroy();
+      this._sessions.delete(sessionId);
+    }
+  }
+
+  public getState(): ConnectionState {
+    return this._state;
+  }
+
+  public async getAuthStatus(): Promise<{ authenticated: boolean; tokenType?: string; expiresAt?: number }> {
+    if (!this._oauthManager) {
+      return { authenticated: false };
+    }
+
+    try {
+      const credentials = await this._oauthManager.getCredentials();
+      return {
+        authenticated: true,
+        tokenType: credentials.tokenType,
+        expiresAt: credentials.expiryDate,
+      };
+    } catch {
+      return { authenticated: false };
+    }
+  }
+
+  public async listModels(): Promise<ModelInfo[]> {
+    const models: ModelInfo[] = [];
+
+    for (const [modelId, info] of Object.entries(GEMINI_CLI_MODELS)) {
+      models.push({
+        id: modelId,
+        name: info.name,
+        capabilities: {
+          supports: {
+            vision: false,
+            tools: info.supportsNativeTools,
+            thinking: info.supportsThinking,
+          },
+          limits: {
+            maxContextWindowTokens: info.contextWindow,
+            maxPromptTokens: info.contextWindow,
+          },
+        },
+      });
+    }
+
+    return models;
+  }
+
+  public async refreshAuth(): Promise<void> {
+    if (this._oauthManager) {
+      await this._oauthManager.ensureAuthenticated(true);
+    }
+  }
+}

package/src/exceptions.ts

@@ -0,0 +1,289 @@
+/**
+ * Custom exceptions for GeminiSDK TypeScript
+ */
+
+export interface ErrorDetails {
+  [key: string]: unknown;
+}
+
+export class GeminiSDKError extends Error {
+  public readonly details: ErrorDetails;
+
+  constructor(message: string, details: ErrorDetails = {}) {
+    super(message);
+    this.name = 'GeminiSDKError';
+    this.details = details;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}
+
+export class AuthenticationError extends GeminiSDKError {
+  constructor(message = 'Authentication failed', details: ErrorDetails = {}) {
+    super(message, details);
+    this.name = 'AuthenticationError';
+  }
+}
+
+export class CredentialsNotFoundError extends AuthenticationError {
+  public readonly credentialPath: string;
+
+  constructor(credentialPath: string, message?: string) {
+    const msg =
+      message ??
+      `Gemini OAuth credentials not found at ${credentialPath}. ` +
+        'Please login using the Gemini CLI first: gemini auth login';
+    super(msg, { credentialPath });
+    this.name = 'CredentialsNotFoundError';
+    this.credentialPath = credentialPath;
+  }
+}
+
+export class TokenRefreshError extends AuthenticationError {
+  public readonly statusCode?: number;
+  public readonly responseBody?: string;
+
+  constructor(
+    message = 'Failed to refresh access token',
+    statusCode?: number,
+    responseBody?: string
+  ) {
+    const details: ErrorDetails = {};
+    if (statusCode !== undefined) details['statusCode'] = statusCode;
+    if (responseBody !== undefined) details['responseBody'] = responseBody;
+    super(message, details);
+    this.name = 'TokenRefreshError';
+    this.statusCode = statusCode;
+    this.responseBody = responseBody;
+  }
+}
+
+export class TokenExpiredError extends AuthenticationError {
+  constructor(message = 'Access token has expired') {
+    super(message);
+    this.name = 'TokenExpiredError';
+  }
+}
+
+export class ConnectionError extends GeminiSDKError {
+  public readonly endpoint?: string;
+
+  constructor(
+    message = 'Failed to connect to Gemini API',
+    endpoint?: string,
+    details: ErrorDetails = {}
+  ) {
+    if (endpoint) details['endpoint'] = endpoint;
+    super(message, details);
+    this.name = 'ConnectionError';
+    this.endpoint = endpoint;
+  }
+}
+
+export class APIError extends GeminiSDKError {
+  public readonly statusCode: number;
+  public readonly responseBody?: string;
+  public readonly endpoint?: string;
+
+  constructor(
+    message: string,
+    statusCode: number,
+    responseBody?: string,
+    endpoint?: string
+  ) {
+    const details: ErrorDetails = { statusCode };
+    if (responseBody !== undefined) details['responseBody'] = responseBody;
+    if (endpoint !== undefined) details['endpoint'] = endpoint;
+    super(message, details);
+    this.name = 'APIError';
+    this.statusCode = statusCode;
+    this.responseBody = responseBody;
+    this.endpoint = endpoint;
+  }
+}
+
+export class RateLimitError extends APIError {
+  public readonly retryAfter?: number;
+
+  constructor(
+    message = 'Rate limit exceeded',
+    statusCode = 429,
+    retryAfter?: number,
+    responseBody?: string
+  ) {
+    super(message, statusCode, responseBody);
+    this.name = 'RateLimitError';
+    this.retryAfter = retryAfter;
+    if (retryAfter !== undefined) this.details['retryAfter'] = retryAfter;
+  }
+}
+
+export class QuotaExceededError extends APIError {
+  public readonly resetTime?: string;
+
+  constructor(
+    message = 'Quota exceeded',
+    statusCode = 429,
+    resetTime?: string,
+    responseBody?: string
+  ) {
+    super(message, statusCode, responseBody);
+    this.name = 'QuotaExceededError';
+    this.resetTime = resetTime;
+    if (resetTime !== undefined) this.details['resetTime'] = resetTime;
+  }
+}
+
+export class PermissionDeniedError extends APIError {
+  constructor(
+    message = 'Permission denied',
+    statusCode = 403,
+    responseBody?: string
+  ) {
+    super(message, statusCode, responseBody);
+    this.name = 'PermissionDeniedError';
+  }
+}
+
+export class NotFoundError extends APIError {
+  public readonly resource?: string;
+
+  constructor(
+    message = 'Resource not found',
+    statusCode = 404,
+    resource?: string,
+    responseBody?: string
+  ) {
+    super(message, statusCode, responseBody);
+    this.name = 'NotFoundError';
+    this.resource = resource;
+    if (resource !== undefined) this.details['resource'] = resource;
+  }
+}
+
+export class SessionError extends GeminiSDKError {
+  public readonly sessionId?: string;
+
+  constructor(message: string, sessionId?: string, details: ErrorDetails = {}) {
+    if (sessionId) details['sessionId'] = sessionId;
+    super(message, details);
+    this.name = 'SessionError';
+    this.sessionId = sessionId;
+  }
+}
+
+export class SessionNotFoundError extends SessionError {
+  constructor(sessionId: string) {
+    super(`Session not found: ${sessionId}`, sessionId);
+    this.name = 'SessionNotFoundError';
+  }
+}
+
+export class SessionClosedError extends SessionError {
+  constructor(sessionId?: string) {
+    super('Session is closed', sessionId);
+    this.name = 'SessionClosedError';
+  }
+}
+
+export class ToolError extends GeminiSDKError {
+  public readonly toolName?: string;
+
+  constructor(message: string, toolName?: string, details: ErrorDetails = {}) {
+    if (toolName) details['toolName'] = toolName;
+    super(message, details);
+    this.name = 'ToolError';
+    this.toolName = toolName;
+  }
+}
+
+export class ToolNotFoundError extends ToolError {
+  constructor(toolName: string) {
+    super(`Tool not found: ${toolName}`, toolName);
+    this.name = 'ToolNotFoundError';
+  }
+}
+
+export class ToolExecutionError extends ToolError {
+  public readonly originalError?: Error;
+
+  constructor(message: string, toolName: string, originalError?: Error) {
+    const details: ErrorDetails = {};
+    if (originalError) details['originalError'] = originalError.message;
+    super(message, toolName, details);
+    this.name = 'ToolExecutionError';
+    this.originalError = originalError;
+  }
+}
+
+export class ValidationError extends GeminiSDKError {
+  public readonly field?: string;
+  public readonly value?: unknown;
+
+  constructor(message: string, field?: string, value?: unknown) {
+    const details: ErrorDetails = {};
+    if (field !== undefined) details['field'] = field;
+    if (value !== undefined) details['value'] = String(value);
+    super(message, details);
+    this.name = 'ValidationError';
+    this.field = field;
+    this.value = value;
+  }
+}
+
+export class ConfigurationError extends GeminiSDKError {
+  public readonly configKey?: string;
+
+  constructor(message: string, configKey?: string) {
+    const details: ErrorDetails = {};
+    if (configKey) details['configKey'] = configKey;
+    super(message, details);
+    this.name = 'ConfigurationError';
+    this.configKey = configKey;
+  }
+}
+
+export class StreamError extends GeminiSDKError {
+  public readonly partialContent?: string;
+
+  constructor(message: string, partialContent?: string) {
+    const details: ErrorDetails = {};
+    if (partialContent) details['partialContent'] = partialContent.slice(0, 500);
+    super(message, details);
+    this.name = 'StreamError';
+    this.partialContent = partialContent;
+  }
+}
+
+export class CancellationError extends GeminiSDKError {
+  constructor(message = 'Operation was cancelled') {
+    super(message);
+    this.name = 'CancellationError';
+  }
+}
+
+export class TimeoutError extends GeminiSDKError {
+  public readonly timeout?: number;
+
+  constructor(message = 'Operation timed out', timeout?: number) {
+    const details: ErrorDetails = {};
+    if (timeout !== undefined) details['timeout'] = timeout;
+    super(message, details);
+    this.name = 'TimeoutError';
+    this.timeout = timeout;
+  }
+}
+
+export class OnboardingError extends GeminiSDKError {
+  public readonly tierId?: string;
+
+  constructor(
+    message = 'Failed to complete Gemini Code Assist onboarding',
+    tierId?: string
+  ) {
+    const details: ErrorDetails = {};
+    if (tierId) details['tierId'] = tierId;
+    super(message, details);
+    this.name = 'OnboardingError';
+    this.tierId = tierId;
+  }
+}

package/src/index.ts

@@ -0,0 +1,148 @@
+/**
+ * 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();
+ * ```
+ */
+
+export const VERSION = '0.1.1';
+
+// Client
+export { GeminiClient } from './client.js';
+
+// Session
+export { GeminiSession } from './session.js';
+
+// Backend
+export { GeminiBackend } from './backend.js';
+
+// Authentication
+export { GeminiOAuthManager } from './auth.js';
+
+// Tools
+export {
+  ToolRegistry,
+  createTool,
+  defineTool,
+  getDefaultRegistry,
+  registerTool,
+} from './tools.js';
+
+// Types
+export {
+  // Connection
+  ConnectionState,
+  LogLevel,
+  Role,
+  // OAuth
+  GeminiOAuthCredentials,
+  // Models
+  GeminiModelInfo,
+  ModelVisionLimits,
+  ModelLimits,
+  ModelSupports,
+  ModelCapabilities,
+  ModelInfo,
+  // Messages
+  ContentPart,
+  Message,
+  Attachment,
+  // Tools
+  FunctionCall,
+  ToolCall,
+  ToolInvocation,
+  ToolResultType,
+  ToolResult,
+  ToolHandler,
+  Tool,
+  // Generation
+  GenerationConfig,
+  ThinkingConfig,
+  // Request/Response
+  MessageOptions,
+  LLMUsage,
+  LLMChunk,
+  // Session
+  SessionConfig,
+  SessionMetadata,
+  // Client
+  GeminiClientOptions,
+  // Events
+  EventType,
+  SessionEvent,
+  SessionEventHandler,
+  // Constants
+  GEMINI_OAUTH_REDIRECT_URI,
+  GEMINI_OAUTH_BASE_URL,
+  GEMINI_OAUTH_TOKEN_ENDPOINT,
+  GEMINI_OAUTH_AUTH_ENDPOINT,
+  GEMINI_OAUTH_CLIENT_ID,
+  GEMINI_OAUTH_CLIENT_SECRET,
+  GEMINI_OAUTH_SCOPES,
+  GEMINI_CODE_ASSIST_ENDPOINT,
+  GEMINI_CODE_ASSIST_API_VERSION,
+  GEMINI_DIR,
+  GEMINI_CREDENTIAL_FILENAME,
+  GEMINI_ENV_FILENAME,
+  TOKEN_REFRESH_BUFFER_MS,
+  HTTP_OK,
+  HTTP_UNAUTHORIZED,
+  HTTP_FORBIDDEN,
+  GEMINI_CLI_MODELS,
+  getGeminiCliCredentialPath,
+  getGeminiCliEnvPath,
+} from './types.js';
+
+// Exceptions
+export {
+  GeminiSDKError,
+  AuthenticationError,
+  CredentialsNotFoundError,
+  TokenRefreshError,
+  TokenExpiredError,
+  ConnectionError,
+  APIError,
+  RateLimitError,
+  QuotaExceededError,
+  PermissionDeniedError,
+  NotFoundError,
+  SessionError,
+  SessionNotFoundError,
+  SessionClosedError,
+  ToolError,
+  ToolNotFoundError,
+  ToolExecutionError,
+  ValidationError,
+  ConfigurationError,
+  StreamError,
+  CancellationError,
+  TimeoutError,
+  OnboardingError,
+} from './exceptions.js';