import { z } from 'zod';
import type { RewindClient } from '../client.js';
export type TextBlock = {
    type: 'text';
    text: string;
};
export type ImageBlock = {
    type: 'image';
    data: string;
    mimeType: string;
};
export type ResourceLinkBlock = {
    type: 'resource_link';
    uri: string;
    name: string;
    mimeType?: string;
    description?: string;
};
export type ContentBlock = TextBlock | ImageBlock | ResourceLinkBlock;
export type ToolResult<S = unknown> = {
    content: ContentBlock[];
    structuredContent?: S;
    isError?: boolean;
};
/** Build a text content block. */
export declare function text(value: string): TextBlock;
/**
 * Build a resource_link content block.
 * Returns null if the URI is missing/empty so callers can `.filter(Boolean)`.
 */
export declare function resourceLink(uri: string | null | undefined, name: string, opts?: {
    mimeType?: string;
    description?: string;
}): ResourceLinkBlock | null;
/**
 * An image attachment as returned by Rewind entity responses.
 * Accepts both `cdn_url` (live API) and `url` (OpenAPI-schema-example field).
 */
export type ImageAttachment = {
    cdn_url?: string | null;
    url?: string | null;
    thumbhash?: string | null;
    dominant_color?: string | null;
    accent_color?: string | null;
} | null | undefined;
/**
 * Build an image content block from an entity's image attachment by fetching
 * the public CDN URL directly. Returns null on any failure or missing URL --
 * never throws. Image blocks are best-effort; we always want to return
 * text/data even if the image fetch breaks.
 *
 * Pass `targetPx` to request a smaller transform -- overrides the `width` and
 * `height` query params on the CDN URL. Useful for list tools that must stay
 * under the client's per-response size budget. Omit for full-size (typically
 * 300x300) detail-tool posters.
 */
export declare function imageBlock(client: RewindClient, image: ImageAttachment, targetPx?: number): Promise<ImageBlock | null>;
/** Target pixel size for list-tool image blocks. Keeps responses under ~250KB. */
export declare const LIST_IMAGE_PX = 150;
/** Extract host (e.g. "nytimes.com") from a URL for inline labels. */
export declare function hostOf(url: string | null | undefined): string;
/**
 * Wrap a tool handler that returns only text.
 * Returns { content, isError: true } on failure.
 */
export declare function withErrorHandling(fn: () => Promise<string>): Promise<{
    content: TextBlock[];
    isError?: boolean;
}>;
/**
 * Wrap a tool handler that returns a rich response (text + images + resource_links + structuredContent).
 * Returns a well-formed error ToolResult on failure.
 *
 * Callers should construct content arrays via the builders above and filter nulls:
 *   return {
 *     content: [text(summary), ...blocks.filter(Boolean)],
 *     structuredContent: data,
 *   };
 */
export declare function withRichResponse<S = unknown>(fn: () => Promise<ToolResult<S>>): Promise<ToolResult<S>>;
/** Format a date string as "Jan 15, 2025" */
export declare function formatDate(iso: string | null | undefined): string;
/** Format a date string as relative time like "2h ago" */
export declare function timeAgo(iso: string): string;
/** Format a number with commas */
export declare function fmt(n: number | null | undefined): string;
/**
 * Format a Letterboxd-style 0-5 star user rating. The Rewind API stores
 * these in the 0-5 half-star range (e.g. 4.5 = four and a half stars).
 * Renders as "4.5★" or "4★" -- never "4/10", which is a different scale.
 */
export declare function formatStars(r: number | null | undefined): string;
/** Common date filter params reused across tools. */
export declare const dateFilterParams: {
    date: z.ZodOptional<z.ZodString>;
    from: z.ZodOptional<z.ZodString>;
    to: z.ZodOptional<z.ZodString>;
};
/** Shared optional input for tools that return image content blocks. */
export declare const includeImagesParam: {
    include_images: z.ZodDefault<z.ZodBoolean>;
};
/**
 * Standard annotations for all Rewind tools. Read-only and closed-world:
 * every tool reads the user's own bounded archive via api.rewind.rest, never
 * an unbounded external space at call time.
 */
export declare const READ_ONLY_ANNOTATIONS: {
    readOnlyHint: true;
    destructiveHint: false;
    idempotentHint: true;
    openWorldHint: false;
};
export type { RewindClient };