@flare-proxy/client

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

Installation

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

Quick Start

Client-Side Signing (Recommended)

Sign URLs locally without making API calls:

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:

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

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.

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:

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:

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:

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

Examples

React Component

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

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

License

MIT