Access-Control-Allow-Origin: <origin>
Access-Control-Allow-Methods: GET, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization
Cache-Control: public, s-maxage=<TTL>, stale-while-revalidate=<TTL*2>
Content-Type: application/json; charset=utf-8

/** Returns CORS headers object for the given request and allowed methods. */
function getCorsHeaders(
  req: Request,
  methods?: string   // default "GET, OPTIONS"
): Record<string, string>;

/** Returns true if the request origin is NOT on the allowlist. */
function isDisallowedOrigin(req: Request): boolean;

/** Record a cache outcome for a named endpoint. */
function recordCacheTelemetry(
  endpoint: string,
  outcome: "HIT" | "MISS" | "STALE"
): void;

/** Return the current telemetry snapshot. */
function getCacheTelemetrySnapshot(): Record<string, {
  hit: number;
  miss: number;
  stale: number;
  total: number;
  hitRate: number;   // 0–1 float
}>;

function createIpRateLimiter(opts?: {
  limit?: number;              // default 60
  windowMs?: number;           // default 60_000 (1 min)
  maxEntries?: number;         // default 10_000
  cleanupIntervalMs?: number;  // default 300_000 (5 min)
}): {
  check(ip: string): { allowed: boolean; retryAfter?: number };
  size(): number;
};

/** Retrieve cached JSON by key. Returns null on miss. */
async function getCachedJson<T = unknown>(key: string): Promise<T | null>;

/** Store JSON with a TTL in seconds. */
async function setCachedJson(key: string, value: unknown, ttlSeconds: number): Promise<void>;

/** Batch-get multiple keys. Returns array in same order (null for misses). */
async function mget<T = unknown>(...keys: string[]): Promise<(T | null)[]>;

/** Deterministic hash for building cache keys. */
function hashString(str: string): string;

interface AcledResponse {
  success: true;
  data: AcledEvent[];
}

interface AcledEvent {
  event_id_cnty: string;
  event_date: string;        // "YYYY-MM-DD"
  event_type: string;
  sub_event_type: string;
  actor1: string;
  country: string;
  latitude: number;
  longitude: number;
  fatalities: number;
  notes: string;
}

interface UcdpCatalogResponse {
  Result: UcdpConflict[];
  TotalCount: number;
  NextPageUrl: string | null;
  PreviousPageUrl: string | null;
}

interface UcdpEventsResponse {
  Result: UcdpGeoEvent[];
}

interface UcdpGeoEvent {
  id: number;
  type_of_violence: number;   // 1=state, 2=non-state, 3=one-sided
  country: string;
  latitude: number;
  longitude: number;
  date_start: string;
  date_end: string;
  deaths_a: number;
  deaths_b: number;
  deaths_civilians: number;
  best: number;               // best estimate of total fatalities
}

interface CountryIntelRequest {
  country: string;       // required — country name or ISO code
  context?: object;      // optional additional context for the LLM
}

interface CountryIntelResponse {
  brief: string;   // markdown-formatted intelligence brief
}

interface FinnhubResponse {
  [symbol: string]: {
    c: number;    // current price
    d: number;    // change (delta)
    dp: number;   // percent change (delta %)
    h: number;    // high of the day
    l: number;    // low of the day
    o: number;    // open price
    pc: number;   // previous close
    t: number;    // timestamp (unix)
  };
}

type CoinGeckoResponse = CoinGeckoMarket[];

interface CoinGeckoMarket {
  id: string;
  symbol: string;
  name: string;
  current_price: number;
  market_cap: number;
  total_volume: number;
  price_change_24h: number;
  price_change_percentage_24h: number;
  sparkline_in_7d?: { price: number[] };
  // ...additional CoinGecko fields
}

interface StablecoinMarketsResponse {
  coins: StablecoinData[];
  timestamp: number;
  unavailable?: boolean;     // true when upstream is unreachable
}

interface StablecoinData {
  id: string;
  symbol: string;
  name: string;
  current_price: number;
  peg_deviation: number;     // deviation from $1.00
  price_change_24h: number;
  high_24h: number;
  low_24h: number;
  market_cap: number;
}

interface ETFFlowsResponse {
  etfs: ETFFlow[];
  totalNetFlow: number;
  timestamp: number;
  unavailable?: boolean;
}

interface ETFFlow {
  symbol: string;
  name: string;
  volume: number;
  estimatedFlow: number;
  price: number;
}

interface StockIndexResponse {
  indices: StockIndex[];
  timestamp: number;
}

interface StockIndex {
  symbol: string;
  name: string;
  country: string;
  price: number;
  change: number;
  changePercent: number;
}

interface FredDataResponse {
  observations: FredObservation[];
}

interface FredObservation {
  date: string;     // "YYYY-MM-DD"
  value: string;    // numeric string
}

interface MacroSignalsResponse {
  verdict: "BUY" | "CASH";
  confidence: number;          // 0–1
  signals: MacroSignal[];
  timestamp: number;
  unavailable?: boolean;
}

