@skyvexsoftware/stratos-sdk 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Skyvex Software
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,201 @@
+# @skyvexsoftware/stratos-sdk
+
+The Stratos Plugin SDK provides typed access to shell APIs, shared UI components, and utility functions for building Stratos plugins.
+
+## Installation
+
+**External plugin developers (npm):**
+
+```bash
+npm install @skyvexsoftware/stratos-sdk
+```
+
+**Within the Stratos monorepo (workspace):**
+
+```bash
+pnpm add @skyvexsoftware/stratos-sdk --workspace
+```
+
+## Available APIs
+
+### Plugin Contract Types
+
+Type definitions for the plugin system:
+
+```ts
+import type {
+  PluginManifest,
+  PluginContext,
+  PluginUIContext,
+  PluginBackgroundModule,
+  PluginUIModule,
+} from "@skyvexsoftware/stratos-sdk";
+```
+
+### Helper Functions
+
+#### `createPlugin(module)`
+
+Validates and returns a typed plugin background module:
+
+```ts
+import { createPlugin } from "@skyvexsoftware/stratos-sdk";
+
+export default createPlugin({
+  async onStart(ctx) {
+    ctx.logger.info("MyPlugin", "Starting...");
+  },
+  async onStop() {
+    // cleanup
+  },
+});
+```
+
+#### `PluginRouter` component
+
+Optional lightweight router for plugins that need internal multi-page navigation:
+
+```tsx
+import { PluginRouter } from "@skyvexsoftware/stratos-sdk";
+import TrackingPage from "./pages/TrackingPage";
+import HistoryPage from "./pages/HistoryPage";
+import HistoryDetailPage from "./pages/HistoryDetailPage";
+
+const routes = [
+  { path: "tracking", component: TrackingPage },
+  { path: "history", component: HistoryPage },
+  { path: "history/:id", component: HistoryDetailPage },
+];
+
+export default function MyPluginRoot() {
+  return <PluginRouter routes={routes} defaultPath="tracking" />;
+}
+```
+
+For single-page plugins, just export the component directly:
+
+```tsx
+import HomePage from "./HomePage";
+export default HomePage;
+```
+
+#### `usePluginRoute()`
+
+Returns the current sub-path within the plugin (the URL portion after `/plugins/{pluginId}/`):
+
+```tsx
+import { usePluginRoute } from "@skyvexsoftware/stratos-sdk";
+
+function MyComponent() {
+  const { subPath } = usePluginRoute();
+  // e.g. "history/abc123"
+}
+```
+
+#### `usePluginParams()`
+
+Access route params matched by `PluginRouter` (e.g. `history/:id`):
+
+```tsx
+import { usePluginParams } from "@skyvexsoftware/stratos-sdk";
+
+function DetailPage() {
+  const { id } = usePluginParams<{ id: string }>();
+  // id === "abc123" when URL is /plugins/my-plugin/history/abc123
+}
+```
+
+### React Hooks
+
+Access shell services from plugin components. All hooks must be used within a `PluginShellProvider` (provided by the shell at runtime).
+
+| Hook                 | Returns              | Description                    |
+| -------------------- | -------------------- | ------------------------------ |
+| `useShellAuth()`     | Auth state           | Authentication state and token |
+| `useShellConfig()`   | Config store         | Scoped configuration access    |
+| `useShellNavigation()` | Navigation helpers | Route navigation utilities     |
+| `useShellToast()`    | Toast API            | Toast/notification functions   |
+| `usePluginLogger()`  | Logger               | Scoped renderer-side logger    |
+| `usePluginContext()` | Full PluginUIContext | All of the above combined      |
+
+```tsx
+import { useShellAuth, useShellToast } from "@skyvexsoftware/stratos-sdk";
+
+function MyComponent() {
+  const { isAuthenticated } = useShellAuth();
+  const toast = useShellToast();
+
+  return (
+    <button onClick={() => toast.success("Hello!")}>
+      {isAuthenticated ? "Logged in" : "Not authenticated"}
+    </button>
+  );
+}
+```
+
+### UI Primitives
+
+Pre-styled shadcn/ui components using Tailwind CSS and Radix UI:
+
+```tsx
+import { Button, Card, CardContent, Input, Label } from "@skyvexsoftware/stratos-sdk";
+```
+
+Available components:
+
+- **Button** — with variants: default, destructive, outline, secondary, ghost, link
+- **Card** — CardHeader, CardTitle, CardDescription, CardAction, CardContent, CardFooter
+- **Dialog** — DialogTrigger, DialogContent, DialogHeader, DialogFooter, DialogTitle, DialogDescription
+- **Input** — text input with validation states
+- **Label** — form label
+- **Select** — SelectTrigger, SelectContent, SelectItem, SelectGroup, SelectValue
+- **Badge** — with variants: default, secondary, destructive, outline
+- **Separator** — horizontal or vertical divider
+- **Tabs** — TabsList, TabsTrigger, TabsContent
+- **Tooltip** — TooltipProvider, TooltipTrigger, TooltipContent
+
+### Shared Types
+
+Common types used across plugins:
+
+```ts
+import { FlightPhase, SimulatorType } from "@skyvexsoftware/stratos-sdk";
+import type { FlightData, ThemeMode } from "@skyvexsoftware/stratos-sdk";
+```
+
+### Utilities
+
+```ts
+import { cn } from "@skyvexsoftware/stratos-sdk";
+
+// Tailwind class merging utility
+cn("bg-red-500", conditional && "text-white", className);
+```
+
+## Peer Dependencies
+
+The SDK expects these to be provided by the shell at runtime:
+
+- `react` ^19.0.0
+- `@radix-ui/react-*` (dialog, label, select, separator, slot, tabs, tooltip)
+- `@tanstack/react-query` ^5.0.0
+- `class-variance-authority` ^0.7.0
+- `lucide-react` >=0.300.0
+- `socket.io-client` ^4.0.0
+
+## Publishing
+
+The SDK is published to npm as `@skyvexsoftware/stratos-sdk` directly from the monorepo.
+
+```bash
+pnpm build:sdk                                        # compile TypeScript to dist/
+pnpm --filter @skyvexsoftware/stratos-sdk publish      # publish to npm
+```
+
+The published package contains only the `dist/` folder (compiled JS + declaration files). Locally in the monorepo, pnpm's `workspace:*` protocol resolves to the source files via TypeScript project references.
+
+To inspect what would be published without actually publishing:
+
+```bash
+pnpm --filter @skyvexsoftware/stratos-sdk pack
+```

