@kquika-inc/s-system 1.0.8 → 2.0.1

package/README.md

@@ -26,6 +26,10 @@ record before acting on it.
 | `live_feed` | Observed from the live provider feed. |
 | `database` | Observed on an earlier read and persisted. |
 
+Every record this API returns is an observation. `live_feed` is the current
+reading from the provider; `database` is the same reading persisted from an
+earlier call, so it may lag the feed. Neither is an estimate.
+
 Fields are left null where the source carries no value. A null
 `delay_minutes` means no time was reported.
 
@@ -35,6 +39,20 @@ Fields are left null where the source carries no value. A null
 are in the response. Flights that reported no time are excluded from that
 denominator, so other ratios can be derived from the same payload.
 
+`on_time` counts departures within `on_time_threshold_minutes`, which is
+returned on the response and defaults to 15. Read it rather than assuming it.
+
+`on_time_percentage` is null when the figure cannot be measured, and
+`ontime_unavailable_reason` says why. Three cases:
+
+- Nothing was measured.
+- Coverage was too thin to describe the operation.
+- The sample was censored: every flight carrying a time was late, and none
+  departed early or on schedule. This happens when the upstream feed publishes
+  a delay only when there is one, so "on time" and "unknown" collapse into the
+  same absence. A rate over only late flights reads near zero whatever the
+  real punctuality is, so no rate is returned at all.
+
 `gate_conflicts` is keyed on airport and gate together, so gate labels are
 only compared within a single station.
 
@@ -49,23 +67,23 @@ only compared within a single station.
 | **Route analytics**: performance grouped by route | Professional |
 | **Refresh** the live feed on demand | Professional |
 | **Airport overview**: movements, delay, stand utilization | Standard |
-| **LiDAR heatmap**: passenger density by zone | Professional |
+| **Passenger heatmap**: density by zone, measured or modeled | Professional |
 | **Congestion**: current level plus 1h and 3h forecast | Professional |
+| **Disruption lists**: the flights most at risk, with causes and actions | IOCC Briefing |
+| **Aircraft rotations**: how a delay travels through the day | Disruption Prediction or IOCC Briefing |
+| **Passengers, crew and fuel**: counts, duty margins and tankering | The matching capability, or IOCC Briefing |
+| **Stations and airfield congestion** | Airport Heatmap or IOCC Briefing |
 
 Passenger intelligence is delivered through the application and through
 scheduled data delivery. Contact your account manager about direct access for
 your integration.
 
-## Plans
-
-Your rate limit follows your plan. Read it from the response headers instead
-of hardcoding it.
+## Plans and rate limits
 
-| Plan | Rate limit | Burst |
-|---|---|---|
-| Standard | 100 requests/minute | 200/minute |
-| Professional | 500 requests/minute | 1,000/minute |
-| Enterprise | 2,000 requests/minute | 5,000/minute |
+Each key carries an hourly request limit, set with your plan. Every response
+reports it in `X-RateLimit-Limit`, with what remains in `X-RateLimit-Remaining`
+and in the `quota` block, so read it there instead of hardcoding a number. A
+refused request returns 429 with `Retry-After`, in seconds.
 
 API access starts at Standard. Starter covers the dashboard and basic
 passenger insights without programmatic access.
@@ -88,7 +106,7 @@ client.setConfig({
   headers: { 'X-API-Key': process.env.S_SYSTEM_API_KEY! },
 });
 
