/**
 * @fileoverview Shared fetch helper for GDELT API calls. Handles rate-limiting,
 * retries, HTML error detection, and JSON parsing.
 * @module services/gdelt/gdelt-fetch
 */
import type { Context } from '@cyanheads/mcp-ts-core';
/**
 * The `gdelt_unavailable` contract entry every upstream-backed tool declares, as it reaches
 * the wire. The hint is the declared `recovery` for that reason; the service layer throws
 * below `ctx.fail`, so it is carried here rather than resolved from the contract.
 */
export declare const GDELT_UNAVAILABLE_DATA: {
    readonly reason: 'gdelt_unavailable';
    readonly retryable: true;
    readonly recovery: {
        readonly hint: 'Retry after a short delay; GDELT may be temporarily unavailable.';
    };
};
/** Apply timespan or explicit date range to URL params. */
export declare function applyTimeRange(params: URLSearchParams, timespan?: string, startDatetime?: string, endDatetime?: string): void;
/**
 * Resolve a GDELT timespan string (e.g. "1y", "6m", "7d", "24h", "15min") to an
 * absolute `{ start, end }` date range anchored to now.
 * Returns `undefined` when the string cannot be parsed.
 */
export declare function resolveTimespan(timespan: string): {
    start: Date;
    end: Date;
} | undefined;
/** Format a Date as YYYY-MM-DD for human-readable display. */
export declare function formatDateShort(d: Date): string;
/**
 * Fetch a GDELT endpoint through the shared pacer, with retries and JSON parsing.
 *
 * Retry outside, pacer inside: each attempt re-queues and is re-paced, and the pacer's
 * cooldown gate is an absolute instant rather than a duration counted from dequeue, so a
 * backoff and the gate overlap in wall-clock instead of summing. Both GDELT rate-limit
 * shapes — the HTTP 429 `failFastOnRateLimit` re-throws and the HTTP-200 notice
 * `parseGdeltJson` classifies — are raised inside the paced task as a `RateLimited`
 * `McpError`, which is what closes the gate for every other queued caller.
 *
 * Two clocks bound the call. `GDELT_REQUEST_TIMEOUT_MS` is one attempt's deadline, clamped to
 * whatever is left of the total budget so an attempt cannot overshoot it; the budget itself is
 * `GDELT_CALL_DEADLINE_MULTIPLIER` times that, threaded through `withRetry`'s `deadlineMs` so
 * the caller gets this server's classified error rather than their own transport timeout.
 */
export declare function gdeltFetch<T>(baseUrl: string, params: URLSearchParams, ctx: Context, operation: string, apiLabel: string): Promise<T>;
/**
 * Parse a GDELT response body, classifying the non-JSON bodies GDELT returns for
 * upstream trouble (HTML, empty) and caller-side query rejections (see
 * `GDELT_REJECTIONS`) before falling back to a generic serialization failure.
 *
 * Exported for direct testing — production callers reach it through `gdeltFetch`.
 */
export declare function parseGdeltJson<T>(text: string, apiLabel: string): T;
//# sourceMappingURL=gdelt-fetch.d.ts.map