mirror of
https://github.com/koala73/worldmonitor.git
synced 2026-04-26 01:24:59 +02:00
45f5e5a457
* feat(forecast): add AI Forecasts prediction module (Pro-tier)
MiroFish-inspired prediction engine that generates structured forecasts
across 6 domains (conflict, market, supply chain, political, military,
infrastructure) using existing WorldMonitor data streams.
- Proto definitions for ForecastService with GetForecasts RPC
- Dedicated seed script (seed-forecasts.mjs) with 6 domain detectors,
cross-domain cascade resolver, prediction market calibration, and
trend detection via prior snapshot comparison
- Premium-gated RPC handler (PREMIUM_RPC_PATHS enforcement)
- Lazy-loaded ForecastPanel with domain filters, probability bars,
trend arrows, signal evidence, and cascade links
- Health monitoring integration (seed-meta freshness tracking)
- Refresh scheduler with API key guard
* test(forecast): add 47 unit tests for forecast detectors and utilities
Covers forecastId, normalize, resolveCascades, calibrateWithMarkets,
computeTrends, and smoke tests for all 6 domain detectors. Exports
testable functions from seed script with direct-run guard.
* fix(forecast): domain mismatch 'infra' vs 'infrastructure', add panel category
- Seed script used 'infra' but ForecastPanel filtered on 'infrastructure',
causing Infra tab to show zero results
- Added 'forecast' to intelligence category in PANEL_CATEGORY_MAP
* fix(forecast): move CSS to one-time injection, improve type safety
- P2: Move style block from setContent to one-time document.head injection
to prevent CSS accumulation on repeated renders
- P3: Replace +toFixed(3) with Math.round for readability in seed script
- P3: Use Forecast type instead of any[] in RPC handler filter
* fix(forecast): handle sebuf proto data shapes from Redis
Detectors now normalize CII scores from server-side proto format
(combinedScore, TREND_DIRECTION_RISING, region) to uniform shape.
Outage severity handles proto enum format (SEVERITY_LEVEL_HIGH).
Added confidence floor of 0.3 for single-source predictions.
Verified against live Redis: 2 predictions generated (Iran infra
shutdown, IL political instability).
* feat(forecast): unlock AI Forecasts on web, lock desktop only (trial)
- Remove forecast RPC from PREMIUM_RPC_PATHS (web access is free)
- Panel locked on desktop only (same as oref-sirens/telegram-intel)
- Remove API key guards from data-loader and refresh scheduler
- Web users get full access during trial period
* chore: regenerate proto types with make generate
Re-ran make generate after rebasing on main. Plugin v0.7.0 dropped
@ts-nocheck from output, added it back to all 50 generated files.
Fixed 4 type errors from proto codegen changes:
- MarketSource enum -> string union type
- TemporalAnomalyProto -> TemporalAnomaly rename
- webcam lastUpdated number -> string
* fix(forecast): use chokepoints v4 key, include ciiContribution in unrest
- P1: Switch chokepoints input from stale v2 to active v4 Redis key,
matching bootstrap.js and cache-keys.ts
- P2: Add ciiContribution to unrest component fallback chain in
normalizeCiiEntry so political detector reads the correct sebuf field
* feat(forecast): Phase 2 LLM scenario enrichment + confidence model
MiroFish-inspired enhancements:
- LLM scenario narratives via Groq/OpenRouter (narrative-only, no numeric
adjustment). Evidence-grounded prompts with mandatory signal citation
and few-shot examples from MiroFish's SECTION_SYSTEM_PROMPT_TEMPLATE.
- Top-4 predictions batched into single LLM call for cost efficiency.
- News context from newsInsights attached to all predictions for LLM
prompt grounding (NOT in signals, cannot affect confidence).
- Deterministic confidence model: source diversity via SIGNAL_TO_SOURCE
mapping (deduplicates cii+cii_delta, theater+indicators) + calibration
agreement from prediction market drift. Floor 0.2, ceiling 1.0.
- Output validation: rejects scenarios without signal references.
- Truncated JSON repair for small model output.
- Structured JSON logging for LLM calls.
- Redis cache for LLM scenarios (1h TTL).
- 23 new tests (70 total), all passing.
- Live-tested: OpenRouter gemini-2.5-flash produces evidence-grounded
scenario narratives from real WorldMonitor data.
* feat(forecast): Phase 3 multi-perspective scenarios, projections, data-driven cascades
MiroFish-inspired enhancements:
- Multi-perspective LLM analysis: top-2 predictions get strategic,
regional, and contrarian viewpoints via combined LLM call
- Probability projections: domain-specific decay curves (h24/d7/d30)
anchored to timeHorizon so probability equals projections[timeHorizon]
- Data-driven cascade rules: moved from hardcoded array to JSON config
(scripts/data/cascade-rules.json) with schema validation, named
predicate evaluators, unknown key rejection, and fallback to defaults
- 4 new cascade paths: infrastructure->supply_chain, infrastructure->market
(both requiresSeverity:total), conflict->political, political->market
- Proto: added Perspectives and Projections messages to Forecast
- ForecastPanel: renders projections row and conditional perspectives toggle
- 89 tests (19 new), all passing
- Live-tested: OpenRouter produces perspectives from real data
* feat(forecast): Phase 4 data utilization + entity graph
Fixes data gaps that prevented 4 of 6 detectors from firing:
- Input normalizers: chokepoint v4 shape + GPS hexes-to-zones mapping
- Chokepoint warm-ping (production-only, requires WM_API_BASE_URL)
- Lowered CII conflict threshold from 70 to 60, gated on level=high|critical
4 new standalone detectors:
- UCDP conflict zones (10+ events per country)
- Cyber threat concentration (5+ threats per country)
- GPS jamming in maritime shipping zones (5 regions)
- Prediction markets as signals (60-90% probability markets)
Entity-relationship graph (file-based, 38 nodes):
- Countries, theaters, commodities, chokepoints, alliances
- Alias table resolves both ISO codes and display names
- Graph cascade discovery links predictions across entities
Result: 51 predictions (up from 1-2), spanning conflict, infrastructure,
and supply chain domains. 112 tests, all passing.
* fix(forecast): redis cache format, signal source mapping, type safety
Fresh-eyes audit fixes:
- BUG: redisSet used wrong Upstash API format (POST body with {value,ex}
instead of command array ['SET',key,value,'EX',ttl]). LLM cache writes
were silently failing, causing fresh LLM calls every run.
- BUG: prediction_market signal type missing from SIGNAL_TO_SOURCE,
inflating confidence for market-derived predictions.
- CLEANUP: Remove unnecessary (f as any) casts in ForecastPanel since
generated Forecast type already has projections/perspectives fields.
- CLEANUP: Bump health maxStaleMin from 60 to 90 to avoid false STALE
alerts when LLM calls add latency to seed runs.
* feat(forecast): headline-entity matching with news corroboration signals
Uses entity graph aliases to match headlines to predictions by
country/theater (excludes commodity/infrastructure nodes to prevent
false positives). Predictions with matching headlines get a
news_corroboration signal visible in the panel.
Also fixes buildUserPrompt to merge unique headlines from ALL
predictions in the LLM batch (was only reading preds[0].newsContext).
Live-tested: 13 of 51 predictions now have corroborating headlines
(Iran, Israel, Syria, Ukraine, etc). 116 tests, all passing.
* feat(forecast): add country-codes.json for headline-entity matching
56 countries with ISO codes, full names, and scoring keywords (extracted
from src/config/countries.ts + UCDP-relevant additions). Used by
attachNewsContext for richer headline matching via getSearchTermsForRegion
which combines country-codes + entity graph + keyword aliases.
14/57 predictions now have news corroboration (limited by headline
coverage, not matching quality: only 8 headlines currently available).
* feat(forecast): read 300 headlines from news digest instead of 8
Read news:digest:v1:full:en (300 headlines across 16 categories) instead
of just news:insights:v1 topStories (8 headlines). Fallback to topStories
if digest is unavailable.
Result: news corroboration jumped from 25% to 64% (38/59 predictions).
* fix(forecast): handle parenthetical country names in headline matching
Strip suffixes like '(Zaire)', '(Burma)', '(Soviet Union)' from UCDP
region names before matching against country-codes.json. Also use
includes() for reverse name lookup to catch partial matches.
Corroboration: 64% -> 69% (41/59). Remaining 18 unmatched are countries
with no current English-language news coverage.
* fix(forecast): cache validated LLM output, add digest test, log cache errors
Fresh-eyes audit fixes:
- Combined LLM cache now stores only validated items (was caching raw
unvalidated output, serving potentially invalid scenarios on cache hit)
- redisSet logs warnings on failure (was silently swallowing all errors)
- Added digest-based test for attachNewsContext (primary path was untested)
- Fixed test arity: attachNewsContext(preds, news, digest) with 3 params
* fix(forecast): remove dead confidenceFromSources, reduce warm-ping timeout
- P2: Remove confidenceFromSources (dead code, computeConfidence overwrites
all initial confidence values). Inline the formula in original detectors.
- P3: Reduce warm-ping timeout from 30s to 15s (non-critical step)
- P3: Add trial status comment on forecast panel config
* fix(forecast): resolve ISO codes to country names, fix market detector, safe pre-push
P1 fixes from code review:
- CII ISO codes (IL, IR) now resolved to full country names (Israel, Iran)
via country-codes.json. Prevents substring false positives (IL matching
Chile) in event correlation. Uses word-boundary regex for matching.
- Market detector CII-to-theater mapping now uses entity graph traversal
instead of broken theater-name substring matching. Iran correctly maps
to Middle East theater via graph links.
- Pre-push hook no longer runs destructive git checkout on proto freshness
failure. Reports mismatch and exits without modifying worktree.
1 line
34 KiB
JSON
1 line
34 KiB
JSON
{"components":{"schemas":{"AirportDelayAlert":{"description":"AirportDelayAlert represents a flight delay advisory at an airport.\n Sourced from FAA and Eurocontrol.","properties":{"avgDelayMinutes":{"description":"Average delay in minutes.","format":"int32","type":"integer"},"cancelledFlights":{"description":"Number of cancelled flights.","format":"int32","type":"integer"},"city":{"description":"City where the airport is located.","type":"string"},"country":{"description":"Country code (ISO 3166-1 alpha-2).","type":"string"},"delayType":{"description":"FlightDelayType represents the type of flight delay.","enum":["FLIGHT_DELAY_TYPE_UNSPECIFIED","FLIGHT_DELAY_TYPE_GROUND_STOP","FLIGHT_DELAY_TYPE_GROUND_DELAY","FLIGHT_DELAY_TYPE_DEPARTURE_DELAY","FLIGHT_DELAY_TYPE_ARRIVAL_DELAY","FLIGHT_DELAY_TYPE_GENERAL","FLIGHT_DELAY_TYPE_CLOSURE"],"type":"string"},"delayedFlightsPct":{"description":"Percentage of delayed flights.","format":"double","type":"number"},"iata":{"description":"IATA airport code (e.g., \"JFK\").","type":"string"},"icao":{"description":"ICAO airport code (e.g., \"KJFK\").","type":"string"},"id":{"description":"Unique alert identifier.","minLength":1,"type":"string"},"location":{"$ref":"#/components/schemas/GeoCoordinates"},"name":{"description":"Airport name.","type":"string"},"reason":{"description":"Human-readable reason for delays.","type":"string"},"region":{"description":"AirportRegion represents the geographic region of an airport.","enum":["AIRPORT_REGION_UNSPECIFIED","AIRPORT_REGION_AMERICAS","AIRPORT_REGION_EUROPE","AIRPORT_REGION_APAC","AIRPORT_REGION_MENA","AIRPORT_REGION_AFRICA"],"type":"string"},"severity":{"description":"FlightDelaySeverity represents the severity of flight delays at an airport.\n Maps to TS union: 'normal' | 'minor' | 'moderate' | 'major' | 'severe'.","enum":["FLIGHT_DELAY_SEVERITY_UNSPECIFIED","FLIGHT_DELAY_SEVERITY_NORMAL","FLIGHT_DELAY_SEVERITY_MINOR","FLIGHT_DELAY_SEVERITY_MODERATE","FLIGHT_DELAY_SEVERITY_MAJOR","FLIGHT_DELAY_SEVERITY_SEVERE"],"type":"string"},"source":{"description":"FlightDelaySource represents the source of delay data.","enum":["FLIGHT_DELAY_SOURCE_UNSPECIFIED","FLIGHT_DELAY_SOURCE_FAA","FLIGHT_DELAY_SOURCE_EUROCONTROL","FLIGHT_DELAY_SOURCE_COMPUTED","FLIGHT_DELAY_SOURCE_AVIATIONSTACK","FLIGHT_DELAY_SOURCE_NOTAM"],"type":"string"},"totalFlights":{"description":"Total flights scheduled.","format":"int32","type":"integer"},"updatedAt":{"description":"Last data update time, as Unix epoch milliseconds.. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"}},"required":["id"],"type":"object"},"AirportOpsSummary":{"description":"AirportOpsSummary contains operational health metrics for a single airport.","properties":{"avgDelayMinutes":{"description":"Average delay in minutes across delayed flights.","format":"int32","type":"integer"},"cancellationRate":{"description":"Cancellation rate as a percentage (0-100).","format":"double","type":"number"},"closureStatus":{"description":"Whether the airport is currently closed.","type":"boolean"},"delayPct":{"description":"Percentage of flights currently delayed (0-100).","format":"double","type":"number"},"iata":{"description":"IATA airport code.","type":"string"},"icao":{"description":"ICAO airport code.","type":"string"},"name":{"description":"Airport name.","type":"string"},"notamFlags":{"items":{"description":"Active NOTAM summary flags (e.g., \"RWY 06/24 CLSD\", \"LOW VIS OPS\").","type":"string"},"type":"array"},"severity":{"description":"FlightDelaySeverity represents the severity of flight delays at an airport.\n Maps to TS union: 'normal' | 'minor' | 'moderate' | 'major' | 'severe'.","enum":["FLIGHT_DELAY_SEVERITY_UNSPECIFIED","FLIGHT_DELAY_SEVERITY_NORMAL","FLIGHT_DELAY_SEVERITY_MINOR","FLIGHT_DELAY_SEVERITY_MODERATE","FLIGHT_DELAY_SEVERITY_MAJOR","FLIGHT_DELAY_SEVERITY_SEVERE"],"type":"string"},"source":{"description":"Data source identifier.","type":"string"},"timezone":{"description":"IANA timezone (e.g., \"Europe/Istanbul\").","type":"string"},"topDelayReasons":{"items":{"description":"Top reasons for delays.","type":"string"},"type":"array"},"totalFlights":{"description":"Total flights in the observation window.","format":"int32","type":"integer"},"updatedAt":{"description":"Last update time as Unix epoch milliseconds.. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"}},"type":"object"},"AirportRef":{"description":"AirportRef is a lightweight reference to an airport.","properties":{"iata":{"description":"IATA airport code (e.g., \"IST\").","type":"string"},"icao":{"description":"ICAO airport code (e.g., \"LTFM\").","type":"string"},"name":{"description":"Airport name (e.g., \"Istanbul Airport\").","type":"string"},"timezone":{"description":"IANA timezone (e.g., \"Europe/Istanbul\").","type":"string"}},"type":"object"},"AviationNewsItem":{"description":"AviationNewsItem represents a single aviation news article or press release.","properties":{"id":{"description":"Unique item identifier (hash of URL).","type":"string"},"imageUrl":{"description":"Article image URL (if available).","type":"string"},"matchedEntities":{"items":{"description":"Entities matched from the query (airport codes, airline names).","type":"string"},"type":"array"},"publishedAt":{"description":"Publication time as Unix epoch milliseconds.. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"snippet":{"description":"Short text snippet or description.","type":"string"},"sourceName":{"description":"Name of the news source (e.g., \"FlightGlobal\").","type":"string"},"title":{"description":"Article title.","type":"string"},"url":{"description":"Article URL.","type":"string"}},"type":"object"},"Carrier":{"description":"Carrier represents an airline or aircraft operator.","properties":{"iataCode":{"description":"IATA two-letter airline code (e.g., \"TK\").","type":"string"},"icaoCode":{"description":"ICAO three-letter airline code (e.g., \"THY\").","type":"string"},"name":{"description":"Full airline name (e.g., \"Turkish Airlines\").","type":"string"}},"type":"object"},"CarrierOpsSummary":{"description":"CarrierOpsSummary contains delay and cancellation metrics for a carrier at an airport.","properties":{"airport":{"description":"Airport IATA code this summary applies to.","type":"string"},"avgDelayMinutes":{"description":"Average delay in minutes across delayed flights.","format":"int32","type":"integer"},"cancellationRate":{"description":"Cancellation rate (0-100).","format":"double","type":"number"},"cancelledCount":{"description":"Number of cancelled flights.","format":"int32","type":"integer"},"carrier":{"$ref":"#/components/schemas/Carrier"},"delayPct":{"description":"Delay percentage (0-100).","format":"double","type":"number"},"delayedCount":{"description":"Number of delayed flights.","format":"int32","type":"integer"},"totalFlights":{"description":"Total flights observed.","format":"int32","type":"integer"},"updatedAt":{"description":"Last update time as Unix epoch milliseconds.. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"}},"type":"object"},"Error":{"description":"Error is returned when a handler encounters an error. It contains a simple error message that the developer can customize.","properties":{"message":{"description":"Error message (e.g., 'user not found', 'database connection failed')","type":"string"}},"type":"object"},"FieldViolation":{"description":"FieldViolation describes a single validation error for a specific field.","properties":{"description":{"description":"Human-readable description of the validation violation (e.g., 'must be a valid email address', 'required field missing')","type":"string"},"field":{"description":"The field path that failed validation (e.g., 'user.email' for nested fields). For header validation, this will be the header name (e.g., 'X-API-Key')","type":"string"}},"required":["field","description"],"type":"object"},"FlightInstance":{"description":"FlightInstance represents a specific occurrence of a flight on a given date.","properties":{"actualArrival":{"description":"Actual arrival time as Unix epoch milliseconds (UTC).. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"actualDeparture":{"description":"Actual departure time as Unix epoch milliseconds (UTC).. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"aircraftIcao24":{"description":"ICAO 24-bit transponder address of the aircraft (hex, e.g., \"4b1805\").","type":"string"},"aircraftType":{"description":"Aircraft type designator (e.g., \"B738\").","type":"string"},"cancelled":{"description":"Whether the flight is cancelled.","type":"boolean"},"codeshareFlightNumbers":{"items":{"description":"Codeshare flight numbers marketed under this operating flight.","type":"string"},"type":"array"},"date":{"description":"Departure date in ISO 8601 format (e.g., \"2026-03-05\").","type":"string"},"delayMinutes":{"description":"Delay in minutes (0 if on time, negative if early).","format":"int32","type":"integer"},"destination":{"$ref":"#/components/schemas/AirportRef"},"diverted":{"description":"Whether the flight has been diverted.","type":"boolean"},"estimatedArrival":{"description":"Estimated arrival time as Unix epoch milliseconds (UTC).. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"estimatedDeparture":{"description":"Estimated departure time as Unix epoch milliseconds (UTC).. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"flightNumber":{"description":"IATA flight number (e.g., \"TK1952\").","type":"string"},"gate":{"description":"Departure gate (if available).","type":"string"},"operatingCarrier":{"$ref":"#/components/schemas/Carrier"},"origin":{"$ref":"#/components/schemas/AirportRef"},"scheduledArrival":{"description":"Scheduled arrival time as Unix epoch milliseconds (UTC).. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"scheduledDeparture":{"description":"Scheduled departure time as Unix epoch milliseconds (UTC).. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"source":{"description":"Data source provider name.","type":"string"},"status":{"description":"FlightInstanceStatus represents the operational status of a flight occurrence.","enum":["FLIGHT_INSTANCE_STATUS_UNSPECIFIED","FLIGHT_INSTANCE_STATUS_SCHEDULED","FLIGHT_INSTANCE_STATUS_BOARDING","FLIGHT_INSTANCE_STATUS_DEPARTED","FLIGHT_INSTANCE_STATUS_AIRBORNE","FLIGHT_INSTANCE_STATUS_LANDED","FLIGHT_INSTANCE_STATUS_ARRIVED","FLIGHT_INSTANCE_STATUS_CANCELLED","FLIGHT_INSTANCE_STATUS_DIVERTED","FLIGHT_INSTANCE_STATUS_UNKNOWN"],"type":"string"},"terminal":{"description":"Departure terminal (if available).","type":"string"},"updatedAt":{"description":"Last update time as Unix epoch milliseconds.. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"}},"type":"object"},"GeoCoordinates":{"description":"GeoCoordinates represents a geographic location using WGS84 coordinates.","properties":{"latitude":{"description":"Latitude in decimal degrees (-90 to 90).","format":"double","maximum":90,"minimum":-90,"type":"number"},"longitude":{"description":"Longitude in decimal degrees (-180 to 180).","format":"double","maximum":180,"minimum":-180,"type":"number"}},"type":"object"},"GetAirportOpsSummaryRequest":{"description":"GetAirportOpsSummaryRequest specifies which airports to summarize.","properties":{"airports":{"items":{"description":"IATA airport codes to query (e.g., [\"IST\", \"ESB\", \"LHR\"]).","maxItems":20,"minItems":1,"type":"string"},"maxItems":20,"minItems":1,"type":"array"}},"type":"object"},"GetAirportOpsSummaryResponse":{"description":"GetAirportOpsSummaryResponse contains operational summaries for requested airports.","properties":{"cacheHit":{"description":"Whether the response was served from cache.","type":"boolean"},"summaries":{"items":{"$ref":"#/components/schemas/AirportOpsSummary"},"type":"array"}},"type":"object"},"GetCarrierOpsRequest":{"description":"GetCarrierOpsRequest specifies parameters for carrier operations metrics.","properties":{"airports":{"items":{"description":"IATA airport codes to aggregate carrier metrics from.","maxItems":20,"minItems":1,"type":"string"},"maxItems":20,"minItems":1,"type":"array"},"minFlights":{"description":"Minimum number of flights required to include a carrier (default: 1).","format":"int32","minimum":0,"type":"integer"}},"type":"object"},"GetCarrierOpsResponse":{"description":"GetCarrierOpsResponse contains carrier operations metrics.","properties":{"carriers":{"items":{"$ref":"#/components/schemas/CarrierOpsSummary"},"type":"array"},"source":{"description":"Data source identifier.","type":"string"},"updatedAt":{"description":"Last update time as Unix epoch milliseconds.. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"}},"type":"object"},"GetFlightStatusRequest":{"description":"GetFlightStatusRequest specifies a flight to look up.","properties":{"date":{"description":"Departure date in ISO 8601 format (e.g., \"2026-03-05\").","maxLength":10,"minLength":10,"type":"string"},"flightNumber":{"description":"IATA flight number (e.g., \"TK1952\").","maxLength":10,"minLength":3,"type":"string"},"origin":{"description":"Optional origin airport IATA code to disambiguate.","type":"string"}},"required":["flightNumber","date"],"type":"object"},"GetFlightStatusResponse":{"description":"GetFlightStatusResponse contains flight status results.","properties":{"cacheHit":{"description":"Whether the response was served from cache.","type":"boolean"},"flights":{"items":{"$ref":"#/components/schemas/FlightInstance"},"type":"array"},"source":{"description":"Data source identifier.","type":"string"}},"type":"object"},"ListAirportDelaysRequest":{"description":"ListAirportDelaysRequest specifies filters for retrieving airport delay alerts.","properties":{"cursor":{"description":"Cursor for next page.","type":"string"},"minSeverity":{"description":"FlightDelaySeverity represents the severity of flight delays at an airport.\n Maps to TS union: 'normal' | 'minor' | 'moderate' | 'major' | 'severe'.","enum":["FLIGHT_DELAY_SEVERITY_UNSPECIFIED","FLIGHT_DELAY_SEVERITY_NORMAL","FLIGHT_DELAY_SEVERITY_MINOR","FLIGHT_DELAY_SEVERITY_MODERATE","FLIGHT_DELAY_SEVERITY_MAJOR","FLIGHT_DELAY_SEVERITY_SEVERE"],"type":"string"},"pageSize":{"description":"Maximum items per page (1-100).","format":"int32","type":"integer"},"region":{"description":"AirportRegion represents the geographic region of an airport.","enum":["AIRPORT_REGION_UNSPECIFIED","AIRPORT_REGION_AMERICAS","AIRPORT_REGION_EUROPE","AIRPORT_REGION_APAC","AIRPORT_REGION_MENA","AIRPORT_REGION_AFRICA"],"type":"string"}},"type":"object"},"ListAirportDelaysResponse":{"description":"ListAirportDelaysResponse contains airport delay alerts matching the request.","properties":{"alerts":{"items":{"$ref":"#/components/schemas/AirportDelayAlert"},"type":"array"},"pagination":{"$ref":"#/components/schemas/PaginationResponse"}},"type":"object"},"ListAirportFlightsRequest":{"description":"ListAirportFlightsRequest specifies parameters for retrieving recent flights at an airport.","properties":{"airport":{"description":"IATA airport code (e.g., \"IST\").","maxLength":4,"minLength":3,"type":"string"},"direction":{"description":"FlightDirection specifies whether to retrieve departures, arrivals, or both.","enum":["FLIGHT_DIRECTION_UNSPECIFIED","FLIGHT_DIRECTION_DEPARTURE","FLIGHT_DIRECTION_ARRIVAL","FLIGHT_DIRECTION_BOTH"],"type":"string"},"limit":{"description":"Maximum number of flights to return (1-100).","format":"int32","maximum":100,"minimum":1,"type":"integer"}},"required":["airport"],"type":"object"},"ListAirportFlightsResponse":{"description":"ListAirportFlightsResponse contains recent flights at an airport.","properties":{"flights":{"items":{"$ref":"#/components/schemas/FlightInstance"},"type":"array"},"source":{"description":"Data source identifier.","type":"string"},"totalAvailable":{"description":"Total number of flights available from the provider.","format":"int32","type":"integer"},"updatedAt":{"description":"Last update time as Unix epoch milliseconds.. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"}},"type":"object"},"ListAviationNewsRequest":{"description":"ListAviationNewsRequest specifies filters for aviation news retrieval.","properties":{"entities":{"items":{"description":"Entities to filter by (airline names, airport codes, route strings).","maxItems":10,"minItems":1,"type":"string"},"maxItems":10,"minItems":1,"type":"array"},"maxItems":{"description":"Maximum number of news items to return (1-50).","format":"int32","maximum":50,"minimum":1,"type":"integer"},"windowHours":{"description":"Time window in hours to look back (1-168).","format":"int32","maximum":168,"minimum":1,"type":"integer"}},"type":"object"},"ListAviationNewsResponse":{"description":"ListAviationNewsResponse contains filtered aviation news items.","properties":{"items":{"items":{"$ref":"#/components/schemas/AviationNewsItem"},"type":"array"},"source":{"description":"Data source identifier.","type":"string"},"updatedAt":{"description":"Last update time as Unix epoch milliseconds.. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"}},"type":"object"},"PaginationResponse":{"description":"PaginationResponse contains pagination metadata returned alongside list results.","properties":{"nextCursor":{"description":"Cursor for fetching the next page. Empty string indicates no more pages.","type":"string"},"totalCount":{"description":"Total count of items matching the query, if known. Zero if the total is unknown.","format":"int32","type":"integer"}},"type":"object"},"PositionSample":{"description":"PositionSample represents a single aircraft position observation.","properties":{"altitudeM":{"description":"Barometric altitude in metres.","format":"double","type":"number"},"callsign":{"description":"ATC callsign (e.g., \"THY7CX\").","type":"string"},"groundSpeedKts":{"description":"Ground speed in knots.","format":"double","type":"number"},"icao24":{"description":"ICAO 24-bit transponder address (hex, e.g., \"4b1805\").","type":"string"},"lat":{"description":"Latitude in decimal degrees.","format":"double","type":"number"},"lon":{"description":"Longitude in decimal degrees.","format":"double","type":"number"},"observedAt":{"description":"Observation time as Unix epoch milliseconds.. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"onGround":{"description":"Whether the aircraft is on the ground.","type":"boolean"},"source":{"description":"PositionSource identifies the provider of aircraft position data.","enum":["POSITION_SOURCE_UNSPECIFIED","POSITION_SOURCE_OPENSKY","POSITION_SOURCE_WINGBITS","POSITION_SOURCE_SIMULATED"],"type":"string"},"trackDeg":{"description":"True track over ground in degrees (0 = North, clockwise).","format":"double","type":"number"},"verticalRate":{"description":"Vertical rate in metres per second (positive = climbing).","format":"double","type":"number"}},"type":"object"},"PriceQuote":{"description":"PriceQuote represents a single flight price offer from a provider.","properties":{"bookingUrl":{"description":"Booking URL or deep-link (if available).","type":"string"},"cabin":{"description":"CabinClass represents the travel class for a flight ticket.","enum":["CABIN_CLASS_UNSPECIFIED","CABIN_CLASS_ECONOMY","CABIN_CLASS_PREMIUM_ECONOMY","CABIN_CLASS_BUSINESS","CABIN_CLASS_FIRST"],"type":"string"},"carrier":{"$ref":"#/components/schemas/Carrier"},"checkoutRef":{"description":"Reference used during the checkout process (for follow-up actions).","type":"string"},"currency":{"description":"ISO 4217 currency code (e.g., \"EUR\", \"USD\", \"TRY\").","type":"string"},"departureDate":{"description":"Outbound departure date (ISO 8601).","type":"string"},"destination":{"description":"Destination airport IATA code.","type":"string"},"durationMinutes":{"description":"Total travel duration in minutes.","format":"int32","type":"integer"},"expiresAt":{"description":"Time when this quote expires, as Unix epoch milliseconds.. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"id":{"description":"Unique quote identifier.","type":"string"},"isIndicative":{"description":"Whether the price is indicative rather than bookable.","type":"boolean"},"observedAt":{"description":"Time when this quote was observed, as Unix epoch milliseconds.. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"},"origin":{"description":"Origin airport IATA code.","type":"string"},"priceAmount":{"description":"Total price amount.","format":"double","type":"number"},"provider":{"description":"Provider name (e.g., \"amadeus\", \"demo\").","type":"string"},"returnDate":{"description":"Return date (ISO 8601), empty for one-way.","type":"string"},"stops":{"description":"Number of stops (0 = nonstop).","format":"int32","type":"integer"}},"type":"object"},"SearchFlightPricesRequest":{"description":"SearchFlightPricesRequest specifies parameters for a flight price search.","properties":{"adults":{"description":"Number of adult passengers (1-9).","format":"int32","maximum":9,"minimum":1,"type":"integer"},"cabin":{"description":"CabinClass represents the travel class for a flight ticket.","enum":["CABIN_CLASS_UNSPECIFIED","CABIN_CLASS_ECONOMY","CABIN_CLASS_PREMIUM_ECONOMY","CABIN_CLASS_BUSINESS","CABIN_CLASS_FIRST"],"type":"string"},"currency":{"description":"ISO 4217 currency code for prices (e.g., \"usd\", \"eur\", \"try\").","type":"string"},"departureDate":{"description":"Outbound departure date (ISO 8601).","maxLength":10,"minLength":10,"type":"string"},"destination":{"description":"Destination airport IATA code.","maxLength":4,"minLength":3,"type":"string"},"market":{"description":"Market/locale code (e.g., \"us\", \"tr\").","type":"string"},"maxResults":{"description":"Maximum number of quotes to return (1-50).","format":"int32","maximum":50,"minimum":1,"type":"integer"},"nonstopOnly":{"description":"Whether to restrict to nonstop flights only.","type":"boolean"},"origin":{"description":"Origin airport IATA code.","maxLength":4,"minLength":3,"type":"string"},"returnDate":{"description":"Return date (ISO 8601), empty for one-way.","type":"string"}},"required":["origin","destination","departureDate"],"type":"object"},"SearchFlightPricesResponse":{"description":"SearchFlightPricesResponse contains flight price offers.","properties":{"isDemoMode":{"description":"Whether results are from demo/simulated mode.","type":"boolean"},"isIndicative":{"description":"Whether returned prices are indicative (subject to change).","type":"boolean"},"provider":{"description":"Provider name (e.g., \"amadeus\", \"demo\").","type":"string"},"quotes":{"items":{"$ref":"#/components/schemas/PriceQuote"},"type":"array"},"updatedAt":{"description":"Last update time as Unix epoch milliseconds.. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"}},"type":"object"},"TrackAircraftRequest":{"description":"TrackAircraftRequest specifies an aircraft to track.","properties":{"callsign":{"description":"ATC callsign (e.g., \"THY7CX\").","type":"string"},"icao24":{"description":"ICAO 24-bit transponder address (hex, e.g., \"4b1805\").","type":"string"},"neLat":{"description":"Optional bounding box north-east latitude.","format":"double","type":"number"},"neLon":{"description":"Optional bounding box north-east longitude.","format":"double","type":"number"},"swLat":{"description":"Optional bounding box south-west latitude.","format":"double","type":"number"},"swLon":{"description":"Optional bounding box south-west longitude.","format":"double","type":"number"}},"type":"object"},"TrackAircraftResponse":{"description":"TrackAircraftResponse contains aircraft position observations.","properties":{"positions":{"items":{"$ref":"#/components/schemas/PositionSample"},"type":"array"},"source":{"description":"Data source identifier.","type":"string"},"updatedAt":{"description":"Last update time as Unix epoch milliseconds.. Warning: Values \u003e 2^53 may lose precision in JavaScript","format":"int64","type":"integer"}},"type":"object"},"ValidationError":{"description":"ValidationError is returned when request validation fails. It contains a list of field violations describing what went wrong.","properties":{"violations":{"description":"List of validation violations","items":{"$ref":"#/components/schemas/FieldViolation"},"type":"array"}},"required":["violations"],"type":"object"}}},"info":{"title":"AviationService API","version":"1.0.0"},"openapi":"3.1.0","paths":{"/api/aviation/v1/get-airport-ops-summary":{"get":{"description":"GetAirportOpsSummary returns operational health metrics for watched airports.","operationId":"GetAirportOpsSummary","parameters":[{"description":"IATA airport codes to query (e.g., [\"IST\", \"ESB\", \"LHR\"]).","in":"query","name":"airports","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetAirportOpsSummaryResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Validation error"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error response"}},"summary":"GetAirportOpsSummary","tags":["AviationService"]}},"/api/aviation/v1/get-carrier-ops":{"get":{"description":"GetCarrierOps returns delay and cancellation metrics grouped by carrier.","operationId":"GetCarrierOps","parameters":[{"description":"IATA airport codes to aggregate carrier metrics from.","in":"query","name":"airports","required":false,"schema":{"type":"string"}},{"description":"Minimum number of flights required to include a carrier (default: 1).","in":"query","name":"min_flights","required":false,"schema":{"format":"int32","type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetCarrierOpsResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Validation error"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error response"}},"summary":"GetCarrierOps","tags":["AviationService"]}},"/api/aviation/v1/get-flight-status":{"get":{"description":"GetFlightStatus looks up the current status of a specific flight.","operationId":"GetFlightStatus","parameters":[{"description":"IATA flight number (e.g., \"TK1952\").","in":"query","name":"flight_number","required":false,"schema":{"type":"string"}},{"description":"Departure date in ISO 8601 format (e.g., \"2026-03-05\").","in":"query","name":"date","required":false,"schema":{"type":"string"}},{"description":"Optional origin airport IATA code to disambiguate.","in":"query","name":"origin","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetFlightStatusResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Validation error"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error response"}},"summary":"GetFlightStatus","tags":["AviationService"]}},"/api/aviation/v1/list-airport-delays":{"get":{"description":"ListAirportDelays retrieves current airport delay alerts.","operationId":"ListAirportDelays","parameters":[{"description":"Maximum items per page (1-100).","in":"query","name":"page_size","required":false,"schema":{"format":"int32","type":"integer"}},{"description":"Cursor for next page.","in":"query","name":"cursor","required":false,"schema":{"type":"string"}},{"description":"Optional region filter.","in":"query","name":"region","required":false,"schema":{"type":"string"}},{"description":"Optional minimum severity filter.","in":"query","name":"min_severity","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListAirportDelaysResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Validation error"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error response"}},"summary":"ListAirportDelays","tags":["AviationService"]}},"/api/aviation/v1/list-airport-flights":{"get":{"description":"ListAirportFlights retrieves recent flights at a specific airport.","operationId":"ListAirportFlights","parameters":[{"description":"IATA airport code (e.g., \"IST\").","in":"query","name":"airport","required":false,"schema":{"type":"string"}},{"description":"Direction filter.","in":"query","name":"direction","required":false,"schema":{"type":"string"}},{"description":"Maximum number of flights to return (1-100).","in":"query","name":"limit","required":false,"schema":{"format":"int32","type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListAirportFlightsResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Validation error"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error response"}},"summary":"ListAirportFlights","tags":["AviationService"]}},"/api/aviation/v1/list-aviation-news":{"get":{"description":"ListAviationNews retrieves filtered aviation news articles.","operationId":"ListAviationNews","parameters":[{"description":"Entities to filter by (airline names, airport codes, route strings).","in":"query","name":"entities","required":false,"schema":{"type":"string"}},{"description":"Time window in hours to look back (1-168).","in":"query","name":"window_hours","required":false,"schema":{"format":"int32","type":"integer"}},{"description":"Maximum number of news items to return (1-50).","in":"query","name":"max_items","required":false,"schema":{"format":"int32","type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListAviationNewsResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Validation error"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error response"}},"summary":"ListAviationNews","tags":["AviationService"]}},"/api/aviation/v1/search-flight-prices":{"get":{"description":"SearchFlightPrices searches for flight price offers on a route.","operationId":"SearchFlightPrices","parameters":[{"description":"Origin airport IATA code.","in":"query","name":"origin","required":false,"schema":{"type":"string"}},{"description":"Destination airport IATA code.","in":"query","name":"destination","required":false,"schema":{"type":"string"}},{"description":"Outbound departure date (ISO 8601).","in":"query","name":"departure_date","required":false,"schema":{"type":"string"}},{"description":"Return date (ISO 8601), empty for one-way.","in":"query","name":"return_date","required":false,"schema":{"type":"string"}},{"description":"Number of adult passengers (1-9).","in":"query","name":"adults","required":false,"schema":{"format":"int32","type":"integer"}},{"description":"Desired cabin class.","in":"query","name":"cabin","required":false,"schema":{"type":"string"}},{"description":"Whether to restrict to nonstop flights only.","in":"query","name":"nonstop_only","required":false,"schema":{"type":"boolean"}},{"description":"Maximum number of quotes to return (1-50).","in":"query","name":"max_results","required":false,"schema":{"format":"int32","type":"integer"}},{"description":"ISO 4217 currency code for prices (e.g., \"usd\", \"eur\", \"try\").","in":"query","name":"currency","required":false,"schema":{"type":"string"}},{"description":"Market/locale code (e.g., \"us\", \"tr\").","in":"query","name":"market","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchFlightPricesResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Validation error"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error response"}},"summary":"SearchFlightPrices","tags":["AviationService"]}},"/api/aviation/v1/track-aircraft":{"get":{"description":"TrackAircraft retrieves recent position data for an aircraft.","operationId":"TrackAircraft","parameters":[{"description":"ICAO 24-bit transponder address (hex, e.g., \"4b1805\").","in":"query","name":"icao24","required":false,"schema":{"type":"string"}},{"description":"ATC callsign (e.g., \"THY7CX\").","in":"query","name":"callsign","required":false,"schema":{"type":"string"}},{"description":"Optional bounding box south-west latitude.","in":"query","name":"sw_lat","required":false,"schema":{"format":"double","type":"number"}},{"description":"Optional bounding box south-west longitude.","in":"query","name":"sw_lon","required":false,"schema":{"format":"double","type":"number"}},{"description":"Optional bounding box north-east latitude.","in":"query","name":"ne_lat","required":false,"schema":{"format":"double","type":"number"}},{"description":"Optional bounding box north-east longitude.","in":"query","name":"ne_lon","required":false,"schema":{"format":"double","type":"number"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackAircraftResponse"}}},"description":"Successful response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}},"description":"Validation error"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error response"}},"summary":"TrackAircraft","tags":["AviationService"]}}}} |