@skyvexsoftware/stratos-sdk 0.1.1

package/dist/hooks/useFlightEvents.js

@@ -0,0 +1,152 @@
+/**
+ * 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 { useEffect, useMemo } from "react";
+import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { useSocket } from "./useSimulatorData";
+import { SOCKET_EVENTS } from "../shared-types/socket-events";
+const SERVER_PORT = 2066;
+const API_BASE = `http://127.0.0.1:${SERVER_PORT}`;
+export const flightEventsKeys = {
+    all: ["flight-events"],
+    log: (flightId) => [...flightEventsKeys.all, "log", flightId ?? "current"],
+};
+async function fetchFlightEvents() {
+    const response = await fetch(`${API_BASE}/api/flight-events`, {
+        headers: { Accept: "application/json" },
+    });
+    const json = (await response.json());
+    return json.data;
+}
+/**
+ * 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 function useFlightEvents(options) {
+    const queryClient = useQueryClient();
+    const { socket } = useSocket();
+    const queryKey = flightEventsKeys.log(options?.flightId);
+    const { data, isLoading } = useQuery({
+        queryKey,
+        queryFn: fetchFlightEvents,
+        staleTime: Infinity,
+        refetchOnWindowFocus: false,
+        refetchOnReconnect: false,
+    });
+    // Subscribe to Socket.io events and append new events to the cache
+    useEffect(() => {
+        if (!socket)
+            return;
+        const handleEvent = (payload) => {
+            queryClient.setQueryData(queryKey, (prev) => {
+                if (!prev)
+                    return prev;
+                return {
+                    ...prev,
+                    events: [...prev.events, payload.event],
+                };
+            });
+        };
+        socket.on(SOCKET_EVENTS.FLIGHT_EVENT, handleEvent);
+        return () => {
+            socket.off(SOCKET_EVENTS.FLIGHT_EVENT, handleEvent);
+        };
+    }, [socket, queryClient, options?.flightId]);
+    // ── Comment Mutations ──────────────────────────────────────────────
+    const addCommentMutation = useMutation({
+        mutationFn: async (message) => {
+            const response = await fetch(`${API_BASE}/api/flight-events/comments`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ message }),
+            });
+            const json = (await response.json());
+            return json.data.event;
+        },
+        // No optimistic update for add — the Socket.io flight:event broadcast
+        // will append the new comment event to the cache automatically
+    });
+    const editCommentMutation = useMutation({
+        mutationFn: async ({ id, message }) => {
+            await fetch(`${API_BASE}/api/flight-events/comments/${id}`, {
+                method: "PUT",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({ message }),
+            });
+        },
+        onMutate: async ({ id, message }) => {
+            // Optimistically update the comment in the cache
+            await queryClient.cancelQueries({ queryKey: queryKey });
+            const previous = queryClient.getQueryData(queryKey);
+            queryClient.setQueryData(queryKey, (prev) => {
+                if (!prev)
+                    return prev;
+                return {
+                    ...prev,
+                    events: prev.events.map((e) => e.eventId === id ? { ...e, message } : e),
+                };
+            });
+            return { previous };
+        },
+        onError: (_err, _vars, context) => {
+            // Rollback on error
+            if (context?.previous) {
+                queryClient.setQueryData(queryKey, context.previous);
+            }
+        },
+    });
+    const deleteCommentMutation = useMutation({
+        mutationFn: async (id) => {
+            await fetch(`${API_BASE}/api/flight-events/comments/${id}`, {
+                method: "DELETE",
+            });
+        },
+        onMutate: async (id) => {
+            // Optimistically remove the comment from the cache
+            await queryClient.cancelQueries({ queryKey: queryKey });
+            const previous = queryClient.getQueryData(queryKey);
+            queryClient.setQueryData(queryKey, (prev) => {
+                if (!prev)
+                    return prev;
+                return {
+                    ...prev,
+                    events: prev.events.filter((e) => e.eventId !== id),
+                };
+            });
+            return { previous };
+        },
+        onError: (_err, _vars, context) => {
+            // Rollback on error
+            if (context?.previous) {
+                queryClient.setQueryData(queryKey, context.previous);
+            }
+        },
+    });
+    // Apply category filter if provided
+    const events = useMemo(() => {
+        const allEvents = data?.events ?? [];
+        if (!options?.categories || options.categories.length === 0) {
+            return allEvents;
+        }
+        return allEvents.filter((e) => options.categories.includes(e.category));
+    }, [data?.events, options?.categories]);
+    return {
+        events,
+        isTracking: data?.isTracking ?? false,
+        isLoading,
+        addComment: (message) => addCommentMutation.mutate(message),
+        editComment: (id, message) => editCommentMutation.mutate({ id, message }),
+        deleteComment: (id) => deleteCommentMutation.mutate(id),
+    };
+}
+//# sourceMappingURL=useFlightEvents.js.map

package/dist/hooks/useFlightManager.d.ts

@@ -0,0 +1,20 @@
+/**
+ * useFlightManager — React hook for the shell's FlightManager service.
+ *
+ * Subscribes to `flight:manager` Socket.io events for reactive state.
+ * Hydrates initial state from GET /api/flight-manager/state on mount.
+ * Action methods call REST endpoints to control the flight lifecycle.
+ */
+import type { CurrentFlight, FlightPlan, StartFlightResult, PreflightCheckResult } from "../shared-types/flight-manager";
+type UseFlightManagerReturn = {
+    currentFlight: CurrentFlight | null;
+    startFlight: (plan: FlightPlan) => Promise<StartFlightResult>;
+    pauseFlight: () => Promise<boolean>;
+    resumeFlight: () => Promise<boolean>;
+    endFlight: (status?: "completed" | "diverted" | "crashed" | "cancelled") => Promise<boolean>;
+    addComment: (message: string) => Promise<boolean>;
+    runPreflightChecks: (plan: FlightPlan) => Promise<PreflightCheckResult | null>;
+};
+export declare function useFlightManager(): UseFlightManagerReturn;
+export {};
+//# sourceMappingURL=useFlightManager.d.ts.map

