@skyvexsoftware/stratos-sdk 0.12.0 → 0.13.1

package/dist/shared-types/simulator.d.ts

@@ -1,5 +1,6 @@
 /**
- * Shared flight simulation types for use by plugins.
+ * @page Simulator Data
+ * Standardized flight data, phase detection, and trend types shared across all simulators.
  *
  * These are the canonical definitions of flight data structures.
  * Comprehensive flight data variables for VA platform compatibility.
@@ -207,184 +208,6 @@ export type FlightPhasePayload = {
 };
 /** Simulator connection status */
 export type SimulatorStatus = "disconnected" | "connecting" | "connected" | "error";
-/** Event categories for filtering/display */
-export declare enum EventCategory {
-    SYSTEM = "system",
-    PHASE = "phase",
-    CONTROLS = "controls",
-    ENGINE = "engine",
-    WARNING = "warning",
-    POSITION = "position",
-    COMMENT = "comment"
-}
-/** Flight log event entry */
-export type FlightLogEvent = {
-    eventId: string;
-    eventTimestamp: string;
-    eventElapsedTime: number;
-    eventCondition: string;
-    category: EventCategory;
-    message: string;
-    data?: Record<string, unknown>;
-};
-/** History report entry (position sample) */
-export type HistoryReportEntry = {
-    timestamp: number;
-    elapsedTime: number;
-    latitude: number;
-    longitude: number;
-    altitude: number;
-    altitudeAgl: number;
-    heading: number;
-    groundSpeed: number;
-    indicatedAirspeed: number;
-    verticalSpeed: number;
-    pitch: number;
-    bank: number;
-    phase: FlightPhase;
-    planeOnground: boolean;
-    landingRate: number | null;
-};
-/** Payload for the flight:event Socket.io event */
-export type FlightEventPayload = {
-    event: FlightLogEvent;
-    timestamp: number;
-};
-/** Capture point for landing analysis */
-export type CapturePoint = {
-    timestamp: number;
-    altitude: number;
-    altitudeAgl: number;
-    verticalSpeed: number;
-    groundSpeed: number;
-    indicatedAirspeed: number;
-    latitude: number;
-    longitude: number;
-    pitch: number;
-    bank: number;
-    gForce: number;
-    heading: number;
-    glideslopeDeviation: number | null;
-    localizerDeviation: number | null;
-    flapsControl: number;
-    windDirection: number;
-    windSpeed: number;
-    totalFuelLbs: number;
-    /** Snapshot of data.flapsHandleIndex at the capture moment, null if the sim doesn't provide it. */
-    flapsHandleIndex: number | null;
-};
-/** Bounce data — captured when aircraft becomes airborne after touchdown */
-export type BounceData = {
-    bounceNumber: number;
-    timestamp: number;
-    maxAltitudeAgl: number;
-    touchdownVerticalSpeed: number;
-    touchdownGForce: number;
-    durationMs: number;
-};
-/** Snapshot of aircraft state at the 50 ft stabilized-approach gate */
-export type GateCapture = {
-    /** Actual AGL at capture, may be a few ft above/below the nominal 50 ft */
-    altitudeAgl: number;
-    indicatedAirspeed: number;
-    verticalSpeed: number;
-    bank: number;
-    pitch: number;
-    groundSpeed: number;
-    timestamp: number;
-};
-/** Complete landing analysis result */
-export type LandingAnalysis = {
-    landingRateFpm: number;
-    simulatorVsAtTouchdown: number;
-    touchdownTimestamp: number;
-    touchdownLatitude: number;
-    touchdownLongitude: number;
-    touchdownHeading: number;
-    touchdownGroundSpeed: number;
-    /** Indicated airspeed at touchdown (knots) — sourced from the touchdown CapturePoint. */
-    touchdownIas: number;
-    /** Flaps handle index at touchdown, null if the sim doesn't provide one. */
-    touchdownFlapsIndex: number | null;
-    touchdownPitch: number;
-    touchdownBank: number;
-    /**
-     * Scored touchdown vertical-load G. The peak of a framerate-independent,
-     * time-constant EMA of per-frame gForce over the contact second — not the
-     * raw spike. This is the value scoring reads.
-     */
-    touchdownGForce: number;
-    /**
-     * Forensic raw peak gForce over the same contact window (un-smoothed). Kept
-     * for diagnostics; NOT used for scoring. Optional/null when no frame-buffer
-     * samples fell in the window (the scored value then came from the instantaneous
-     * touchdown-frame G and there is no raw window peak to report).
-     */
-    touchdownGForceRaw?: number | null;
-    approachAltitude: number;
-    approachIas: number;
-    approachVs: number;
-    approachBank: number;
-    approachPitch: number;
-    approachTimestamp: number;
-    /**
-     * Snapshot at ~50 ft AGL on final, used for the stabilized-approach gate.
-     * Null when the capture was missed (e.g. very fast descent, sim disconnect
-     * right before touchdown, or capture armed below 50 ft).
-     */
-    gateCapture: GateCapture | null;
-    descentTimeSeconds: number;
-    averageDescentRateFpm: number;
-    bounceCount: number;
-    bounces: BounceData[];
-    landingDistanceFt: number;
-    captureQuality: "excellent" | "good" | "fair" | "poor";
-    captureNotes: string[];
-};
-/** Debug state for the landing analyzer */
-export type LandingAnalyzerDebugState = {
-    isArmed: boolean;
-    hasCapturedApproach: boolean;
-    hasLanded: boolean;
-    isLandingSettled: boolean;
-    isBouncing: boolean;
-    bounceCount: number;
-    approachCapture: CapturePoint | null;
-    touchdownCapture: CapturePoint | null;
-    lastAirborneVs: number;
-    sampleCount: number;
-    samples: {
-        timestamp: number;
-        vs: number;
-        agl: number;
-        aglGear: number;
-    }[];
-    calculatedLandingRate: number | null;
-    landingAnalysis: LandingAnalysis | null;
-};
-/** High-frequency landing frame sample from the LandingFrameBuffer */
-export type LandingSample = {
-    timestamp: number;
-    onGround: boolean;
-    verticalSpeed: number;
-    altitudeAgl: number;
-    altitudeAglGear: number;
-    gForce: number;
-    pitch: number;
-    bank: number;
-    groundSpeed: number;
-    latitude: number;
-    longitude: number;
-    glideslopeDeviation: number | null;
-    localizerDeviation: number | null;
-};
-/** Payload for the flight:landing Socket.io event */
-export type FlightLandingPayload = {
-    type: "touchdown" | "bounce" | "settled";
-    timestamp: number;
-    landingAnalysis?: LandingAnalysis;
-    bounceData?: BounceData;
-};
 /** Snapshot returned by GET /api/simulator/snapshot for useSimData hydration */
 export type SimDataSnapshot = {
     data: FlightData | null;
@@ -399,21 +222,6 @@ export type FlightPhaseSnapshot = {
     trends: FlightTrends | null;
     isTracking: boolean;
 };
-/** Snapshot returned by GET /api/flight-events for useFlightEvents hydration */
-export type FlightEventsSnapshot = {
-    events: FlightLogEvent[];
-    isTracking: boolean;
-    elapsedTime: number;
-};
-/** Snapshot returned by GET /api/simulator/landing-analysis/snapshot for useLandingAnalysis hydration */
-export type LandingAnalysisSnapshot = {
-    landingRate: number | null;
-    bounceCount: number;
-    touchdowns: BounceData[];
-    isOnGround: boolean;
-    approachData: CapturePoint | null;
-    landingAnalysis: LandingAnalysis | null;
-};
 /** Debug info from the main process FlightStateManager */
 export type FlightStateDebugInfo = {
     trends: FlightTrends;

package/dist/shared-types/simulator.js

@@ -1,5 +1,6 @@
 /**
- * Shared flight simulation types for use by plugins.
+ * @page Simulator Data
+ * Standardized flight data, phase detection, and trend types shared across all simulators.
  *
  * These are the canonical definitions of flight data structures.
  * Comprehensive flight data variables for VA platform compatibility.
@@ -33,15 +34,3 @@ export var FlightPhase;
     FlightPhase["ARRIVED"] = "arrived";
     FlightPhase["DEBOARDING"] = "deboarding";
 })(FlightPhase || (FlightPhase = {}));
-// ── Flight Event Types ─────────────────────────────────────────────────
-/** Event categories for filtering/display */
-export var EventCategory;
-(function (EventCategory) {
-    EventCategory["SYSTEM"] = "system";
-    EventCategory["PHASE"] = "phase";
-    EventCategory["CONTROLS"] = "controls";
-    EventCategory["ENGINE"] = "engine";
-    EventCategory["WARNING"] = "warning";
-    EventCategory["POSITION"] = "position";
-    EventCategory["COMMENT"] = "comment";
-})(EventCategory || (EventCategory = {}));

package/dist/shared-types/socket-events.d.ts

@@ -1,3 +1,8 @@
+/**
+ * @page Socket Events
+ *
+ * The Socket.io event catalog and the payload shapes pushed over it.
+ */
 /**
  * Socket.io Event Catalog — canonical event names and payload types.
  *
@@ -68,6 +73,10 @@ export declare const SOCKET_EVENTS: {
     readonly PLUGIN_LOADED: "plugin:loaded";
     readonly PLUGIN_UNLOADED: "plugin:unloaded";
     readonly PLUGIN_EVENT: "plugin:event";
+    /** A background plugin opened a dialog/prompt. Payload: PluginDialogSpec */
+    readonly DIALOG_OPEN: "plugin:dialog:open";
+    /** A dialog/prompt was settled (answered/cancelled/timed out/unloaded). Payload: PluginDialogClosePayload */
+    readonly DIALOG_CLOSE: "plugin:dialog:close";
 };
 /** Union of all event name strings. */
 export type SocketEventName = (typeof SOCKET_EVENTS)[keyof typeof SOCKET_EVENTS];

package/dist/shared-types/socket-events.js

@@ -1,33 +1,7 @@
 /**
- * Socket.io Event Catalog — canonical event names and payload types.
+ * @page Socket Events
  *
- * This file is the single source of truth for all Socket.io event schemas
- * used across the Stratos platform. Both the shell (emitter) and SDK hooks
- * (consumers) import from here so payloads are always in sync.
- *
- * ┌──────────────────────┬──────────────────────────────────────────────┐
- * │ Event                │ Payload Type                                │
- * ├──────────────────────┼──────────────────────────────────────────────┤
- * │ simulator:data       │ SimulatorDataPayload                        │
- * │ simulator:status     │ SimulatorStatusPayload                      │
- * │ flight:phase         │ FlightPhasePayload                          │
- * │ flight:event         │ FlightEventPayload                          │
- * │ flight:landing       │ FlightLandingPayload                        │
- * │ flight:manager       │ FlightManagerPayload                        │
- * │ flight:state         │ (reserved for future use)                   │
- * │ protocol-url         │ ProtocolUrlPayload                          │
- * │ notification         │ NotificationPayload                         │
- * │ system:metrics       │ SystemMetricsPayload                        │
- * │ window:focus         │ {}                                          │
- * │ window:blur          │ {}                                          │
- * │ window:maximize      │ {}                                          │
- * │ window:unmaximize    │ {}                                          │
- * │ plugin:loaded        │ (plugin-defined)                            │
- * │ plugin:unloaded      │ (plugin-defined)                            │
- * │ plugin:event         │ (plugin-defined)                            │
- * └──────────────────────┴──────────────────────────────────────────────┘
- *
- * All flight-related events include a `timestamp` field (epoch ms).
+ * The Socket.io event catalog and the payload shapes pushed over it.
  */
 // ── Event Names ──────────────────────────────────────────────────────────
 /** Canonical Socket.io event names shared by shell and SDK. */
@@ -78,4 +52,8 @@ export const SOCKET_EVENTS = {
     PLUGIN_LOADED: "plugin:loaded",
     PLUGIN_UNLOADED: "plugin:unloaded",
     PLUGIN_EVENT: "plugin:event",
+    /** A background plugin opened a dialog/prompt. Payload: PluginDialogSpec */
+    DIALOG_OPEN: "plugin:dialog:open",
+    /** A dialog/prompt was settled (answered/cancelled/timed out/unloaded). Payload: PluginDialogClosePayload */
+    DIALOG_CLOSE: "plugin:dialog:close",
 };

package/dist/shared-types/theme.d.ts

@@ -1,3 +1,8 @@
-/** Theme mode for the application */
+/**
+ * @page Theme
+ *
+ * The shell theme mode.
+ */
+/** Theme mode for the application. */
 export type ThemeMode = "dark" | "light" | "system";
 //# sourceMappingURL=theme.d.ts.map

package/dist/shared-types/theme.js

@@ -1 +1,6 @@
+/**
+ * @page Theme
+ *
+ * The shell theme mode.
+ */
 export {};

package/dist/types/context-ui.d.ts

@@ -0,0 +1,101 @@
+/**
+ * @page UI Context
+ * The context the shell injects into a plugin's React tree via PluginShellProvider.
+ */
+import type { AxiosInstance } from "axios";
+import type { PluginLogger } from "./context";
+/** Pilot user profile provided by the shell's auth system */
+export type PluginPilotUser = {
+    dbID: number;
+    pilotID: string;
+    firstName: string;
+    lastName: string;
+    email: string;
+    rank: string;
+    rankLevel: number;
+    rankImage: string;
+    avatar: string;
+};
+/** Navigation helper for plugin UI components */
+export type PluginNavigationHelper = {
+    /** Navigate to a route within this plugin */
+    navigateTo(path: string): void;
+    /** Navigate to a route in another plugin */
+    navigateToPlugin(pluginId: string, path: string): void;
+    /** Navigate to a shell route */
+    navigateToShell(path: string): void;
+    /** Get the current route path */
+    getCurrentPath(): string;
+};
+/** Toast/notification API for plugin UI */
+export type PluginToastAPI = {
+    success(message: string): void;
+    error(message: string): void;
+    info(message: string): void;
+    warning(message: string): void;
+};
+/**
+ * UI context available to plugin renderer components via React context.
+ * Provides shared hooks and utilities from the shell.
+ */
+export type PluginUIContext = {
+    /**
+     * Shared axios instance for the bound airline's API, with auto-refresh on
+     * 401. Provided by the shell so all plugin UIs and the shell itself share
+     * one in-flight refresh promise — concurrent 401s coalesce to a single
+     * `POST /api/auth/va/refresh`. Reach this through `useVaApi()`.
+     */
+    vaApi: AxiosInstance;
+    /** The plugin's unique ID */
+    pluginId: string;
+    /** Auth state from the shell */
+    auth: {
+        isAuthenticated: boolean;
+        token: string | null;
+        user: PluginPilotUser | null;
+    };
+    /** Current airline info (from Stratos API). Bundled with the VA bearer
+     *  so plugins can call the airline backend directly. */
+    airline?: {
+        id: string;
+        name: string;
+        icao: string;
+        logo_light: string;
+        logo_dark: string;
+        /** Origin of the VA's API (no trailing slash). */
+        base_url: string;
+        /** Bearer for this airline's API. Null if the VA session has expired. */
+        token: string | null;
+    } | null;
+    /** Config access hooks */
+    config: {
+        get<T>(key: string): T | undefined;
+        get<T>(key: string, defaultValue: T): T;
+    };
+    /**
+     * Real-time bridge between this plugin's background and UI modules.
+     *
+     * - `on(event, handler)` subscribes to broadcasts the background made via
+     *   `ctx.ipc.send(event, payload)`. The shell scopes the channel to the
+     *   current plugin id automatically — pass the leaf event name on both
+     *   ends. Plugin A's UI cannot receive plugin B's broadcasts.
+     * - `off(event, handler)` removes a previously registered handler.
+     * - `emit` is intentionally not implemented. Send UI→background traffic
+     *   through HTTP routes registered via `ctx.server.registerRouter`.
+     * - `connected` is always `true` in the renderer; the underlying Electron
+     *   IPC pipe has no connection lifecycle.
+     */
+    socket: {
+        connected: boolean;
+        emit(event: string, data: unknown): void;
+        on(event: string, handler: (data: unknown) => void): void;
+        off(event: string, handler: (data: unknown) => void): void;
+    };
+    /** Navigation utilities */
+    navigation: PluginNavigationHelper;
+    /** Toast/notification API */
+    toast: PluginToastAPI;
+    /** Scoped logger for renderer-side logging */
+    logger: PluginLogger;
+};
+//# sourceMappingURL=context-ui.d.ts.map

package/dist/types/context-ui.js

@@ -0,0 +1,5 @@
+/**
+ * @page UI Context
+ * The context the shell injects into a plugin's React tree via PluginShellProvider.
+ */
+export {};