@skyvexsoftware/stratos-sdk 0.11.1 → 0.13.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, PluginDialogApi, PluginPromptApi, PluginDialogAlertInput, PluginDialogConfirmInput, PluginPromptTextInput, PluginPromptNumberInput, PluginPromptSelectInput, 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";
@@ -30,6 +30,7 @@ export { useShellToast } from "./hooks/useShellToast";
 export { useSocket, useSimulatorData, useProtocolUrl, useNotifications, useSystemMetrics, } from "./hooks/useSimulatorData";
 export { SOCKET_EVENTS } from "./shared-types/socket-events";
 export type { AutoStartConfirmPayload, ConnectionState, LogEntryPayload, NotificationPayload, ProtocolUrlPayload, SimulatorDataPayload, SimulatorStatusPayload, SocketEventName, SystemMetricsPayload, } from "./shared-types/socket-events";
+export type { PluginDialogKind, PluginDialogSelectOption, PluginDialogSpec, PluginDialogResult, PluginDialogClosePayload, } from "./shared-types/plugin-dialogs";
 export { AlertDialog, AlertDialogPortal, AlertDialogOverlay, AlertDialogTrigger, AlertDialogContent, AlertDialogHeader, AlertDialogFooter, AlertDialogTitle, AlertDialogDescription, AlertDialogAction, AlertDialogCancel, Badge, badgeVariants, Button, buttonVariants, Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Combobox, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogOverlay, DialogPortal, DialogTitle, DialogTrigger, Input, Label, Popover, PopoverAnchor, PopoverContent, PopoverTrigger, RadioGroup, RadioGroupItem, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectScrollDownButton, SelectScrollUpButton, SelectSeparator, SelectTrigger, SelectValue, Separator, Slider, Switch, Tabs, TabsContent, TabsList, TabsTrigger, Textarea, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, } from "./ui";
 export type { BadgeProps, ButtonProps, ComboboxOption, ComboboxProps, } from "./ui";
 export { STRATOS_ICONS, STRATOS_ICON_NAMES } from "./icons";

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/shared-types/index.d.ts

@@ -6,4 +6,5 @@ export type { AdditionalFieldsConfig, FieldDelivery, } from "./additional-fields
 export type { FlightPlan, FlightStatus, CurrentFlight, FlightComment, PreflightCheck, PreflightCheckResult, StartFlightOptions, FlightManagerPayload, StartFlightResult, RecoverableFlight, } from "./flight-manager";
 export { SOCKET_EVENTS } from "./socket-events";
 export type { ConnectionState, LogEntryPayload, NotificationPayload, ProtocolUrlPayload, SimulatorDataPayload, SimulatorStatusPayload, SocketEventName, SystemMetricsPayload, } from "./socket-events";
+export type { PluginDialogKind, PluginDialogSelectOption, PluginDialogSpec, PluginDialogResult, PluginDialogClosePayload, } from "./plugin-dialogs";
 //# sourceMappingURL=index.d.ts.map

package/dist/shared-types/plugin-dialogs.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Wire types for the background-plugin dialog/prompt surface.
+ *
+ * A `PluginDialogSpec` is broadcast to the renderer (SOCKET_EVENTS.DIALOG_OPEN)
+ * and also served by GET /api/plugin-dialogs for hydrate. The renderer posts a
+ * `PluginDialogResult` back. The wire value is always a string (or absent) — the
+ * typed coercion to boolean/number/null lives in the loader wrappers.
+ */
+export type PluginDialogKind = "alert" | "confirm" | "text" | "number" | "select";
+export type PluginDialogSelectOption = {
+    value: string;
+    label: string;
+};
+/** Fully-resolved spec for one open dialog. */
+export type PluginDialogSpec = {
+    requestId: string;
+    pluginId: string;
+    pluginName: string;
+    kind: PluginDialogKind;
+    title: string;
+    /** Body text (dialogs) or helper text above the field (prompts). */
+    message?: string;
+    /** Field label (prompts only). */
+    label?: string;
+    placeholder?: string;
+    /** Pre-filled value (always a string on the wire; number prompts stringify it). */
+    defaultValue?: string;
+    required?: boolean;
+    maxLength?: number;
+    min?: number;
+    max?: number;
+    step?: number;
+    options?: PluginDialogSelectOption[];
+    okLabel?: string;
+    confirmLabel?: string;
+    cancelLabel?: string;
+    submitLabel?: string;
+    timeoutMs?: number;
+};
+/** Result posted back from the renderer / used to settle the pending promise. */
+export type PluginDialogResult = {
+    submitted: boolean;
+    value?: string;
+};
+/** Payload for SOCKET_EVENTS.DIALOG_CLOSE. */
+export type PluginDialogClosePayload = {
+    requestId: string;
+};
+//# sourceMappingURL=plugin-dialogs.d.ts.map

