@kquika-inc/s-system 1.0.7 → 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

@@ -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 } from './types.gen';
+import type { ListFlightsData, GetFlightData, GetFlightMetricsData, GetRouteAnalyticsData, SearchFlightsData, RefreshFlightsData, GetAirportOverviewData, GetAirportHeatmapData, GetAirportCongestionData, GetUsageData } 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 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>;
 /**
@@ -96,3 +97,12 @@ export declare const getAirportHeatmap: <ThrowOnError extends boolean = false>(o
  * immigration and customs.
  */
 export declare const getAirportCongestion: <ThrowOnError extends boolean = false>(options: Options<GetAirportCongestionData, ThrowOnError>) => import("@hey-api/client-fetch").RequestResult<import("./types.gen").CongestionResponse, import("./types.gen").ErrorResponse, ThrowOnError>;
+/**
+ * Usage against your allowance
+ * Calls made this period, the allowance, and what remains.
+ *
+ * **Requires Standard.**
+ *
+ * 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>;

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({
@@ -182,3 +183,23 @@ export const getAirportCongestion = (options) => {
         ...options
     });
 };
+/**
+ * Usage against your allowance
+ * Calls made this period, the allowance, and what remains.
+ *
+ * **Requires Standard.**
+ *
+ * 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 const getUsage = (options) => {
+    return (options?.client ?? _heyApiClient).get({
+        security: [
+            {
+                name: 'X-API-Key',
+                type: 'apiKey'
+            }
+        ],
+        url: '/api/v1/usage',
+        ...options
+    });
+};

package/dist/types.gen.d.ts

@@ -16,6 +16,20 @@ export type Envelope = {
      * contract; branch on the HTTP status or on `error`.
      */
     message: string;
+    /**
+     * Your consumption after this call, on every response. A client can slow down before it is throttled rather than after: a quota you discover only by being refused is not a quota. Mirrored in the X-Quota-Remaining and X-RateLimit-Remaining headers, so a caller that does not parse the body still sees it.
+     */
+    quota?: {
+        /**
+         * Null on plans metered by rate rather than volume.
+         */
+        calls_remaining?: number | null;
+        percent_used?: number | null;
+        /**
+         * Requests left in the current minute.
+         */
+        rate_limit_remaining?: number | null;
+    };
 };
 export type Flight = {
     flight_number: string;
@@ -45,21 +59,26 @@ 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?: {
         flights?: Array<Flight>;
         count?: number;
         /**
-         * Provenance of the returned records. `generated` indicates synthetic sample
-         * data.
+         * Provenance of the returned records. `generated` appears only when it was requested explicitly, since the default excludes it.
+         */
+        source?: 'live_feed' | 'database' | 'mixed';
+        /**
+         * 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.
          */
-        source?: 'live_feed' | 'database' | 'generated' | 'mixed';
+        excluded_generated?: number | null;
     };
 };
 export type FlightResponse = Envelope & {
@@ -76,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.
@@ -138,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;
@@ -179,6 +228,28 @@ export type ErrorResponse = Envelope & {
      */
     retry_after_seconds?: number | null;
 };
+export type UsageResponse = Envelope & {
+    data?: {
+        period_start?: string;
+        period_end?: string;
+        plan?: 'Standard' | 'Professional' | 'Enterprise';
+        calls_made?: number;
+        /**
+         * Monthly allowance. Null on plans metered by rate rather than volume, which is not the same as unlimited: the per-minute limit still applies.
+         */
+        calls_included?: number | null;
+        calls_remaining?: number | null;
+        percent_used?: number | null;
+        /**
+         * Where the calls went. The reason to call this endpoint.
+         */
+        by_endpoint?: Array<{
+            endpoint?: string;
+            calls?: number;
+        }>;
+        rate_limit_per_minute?: number;
+    };
+};
 /**
  * IATA code, three letters. Case insensitive.
  */
@@ -446,6 +517,26 @@ export type GetAirportCongestionResponses = {
     200: CongestionResponse;
 };
 export type GetAirportCongestionResponse = GetAirportCongestionResponses[keyof GetAirportCongestionResponses];
+export type GetUsageData = {
+    body?: never;
+    path?: never;
+    query?: never;
+    url: '/api/v1/usage';
+};
+export type GetUsageErrors = {
+    /**
+     * Missing or invalid API key.
+     */
+    401: ErrorResponse;
+};
+export type GetUsageError = GetUsageErrors[keyof GetUsageErrors];
+export type GetUsageResponses = {
+    /**
+     * Usage for the current period.
+     */
+    200: UsageResponse;
+};
+export type GetUsageResponse = GetUsageResponses[keyof GetUsageResponses];
 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.7",
+  "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",