interface MacroSignal {
  name: string;
  // One of: liquidity, flowStructure, macroRegime,
  //         technicalTrend, hashRate, miningCost, fearGreed
  value: number;
  signal: "BUY" | "CASH" | "NEUTRAL";
  weight: number;
  source: string;
}

type PolymarketResponse = PredictionMarket[];

interface PredictionMarket {
  id: string;
  question: string;
  outcomePrices: string[];    // array of price strings
  volume: number;
  endDate: string;
  active: boolean;
}

interface OpenSkyResponse {
  time: number;
  states: FlightState[][];
}

// FlightState tuple indices:
// [0]  icao24          string   – ICAO 24-bit address
// [1]  callsign        string   – callsign (trimmed)
// [2]  origin_country  string
// [3]  time_position   number   – unix timestamp
// [4]  last_contact    number   – unix timestamp
// [5]  longitude       number
// [6]  latitude        number
// [7]  baro_altitude   number   – barometric altitude (m)
// [8]  on_ground       boolean
// [9]  velocity        number   – m/s
// [10] true_track       number   – heading (degrees)
// [11] vertical_rate   number   – m/s
// [12] sensors         number[]
// [13] geo_altitude    number   – geometric altitude (m)
// [14] squawk          string
// [15] spi             boolean  – special purpose indicator
// [16] position_source number   – 0=ADS-B, 1=ASTERIX, 2=MLAT

interface AISSnapshotResponse {
  vessels: AISVessel[];
  timestamp: number;
  count: number;
}

interface AISVessel {
  mmsi: number;
  name?: string;
  lat: number;
  lon: number;
  cog: number;       // course over ground
  sog: number;       // speed over ground (knots)
  heading?: number;
  shipType?: number;
  destination?: string;
  timestamp: number;
}

interface TheaterPostureResponse {
  theaters: TheaterPosture[];
  globalReadiness: number;     // 0–1 composite score
  timestamp: number;
}

interface TheaterPosture {
  region: string;              // e.g., "EUCOM", "INDOPACOM"
  alertLevel: string;          // "LOW" | "ELEVATED" | "HIGH" | "CRITICAL"
  flightActivity: number;
  assessment: string;          // human-readable assessment
}

interface CyberThreatsResponse {
  threats: CyberThreat[];
  sources: string[];
  timestamp: number;
}

interface CyberThreat {
  ip: string;
  type: string;           // "botnet" | "c2" | "malware" | "scanner" | ...
  source: string;         // originating feed
  country: string;
  latitude: number;
  longitude: number;
  confidence: number;     // 0–100
  tags: string[];
}

interface EarthquakeFeature {
  type: "Feature";
  properties: {
    mag: number;
    place: string;
    time: number;          // unix ms
    url: string;
    tsunami: number;       // 0 or 1
    type: string;
  };
  geometry: {
    type: "Point";
    coordinates: [number, number, number];  // [lon, lat, depth_km]
  };
}

interface FIRMSResponse {
  fires: FIRMSFire[];
  count: number;
  regions: string[];
}

interface FIRMSFire {
  latitude: number;
  longitude: number;
  brightness: number;
  frp: number;              // fire radiative power (MW)
  confidence: string;       // "low" | "nominal" | "high"
  acq_date: string;         // "YYYY-MM-DD"
  acq_time: string;         // "HHMM" UTC
  satellite: string;        // "MODIS" | "VIIRS" | ...
}

interface ClimateAnomaliesResponse {
  zones: ClimateZone[];
  globalAnomaly: number;
  timestamp: number;
}

interface ClimateZone {
  name: string;
  tempAnomaly: number;       // °C above/below baseline
  precipAnomaly: number;     // mm above/below baseline
  severity: string;          // "normal" | "moderate" | "severe" | "extreme"
}

interface ClassifyBatchRequest {
  items: ClassifyItem[];     // max 20
}

interface ClassifyItem {
  title: string;
  description?: string;
}

interface ClassifyBatchResponse {
  results: Classification[];
}

interface Classification {
  category: string;
  severity: string;         // "low" | "medium" | "high" | "critical"
  confidence: number;       // 0–1
  tags: string[];
}

interface ClassifyEventResponse {
  category: string;
  severity: string;
  confidence: number;
  tags: string[];
}

interface SummarizeRequest {
  text: string;          // article text to summarize
  type?: string;         // content type hint
  panelId?: string;      // originating panel identifier
}

interface SummarizeResponse {
  summary: string;
}

interface CloudflareOutagesResponse {
  outages: CloudflareOutage[];
  count: number;
}

interface CloudflareOutage {
  id: string;
  name: string;
  scope: string;
  asns: number[];
  locations: string[];
  startDate: string;
  endDate?: string;
  eventType: string;
}

interface ServiceStatusResponse {
  services: ServiceStatus[];
}

interface ServiceStatus {
  name: string;
  status: "operational" | "degraded" | "major" | "critical";
  url: string;
  indicator: string;
}

