@orchard9ai/forge-api-client

TypeScript API client for the Forge Development System with support for multiple frameworks. Auto-generated from OpenAPI specification using Orval.

Features

• 🚀 Type-safe API client with full TypeScript support
• 🔄 Automatic retry logic for transient failures
• 🎯 Framework-specific integrations (React, Vue)
• 🧪 Built-in testing support with MSW
• ✅ Runtime validation with Zod schemas
• 🛡️ Comprehensive error handling for Forge ResponseStatus pattern
• 🆕 Request Management System (v1.1.0) - Complete audit, research, and requirement workflows
• ⚡ Real-time Events (v1.1.0) - WebSocket integration for live updates
• 🔧 Auto-healing YAML (v1.1.0) - Intelligent corruption detection and repair

Installation

npm install @orchard9ai/forge-api-client
# or
yarn add @orchard9ai/forge-api-client
# or
pnpm add @orchard9ai/forge-api-client

Quick Start

Vanilla TypeScript

import ForgeClient from '@orchard9ai/forge-api-client';

const client = new ForgeClient({
  baseURL: 'http://localhost:50052',
  timeout: 30000,
});

// List tasks
const tasks = await client.listTasks({
  project_id: 'my-project',
  status: 'in-progress',
});

// Create a task
const newTask = await client.createTask({
  title: 'Implement feature X',
  definition: 'Add new functionality for feature X',
  persona: 'principal-developer',
  version: '1.0.0',
});

// NEW in v1.1.0: Create an audit request
const auditRequest = await client.createAuditRequest({
  project_id: 'my-project',
  title: 'Security Review',
  description: 'Comprehensive security audit of authentication system',
  version: '1.1.0',
});

React

import { useListTasks, useCreateTask } from '@orchard9ai/forge-api-client/react';

function TaskList() {
  const { data, isLoading, error } = useListTasks({
    project_id: 'my-project',
  });
  
  const createTaskMutation = useCreateTask();
  
  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
  
  return (
    <div>
      {data?.tasks?.map(task => (
        <div key={task.id}>{task.title}</div>
      ))}
    </div>
  );
}

Vue

<script setup>
import { useListTasks } from '@orchard9ai/forge-api-client/vue';

const { data, isLoading, error } = useListTasks({
  project_id: 'my-project',
});

const tasks = computed(() => data.value?.tasks || []);
</script>

Error Handling

The client automatically handles Forge's ResponseStatus pattern:

try {
  const task = await client.getTask('task-123');
} catch (error) {
  if (error instanceof ForgeApiError) {
    console.error(`API Error ${error.code}: ${error.message}`);
    
    switch (error.code) {
      case 5: // NOT_FOUND
        console.log('Task not found');
        break;
      case 13: // INTERNAL
        console.log('Server error');
        break;
    }
  }
}

Advanced Features

Authentication

// Set bearer token
client.setAuthToken('your-jwt-token');

// Set custom headers
client.setHeaders({
  'X-API-Key': 'your-api-key',
});

Retry Logic

import { withRetry } from '@orchard9ai/forge-api-client';

const result = await withRetry(
  () => client.getTask('task-123'),
  3,    // max attempts
  1000  // initial delay
);

Testing with MSW

import { setupServer } from 'msw/node';
import { handlers } from '@orchard9ai/forge-api-client/mocks';

const server = setupServer(...handlers);

beforeAll(() => server.listen());
afterEach(() => server.resetHandlers());
afterAll(() => server.close());

Development

This client is auto-generated from the Forge OpenAPI specification using orval.

Regenerate Client

# Generate all SDK variants
npm run generate:all

# Generate specific targets
npm run generate:core   # TypeScript functions
npm run generate:react  # React hooks
npm run generate:vue    # Vue composables
npm run generate:msw    # MSW handlers
npm run generate:zod    # Zod schemas

# Watch mode
npm run generate:watch

Project Structure

src/
├── generated/          # Auto-generated code
│   ├── forge.ts       # Core API functions
│   ├── model/         # TypeScript types
│   ├── react/         # React hooks
│   ├── vue/           # Vue composables
│   ├── mocks/         # MSW handlers
│   └── zod/           # Validation schemas
├── mutators/          # Custom axios configuration
├── client.ts          # High-level client class
└── index.ts           # Main exports

Available Endpoints

The generated client includes functions for all Forge API endpoints:

• Projects: Create, list, get, update project metadata
• Tasks: Full CRUD operations, move tasks, manage dependencies
• Git: Create branches, pull requests, handle git hooks
• Agents: Manage AI agent contexts
• Activities: Track project activity
• Features: Manage features and their tasks
• Releases: Handle release management
• Docker: Container operations (build, publish, validate)
• Document Analysis: Analyze project documentation
• Dashboard: Get project statistics and summaries
• Requests: Complete audit, research, and requirement request lifecycle management

Examples

See the examples/ directory for complete examples:

• typescript-client-usage.ts - Vanilla TypeScript usage
• react-example.tsx - React with react-query
• vue-example.vue - Vue 3 composition API
• testing-with-msw.ts - Testing with Mock Service Worker
• request-management-example.ts - NEW in v1.1.0: Complete request management workflows

API Documentation

For complete API documentation, see:

• Forge SDK Documentation
• API Reference

License

MIT