npm package: @orchard9ai/forge-api-client
Description: TypeScript client for Forge API - auto-generated from OpenAPI spec
Author: Forge Development Team
Latest version: 3.1.0

# @orchard9ai/forge-api-client

[![npm version](https://badge.fury.io/js/@orchard9ai%2Fforge-api-client.svg)](https://www.npmjs.com/package/@orchard9ai/forge-api-client)

TypeScript API client for the Forge Development System with support for multiple frameworks. Auto-generated from OpenAPI specification using [Orval](https://orval.dev/).

## 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

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

## Quick Start

### Vanilla TypeScript

```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

```tsx
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

```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:

```typescript
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

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

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

### Retry Logic

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

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

### Testing with MSW

```typescript
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](https://orval.dev/).

### Regenerate Client

```bash
# 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](../../docs/sdk/README.md)
- [API Reference](../../docs/api/)

## License

MIT