interface UNHCRResponse {
  items: DisplacementRecord[];
  pagination: {
    page: number;
    pages: number;
    total: number;
  };
}

interface DisplacementRecord {
  year: number;
  country_of_origin: string;
  country_of_asylum: string;
  refugees: number;
  asylum_seekers: number;
  internally_displaced: number;
  stateless: number;
}

interface HapiResponse {
  data: HapiConflictEvent[];
}

interface HapiConflictEvent {
  event_type: string;
  admin1: string;
  admin2: string;
  location_name: string;
  country: string;
  date: string;
  fatalities: number;
  latitude: number;
  longitude: number;
}

interface PopulationExposure {
  country: string;
  mode: "conflict" | "earthquake" | "flood" | "fire";
  exposedPopulation: number;
  totalPopulation: number;
  percentage: number;         // 0–100
}

interface WorldBankResponse {
  data: WorldBankIndicator[];
}

interface WorldBankIndicator {
  country: { id: string; value: string };
  date: string;
  value: number | null;
  indicator: { id: string; value: string };
}

type HackerNewsResponse = HNStory[];

interface HNStory {
  id: number;
  title: string;
  url?: string;
  score: number;
  by: string;
  time: number;            // unix timestamp
  descendants: number;     // comment count
}

type GitHubTrendingResponse = TrendingRepo[];

interface TrendingRepo {
  name: string;
  owner: string;
  description: string;
  stars: number;
  forks: number;
  language: string | null;
  todayStars: number;
  url: string;
}

type TechEventsResponse = TechEvent[];

interface TechEvent {
  name: string;
  date: string;
  location: string;
  lat: number;
  lng: number;
  category: string;
  url: string;
}

interface VersionResponse {
  version: string;           // e.g., "1.4.2"
  url: string;               // release page URL
  published_at: string;      // ISO 8601 date
}

{ "error": "Not available" }

interface RiskScoresResponse {
  scores: RiskScore[];
  timestamp: number;
}

interface RiskScore {
  country: string;
  countryCode: string;
  cii: number;                // Country Instability Index (0–100)
  components: {
    conflict: number;
    economic: number;
    governance: number;
    social: number;
  };
  trend: "improving" | "stable" | "deteriorating";
}

interface BaselineReadResponse {
  mean: number;
  variance: number;
  stddev: number;
  count: number;
  lastUpdated: string;      // ISO 8601
}

interface BaselineUpdateRequest {
  key: string;
  value: number;
}

interface BaselineUpdateResponse {
  updated: true;
  stats: {
    mean: number;
    variance: number;
    stddev: number;
    count: number;
  };
}

interface ErrorResponse {
  error: string;               // human-readable message
  status?: number;             // HTTP status code (sometimes included)
  details?: string;            // additional context (dev-mode only)
}

HTTP/1.1 429 Too Many Requests
Retry-After: 42
Content-Type: application/json

{
  "error": "Rate limit exceeded",
  "retryAfter": 42
}

┌──────────────────────────────────────────────────┐
│                   Client                         │
└──────────────────┬───────────────────────────────┘
                   │
┌──────────────────▼───────────────────────────────┐
│  Tier 1: Vercel CDN Edge Cache                   │
│  ─────────────────────────────────               │
│  • Cache-Control: s-maxage=<TTL>                 │
│  • stale-while-revalidate=<TTL*2>                │
│  • Fastest — zero origin hit on cache hit        │
│  • TTLs: 15 s (real-time) to 3600 s (static)    │
└──────────────────┬───────────────────────────────┘
                   │ (CDN MISS)
┌──────────────────▼───────────────────────────────┐
│  Tier 2: Upstash Redis                           │
│  ─────────────────────────────────               │
│  • Distributed, shared across all Edge instances │
│  • Key-value with per-key TTL                    │
│  • Used for expensive/quota-limited upstreams    │
│  • TTLs: 120 s (crypto) to 7 776 000 s (90 d)   │
│  • Sidecar mode: in-memory Map + disk persist    │
└──────────────────┬───────────────────────────────┘
                   │ (Upstash MISS)
┌──────────────────▼───────────────────────────────┐
│  Tier 3: In-Memory Map (per-instance)            │
│  ─────────────────────────────────               │
│  • Process-local, fastest read path              │
│  • Used as write-through for hot endpoints       │
│  • Bounded by MAX_PERSIST_ENTRIES (5000)         │
│  • Survives within a single Edge invocation      │
└──────────────────┬───────────────────────────────┘
                   │ (All MISS)
┌──────────────────▼───────────────────────────────┐
│  Origin: External API                            │
│  ─────────────────────────────────               │
│  • Actual upstream fetch                         │
│  • Result written back to all applicable tiers   │
└──────────────────────────────────────────────────┘

{
  "acled": { "hit": 142, "miss": 8, "stale": 3, "total": 153, "hitRate": 0.928 },
  "earthquakes": { "hit": 891, "miss": 12, "stale": 0, "total": 903, "hitRate": 0.987 }
}