docs/client-generation.md

# Client SDK Generation Guide

This guide explains how to generate and use client SDKs for the Video Generation API.

## Overview

The Video Generation API supports automatic client SDK generation in multiple programming languages using OpenAPI Generator. This allows developers to quickly integrate with the API using idiomatic code in their preferred language.

## Supported Languages

- **TypeScript/JavaScript** - Modern TypeScript client with fetch API
- **Python** - Python client with requests library
- **Java** - Java client with OkHttp and Gson
- **C#** - .NET Standard 2.0 compatible client
- **Go** - Go client with native HTTP library
- **PHP** - PHP client with Guzzle HTTP
- **Ruby** - Ruby client with Faraday HTTP

## Prerequisites

### Required Tools

1. **Node.js and npm** - For OpenAPI Generator CLI
2. **OpenAPI Generator CLI** - For generating clients
3. **Language-specific tools** (optional, for testing):
   - TypeScript: Node.js, npm
   - Python: Python 3.7+, pip
   - Java: JDK 8+, Maven
   - C#: .NET Core SDK
   - Go: Go 1.16+
   - PHP: PHP 7.4+, Composer
   - Ruby: Ruby 2.7+, Bundler

### Installation

Install OpenAPI Generator CLI:

```bash

npm install -g @openapitools/openapi-generator-cli

```

## Quick Start

### Using the Python Script

The easiest way to generate clients is using the provided Python script:

```bash

# Generate all supported clients

python scripts/generate_clients.py



# Generate specific languages

python scripts/generate_clients.py --languages typescript python



# Use custom API URL

python scripts/generate_clients.py --api-url https://api.example.com



# Custom output directory

python scripts/generate_clients.py --output-dir my_clients

```

### Using the Shell Script

Alternatively, use the shell script:

```bash

# Generate all clients

./scripts/generate_clients.sh



# Generate specific languages

./scripts/generate_clients.sh typescript python java



# Use custom API URL

./scripts/generate_clients.sh --api-url https://api.example.com typescript

```

### Manual Generation

For manual control, use OpenAPI Generator CLI directly:

```bash

# Fetch OpenAPI specification

curl -o openapi.json http://localhost:8000/openapi.json



# Generate TypeScript client

openapi-generator-cli generate \

  -i openapi.json \

  -g typescript-fetch \

  -o clients/typescript \

  --package-name video-api-client



# Generate Python client

openapi-generator-cli generate \

  -i openapi.json \

  -g python \

  -o clients/python \

  --package-name video_api_client

```

## Generated Client Structure

Each generated client includes:

```

clients/

├── typescript/

│   ├── src/

│   │   ├── apis/

│   │   ├── models/

│   │   └── index.ts

│   ├── package.json

│   ├── README.md

│   └── example.ts

├── python/

│   ├── video_api_client/

│   │   ├── api/

│   │   ├── models/

│   │   └── __init__.py

│   ├── setup.py

│   ├── README.md

│   └── example.py

└── ...

```

## Usage Examples

### TypeScript

```typescript

import { Configuration, VideosApi } from 'video-api-client';



const config = new Configuration({

  basePath: 'https://api.example.com',

  accessToken: 'your-clerk-session-token'

});



const videosApi = new VideosApi(config);



async function generateVideo() {

  try {

    const jobResponse = await videosApi.createVideoGenerationJob({

      configuration: {

        topic: "Pythagorean Theorem",

        context: "Explain the mathematical proof",

        quality: "medium",

        use_rag: true

      }

    });

    

    console.log('Job created:', jobResponse.job_id);

    

    // Poll for completion

    let status = 'queued';

    while (status !== 'completed' && status !== 'failed') {

      await new Promise(resolve => setTimeout(resolve, 5000));

      

      const statusResponse = await videosApi.getVideoJobStatus(jobResponse.job_id);

      status = statusResponse.status;

      

      console.log(`Status: ${status} (${statusResponse.progress.percentage}%)`);

    }

    

    if (status === 'completed') {

      const videoBlob = await videosApi.downloadVideoFile(jobResponse.job_id);

      console.log('Video downloaded');

    }

    

  } catch (error) {

    console.error('Error:', error);

  }

}

```

### Python

```python

import time

from video_api_client import Configuration, ApiClient, VideosApi

from video_api_client.models import JobCreateRequest, JobConfiguration



configuration = Configuration(

    host="https://api.example.com",

    access_token="your-clerk-session-token"

)



with ApiClient(configuration) as api_client:

    videos_api = VideosApi(api_client)

    

    try:

        # Create job

        job_request = JobCreateRequest(

            configuration=JobConfiguration(

                topic="Pythagorean Theorem",

                context="Explain the mathematical proof",

                quality="medium",

                use_rag=True

            )

        )

        

        job_response = videos_api.create_video_generation_job(job_request)

        print(f"Job created: {job_response.job_id}")

        

        # Poll for completion

        status = "queued"

        while status not in ["completed", "failed"]:

            time.sleep(5)

            

            status_response = videos_api.get_video_job_status(job_response.job_id)

            status = status_response.status

            

            print(f"Status: {status} ({status_response.progress.percentage}%)")

        

        if status == "completed":

            video_data = videos_api.download_video_file(job_response.job_id)

            with open("video.mp4", "wb") as f:

                f.write(video_data)

            print("Video downloaded")

            

    except Exception as e:

        print(f"Error: {e}")

```

### Java

