@computesdk/vercel 1.0.0 → 1.1.1

package/README.md

@@ -1,6 +1,6 @@
 # @computesdk/vercel
 
-Vercel Sandbox provider for ComputeSDK - Execute Node.js and Python code in secure, isolated Vercel sandboxes.
+Vercel provider for ComputeSDK - Execute Node.js and Python code in secure, isolated Vercel sandboxes.
 
 ## Installation
 
@@ -8,187 +8,254 @@ Vercel Sandbox provider for ComputeSDK - Execute Node.js and Python code in secu
 npm install @computesdk/vercel
 ```
 
-## Prerequisites
+## Authentication
 
-You need the following environment variables set:
+Vercel provider supports two authentication methods:
 
-- `VERCEL_TOKEN` - Your Vercel access token (get from [Vercel Account Tokens](https://vercel.com/account/tokens))
-- `VERCEL_TEAM_ID` - Your Vercel team ID
-- `VERCEL_PROJECT_ID` - Your Vercel project ID
+### Method 1: OIDC Token (Recommended)
 
-## Quick Start
+The simplest way to authenticate. Vercel manages token expiration automatically.
 
-### Basic Usage
+**Development:**
+```bash
+vercel env pull  # Downloads VERCEL_OIDC_TOKEN to .env.local
+```
 
-```typescript
-import { vercel } from '@computesdk/vercel';
+**Production:** Vercel automatically provides `VERCEL_OIDC_TOKEN` in your deployment environment.
 
-// Create sandbox with default Node.js runtime
-const sandbox = vercel();
+### Method 2: Access Token + Team/Project IDs
 
-// Execute Node.js code
-const result = await sandbox.doExecute('console.log("Hello from Vercel!");');
-console.log(result.stdout); // "Hello from Vercel!"
+Alternative method using explicit credentials:
 
-// Clean up
-await sandbox.doKill();
+```bash
+export VERCEL_TOKEN=your_vercel_token_here
+export VERCEL_TEAM_ID=your_team_id_here
+export VERCEL_PROJECT_ID=your_project_id_here
 ```
 
