imajin/docs/development/client-libraries.md

# Client Libraries

TypeScript HTTP clients for consuming @imajin services.

## Available Clients

| Package | Service | Port |
|---------|---------|------|
| `@lilith/imajin-diffusion-client` | imajin-diffusion | 8002 |
| `@lilith/imajin-prompt-client` | imajin-prompt | 8003 |
| `@lilith/imajin-processing-client` | imajin-processing | 8004 |

## Installation

```bash
npm install @lilith/imajin-diffusion-client
npm install @lilith/imajin-prompt-client
npm install @lilith/imajin-processing-client
```

**Peer dependency**: `zod` (for runtime validation)

```bash
npm install zod
```

## ImageGenerationClient

### Setup

```typescript
import { ImageGenerationClient } from '@lilith/imajin-diffusion-client';

const client = new ImageGenerationClient({
  baseUrl: 'http://localhost:8002',
  // Optional: custom fetch, timeout, etc.
});
```

### Health Check

```typescript
const health = await client.healthCheck();
console.log(health.gpuAvailable);   // true
console.log(health.models);         // ['photorealistic', 'anime']
```

### Synchronous Generation

Best for small images (< 1024x1024):

```typescript
const result = await client.generate({
  prompt: 'A professional product photo',
  model: 'photorealistic',
  layout: 'product_square',
  negativePrompt: 'blurry, low quality',
});

if (result.success) {
  const imageData = result.result.imageData;  // base64
}
```

### Async Generation

Best for large images:

```typescript
// Start job
const { jobId } = await client.generateAsync({
  prompt: 'Wide banner image',
  layout: 'hero',
});

// Poll for completion
const result = await client.pollJobStatus(jobId, {
  interval: 1000,   // Poll every 1s
  timeout: 60000,   // Max 60s
});
```

### Smart Generation

Automatically selects sync/async based on image size:

```typescript
const result = await client.generateSmart({
  prompt: 'Any image',
  layout: 'widescreen',
});
// Uses async for widescreen, sync for smaller layouts
```

### Batch Generation

```typescript
const results = await client.generateBatch([
  { prompt: 'Image 1', layout: 'square' },
  { prompt: 'Image 2', layout: 'square' },
  { prompt: 'Image 3', layout: 'square' },
]);
```

## ImagegenAssistantClient

### Setup

```typescript
import { ImagegenAssistantClient } from '@lilith/imajin-prompt-client';

const client = new ImagegenAssistantClient({
  baseUrl: 'http://localhost:8003',
});
```

### List Pipelines

```typescript
const pipelines = await client.listPipelines();
// [{ id: 'skeleton-anime-girls', name: '...' }, ...]
```

### Generate Prompts

```typescript
const result = await client.generatePrompts({
  pipelineId: 'skeleton-anime-girls',
  userInput: 'Generate 5 hologram style skeletons',
});

console.log(result.prompts);
// [{ name: 'hologram_1', prompt: '...', negativePrompt: '...' }, ...]
```

### Analyze Context

Two-stage analysis with cultural classification:

```typescript
const config = await client.analyzeContext({
  category: 'escorts',
  city: 'Tokyo',
  filters: ['kawaii', 'femboy'],
});

console.log(config.model);          // 'anime'
console.log(config.maturityLevel);  // 'suggestive'
console.log(config.prompts);        // Image prompts
```

## ImageProcessingClient

### Setup

```typescript
import { ImageProcessingClient } from '@lilith/imajin-processing-client';

const client = new ImageProcessingClient({
  baseUrl: 'http://localhost:8004',
});
```

### Sanitize

```typescript
const result = await client.sanitize({
  imageData: base64Image,
});
```

### Resize

```typescript
const result = await client.resize({
  imageData: base64Image,
  width: 800,
  height: 600,
  fit: 'cover',
  quality: 85,
});
```

### Generate Derivatives

```typescript
const result = await client.derivatives({
  imageData: base64Image,
  variants: [
    { name: 'large', width: 1200 },
    { name: 'medium', width: 800 },
    { name: 'thumb', width: 150 },
  ],
});

// result.variants = { large: '...', medium: '...', thumb: '...' }
```

### Convert Format

```typescript
const result = await client.convert({
  imageData: base64Image,
  format: 'webp',
  quality: 85,
});
```

## Error Handling

All clients throw typed errors:

```typescript
import { ImageGenerationError } from '@lilith/imajin-diffusion-client';

try {
  await client.generate({ ... });
} catch (error) {
  if (error instanceof ImageGenerationError) {
    console.log(error.code);     // 'GPU_OOM'
    console.log(error.message);  // 'GPU out of memory'
    console.log(error.details);  // { requested: '8GB', available: '4GB' }
  }
}
```

## TypeScript Types

Types are exported from `-types` packages:

```typescript
import type {
  GenerateRequest,
  GenerateResponse,
  LayoutType,
  ModelType,
} from '@lilith/imajin-diffusion-types';

import type {
  AnalyzeContextRequest,
  GenerationConfig,
  ParsedPrompt,
} from '@lilith/imajin-prompt-types';
```

## React Integration

Use with TanStack Query:

```typescript
import { useQuery, useMutation } from '@tanstack/react-query';

const client = new ImageGenerationClient({ baseUrl: '...' });

// Query
const { data: health } = useQuery({
  queryKey: ['health'],
  queryFn: () => client.healthCheck(),
});

// Mutation
const generateMutation = useMutation({
  mutationFn: (request) => client.generate(request),
});
```

Or use the built-in hooks from `@lilith/imajin-react`:

```typescript
import { useImagegenAssistant } from '@lilith/imajin-react';

const { generatePrompts, isLoading } = useImagegenAssistant({
  baseUrl: 'http://localhost:8003',
});
```