package/dist/helpers/createPlugin.d.ts

@@ -0,0 +1,22 @@
+import type { PluginBackgroundModule } from "../types/module";
+/**
+ * Validates and returns a typed plugin background module.
+ *
+ * Ensures the module exports the required onStart and onStop functions.
+ *
+ * @example
+ * ```ts
+ * import { createPlugin } from "@skyvexsoftware/stratos-sdk";
+ *
+ * export default createPlugin({
+ *   async onStart(ctx) {
+ *     ctx.logger.info("MyPlugin", "Starting up...");
+ *   },
+ *   async onStop() {
+ *     // cleanup
+ *   },
+ * });
+ * ```
+ */
+export declare function createPlugin(module: PluginBackgroundModule): PluginBackgroundModule;
+//# sourceMappingURL=createPlugin.d.ts.map

package/dist/helpers/createPlugin.js

@@ -0,0 +1,32 @@
+/**
+ * Validates and returns a typed plugin background module.
+ *
+ * Ensures the module exports the required onStart and onStop functions.
+ *
+ * @example
+ * ```ts
+ * import { createPlugin } from "@skyvexsoftware/stratos-sdk";
+ *
+ * export default createPlugin({
+ *   async onStart(ctx) {
+ *     ctx.logger.info("MyPlugin", "Starting up...");
+ *   },
+ *   async onStop() {
+ *     // cleanup
+ *   },
+ * });
+ * ```
+ */
+export function createPlugin(module) {
+    if (typeof module.onStart !== "function") {
+        throw new Error("Plugin module must export an onStart function");
+    }
+    if (typeof module.onStop !== "function") {
+        throw new Error("Plugin module must export an onStop function");
+    }
+    if (module.onResume !== undefined && typeof module.onResume !== "function") {
+        throw new Error("Plugin module onResume must be a function if provided");
+    }
+    return module;
+}
+//# sourceMappingURL=createPlugin.js.map

package/dist/helpers/index.d.ts