-### Python Runtime
+Get your token from [Vercel Account Tokens](https://vercel.com/account/tokens)
+
+## Usage
+
+### With ComputeSDK
 
 ```typescript
+import { compute } from 'computesdk';
 import { vercel } from '@computesdk/vercel';
 
-// Create sandbox with Python runtime
-const sandbox = vercel({ runtime: 'python' });
+// Set as default provider
+compute.setConfig({ 
+  provider: vercel({ runtime: 'node' }) 
+});
+
+// Create sandbox
+const sandbox = await compute.sandbox.create({});
+
+// Execute Node.js code
+const result = await sandbox.runCode('console.log("Hello from Vercel!");');
+console.log(result.stdout); // "Hello from Vercel!"
 
 // Execute Python code
-const result = await sandbox.doExecute('print("Hello from Python on Vercel!")');
-console.log(result.stdout); // "Hello from Python on Vercel!"
+const pythonResult = await sandbox.runCode('print("Hello from Python!")', 'python');
+console.log(pythonResult.stdout); // "Hello from Python!"
 
-await sandbox.doKill();
+// Clean up
+await compute.sandbox.destroy(sandbox.sandboxId);
 ```
 
-### With ComputeSDK
+### Direct Usage
 
 ```typescript
 import { vercel } from '@computesdk/vercel';
-import { executeSandbox } from 'computesdk';
 
-// One-off execution
-const result = await executeSandbox({
-  sandbox: vercel({ runtime: 'python' }),
-  code: `
-import json
-import datetime
-
-data = {
-    "timestamp": datetime.datetime.now().isoformat(),
-    "message": "Hello from Vercel Sandbox"
-}
-
-print(json.dumps(data, indent=2))
-  `
+// Create provider with explicit config
+const provider = vercel({
+  token: 'your-token',
+  teamId: 'your-team-id', 
+  projectId: 'your-project-id',
+  runtime: 'python',
+  timeout: 600000 // 10 minutes
 });
 
-console.log(result.stdout);
+// Use with compute singleton
+const sandbox = await compute.sandbox.create({ provider });
 ```
 
 ## Configuration
 
-### Options
+### Environment Variables
 
-```typescript
-interface SandboxConfig {
-  runtime?: 'node' | 'python';  // Default: 'node'
-  timeout?: number;              // Default: 300000 (5 minutes)
-  provider?: string;             // Default: 'vercel'
-}
+```bash
+# Method 1: OIDC Token (Recommended)
+export VERCEL_OIDC_TOKEN=your_oidc_token_here
+
+# Method 2: Traditional
+export VERCEL_TOKEN=your_vercel_token_here
+export VERCEL_TEAM_ID=your_team_id_here
+export VERCEL_PROJECT_ID=your_project_id_here
 ```
 
-### Example with Custom Configuration
+### Configuration Options
 
 ```typescript
-const sandbox = vercel({
-  runtime: 'python',
-  timeout: 600000,  // 10 minutes
-});
+interface VercelConfig {
+  /** Vercel API token - if not provided, will use VERCEL_TOKEN env var */
+  token?: string;
+  /** Vercel team ID - if not provided, will use VERCEL_TEAM_ID env var */
+  teamId?: string;
+  /** Vercel project ID - if not provided, will use VERCEL_PROJECT_ID env var */
+  projectId?: string;
+  /** Default runtime environment */
+  runtime?: 'node' | 'python';
+  /** Execution timeout in milliseconds */
+  timeout?: number;
+}
 ```
 
 ## Features
 
-### Supported Runtimes
+- ✅ **Code Execution** - Node.js 22 and Python 3.13 runtime support
+- ✅ **Command Execution** - Run shell commands in sandbox
+- ✅ **Filesystem Operations** - Full file system access via shell commands
+- ✅ **Auto Runtime Detection** - Automatically detects Python vs Node.js
+- ✅ **Long-running Tasks** - Up to 45 minutes execution time
+- ✅ **Global Infrastructure** - Runs on Vercel's global network
+- ❌ **Interactive Terminals** - Not supported by Vercel Sandbox
+- ❌ **Sandbox Reconnection** - Sandboxes are ephemeral (single-use)
+
+## API Reference
+
+### Code Execution
+
+```typescript
+// Execute Node.js code
+const result = await sandbox.runCode(`
+const data = { message: "Hello from Node.js" };
+console.log(JSON.stringify(data));
+`, 'node');
+
+// Execute Python code  
+const result = await sandbox.runCode(`
+import json
+data = {"message": "Hello from Python"}
+print(json.dumps(data))
+`, 'python');
 
-- **Node.js 22** (`node`) - Default runtime
-- **Python 3.13** (`python`) - Full Python environment
+// Auto-detection (based on code patterns)
+const result = await sandbox.runCode('print("Auto-detected as Python")');
+```
 
-### Capabilities
+### Command Execution
 
-- ✅ **Isolated execution** - Each sandbox runs in its own secure environment
-- ✅ **Long-running tasks** - Up to 45 minutes execution time
-- ✅ **Standard libraries** - Node.js and Python standard libraries included
-- ✅ **Error handling** - Comprehensive error reporting
-- ✅ **Stream support** - Real-time stdout/stderr capture
-- ✅ **Global deployment** - Runs on Vercel's global infrastructure
+```typescript
+// List files
+const result = await sandbox.runCommand('ls', ['-la']);
 
-### Limitations
+// Install packages (Node.js)
+const result = await sandbox.runCommand('npm', ['install', 'lodash']);
 
-- Maximum execution time: 45 minutes (configurable)
-- Maximum 8 vCPUs per sandbox (default: 2 vCPUs)
-- Memory allocation: 2048 MB per vCPU
+// Install packages (Python)
+const result = await sandbox.runCommand('pip', ['install', 'requests']);
 
-## API Reference
+// Run scripts
+const result = await sandbox.runCommand('node', ['script.js']);
+```
 
-### `vercel(config?)`
+### Filesystem Operations
 
-Creates a new Vercel sandbox provider.
+```typescript
+// Write file
+await sandbox.filesystem.writeFile('/tmp/hello.py', 'print("Hello World")');
 
-**Parameters:**
-- `config` (optional): Configuration object
+// Read file
+const content = await sandbox.filesystem.readFile('/tmp/hello.py');
 
-**Returns:** `VercelProvider` instance
+// Create directory
+await sandbox.filesystem.mkdir('/tmp/data');
 
-### `sandbox.doExecute(code, runtime?)`
+// List directory contents
+const files = await sandbox.filesystem.readdir('/tmp');
 
-Executes code in the sandbox.
+// Check if file exists
+const exists = await sandbox.filesystem.exists('/tmp/hello.py');
 
-**Parameters:**
-- `code`: String containing the code to execute
-- `runtime` (optional): Runtime to use ('node' | 'python')
+// Remove file or directory
+await sandbox.filesystem.remove('/tmp/hello.py');
+```
 
-**Returns:** `Promise<ExecutionResult>`
+### Sandbox Management
 
 ```typescript
-interface ExecutionResult {
-  stdout: string;
-  stderr: string;
-  exitCode: number;
-  executionTime: number;
-  sandboxId: string;
-  provider: string;
-}
+// Get sandbox info
+const info = await sandbox.getInfo();
+console.log(info.id, info.provider, info.status);
+
+// Get existing sandbox
+const existing = await compute.sandbox.getById(provider, 'sandbox-id');
+
+// Destroy sandbox
+await compute.sandbox.destroy(provider, 'sandbox-id');
+
+// Note: Vercel doesn't support listing all sandboxes
+// Each sandbox is ephemeral and single-use
 ```
 
-### `sandbox.doGetInfo()`
+## Runtime Detection
+
+The provider automatically detects the runtime based on code patterns:
+
+**Python indicators:**
+- `print(` statements
+- `import` statements  
+- `def` function definitions
+- Python-specific syntax (`f"`, `__`, etc.)
 
-Gets information about the sandbox.
+**Default:** Node.js for all other cases
 
-**Returns:** `Promise<SandboxInfo>`
+## Error Handling
 
 ```typescript
-interface SandboxInfo {
-  id: string;
-  provider: string;
-  runtime: string;
-  status: 'running' | 'stopped';
-  createdAt: Date;
-  timeout: number;
-  metadata: {
-    vercelSandboxId: string;
-    teamId: string;
-    projectId: string;
-    vcpus: number;
-    region: string;
-  };
+try {
+  const result = await sandbox.runCode('invalid code');
+} catch (error) {
+  if (error.message.includes('Missing Vercel authentication')) {
+    console.error('Set VERCEL_OIDC_TOKEN or VERCEL_TOKEN environment variables');
+  } else if (error.message.includes('authentication failed')) {
+    console.error('Check your Vercel credentials');
+  } else if (error.message.includes('team/project configuration failed')) {
+    console.error('Check your VERCEL_TEAM_ID and VERCEL_PROJECT_ID');
+  } else if (error.message.includes('Syntax error')) {
+    console.error('Code has syntax errors');
+  }
 }
 ```
 
-### `sandbox.doKill()`
+## Web Framework Integration
+
+Use with web frameworks via the request handler:
 
-Terminates the sandbox.
+```typescript
+import { handleComputeRequest } from 'computesdk';
+import { vercel } from '@computesdk/vercel';
 
-**Returns:** `Promise<void>`
+export async function POST(request: Request) {
+  return handleComputeRequest({
+    request,
+    provider: vercel({ runtime: 'node' })
+  });
+}
+```
 
 ## Examples
 
 ### Node.js Web Server Simulation
 
 ```typescript
-import { vercel } from '@computesdk/vercel';
-
-const sandbox = vercel({ runtime: 'node' });
+const sandbox = await compute.sandbox.create({
+  provider: vercel({ runtime: 'node' })
+});
 
-const result = await sandbox.doExecute(`
+const result = await sandbox.runCode(`
 const http = require('http');
 const url = require('url');
 
@@ -200,7 +267,10 @@ const routes = {
       { id: 2, name: 'Bob', role: 'Designer' }
     ]
   }),
-  '/api/health': () => ({ status: 'healthy', timestamp: new Date().toISOString() })
+  '/api/health': () => ({ 
+    status: 'healthy', 
+    timestamp: new Date().toISOString() 
+  })
 };
 
 // Process request
@@ -216,11 +286,11 @@ console.log(result.stdout);
 ### Python Data Processing
 
 ```typescript
-import { vercel } from '@computesdk/vercel';
-
-const sandbox = vercel({ runtime: 'python' });
+const sandbox = await compute.sandbox.create({
+  provider: vercel({ runtime: 'python' })
+});
 
-const result = await sandbox.doExecute(`
+const result = await sandbox.runCode(`
 import json
 import statistics
 from collections import Counter
@@ -256,81 +326,179 @@ for product, revenue in sorted(product_sales.items(), key=lambda x: x[1], revers
 console.log(result.stdout);
 ```
 
-## Error Handling
-
-The provider includes comprehensive error handling:
+### Filesystem Operations Pipeline
 
 ```typescript
-import { vercel } from '@computesdk/vercel';
+const sandbox = await compute.sandbox.create({
+  provider: vercel({ runtime: 'python' })
+});
 
-try {
-  const sandbox = vercel();
-  const result = await sandbox.doExecute('invalid syntax here');
-} catch (error) {
-  if (error.message.includes('timeout')) {
-    console.error('Execution timed out');
-  } else if (error.message.includes('memory')) {
-    console.error('Memory limit exceeded');
-  } else if (error.message.includes('authentication')) {
-    console.error('Check your VERCEL_TOKEN');
-  } else {
-    console.error('Execution failed:', error.message);
+// Create project structure
+await sandbox.filesystem.mkdir('/tmp/project');
+await sandbox.filesystem.mkdir('/tmp/project/data');
+await sandbox.filesystem.mkdir('/tmp/project/output');
+
+// Create configuration file
+const config = {
+  project_name: "Vercel Data Pipeline",
+  version: "1.0.0",
+  settings: {
+    input_format: "json",
+    output_format: "csv",
+    debug: true
   }
-}
-```
+};
 
-## Authentication Setup
+await sandbox.filesystem.writeFile(
+  '/tmp/project/config.json', 
+  JSON.stringify(config, null, 2)
+);
+
+// Create sample data
+const sampleData = [
+  { id: 1, name: "Alice", department: "Engineering", salary: 95000 },
+  { id: 2, name: "Bob", department: "Marketing", salary: 75000 },
+  { id: 3, name: "Charlie", department: "Engineering", salary: 105000 },
+  { id: 4, name: "Diana", department: "Sales", salary: 85000 }
+];
+
+await sandbox.filesystem.writeFile(
+  '/tmp/project/data/employees.json',
+  JSON.stringify(sampleData, null, 2)
+);
+
+// Process data
+const result = await sandbox.runCode(`
+import json
+import csv
+from collections import defaultdict
+
+# Read configuration
+with open('/tmp/project/config.json', 'r') as f:
+    config = json.load(f)
+
+print(f"Running {config['project_name']} v{config['version']}")
+
+# Read employee data
+with open('/tmp/project/data/employees.json', 'r') as f:
+    employees = json.load(f)
+
+# Process data - calculate department statistics
+dept_stats = defaultdict(list)
+for emp in employees:
+    dept_stats[emp['department']].append(emp['salary'])
+
+# Calculate averages
+results = []
+for dept, salaries in dept_stats.items():
+    avg_salary = sum(salaries) / len(salaries)
+    results.append({
+        'department': dept,
+        'employee_count': len(salaries),
+        'average_salary': round(avg_salary, 2),
+        'total_salary': sum(salaries)
+    })
+
+# Sort by average salary
+results.sort(key=lambda x: x['average_salary'], reverse=True)
+
+# Write results as JSON
+with open('/tmp/project/output/department_stats.json', 'w') as f:
+    json.dump(results, f, indent=2)
+
+# Write results as CSV
+with open('/tmp/project/output/department_stats.csv', 'w', newline='') as f:
+    writer = csv.DictWriter(f, fieldnames=['department', 'employee_count', 'average_salary', 'total_salary'])
+    writer.writeheader()
+    writer.writerows(results)
+
+print("Processing complete!")
+print(f"Generated {len(results)} department statistics")
+
+# Print summary
+for result in results:
+    print(f"{result['department']}: {result['employee_count']} employees, avg salary ${result['average_salary']}")
+`);
 
-1. **Get Vercel Token:**
-   - Go to [Vercel Account Tokens](https://vercel.com/account/tokens)
-   - Create a new token with appropriate permissions
-   - Set as `VERCEL_TOKEN` environment variable
+console.log('Execution Output:', result.stdout);
 
-2. **Get Team and Project IDs:**
-   - Find your team ID in the Vercel dashboard URL
-   - Find your project ID in the project settings
-   - Set as `VERCEL_TEAM_ID` and `VERCEL_PROJECT_ID`
+// Read and display results
+const jsonResults = await sandbox.filesystem.readFile('/tmp/project/output/department_stats.json');
+const csvResults = await sandbox.filesystem.readFile('/tmp/project/output/department_stats.csv');
 
-3. **Environment Variables:**
-   ```bash
-   export VERCEL_TOKEN=your_vercel_token_here
-   export VERCEL_TEAM_ID=your_team_id_here
-   export VERCEL_PROJECT_ID=your_project_id_here
-   ```
+console.log('JSON Results:', jsonResults);
+console.log('CSV Results:', csvResults);
 
-## Testing
+// List all generated files
+const outputFiles = await sandbox.filesystem.readdir('/tmp/project/output');
+console.log('Generated files:');
+outputFiles.forEach(file => {
+  console.log(`  ${file.name} (${file.size} bytes)`);
+});
+```
 
-Run the test suite:
+### Package Installation and Usage
 
-```bash
-npm test
-```
+```typescript
+// Node.js example with package installation
+const sandbox = await compute.sandbox.create({
+  provider: vercel({ runtime: 'node' })
+});
 
-Run tests with coverage:
+// Install lodash
+const installResult = await sandbox.runCommand('npm', ['install', 'lodash']);
+console.log('Install result:', installResult.stdout);
 
-```bash
-npm run test:coverage
-```
+// Use lodash in code
+const result = await sandbox.runCode(`
+const _ = require('lodash');
 
-## Development
+const data = [
+  { name: 'Alice', age: 25, city: 'New York' },
+  { name: 'Bob', age: 30, city: 'San Francisco' },
+  { name: 'Charlie', age: 35, city: 'Chicago' }
+];
 
-Build the package:
+// Group by city
+const grouped = _.groupBy(data, 'city');
+console.log('Grouped by city:', JSON.stringify(grouped, null, 2));
 
-```bash
-npm run build
-```
+// Calculate average age
+const avgAge = _.meanBy(data, 'age');
+console.log('Average age:', avgAge);
 
-Run in development mode:
+// Find oldest person
+const oldest = _.maxBy(data, 'age');
+console.log('Oldest person:', oldest.name);
+`);
 
-```bash
-npm run dev
+console.log(result.stdout);
 ```
 
-## License
+## Best Practices
+
+1. **Authentication**: Use OIDC token method when possible for simpler setup
+2. **Resource Management**: Destroy sandboxes when done (they're ephemeral anyway)
+3. **Error Handling**: Use try-catch blocks for robust error handling
+4. **Timeouts**: Set appropriate timeouts for long-running tasks (up to 45 minutes)
+5. **File Organization**: Use the filesystem API to organize project files
+6. **Package Installation**: Install packages at runtime as needed
+
+## Limitations
 
-MIT - see LICENSE file for details.
+- **Ephemeral Sandboxes**: Each sandbox is single-use and cannot be reconnected to
+- **No Sandbox Listing**: Vercel doesn't support listing all sandboxes
+- **No Interactive Terminals**: Terminal operations are not supported
+- **Memory Limits**: Subject to Vercel sandbox memory constraints (2048 MB per vCPU)
+- **Execution Time**: Maximum 45 minutes execution time
+- **Network Access**: Limited outbound network access
 
 ## Support
 
-- [GitHub Issues](https://github.com/computesdk/computesdk/issues)
-- [ComputeSDK Documentation](https://github.com/computesdk/computesdk)
+- [Vercel Documentation](https://vercel.com/docs)
+- [ComputeSDK Issues](https://github.com/computesdk/computesdk/issues)
+- [Vercel Support](https://vercel.com/support)
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -1,21 +1,24 @@
-import { ComputeSpecification, SandboxConfig, Runtime, ExecutionResult, SandboxInfo } from 'computesdk';
+import * as computesdk from 'computesdk';
+import { Runtime } from 'computesdk';
 
-declare class VercelProvider implements ComputeSpecification {
-    readonly specificationVersion: "v1";
-    readonly provider = "vercel";
-    readonly sandboxId: string;
-    private sandbox;
-    private readonly token;
-    private readonly teamId;
-    private readonly projectId;
-    private readonly runtime;
-    private readonly timeout;
-    constructor(config: SandboxConfig);
-    private ensureSandbox;
-    doExecute(code: string, runtime?: Runtime): Promise<ExecutionResult>;
-    doKill(): Promise<void>;
-    doGetInfo(): Promise<SandboxInfo>;
+/**
+ * Vercel-specific configuration options
+ */
+interface VercelConfig {
+    /** Vercel API token - if not provided, will fallback to VERCEL_TOKEN environment variable */
+    token?: string;
+    /** Vercel team ID - if not provided, will fallback to VERCEL_TEAM_ID environment variable */
+    teamId?: string;
+    /** Vercel project ID - if not provided, will fallback to VERCEL_PROJECT_ID environment variable */
+    projectId?: string;
+    /** Default runtime environment */
+    runtime?: Runtime;
+    /** Execution timeout in milliseconds */
+    timeout?: number;
 }
-declare function vercel(config?: Partial<SandboxConfig>): VercelProvider;
+/**
+ * Create a Vercel provider instance using the factory pattern
+ */
+declare const vercel: (config: VercelConfig) => computesdk.Provider;
 
-export { VercelProvider, vercel };
+export { type VercelConfig, vercel };