@vibeship/api-client

Unified API client for all Vibeship DevTools operations.

Installation

npm install @vibeship/api-client

Usage

import { createVibeshipAPIClient } from '@vibeship/api-client';

// Create a client instance
const client = createVibeshipAPIClient({
  baseUrl: '/api/vibeship',
  apiKey: 'your-api-key',
  onError: (error) => console.error('API Error:', error),
});

// Fetch tasks
const tasksResponse = await client.tasks.list({
  path: './src',
  types: 'todo,fixme',
  limit: 100
});

if (tasksResponse.success) {
  console.log('Tasks:', tasksResponse.data);
}

// Read a file
const fileResponse = await client.files.read('./README.md');

if (fileResponse.success) {
  console.log('File content:', fileResponse.data.content);
}

// Stream tasks in real-time
const unsubscribe = client.tasks.stream((tasks) => {
  console.log('Tasks updated:', tasks);
});

// Later: stop streaming
unsubscribe();

API Reference

Client Configuration

interface VibeshipAPIClientConfig {
  baseUrl?: string;          // API base URL (default: '/api/vibeship')
  apiKey?: string;           // API key for authentication
  headers?: Record<string, string>; // Additional headers
  timeout?: number;          // Request timeout in ms (default: 30000)
  onError?: (error: APIError) => void;
  onRequest?: (url: string, options: RequestInit) => void;
  onResponse?: (response: Response, data: any) => void;
}

Tasks API

• list(options) - List tasks with optional filters
• get(id) - Get a specific task
• update(id, updates) - Update a task
• stream(onUpdate) - Stream task updates in real-time

Files API

• list(pattern) - List files matching a pattern
• read(path) - Read file content
• write(path, content) - Write file content
• delete(path) - Delete a file
• watch(onChange) - Watch for file changes

Config API

• get() - Get current configuration
• update(config) - Update configuration
• validate(config) - Validate configuration

AI API

• chat(messages, options) - Send chat messages
• complete(prompt, options) - Get text completion
• stream(messages, onChunk, options) - Stream chat responses

Error Handling

All API methods return an APIResponse object:

interface APIResponse<T> {
  success: boolean;
  data?: T;
  error?: APIError;
  metadata?: ResponseMetadata;
}

Always check the success field before accessing data:

const response = await client.tasks.list();

if (response.success) {
  // Handle success
  console.log(response.data);
} else {
  // Handle error
  console.error(response.error);
}

Real-time Updates

Use the streaming methods for real-time updates:

// Stream tasks
const unsubscribeTasks = client.tasks.stream((tasks) => {
  // Handle task updates
});

// Watch files
const unsubscribeFiles = client.files.watch((event) => {
  // Handle file changes
});

// Stream AI responses
const unsubscribeAI = client.ai.stream(
  [{ role: 'user', content: 'Hello' }],
  (chunk) => {
    // Handle response chunks
  }
);

// Clean up when done
unsubscribeTasks();
unsubscribeFiles();
unsubscribeAI();