TypeScript client library for connecting to the Vreko local coordination service (vrekod) via IPC.

Features

• Type-safe API: Full TypeScript support with typed method wrappers
• Auto-reconnection: Exponential backoff reconnection strategy
• Request correlation: Automatic request/response matching with timeout handling
• Event-driven: Subscribe to connection state changes and server notifications
• Cross-platform: Unix sockets (macOS/Linux) and named pipes (Windows)

Installation

pnpm add @vreko/local-service-client

Quick Start

import { VrekoLocalClient } from '@vreko/local-service-client';

// Create client
const client = new VrekoLocalClient();

// Connect to service
await client.connect();

// Initialize protocol
await client.initialize({
  protocolVersion: '1.0.0',
  clientInfo: {
    name: 'my-app',
    version: '1.0.0'
  }
});

// Use type-safe methods
const snapshot = await client.snapshot.create({
  filePath: '/path/to/file.ts',
  content: 'const x = 1;',
  trigger: 'save'
});

console.log('Created snapshot:', snapshot.id);

// Clean up
client.close();

API

Client Options

interface ClientOptions {
  socketPath?: string;           // Default: platform-specific
  timeout?: number;               // Default: 30000ms
  autoReconnect?: boolean;        // Default: true
  maxReconnectAttempts?: number;  // Default: 5
  reconnectDelay?: number;        // Default: 1000ms
  maxReconnectDelay?: number;     // Default: 30000ms
}

Method Namespaces

Health

// Check service health
const health = await client.health.check({ verbose: true });

// Simple ping
const pong = await client.health.ping();

Session

// Get current session
const { session } = await client.session.current();

// Start new session
const newSession = await client.session.start({
  workspacePath: '/path/to/workspace'
});

// End session
await client.session.end();

// List sessions
const { sessions } = await client.session.list({ limit: 10 });

Snapshot

// Create snapshot
const snapshot = await client.snapshot.create({
  filePath: '/path/to/file.ts',
  content: 'code here',
  trigger: 'save'
});

// Get snapshot
const vreko = await client.snapshot.get({
  snapshotId: 'vreko-123',
  includeContent: true
});

// List snapshots
const { snapshots } = await client.snapshot.list({
  filePath: '/path/to/file.ts',
  limit: 50
});

// Restore snapshot
const restored = await client.snapshot.restore({
  snapshotId: 'vreko-123',
  createBackup: true
});

// Diff snapshots
const diff = await client.snapshot.diff({
  baseSnapshotId: 'vreko-123',
  compareSnapshotId: 'vreko-456'
});

// Delete snapshots
await client.snapshot.delete({
  snapshotIds: ['vreko-123', 'vreko-456']
});

Protection

// Evaluate protection policy
const decision = await client.protection.evaluate({
  filePath: '/path/to/file.ts'
});

// Get protection levels
const { levels } = await client.protection.levels({
  filePaths: ['/path/to/file1.ts', '/path/to/file2.ts']
});

// Set protection level
await client.protection.set({
  filePath: '/path/to/file.ts',
  level: 'warn',
  scope: 'file'
});

Detection

// Check for AI activity
const result = await client.detection.check({
  filePath: '/path/to/file.ts',
  content: 'new content',
  previousContent: 'old content'
});

console.log('AI detected:', result.detected, 'confidence:', result.confidence);

Events

// Connection state changes
client.on('stateChange', (state) => {
  console.log('State:', state); // 'disconnected' | 'connecting' | 'connected' | 'reconnecting' | 'closed'
});

// Connection established
client.on('connected', () => {
  console.log('Connected to service');
});

// Connection lost
client.on('disconnected', (error) => {
  console.log('Disconnected:', error?.message);
});

// Reconnection attempts
client.on('reconnecting', (attempt, maxAttempts) => {
  console.log(`Reconnecting (${attempt}/${maxAttempts})...`);
});

// Server notifications
client.on('notification', (method, params) => {
  console.log('Notification:', method, params);
});

// Errors
client.on('error', (error) => {
  console.error('Error:', error);
});

Error Handling

import { JsonRpcClientError, RequestTimeoutError, ConnectionTimeoutError } from '@vreko/local-service-client';

try {
  await client.snapshot.create({ ... });
} catch (error) {
  if (error instanceof JsonRpcClientError) {
    console.error('Server error:', error.code, error.message, error.data);
  } else if (error instanceof RequestTimeoutError) {
    console.error('Request timed out');
  } else if (error instanceof ConnectionTimeoutError) {
    console.error('Connection timed out');
  }
}

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Run tests
pnpm test

# Type check
pnpm type-check

# Lint
pnpm lint

License

Apache-2.0