@skyvexsoftware/stratos-sdk 0.11.1 → 0.12.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export type { PluginAuthor, PluginManifest } from "./types/manifest";
-export type { PluginAirline, PluginAirlineAccessor, PluginAuthAccessor, PluginVaApiClient, PluginConfigStore, PluginContext, PluginDatabaseAccessor, PluginIPCRegistrar, PluginLogger, PluginNavigationHelper, PluginPilotUser, PluginServerRegistrar, PluginToastAPI, PluginUIContext, PluginSettingType, PluginSettingOption, PluginSettingDefinition, PluginAvailableSettings, BooleanSettingDef, TextSettingDef, LongtextSettingDef, NumberSettingDef, RangeSettingDef, ListSettingDef, RadioSettingDef, DateSettingDef, JsonSettingDef, } from "./types/context";
+export type { PluginAirline, PluginAirlineAccessor, PluginAuthAccessor, PluginVaApiClient, PluginConfigStore, PluginContext, PluginDatabaseAccessor, PluginIPCRegistrar, PluginLogger, PluginNavigationHelper, PluginPilotUser, PluginServerRegistrar, PluginToastAPI, PluginUIContext, PluginFlightAccessor, PluginFlightLogWriter, PluginFlightLogInput, PluginFlightLogPatch, PluginStartGuard, PluginStartContext, PluginStartDecision, PluginNotifier, PluginToastInput, PluginAlertSound, PluginSettingType, PluginSettingOption, PluginSettingDefinition, PluginAvailableSettings, BooleanSettingDef, TextSettingDef, LongtextSettingDef, NumberSettingDef, RangeSettingDef, ListSettingDef, RadioSettingDef, DateSettingDef, JsonSettingDef, } from "./types/context";
 export type { PluginBackgroundModule, PluginRouteComponent, PluginUIModule, } from "./types/module";
 export { FlightPhase, SimulatorType, EventCategory, } from "./shared-types/simulator";
 export type { BounceData, CapturePoint, FlightData, FlightDataSnapshot, FlightEventPayload, FlightEventsSnapshot, FlightLandingPayload, FlightLogEvent, FlightPhasePayload, FlightPhaseSnapshot, FlightStateDebugInfo, FlightTrends, GateCapture, HistoryReportEntry, LandingAnalysis, LandingAnalysisSnapshot, LandingAnalyzerDebugState, LandingSample, PendingPhaseTransition, SimDataSnapshot, SimulatorStatus, } from "./shared-types/simulator";

package/dist/shared-types/flight-manager.d.ts