```java

import com.example.videoapiclient.ApiClient;

import com.example.videoapiclient.Configuration;

import com.example.videoapiclient.api.VideosApi;

import com.example.videoapiclient.model.*;



public class VideoApiExample {

    public static void main(String[] args) {

        ApiClient client = Configuration.getDefaultApiClient();

        client.setBasePath("https://api.example.com");

        client.setAccessToken("your-clerk-session-token");

        

        VideosApi videosApi = new VideosApi(client);

        

        try {

            JobConfiguration config = new JobConfiguration()

                .topic("Pythagorean Theorem")

                .context("Explain the mathematical proof")

                .quality(VideoQuality.MEDIUM)

                .useRag(true);

            

            JobCreateRequest request = new JobCreateRequest().configuration(config);

            JobResponse jobResponse = videosApi.createVideoGenerationJob(request);

            

            System.out.println("Job created: " + jobResponse.getJobId());

            

            // Poll for completion

            String status = "queued";

            while (!"completed".equals(status) && !"failed".equals(status)) {

                Thread.sleep(5000);

                

                JobStatusResponse statusResponse = videosApi.getVideoJobStatus(jobResponse.getJobId());

                status = statusResponse.getStatus().getValue();

                

                System.out.println("Status: " + status + " (" + 

                    statusResponse.getProgress().getPercentage() + "%)");

            }

            

            if ("completed".equals(status)) {

                System.out.println("Video generation completed!");

            }

            

        } catch (Exception e) {

            System.err.println("Error: " + e.getMessage());

        }

    }

}

```

## Authentication

All clients support Clerk authentication. Set your session token when configuring the client:

### TypeScript
```typescript

const config = new Configuration({

  accessToken: 'your-clerk-session-token'

});

```

### Python
```python

configuration.access_token = 'your-clerk-session-token'

```

### Java
```java

client.setAccessToken("your-clerk-session-token");

```

## Error Handling

All clients provide structured error handling:

### TypeScript
```typescript

try {

  const response = await api.createVideoGenerationJob(request);

} catch (error) {

  if (error.status === 422) {

    console.error('Validation error:', error.body);

  } else if (error.status === 429) {

    console.error('Rate limit exceeded');

  } else {

    console.error('API error:', error);

  }

}

```

### Python
```python

from video_api_client.exceptions import ApiException



try:

    response = api.create_video_generation_job(request)

except ApiException as e:

    if e.status == 422:

        print(f"Validation error: {e.body}")

    elif e.status == 429:

        print("Rate limit exceeded")

    else:

        print(f"API error: {e}")

```

## Testing Generated Clients

Use the provided testing script to validate generated clients:

```bash

# Test all generated clients

python scripts/test_clients.py



# Test with custom API URL

python scripts/test_clients.py --api-url https://api.example.com



# Save test results

python scripts/test_clients.py --output-file test_results.json



# Verbose output

python scripts/test_clients.py --verbose

```

The test script validates:
- Client structure and files
- Build/compilation success
- Import/usage capability
- API connectivity
- Basic functionality

## Customization

### Custom Templates

Create custom templates in the `templates/` directory:

```

templates/

├── typescript/

│   ├── api.mustache

│   ├── model.mustache

│   └── README.mustache

├── python/

│   ├── api.mustache

│   └── model.mustache

└── ...

```

### Configuration File

Modify `openapi-generator-config.yaml` to customize generation:

```yaml

typescript:

  generatorName: typescript-fetch

  additionalProperties:

    npmName: my-custom-client

    supportsES6: true

    withInterfaces: true

```

### Custom Properties

Pass additional properties during generation:

```bash

openapi-generator-cli generate \

  -i openapi.json \

  -g typescript-fetch \

  -o clients/typescript \

  --additional-properties=npmName=my-client,supportsES6=true

```

## Publishing Clients

### NPM (TypeScript/JavaScript)

```bash

cd clients/typescript

npm publish

```

### PyPI (Python)

```bash

cd clients/python

python setup.py sdist bdist_wheel

twine upload dist/*

```

### Maven Central (Java)

```bash

cd clients/java

mvn deploy

```

### NuGet (C#)

```bash

cd clients/csharp

dotnet pack

dotnet nuget push *.nupkg

```

## Troubleshooting

### Common Issues

1. **OpenAPI Generator not found**
   ```bash

   npm install -g @openapitools/openapi-generator-cli

   ```

2. **API server not running**
   ```bash

   # Start the API server first

   python -m uvicorn src.app.main:app --reload

   ```

3. **Build failures**
   - Check language-specific requirements
   - Verify generated code syntax
   - Review error messages in build logs

4. **Import errors**
   - Ensure proper installation
   - Check Python path and virtual environments
   - Verify package structure

### Debug Mode

Enable debug output for troubleshooting:

```bash

# Python script

python scripts/generate_clients.py --verbose



# OpenAPI Generator

openapi-generator-cli generate \

  --verbose \

  --debug-operations \

  -i openapi.json \

  -g typescript-fetch \

  -o clients/typescript

```

### Validation

Validate OpenAPI specification before generation:

```bash

# Using OpenAPI Generator

openapi-generator-cli validate -i openapi.json



# Using Swagger Editor online

# Visit: https://editor.swagger.io/

```

## Best Practices

1. **Version Management**
   - Tag client versions with API versions
   - Maintain backward compatibility
   - Document breaking changes

2. **Testing**
   - Test clients against real API
   - Include integration tests
   - Validate error handling

3. **Documentation**
   - Include usage examples
   - Document authentication setup
   - Provide troubleshooting guides

4. **Distribution**
   - Use semantic versioning
   - Publish to appropriate package managers
   - Maintain changelogs

## Support

For issues with client generation:

- Check the [OpenAPI Generator documentation](https://openapi-generator.tech/)
- Review API documentation at `/docs`
- Contact support at support@example.com
- File issues on GitHub

## Contributing

To contribute to client generation:

1. Fork the repository
2. Create custom templates or improve scripts
3. Test with multiple languages
4. Submit pull request with documentation

## License

Generated clients inherit the same license as the API project (MIT License).