@hasna/connectors 0.0.1

package/connectors/connect-e2b/GEMINI.md

@@ -0,0 +1,126 @@
+# GEMINI.md
+
+This file provides guidance to Gemini when working with this repository.
+
+## Project Overview
+
+connect-e2b is a TypeScript connector for the E2B Code Interpreter API. E2B provides secure cloud sandboxes for running AI-generated code in isolated environments. This connector provides both a programmatic API and a CLI for interacting with E2B sandboxes.
+
+## Build & Run Commands
+
+```bash
+# Install dependencies
+bun install
+
+# Run CLI in development
+bun run dev
+
+# Build for distribution
+bun run build
+
+# Type check
+bun run typecheck
+```
+
+## Code Style
+
+- TypeScript with strict mode
+- ESM modules (`type: module`)
+- Async/await for all async operations
+- Minimal dependencies: commander, chalk
+- Type annotations required everywhere
+
+## Project Structure
+
+```
+src/
+├── api/           # API client modules
+│   ├── client.ts  # HTTP client with authentication
+│   └── index.ts   # Main connector class
+├── cli/
+│   └── index.ts   # CLI commands
+├── types/
+│   └── index.ts   # TypeScript types
+├── utils/
+│   ├── config.ts  # Multi-profile configuration
+│   └── output.ts  # CLI output formatting
+└── index.ts       # Library exports
+```
+
+## Authentication
+
+API Key authentication. Credentials can be set via:
+- Environment variable (see below)
+- Profile configuration: `connect-e2b config set-key <key>`
+
+
+## CLI Commands
+
+### Sandbox Management
+
+```bash
+connect-e2b sandbox create [--template <template>] [--timeout <ms>]
+connect-e2b sandbox list
+connect-e2b sandbox get <sandboxId>
+connect-e2b sandbox kill <sandboxId>
+connect-e2b sandbox keep-alive <sandboxId> [--timeout <ms>]
+```
+
+### Code Execution
+
+```bash
+connect-e2b run "<code>" [--language <lang>] [--sandbox <id>] [--no-cleanup]
+connect-e2b exec "<command>" [--sandbox <id>] [--workdir <path>]
+```
+
+### File Operations
+
+```bash
+connect-e2b file read <sandboxId> <path>
+connect-e2b file write <sandboxId> <path> <content>
+connect-e2b file list <sandboxId> [path]
+connect-e2b file mkdir <sandboxId> <path>
+connect-e2b file rm <sandboxId> <path>
+```
+
+### Configuration
+
+```bash
+connect-e2b config set-key <apiKey>
+connect-e2b config set-template <template>
+connect-e2b config set-timeout <ms>
+connect-e2b config show
+connect-e2b config clear
+```
+
+### Profile Management
+
+```bash
+connect-e2b profile list
+connect-e2b profile create <name> [--api-key <key>] [--use]
+connect-e2b profile use <name>
+connect-e2b profile delete <name>
+connect-e2b profile show [name]
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `E2B_API_KEY` | E2B API key (required) |
+| `E2B_BASE_URL` | Override base URL (optional) |
+
+## Data Storage
+
+```
+~/.connect/connect-e2b/
+├── current_profile   # Active profile name
+└── profiles/
+    ├── default.json  # Default profile
+    └── {name}.json   # Named profiles
+```
+
+## Dependencies
+
+- commander: CLI framework
+- chalk: Terminal styling

package/connectors/connect-e2b/README.md

@@ -0,0 +1,135 @@
+# connect-e2b
+
+E2B Code Interpreter API connector - Run code in secure cloud sandboxes
+
+## Installation
+
+```bash
+bun install -g @hasna/connect-e2b
+```
+
+## Quick Start
+
+```bash
+# Set your API key
+connect-e2b config set-key YOUR_API_KEY
+
+# Or use environment variable
+export E2B_API_KEY=YOUR_API_KEY
+```
+
+## CLI Commands
+
+### Sandbox Management
+
+```bash
+connect-e2b sandbox create [--template <template>] [--timeout <ms>]
+connect-e2b sandbox list
+connect-e2b sandbox get <sandboxId>
+connect-e2b sandbox kill <sandboxId>
+connect-e2b sandbox keep-alive <sandboxId> [--timeout <ms>]
+```
+
+### Code Execution
+
+```bash
+connect-e2b run "<code>" [--language <lang>] [--sandbox <id>] [--no-cleanup]
+connect-e2b exec "<command>" [--sandbox <id>] [--workdir <path>]
+```
+
+### File Operations
+
+```bash
+connect-e2b file read <sandboxId> <path>
+connect-e2b file write <sandboxId> <path> <content>
+connect-e2b file list <sandboxId> [path]
+connect-e2b file mkdir <sandboxId> <path>
+connect-e2b file rm <sandboxId> <path>
+```
+
+### Configuration
+
+```bash
+connect-e2b config set-key <apiKey>
+connect-e2b config set-template <template>
+connect-e2b config set-timeout <ms>
+connect-e2b config show
+connect-e2b config clear
+```
+
+### Profile Management
+
+```bash
+connect-e2b profile list
+connect-e2b profile create <name> [--api-key <key>] [--use]
+connect-e2b profile use <name>
+connect-e2b profile delete <name>
+connect-e2b profile show [name]
+```
+
+## Profile Management
+
+```bash
+# Create profiles for different accounts
+connect-e2b profile create work --api-key xxx --use
+connect-e2b profile create personal --api-key yyy
+
+# Switch profiles
+connect-e2b profile use work
+
+# Use profile for single command
+connect-e2b -p personal <command>
+
+# List profiles
+connect-e2b profile list
+```
+
+## Library Usage
+
+```typescript
+import { E2b } from '@hasna/connect-e2b';
+
+const client = new E2b({ apiKey: 'YOUR_API_KEY' });
+
+// Use the client
+// See CLAUDE.md for detailed API documentation
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `E2B_API_KEY` | E2B API key (required) |
+| `E2B_BASE_URL` | Override base URL (optional) |
+
+## Data Storage
+
+Configuration stored in `~/.connect/connect-e2b/`:
+
+```
+~/.connect/connect-e2b/
+├── current_profile   # Active profile name
+└── profiles/
+    ├── default.json  # Default profile
+    └── {name}.json   # Named profiles
+```
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Run CLI in development
+bun run dev
+
+# Build
+bun run build
+
+# Type check
+bun run typecheck
+```
+
+## License
+
+MIT

package/connectors/connect-e2b/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@hasna/connect-e2b",
+  "version": "0.0.1",
+  "description": "E2B Code Interpreter API connector - Run code in secure cloud sandboxes",
+  "type": "module",
+  "bin": {
+    "connect-e2b": "./bin/index.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun && bun build ./src/cli/index.ts --outdir ./bin --target bun",
+    "dev": "bun run ./src/cli/index.ts",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "e2b",
+    "code-interpreter",
+    "sandbox",
+    "api",
+    "connector",
+    "cli",
+    "typescript",
+    "bun",
+    "hasna"
+  ],
+  "author": "Hasna",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "chalk": "^5.3.0"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hasna/opensource-connectors.git"
+  }
+}

package/connectors/connect-e2b/src/api/client.ts

@@ -0,0 +1,150 @@
+import type { E2BConfig, OutputFormat } from '../types';
+import { E2BApiError } from '../types';
+
+// E2B API Base URL
+const DEFAULT_BASE_URL = 'https://api.e2b.dev';
+
+export interface RequestOptions {
+  method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+  params?: Record<string, string | number | boolean | undefined>;
+  body?: Record<string, unknown> | unknown[] | string;
+  headers?: Record<string, string>;
+  format?: OutputFormat;
+  timeout?: number;
+}
+
+export class E2BClient {
+  private readonly apiKey: string;
+  private readonly baseUrl: string;
+
+  constructor(config: E2BConfig) {
+    if (!config.apiKey) {
+      throw new Error('E2B API key is required');
+    }
+    this.apiKey = config.apiKey;
+    this.baseUrl = config.baseUrl || DEFAULT_BASE_URL;
+  }
+
+  private buildUrl(path: string, params?: Record<string, string | number | boolean | undefined>): string {
+    const url = new URL(`${this.baseUrl}${path}`);
+
+    if (params) {
+      Object.entries(params).forEach(([key, value]) => {
+        if (value !== undefined && value !== null && value !== '') {
+          url.searchParams.append(key, String(value));
+        }
+      });
+    }
+
+    return url.toString();
+  }
+
+  /**
+   * Make an authenticated request to the E2B API
+   * E2B uses X-API-Key header for authentication
+   */
+  async request<T>(path: string, options: RequestOptions = {}): Promise<T> {
+    const { method = 'GET', params, body, headers = {}, timeout } = options;
+
+    const url = this.buildUrl(path, params);
+
+    // E2B authentication via X-API-Key header
+    const requestHeaders: Record<string, string> = {
+      'X-API-Key': this.apiKey,
+      'Accept': 'application/json',
+      ...headers,
+    };
+
+    if (body && ['POST', 'PUT', 'PATCH'].includes(method)) {
+      requestHeaders['Content-Type'] = 'application/json';
+    }
+
+    const fetchOptions: RequestInit = {
+      method,
+      headers: requestHeaders,
+    };
+
+    if (body && ['POST', 'PUT', 'PATCH'].includes(method)) {
+      fetchOptions.body = typeof body === 'string' ? body : JSON.stringify(body);
+    }
+
+    // Add timeout via AbortController if specified
+    let controller: AbortController | undefined;
+    if (timeout) {
+      controller = new AbortController();
+      fetchOptions.signal = controller.signal;
+      setTimeout(() => controller?.abort(), timeout);
+    }
+
+    const response = await fetch(url, fetchOptions);
+
+    // Handle 204 No Content
+    if (response.status === 204) {
+      return {} as T;
+    }
+
+    // Parse response
+    let data: unknown;
+    const contentType = response.headers.get('content-type') || '';
+
+    if (contentType.includes('application/json')) {
+      const text = await response.text();
+      if (text) {
+        try {
+          data = JSON.parse(text);
+        } catch {
+          data = text;
+        }
+      }
+    } else {
+      data = await response.text();
+    }
+
+    // Handle errors
+    if (!response.ok) {
+      const errorMessage = typeof data === 'object' && data !== null
+        ? JSON.stringify(data)
+        : String(data || response.statusText);
+      throw new E2BApiError(errorMessage, response.status);
+    }
+
+    return data as T;
+  }
+
+  async get<T>(path: string, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'GET', params });
+  }
+
+  async post<T>(path: string, body?: Record<string, unknown> | unknown[] | string | object, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'POST', body: body as Record<string, unknown>, params });
+  }
+
+  async put<T>(path: string, body?: Record<string, unknown> | object, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'PUT', body: body as Record<string, unknown>, params });
+  }
+
+  async patch<T>(path: string, body?: Record<string, unknown> | object, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'PATCH', body: body as Record<string, unknown>, params });
+  }
+
+  async delete<T>(path: string, params?: Record<string, string | number | boolean | undefined>): Promise<T> {
+    return this.request<T>(path, { method: 'DELETE', params });
+  }
+
+  /**
+   * Get the base URL for sandbox connections
+   */
+  getBaseUrl(): string {
+    return this.baseUrl;
+  }
+
+  /**
+   * Get a preview of the API key (for display/debugging)
+   */
+  getApiKeyPreview(): string {
+    if (this.apiKey.length > 10) {
+      return `${this.apiKey.substring(0, 6)}...${this.apiKey.substring(this.apiKey.length - 4)}`;
+    }
+    return '***';
+  }
+}

package/connectors/connect-e2b/src/api/code.ts

@@ -0,0 +1,188 @@
+import type { E2BClient } from './client';
+import type {
+  ExecutionResult,
+  ExecuteCodeOptions,
+  ExecuteCommandOptions,
+  ProcessInfo,
+} from '../types';
+
+/**
+ * Code Execution API - Execute code and commands in E2B sandboxes
+ */
+export class CodeApi {
+  constructor(private readonly client: E2BClient) {}
+
+  /**
+   * Execute code in a sandbox
+   * @param sandboxId - The sandbox ID
+   * @param options - Code execution options
+   * @returns Execution result with stdout/stderr
+   */
+  async execute(sandboxId: string, options: ExecuteCodeOptions): Promise<ExecutionResult> {
+    const body: Record<string, unknown> = {
+      code: options.code,
+    };
+
+    if (options.language) {
+      body.language = options.language;
+    }
+    if (options.workDir) {
+      body.workDir = options.workDir;
+    }
+    if (options.envs) {
+      body.envVars = options.envs;
+    }
+    if (options.timeout !== undefined) {
+      body.timeout = options.timeout;
+    }
+
+    return this.client.post<ExecutionResult>(`/sandboxes/${sandboxId}/code`, body);
+  }
+
+  /**
+   * Execute code with a specific language (convenience method)
+   * @param sandboxId - The sandbox ID
+   * @param code - The code to execute
+   * @param language - Programming language
+   */
+  async executeCode(sandboxId: string, code: string, language?: string): Promise<ExecutionResult> {
+    return this.execute(sandboxId, { code, language });
+  }
+
+  /**
+   * Execute Python code
+   * @param sandboxId - The sandbox ID
+   * @param code - Python code to execute
+   */
+  async python(sandboxId: string, code: string): Promise<ExecutionResult> {
+    return this.execute(sandboxId, { code, language: 'python' });
+  }
+
+  /**
+   * Execute JavaScript code
+   * @param sandboxId - The sandbox ID
+   * @param code - JavaScript code to execute
+   */
+  async javascript(sandboxId: string, code: string): Promise<ExecutionResult> {
+    return this.execute(sandboxId, { code, language: 'javascript' });
+  }
+
+  /**
+   * Execute a file in the sandbox
+   * @param sandboxId - The sandbox ID
+   * @param filePath - Path to the file to execute
+   * @param options - Additional execution options
+   */
+  async executeFile(sandboxId: string, filePath: string, options: Partial<ExecuteCodeOptions> = {}): Promise<ExecutionResult> {
+    // Determine language from file extension
+    const ext = filePath.split('.').pop()?.toLowerCase();
+    const languageMap: Record<string, string> = {
+      'py': 'python',
+      'js': 'javascript',
+      'ts': 'typescript',
+      'sh': 'bash',
+      'bash': 'bash',
+      'go': 'go',
+      'rs': 'rust',
+      'java': 'java',
+      'php': 'php',
+      'pl': 'perl',
+      'cs': 'dotnet',
+    };
+
+    const language = ext ? languageMap[ext] : undefined;
+
+    // Execute file via command
+    return this.runCommand(sandboxId, {
+      command: this.getRunCommand(filePath, language),
+      workDir: options.workDir,
+      envs: options.envs,
+      timeout: options.timeout,
+    });
+  }
+
+  /**
+   * Run a shell command in the sandbox
+   * @param sandboxId - The sandbox ID
+   * @param options - Command execution options
+   */
+  async runCommand(sandboxId: string, options: ExecuteCommandOptions): Promise<ExecutionResult> {
+    const body: Record<string, unknown> = {
+      command: options.command,
+    };
+
+    if (options.workDir) {
+      body.workDir = options.workDir;
+    }
+    if (options.envs) {
+      body.envVars = options.envs;
+    }
+    if (options.timeout !== undefined) {
+      body.timeout = options.timeout;
+    }
+    if (options.background) {
+      body.background = options.background;
+    }
+
+    return this.client.post<ExecutionResult>(`/sandboxes/${sandboxId}/commands`, body);
+  }
+
+  /**
+   * Run a command in the background
+   * @param sandboxId - The sandbox ID
+   * @param command - The command to run
+   */
+  async runBackground(sandboxId: string, command: string): Promise<ProcessInfo> {
+    return this.client.post<ProcessInfo>(`/sandboxes/${sandboxId}/commands`, {
+      command,
+      background: true,
+    });
+  }
+
+  /**
+   * List running processes in the sandbox
+   * @param sandboxId - The sandbox ID
+   */
+  async listProcesses(sandboxId: string): Promise<ProcessInfo[]> {
+    return this.client.get<ProcessInfo[]>(`/sandboxes/${sandboxId}/processes`);
+  }
+
+  /**
+   * Kill a process in the sandbox
+   * @param sandboxId - The sandbox ID
+   * @param pid - Process ID to kill
+   */
+  async killProcess(sandboxId: string, pid: number): Promise<void> {
+    await this.client.delete(`/sandboxes/${sandboxId}/processes/${pid}`);
+  }
+
+  /**
+   * Get the appropriate run command for a file based on language
+   */
+  private getRunCommand(filePath: string, language?: string): string {
+    switch (language) {
+      case 'python':
+        return `python3 ${filePath}`;
+      case 'javascript':
+        return `node ${filePath}`;
+      case 'typescript':
+        return `npx ts-node ${filePath}`;
+      case 'bash':
+        return `bash ${filePath}`;
+      case 'go':
+        return `go run ${filePath}`;
+      case 'rust':
+        return `rustc ${filePath} -o /tmp/out && /tmp/out`;
+      case 'java':
+        return `java ${filePath}`;
+      case 'php':
+        return `php ${filePath}`;
+      case 'perl':
+        return `perl ${filePath}`;
+      case 'dotnet':
+        return `dotnet run ${filePath}`;
+      default:
+        return filePath;
+    }
+  }
+}