-const { data, error } = await listFlights({ query: { origin: 'SDQ', limit: 25 } });
+const { data, error } = await listFlights({ query: { origin: 'JFK', limit: 25 } });
 
 if (error || !data?.success) {
   console.error(data?.message ?? error);
@@ -105,16 +123,21 @@ if (error || !data?.success) {
 ## `data_confidence`
 
 ```ts
-for (const flight of data.data) {
-  if (flight.data_confidence === 'live_feed') schedule(flight);
+for (const flight of data.data.flights) {
+  // Both values are observations, so both are safe to schedule against.
+  // Branch on freshness only when it matters to you: `database` may lag the
+  // live feed by a sync interval.
+  if (flight.data_confidence === 'live_feed') scheduleNow(flight);
+  else queueForRefresh(flight);
 }
 ```
 
 `live_feed` is the current reading from the provider. `database` is the same
-reading persisted from an earlier call, so it may lag the feed.
+reading persisted from an earlier call, so it may lag the feed by up to one
+sync interval.
 
-TypeScript narrows that union, so a typo fails to compile instead of
-silently never matching.
+TypeScript narrows the union, so a typo fails to compile instead of silently
+never matching.
 
 ## Nulls
 
@@ -143,21 +166,27 @@ import {
   getAirportOverview, getAirportHeatmap, getAirportCongestion,
 } from '@kquika-inc/s-system';
 
-const heat = await getAirportHeatmap({ path: { airport_code: 'SDQ' } });
+const heat = await getAirportHeatmap({ path: { airport_code: 'JFK' } });
+const h = heat.data!.data!;
 
-if (!heat.data?.data?.lidar_available) {
-  // This station has no LiDAR coverage, so points is empty.
-  console.log('No LiDAR here.');
-} else {
-  for (const p of heat.data.data.points!) {
-    console.log(p.zone, p.intensity, p.wait_time_minutes);
-  }
+console.log(h.data_source);             // measured, or modelled
+for (const p of h.points!) {
+  console.log(p.zone, p.intensity, p.wait_time_minutes);
 }
 ```
 
 `avg_wait_minutes` covers queueing zones only: security, check-in,
 immigration and customs. Gates and lounges are out of scope.
 
+Points come from the sensor or survey readings an airport shares, and are
+modeled where it shares none; `lidar_available` keeps its name for
+compatibility and is true when readings are available. Check `data_source` on
+the heatmap response before acting on occupancy or wait times. `measured` means a sensor, gate read or throughput count is behind the
+figure. `modelled` means it is derived from terminal layout and time of day
+with no sensor behind it, in which case two calls seconds apart can return
+different values with no underlying event. Do not diff them to infer movement.
+
+
 Heatmap and congestion require Professional. Overview is Standard.
 
 ## Flight metrics and route analytics
@@ -179,6 +208,25 @@ flight as on time.
 time, which means the check could not run. Null and 0 carry different
 meanings here.
 
+## Operations
+
+The disruption lists, rotations, passengers, crew, fuel and stations your
+operations team works from.
+
+```ts
+import { getDisruptions, getRotation } from '@kquika-inc/s-system';
+
+const risk = await getDisruptions({ query: { kind: 'daily' } });
+for (const flight of risk.data!.data!.items as any[]) {
+  console.log(flight.flight_number, flight.probability, flight.action);
+}
+
+const day = await getRotation({ query: { tail: 'N123XX', seed: 45 } });   // a 45 minute what-if
+```
+
+Each needs the capability shown in **What you can call** and a key carrying its
+permission. Dates are `YYYY-MM-DD` and default to today; times are UTC.
+
 ## Errors
 
 | Code | Meaning |
@@ -187,6 +235,9 @@ meanings here.
 | `forbidden` | The key lacks the permission for this endpoint. |
 | `plan_required` | Your plan does not cover this endpoint. |
 | `rate_limited` | Back off for `retry_after_seconds`. |
+| `not_found` | No such flight or station among yours. |
+| `bad_request` | A parameter is missing or malformed; `message` says which. |
+| `server_error` | Ours to fix. Retry once, then contact support. |
 
 `error` is a stable code and safe to branch on. `message` is for a human and
 its wording may change.
@@ -204,16 +255,22 @@ Every schema is exported.
 ```ts
 import type {
   Flight,
-  DisruptionPrediction,
-  Exposure,
-  Meta,
+  MetricsResponse,
+  HeatmapResponse,
+  ErrorResponse,
 } from '@kquika-inc/s-system';
 
-function isActionable(p: DisruptionPrediction): boolean {
-  return p.risk_level === 'critical' || p.risk_level === 'elevated';
+function isActionable(flight: Flight): boolean {
+  // delay_minutes must be null-checked first. `?? 0` here would treat an
+  // unreported flight as departing exactly on schedule.
+  return flight.delay_minutes !== null && flight.delay_minutes > 15;
 }
 ```
 
+Disruption lists are on the Operations endpoints. Passenger-rights exposure is
+delivered through the application and through scheduled data delivery; talk to
+your account manager about direct access.
+
 ## Support
 
 An API key, a plan change, or a capability you need that your plan does not

package/dist/sdk.gen.d.ts

@@ -1,5 +1,5 @@
 import type { Options as ClientOptions, TDataShape, Client } from '@hey-api/client-fetch';
-import type { ListFlightsData, GetFlightData, GetFlightMetricsData, GetRouteAnalyticsData, SearchFlightsData, RefreshFlightsData, GetAirportOverviewData, GetAirportHeatmapData, GetAirportCongestionData, GetUsageData } from './types.gen';
+import type { ListFlightsData, GetFlightData, GetFlightMetricsData, GetRouteAnalyticsData, SearchFlightsData, RefreshFlightsData, GetAirportOverviewData, GetAirportHeatmapData, GetAirportCongestionData, GetUsageData, GetDisruptionsData, GetRotationData, GetAirfieldCongestionData, GetPassengersData, GetCrewData, GetFuelPlanData, ListStationsData, GetStationData, GetCapabilitiesData } from './types.gen';
 export type Options<TData extends TDataShape = TDataShape, ThrowOnError extends boolean = boolean> = ClientOptions<TData, ThrowOnError> & {
     /**
      * You can provide a client instance returned by `createClient()` instead of
@@ -19,8 +19,9 @@ export type Options<TData extends TDataShape = TDataShape, ThrowOnError extends
  *
  * **Requires Standard.**
  *
- * Each flight carries a `data_confidence` value. Confirm it before using the
- * flight for operational planning.
+ * Every record returned is an observation. Records generated to fill a gap in the live
+ * feed are excluded rather than labeled, so no provenance check is required before using
+ * a flight for operational planning. `excluded_generated` reports how many were removed.
  */
 export declare const listFlights: <ThrowOnError extends boolean = false>(options?: Options<ListFlightsData, ThrowOnError>) => import("@hey-api/client-fetch").RequestResult<import("./types.gen").FlightListResponse, import("./types.gen").ErrorResponse, ThrowOnError>;
 /**
@@ -77,13 +78,15 @@ export declare const refreshFlights: <ThrowOnError extends boolean = false>(opti
  */
 export declare const getAirportOverview: <ThrowOnError extends boolean = false>(options: Options<GetAirportOverviewData, ThrowOnError>) => import("@hey-api/client-fetch").RequestResult<import("./types.gen").AirportOverviewResponse, import("./types.gen").ErrorResponse, ThrowOnError>;
 /**
- * LiDAR heatmap
- * Passenger density by zone, from LiDAR.
+ * Passenger heatmap
+ * Passenger density by zone.
  *
  * **Requires Professional.**
  *
- * Points are returned for stations with LiDAR coverage. Check
- * `lidar_available` on the response before reading `points`.
+ * Measured from the sensor or survey readings an airport shares, and modeled from
+ * terminal layout and time of day where it shares none. Read `data_source` before
+ * acting on occupancy or wait times. `lidar_available` keeps its name for
+ * compatibility and is true when readings are available.
  */
 export declare const getAirportHeatmap: <ThrowOnError extends boolean = false>(options: Options<GetAirportHeatmapData, ThrowOnError>) => import("@hey-api/client-fetch").RequestResult<import("./types.gen").HeatmapResponse, import("./types.gen").ErrorResponse, ThrowOnError>;
 /**
@@ -105,3 +108,66 @@ export declare const getAirportCongestion: <ThrowOnError extends boolean = false
  * Every response already carries the same position in its `quota` block and in the `X-Quota-*` headers, so polling this endpoint to watch consumption wastes the allowance it reports. Call it when you want the breakdown by endpoint, which headers cannot carry.
  */
 export declare const getUsage: <ThrowOnError extends boolean = false>(options?: Options<GetUsageData, ThrowOnError>) => import("@hey-api/client-fetch").RequestResult<import("./types.gen").UsageResponse, import("./types.gen").ErrorResponse, ThrowOnError>;
+/**
+ * Flights most at risk
+ * The daily or Next hours list: each flight’s risk, likely delay, causes, suggested action and rebooking options.
+ *
+ * **Requires IOCC Briefing.** Key permission `iocc:read`.
+ */
+export declare const getDisruptions: <ThrowOnError extends boolean = false>(options?: Options<GetDisruptionsData, ThrowOnError>) => import("@hey-api/client-fetch").RequestResult<import("./types.gen").OpsResponse, import("./types.gen").ErrorResponse, ThrowOnError>;
+/**
+ * An aircraft’s day
+ * How a delay travels through the aircraft’s rotation, leg by leg. Give a flight or a tail number; `seed` adds a starting delay as a what-if.
+ *
+ * **Requires Disruption Prediction or IOCC Briefing.** Key permission `disruptions:read`.
+ */
+export declare const getRotation: <ThrowOnError extends boolean = false>(options?: Options<GetRotationData, ThrowOnError>) => import("@hey-api/client-fetch").RequestResult<import("./types.gen").OpsResponse, import("./types.gen").ErrorResponse, ThrowOnError>;
+/**
+ * Airfield congestion
+ * Airfield congestion per hour from measured taxi times, in UTC.
+ *
+ * **Requires Airport Heatmap or IOCC Briefing.** Key permission `heatmaps:read`.
+ */
+export declare const getAirfieldCongestion: <ThrowOnError extends boolean = false>(options: Options<GetAirfieldCongestionData, ThrowOnError>) => import("@hey-api/client-fetch").RequestResult<import("./types.gen").OpsResponse, import("./types.gen").ErrorResponse, ThrowOnError>;
+/**
+ * Passengers per flight
+ * Booked, connecting and infant passengers per flight. Counts only; never a name.
+ *
+ * **Requires Passenger Analytics or IOCC Briefing.** Key permission `passengers:read`.
+ */
+export declare const getPassengers: <ThrowOnError extends boolean = false>(options?: Options<GetPassengersData, ThrowOnError>) => import("@hey-api/client-fetch").RequestResult<import("./types.gen").OpsResponse, import("./types.gen").ErrorResponse, ThrowOnError>;
+/**
+ * Crew duty margins
+ * Duty margin per leg, and reserve crews needed per base. No individual is named.
+ *
+ * **Requires Crew Reserve or IOCC Briefing.** Key permission `crew:read`.
+ */
+export declare const getCrew: <ThrowOnError extends boolean = false>(options?: Options<GetCrewData, ThrowOnError>) => import("@hey-api/client-fetch").RequestResult<import("./types.gen").OpsResponse, import("./types.gen").ErrorResponse, ThrowOnError>;
+/**
+ * Fuel tankering plan
+ * Whether carrying extra fuel pays on each leg, with the saving and its CO2 cost.
+ *
+ * **Requires Fuel Tankering or IOCC Briefing.** Key permission `fuel:read`.
+ */
+export declare const getFuelPlan: <ThrowOnError extends boolean = false>(options?: Options<GetFuelPlanData, ThrowOnError>) => import("@hey-api/client-fetch").RequestResult<import("./types.gen").OpsResponse, import("./types.gen").ErrorResponse, ThrowOnError>;
+/**
+ * Stations
+ * The airline’s stations, busiest first, kept current from its own flights.
+ *
+ * **Requires Airport Heatmap or IOCC Briefing.** Key permission `airports:read`.
+ */
+export declare const listStations: <ThrowOnError extends boolean = false>(options?: Options<ListStationsData, ThrowOnError>) => import("@hey-api/client-fetch").RequestResult<import("./types.gen").OpsResponse, import("./types.gen").ErrorResponse, ThrowOnError>;
+/**
+ * One station
+ * A station’s departures at risk in the coming hours, and its congestion.
+ *
+ * **Requires Airport Heatmap or IOCC Briefing.** Key permission `airports:read`.
+ */
+export declare const getStation: <ThrowOnError extends boolean = false>(options: Options<GetStationData, ThrowOnError>) => import("@hey-api/client-fetch").RequestResult<import("./types.gen").OpsResponse, import("./types.gen").ErrorResponse, ThrowOnError>;
+/**
+ * Capabilities
+ * Every data type this API serves, and whether your airline has it.
+ *
+ * **Available on every plan.**
+ */
+export declare const getCapabilities: <ThrowOnError extends boolean = false>(options?: Options<GetCapabilitiesData, ThrowOnError>) => import("@hey-api/client-fetch").RequestResult<import("./types.gen").OpsResponse, import("./types.gen").ErrorResponse, ThrowOnError>;

package/dist/sdk.gen.js

@@ -6,8 +6,9 @@ import { client as _heyApiClient } from './client.gen';
  *
  * **Requires Standard.**
  *
- * Each flight carries a `data_confidence` value. Confirm it before using the
- * flight for operational planning.
+ * Every record returned is an observation. Records generated to fill a gap in the live
+ * feed are excluded rather than labeled, so no provenance check is required before using
+ * a flight for operational planning. `excluded_generated` reports how many were removed.
  */
 export const listFlights = (options) => {
     return (options?.client ?? _heyApiClient).get({
@@ -141,13 +142,15 @@ export const getAirportOverview = (options) => {
     });
 };
 /**
- * LiDAR heatmap
- * Passenger density by zone, from LiDAR.
+ * Passenger heatmap
+ * Passenger density by zone.
  *
  * **Requires Professional.**
  *
- * Points are returned for stations with LiDAR coverage. Check
- * `lidar_available` on the response before reading `points`.
+ * Measured from the sensor or survey readings an airport shares, and modeled from
+ * terminal layout and time of day where it shares none. Read `data_source` before
+ * acting on occupancy or wait times. `lidar_available` keeps its name for
+ * compatibility and is true when readings are available.
  */
 export const getAirportHeatmap = (options) => {
     return (options.client ?? _heyApiClient).get({
@@ -202,3 +205,165 @@ export const getUsage = (options) => {
         ...options
     });
 };
+/**
+ * Flights most at risk
+ * The daily or Next hours list: each flight’s risk, likely delay, causes, suggested action and rebooking options.
+ *
+ * **Requires IOCC Briefing.** Key permission `iocc:read`.
+ */
+export const getDisruptions = (options) => {
+    return (options?.client ?? _heyApiClient).get({
+        security: [
+            {
+                name: 'X-API-Key',
+                type: 'apiKey'
+            }
+        ],
+        url: '/api/v1/ops/disruptions',
+        ...options
+    });
+};
+/**
+ * An aircraft’s day
+ * How a delay travels through the aircraft’s rotation, leg by leg. Give a flight or a tail number; `seed` adds a starting delay as a what-if.
+ *
+ * **Requires Disruption Prediction or IOCC Briefing.** Key permission `disruptions:read`.
+ */
+export const getRotation = (options) => {
+    return (options?.client ?? _heyApiClient).get({
+        security: [
+            {
+                name: 'X-API-Key',
+                type: 'apiKey'
+            }
+        ],
+        url: '/api/v1/ops/rotation',
+        ...options
+    });
+};
+/**
+ * Airfield congestion
+ * Airfield congestion per hour from measured taxi times, in UTC.
+ *
+ * **Requires Airport Heatmap or IOCC Briefing.** Key permission `heatmaps:read`.
+ */
+export const getAirfieldCongestion = (options) => {
+    return (options.client ?? _heyApiClient).get({
+        security: [
+            {
+                name: 'X-API-Key',
+                type: 'apiKey'
+            }
+        ],
+        url: '/api/v1/ops/congestion',
+        ...options
+    });
+};
+/**
+ * Passengers per flight
+ * Booked, connecting and infant passengers per flight. Counts only; never a name.
+ *
+ * **Requires Passenger Analytics or IOCC Briefing.** Key permission `passengers:read`.
+ */
+export const getPassengers = (options) => {
+    return (options?.client ?? _heyApiClient).get({
+        security: [
+            {
+                name: 'X-API-Key',
+                type: 'apiKey'
+            }
+        ],
+        url: '/api/v1/ops/passengers',
+        ...options
+    });
+};
+/**
+ * Crew duty margins
+ * Duty margin per leg, and reserve crews needed per base. No individual is named.
+ *
+ * **Requires Crew Reserve or IOCC Briefing.** Key permission `crew:read`.
+ */
+export const getCrew = (options) => {
+    return (options?.client ?? _heyApiClient).get({
+        security: [
+            {
+                name: 'X-API-Key',
+                type: 'apiKey'
+            }
+        ],
+        url: '/api/v1/ops/crew',
+        ...options
+    });
+};
+/**
+ * Fuel tankering plan
+ * Whether carrying extra fuel pays on each leg, with the saving and its CO2 cost.
+ *
+ * **Requires Fuel Tankering or IOCC Briefing.** Key permission `fuel:read`.
+ */
+export const getFuelPlan = (options) => {
+    return (options?.client ?? _heyApiClient).get({
+        security: [
+            {
+                name: 'X-API-Key',
+                type: 'apiKey'
+            }
+        ],
+        url: '/api/v1/ops/fuel',
+        ...options
+    });
+};
+/**
+ * Stations
+ * The airline’s stations, busiest first, kept current from its own flights.
+ *
+ * **Requires Airport Heatmap or IOCC Briefing.** Key permission `airports:read`.
+ */
+export const listStations = (options) => {
+    return (options?.client ?? _heyApiClient).get({
+        security: [
+            {
+                name: 'X-API-Key',
+                type: 'apiKey'
+            }
+        ],
+        url: '/api/v1/ops/airports',
+        ...options
+    });
+};
+/**
+ * One station
+ * A station’s departures at risk in the coming hours, and its congestion.
+ *
+ * **Requires Airport Heatmap or IOCC Briefing.** Key permission `airports:read`.
+ */
+export const getStation = (options) => {
+    return (options.client ?? _heyApiClient).get({
+        security: [
+            {
+                name: 'X-API-Key',
+                type: 'apiKey'
+            }
+        ],
+        url: '/api/v1/ops/airports/{code}',
+        ...options
+    });
+};
+/**
+ * Capabilities
+ * Every data type this API serves, and whether your airline has it.
+ *
+ * **Available on every plan.**
+ */
+export const getCapabilities = (options) => {
+    return (options?.client ?? _heyApiClient).get({
+        security: [
+            {
+                name: 'X-API-Key',
+                type: 'apiKey'
+            }
+        ],
+        url: '/api/v1/ops/capabilities',
+        ...options
+    });
+};

package/dist/types.gen.d.ts

@@ -59,11 +59,11 @@ export type Flight = {
      */
     status?: 'scheduled' | 'active' | 'landed' | 'delayed' | 'cancelled' | 'diverted' | 'unknown';
     /**
-     * Provenance of this record. `live_feed` and `database` are observed records.
-     * `generated` is synthetic sample data and is not suitable for operational
-     * planning.
+     * Provenance of this record. Both values are observations: `live_feed` is the current reading from the provider, `database` is the same reading persisted from an earlier call and may lag the feed by up to one sync interval.
+     *
+     * There is no value for generated data. Records produced to fill a gap in the feed are excluded from this API entirely rather than labelled, so every record you receive is an observation and no client-side check is required before acting on one.
      */
-    data_confidence: 'live_feed' | 'database' | 'generated';
+    data_confidence: 'live_feed' | 'database';
 };
 export type FlightListResponse = Envelope & {
     data?: {
@@ -72,11 +72,13 @@ export type FlightListResponse = Envelope & {
         /**
          * Provenance of the returned records. `generated` appears only when it was requested explicitly, since the default excludes it.
          */
-        source?: 'live_feed' | 'database' | 'generated' | 'mixed';
+        source?: 'live_feed' | 'database' | 'mixed';
         /**
-         * Records matching the other filters but removed by `confidence`. With no filter this counts the generated rows the default excluded, so a non-zero value here on a default query means the feed is carrying synthetic data.
+         * Records matching your filters that were produced to fill a gap in the live feed, and therefore excluded. Always excluded; this is the count, not a choice.
+         *
+         * A non-zero value means the feed was thin enough for the platform to generate rows, so a short result can be told apart from a short schedule. It is a signal about the feed, not about your query.
          */
-        excluded_by_confidence?: number | null;
+        excluded_generated?: number | null;
     };
 };
 export type FlightResponse = Envelope & {
@@ -93,13 +95,29 @@ export type MetricsResponse = Envelope & {
          */
         measured_flights?: number;
         /**
-         * Departures within 15 minutes of schedule.
+         * Departures within `on_time_threshold_minutes` of schedule, which defaults to 15. Read the threshold from the response rather than assuming it.
          */
         on_time?: number;
         /**
-         * `on_time` divided by `measured_flights`. Null when `measured_flights` is 0.
+         * `on_time` divided by `measured_flights`.
+         *
+         * Null in three cases, which `ontime_unavailable_reason` distinguishes: nothing was measured; coverage was too thin for the figure to describe the operation; or the sample was censored, meaning every flight carrying a time was late and none departed early or on schedule. The third is the one to watch, because a rate computed over only late flights reads near zero whatever the real punctuality is.
+         *
+         * Null is not zero. Treating it as zero reports perfect lateness on a day nothing was measured.
          */
         on_time_percentage?: number | null;
+        /**
+         * False when the sample cannot support an on-time rate. `on_time_percentage` is null whenever this is false.
+         */
+        ontime_measurable?: boolean;
+        /**
+         * Plain sentence naming why the rate could not be computed. Null when it could.
+         */
+        ontime_unavailable_reason?: string | null;
+        /**
+         * Minutes of delay still counted as on time. Configurable per deployment, so read it rather than assuming 15.
+         */
+        on_time_threshold_minutes?: number;
         /**
          * Mean delay across delayed departures only. The denominator excludes on time
          * departures.
@@ -153,10 +171,23 @@ export type HeatmapResponse = Envelope & {
     data?: {
         airport_code?: string;
         /**
-         * Whether LiDAR coverage exists at this station. `points` is empty when false,
-         * which carries no information about occupancy.
+         * True when the airport shares sensor or survey readings, which the points then
+         * come from. The name is kept for compatibility. Read `data_source` for the same
+         * answer as `measured` or `modelled`.
          */
         lidar_available?: boolean;
+        /**
+         * How the figures in `points` were produced. `measured` means a sensor, gate read or throughput count. `modelled` means derived from terminal layout and time of day, with no sensor behind it. Two calls seconds apart can return different modelled values with no underlying event, so do not diff them to infer movement.
+         */
+        data_source?: 'measured' | 'modelled';
+        /**
+         * False when the figures are modelled. Present as a boolean as well as in `data_source` so a client can branch without string comparison.
+         */
+        is_measured?: boolean;
+        /**
+         * Plain sentence describing how these figures were produced, safe to display.
+         */
+        provenance_note?: string | null;
         points?: Array<{
             zone?: string;
             zone_type?: string;
@@ -215,21 +246,28 @@ export type UsageResponse = Envelope & {
             endpoint?: string;
             calls?: number;
         }>;
+        /**
+         * The hourly limit spread evenly across a minute. Keys are limited per hour; see `rate_limit_per_hour`.
+         */
         rate_limit_per_minute?: number;
+        /**
+         * The requests this key may make per hour. Null when the call was not made with a key.
+         */
+        rate_limit_per_hour?: number | null;
+    };
+};
+export type OpsResponse = Envelope & {
+    /**
+     * The figures the endpoint describes. Dates are YYYY-MM-DD and times are UTC.
+     */
+    data?: {
+        [key: string]: unknown;
     };
 };
 /**
  * IATA code, three letters. Case insensitive.
  */
 export type AirportCode = string;
-/**
- * Restrict to records of this provenance. Repeat the parameter for more than one value.
- *
- * **Defaults to `live_feed` and `database`.** Generated records must be asked for by name. A generated row filled a gap in the feed and carries a real carrier code on a route that carrier may not fly, so it does not reach a planner who did not ask for it.
- *
- * `count` reflects what was returned. `excluded_by_confidence` reports what the filter removed, so a small result can be told apart from a thin feed.
- */
-export type Confidence = Array<'live_feed' | 'database' | 'generated'>;
 export type ListFlightsData = {
     body?: never;
     path?: never;
@@ -244,14 +282,6 @@ export type ListFlightsData = {
          */
         date?: string;
         limit?: number;
-        /**
-         * Restrict to records of this provenance. Repeat the parameter for more than one value.
-         *
-         * **Defaults to `live_feed` and `database`.** Generated records must be asked for by name. A generated row filled a gap in the feed and carries a real carrier code on a route that carrier may not fly, so it does not reach a planner who did not ask for it.
-         *
-         * `count` reflects what was returned. `excluded_by_confidence` reports what the filter removed, so a small result can be told apart from a thin feed.
-         */
-        confidence?: Array<'live_feed' | 'database' | 'generated'>;
     };
     url: '/api/v1/flights';
 };
@@ -365,14 +395,6 @@ export type SearchFlightsData = {
          */
         q: string;
         limit?: number;
-        /**
-         * Restrict to records of this provenance. Repeat the parameter for more than one value.
-         *
-         * **Defaults to `live_feed` and `database`.** Generated records must be asked for by name. A generated row filled a gap in the feed and carries a real carrier code on a route that carrier may not fly, so it does not reach a planner who did not ask for it.
-         *
-         * `count` reflects what was returned. `excluded_by_confidence` reports what the filter removed, so a small result can be told apart from a thin feed.
-         */
-        confidence?: Array<'live_feed' | 'database' | 'generated'>;
     };
     url: '/api/v1/flights/search';
 };
@@ -529,6 +551,270 @@ export type GetUsageResponses = {
     200: UsageResponse;
 };
 export type GetUsageResponse = GetUsageResponses[keyof GetUsageResponses];
+export type GetDisruptionsData = {
+    body?: never;
+    path?: never;
+    query?: {
+        /**
+         * daily: the day-ahead list. sameday: Next hours.
+         */
+        kind?: 'daily' | 'sameday';
+        /**
+         * Operating day. Defaults to today.
+         */
+        date?: string;
+        /**
+         * One departure station, IATA.
+         */
+        station?: string;
+    };
+    url: '/api/v1/ops/disruptions';
+};
+export type GetDisruptionsErrors = {
+    /**
+     * Missing or invalid API key.
+     */
+    401: ErrorResponse;
+};
+export type GetDisruptionsError = GetDisruptionsErrors[keyof GetDisruptionsErrors];
+export type GetDisruptionsResponses = {
+    /**
+     * Flights most at risk.
+     */
+    200: OpsResponse;
+};
+export type GetDisruptionsResponse = GetDisruptionsResponses[keyof GetDisruptionsResponses];
+export type GetRotationData = {
+    body?: never;
+    path?: never;
+    query?: {
+        /**
+         * Flight number.
+         */
+        flight?: string;
+        /**
+         * Tail number, instead of a flight.
+         */
+        tail?: string;
+        /**
+         * Operating day. Defaults to today.
+         */
+        date?: string;
+        /**
+         * Departure station, when the flight number repeats.
+         */
+        origin?: string;
+        /**
+         * Starting delay in minutes.
+         */
+        seed?: number;
+    };
+    url: '/api/v1/ops/rotation';
+};
+export type GetRotationErrors = {
+    /**
+     * Missing or invalid API key.
+     */
+    401: ErrorResponse;
+};
+export type GetRotationError = GetRotationErrors[keyof GetRotationErrors];
+export type GetRotationResponses = {
+    /**
+     * An aircraft’s day.
+     */
+    200: OpsResponse;
+};
+export type GetRotationResponse = GetRotationResponses[keyof GetRotationResponses];
+export type GetAirfieldCongestionData = {
+    body?: never;
+    path?: never;
+    query: {
+        /**
+         * Station, IATA.
+         */
+        airport: string;
+        /**
+         * Hours ahead, up to 48.
+         */
+        hours?: number;
+        /**
+         * Start hour, YYYY-MM-DDTHH:MM, UTC. Defaults to now.
+         */
+        start?: string;
+    };
+    url: '/api/v1/ops/congestion';
+};
+export type GetAirfieldCongestionErrors = {
+    /**
+     * Missing or invalid API key.
+     */
+    401: ErrorResponse;
+};
+export type GetAirfieldCongestionError = GetAirfieldCongestionErrors[keyof GetAirfieldCongestionErrors];
+export type GetAirfieldCongestionResponses = {
+    /**
+     * Airfield congestion.
+     */
+    200: OpsResponse;
+};
+export type GetAirfieldCongestionResponse = GetAirfieldCongestionResponses[keyof GetAirfieldCongestionResponses];
+export type GetPassengersData = {
+    body?: never;
+    path?: never;
+    query?: {
+        /**
+         * Operating day. Defaults to today.
+         */
+        date?: string;
+        /**
+         * One flight.
+         */
+        flight?: string;
+    };
+    url: '/api/v1/ops/passengers';
+};
+export type GetPassengersErrors = {
+    /**
+     * Missing or invalid API key.
+     */
+    401: ErrorResponse;
+};
+export type GetPassengersError = GetPassengersErrors[keyof GetPassengersErrors];
+export type GetPassengersResponses = {
+    /**
+     * Passengers per flight.
+     */
+    200: OpsResponse;
+};
+export type GetPassengersResponse = GetPassengersResponses[keyof GetPassengersResponses];
+export type GetCrewData = {
+    body?: never;
+    path?: never;
+    query?: {
+        /**
+         * Operating day. Defaults to today.
+         */
+        date?: string;
+        /**
+         * One base.
+         */
+        station?: string;
+    };
+    url: '/api/v1/ops/crew';
+};
+export type GetCrewErrors = {
+    /**
+     * Missing or invalid API key.
+     */
+    401: ErrorResponse;
+};
+export type GetCrewError = GetCrewErrors[keyof GetCrewErrors];
+export type GetCrewResponses = {
+    /**
+     * Crew duty margins.
+     */
+    200: OpsResponse;
+};
+export type GetCrewResponse = GetCrewResponses[keyof GetCrewResponses];
+export type GetFuelPlanData = {
+    body?: never;
+    path?: never;
+    query?: {
+        /**
+         * Operating day. Defaults to today.
+         */
+        date?: string;
+        /**
+         * One flight.
+         */
+        flight?: string;
+    };
+    url: '/api/v1/ops/fuel';
+};
+export type GetFuelPlanErrors = {
+    /**
+     * Missing or invalid API key.
+     */
+    401: ErrorResponse;
+};
+export type GetFuelPlanError = GetFuelPlanErrors[keyof GetFuelPlanErrors];
+export type GetFuelPlanResponses = {
+    /**
+     * Fuel tankering plan.
+     */
+    200: OpsResponse;
+};
+export type GetFuelPlanResponse = GetFuelPlanResponses[keyof GetFuelPlanResponses];
+export type ListStationsData = {
+    body?: never;
+    path?: never;
+    query?: never;
+    url: '/api/v1/ops/airports';
+};
+export type ListStationsErrors = {
+    /**
+     * Missing or invalid API key.
+     */
+    401: ErrorResponse;
+};
+export type ListStationsError = ListStationsErrors[keyof ListStationsErrors];
+export type ListStationsResponses = {
+    /**
+     * Stations.
+     */
+    200: OpsResponse;
+};
+export type ListStationsResponse = ListStationsResponses[keyof ListStationsResponses];
+export type GetStationData = {
+    body?: never;
+    path: {
+        /**
+         * Station, IATA.
+         */
+        code: string;
+    };
+    query?: {
+        /**
+         * Hours ahead.
+         */
+        hours?: number;
+    };
+    url: '/api/v1/ops/airports/{code}';
+};
+export type GetStationErrors = {
+    /**
+     * Missing or invalid API key.
+     */
+    401: ErrorResponse;
+};
+export type GetStationError = GetStationErrors[keyof GetStationErrors];
+export type GetStationResponses = {
+    /**
+     * One station.
+     */
+    200: OpsResponse;
+};
+export type GetStationResponse = GetStationResponses[keyof GetStationResponses];
+export type GetCapabilitiesData = {
+    body?: never;
+    path?: never;
+    query?: never;
+    url: '/api/v1/ops/capabilities';
+};
+export type GetCapabilitiesErrors = {
+    /**
+     * Missing or invalid API key.
+     */
+    401: ErrorResponse;
+};
+export type GetCapabilitiesError = GetCapabilitiesErrors[keyof GetCapabilitiesErrors];
+export type GetCapabilitiesResponses = {
+    /**
+     * Capabilities.
+     */
+    200: OpsResponse;
+};
+export type GetCapabilitiesResponse = GetCapabilitiesResponses[keyof GetCapabilitiesResponses];
 export type ClientOptions = {
     baseUrl: 'https://www.s-system.cloud' | (string & {});
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kquika-inc/s-system",
-  "version": "1.0.8",
+  "version": "2.0.1",
   "description": "Predict flight disruption, price the passenger-rights exposure it carries, and rebook before it costs you.",
   "author": { "name": "Kquika, Inc.", "email": "support@kquika.com" },
   "homepage": "https://www.s-system.cloud/document",