@@ -0,0 +1,4 @@
+export { createPlugin } from "./createPlugin";
+export { weightToLbs, weightFromLbs, altitudeToFt, altitudeFromFt, verticalSpeedFromFpm, verticalSpeedToFpm, distanceToNm, distanceFromNm, formatWeight, formatAltitude, formatDistance, formatVerticalSpeed, } from "./units";
+export type { WeightUnit, AltitudeUnit, DistanceUnit, UnitPreferences, } from "./units";
+//# sourceMappingURL=index.d.ts.map

package/dist/helpers/index.js

@@ -0,0 +1,3 @@
+export { createPlugin } from "./createPlugin";
+export { weightToLbs, weightFromLbs, altitudeToFt, altitudeFromFt, verticalSpeedFromFpm, verticalSpeedToFpm, distanceToNm, distanceFromNm, formatWeight, formatAltitude, formatDistance, formatVerticalSpeed, } from "./units";
+//# sourceMappingURL=index.js.map

package/dist/helpers/units.d.ts

@@ -0,0 +1,36 @@
+export type WeightUnit = "lbs" | "kg";
+export type AltitudeUnit = "ft" | "m";
+export type DistanceUnit = "nm" | "km" | "mi";
+export type UnitPreferences = {
+    weight: WeightUnit;
+    altitude: AltitudeUnit;
+    distance: DistanceUnit;
+};
+/** Convert a weight value FROM the given unit TO lbs (canonical). */
+export declare function weightToLbs(value: number, from: WeightUnit): number;
+/** Convert a weight value FROM lbs (canonical) TO the given unit. */
+export declare function weightFromLbs(lbs: number, to: WeightUnit): number;
+/** Convert an altitude value FROM the given unit TO ft (canonical). */
+export declare function altitudeToFt(value: number, from: AltitudeUnit): number;
+/** Convert an altitude value FROM ft (canonical) TO the given unit. */
+export declare function altitudeFromFt(ft: number, to: AltitudeUnit): number;
+/** Convert a vertical speed FROM fpm (canonical) TO the user's altitude unit per minute. */
+export declare function verticalSpeedFromFpm(fpm: number, to: AltitudeUnit): number;
+/** Convert a vertical speed FROM the user's altitude unit per minute TO fpm (canonical). */
+export declare function verticalSpeedToFpm(value: number, from: AltitudeUnit): number;
+/** Convert a distance value FROM the given unit TO nm (canonical). */
+export declare function distanceToNm(value: number, from: DistanceUnit): number;
+/** Convert a distance value FROM nm (canonical) TO the given unit. */
+export declare function distanceFromNm(nm: number, to: DistanceUnit): number;
+/** Format a weight (in lbs) for display in the user's preferred unit. */
+export declare function formatWeight(lbs: number, unit: WeightUnit): string;
+/** Format an altitude (in ft) for display in the user's preferred unit. */
+export declare function formatAltitude(ft: number, unit: AltitudeUnit): string;
+/** Format a distance (in nm) for display in the user's preferred unit. */
+export declare function formatDistance(nm: number, unit: DistanceUnit): string;
+/**
+ * Format a vertical speed / landing rate (in fpm) for display in the
+ * user's preferred altitude unit per minute.
+ */
+export declare function formatVerticalSpeed(fpm: number, unit: AltitudeUnit): string;
+//# sourceMappingURL=units.d.ts.map

package/dist/helpers/units.js

