@cyanheads/gdelt-mcp-server 0.1.1

package/dist/services/gdelt/gdelt-doc-service.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @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?: 'date' | 'relevance' | 'social';
+};
+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

package/dist/services/gdelt/gdelt-doc-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gdelt-doc-service.d.ts","sourceRoot":"","sources":["../../../src/services/gdelt/gdelt-doc-service.ts"],"names":[],"mappings":"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"}

package/dist/services/gdelt/gdelt-doc-service.js

@@ -0,0 +1,116 @@
+/**
+ * @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 { applyTimeRange, gdeltFetch } from './gdelt-fetch.js';
+const DOC_ENDPOINT = '/doc/doc';
+export class GdeltDocService {
+    baseUrl;
+    constructor(_config, _storage, serverConfig) {
+        this.baseUrl = serverConfig.baseUrl + DOC_ENDPOINT;
+    }
+    /** Search articles (artlist mode). */
+    async searchArticles(params, ctx) {
+        const urlParams = this.buildBaseParams(params.query);
+        urlParams.set('mode', 'artlist');
+        if (params.maxRecords)
+            urlParams.set('maxrecords', String(params.maxRecords));
+        if (params.sort)
+            urlParams.set('sort', params.sort);
+        applyTimeRange(urlParams, params.timespan, params.startDatetime, params.endDatetime);
+        const raw = await this.fetch(urlParams, ctx);
+        const articles = (raw.articles ?? []).map(normalizeArticle);
+        return { articles, totalReturned: articles.length };
+    }
+    /** Fetch a coverage or tone timeline. */
+    async getTimeline(params, ctx) {
+        const urlParams = this.buildBaseParams(params.query);
+        urlParams.set('mode', params.mode);
+        if (params.smoothing != null)
+            urlParams.set('smoothing', String(params.smoothing));
+        applyTimeRange(urlParams, params.timespan, params.startDatetime, params.endDatetime);
+        if (params.mode === 'timelinevolinfo') {
+            const raw = await this.fetch(urlParams, ctx);
+            return parseVolInfoTimeline(raw);
+        }
+        const raw = await this.fetch(urlParams, ctx);
+        return parseTimeline(raw);
+    }
+    /** Fetch tone distribution histogram (tonechart mode). */
+    async getToneDistribution(params, ctx) {
+        const urlParams = this.buildBaseParams(params.query);
+        urlParams.set('mode', 'tonechart');
+        applyTimeRange(urlParams, params.timespan, params.startDatetime, params.endDatetime);
+        const raw = await this.fetch(urlParams, ctx);
+        return (raw.tonechart ?? []).map((b) => ({
+            bin: b.bin,
+            count: b.count,
+            articles: b.toparts ?? [],
+        }));
+    }
+    /** Fetch language or source-country breakdown time series. */
+    async getBreakdown(params, ctx) {
+        const urlParams = this.buildBaseParams(params.query);
+        urlParams.set('mode', params.mode);
+        applyTimeRange(urlParams, params.timespan, params.startDatetime, params.endDatetime);
+        const raw = await this.fetch(urlParams, ctx);
+        return parseTimeline(raw).map((s) => ({
+            label: s.label,
+            data: s.data.map((d) => ({ date: d.date, value: d.value })),
+        }));
+    }
+    // ─── Private helpers ────────────────────────────────────────────────────────
+    buildBaseParams(query) {
+        const p = new URLSearchParams();
+        p.set('query', query);
+        p.set('format', 'json');
+        return p;
+    }
+    fetch(params, ctx) {
+        return gdeltFetch(this.baseUrl, params, ctx, 'GdeltDocService.fetch', 'GDELT DOC');
+    }
+}
+// ─── Normalizers ─────────────────────────────────────────────────────────────
+function normalizeArticle(raw) {
+    return {
+        url: raw.url,
+        title: raw.title,
+        seendate: raw.seendate,
+        domain: raw.domain,
+        language: raw.language,
+        sourcecountry: raw.sourcecountry,
+        ...(raw.socialimage ? { socialimage: raw.socialimage } : {}),
+    };
+}
+function parseTimeline(raw) {
+    return (raw.timeline ?? []).map((s) => ({
+        label: s.series ?? 'Series',
+        data: (s.data ?? []).map((d) => ({ date: d.date, value: d.value })),
+    }));
+}
+function parseVolInfoTimeline(raw) {
+    return (raw.timeline ?? []).map((s) => ({
+        label: s.series ?? 'Volume Intensity',
+        data: (s.data ?? []).map((d) => ({
+            date: d.date,
+            value: d.value,
+            ...(d.toparts?.length
+                ? {
+                    articles: d.toparts.map((a) => ({ url: a.url, title: a.title })),
+                }
+                : {}),
+        })),
+    }));
+}
+// ─── Init/accessor pattern ────────────────────────────────────────────────────
+let _service;
+export function initGdeltDocService(config, storage, serverConfig) {
+    _service = new GdeltDocService(config, storage, serverConfig);
+}
+export function getGdeltDocService() {
+    if (!_service)
+        throw new Error('GdeltDocService not initialized — call initGdeltDocService() in setup()');
+    return _service;
+}
+//# sourceMappingURL=gdelt-doc-service.js.map

