@providerprotocol/ai 0.0.18 → 0.0.20

package/dist/image-Dhq-Yuq4.d.ts

@@ -0,0 +1,456 @@
+import { P as ProviderConfig, h as ImageProvider } from './provider-BBMBZuGn.js';
+import { b as ImageSource, I as ImageBlock } from './content-DEl3z_W2.js';
+
+/**
+ * @fileoverview Image content handling for the Universal Provider Protocol.
+ *
+ * Provides a unified Image class for working with images across different sources
+ * (file paths, URLs, raw bytes, base64). Supports conversion between formats and
+ * integration with UPP message content blocks.
+ *
+ * @module core/media/Image
+ */
+
+/**
+ * Represents an image that can be used in UPP messages.
+ *
+ * Images can be created from various sources (files, URLs, bytes, base64) and
+ * converted to different formats as needed by providers. The class provides
+ * a unified interface regardless of the underlying source type.
+ *
+ * @example
+ * ```typescript
+ * // Load from file
+ * const fileImage = await Image.fromPath('./photo.jpg');
+ *
+ * // Reference by URL
+ * const urlImage = Image.fromUrl('https://example.com/image.png');
+ *
+ * // From raw bytes
+ * const bytesImage = Image.fromBytes(uint8Array, 'image/png');
+ *
+ * // Use in a message
+ * const message = new UserMessage([image.toBlock()]);
+ * ```
+ */
+declare class Image {
+    /** The underlying image source (bytes, base64, or URL) */
+    readonly source: ImageSource;
+    /** MIME type of the image (e.g., 'image/jpeg', 'image/png') */
+    readonly mimeType: string;
+    /** Image width in pixels, if known */
+    readonly width?: number;
+    /** Image height in pixels, if known */
+    readonly height?: number;
+    private constructor();
+    /**
+     * Whether this image has data loaded in memory.
+     *
+     * Returns `false` for URL-sourced images that reference external resources.
+     * These must be fetched before their data can be accessed.
+     */
+    get hasData(): boolean;
+    /**
+     * Converts the image to a base64-encoded string.
+     *
+     * @returns The image data as a base64 string
+     * @throws {Error} When the source is a URL (data must be fetched first)
+     */
+    toBase64(): string;
+    /**
+     * Converts the image to a data URL suitable for embedding in HTML or CSS.
+     *
+     * @returns A data URL in the format `data:{mimeType};base64,{data}`
+     * @throws {Error} When the source is a URL (data must be fetched first)
+     */
+    toDataUrl(): string;
+    /**
+     * Gets the image data as raw bytes.
+     *
+     * @returns The image data as a Uint8Array
+     * @throws {Error} When the source is a URL (data must be fetched first)
+     */
+    toBytes(): Uint8Array;
+    /**
+     * Gets the URL for URL-sourced images.
+     *
+     * @returns The image URL
+     * @throws {Error} When the source is not a URL
+     */
+    toUrl(): string;
+    /**
+     * Converts this Image to an ImageBlock for use in UPP messages.
+     *
+     * @returns An ImageBlock that can be included in message content arrays
+     */
+    toBlock(): ImageBlock;
+    /**
+     * Creates an Image by reading a file from disk.
+     *
+     * The file is read into memory as bytes. MIME type is automatically
+     * detected from the file extension.
+     *
+     * @param path - Path to the image file
+     * @returns Promise resolving to an Image with the file contents
+     *
+     * @example
+     * ```typescript
+     * const image = await Image.fromPath('./photos/vacation.jpg');
+     * ```
+     */
+    static fromPath(path: string): Promise<Image>;
+    /**
+     * Creates an Image from a URL reference.
+     *
+     * The URL is stored as a reference and not fetched. Providers will handle
+     * URL-to-data conversion if needed. MIME type is detected from the URL
+     * path if not provided.
+     *
+     * @param url - URL pointing to the image
+     * @param mimeType - Optional MIME type override
+     * @returns An Image referencing the URL
+     *
+     * @example
+     * ```typescript
+     * const image = Image.fromUrl('https://example.com/logo.png');
+     * ```
+     */
+    static fromUrl(url: string, mimeType?: string): Image;
+    /**
+     * Creates an Image from raw byte data.
+     *
+     * @param data - The image data as a Uint8Array
+     * @param mimeType - The MIME type of the image
+     * @returns An Image containing the byte data
+     *
+     * @example
+     * ```typescript
+     * const image = Image.fromBytes(pngData, 'image/png');
+     * ```
+     */
+    static fromBytes(data: Uint8Array, mimeType: string): Image;
+    /**
+     * Creates an Image from a base64-encoded string.
+     *
+     * @param base64 - The base64-encoded image data (without data URL prefix)
+     * @param mimeType - The MIME type of the image
+     * @returns An Image containing the base64 data
+     *
+     * @example
+     * ```typescript
+     * const image = Image.fromBase64(base64String, 'image/jpeg');
+     * ```
+     */
+    static fromBase64(base64: string, mimeType: string): Image;
+    /**
+     * Creates an Image from an existing ImageBlock.
+     *
+     * Useful for converting content blocks received from providers back
+     * into Image instances for further processing.
+     *
+     * @param block - An ImageBlock from message content
+     * @returns An Image with the block's source and metadata
+     */
+    static fromBlock(block: ImageBlock): Image;
+}
+
+/**
+ * @fileoverview Image generation types for the Universal Provider Protocol.
+ *
+ * Defines the interfaces for configuring and executing image generation operations,
+ * including options, instances, requests, responses, streaming, and capabilities.
+ *
+ * @module types/image
+ */
+
+/**
+ * Structural type for image model input.
+ * Uses structural typing to avoid generic variance issues with Provider generics.
+ */
+interface ImageModelInput {
+    readonly modelId: string;
+    readonly provider: {
+        readonly name: string;
+        readonly version: string;
+        readonly modalities: {
+            image?: unknown;
+        };
+    };
+}
+/**
+ * Options for creating an image instance with the image() function.
+ *
+ * @typeParam TParams - Provider-specific parameter type
+ *
+ * @example
+ * ```typescript
+ * const options: ImageOptions<OpenAIImageParams> = {
+ *   model: openai('dall-e-3'),
+ *   config: { apiKey: process.env.OPENAI_API_KEY },
+ *   params: { size: '1024x1024', quality: 'hd' }
+ * };
+ * ```
+ */
+interface ImageOptions<TParams = unknown> {
+    /** A model reference from a provider factory */
+    model: ImageModelInput;
+    /** Provider infrastructure configuration */
+    config?: ProviderConfig;
+    /** Provider-specific parameters (passed through unchanged) */
+    params?: TParams;
+}
+/**
+ * Input type for generate() - either a string prompt or object with prompt.
+ */
+type ImageInput = string | {
+    prompt: string;
+};
+/**
+ * Input for edit() operations.
+ */
+interface ImageEditInput {
+    /** Base image to edit */
+    image: Image;
+    /** Mask indicating edit region (interpretation varies by provider) */
+    mask?: Image;
+    /** Edit instruction prompt */
+    prompt: string;
+}
+/**
+ * A single generated image with optional metadata.
+ */
+interface GeneratedImage {
+    /** The generated image */
+    image: Image;
+    /** Provider-specific per-image metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Usage statistics for image generation.
+ * Fields are optional because providers report usage differently.
+ */
+interface ImageUsage {
+    /** Number of images generated */
+    imagesGenerated?: number;
+    /** Input tokens consumed (token-based pricing) */
+    inputTokens?: number;
+    /** Output tokens consumed (token-based pricing) */
+    outputTokens?: number;
+    /** Provider-reported cost (credits, dollars, etc.) */
+    cost?: number;
+}
+/**
+ * Result from generate() or edit() calls.
+ */
+interface ImageResult {
+    /** Generated images */
+    images: GeneratedImage[];
+    /** Provider-specific response metadata */
+    metadata?: Record<string, unknown>;
+    /** Usage/billing information */
+    usage?: ImageUsage;
+}
+/**
+ * Stream events for image generation.
+ */
+type ImageStreamEvent = {
+    type: 'preview';
+    image: Image;
+    index: number;
+    metadata?: Record<string, unknown>;
+} | {
+    type: 'complete';
+    image: GeneratedImage;
+    index: number;
+};
+/**
+ * Async iterable stream with final result accessor.
+ * Returned when stream() is called.
+ */
+interface ImageStreamResult extends AsyncIterable<ImageStreamEvent> {
+    /** Promise resolving to complete result after streaming */
+    readonly result: Promise<ImageResult>;
+    /** Abort the generation */
+    abort(): void;
+}
+/**
+ * Image generation capabilities.
+ */
+interface ImageCapabilities {
+    /** Supports text-to-image generation */
+    generate: boolean;
+    /** Supports streaming with partial previews */
+    streaming: boolean;
+    /** Supports image editing/inpainting */
+    edit: boolean;
+    /** Maximum images per request (if known) */
+    maxImages?: number;
+}
+/**
+ * Image instance returned by the image() function.
+ *
+ * @typeParam TParams - Provider-specific parameter type
+ *
+ * @example
+ * ```typescript
+ * const dalle = image({ model: openai('dall-e-3') });
+ *
+ * // Simple generation
+ * const result = await dalle.generate('A sunset over mountains');
+ *
+ * // Streaming (if supported)
+ * if (dalle.capabilities.streaming && dalle.stream) {
+ *   const stream = dalle.stream('A cyberpunk cityscape');
+ *   for await (const event of stream) {
+ *     // Handle preview/complete events
+ *   }
+ * }
+ * ```
+ */
+interface ImageInstance<TParams = unknown> {
+    /**
+     * Generate images from a text prompt.
+     *
+     * @param input - The prompt string or object with prompt
+     * @returns Promise resolving to the generated images
+     */
+    generate(input: ImageInput): Promise<ImageResult>;
+    /**
+     * Generate with streaming progress (if supported).
+     * Only available when capabilities.streaming is true.
+     *
+     * @param input - The prompt string or object with prompt
+     * @returns ImageStreamResult with events and final result
+     */
+    stream?(input: ImageInput): ImageStreamResult;
+    /**
+     * Edit an existing image (if supported).
+     * Only available when capabilities.edit is true.
+     *
+     * @param input - Edit input with image, optional mask, and prompt
+     * @returns Promise resolving to the edited images
+     */
+    edit?(input: ImageEditInput): Promise<ImageResult>;
+    /** The bound image model */
+    readonly model: BoundImageModel<TParams>;
+    /** Current parameters */
+    readonly params: TParams | undefined;
+    /** Model capabilities */
+    readonly capabilities: ImageCapabilities;
+}
+/**
+ * Request passed from image() core to providers for generation.
+ * @internal
+ */
+interface ImageRequest<TParams = unknown> {
+    /** Generation prompt */
+    prompt: string;
+    /** Provider-specific parameters (passed through unchanged) */
+    params?: TParams;
+    /** Provider infrastructure config */
+    config: ProviderConfig;
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+}
+/**
+ * Request passed to providers for edit operations.
+ * @internal
+ */
+interface ImageEditRequest<TParams = unknown> {
+    /** Base image to edit */
+    image: Image;
+    /** Edit mask */
+    mask?: Image;
+    /** Edit instruction prompt */
+    prompt: string;
+    /** Provider-specific parameters */
+    params?: TParams;
+    /** Provider infrastructure config */
+    config: ProviderConfig;
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+}
+/**
+ * Response from provider's generate or edit method.
+ * @internal
+ */
+interface ImageResponse {
+    /** Generated images */
+    images: GeneratedImage[];
+    /** Provider-specific response metadata */
+    metadata?: Record<string, unknown>;
+    /** Usage information */
+    usage?: ImageUsage;
+}
+/**
+ * Raw provider stream result.
+ * An async iterable of ImageStreamEvent with a response promise.
+ * @internal
+ */
+interface ImageProviderStreamResult extends AsyncIterable<ImageStreamEvent> {
+    /** Promise resolving to the complete response */
+    readonly response: Promise<ImageResponse>;
+}
+/**
+ * Bound image model - full definition.
+ *
+ * Represents an image model bound to a specific provider and model ID,
+ * ready to execute generation requests.
+ *
+ * @typeParam TParams - Provider-specific parameter type
+ */
+interface BoundImageModel<TParams = unknown> {
+    /** The model identifier */
+    readonly modelId: string;
+    /** Reference to the parent provider */
+    readonly provider: ImageProvider<TParams>;
+    /** Model capabilities */
+    readonly capabilities: ImageCapabilities;
+    /**
+     * Generate images from a prompt.
+     *
+     * @param request - The generation request
+     * @returns Promise resolving to the response
+     */
+    generate(request: ImageRequest<TParams>): Promise<ImageResponse>;
+    /**
+     * Stream image generation (optional).
+     *
+     * @param request - The generation request
+     * @returns Stream result with events and final response
+     */
+    stream?(request: ImageRequest<TParams>): ImageProviderStreamResult;
+    /**
+     * Edit an image (optional).
+     *
+     * @param request - The edit request
+     * @returns Promise resolving to the response
+     */
+    edit?(request: ImageEditRequest<TParams>): Promise<ImageResponse>;
+}
+/**
+ * Image Handler interface for providers.
+ *
+ * Implemented by providers to enable image generation capabilities.
+ *
+ * @typeParam TParams - Provider-specific parameter type
+ */
+interface ImageHandler<TParams = unknown> {
+    /**
+     * Binds a model ID to create an executable image model.
+     *
+     * @param modelId - The model identifier to bind
+     * @returns A bound image model ready for generation
+     */
+    bind(modelId: string): BoundImageModel<TParams>;
+    /**
+     * Sets the parent provider reference.
+     * Called by createProvider() after the provider is constructed.
+     *
+     * @param provider - The parent provider
+     * @internal
+     */
+    _setProvider?(provider: ImageProvider<TParams>): void;
+}
+
+export { type BoundImageModel as B, type GeneratedImage as G, type ImageOptions as I, type ImageInstance as a, Image as b, type ImageInput as c, type ImageEditInput as d, type ImageUsage as e, type ImageResult as f, type ImageStreamEvent as g, type ImageStreamResult as h, type ImageCapabilities as i, type ImageRequest as j, type ImageEditRequest as k, type ImageResponse as l, type ImageProviderStreamResult as m, type ImageHandler as n, type ImageModelInput as o };