npm package: @flare-proxy/client
Description: TypeScript client library for Flare Image Proxy - generate signed proxy URLs
Latest version: 1.5.0

# @flare-proxy/client

TypeScript client library for Flare Image Proxy - generate signed proxy URLs with HMAC authentication.

## Installation

```bash
npm install @flare-proxy/client
# or
bun add @flare-proxy/client
```

## Quick Start

### Client-Side Signing (Recommended)

Sign URLs locally without making API calls:

```typescript
import { ProxyClient } from "@flare-proxy/client";

const client = new ProxyClient({
  baseUrl: "https://img.yourdomain.com",
  secret: "your-secret-key",
});

// Generate signed URL
const result = client.generateProxyUrl("https://example.com/image.jpg");
console.log(result.proxyUrl);
// https://img.yourdomain.com/?url=https%3A%2F%2Fexample.com%2Fimage.jpg&sig=abc123...
```

### Server-Side Signing via API

Use the `/generate` endpoint for centralized signing:

```typescript
const client = new ProxyClient({
  baseUrl: "https://img.yourdomain.com",
  secret: "your-secret-key",
  apiKey: "your-api-key",
});

const result = await client.generateProxyUrlViaApi(
  "https://example.com/image.jpg",
);
```

## API Reference

### `ProxyClient`

#### Constructor Options

```typescript
interface ProxyClientOptions {
  baseUrl: string; // Your proxy worker URL
  secret: string; // HMAC secret key
  apiKey?: string; // Optional: for server-side generation
}
```

#### Methods

##### `generateProxyUrl(imageUrl: string): GenerateUrlResult`

Generate a signed URL locally using your secret.

```typescript
const result = client.generateProxyUrl("https://example.com/image.jpg");
// Returns:
// {
//   originalUrl: 'https://example.com/image.jpg',
//   proxyUrl: 'https://img.yourdomain.com/?url=...&sig=...',
//   signature: 'abc123...',
//   encodedUrl: 'https%3A%2F%2Fexample.com%2Fimage.jpg'
// }
```

##### `generateProxyUrlViaApi(imageUrl: string): Promise<GenerateUrlResult>`

Generate a signed URL via the `/generate` API endpoint. Requires `apiKey`.

##### `generateProxyUrls(imageUrls: string[]): GenerateUrlResult[]`

Batch generate multiple URLs:

```typescript
const urls = ["https://example.com/1.jpg", "https://example.com/2.jpg"];
const results = client.generateProxyUrls(urls);
```

##### `validateUrl(url: string): { valid: boolean; error?: string }`

Validate a URL before generating:

```typescript
const check = client.validateUrl("https://example.com/image.jpg");
if (!check.valid) {
  console.error(check.error);
}
```

##### `health(): Promise<{ status: string; version: string; timestamp: string }>`

Check proxy service health:

```typescript
const health = await client.health();
console.log(health.status); // 'healthy'
```

## Examples

### React Component

```tsx
import { ProxyClient } from "@flare-proxy/client";

const client = new ProxyClient({
  baseUrl: process.env.NEXT_PUBLIC_IMG_PROXY_URL!,
  secret: process.env.IMG_PROXY_SECRET!,
});

function ProxiedImage({ src, alt }: { src: string; alt: string }) {
  const proxyUrl = client.generateProxyUrl(src).proxyUrl;
  return <img src={proxyUrl} alt={alt} />;
}
```

### Batch Processing

```typescript
const imageUrls = await fetchImageList();
const proxyUrls = client.generateProxyUrls(imageUrls).map((r) => r.proxyUrl);
```

## License

MIT