# Chunk 1: TypeScript Client Generation

**Parent:** [Build Graph Dashboard](../build-graph-dashboard.md)  
**Next:** [Chunk 2: Hello World App](./chunk-2-hello-world-app.md)

## Overview

Generate TypeScript client code from the DataBuild protobuf definitions to provide type-safe API access for the dashboard.

## Scope

### In Scope
- Generate TypeScript interfaces from `databuild.proto`
- Create typed client for Build Graph Service HTTP API endpoints
- Set up Bazel rules for protobuf-to-TypeScript generation
- Implement simple custom protobuf-to-TypeScript tooling (if off-the-shelf solutions are complex)

### Out of Scope
- Full protobuf runtime features (only need type definitions)
- Complex protobuf features (focus on basic message types)
- Client-side validation (rely on server-side validation)

## Technical Approach

### Proto Analysis
Key messages to generate TypeScript for:
- `BuildEvent` and related event types
- `PartitionRef`, `JobLabel`, `GraphLabel`
- `BuildRequestStatus`, `PartitionStatus`, `JobStatus`
- `JobGraph`, `Task`, `JobConfig`
- Service request/response types

### Generated Client Structure
```typescript
// Generated types
interface PartitionRef {
  str: string;
}

interface BuildStatusResponse {
  build_request_id: string;
  status: BuildRequestStatus;
  requested_partitions: string[];
  created_at: number;
  updated_at: number;
  events: BuildEventSummary[];
}

// Client class
class BuildGraphClient {
  constructor(baseUrl: string);
  
  async submitBuild(partitions: string[]): Promise<{build_request_id: string}>;
  async getBuildStatus(id: string): Promise<BuildStatusResponse>;
  async cancelBuild(id: string): Promise<{cancelled: boolean}>;
  async getPartitionStatus(ref: string): Promise<PartitionStatusResponse>;
  async getPartitionEvents(ref: string): Promise<BuildEventSummary[]>;
  async analyzeGraph(partitions: string[]): Promise<{job_graph: JobGraph}>;
}
```

### Bazel Integration
- Create `//databuild/client:typescript` target
- Generate TypeScript files from `.proto` sources
- Ensure hermetic build process
- Output client code to `databuild/client/typescript/`

## Implementation Strategy

1. **Assess Off-the-Shelf Solutions**
   - Quick evaluation of existing protobuf-to-TypeScript tools
   - If complex setup required, proceed with custom implementation

2. **Custom Generator (if needed)**
   - Simple Python/Rust script to parse proto and generate TypeScript
   - Focus only on message types and basic field mapping
   - No complex protobuf features needed

3. **Bazel Rules**
   - Create `typescript_proto_library` rule
   - Generate client code during build
   - Ensure proper dependency management

## Deliverables

- [ ] TypeScript interfaces for all relevant protobuf messages
- [ ] Typed HTTP client for Build Graph Service endpoints
- [ ] Bazel rules for client generation
- [ ] Documentation for using the generated client

## Success Criteria

- Generated TypeScript compiles without errors
- Client provides type safety for all API endpoints
- Bazel build integrates seamlessly
- Ready for use in Chunk 2 (Hello World App)

## Testing

- Verify generated TypeScript compiles
- Test client against running Build Graph Service
- Validate type safety with TypeScript compiler