package/dist/shared-types/plugin-dialogs.js

@@ -0,0 +1,9 @@
+/**
+ * Wire types for the background-plugin dialog/prompt surface.
+ *
+ * A `PluginDialogSpec` is broadcast to the renderer (SOCKET_EVENTS.DIALOG_OPEN)
+ * and also served by GET /api/plugin-dialogs for hydrate. The renderer posts a
+ * `PluginDialogResult` back. The wire value is always a string (or absent) — the
+ * typed coercion to boolean/number/null lives in the loader wrappers.
+ */
+export {};

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

@@ -68,6 +68,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

@@ -78,4 +78,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/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,194 @@ 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";
+/** Input for `ctx.dialog.alert`. */
+export type PluginDialogAlertInput = {
+    title: string;
+    message: string;
+    /** Acknowledge-button label. Default "OK". */
+    okLabel?: string;
+    /** Optional auto-cancel; on expiry the call resolves (void). */
+    timeoutMs?: number;
+};
+/** Input for `ctx.dialog.confirm`. */
+export type PluginDialogConfirmInput = {
+    title: string;
+    message: string;
+    /** Confirm-button label. Default "Confirm". */
+    confirmLabel?: string;
+    /** Cancel-button label. Default "Cancel". */
+    cancelLabel?: string;
+    /** Optional auto-cancel; on expiry the call resolves false. */
+    timeoutMs?: number;
+};
+/** Input for `ctx.prompt.text`. */
+export type PluginPromptTextInput = {
+    title: string;
+    /** Field label, e.g. "What gate are you departing from?". */
+    label: string;
+    /** Optional helper/body text shown above the field. */
+    message?: string;
+    placeholder?: string;
+    defaultValue?: string;
+    /** When true, Submit is disabled until the field is non-empty. */
+    required?: boolean;
+    maxLength?: number;
+    submitLabel?: string;
+    cancelLabel?: string;
+    timeoutMs?: number;
+};
+/** Input for `ctx.prompt.number`. */
+export type PluginPromptNumberInput = {
+    title: string;
+    label: string;
+    message?: string;
+    placeholder?: string;
+    defaultValue?: number;
+    required?: boolean;
+    min?: number;
+    max?: number;
+    step?: number;
+    submitLabel?: string;
+    cancelLabel?: string;
+    timeoutMs?: number;
+};
+/** Input for `ctx.prompt.select`. */
+export type PluginPromptSelectInput = {
+    title: string;
+    label: string;
+    message?: string;
+    options: {
+        value: string;
+        label: string;
+    }[];
+    /** Pre-selected option value. */
+    defaultValue?: string;
+    required?: boolean;
+    submitLabel?: string;
+    cancelLabel?: string;
+    timeoutMs?: number;
+};
+/**
+ * Message-centric dialogs. The pilot reads a message and clicks a button.
+ * Backs `ctx.dialog`.
+ */
+export type PluginDialogApi = {
+    /** Show a blocking message with a single acknowledge button. */
+    alert(input: PluginDialogAlertInput): Promise<void>;
+    /** Ask a yes/no question. Resolves false on cancel/dismiss/timeout. */
+    confirm(input: PluginDialogConfirmInput): Promise<boolean>;
+};
+/**
+ * Input-centric prompts. The pilot provides a value. Backs `ctx.prompt`.
+ * All resolve null on cancel/dismiss/timeout.
+ */
+export type PluginPromptApi = {
+    /** Ask for free text. */
+    text(input: PluginPromptTextInput): Promise<string | null>;
+    /** Ask for a number. A non-numeric/blank submit resolves null. */
+    number(input: PluginPromptNumberInput): Promise<number | null>;
+    /** Ask the pilot to pick one of the supplied options. Returns the value. */
+    select(input: PluginPromptSelectInput): Promise<string | null>;
+};
 /**
  * Context passed to a plugin's background onStart() function.
  * Provides scoped access to shell infrastructure.
@@ -190,6 +380,17 @@ 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;
+    /** Blocking, awaited message dialogs (alert/confirm). */
+    dialog: PluginDialogApi;
+    /** Blocking, awaited input prompts (text/number/select). */
+    prompt: PluginPromptApi;
 };
 /** 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.13.0",
   "description": "Plugin SDK for Stratos — types, hooks, and UI components",
   "author": {
     "name": "Skyvex Software Pty Ltd",