/**
 * @fileoverview Service wrapping the GDELT DOC API v2. Handles article search,
 * coverage timelines, tone distribution, and language/country breakdowns.
 * @module services/gdelt/gdelt-doc-service
 */
import type { Context } from '@cyanheads/mcp-ts-core';
import type { AppConfig } from '@cyanheads/mcp-ts-core/config';
import type { StorageService } from '@cyanheads/mcp-ts-core/storage';
import type { ServerConfig } from '../../config/server-config.js';
import type { Article } from './types.js';
export type DocTimelineMode = 'timelinevol' | 'timelinevolinfo' | 'timelinetone';
export type DocBreakdownMode = 'timelinelang' | 'timelinesourcecountry';
export type DocSearchParams = {
    query: string;
    timespan?: string;
    startDatetime?: string;
    endDatetime?: string;
    maxRecords?: number;
    sort?: 'relevance' | 'dateDesc' | 'dateAsc' | 'toneDesc' | 'toneAsc' | 'hybridRel';
};
export type DocTimelineParams = {
    query: string;
    mode: DocTimelineMode;
    timespan?: string;
    startDatetime?: string;
    endDatetime?: string;
    smoothing?: number;
};
export type DocToneParams = {
    query: string;
    timespan?: string;
    startDatetime?: string;
    endDatetime?: string;
};
export type DocBreakdownParams = {
    query: string;
    mode: DocBreakdownMode;
    timespan?: string;
    startDatetime?: string;
    endDatetime?: string;
};
export type ArticleSearchResult = {
    articles: Article[];
    totalReturned: number;
};
export type TimelineDataPoint = {
    date: string;
    value: number;
    articles?: Array<{
        url: string;
        title: string;
    }>;
};
export type TimelineSeries = {
    label: string;
    data: TimelineDataPoint[];
};
export type ToneHistogramBin = {
    bin: number;
    count: number;
    articles: Array<{
        url: string;
        title: string;
    }>;
};
export type BreakdownSeries = {
    label: string;
    data: Array<{
        date: string;
        value: number;
    }>;
};
export declare class GdeltDocService {
    private readonly baseUrl;
    constructor(_config: AppConfig, _storage: StorageService, serverConfig: ServerConfig);
    /** Search articles (artlist mode). */
    searchArticles(params: DocSearchParams, ctx: Context): Promise<ArticleSearchResult>;
    /** Fetch a coverage or tone timeline. */
    getTimeline(params: DocTimelineParams, ctx: Context): Promise<TimelineSeries[]>;
    /** Fetch tone distribution histogram (tonechart mode). */
    getToneDistribution(params: DocToneParams, ctx: Context): Promise<ToneHistogramBin[]>;
    /** Fetch language or source-country breakdown time series. */
    getBreakdown(params: DocBreakdownParams, ctx: Context): Promise<BreakdownSeries[]>;
    private buildBaseParams;
    private fetch;
}
export declare function initGdeltDocService(config: AppConfig, storage: StorageService, serverConfig: ServerConfig): void;
export declare function getGdeltDocService(): GdeltDocService;
//# sourceMappingURL=gdelt-doc-service.d.ts.map