@kquika-inc/s-system 1.0.8 → 2.0.0

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.
 
@@ -106,15 +124,20 @@ if (error || !data?.success) {
 
 ```ts
 for (const flight of data.data) {
-  if (flight.data_confidence === 'live_feed') schedule(flight);
+  // 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
 
@@ -158,6 +181,13 @@ if (!heat.data?.data?.lidar_available) {
 `avg_wait_minutes` covers queueing zones only: security, check-in,
 immigration and customs. Gates and lounges are out of scope.
 
+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
@@ -204,16 +234,23 @@ 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 prediction and passenger-rights exposure are not on the public API
+and have no exported types. They are 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

@@ -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 labelled, 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>;
 /**

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 labelled, 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({

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.
@@ -155,8 +173,22 @@ export type HeatmapResponse = Envelope & {
         /**
          * Whether LiDAR coverage exists at this station. `points` is empty when false,
          * which carries no information about occupancy.
+         *
+         * **Read `data_source` before acting on any figure here.** Where it is `modelled`, occupancy and wait times are derived from terminal layout and time of day rather than measured from sensors, regardless of what this flag says.
          */
         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;
@@ -222,14 +254,6 @@ export type UsageResponse = Envelope & {
  * 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 +268,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 +381,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';
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kquika-inc/s-system",
-  "version": "1.0.8",
+  "version": "2.0.0",
   "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",