@@ -79,6 +79,8 @@ export type PreflightCheckResult = {
 /** Options for startFlight */
 export type StartFlightOptions = {
     forceStart?: boolean;
+    /** True when the start was triggered by auto-start (not a manual click). Surfaced to plugin start guards. */
+    isAutoStart?: boolean;
 };
 /** Lean subset of stored flight data for recovery prompt in the renderer */
 export type RecoverableFlight = {

package/dist/types/context.d.ts

@@ -5,6 +5,8 @@
  * for both background (main process) and UI (renderer) usage.
  */
 import type { AxiosInstance } from "axios";
+import type { EventCategory, FlightLogEvent, FlightPhasePayload, FlightPhaseSnapshot, FlightLandingPayload, LandingAnalysisSnapshot, SimDataSnapshot } from "../shared-types/simulator";
+import type { FlightManagerPayload, FlightPlan } from "../shared-types/flight-manager";
 /** All supported setting control types */
 export type PluginSettingType = "boolean" | "text" | "longtext" | "number" | "range" | "list" | "radio" | "date" | "json";
 /** Option entry for list and radio settings */
@@ -171,6 +173,105 @@ export type PluginDatabaseAccessor = {
      */
     open(filename: string): unknown;
 };
+/**
+ * Writer for the authoritative flight log. Backs `ctx.flight.log`.
+ *
+ * Replaces the rejected pattern of importing core's FlightEventManager and
+ * mutating its private `flightLog` array. All mutations are routed through the
+ * shell so persistence, the event bus, and the pirep split stay consistent.
+ */
+export type PluginFlightLogWriter = {
+    /**
+     * Append an event to the flight log. Returns the created event, or null when
+     * there is no active tracking session (mirrors `addComment`).
+     */
+    add(event: PluginFlightLogInput): Promise<FlightLogEvent | null>;
+    /** Remove a previously-added event by id. Returns true if it existed. */
+    remove(eventId: string): Promise<boolean>;
+    /** Patch an existing event in place. Returns true if it existed. */
+    update(eventId: string, patch: PluginFlightLogPatch): Promise<boolean>;
+};
+/** Input for `ctx.flight.log.add`. */
+export type PluginFlightLogInput = {
+    category: EventCategory;
+    condition: string;
+    message: string;
+    data?: Record<string, unknown>;
+};
+/** Patch shape for `ctx.flight.log.update`. */
+export type PluginFlightLogPatch = Partial<Pick<PluginFlightLogInput, "category" | "message" | "data">>;
+/**
+ * Read/subscribe accessor for live flight state. Backs `ctx.flight`.
+ *
+ * Reads return serialisable snapshots; subscriptions deliver the same payloads
+ * the shell broadcasts over Socket.io. Every `onX` returns an unsubscribe.
+ */
+export type PluginFlightAccessor = {
+    /** Current flight-manager state (flight, pending recovery, sim-disconnect). */
+    getState(): Promise<FlightManagerPayload>;
+    /** Latest simulator data snapshot, or null when no sim is connected. */
+    getSnapshot(): Promise<SimDataSnapshot | null>;
+    /** Current flight-phase snapshot. */
+    getPhase(): Promise<FlightPhaseSnapshot>;
+    /** Current landing-analysis snapshot. */
+    getLandingReport(): Promise<LandingAnalysisSnapshot>;
+    /** Subscribe to flight-manager state changes. Returns an unsubscribe. */
+    onUpdate(cb: (state: FlightManagerPayload) => void): () => void;
+    /** Subscribe to flight-phase changes. Returns an unsubscribe. */
+    onPhaseChange(cb: (payload: FlightPhasePayload) => void): () => void;
+    /** Subscribe to live simulator data frames. Returns an unsubscribe. */
+    onSimData(cb: (snapshot: SimDataSnapshot) => void): () => void;
+    /** Subscribe to landing events (touchdown/bounce/settled). Returns an unsubscribe. */
+    onLanding(cb: (payload: FlightLandingPayload) => void): () => void;
+    /** Authoritative flight-log writer. */
+    log: PluginFlightLogWriter;
+    /**
+     * Register a guard consulted inside `startFlight` BEFORE the flight is
+     * created or persisted. A guard returning `{ allow: false, reason }` vetoes
+     * the start (surfaced via the existing preflight-failure path). Guards are
+     * fail-open: a throw or timeout (~5s) allows the start with a loud warning.
+     * Multiple guards: the first `allow: false` wins. Returns an unsubscribe.
+     */
+    registerStartGuard(guard: PluginStartGuard): () => void;
+};
+/** Context handed to a start guard. */
+export type PluginStartContext = {
+    plan: FlightPlan;
+    snapshot: SimDataSnapshot | null;
+    isAutoStart: boolean;
+};
+/** Decision returned by a start guard. */
+export type PluginStartDecision = {
+    allow: true;
+} | {
+    allow: false;
+    reason: string;
+};
+/** Guard run inside `startFlight` before the flight is created/persisted. */
+export type PluginStartGuard = (ctx: PluginStartContext) => PluginStartDecision | Promise<PluginStartDecision>;
+/**
+ * Toast + sound surface. Backs `ctx.notify`.
+ *
+ * Replaces the rejected pattern of `webContents.executeJavaScript` to build
+ * DOM toasts and play `new Audio(...)`. The shell owns the DOM and the sound
+ * catalogue; the plugin only describes what to show / which sound to play.
+ */
+export type PluginNotifier = {
+    /** Show a toast in the renderer. */
+    toast(n: PluginToastInput): Promise<void>;
+    /** Play a shell-bundled sound by name (no plugin-supplied audio). */
+    sound(name: PluginAlertSound): Promise<void>;
+};
+/** Input for `ctx.notify.toast`. */
+export type PluginToastInput = {
+    type: "info" | "success" | "warning" | "error";
+    title: string;
+    message: string;
+    durationMs?: number;
+    id?: string;
+};
+/** Fixed shell-bundled sound catalogue. No plugin-supplied audio. */
+export type PluginAlertSound = "alert" | "warning" | "error" | "success" | "chime";
 /**
  * Context passed to a plugin's background onStart() function.
  * Provides scoped access to shell infrastructure.
@@ -190,6 +291,13 @@ export type PluginContext = {
     server: PluginServerRegistrar;
     /** SQLite database accessor (files stored in plugin's data directory) */
     database: PluginDatabaseAccessor;
+    /**
+     * Live flight state: reads, subscriptions, the authoritative flight-log
+     * writer, and start guards.
+     */
+    flight: PluginFlightAccessor;
+    /** Toast + sound surface. */
+    notify: PluginNotifier;
 };
 /** Pilot user profile provided by the shell's auth system */
 export type PluginPilotUser = {

package/dist/types/index.d.ts

@@ -1,4 +1,4 @@
 export type { PluginAuthor, PluginManifest } from "./manifest";
-export type { PluginAirline, PluginAirlineAccessor, PluginAuthAccessor, PluginConfigStore, PluginContext, PluginDatabaseAccessor, PluginIPCRegistrar, PluginLogger, PluginNavigationHelper, PluginServerRegistrar, PluginToastAPI, PluginUIContext, } from "./context";
+export type { PluginAirline, PluginAirlineAccessor, PluginAuthAccessor, PluginConfigStore, PluginContext, PluginDatabaseAccessor, PluginIPCRegistrar, PluginLogger, PluginNavigationHelper, PluginServerRegistrar, PluginToastAPI, PluginUIContext, PluginFlightAccessor, PluginFlightLogWriter, PluginFlightLogInput, PluginFlightLogPatch, PluginStartGuard, PluginStartContext, PluginStartDecision, PluginNotifier, PluginToastInput, PluginAlertSound, } from "./context";
 export type { PluginBackgroundModule, PluginRouteComponent, PluginUIModule, } from "./module";
 //# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyvexsoftware/stratos-sdk",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "Plugin SDK for Stratos — types, hooks, and UI components",
   "author": {
     "name": "Skyvex Software Pty Ltd",