import type { PromptDefinition, PromptLabel, PromptReference, PromptStore, PromptVersion, RenderedPrompt, RenderOptions } from '../types/prompts.js';
/** The read side of a prompt store, which is all serving needs. */
export type PromptSource = Pick<PromptStore, 'getLabel' | 'getVersion'>;
/** Options for a prompt client. */
export interface PromptClientOptions {
    /** Where labels and versions are read from: a store, or a registry's `store`. */
    source: PromptSource;
    /** Label served when a call names none. Defaults to `production`. */
    label?: string;
    /** How long a label is served without asking the source again, in milliseconds. Defaults to 60 seconds. */
    ttlMs?: number;
    /**
     * How long after `ttlMs` a label is still served immediately while it refreshes in the background,
     * in milliseconds. Defaults to `ttlMs`. Past it, a call waits for the refresh.
     */
    staleWhileRevalidateMs?: number;
    /**
     * Serves the last version seen when a refresh fails, however old, so a registry outage does not take
     * prompts down with it. Defaults to true.
     */
    serveStaleOnError?: boolean;
    /** Definitions served when the source has nothing and nothing is cached, such as the prompts bundled in code. */
    fallbacks?: ReadonlyArray<PromptDefinition | {
        definition: PromptDefinition;
    }>;
    /** Receives refresh failures, including the ones hidden by serving a stale version. */
    onError?: (error: unknown, name: string, label: string) => void;
    /** Labels cached before the least recently refreshed is dropped. Defaults to 500. */
    maxEntries?: number;
    /** Replaces the system clock, in epoch milliseconds, for tests. */
    now?: () => number;
}
/** A version chosen for one call, and how it was obtained. */
export interface ServedPrompt {
    /** The version served. */
    version: PromptVersion;
    /** Name, version, label, and arm, as rendered requests record them. */
    reference: PromptReference;
    /** `cache` when fresh, `stale` when served past its TTL, `source` when just fetched, `fallback` when bundled. */
    from: 'cache' | 'stale' | 'source' | 'fallback';
}
/**
 * Serves prompts by label to application code, fast and through outages.
 *
 * A label is read from the source at most once per `ttlMs`; within the stale window a call is answered
 * from cache while the label refreshes in the background, and when the source is unreachable the last
 * version seen keeps serving. Versions never change, so once fetched they are kept. A split label
 * picks its arm by `key`, so the same user sees the same version on every call.
 */
export declare class PromptClient {
    private readonly options;
    private readonly labels;
    private readonly inflight;
    private readonly versions;
    private readonly fallbacks;
    private readonly fallbackVersions;
    private readonly now;
    constructor(options: PromptClientOptions);
    /** The version to serve for a prompt, choosing an A/B arm by `key` when the label splits traffic. */
    get(name: string, options?: {
        label?: string;
        key?: string;
    }): Promise<ServedPrompt>;
    /** Renders a prompt by label, recording what was served in `metadata.prompt`. */
    render(name: string, variables?: Record<string, unknown>, options?: RenderOptions & {
        label?: string;
        key?: string;
    }): Promise<RenderedPrompt>;
    /**
     * Reads a label from the source now, with every version it serves, and caches them. Concurrent
     * refreshes of one label share a request.
     */
    refresh(name: string, label?: string): Promise<PromptLabel>;
    private refreshEntry;
    /** Forgets every cached label and version. */
    clear(): void;
    private loadVersion;
    private fallback;
}