/**
 * Content Item Builders
 *
 * Utility functions for constructing ContentItem objects in a type-safe manner.
 * These builders provide a convenient API for creating universal content items
 * from various input types.
 *
 * ## Builder Functions
 * - `textContent()`: Create text content items
 * - `imageContent()`: Create image content items
 * - `resourceContent()`: Create resource content items
 * - `normalizeContent()`: Convert any value to ContentItem array
 *
 * @example Creating content items
 * ```typescript
 * import { textContent, imageContent } from "@wavespec/kit/response";
 *
 * const text = textContent("Hello, world!");
 * const image = imageContent("base64data...", "image/png");
 * const resource = resourceContent("filedata...", "application/pdf");
 * ```
 *
 * @example Normalizing mixed content
 * ```typescript
 * const content = normalizeContent({
 *   text: "Some text",
 *   data: { nested: "object" }
 * });
 * // => [
 * //   { type: "text", text: "Some text" },
 * //   { type: "text", text: '{\n  "nested": "object"\n}' }
 * // ]
 * ```
 *
 * @module @wavespec/kit/response/builders
 */
import type { ContentItem } from "@wavespec/types";
/**
 * Create a text content item
 *
 * Wraps a string or text-like value in a text ContentItem. This is the most
 * common content type and is used for plain text, JSON, XML, and other
 * text-based formats.
 *
 * @param text - The text content
 * @param mimeType - Optional MIME type (e.g., "application/json", "text/html")
 * @returns ContentItem with type "text"
 *
 * @example Plain text
 * ```typescript
 * const item = textContent("Hello, world!");
 * // => { type: "text", text: "Hello, world!" }
 * ```
 *
 * @example JSON text
 * ```typescript
 * const item = textContent('{"name":"Alice"}', "application/json");
 * // => { type: "text", text: '{"name":"Alice"}', mimeType: "application/json" }
 * ```
 *
 * @example HTML text
 * ```typescript
 * const item = textContent("<h1>Title</h1>", "text/html");
 * // => { type: "text", text: "<h1>Title</h1>", mimeType: "text/html" }
 * ```
 */
export declare function textContent(text: string, mimeType?: string): ContentItem;
/**
 * Create an image content item
 *
 * Constructs an image ContentItem from base64-encoded image data. The data
 * should be base64-encoded binary image data, and the MIME type should
 * indicate the image format.
 *
 * @param data - Base64-encoded image data
 * @param mimeType - Image MIME type (e.g., "image/png", "image/jpeg", "image/gif")
 * @returns ContentItem with type "image"
 *
 * @example PNG image
 * ```typescript
 * const base64Png = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==";
 * const item = imageContent(base64Png, "image/png");
 * // => { type: "image", data: "iVBORw0...", mimeType: "image/png" }
 * ```
 *
 * @example JPEG image
 * ```typescript
 * const base64Jpeg = "/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAIB...";
 * const item = imageContent(base64Jpeg, "image/jpeg");
 * // => { type: "image", data: "/9j/4AAQSkZJRgA...", mimeType: "image/jpeg" }
 * ```
 *
 * @example GIF image
 * ```typescript
 * const base64Gif = "R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7";
 * const item = imageContent(base64Gif, "image/gif");
 * // => { type: "image", data: "R0lGODlh...", mimeType: "image/gif" }
 * ```
 */
export declare function imageContent(data: string, mimeType?: string): ContentItem;
/**
 * Create a resource content item
 *
 * Constructs a resource ContentItem for binary files or non-text data.
 * Resources are typically documents, archives, executables, or other
 * binary formats that aren't images.
 *
 * @param data - Base64-encoded or string resource data
 * @param mimeType - Resource MIME type (e.g., "application/pdf", "application/zip")
 * @returns ContentItem with type "resource"
 *
 * @example PDF document
 * ```typescript
 * const base64Pdf = "JVBERi0xLjQKJeLjz9MNCjEgMCBvYmo8PC9U...";
 * const item = resourceContent(base64Pdf, "application/pdf");
 * // => { type: "resource", data: "JVBERi0xLjQK...", mimeType: "application/pdf" }
 * ```
 *
 * @example ZIP archive
 * ```typescript
 * const base64Zip = "UEsDBAoAAAAAAIdO5lYAAAAAAAAAAAAAAAAJ...";
 * const item = resourceContent(base64Zip, "application/zip");
 * // => { type: "resource", data: "UEsDBAoAAAAA...", mimeType: "application/zip" }
 * ```
 *
 * @example Excel file
 * ```typescript
 * const base64Xlsx = "UEsDBBQABgAIAAAAIQDfpq7jWQEAAJsF...";
 * const item = resourceContent(base64Xlsx, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet");
 * // => { type: "resource", data: "UEsDBBQABgAI...", mimeType: "application/vnd..." }
 * ```
 */
export declare function resourceContent(data: string, mimeType?: string): ContentItem;
/**
 * Normalize any value to a ContentItem array
 *
 * Recursively processes a value of any type and converts it to an array of
 * ContentItems. This is the main normalization entry point for handling
 * diverse response formats from different protocols.
 *
 * ## Normalization Rules
 * 1. **null/undefined**: Filtered out (returns empty)
 * 2. **string**: Wrapped in text ContentItem
 * 3. **number/boolean**: Converted to string, wrapped in text ContentItem
 * 4. **ContentItem**: Returned as-is (after validation)
 * 5. **Array**: Each element normalized, results concatenated
 * 6. **Object with `type` field**: Validated as ContentItem
 * 7. **Plain object**: JSON.stringify with pretty formatting
 *
 * @param value - Any value to normalize (can be nested structures)
 * @returns Array of ContentItems (may be empty)
 *
 * @example Normalizing strings
 * ```typescript
 * normalizeContent("hello");
 * // => [{ type: "text", text: "hello" }]
 * ```
 *
 * @example Normalizing objects
 * ```typescript
 * normalizeContent({ name: "Alice", age: 30 });
 * // => [{ type: "text", text: '{\n  "name": "Alice",\n  "age": 30\n}' }]
 * ```
 *
 * @example Normalizing arrays
 * ```typescript
 * normalizeContent(["hello", { data: "world" }]);
 * // => [
 * //   { type: "text", text: "hello" },
 * //   { type: "text", text: '{\n  "data": "world"\n}' }
 * // ]
 * ```
 *
 * @example Normalizing ContentItems
 * ```typescript
 * normalizeContent([
 *   { type: "text", text: "Direct item" },
 *   "String to convert"
 * ]);
 * // => [
 * //   { type: "text", text: "Direct item" },
 * //   { type: "text", text: "String to convert" }
 * // ]
 * ```
 *
 * @example Mixed nested content
 * ```typescript
 * normalizeContent({
 *   text: "Some text",
 *   items: [1, 2, 3],
 *   nested: { deep: "value" }
 * });
 * // => [{ type: "text", text: '{\n  "text": "Some text",\n  "items": [1,2,3],\n  "nested": { "deep": "value" }\n}' }]
 * ```
 */
export declare function normalizeContent(value: unknown): ContentItem[];
//# sourceMappingURL=builders.d.ts.map