package/dist/services/gdelt/gdelt-doc-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gdelt-doc-service.js","sourceRoot":"","sources":["../../../src/services/gdelt/gdelt-doc-service.ts"],"names":[],"mappings":"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"}

package/dist/services/gdelt/gdelt-fetch.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @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';
+/** Apply timespan or explicit date range to URL params. */
+export declare function applyTimeRange(params: URLSearchParams, timespan?: string, startDatetime?: string, endDatetime?: string): void;
+/** Fetch a GDELT endpoint with rate-limiting, retries, and JSON parsing. */
+export declare function gdeltFetch<T>(baseUrl: string, params: URLSearchParams, ctx: Context, operation: string, apiLabel: string): Promise<T>;
+//# sourceMappingURL=gdelt-fetch.d.ts.map

package/dist/services/gdelt/gdelt-fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gdelt-fetch.d.ts","sourceRoot":"","sources":["../../../src/services/gdelt/gdelt-fetch.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAKtD,2DAA2D;AAC3D,wBAAgB,cAAc,CAC5B,MAAM,EAAE,eAAe,EACvB,QAAQ,CAAC,EAAE,MAAM,EACjB,aAAa,CAAC,EAAE,MAAM,EACtB,WAAW,CAAC,EAAE,MAAM,GACnB,IAAI,CAON;AAED,4EAA4E;AAC5E,wBAAgB,UAAU,CAAC,CAAC,EAC1B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,eAAe,EACvB,GAAG,EAAE,OAAO,EACZ,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,CAAC,CAAC,CAcZ"}

package/dist/services/gdelt/gdelt-fetch.js

