@skyvexsoftware/stratos-sdk 0.12.0 → 0.13.1

package/dist/types/context.d.ts

@@ -1,86 +1,15 @@
 /**
- * Plugin Context Types
+ * @page Background Context
+ * The context object the shell passes to a plugin's background module — ctx — and its accessors.
  *
- * Defines the context objects the shell provides to plugins
- * for both background (main process) and UI (renderer) usage.
+ * Defines the context objects the shell provides to background plugins
+ * (main process). For the renderer-facing surface see context-ui.ts.
  */
 import type { AxiosInstance } from "axios";
-import type { EventCategory, FlightLogEvent, FlightPhasePayload, FlightPhaseSnapshot, FlightLandingPayload, LandingAnalysisSnapshot, SimDataSnapshot } from "../shared-types/simulator";
+import type { FlightPhasePayload, FlightPhaseSnapshot, SimDataSnapshot } from "../shared-types/simulator";
+import type { EventCategory, FlightLogEvent } from "../shared-types/flight-events";
+import type { FlightLandingPayload, LandingAnalysisSnapshot } from "../shared-types/landing";
 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 */
-export type PluginSettingOption = {
-    value: string;
-    label: string;
-};
-/** Base fields shared by all setting definitions */
-type PluginSettingBase = {
-    key: string;
-    name: string;
-    description?: string;
-    scope: "user" | "airline";
-};
-/** Boolean setting — rendered as a Switch */
-export type BooleanSettingDef = PluginSettingBase & {
-    type: "boolean";
-    default?: boolean;
-};
-/** Text setting — rendered as an Input */
-export type TextSettingDef = PluginSettingBase & {
-    type: "text";
-    default?: string;
-    pattern?: string;
-    placeholder?: string;
-};
-/** Long text setting — rendered as a Textarea */
-export type LongtextSettingDef = PluginSettingBase & {
-    type: "longtext";
-    default?: string;
-    placeholder?: string;
-};
-/** Number setting — rendered as a Number Input */
-export type NumberSettingDef = PluginSettingBase & {
-    type: "number";
-    default?: number;
-    min?: number;
-    max?: number;
-    step?: number;
-};
-/** Range setting — rendered as a Slider + value label */
-export type RangeSettingDef = PluginSettingBase & {
-    type: "range";
-    default?: number;
-    min: number;
-    max: number;
-    step?: number;
-};
-/** List setting — rendered as a Select dropdown */
-export type ListSettingDef = PluginSettingBase & {
-    type: "list";
-    default?: string;
-    options: PluginSettingOption[];
-};
-/** Radio setting — rendered as a Radio group */
-export type RadioSettingDef = PluginSettingBase & {
-    type: "radio";
-    default?: string;
-    options: PluginSettingOption[];
-};
-/** Date setting — rendered as a Date input */
-export type DateSettingDef = PluginSettingBase & {
-    type: "date";
-    default?: string;
-};
-/** JSON setting — rendered as a monospace Textarea */
-export type JsonSettingDef = PluginSettingBase & {
-    type: "json";
-    default?: string;
-};
-/** Discriminated union of all setting definitions */
-export type PluginSettingDefinition = BooleanSettingDef | TextSettingDef | LongtextSettingDef | NumberSettingDef | RangeSettingDef | ListSettingDef | RadioSettingDef | DateSettingDef | JsonSettingDef;
-/** Array of available settings declared by a plugin */
-export type PluginAvailableSettings = PluginSettingDefinition[];
 /** Scoped logger provided to background plugins (prefixed with plugin ID) */
 export type PluginLogger = {
     info(category: string, message: string, ...args: unknown[]): void;
@@ -272,6 +201,95 @@ export type PluginToastInput = {
 };
 /** 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.
@@ -298,100 +316,9 @@ export type PluginContext = {
     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 = {
-    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;
-};
-export {};
 //# sourceMappingURL=context.d.ts.map

package/dist/types/context.js

@@ -1,7 +1,8 @@
 /**
- * Plugin Context Types
+ * @page Background Context
+ * The context object the shell passes to a plugin's background module — ctx — and its accessors.
  *
- * Defines the context objects the shell provides to plugins
- * for both background (main process) and UI (renderer) usage.
+ * Defines the context objects the shell provides to background plugins
+ * (main process). For the renderer-facing surface see context-ui.ts.
  */
 export {};

package/dist/types/index.d.ts

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

package/dist/types/manifest.d.ts

@@ -1,5 +1,5 @@
 /**
- * Plugin Manifest Schema
+ * Plugin manifest schema — the contents of every plugin's plugin.json.
  *
  * Defines the structure of a plugin's plugin.json file.
  * Every plugin must include a valid plugin.json at its root.
@@ -7,13 +7,15 @@
  * Background and UI modules are discovered by convention:
  * - background/index.js — background service entry point
  * - ui/index.js — renderer UI entry point
+ *
+ * @page Manifest
  */
-import type { PluginSettingDefinition } from "./context";
+import type { PluginSettingDefinition } from "./settings";
 /** Plugin author information */
 export type PluginAuthor = {
     /** Unique developer slug (e.g. "skyvex-software") */
     id: string;
-    /** Display name (e.g. "SkyVex Software") */
+    /** Display name (e.g. "Skyvex Software") */
     name: string;
     /** Contact email address (optional) */
     contact?: string;

package/dist/types/manifest.js

@@ -1,5 +1,5 @@
 /**
- * Plugin Manifest Schema
+ * Plugin manifest schema — the contents of every plugin's plugin.json.
  *
  * Defines the structure of a plugin's plugin.json file.
  * Every plugin must include a valid plugin.json at its root.
@@ -7,5 +7,7 @@
  * Background and UI modules are discovered by convention:
  * - background/index.js — background service entry point
  * - ui/index.js — renderer UI entry point
+ *
+ * @page Manifest
  */
 export {};

package/dist/types/module.d.ts

@@ -1,7 +1,9 @@
 /**
- * Plugin Module Contracts
+ * The background and UI module shapes a plugin's entry points must satisfy.
  *
  * Defines the export shapes for plugin background and UI modules.
+ *
+ * @page Modules
  */
 import type { ComponentType, LazyExoticComponent } from "react";
 import type { PluginContext } from "./context";
@@ -10,7 +12,7 @@ import type { PluginContext } from "./context";
  * Each plugin's background entry module must export these functions.
  */
 export type PluginBackgroundModule = {
-    /** Called during shell startup after auth is initialized */
+    /** Called during shell startup after auth is initialised */
     onStart(ctx: PluginContext): Promise<void>;
     /** Called during shell shutdown for graceful teardown */
     onStop(ctx: PluginContext): Promise<void>;

package/dist/types/module.js

@@ -1,6 +1,8 @@
 /**
- * Plugin Module Contracts
+ * The background and UI module shapes a plugin's entry points must satisfy.
  *
  * Defines the export shapes for plugin background and UI modules.
+ *
+ * @page Modules
  */
 export {};

package/dist/types/settings.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @page Settings
+ *
+ * Typed plugin setting definitions — the controls a plugin declares in its manifest's availableSettings.
+ */
+/** All supported setting control types */
+export type PluginSettingType = "boolean" | "text" | "longtext" | "number" | "range" | "list" | "radio" | "date" | "json";
+/** Option entry for list and radio settings */
+export type PluginSettingOption = {
+    value: string;
+    label: string;
+};
+/** Base fields shared by all setting definitions */
+type PluginSettingBase = {
+    key: string;
+    name: string;
+    description?: string;
+    scope: "user" | "airline";
+};
+/** Boolean setting — rendered as a Switch */
+export type BooleanSettingDef = PluginSettingBase & {
+    type: "boolean";
+    default?: boolean;
+};
+/** Text setting — rendered as an Input */
+export type TextSettingDef = PluginSettingBase & {
+    type: "text";
+    default?: string;
+    pattern?: string;
+    placeholder?: string;
+};
+/** Long text setting — rendered as a Textarea */
+export type LongtextSettingDef = PluginSettingBase & {
+    type: "longtext";
+    default?: string;
+    placeholder?: string;
+};
+/** Number setting — rendered as a Number Input */
+export type NumberSettingDef = PluginSettingBase & {
+    type: "number";
+    default?: number;
+    min?: number;
+    max?: number;
+    step?: number;
+};
+/** Range setting — rendered as a Slider + value label */
+export type RangeSettingDef = PluginSettingBase & {
+    type: "range";
+    default?: number;
+    min: number;
+    max: number;
+    step?: number;
+};
+/** List setting — rendered as a Select dropdown */
+export type ListSettingDef = PluginSettingBase & {
+    type: "list";
+    default?: string;
+    options: PluginSettingOption[];
+};
+/** Radio setting — rendered as a Radio group */
+export type RadioSettingDef = PluginSettingBase & {
+    type: "radio";
+    default?: string;
+    options: PluginSettingOption[];
+};
+/** Date setting — rendered as a Date input */
+export type DateSettingDef = PluginSettingBase & {
+    type: "date";
+    default?: string;
+};
+/** JSON setting — rendered as a monospace Textarea */
+export type JsonSettingDef = PluginSettingBase & {
+    type: "json";
+    default?: string;
+};
+/** Discriminated union of all setting definitions */
+export type PluginSettingDefinition = BooleanSettingDef | TextSettingDef | LongtextSettingDef | NumberSettingDef | RangeSettingDef | ListSettingDef | RadioSettingDef | DateSettingDef | JsonSettingDef;
+/** Array of available settings declared by a plugin */
+export type PluginAvailableSettings = PluginSettingDefinition[];
+export {};
+//# sourceMappingURL=settings.d.ts.map

package/dist/types/settings.js

@@ -0,0 +1,6 @@
+/**
+ * @page Settings
+ *
+ * Typed plugin setting definitions — the controls a plugin declares in its manifest's availableSettings.
+ */
+export {};

package/dist/ui/badge.d.ts

@@ -1,8 +1,10 @@
+/** @page UI Component Props */
 import * as React from "react";
 import { type VariantProps } from "class-variance-authority";
 declare const badgeVariants: (props?: ({
     variant?: "default" | "destructive" | "outline" | "secondary" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
+/** Props for the `Badge` component, extending native div attributes with CVA variants. */
 export type BadgeProps = React.HTMLAttributes<HTMLDivElement> & VariantProps<typeof badgeVariants>;
 declare function Badge({ className, variant, ...props }: BadgeProps): import("react/jsx-runtime").JSX.Element;
 export { Badge, badgeVariants };

package/dist/ui/button.d.ts

@@ -1,9 +1,15 @@
+/**
+ * @page UI Component Props
+ *
+ * Prop types for the shared SDK UI primitives.
+ */
 import * as React from "react";
 import { type VariantProps } from "class-variance-authority";
 declare const buttonVariants: (props?: ({
     variant?: "link" | "default" | "destructive" | "outline" | "secondary" | "ghost" | "pill-pause" | "pill-resume" | "pill-end" | "pill-submit" | null | undefined;
     size?: "default" | "sm" | "lg" | "icon" | "pill" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
+/** Props for the `Button` component, extending native button attributes with CVA variants. */
 export type ButtonProps = React.ButtonHTMLAttributes<HTMLButtonElement> & VariantProps<typeof buttonVariants> & {
     asChild?: boolean;
 };

package/dist/ui/button.js

@@ -1,4 +1,9 @@
 import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * @page UI Component Props
+ *
+ * Prop types for the shared SDK UI primitives.
+ */
 import * as React from "react";
 import { Slot } from "@radix-ui/react-slot";
 import { cva } from "class-variance-authority";

package/dist/ui/combobox.d.ts

@@ -1,7 +1,10 @@
+/** @page UI Component Props */
+/** A single selectable option in the `Combobox` list. */
 export type ComboboxOption = {
     value: string;
     label: string;
 };
+/** Props for the searchable single-select `Combobox` component. */
 export type ComboboxProps = {
     options: ComboboxOption[];
     value?: string;

package/dist/ui/combobox.js

@@ -1,4 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/** @page UI Component Props */
 import * as React from "react";
 import { Command } from "cmdk";
 import { Check, ChevronsUpDown, Search } from "lucide-react";

package/package.json

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