@epic-flow/obs-client

TypeScript SDK for Epic Flow Observability Platform - shared client library for CLI and MCP integrations.

Overview

This package provides a type-safe, promise-based SDK for interacting with the Epic Flow Observability Platform. It is designed to be used by both the FlowState CLI and MCP (Model Context Protocol) server, ensuring consistent behavior across both human and AI interactions.

Current Phase: MVP (Phase 1) - REST API support for errors, logs, sessions, and projects

Coming in Phase 3: Real-time streaming support via WebSockets for live error/log tailing and event monitoring.

Installation

yarn add @epic-flow/obs-client

Usage

Basic Setup

import { ObsClient } from '@epic-flow/obs-client';

const client = new ObsClient({
  serverUrl: 'http://localhost:7081',
  apiKey: 'your-api-key',
  timeout: 30000,  // Optional: request timeout in ms (default: 30000)
  retries: 3,      // Optional: retry attempts (default: 3)
});

Querying Errors

// List errors with filters
const response = await client.errors.list({
  projectId: 'my-project-id',
  level: 'fatal',
  from: Date.now() - 86400000, // Last 24 hours
  limit: 50,
});

console.log(`Found ${response.total} errors`);
response.errors.forEach(error => {
  console.log(`${error.level}: ${error.message}`);
});

// Get detailed error information
const error = await client.errors.get('error-id');
console.log(error.stackTrace);

// Get error statistics
const stats = await client.errors.stats('my-project-id', {
  from: Date.now() - 604800000, // Last 7 days
  groupBy: 'day',
});
console.log(`Total errors: ${stats.totalErrors}`);
console.log(`Error rate: ${stats.errorRate} errors/hour`);

Querying Logs

// List logs
const logs = await client.logs.list({
  projectId: 'my-project-id',
  level: 'error',
  search: 'database',
  limit: 100,
});

// Get specific log
const log = await client.logs.get('log-id');

Managing Sessions

// List sessions
const sessions = await client.sessions.list({
  projectId: 'my-project-id',
  userId: 'user-123',
  limit: 20,
});

// Get session details
const session = await client.sessions.get('session-id');

// Get session breadcrumbs for debugging
const breadcrumbs = await client.sessions.getBreadcrumbs('session-id');
breadcrumbs.forEach(bc => {
  console.log(`[${bc.type}] ${bc.message}`);
});

Managing Projects

// Create a new project
const project = await client.projects.create({
  name: 'my-app',
  description: 'Production monitoring for my app',
  settings: {
    retentionDays: 30,
  },
});
console.log(`API Key: ${project.apiKey}`);

// List all projects
const projects = await client.projects.list();

// Update project
await client.projects.update(project.id, {
  description: 'Updated description',
});

// Get project statistics
const stats = await client.projects.stats(project.id, {
  from: Date.now() - 2592000000, // Last 30 days
});

// Delete project
await client.projects.delete(project.id);

API Reference

ObsClient

Main client class providing access to all resources.

class ObsClient {
  constructor(config: ObsClientConfig);

  readonly errors: ErrorsResource;
  readonly logs: LogsResource;
  readonly sessions: SessionsResource;
  readonly projects: ProjectsResource;
}

ErrorsResource

Manages error event operations.

• list(filters: ErrorFilters): Promise<ErrorListResponse>
• get(id: string): Promise<ErrorEvent>
• stats(projectId: string, options?: StatsOptions): Promise<ErrorStats>

LogsResource

Manages log event operations.

• list(filters: LogFilters): Promise<LogListResponse>
• get(id: string): Promise<LogEvent>

SessionsResource

Manages session operations.

• list(filters: SessionFilters): Promise<SessionListResponse>
• get(id: string): Promise<Session>
• getBreadcrumbs(id: string): Promise<Breadcrumb[]>

ProjectsResource

Manages project operations.

• create(input: CreateProjectInput): Promise<Project>
• list(): Promise<Project[]>
• get(id: string): Promise<Project>
• update(id: string, input: UpdateProjectInput): Promise<Project>
• delete(id: string): Promise<{ success: boolean }>
• stats(id: string, options?: StatsOptions): Promise<ProjectStats>

Error Handling

The SDK provides specific error classes for different failure scenarios:

import { AuthError, NotFoundError, RateLimitError, ApiError } from '@epic-flow/obs-client';

try {
  await client.errors.list({ projectId: 'invalid' });
} catch (error) {
  if (error instanceof AuthError) {
    console.error('Invalid API key');
  } else if (error instanceof NotFoundError) {
    console.error('Resource not found');
  } else if (error instanceof RateLimitError) {
    console.error('Rate limit exceeded');
  } else if (error instanceof ApiError) {
    console.error('API error:', error.message);
  }
}

TypeScript Support

This package is written in TypeScript and provides comprehensive type definitions. All types are exported from the main entry point:

import type {
  ObsClientConfig,
  ErrorEvent,
  LogEvent,
  Session,
  Project,
  // ... and more
} from '@epic-flow/obs-client';

Development

# Install dependencies
yarn install

# Build the package
yarn build

# Run tests
yarn test

# Run tests in watch mode
yarn test:watch

# Type checking
yarn typecheck

# Lint
yarn lint

Architecture

This SDK is designed as a shared library used by:

1. FlowState CLI - Terminal commands for developers
2. FlowState MCP - AI-assisted debugging via Claude

By sharing the same SDK, both interfaces provide consistent functionality and behavior.

License

MIT

Contributing

See CONTRIBUTING.md for details.