@cloudwerk/images 0.1.3

package/dist/index.d.ts

@@ -0,0 +1,1209 @@
+/**
+ * @cloudwerk/images - Type Definitions
+ *
+ * Core types for Cloudflare Images integration.
+ */
+/**
+ * Configuration for an image variant (transformation preset).
+ *
+ * @example
+ * ```typescript
+ * const thumbnailVariant: ImageVariant = {
+ *   width: 100,
+ *   height: 100,
+ *   fit: 'cover',
+ *   quality: 80,
+ * }
+ * ```
+ */
+interface ImageVariant {
+    /** Width in pixels */
+    width?: number;
+    /** Height in pixels */
+    height?: number;
+    /**
+     * How the image should be resized to fit the dimensions.
+     *
+     * - 'cover': Fill the dimensions, cropping if necessary
+     * - 'contain': Fit within dimensions, may have letterboxing
+     * - 'scale-down': Only shrink, never enlarge
+     * - 'crop': Crop to exact dimensions from center
+     * - 'pad': Fit within dimensions, padding if necessary
+     */
+    fit?: 'cover' | 'contain' | 'scale-down' | 'crop' | 'pad';
+    /**
+     * Blur radius (1-250).
+     * Higher values = more blur.
+     */
+    blur?: number;
+    /**
+     * Quality for lossy formats (1-100).
+     * @default 85
+     */
+    quality?: number;
+    /**
+     * Output format override.
+     * If not specified, format is negotiated based on Accept header.
+     */
+    format?: 'webp' | 'avif' | 'json' | 'jpeg' | 'png';
+    /**
+     * Device pixel ratio (1-3).
+     * Multiplies width/height for retina displays.
+     */
+    dpr?: number;
+    /**
+     * Gravity for cropping (where to focus when cropping).
+     */
+    gravity?: 'auto' | 'center' | 'top' | 'bottom' | 'left' | 'right' | 'face';
+    /**
+     * Sharpen the image (0-10).
+     */
+    sharpen?: number;
+    /**
+     * Brightness adjustment (-1 to 1).
+     */
+    brightness?: number;
+    /**
+     * Contrast adjustment (-1 to 1).
+     */
+    contrast?: number;
+    /**
+     * Rotate the image in degrees (0-360).
+     */
+    rotate?: number;
+    /**
+     * Metadata handling.
+     *
+     * - 'keep': Preserve all metadata
+     * - 'copyright': Keep only copyright info
+     * - 'none': Strip all metadata
+     */
+    metadata?: 'keep' | 'copyright' | 'none';
+}
+/**
+ * Environment variable reference for sensitive configuration.
+ *
+ * @example
+ * ```typescript
+ * const config: ImageConfig = {
+ *   accountId: { env: 'CF_ACCOUNT_ID' },
+ *   apiToken: { env: 'CF_IMAGES_API_TOKEN' },
+ * }
+ * ```
+ */
+interface EnvRef {
+    /** Name of the environment variable */
+    env: string;
+}
+/**
+ * Configuration for defining a Cloudflare Images integration.
+ *
+ * @example
+ * ```typescript
+ * // app/images/avatars.ts
+ * export default defineImage({
+ *   name: 'avatars',
+ *   variants: {
+ *     thumbnail: { width: 100, height: 100, fit: 'cover' },
+ *     profile: { width: 400, height: 400, fit: 'cover' },
+ *   },
+ * })
+ * ```
+ */
+interface ImageConfig {
+    /**
+     * Unique name for this image configuration.
+     * Defaults to the filename (without extension).
+     */
+    name?: string;
+    /**
+     * Cloudflare account ID.
+     * Can be a string value or environment variable reference.
+     */
+    accountId?: string | EnvRef;
+    /**
+     * Cloudflare Images API token.
+     * Can be a string value or environment variable reference.
+     */
+    apiToken?: string | EnvRef;
+    /**
+     * Predefined image variants (transformation presets).
+     *
+     * @example
+     * ```typescript
+     * variants: {
+     *   thumbnail: { width: 100, height: 100, fit: 'cover' },
+     *   large: { width: 1200, height: 800, fit: 'contain' },
+     *   blur: { blur: 20, width: 20 },
+     * }
+     * ```
+     */
+    variants?: Record<string, ImageVariant>;
+    /**
+     * Custom domain for image delivery.
+     * If not specified, uses the default Cloudflare Images URL.
+     *
+     * @example 'https://images.example.com'
+     */
+    deliveryUrl?: string;
+    /**
+     * Default variant to use when none is specified.
+     */
+    defaultVariant?: string;
+    /**
+     * Whether to require signed URLs for this image configuration.
+     * @default false
+     */
+    requireSignedURLs?: boolean;
+}
+/**
+ * An image definition created by `defineImage()`.
+ *
+ * This is the return type of the factory function and contains
+ * the processed configuration with a brand marker for type safety.
+ */
+interface ImageDefinition {
+    /** Internal marker identifying this as an image definition */
+    readonly __brand: 'cloudwerk-image';
+    /** Image configuration name */
+    readonly name: string;
+    /** Processed configuration with defaults applied */
+    readonly config: ImageConfig;
+    /** Variant definitions */
+    readonly variants: Record<string, ImageVariant>;
+}
+/**
+ * Options for uploading an image.
+ *
+ * @example
+ * ```typescript
+ * const result = await images.avatars.upload(file, {
+ *   id: 'user-123-avatar',
+ *   metadata: { userId: '123', uploadedAt: new Date().toISOString() },
+ * })
+ * ```
+ */
+interface UploadOptions {
+    /**
+     * Custom metadata to attach to the image.
+     * Can be used for organization and filtering.
+     */
+    metadata?: Record<string, string>;
+    /**
+     * Whether to require signed URLs to access this image.
+     * Overrides the configuration-level setting.
+     */
+    requireSignedURLs?: boolean;
+    /**
+     * Custom image ID.
+     * If not specified, Cloudflare generates a UUID.
+     */
+    id?: string;
+}
+/**
+ * Options for generating a direct upload URL.
+ *
+ * Direct upload URLs allow clients to upload images directly to Cloudflare
+ * without going through your server, reducing bandwidth costs.
+ *
+ * @example
+ * ```typescript
+ * const { uploadUrl, id } = await images.avatars.getDirectUploadUrl({
+ *   expiry: '1h',
+ *   metadata: { userId: '123' },
+ * })
+ *
+ * // Return uploadUrl to client for direct upload
+ * ```
+ */
+interface DirectUploadOptions {
+    /**
+     * Custom metadata to attach to the uploaded image.
+     */
+    metadata?: Record<string, string>;
+    /**
+     * Whether to require signed URLs to access the uploaded image.
+     */
+    requireSignedURLs?: boolean;
+    /**
+     * How long the upload URL is valid.
+     * Can be a duration string ('1h', '30m') or seconds.
+     * @default '30m'
+     */
+    expiry?: string | number;
+}
+/**
+ * Options for listing images.
+ */
+interface ListOptions {
+    /** Page number (1-based) */
+    page?: number;
+    /** Number of images per page (1-100) */
+    perPage?: number;
+}
+/**
+ * Result of an image upload operation.
+ *
+ * @example
+ * ```typescript
+ * const result = await images.avatars.upload(file)
+ * console.log(result.id)        // 'abc123'
+ * console.log(result.variants)  // ['thumbnail', 'profile']
+ * console.log(result.uploaded)  // Date object
+ * ```
+ */
+interface ImageResult {
+    /** Unique image ID */
+    id: string;
+    /** Original filename (if provided during upload) */
+    filename?: string;
+    /** When the image was uploaded */
+    uploaded: Date;
+    /** Available variant names for this image */
+    variants: string[];
+    /** Custom metadata attached to the image */
+    metadata?: Record<string, string>;
+    /** Whether the image requires signed URLs */
+    requireSignedURLs?: boolean;
+}
+/**
+ * Result of generating a direct upload URL.
+ */
+interface DirectUploadResult {
+    /** One-time upload URL for direct client upload */
+    uploadUrl: string;
+    /** Image ID that will be assigned to the uploaded image */
+    id: string;
+}
+/**
+ * Image client interface for interacting with Cloudflare Images.
+ *
+ * @typeParam T - Variant names type for this image configuration
+ */
+interface ImageClientInterface<T extends string = string> {
+    /**
+     * Upload an image file.
+     *
+     * @param file - File, Blob, or ReadableStream to upload
+     * @param options - Upload options
+     * @returns Upload result with image ID and metadata
+     */
+    upload(file: File | Blob | ReadableStream, options?: UploadOptions): Promise<ImageResult>;
+    /**
+     * Generate a direct upload URL for client-side uploads.
+     *
+     * @param options - Direct upload options
+     * @returns Upload URL and image ID
+     */
+    getDirectUploadUrl(options?: DirectUploadOptions): Promise<DirectUploadResult>;
+    /**
+     * Delete an image.
+     *
+     * @param imageId - ID of the image to delete
+     */
+    delete(imageId: string): Promise<void>;
+    /**
+     * Get image details.
+     *
+     * @param imageId - ID of the image
+     * @returns Image result or null if not found
+     */
+    get(imageId: string): Promise<ImageResult | null>;
+    /**
+     * List images with pagination.
+     *
+     * @param options - Pagination options
+     * @returns Array of image results
+     */
+    list(options?: ListOptions): Promise<ImageResult[]>;
+    /**
+     * Generate URL for an image with optional variant.
+     *
+     * @param imageId - ID of the image
+     * @param variant - Variant name (optional)
+     * @returns Full URL to the image
+     */
+    url(imageId: string, variant?: T): string;
+}
+/**
+ * A scanned image file from the app/images/ directory.
+ */
+interface ScannedImage {
+    /** Relative path from app/images/ (e.g., 'avatars.ts') */
+    relativePath: string;
+    /** Absolute filesystem path */
+    absolutePath: string;
+    /** File name without extension (e.g., 'avatars') */
+    name: string;
+    /** File extension (e.g., '.ts') */
+    extension: string;
+}
+/**
+ * Result of scanning the app/images/ directory.
+ */
+interface ImageScanResult {
+    /** All discovered image files */
+    images: ScannedImage[];
+}
+/**
+ * A compiled image entry in the manifest.
+ */
+interface ImageEntry {
+    /** Image name derived from filename (e.g., 'avatars') */
+    name: string;
+    /** Binding name for wrangler.toml (e.g., 'AVATARS_IMAGES') */
+    bindingName: string;
+    /** Relative path to the image definition file */
+    filePath: string;
+    /** Absolute path to the image definition file */
+    absolutePath: string;
+    /** Variant definitions from the image config */
+    variants: Record<string, ImageVariant>;
+    /** Full image configuration */
+    config: ImageConfig;
+}
+/**
+ * Validation error for an image definition.
+ */
+interface ImageValidationError {
+    /** Image file path */
+    file: string;
+    /** Error message */
+    message: string;
+    /** Error code for programmatic handling */
+    code: 'INVALID_CONFIG' | 'DUPLICATE_NAME' | 'INVALID_NAME' | 'MISSING_REQUIRED';
+}
+/**
+ * Validation warning for an image definition.
+ */
+interface ImageValidationWarning {
+    /** Image file path */
+    file: string;
+    /** Warning message */
+    message: string;
+    /** Warning code */
+    code: 'NO_VARIANTS' | 'MISSING_ACCOUNT_ID' | 'MISSING_API_TOKEN';
+}
+/**
+ * Complete image manifest generated during build.
+ */
+interface ImageManifest {
+    /** All compiled image entries */
+    images: ImageEntry[];
+    /** Validation errors (image won't be registered) */
+    errors: ImageValidationError[];
+    /** Validation warnings (image will be registered with warning) */
+    warnings: ImageValidationWarning[];
+    /** When the manifest was generated */
+    generatedAt: Date;
+    /** Root directory of the app */
+    rootDir: string;
+}
+
+/**
+ * @cloudwerk/images - Error Classes
+ *
+ * Custom error types for Cloudflare Images operations.
+ */
+/**
+ * Base error class for all image-related errors.
+ */
+declare class ImageError extends Error {
+    constructor(message: string);
+}
+/**
+ * Error thrown when image configuration is invalid.
+ */
+declare class ImageConfigError extends ImageError {
+    readonly field: string;
+    constructor(message: string, field: string);
+}
+/**
+ * Error thrown when a required environment variable is missing.
+ */
+declare class ImageEnvError extends ImageError {
+    readonly envVar: string;
+    constructor(envVar: string);
+}
+/**
+ * Error thrown when an image is not found.
+ */
+declare class ImageNotFoundError extends ImageError {
+    readonly imageId: string;
+    constructor(imageId: string);
+}
+/**
+ * Error thrown when an image upload fails.
+ */
+declare class ImageUploadError extends ImageError {
+    readonly statusCode?: number;
+    readonly details?: string;
+    constructor(message: string, statusCode?: number, details?: string);
+}
+/**
+ * Error thrown when an image operation fails due to API errors.
+ */
+declare class ImageApiError extends ImageError {
+    readonly statusCode: number;
+    readonly errors: Array<{
+        code: number;
+        message: string;
+    }>;
+    constructor(statusCode: number, errors: Array<{
+        code: number;
+        message: string;
+    }>);
+}
+/**
+ * Error thrown when an invalid variant is requested.
+ */
+declare class ImageVariantError extends ImageError {
+    readonly variant: string;
+    readonly availableVariants: string[];
+    constructor(variant: string, availableVariants: string[]);
+}
+/**
+ * Error thrown when image binding is accessed outside request context.
+ */
+declare class ImageContextError extends ImageError {
+    constructor();
+}
+/**
+ * Error thrown when an image configuration is not found.
+ */
+declare class ImageBindingNotFoundError extends ImageError {
+    readonly name: string;
+    readonly availableImages: string[];
+    constructor(name: string, availableImages: string[]);
+}
+
+/**
+ * @cloudwerk/images - defineImage()
+ *
+ * Factory function for creating image definitions.
+ */
+
+/**
+ * Define a Cloudflare Images configuration.
+ *
+ * This function creates an image definition that will be automatically
+ * discovered and registered by Cloudwerk during build.
+ *
+ * @param config - Image configuration
+ * @returns Image definition
+ *
+ * @example
+ * ```typescript
+ * // app/images/avatars.ts
+ * import { defineImage } from '@cloudwerk/images'
+ *
+ * export default defineImage({
+ *   variants: {
+ *     thumbnail: { width: 100, height: 100, fit: 'cover' },
+ *     profile: { width: 400, height: 400, fit: 'cover' },
+ *     large: { width: 1200, height: 1200, fit: 'contain' },
+ *   },
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // app/images/products.ts - with custom delivery domain
+ * import { defineImage } from '@cloudwerk/images'
+ *
+ * export default defineImage({
+ *   deliveryUrl: 'https://images.mystore.com',
+ *   variants: {
+ *     card: { width: 300, height: 300, fit: 'cover' },
+ *     detail: { width: 800, height: 600, fit: 'contain' },
+ *     zoom: { width: 1600, height: 1200, fit: 'contain' },
+ *   },
+ *   defaultVariant: 'card',
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // app/images/secure.ts - with signed URLs required
+ * import { defineImage } from '@cloudwerk/images'
+ *
+ * export default defineImage({
+ *   requireSignedURLs: true,
+ *   variants: {
+ *     preview: { width: 200, height: 200, fit: 'cover', blur: 20 },
+ *     full: { width: 1920, height: 1080, fit: 'contain' },
+ *   },
+ * })
+ * ```
+ */
+declare function defineImage(config?: ImageConfig): ImageDefinition;
+/**
+ * Check if a value is an image definition created by defineImage().
+ *
+ * @param value - Value to check
+ * @returns true if value is an ImageDefinition
+ */
+declare function isImageDefinition(value: unknown): value is ImageDefinition;
+
+/**
+ * @cloudwerk/images - Image Client
+ *
+ * Client for interacting with Cloudflare Images API.
+ */
+
+/**
+ * Client for interacting with Cloudflare Images.
+ *
+ * @example
+ * ```typescript
+ * const client = new ImageClient('account-id', 'api-token', {
+ *   thumbnail: { width: 100, height: 100, fit: 'cover' },
+ * })
+ *
+ * // Upload an image
+ * const result = await client.upload(file)
+ *
+ * // Get URL with variant
+ * const url = client.url(result.id, 'thumbnail')
+ * ```
+ */
+declare class ImageClient<T extends string = string> implements ImageClientInterface<T> {
+    private readonly accountId;
+    private readonly apiToken;
+    private readonly deliveryUrl?;
+    private readonly variants;
+    private readonly variantNames;
+    constructor(accountId: string, apiToken: string, variants?: Record<string, ImageVariant>, deliveryUrl?: string);
+    /**
+     * Make an authenticated API request.
+     */
+    private fetch;
+    /**
+     * Upload an image file.
+     */
+    upload(file: File | Blob | ReadableStream, options?: UploadOptions): Promise<ImageResult>;
+    /**
+     * Generate a direct upload URL for client-side uploads.
+     */
+    getDirectUploadUrl(options?: DirectUploadOptions): Promise<DirectUploadResult>;
+    /**
+     * Delete an image.
+     */
+    delete(imageId: string): Promise<void>;
+    /**
+     * Get image details.
+     */
+    get(imageId: string): Promise<ImageResult | null>;
+    /**
+     * List images with pagination.
+     */
+    list(options?: ListOptions): Promise<ImageResult[]>;
+    /**
+     * Generate URL for an image with optional variant.
+     */
+    url(imageId: string, variant?: T): string;
+}
+/**
+ * Create an image client from configuration.
+ *
+ * @param accountId - Cloudflare account ID
+ * @param apiToken - Cloudflare Images API token
+ * @param variants - Variant definitions
+ * @param deliveryUrl - Custom delivery URL (optional)
+ * @returns Image client instance
+ */
+declare function createImageClient<T extends string = string>(accountId: string, apiToken: string, variants?: Record<T, ImageVariant>, deliveryUrl?: string): ImageClient<T>;
+
+/**
+ * @cloudwerk/images - Cloudflare API Types
+ *
+ * Type definitions for Cloudflare Images API responses.
+ * Based on Cloudflare API documentation.
+ */
+/**
+ * Standard Cloudflare API response wrapper.
+ */
+interface CloudflareApiResponse<T> {
+    result: T;
+    success: boolean;
+    errors: CloudflareApiError[];
+    messages: CloudflareApiMessage[];
+}
+/**
+ * Cloudflare API error.
+ */
+interface CloudflareApiError {
+    code: number;
+    message: string;
+}
+/**
+ * Cloudflare API message.
+ */
+interface CloudflareApiMessage {
+    code: number;
+    message: string;
+}
+/**
+ * Cloudflare Image object from API.
+ */
+interface CloudflareImage {
+    /** Unique image identifier */
+    id: string;
+    /** Original filename */
+    filename: string;
+    /** Upload timestamp (ISO 8601) */
+    uploaded: string;
+    /** Whether signed URLs are required */
+    requireSignedURLs: boolean;
+    /** Available variant URLs */
+    variants: string[];
+    /** Custom metadata */
+    meta?: Record<string, string>;
+}
+/**
+ * Response from uploading an image.
+ */
+interface CloudflareUploadResponse {
+    id: string;
+    filename: string;
+    uploaded: string;
+    requireSignedURLs: boolean;
+    variants: string[];
+    meta?: Record<string, string>;
+}
+/**
+ * Response from creating a direct upload URL.
+ */
+interface CloudflareDirectUploadResponse {
+    id: string;
+    uploadURL: string;
+}
+/**
+ * Response from listing images.
+ */
+interface CloudflareListResponse {
+    images: CloudflareImage[];
+    continuation_token?: string;
+}
+/**
+ * Response from getting image details.
+ */
+interface CloudflareImageDetailsResponse {
+    id: string;
+    filename: string;
+    uploaded: string;
+    requireSignedURLs: boolean;
+    variants: string[];
+    meta?: Record<string, string>;
+}
+/**
+ * Request body for creating a direct upload URL.
+ */
+interface DirectUploadRequest {
+    /** Whether to require signed URLs */
+    requireSignedURLs?: boolean;
+    /** Custom metadata */
+    metadata?: Record<string, string>;
+    /** Expiry timestamp (ISO 8601 or Unix timestamp) */
+    expiry?: string;
+}
+/**
+ * Cloudflare Images variant configuration (API format).
+ */
+interface CloudflareVariant {
+    id: string;
+    options: {
+        fit?: 'cover' | 'contain' | 'scale-down' | 'crop' | 'pad';
+        width?: number;
+        height?: number;
+        metadata?: 'keep' | 'copyright' | 'none';
+    };
+    neverRequireSignedURLs?: boolean;
+}
+/**
+ * Cloudflare Images usage statistics.
+ */
+interface CloudflareImagesStats {
+    count: {
+        current: number;
+        allowed: number;
+    };
+}
+/**
+ * Cloudflare Images API endpoints.
+ */
+declare const CLOUDFLARE_IMAGES_API: {
+    /** Base URL for Cloudflare API v4 */
+    readonly BASE: "https://api.cloudflare.com/client/v4";
+    /**
+     * Get the images endpoint for an account.
+     */
+    readonly images: (accountId: string) => string;
+    /**
+     * Get the direct upload endpoint.
+     */
+    readonly directUpload: (accountId: string) => string;
+    /**
+     * Get a specific image endpoint.
+     */
+    readonly image: (accountId: string, imageId: string) => string;
+    /**
+     * Get the default delivery URL format.
+     */
+    readonly deliveryUrl: (accountId: string, imageId: string, variant: string) => string;
+};
+
+/**
+ * @cloudwerk/images - Image Transformer
+ *
+ * Route handler helper for Cloudflare's Image Resizing service.
+ * Creates a handler that transforms images via `fetch(url, { cf: { image: {...} } })`.
+ *
+ * @example
+ * ```typescript
+ * // app/cdn/images/[...path]/route.ts
+ * import { createImageTransformer } from '@cloudwerk/images'
+ *
+ * export const GET = createImageTransformer({
+ *   allowedOrigins: ['https://images.mysite.com'],
+ *   presets: {
+ *     thumbnail: { width: 100, height: 100, fit: 'cover' },
+ *     hero: { width: 1920, height: 1080, fit: 'cover' },
+ *   },
+ * })
+ * ```
+ */
+
+/**
+ * Configuration for the image transformer route handler.
+ */
+interface TransformerConfig {
+    /**
+     * Allowed origin URLs for image sources.
+     * If not specified, any origin is allowed (not recommended for production).
+     *
+     * @example ['https://images.mysite.com', 'https://cdn.example.com']
+     */
+    allowedOrigins?: string[];
+    /**
+     * Named transformation presets.
+     * Can be applied via URL parameter (e.g., ?preset=thumbnail).
+     *
+     * @example
+     * ```typescript
+     * presets: {
+     *   thumbnail: { width: 100, height: 100, fit: 'cover' },
+     *   hero: { width: 1920, height: 1080, fit: 'cover' },
+     * }
+     * ```
+     */
+    presets?: Record<string, TransformPreset>;
+    /**
+     * Default transformation options applied to all requests.
+     */
+    defaults?: TransformPreset;
+    /**
+     * Maximum allowed width. Requests exceeding this will be clamped.
+     * @default 4096
+     */
+    maxWidth?: number;
+    /**
+     * Maximum allowed height. Requests exceeding this will be clamped.
+     * @default 4096
+     */
+    maxHeight?: number;
+    /**
+     * Cache control header for transformed images.
+     * @default 'public, max-age=31536000' (1 year)
+     */
+    cacheControl?: string;
+    /**
+     * Whether to allow arbitrary width/height from query parameters.
+     * If false, only preset transformations are allowed.
+     * @default true
+     */
+    allowArbitrary?: boolean;
+    /**
+     * Custom validation function for source URLs.
+     * Return true to allow the URL, false to reject.
+     */
+    validateSource?: (url: URL) => boolean | Promise<boolean>;
+}
+/**
+ * Transformation preset options.
+ * Subset of Cloudflare Image Resizing options.
+ */
+interface TransformPreset {
+    /** Width in pixels */
+    width?: number;
+    /** Height in pixels */
+    height?: number;
+    /** Fit mode */
+    fit?: 'cover' | 'contain' | 'scale-down' | 'crop' | 'pad';
+    /** Output format */
+    format?: 'webp' | 'avif' | 'json' | 'jpeg' | 'png' | 'auto';
+    /** Quality (1-100) */
+    quality?: number;
+    /** Device pixel ratio (1-3) */
+    dpr?: number;
+    /** Gravity for cropping */
+    gravity?: 'auto' | 'center' | 'top' | 'bottom' | 'left' | 'right' | 'face';
+    /** Sharpen (0-10) */
+    sharpen?: number;
+    /** Blur (1-250) */
+    blur?: number;
+    /** Brightness (-1 to 1) */
+    brightness?: number;
+    /** Contrast (-1 to 1) */
+    contrast?: number;
+    /** Rotation (0, 90, 180, 270) */
+    rotate?: 0 | 90 | 180 | 270;
+    /** Metadata handling */
+    metadata?: 'keep' | 'copyright' | 'none';
+    /** Background color for padding */
+    background?: string;
+}
+/**
+ * Error thrown when image transformation fails.
+ */
+declare class ImageTransformError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(message: string, status: number, code: string);
+}
+/**
+ * Create an image transformer route handler.
+ *
+ * This creates a GET handler that:
+ * 1. Extracts the source image URL from the request path
+ * 2. Parses transformation options from query parameters
+ * 3. Fetches the source image with Cloudflare Image Resizing options
+ * 4. Returns the transformed image
+ *
+ * @param config - Transformer configuration
+ * @returns Route handler function
+ *
+ * @example
+ * ```typescript
+ * // app/cdn/images/[...path]/route.ts
+ * import { createImageTransformer } from '@cloudwerk/images'
+ *
+ * export const GET = createImageTransformer({
+ *   allowedOrigins: ['https://images.mysite.com'],
+ *   presets: {
+ *     thumbnail: { width: 100, height: 100, fit: 'cover' },
+ *     hero: { width: 1920, height: 1080, fit: 'cover' },
+ *   },
+ *   defaults: {
+ *     format: 'auto',
+ *     quality: 85,
+ *   },
+ * })
+ *
+ * // Usage:
+ * // /cdn/images/https://images.mysite.com/photo.jpg?preset=thumbnail
+ * // /cdn/images/https://images.mysite.com/photo.jpg?w=800&h=600&fit=cover
+ * ```
+ */
+declare function createImageTransformer(config?: TransformerConfig): (request: Request, context: {
+    params: Record<string, string | string[]>;
+}) => Promise<Response>;
+/**
+ * Convert an ImageVariant to a TransformPreset.
+ * Useful when you want to reuse variants defined for Hosted Images.
+ */
+declare function variantToPreset(variant: ImageVariant): TransformPreset;
+
+/**
+ * @cloudwerk/images - Cloudflare IMAGES Binding Types
+ *
+ * Type definitions for the Cloudflare IMAGES binding used in Workers.
+ * This binding provides on-the-fly image transformation without uploading
+ * to Cloudflare Images.
+ *
+ * @example
+ * ```typescript
+ * // wrangler.toml
+ * [images]
+ * binding = "MY_IMAGES"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * import { getBinding } from '@cloudwerk/core/bindings'
+ * import type { CloudflareImagesBinding } from '@cloudwerk/images'
+ *
+ * const IMAGES = getBinding<CloudflareImagesBinding>('MY_IMAGES')
+ *
+ * // Transform an image
+ * const result = await IMAGES
+ *   .input(imageStream)
+ *   .transform({ width: 800 })
+ *   .output({ format: 'image/webp' })
+ *   .response()
+ * ```
+ */
+/**
+ * Image information returned by the IMAGES binding.
+ */
+interface CloudflareImageInfo {
+    /** Width of the image in pixels */
+    width: number;
+    /** Height of the image in pixels */
+    height: number;
+    /** Format of the image (e.g., 'image/jpeg', 'image/png') */
+    format: string;
+    /** File size in bytes */
+    fileSize: number;
+}
+/**
+ * Transform options for the IMAGES binding.
+ */
+interface CloudflareImageTransformOptions {
+    /** Width in pixels */
+    width?: number;
+    /** Height in pixels */
+    height?: number;
+    /** Fit mode for resizing */
+    fit?: 'scale-down' | 'contain' | 'cover' | 'crop' | 'pad';
+    /** Gravity for cropping */
+    gravity?: 'auto' | 'left' | 'right' | 'top' | 'bottom' | 'center' | 'face';
+    /** Quality for lossy formats (1-100) */
+    quality?: number;
+    /** Device pixel ratio (1-3) */
+    dpr?: number;
+    /** Rotation in degrees (0, 90, 180, 270) */
+    rotate?: 0 | 90 | 180 | 270;
+    /** Sharpen amount (0-10) */
+    sharpen?: number;
+    /** Blur radius (1-250) */
+    blur?: number;
+    /** Brightness adjustment (-1 to 1) */
+    brightness?: number;
+    /** Contrast adjustment (-1 to 1) */
+    contrast?: number;
+    /** Background color for padding (hex or rgb) */
+    background?: string;
+    /** Border configuration */
+    border?: {
+        color: string;
+        width: number;
+    };
+    /** Trim whitespace from edges */
+    trim?: {
+        top?: number;
+        right?: number;
+        bottom?: number;
+        left?: number;
+    };
+}
+/**
+ * Output options for the IMAGES binding.
+ */
+interface CloudflareImageOutputOptions {
+    /** Output format */
+    format?: 'image/jpeg' | 'image/png' | 'image/webp' | 'image/avif' | 'image/gif';
+    /** Quality for lossy formats (1-100) */
+    quality?: number;
+    /** Metadata handling */
+    metadata?: 'keep' | 'copyright' | 'none';
+}
+/**
+ * Result object returned after awaiting the transform pipeline.
+ * Use `.response()` to get the transformed image.
+ */
+interface CloudflareImagesTransformResult {
+    /**
+     * Get the transformed image as a Response.
+     * @returns Response containing the transformed image
+     */
+    response(): Response;
+}
+/**
+ * Transform builder interface for the IMAGES binding.
+ * Provides a fluent API for chaining transformations.
+ *
+ * @example
+ * ```typescript
+ * // The entire chain must be awaited, then call .response()
+ * const result = await IMAGES
+ *   .input(stream)
+ *   .transform({ rotate: 90 })
+ *   .output({ format: 'image/webp' })
+ *
+ * return result.response()
+ * ```
+ */
+interface CloudflareImagesTransformBuilder {
+    /**
+     * Apply transformation options to the image.
+     * Can be chained multiple times.
+     * @param options - Transformation options
+     * @returns The builder for chaining
+     */
+    transform(options: CloudflareImageTransformOptions): CloudflareImagesTransformBuilder;
+    /**
+     * Set output format and options.
+     * @param options - Output options
+     * @returns Promise that resolves to a result object with .response() method
+     */
+    output(options: CloudflareImageOutputOptions): Promise<CloudflareImagesTransformResult>;
+    /**
+     * Draw another image over this one (watermarking/compositing).
+     * @param image - Another transform builder or ReadableStream
+     * @param position - Position options (top, left, bottom, right, opacity, repeat)
+     * @returns The builder for chaining
+     */
+    draw(image: CloudflareImagesTransformBuilder | ReadableStream<Uint8Array>, position?: {
+        top?: number;
+        left?: number;
+        bottom?: number;
+        right?: number;
+        opacity?: number;
+        repeat?: boolean | 'x' | 'y';
+    }): CloudflareImagesTransformBuilder;
+}
+/**
+ * Cloudflare IMAGES binding interface.
+ *
+ * This binding provides access to Cloudflare's image transformation pipeline
+ * for on-the-fly image processing without uploading to Cloudflare Images.
+ *
+ * @example
+ * ```typescript
+ * import { getBinding } from '@cloudwerk/core/bindings'
+ * import type { CloudflareImagesBinding } from '@cloudwerk/images'
+ *
+ * export async function GET(request: Request) {
+ *   const IMAGES = getBinding<CloudflareImagesBinding>('MY_IMAGES')
+ *
+ *   // Transform an image from a stream
+ *   // Note: await the chain, then call .response()
+ *   const result = await IMAGES
+ *     .input(imageStream)
+ *     .transform({ width: 800, rotate: 90 })
+ *     .output({ format: 'image/webp' })
+ *
+ *   return result.response()
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Get image information
+ * const info = await IMAGES.info(imageStream)
+ * console.log(`Image size: ${info.width}x${info.height}`)
+ * ```
+ */
+interface CloudflareImagesBinding {
+    /**
+     * Start a transformation pipeline with an input image.
+     * @param source - Image source as Blob, ArrayBuffer, or ReadableStream
+     * @returns Transform builder for chaining operations
+     */
+    input(source: Blob | ArrayBuffer | ReadableStream<Uint8Array>): CloudflareImagesTransformBuilder;
+    /**
+     * Get information about an image without transforming it.
+     * @param source - Image source as Blob, ArrayBuffer, or ReadableStream
+     * @returns Image information including dimensions and format
+     */
+    info(source: Blob | ArrayBuffer | ReadableStream<Uint8Array>): Promise<CloudflareImageInfo>;
+}
+/**
+ * Fit modes for image resizing.
+ *
+ * - `scale-down`: Shrink to fit within dimensions, never enlarge
+ * - `contain`: Fit within dimensions, may add letterboxing
+ * - `cover`: Fill dimensions, cropping if necessary
+ * - `crop`: Crop to exact dimensions from center
+ * - `pad`: Fit within dimensions, padding if necessary
+ */
+type ImageFitMode = 'scale-down' | 'contain' | 'cover' | 'crop' | 'pad';
+/**
+ * Gravity options for cropping.
+ *
+ * - `auto`: Automatic based on image content
+ * - `left`, `right`, `top`, `bottom`: Align to edge
+ * - `center`: Center crop
+ * - `face`: Focus on detected faces
+ */
+type ImageGravity = 'auto' | 'left' | 'right' | 'top' | 'bottom' | 'center' | 'face';
+/**
+ * Supported output formats.
+ */
+type ImageOutputFormat = 'image/jpeg' | 'image/png' | 'image/webp' | 'image/avif' | 'image/gif';
+/**
+ * Metadata handling options.
+ *
+ * - `keep`: Preserve all metadata
+ * - `copyright`: Keep only copyright information
+ * - `none`: Strip all metadata
+ */
+type ImageMetadataHandling = 'keep' | 'copyright' | 'none';
+/**
+ * Preset transform configurations for common use cases.
+ */
+interface ImageTransformPreset {
+    /** Width in pixels */
+    width?: number;
+    /** Height in pixels */
+    height?: number;
+    /** Fit mode */
+    fit?: ImageFitMode;
+    /** Quality (1-100) */
+    quality?: number;
+    /** Output format */
+    format?: ImageOutputFormat;
+}
+/**
+ * Common presets for image transformations.
+ */
+declare const IMAGE_PRESETS: {
+    /** Small thumbnail (100x100 cover) */
+    readonly thumbnail: {
+        readonly width: 100;
+        readonly height: 100;
+        readonly fit: "cover";
+        readonly quality: 80;
+    };
+    /** Medium preview (400x400 contain) */
+    readonly preview: {
+        readonly width: 400;
+        readonly height: 400;
+        readonly fit: "contain";
+        readonly quality: 85;
+    };
+    /** Large display (1200px wide) */
+    readonly large: {
+        readonly width: 1200;
+        readonly fit: "scale-down";
+        readonly quality: 90;
+    };
+    /** Hero banner (1920x1080 cover) */
+    readonly hero: {
+        readonly width: 1920;
+        readonly height: 1080;
+        readonly fit: "cover";
+        readonly quality: 85;
+    };
+    /** Social share (1200x630 for Open Graph) */
+    readonly social: {
+        readonly width: 1200;
+        readonly height: 630;
+        readonly fit: "cover";
+        readonly quality: 85;
+    };
+    /** Mobile optimized (640px wide, WebP) */
+    readonly mobile: {
+        readonly width: 640;
+        readonly fit: "scale-down";
+        readonly quality: 75;
+        readonly format: "image/webp";
+    };
+};
+/**
+ * Type for preset names.
+ */
+type ImagePresetName = keyof typeof IMAGE_PRESETS;
+
+export { CLOUDFLARE_IMAGES_API, type CloudflareApiError, type CloudflareApiMessage, type CloudflareApiResponse, type CloudflareDirectUploadResponse, type CloudflareImage, type CloudflareImageDetailsResponse, type CloudflareImageInfo, type CloudflareImageOutputOptions, type CloudflareImageTransformOptions, type CloudflareImagesBinding, type CloudflareImagesStats, type CloudflareImagesTransformBuilder, type CloudflareImagesTransformResult, type CloudflareListResponse, type CloudflareUploadResponse, type CloudflareVariant, type DirectUploadOptions, type DirectUploadRequest, type DirectUploadResult, type EnvRef, IMAGE_PRESETS, ImageApiError, ImageBindingNotFoundError, ImageClient, type ImageClientInterface, type ImageConfig, ImageConfigError, ImageContextError, type ImageDefinition, type ImageEntry, ImageEnvError, ImageError, type ImageFitMode, type ImageGravity, type ImageManifest, type ImageMetadataHandling, ImageNotFoundError, type ImageOutputFormat, type ImagePresetName, type ImageResult, type ImageScanResult, ImageTransformError, type ImageTransformPreset, ImageUploadError, type ImageValidationError, type ImageValidationWarning, type ImageVariant, ImageVariantError, type ListOptions, type ScannedImage, type TransformPreset, type TransformerConfig, type UploadOptions, createImageClient, createImageTransformer, defineImage, isImageDefinition, variantToPreset };