@@ -0,0 +1,46 @@
+/**
+ * @fileoverview Shared fetch helper for GDELT API calls. Handles rate-limiting,
+ * retries, HTML error detection, and JSON parsing.
+ * @module services/gdelt/gdelt-fetch
+ */
+import { serializationError, serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
+import { fetchWithTimeout, withRetry } from '@cyanheads/mcp-ts-core/utils';
+import { getRateLimiter } from './rate-limiter.js';
+/** Apply timespan or explicit date range to URL params. */
+export function applyTimeRange(params, timespan, startDatetime, endDatetime) {
+    if (startDatetime && endDatetime) {
+        params.set('startdatetime', startDatetime);
+        params.set('enddatetime', endDatetime);
+    }
+    else if (timespan) {
+        params.set('timespan', timespan);
+    }
+}
+/** Fetch a GDELT endpoint with rate-limiting, retries, and JSON parsing. */
+export function gdeltFetch(baseUrl, params, ctx, operation, apiLabel) {
+    const limiter = getRateLimiter();
+    const rctx = ctx;
+    return withRetry(async () => {
+        await limiter.acquire();
+        const url = `${baseUrl}?${params.toString()}`;
+        ctx.log.debug(`${apiLabel} API request`, { url });
+        const response = await fetchWithTimeout(url, 30_000, rctx, { signal: ctx.signal });
+        const text = await response.text();
+        return parseGdeltJson(text, apiLabel);
+    }, { operation, context: rctx, baseDelayMs: 5100, signal: ctx.signal });
+}
+function parseGdeltJson(text, apiLabel) {
+    if (/^\s*<(!DOCTYPE\s+html|html[\s>])/i.test(text)) {
+        throw serviceUnavailable(`${apiLabel} API returned HTML — likely rate-limited or unavailable. Retry after 5 seconds.`);
+    }
+    if (text.trim().length === 0) {
+        throw serviceUnavailable(`${apiLabel} API returned an empty response — endpoint may be temporarily unavailable.`);
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw serializationError(`${apiLabel} API returned unparseable response: ${text.slice(0, 200)}`);
+    }
+}
+//# sourceMappingURL=gdelt-fetch.js.map

package/dist/services/gdelt/gdelt-fetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gdelt-fetch.js","sourceRoot":"","sources":["../../../src/services/gdelt/gdelt-fetch.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AACvF,OAAO,EAAE,gBAAgB,EAA2B,SAAS,EAAE,MAAM,8BAA8B,CAAC;AACpG,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAEnD,2DAA2D;AAC3D,MAAM,UAAU,cAAc,CAC5B,MAAuB,EACvB,QAAiB,EACjB,aAAsB,EACtB,WAAoB;IAEpB,IAAI,aAAa,IAAI,WAAW,EAAE,CAAC;QACjC,MAAM,CAAC,GAAG,CAAC,eAAe,EAAE,aAAa,CAAC,CAAC;QAC3C,MAAM,CAAC,GAAG,CAAC,aAAa,EAAE,WAAW,CAAC,CAAC;IACzC,CAAC;SAAM,IAAI,QAAQ,EAAE,CAAC;QACpB,MAAM,CAAC,GAAG,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;IACnC,CAAC;AACH,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,UAAU,CACxB,OAAe,EACf,MAAuB,EACvB,GAAY,EACZ,SAAiB,EACjB,QAAgB;IAEhB,MAAM,OAAO,GAAG,cAAc,EAAE,CAAC;IACjC,MAAM,IAAI,GAAG,GAAoC,CAAC;IAClD,OAAO,SAAS,CACd,KAAK,IAAI,EAAE;QACT,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC;QACxB,MAAM,GAAG,GAAG,GAAG,OAAO,IAAI,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC;QAC9C,GAAG,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,QAAQ,cAAc,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;QAClD,MAAM,QAAQ,GAAG,MAAM,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;QACnF,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;QACnC,OAAO,cAAc,CAAI,IAAI,EAAE,QAAQ,CAAC,CAAC;IAC3C,CAAC,EACD,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CACpE,CAAC;AACJ,CAAC;AAED,SAAS,cAAc,CAAI,IAAY,EAAE,QAAgB;IACvD,IAAI,mCAAmC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACnD,MAAM,kBAAkB,CACtB,GAAG,QAAQ,iFAAiF,CAC7F,CAAC;IACJ,CAAC;IACD,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7B,MAAM,kBAAkB,CACtB,GAAG,QAAQ,4EAA4E,CACxF,CAAC;IACJ,CAAC;IACD,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAM,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,kBAAkB,CACtB,GAAG,QAAQ,uCAAuC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CACvE,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/services/gdelt/gdelt-tv-service.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @fileoverview Service wrapping the GDELT TV API v2. Handles TV news transcript search,
+ * clip retrieval, context/word cloud, trending topics, and station metadata.
+ * @module services/gdelt/gdelt-tv-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 { TvClip, TvStation } from './types.js';
+export type TvSearchParams = {
+    query: string;
+    stations?: string[];
+    timespan?: string;
+    startDatetime?: string;
+    endDatetime?: string;
+    smoothing?: number;
+    normalize?: boolean;
+};
+export type TvClipParams = {
+    query: string;
+    stations?: string[];
+    timespan?: string;
+    startDatetime?: string;
+    endDatetime?: string;
+    maxRecords?: number;
+    sort?: 'relevance' | 'dateDesc' | 'dateAsc';
+};
+export type TvContextParams = {
+    query: string;
+    stations?: string[];
+    timespan?: string;
+};
+export type TvSearchSeries = {
+    station: string;
+    data: Array<{
+        date: string;
+        value: number;
+    }>;
+};
+export type TvContextWord = {
+    label: string;
+    score: number;
+};
+export type TvTrendingTopic = {
+    label: string;
+    score: number;
+};
+export declare class GdeltTvService {
+    private readonly baseUrl;
+    constructor(_config: AppConfig, _storage: StorageService, serverConfig: ServerConfig);
+    /** Search TV coverage — returns per-station normalized time series. */
+    searchTv(params: TvSearchParams, ctx: Context): Promise<{
+        series: TvSearchSeries[];
+        dateResolution: 'hour' | 'day' | 'month';
+        timeRange: {
+            start: string;
+            end: string;
+        };
+        normalized: boolean;
+    }>;
+    /** Retrieve TV clips (clip gallery). */
+    getTvClips(params: TvClipParams, ctx: Context): Promise<TvClip[]>;
+    /** Fetch word cloud / co-occurring terms for TV clips matching a query. */
+    getTvContext(params: TvContextParams, ctx: Context): Promise<{
+        words: TvContextWord[];
+        clipsAnalyzed: number;
+    }>;
+    /** Fetch currently trending topics on TV news. */
+    getTvTrending(ctx: Context): Promise<TvTrendingTopic[]>;
+    /** List all TV stations with metadata. */
+    listStations(ctx: Context): Promise<TvStation[]>;
+    private buildBaseParams;
+    private fetch;
+}
+export declare function initGdeltTvService(config: AppConfig, storage: StorageService, serverConfig: ServerConfig): void;
+export declare function getGdeltTvService(): GdeltTvService;
+//# sourceMappingURL=gdelt-tv-service.d.ts.map

package/dist/services/gdelt/gdelt-tv-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gdelt-tv-service.d.ts","sourceRoot":"","sources":["../../../src/services/gdelt/gdelt-tv-service.ts"],"names":[],"mappings":"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"}

package/dist/services/gdelt/gdelt-tv-service.js

@@ -0,0 +1,153 @@
+/**
+ * @fileoverview Service wrapping the GDELT TV API v2. Handles TV news transcript search,
+ * clip retrieval, context/word cloud, trending topics, and station metadata.
+ * @module services/gdelt/gdelt-tv-service
+ */
+import { applyTimeRange, gdeltFetch } from './gdelt-fetch.js';
+const TV_ENDPOINT = '/tv/tv';
+/** Threshold for "active" station: endDate within this many milliseconds of now. */
+const ACTIVE_THRESHOLD_MS = 24 * 60 * 60 * 1000; // 24 hours
+export class GdeltTvService {
+    baseUrl;
+    constructor(_config, _storage, serverConfig) {
+        this.baseUrl = serverConfig.baseUrl + TV_ENDPOINT;
+    }
+    /** Search TV coverage — returns per-station normalized time series. */
+    async searchTv(params, ctx) {
+        const urlParams = this.buildBaseParams(params.query, params.stations);
+        urlParams.set('mode', params.normalize !== false ? 'timelinevolnorm' : 'timelinevol');
+        if (params.smoothing != null)
+            urlParams.set('smoothing', String(params.smoothing));
+        applyTimeRange(urlParams, params.timespan, params.startDatetime, params.endDatetime);
+        const raw = await this.fetch(urlParams, ctx);
+        const series = (raw.timeline ?? []).map((s) => ({
+            station: s.series ?? 'Unknown',
+            data: (s.data ?? []).map((d) => ({ date: d.date, value: d.value })),
+        }));
+        const allDates = series.flatMap((s) => s.data.map((d) => d.date));
+        const sorted = allDates.slice().sort();
+        const timeRange = {
+            start: sorted[0] ?? '',
+            end: sorted[sorted.length - 1] ?? '',
+        };
+        const resStr = raw.dateresolution ?? 'day';
+        const dateResolution = resStr === 'hour' ? 'hour' : resStr === 'month' ? 'month' : 'day';
+        return { series, dateResolution, timeRange, normalized: params.normalize !== false };
+    }
+    /** Retrieve TV clips (clip gallery). */
+    async getTvClips(params, ctx) {
+        const urlParams = this.buildBaseParams(params.query, params.stations);
+        urlParams.set('mode', 'clipgallery');
+        if (params.maxRecords)
+            urlParams.set('maxrecords', String(params.maxRecords));
+        if (params.sort) {
+            const sortMap = { relevance: 'relevance', dateDesc: 'date', dateAsc: 'date' };
+            urlParams.set('sort', sortMap[params.sort]);
+            if (params.sort === 'dateAsc')
+                urlParams.set('sortdir', 'asc');
+        }
+        applyTimeRange(urlParams, params.timespan, params.startDatetime, params.endDatetime);
+        const raw = await this.fetch(urlParams, ctx);
+        return (raw.clips ?? []).map((c) => ({
+            show: c.show,
+            station: c.station,
+            date: c.date,
+            snippet: c.snippet,
+            archiveUrl: c.preview_url,
+            ...(c.preview_thumb ? { thumbnail: c.preview_thumb } : {}),
+        }));
+    }
+    /** Fetch word cloud / co-occurring terms for TV clips matching a query. */
+    async getTvContext(params, ctx) {
+        const urlParams = this.buildBaseParams(params.query, params.stations);
+        urlParams.set('mode', 'wordcloud');
+        if (params.timespan)
+            urlParams.set('timespan', params.timespan);
+        const raw = await this.fetch(urlParams, ctx);
+        const words = (raw.wordcloud ?? []).map((w) => ({
+            label: w.label,
+            score: w.count,
+        }));
+        return { words, clipsAnalyzed: raw.numclips ?? 0 };
+    }
+    /** Fetch currently trending topics on TV news. */
+    async getTvTrending(ctx) {
+        const urlParams = new URLSearchParams();
+        urlParams.set('mode', 'trendingtopics');
+        urlParams.set('format', 'json');
+        const raw = await this.fetch(urlParams, ctx);
+        return (raw.OverallTrendingTopics ?? raw.OverallTrendingPhrases ?? []).map((t) => ({
+            label: t.label,
+            score: t.score,
+        }));
+    }
+    /** List all TV stations with metadata. */
+    async listStations(ctx) {
+        const urlParams = new URLSearchParams();
+        urlParams.set('mode', 'stationdetails');
+        urlParams.set('format', 'json');
+        const raw = await this.fetch(urlParams, ctx);
+        const now = Date.now();
+        return (raw.station_details ?? []).map((s) => {
+            const endMs = parseGdeltDate(s.EndDate);
+            const isActive = endMs != null && now - endMs < ACTIVE_THRESHOLD_MS;
+            return {
+                stationId: s.StationID,
+                description: s.Description,
+                market: s.Market,
+                network: s.Network,
+                startDate: formatGdeltDate(s.StartDate),
+                endDate: formatGdeltDate(s.EndDate),
+                isActive,
+            };
+        });
+    }
+    // ─── Private helpers ────────────────────────────────────────────────────────
+    buildBaseParams(query, stations) {
+        const p = new URLSearchParams();
+        // TV API embeds station filters inside the query string
+        let q = query;
+        if (stations?.length) {
+            q += ' ' + stations.map((s) => `station:${s}`).join(' ');
+        }
+        p.set('query', q);
+        p.set('format', 'json');
+        return p;
+    }
+    fetch(params, ctx) {
+        return gdeltFetch(this.baseUrl, params, ctx, 'GdeltTvService.fetch', 'GDELT TV');
+    }
+}
+/** Parse GDELT date string (YYYYMMDDHHMMSS or YYYYMMDD) to ms epoch. Returns undefined on failure. */
+function parseGdeltDate(s) {
+    if (!s)
+        return;
+    const clean = s.replace(/\D/g, '');
+    if (clean.length < 8)
+        return;
+    const year = parseInt(clean.slice(0, 4), 10);
+    const month = parseInt(clean.slice(4, 6), 10) - 1;
+    const day = parseInt(clean.slice(6, 8), 10);
+    const d = new Date(year, month, day);
+    return Number.isNaN(d.getTime()) ? undefined : d.getTime();
+}
+/** Convert GDELT date string to ISO 8601. Returns original on failure. */
+function formatGdeltDate(s) {
+    if (!s)
+        return s;
+    const clean = s.replace(/\D/g, '');
+    if (clean.length < 8)
+        return s;
+    return `${clean.slice(0, 4)}-${clean.slice(4, 6)}-${clean.slice(6, 8)}`;
+}
+// ─── Init/accessor pattern ────────────────────────────────────────────────────
+let _service;
+export function initGdeltTvService(config, storage, serverConfig) {
+    _service = new GdeltTvService(config, storage, serverConfig);
+}
+export function getGdeltTvService() {
+    if (!_service)
+        throw new Error('GdeltTvService not initialized — call initGdeltTvService() in setup()');
+    return _service;
+}
+//# sourceMappingURL=gdelt-tv-service.js.map

package/dist/services/gdelt/gdelt-tv-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gdelt-tv-service.js","sourceRoot":"","sources":["../../../src/services/gdelt/gdelt-tv-service.ts"],"names":[],"mappings":"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"}

package/dist/services/gdelt/rate-limiter.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @fileoverview Shared rate limiter for GDELT API calls. Enforces 1 request per 5 seconds
+ * across all API calls (DOC and TV) via a serial queue with minimum delay.
+ * @module services/gdelt/rate-limiter
+ */
+/** Singleton that serializes all GDELT API calls with a minimum inter-request delay. */
+export declare class GdeltRateLimiter {
+    private readonly delayMs;
+    private lastRequestTime;
+    private queue;
+    private processing;
+    constructor(delayMs: number);
+    /** Acquire a rate-limit slot. Resolves when it is safe to issue the next request. */
+    acquire(): Promise<void>;
+    private processQueue;
+}
+export declare function initRateLimiter(delayMs: number): void;
+export declare function getRateLimiter(): GdeltRateLimiter;
+//# sourceMappingURL=rate-limiter.d.ts.map

package/dist/services/gdelt/rate-limiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.d.ts","sourceRoot":"","sources":["../../../src/services/gdelt/rate-limiter.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,wFAAwF;AACxF,qBAAa,gBAAgB;IAKf,OAAO,CAAC,QAAQ,CAAC,OAAO;IAJpC,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,KAAK,CAAyB;IACtC,OAAO,CAAC,UAAU,CAAS;gBAEE,OAAO,EAAE,MAAM;IAE5C,qFAAqF;IACrF,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;YAOV,YAAY;CAc3B;AAID,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAErD;AAED,wBAAgB,cAAc,IAAI,gBAAgB,CAIjD"}

package/dist/services/gdelt/rate-limiter.js

@@ -0,0 +1,47 @@
+/**
+ * @fileoverview Shared rate limiter for GDELT API calls. Enforces 1 request per 5 seconds
+ * across all API calls (DOC and TV) via a serial queue with minimum delay.
+ * @module services/gdelt/rate-limiter
+ */
+/** Singleton that serializes all GDELT API calls with a minimum inter-request delay. */
+export class GdeltRateLimiter {
+    delayMs;
+    lastRequestTime = 0;
+    queue = [];
+    processing = false;
+    constructor(delayMs) {
+        this.delayMs = delayMs;
+    }
+    /** Acquire a rate-limit slot. Resolves when it is safe to issue the next request. */
+    acquire() {
+        return new Promise((resolve) => {
+            this.queue.push(resolve);
+            if (!this.processing)
+                this.processQueue();
+        });
+    }
+    async processQueue() {
+        this.processing = true;
+        while (this.queue.length > 0) {
+            const now = Date.now();
+            const elapsed = now - this.lastRequestTime;
+            if (elapsed < this.delayMs) {
+                await new Promise((r) => setTimeout(r, this.delayMs - elapsed));
+            }
+            this.lastRequestTime = Date.now();
+            const next = this.queue.shift();
+            next?.();
+        }
+        this.processing = false;
+    }
+}
+let _limiter;
+export function initRateLimiter(delayMs) {
+    _limiter = new GdeltRateLimiter(delayMs);
+}
+export function getRateLimiter() {
+    if (!_limiter)
+        throw new Error('GdeltRateLimiter not initialized — call initRateLimiter() in setup()');
+    return _limiter;
+}
+//# sourceMappingURL=rate-limiter.js.map

package/dist/services/gdelt/rate-limiter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.js","sourceRoot":"","sources":["../../../src/services/gdelt/rate-limiter.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,wFAAwF;AACxF,MAAM,OAAO,gBAAgB;IAKE;IAJrB,eAAe,GAAG,CAAC,CAAC;IACpB,KAAK,GAAsB,EAAE,CAAC;IAC9B,UAAU,GAAG,KAAK,CAAC;IAE3B,YAA6B,OAAe;QAAf,YAAO,GAAP,OAAO,CAAQ;IAAG,CAAC;IAEhD,qFAAqF;IACrF,OAAO;QACL,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;YACnC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACzB,IAAI,CAAC,IAAI,CAAC,UAAU;gBAAE,IAAI,CAAC,YAAY,EAAE,CAAC;QAC5C,CAAC,CAAC,CAAC;IACL,CAAC;IAEO,KAAK,CAAC,YAAY;QACxB,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;QACvB,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC7B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YACvB,MAAM,OAAO,GAAG,GAAG,GAAG,IAAI,CAAC,eAAe,CAAC;YAC3C,IAAI,OAAO,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;gBAC3B,MAAM,IAAI,OAAO,CAAO,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;YACxE,CAAC;YACD,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YAClC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;YAChC,IAAI,EAAE,EAAE,CAAC;QACX,CAAC;QACD,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC;IAC1B,CAAC;CACF;AAED,IAAI,QAAsC,CAAC;AAE3C,MAAM,UAAU,eAAe,CAAC,OAAe;IAC7C,QAAQ,GAAG,IAAI,gBAAgB,CAAC,OAAO,CAAC,CAAC;AAC3C,CAAC;AAED,MAAM,UAAU,cAAc;IAC5B,IAAI,CAAC,QAAQ;QACX,MAAM,IAAI,KAAK,CAAC,sEAAsE,CAAC,CAAC;IAC1F,OAAO,QAAQ,CAAC;AAClB,CAAC"}