package/dist/hooks/useFlightManager.js

@@ -0,0 +1,90 @@
+/**
+ * useFlightManager — React hook for the shell's FlightManager service.
+ *
+ * Subscribes to `flight:manager` Socket.io events for reactive state.
+ * Hydrates initial state from GET /api/flight-manager/state on mount.
+ * Action methods call REST endpoints to control the flight lifecycle.
+ */
+import { useEffect, useState, useCallback } from "react";
+import { useSocket } from "./useSimulatorData";
+import { SOCKET_EVENTS } from "../shared-types/socket-events";
+const SERVER_PORT = 2066;
+const API_BASE = `http://127.0.0.1:${SERVER_PORT}/api/flight-manager`;
+async function api(path, method = "GET", body) {
+    const response = await fetch(`${API_BASE}${path}`, {
+        method,
+        headers: { "Content-Type": "application/json", Accept: "application/json" },
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    return (await response.json());
+}
+export function useFlightManager() {
+    const { socket } = useSocket();
+    const [currentFlight, setCurrentFlight] = useState(null);
+    // Hydrate on mount
+    useEffect(() => {
+        api("/state")
+            .then((res) => {
+            if (res.success)
+                setCurrentFlight(res.data);
+        })
+            .catch(() => {
+            // Server may not be ready yet
+        });
+    }, []);
+    // Subscribe to Socket.io events
+    useEffect(() => {
+        if (!socket)
+            return;
+        const handleEvent = (payload) => {
+            setCurrentFlight(payload.flight);
+        };
+        socket.on(SOCKET_EVENTS.FLIGHT_MANAGER, handleEvent);
+        return () => {
+            socket.off(SOCKET_EVENTS.FLIGHT_MANAGER, handleEvent);
+        };
+    }, [socket]);
+    const startFlight = useCallback(async (plan) => {
+        const result = await api("/start", "POST", { flightPlan: plan });
+        return result.data;
+    }, []);
+    const pauseFlight = useCallback(async () => {
+        const result = await api("/pause", "POST");
+        return result.success;
+    }, []);
+    const resumeFlight = useCallback(async () => {
+        const result = await api("/resume", "POST");
+        return result.success;
+    }, []);
+    const endFlight = useCallback(async (status) => {
+        const result = await api("/end", "POST", {
+            status,
+        });
+        return result.success;
+    }, []);
+    const addComment = useCallback(async (message) => {
+        const result = await api("/comment", "POST", {
+            message,
+        });
+        return result.success;
+    }, []);
+    const runPreflightChecks = useCallback(async (plan) => {
+        try {
+            const result = await api("/preflight", "POST", { flightPlan: plan });
+            return result.success ? result.data : null;
+        }
+        catch {
+            return null;
+        }
+    }, []);
+    return {
+        currentFlight,
+        startFlight,
+        pauseFlight,
+        resumeFlight,
+        endFlight,
+        addComment,
+        runPreflightChecks,
+    };
+}
+//# sourceMappingURL=useFlightManager.js.map

package/dist/hooks/useFlightPhase.d.ts

@@ -0,0 +1,31 @@
+/**
+ * useFlightPhase — TanStack Query + Socket.io hook for flight phase tracking.
+ *
+ * Hydrates from GET /api/simulator/flight-phase/snapshot on mount, then
+ * subscribes to flight:phase Socket.io events for real-time phase updates.
+ * Only re-renders when the phase actually changes, not on every data tick.
+ */
+import type { FlightPhaseSnapshot } from "../shared-types/simulator";
+export declare const flightPhaseKeys: {
+    snapshot: readonly ["flight-phase", "snapshot"];
+};
+type UseFlightPhaseOptions<TSelected = FlightPhaseSnapshot> = {
+    select?: (snapshot: FlightPhaseSnapshot) => TSelected;
+};
+type UseFlightPhaseReturn<TSelected = FlightPhaseSnapshot> = {
+    data: TSelected;
+    isLoading: boolean;
+};
+/**
+ * Hook for real-time flight phase tracking using TanStack Query + Socket.io.
+ *
+ * On mount, fetches the current phase state via REST.
+ * Then subscribes to flight:phase Socket.io events and updates the query cache
+ * only when the phase actually changes — not on every data tick.
+ *
+ * Supports an optional `select` parameter to subscribe to specific fields
+ * and only re-render when those fields change.
+ */
+export declare function useFlightPhase<TSelected = FlightPhaseSnapshot>(options?: UseFlightPhaseOptions<TSelected>): UseFlightPhaseReturn<TSelected>;
+export {};
+//# sourceMappingURL=useFlightPhase.d.ts.map

package/dist/hooks/useFlightPhase.js

@@ -0,0 +1,67 @@
+/**
+ * useFlightPhase — TanStack Query + Socket.io hook for flight phase tracking.
+ *
+ * Hydrates from GET /api/simulator/flight-phase/snapshot on mount, then
+ * subscribes to flight:phase Socket.io events for real-time phase updates.
+ * Only re-renders when the phase actually changes, not on every data tick.
+ */
+import { useEffect } from "react";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { useSocket } from "./useSimulatorData";
+import { SOCKET_EVENTS } from "../shared-types/socket-events";
+const SERVER_PORT = 2066;
+const API_BASE = `http://127.0.0.1:${SERVER_PORT}`;
+export const flightPhaseKeys = {
+    snapshot: ["flight-phase", "snapshot"],
+};
+async function fetchPhaseSnapshot() {
+    const response = await fetch(`${API_BASE}/api/simulator/flight-phase/snapshot`, {
+        headers: { Accept: "application/json" },
+    });
+    const json = (await response.json());
+    return json.data;
+}
+/**
+ * Hook for real-time flight phase tracking using TanStack Query + Socket.io.
+ *
+ * On mount, fetches the current phase state via REST.
+ * Then subscribes to flight:phase Socket.io events and updates the query cache
+ * only when the phase actually changes — not on every data tick.
+ *
+ * Supports an optional `select` parameter to subscribe to specific fields
+ * and only re-render when those fields change.
+ */
+export function useFlightPhase(options) {
+    const queryClient = useQueryClient();
+    const { socket } = useSocket();
+    const { data, isLoading } = useQuery({
+        queryKey: flightPhaseKeys.snapshot,
+        queryFn: fetchPhaseSnapshot,
+        select: options?.select,
+        staleTime: Infinity,
+        refetchOnWindowFocus: false,
+        refetchOnReconnect: false,
+    });
+    useEffect(() => {
+        if (!socket)
+            return;
+        const handlePhaseChange = (payload) => {
+            queryClient.setQueryData(flightPhaseKeys.snapshot, (prev) => ({
+                currentPhase: payload.currentPhase,
+                previousPhase: payload.previousPhase,
+                pendingTransition: payload.pendingTransition ?? null,
+                trends: prev?.trends ?? null,
+                isTracking: prev?.isTracking ?? false,
+            }));
+        };
+        socket.on(SOCKET_EVENTS.FLIGHT_PHASE, handlePhaseChange);
+        return () => {
+            socket.off(SOCKET_EVENTS.FLIGHT_PHASE, handlePhaseChange);
+        };
+    }, [socket, queryClient]);
+    return {
+        data: data,
+        isLoading,
+    };
+}
+//# sourceMappingURL=useFlightPhase.js.map

package/dist/hooks/useLandingAnalysis.d.ts

@@ -0,0 +1,37 @@
+/**
+ * useLandingAnalysis — TanStack Query + Socket.io hook for landing analysis.
+ *
+ * Hydrates from GET /api/simulator/landing-analysis/snapshot on mount, then
+ * subscribes to flight:landing Socket.io events for real-time touchdown/bounce
+ * notifications. Only re-renders when landing-relevant events occur.
+ */
+import type { LandingAnalysisSnapshot, CapturePoint, BounceData, LandingAnalysis } from "../shared-types/simulator";
+export declare const landingAnalysisKeys: {
+    snapshot: readonly ["landing-analysis", "snapshot"];
+};
+type UseLandingAnalysisOptions<TSelected = LandingAnalysisSnapshot> = {
+    select?: (snapshot: LandingAnalysisSnapshot) => TSelected;
+};
+type UseLandingAnalysisReturn = {
+    landingRate: number | null;
+    bounceCount: number;
+    touchdowns: BounceData[];
+    isOnGround: boolean;
+    approachData: CapturePoint | null;
+    landingAnalysis: LandingAnalysis | null;
+    isLoading: boolean;
+};
+/**
+ * Hook for real-time landing analysis using TanStack Query + Socket.io.
+ *
+ * On mount, fetches the current landing state via REST.
+ * Then subscribes to flight:landing Socket.io events and updates the query
+ * cache when touchdown, bounce, or settled events arrive.
+ *
+ * Only updates when landing-relevant events occur (not every data tick).
+ * Data resets when a new flight starts (LandingAnalyzer.reset() is called
+ * by FlightEventPipeline.startTracking()).
+ */
+export declare function useLandingAnalysis<TSelected = LandingAnalysisSnapshot>(options?: UseLandingAnalysisOptions<TSelected>): UseLandingAnalysisReturn;
+export {};
+//# sourceMappingURL=useLandingAnalysis.d.ts.map

package/dist/hooks/useLandingAnalysis.js

@@ -0,0 +1,87 @@
+/**
+ * useLandingAnalysis — TanStack Query + Socket.io hook for landing analysis.
+ *
+ * Hydrates from GET /api/simulator/landing-analysis/snapshot on mount, then
+ * subscribes to flight:landing Socket.io events for real-time touchdown/bounce
+ * notifications. Only re-renders when landing-relevant events occur.
+ */
+import { useEffect } from "react";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { useSocket } from "./useSimulatorData";
+import { SOCKET_EVENTS } from "../shared-types/socket-events";
+const SERVER_PORT = 2066;
+const API_BASE = `http://127.0.0.1:${SERVER_PORT}`;
+export const landingAnalysisKeys = {
+    snapshot: ["landing-analysis", "snapshot"],
+};
+async function fetchLandingSnapshot() {
+    const response = await fetch(`${API_BASE}/api/simulator/landing-analysis/snapshot`, {
+        headers: { Accept: "application/json" },
+    });
+    const json = (await response.json());
+    return json.data;
+}
+/**
+ * Hook for real-time landing analysis using TanStack Query + Socket.io.
+ *
+ * On mount, fetches the current landing state via REST.
+ * Then subscribes to flight:landing Socket.io events and updates the query
+ * cache when touchdown, bounce, or settled events arrive.
+ *
+ * Only updates when landing-relevant events occur (not every data tick).
+ * Data resets when a new flight starts (LandingAnalyzer.reset() is called
+ * by FlightEventPipeline.startTracking()).
+ */
+export function useLandingAnalysis(options) {
+    const queryClient = useQueryClient();
+    const { socket } = useSocket();
+    const { data, isLoading } = useQuery({
+        queryKey: landingAnalysisKeys.snapshot,
+        queryFn: fetchLandingSnapshot,
+        select: options?.select,
+        staleTime: Infinity,
+        refetchOnWindowFocus: false,
+        refetchOnReconnect: false,
+    });
+    useEffect(() => {
+        if (!socket)
+            return;
+        const handleLanding = (payload) => {
+            queryClient.setQueryData(landingAnalysisKeys.snapshot, (prev) => {
+                if (!prev)
+                    return prev;
+                if (payload.type === "settled" && payload.landingAnalysis) {
+                    return {
+                        ...prev,
+                        landingRate: payload.landingAnalysis.landingRateFpm,
+                        bounceCount: payload.landingAnalysis.bounceCount,
+                        touchdowns: payload.landingAnalysis.bounces,
+                        landingAnalysis: payload.landingAnalysis,
+                    };
+                }
+                if (payload.type === "bounce" && payload.bounceData) {
+                    return {
+                        ...prev,
+                        bounceCount: prev.bounceCount + 1,
+                        touchdowns: [...prev.touchdowns, payload.bounceData],
+                    };
+                }
+                return prev;
+            });
+        };
+        socket.on(SOCKET_EVENTS.FLIGHT_LANDING, handleLanding);
+        return () => {
+            socket.off(SOCKET_EVENTS.FLIGHT_LANDING, handleLanding);
+        };
+    }, [socket, queryClient]);
+    return {
+        landingRate: data?.landingRate ?? null,
+        bounceCount: data?.bounceCount ?? 0,
+        touchdowns: data?.touchdowns ?? [],
+        isOnGround: data?.isOnGround ?? true,
+        approachData: data?.approachData ?? null,
+        landingAnalysis: data?.landingAnalysis ?? null,
+        isLoading,
+    };
+}
+//# sourceMappingURL=useLandingAnalysis.js.map

package/dist/hooks/usePluginLogger.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Access a scoped logger from a plugin component.
+ * Logs are sent to the shell's logging infrastructure.
+ *
+ * @example
+ * ```tsx
+ * const logger = usePluginLogger();
+ * logger.info("TrackingPage", "User opened flight map");
+ * logger.error("TrackingPage", "Failed to load route", error);
+ * ```
+ */
+export declare function usePluginLogger(): import("..").PluginLogger;
+//# sourceMappingURL=usePluginLogger.d.ts.map

package/dist/hooks/usePluginLogger.js

@@ -0,0 +1,16 @@
+import { usePluginContext } from "./context";
+/**
+ * Access a scoped logger from a plugin component.
+ * Logs are sent to the shell's logging infrastructure.
+ *
+ * @example
+ * ```tsx
+ * const logger = usePluginLogger();
+ * logger.info("TrackingPage", "User opened flight map");
+ * logger.error("TrackingPage", "Failed to load route", error);
+ * ```
+ */
+export function usePluginLogger() {
+    return usePluginContext().logger;
+}
+//# sourceMappingURL=usePluginLogger.js.map

package/dist/hooks/useShellAuth.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Access the shell's auth state from a plugin component.
+ *
+ * @example
+ * ```tsx
+ * const { isAuthenticated, token, user } = useShellAuth();
+ * ```
+ */
+export declare function useShellAuth(): {
+    isAuthenticated: boolean;
+    token: string | null;
+    user: unknown;
+};
+//# sourceMappingURL=useShellAuth.d.ts.map

package/dist/hooks/useShellAuth.js

@@ -0,0 +1,13 @@
+import { usePluginContext } from "./context";
+/**
+ * Access the shell's auth state from a plugin component.
+ *
+ * @example
+ * ```tsx
+ * const { isAuthenticated, token, user } = useShellAuth();
+ * ```
+ */
+export function useShellAuth() {
+    return usePluginContext().auth;
+}
+//# sourceMappingURL=useShellAuth.js.map

package/dist/hooks/useShellConfig.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Access the shell's config store from a plugin component.
+ *
+ * @example
+ * ```tsx
+ * const config = useShellConfig();
+ * const value = config.get<string>("myKey", "default");
+ * ```
+ */
+export declare function useShellConfig(): {
+    get<T>(key: string): T | undefined;
+    get<T>(key: string, defaultValue: T): T;
+};
+//# sourceMappingURL=useShellConfig.d.ts.map

package/dist/hooks/useShellConfig.js

@@ -0,0 +1,14 @@
+import { usePluginContext } from "./context";
+/**
+ * Access the shell's config store from a plugin component.
+ *
+ * @example
+ * ```tsx
+ * const config = useShellConfig();
+ * const value = config.get<string>("myKey", "default");
+ * ```
+ */
+export function useShellConfig() {
+    return usePluginContext().config;
+}
+//# sourceMappingURL=useShellConfig.js.map

package/dist/hooks/useShellNavigation.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Access the shell's navigation helpers from a plugin component.
+ *
+ * @example
+ * ```tsx
+ * const nav = useShellNavigation();
+ * nav.navigateTo("settings");
+ * nav.navigateToPlugin("flight-tracking", "history");
+ * ```
+ */
+export declare function useShellNavigation(): import("..").PluginNavigationHelper;
+//# sourceMappingURL=useShellNavigation.d.ts.map

package/dist/hooks/useShellNavigation.js

@@ -0,0 +1,15 @@
+import { usePluginContext } from "./context";
+/**
+ * Access the shell's navigation helpers from a plugin component.
+ *
+ * @example
+ * ```tsx
+ * const nav = useShellNavigation();
+ * nav.navigateTo("settings");
+ * nav.navigateToPlugin("flight-tracking", "history");
+ * ```
+ */
+export function useShellNavigation() {
+    return usePluginContext().navigation;
+}
+//# sourceMappingURL=useShellNavigation.js.map

package/dist/hooks/useShellToast.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Access the shell's toast/notification API from a plugin component.
+ *
+ * @example
+ * ```tsx
+ * const toast = useShellToast();
+ * toast.success("Flight saved!");
+ * toast.error("Connection lost");
+ * ```
+ */
+export declare function useShellToast(): import("..").PluginToastAPI;
+//# sourceMappingURL=useShellToast.d.ts.map

package/dist/hooks/useShellToast.js

@@ -0,0 +1,15 @@
+import { usePluginContext } from "./context";
+/**
+ * Access the shell's toast/notification API from a plugin component.
+ *
+ * @example
+ * ```tsx
+ * const toast = useShellToast();
+ * toast.success("Flight saved!");
+ * toast.error("Connection lost");
+ * ```
+ */
+export function useShellToast() {
+    return usePluginContext().toast;
+}
+//# sourceMappingURL=useShellToast.js.map