/**
 * Standardized response helpers for MCP tool results.
 *
 * Goals:
 *   - Token-efficient columnar format for tabular/time-series data
 *   - Consistent envelope across all 37 modules
 *   - Server-side stats for numeric data (min/max/mean/trend)
 *   - Uniform truncation with clear signaling
 *
 * Usage in a module:
 *   import { tableResponse, timeseriesResponse, recordResponse, listResponse, emptyResponse } from "../response.js";
 *
 *   // Time-series (FRED, BLS, EIA, NOAA, etc.)
 *   return timeseriesResponse("GDP: 100 observations", {
 *     rows: data.observations,             // array of objects from the API
 *     dateKey: "date",                      // which field is the date/period
 *     valueKey: "value",                    // which field is the primary numeric value
 *   });
 *
 *   // Table (Census, FDIC, FDA, DOL, etc.)
 *   return tableResponse("FDIC institutions: 500 total, showing 50", {
 *     rows: records,                        // array of objects
 *     columns: ["INSTNAME", "STALP", "ASSET", "DEP"],  // optional — auto-detected if omitted
 *   });
 *
 *   // Single record (bill details, series info, etc.)
 *   return recordResponse("HR 1234: Infrastructure Investment Act", record);
 *
 *   // List of non-tabular items (search results, suggestions, etc.)
 *   return listResponse("FRED search: 50 results", { items: series, total: 200 });
 *
 *   // Empty result
 *   return emptyResponse("No bills found matching 'infrastructure'.");
 */
export interface TimeseriesStats {
    count: number;
    min: number | null;
    max: number | null;
    mean: number | null;
    first: {
        date: string;
        value: number;
    } | null;
    last: {
        date: string;
        value: number;
    } | null;
    trend: "increasing" | "decreasing" | "stable" | "volatile" | null;
}
/** Accept any object — typed interfaces and plain Records alike. */
type AnyRow = Record<string, any>;
/**
 * Time-series response — optimized for date+value data (FRED, BLS, EIA, NOAA, etc.)
 *
 * Converts array-of-objects to columnar format + computes stats.
 * Columns default to [dateKey, valueKey, ...extraFields].
 */
export declare function timeseriesResponse(summary: string, opts: {
    rows: AnyRow[];
    dateKey: string;
    valueKey: string;
    extraFields?: string[];
    total?: number;
    maxRows?: number;
    meta?: Record<string, unknown>;
}): string;
/**
 * Table response — for tabular data with multiple columns (Census, FDIC, FDA, DOL, etc.)
 *
 * Converts array-of-objects to columnar format. No stats computed.
 */
export declare function tableResponse(summary: string, opts: {
    rows: AnyRow[];
    columns?: string[];
    total?: number;
    maxRows?: number;
    meta?: Record<string, unknown>;
}): string;
/**
 * Record response — for single-record lookups (bill details, series info, etc.)
 *
 * Strips null values from the record to save tokens.
 */
export declare function recordResponse(summary: string, record: AnyRow, meta?: Record<string, unknown>): string;
/**
 * List response — for search results, suggestions, and other item lists.
 *
 * Keeps the array-of-objects format (items may be heterogeneous or nested),
 * but strips nulls from each item and enforces a max-items cap.
 */
export declare function listResponse(summary: string, opts: {
    items: AnyRow[];
    total?: number;
    maxItems?: number;
    meta?: Record<string, unknown>;
}): string;
/**
 * Empty/no-result response — consistent across all modules.
 */
export declare function emptyResponse(message: string): string;
/**
 * Strip HTML tags and decode HTML entities safely.
 * Uses the `he` library for complete, standards-compliant entity decoding
 * (handles all named, numeric, and hex entities including double-encoded ones).
 *
 * @param input — raw HTML string (or unknown value)
 * @returns plain text with entities decoded and whitespace normalized
 */
export declare function cleanHtml(input: unknown): string;
export {};
//# sourceMappingURL=response.d.ts.map