@@ -0,0 +1,101 @@
+// ── Conversion constants ───────────────────────────────────────────────
+const LBS_TO_KG = 0.45359237;
+const KG_TO_LBS = 1 / LBS_TO_KG;
+const FT_TO_M = 0.3048;
+const M_TO_FT = 1 / FT_TO_M;
+const NM_TO_KM = 1.852;
+const NM_TO_MI = 1.15078;
+const KM_TO_NM = 1 / NM_TO_KM;
+const MI_TO_NM = 1 / NM_TO_MI;
+// FPM ↔ m/min for vertical speed (landing rate)
+const FPM_TO_MPM = FT_TO_M;
+const MPM_TO_FPM = M_TO_FT;
+// ── Weight (canonical: lbs) ────────────────────────────────────────────
+/** Convert a weight value FROM the given unit TO lbs (canonical). */
+export function weightToLbs(value, from) {
+    if (from === "lbs")
+        return value;
+    return value * KG_TO_LBS;
+}
+/** Convert a weight value FROM lbs (canonical) TO the given unit. */
+export function weightFromLbs(lbs, to) {
+    if (to === "lbs")
+        return lbs;
+    return lbs * LBS_TO_KG;
+}
+// ── Altitude (canonical: ft) ───────────────────────────────────────────
+/** Convert an altitude value FROM the given unit TO ft (canonical). */
+export function altitudeToFt(value, from) {
+    if (from === "ft")
+        return value;
+    return value * M_TO_FT;
+}
+/** Convert an altitude value FROM ft (canonical) TO the given unit. */
+export function altitudeFromFt(ft, to) {
+    if (to === "ft")
+        return ft;
+    return ft * FT_TO_M;
+}
+// ── Vertical speed / landing rate (canonical: fpm) ─────────────────────
+/** Convert a vertical speed FROM fpm (canonical) TO the user's altitude unit per minute. */
+export function verticalSpeedFromFpm(fpm, to) {
+    if (to === "ft")
+        return fpm;
+    return fpm * FPM_TO_MPM;
+}
+/** Convert a vertical speed FROM the user's altitude unit per minute TO fpm (canonical). */
+export function verticalSpeedToFpm(value, from) {
+    if (from === "ft")
+        return value;
+    return value * MPM_TO_FPM;
+}
+// ── Distance (canonical: nm) ───────────────────────────────────────────
+/** Convert a distance value FROM the given unit TO nm (canonical). */
+export function distanceToNm(value, from) {
+    if (from === "nm")
+        return value;
+    if (from === "km")
+        return value * KM_TO_NM;
+    return value * MI_TO_NM;
+}
+/** Convert a distance value FROM nm (canonical) TO the given unit. */
+export function distanceFromNm(nm, to) {
+    if (to === "nm")
+        return nm;
+    if (to === "km")
+        return nm * NM_TO_KM;
+    return nm * NM_TO_MI;
+}
+// ── Display formatters ─────────────────────────────────────────────────
+/** Format a weight (in lbs) for display in the user's preferred unit. */
+export function formatWeight(lbs, unit) {
+    const value = weightFromLbs(lbs, unit);
+    return `${Math.round(value).toLocaleString()} ${unit}`;
+}
+/** Format an altitude (in ft) for display in the user's preferred unit. */
+export function formatAltitude(ft, unit) {
+    if (unit === "ft") {
+        const rounded = Math.round(ft);
+        if (rounded >= 18000)
+            return `FL${Math.round(rounded / 100)}`;
+        return `${rounded.toLocaleString()} ft`;
+    }
+    const meters = Math.round(altitudeFromFt(ft, "m"));
+    return `${meters.toLocaleString()} m`;
+}
+/** Format a distance (in nm) for display in the user's preferred unit. */
+export function formatDistance(nm, unit) {
+    const value = distanceFromNm(nm, unit);
+    return `${Math.round(value).toLocaleString()} ${unit}`;
+}
+/**
+ * Format a vertical speed / landing rate (in fpm) for display in the
+ * user's preferred altitude unit per minute.
+ */
+export function formatVerticalSpeed(fpm, unit) {
+    if (unit === "ft")
+        return `${Math.round(fpm).toLocaleString()} fpm`;
+    const mpm = verticalSpeedFromFpm(fpm, "m");
+    return `${Math.round(mpm).toLocaleString()} m/min`;
+}
+//# sourceMappingURL=units.js.map

package/dist/hooks/context.d.ts

@@ -0,0 +1,12 @@
+import type { PluginUIContext } from "../types/context";
+/**
+ * React context for plugin UI components.
+ * The shell provides this context via PluginShellProvider.
+ */
+export declare const PluginUICtx: import("react").Context<PluginUIContext | null>;
+/**
+ * Access the full plugin UI context.
+ * Must be used within a PluginShellProvider (provided by the shell).
+ */
+export declare function usePluginContext(): PluginUIContext;
+//# sourceMappingURL=context.d.ts.map

package/dist/hooks/context.js

@@ -0,0 +1,18 @@
+import { createContext, useContext } from "react";
+/**
+ * React context for plugin UI components.
+ * The shell provides this context via PluginShellProvider.
+ */
+export const PluginUICtx = createContext(null);
+/**
+ * Access the full plugin UI context.
+ * Must be used within a PluginShellProvider (provided by the shell).
+ */
+export function usePluginContext() {
+    const ctx = useContext(PluginUICtx);
+    if (!ctx) {
+        throw new Error("usePluginContext must be used within a PluginShellProvider");
+    }
+    return ctx;
+}
+//# sourceMappingURL=context.js.map

package/dist/hooks/index.d.ts

@@ -0,0 +1,16 @@
+export { PluginUICtx, usePluginContext } from "./context";
+export { useFlightEvents, flightEventsKeys } from "./useFlightEvents";
+export { useFlightManager } from "./useFlightManager";
+export { useFlightPhase, flightPhaseKeys } from "./useFlightPhase";
+export { useLandingAnalysis, landingAnalysisKeys } from "./useLandingAnalysis";
+export { useSimData, simDataKeys } from "./useSimData";
+export { useTrackingSession, trackingSessionKeys } from "./useTrackingSession";
+export { usePluginLogger } from "./usePluginLogger";
+export { useShellAuth } from "./useShellAuth";
+export { useShellConfig } from "./useShellConfig";
+export { useShellNavigation } from "./useShellNavigation";
+export { useShellToast } from "./useShellToast";
+export { useSocket, useSimulatorData, useProtocolUrl, useNotifications, useSystemMetrics, } from "./useSimulatorData";
+export { SOCKET_EVENTS } from "../shared-types/socket-events";
+export type { ConnectionState, NotificationPayload, ProtocolUrlPayload, SimulatorDataPayload, SimulatorStatusPayload, SocketEventName, SystemMetricsPayload, } from "../shared-types/socket-events";
+//# sourceMappingURL=index.d.ts.map

package/dist/hooks/index.js

@@ -0,0 +1,16 @@
+export { PluginUICtx, usePluginContext } from "./context";
+export { useFlightEvents, flightEventsKeys } from "./useFlightEvents";
+export { useFlightManager } from "./useFlightManager";
+export { useFlightPhase, flightPhaseKeys } from "./useFlightPhase";
+export { useLandingAnalysis, landingAnalysisKeys } from "./useLandingAnalysis";
+export { useSimData, simDataKeys } from "./useSimData";
+export { useTrackingSession, trackingSessionKeys } from "./useTrackingSession";
+export { usePluginLogger } from "./usePluginLogger";
+export { useShellAuth } from "./useShellAuth";
+export { useShellConfig } from "./useShellConfig";
+export { useShellNavigation } from "./useShellNavigation";
+export { useShellToast } from "./useShellToast";
+export { useSocket, useSimulatorData, useProtocolUrl, useNotifications, useSystemMetrics, } from "./useSimulatorData";
+// Socket.io event catalog — re-exported from shared-types for convenience
+export { SOCKET_EVENTS } from "../shared-types/socket-events";
+//# sourceMappingURL=index.js.map

package/dist/hooks/useFlightEvents.d.ts

@@ -0,0 +1,37 @@
+/**
+ * useFlightEvents — TanStack Query + Socket.io hook for flight event log.
+ *
+ * Hydrates from GET /api/flight-events on mount, then subscribes to
+ * flight:event Socket.io events to append new events to the query cache.
+ * Provides comment mutations with optimistic updates.
+ */
+import type { FlightLogEvent, EventCategory } from "../shared-types/simulator";
+export declare const flightEventsKeys: {
+    all: readonly ["flight-events"];
+    log: (flightId?: string | number | null) => readonly ["flight-events", "log", string | number];
+};
+type UseFlightEventsOptions = {
+    flightId?: string | number | null;
+    categories?: EventCategory[];
+};
+type UseFlightEventsReturn = {
+    events: FlightLogEvent[];
+    isTracking: boolean;
+    isLoading: boolean;
+    addComment: (message: string) => void;
+    editComment: (id: string, message: string) => void;
+    deleteComment: (id: string) => void;
+};
+/**
+ * Hook for the live flight event log using TanStack Query + Socket.io.
+ *
+ * On mount, fetches the current event log via REST.
+ * Then subscribes to flight:event Socket.io events and appends new events
+ * to the query cache as they arrive.
+ *
+ * Supports optional category filtering via the `categories` parameter.
+ * Comment mutations use optimistic updates and call the REST API.
+ */
+export declare function useFlightEvents(options?: UseFlightEventsOptions): UseFlightEventsReturn;
+export {};
+//# sourceMappingURL=useFlightEvents.d.ts.map