@skyvexsoftware/stratos-sdk 0.7.7 → 0.8.0

package/README.md

@@ -130,11 +130,31 @@ Individual hooks are also available:
 | `useTrackingSession()` | High-level tracking state with derived fields  |
 | `useLandingAnalysis()` | Landing rate, bounces, and settled analysis    |
 | `useShellAuth()`       | Authentication state and token                 |
+| `useVaApi()`           | Shared axios instance for the bound VA's API   |
 | `useShellConfig()`     | Scoped configuration access                    |
 | `useShellNavigation()` | Route navigation utilities                     |
 | `useShellToast()`      | Toast/notification functions                   |
 | `usePluginLogger()`    | Scoped renderer-side logger                    |
 
+### VA API client
+
+For HTTP calls to the bound airline's API, use `useVaApi()` (renderer) or `ctx.airline.createClient()` (background). Both return an [axios](https://axios-http.com/) instance that the shell pre-configures with the airline's `base_url`, the pilot's bearer token, and a `401` → refresh → retry interceptor:
+
+```tsx
+import { useVaApi } from "@skyvexsoftware/stratos-sdk";
+
+const va = useVaApi();
+const { data } = await va.get("/pilot/verify");
+```
+
+The renderer-side instance is provided by `PluginShellProvider` and **shared across the shell and every plugin UI** — concurrent `401`s coalesce onto a single refresh roundtrip rather than each plugin firing its own.
+
+#### About the axios dependency
+
+`axios` is a regular dependency of this SDK, so plugins **don't need to declare it** in their own `package.json` if they only consume it through `useVaApi()` / `ctx.airline.createClient()`. The plugin's bundle won't ship its own copy either — the shell's instance is reused at runtime through the plugin context.
+
+Only add `axios` to your plugin's deps if you import it directly — for example to call `axios.isAxiosError(err)` for narrowing or to build your own custom instance. If you do, pin the same major version as the SDK to avoid runtime surprises.
+
 ### Background Module
 
 Optional main-process code with access to IPC, Express routes, SQLite, and more. Must use the `createPlugin` helper (imported from the `/helpers` subpath) with a default export:

package/dist/api/vaApi.d.ts

@@ -0,0 +1,33 @@
+/**
+ * VA API client — singleton axios instance for plugins to call the bound
+ * airline's API. Transparently refreshes the access token on 401.
+ *
+ * Usage from a plugin component:
+ *
+ *   import { useVaApi } from "@skyvexsoftware/stratos-sdk";
+ *
+ *   const va = useVaApi();
+ *   const profile = await va.get<{ pilotID: string }>("/pilot/verify");
+ *
+ * Refresh behaviour:
+ *   - On 401 we ask the shell to refresh (POST /api/auth/va/refresh).
+ *   - If refresh succeeds, the request is retried exactly once.
+ *   - If refresh fails or the VA isn't configured for refresh, the 401
+ *     surfaces to the caller and the shell's existing re-auth flow takes
+ *     over (the auth state will flip on the next /api/auth poll).
+ *
+ * The token and baseURL are pulled from the local shell server on every
+ * request, so plugins don't need to subscribe to auth changes — the
+ * latest token is always used.
+ *
+ * Concurrency: a single in-flight refresh promise is shared across all
+ * callers of this client. Concurrent 401s coalesce onto the same refresh,
+ * and outbound requests issued while a refresh is running wait for it to
+ * settle before reading the bearer — otherwise they'd send the stale token
+ * and get a redundant 401.
+ */
+import { AxiosInstance } from "axios";
+/** Singleton axios instance for VA API calls with auto-refresh on 401. */
+export declare const vaApi: AxiosInstance;
+export default vaApi;
+//# sourceMappingURL=vaApi.d.ts.map

package/dist/api/vaApi.js

@@ -0,0 +1,107 @@
+/**
+ * VA API client — singleton axios instance for plugins to call the bound
+ * airline's API. Transparently refreshes the access token on 401.
+ *
+ * Usage from a plugin component:
+ *
+ *   import { useVaApi } from "@skyvexsoftware/stratos-sdk";
+ *
+ *   const va = useVaApi();
+ *   const profile = await va.get<{ pilotID: string }>("/pilot/verify");
+ *
+ * Refresh behaviour:
+ *   - On 401 we ask the shell to refresh (POST /api/auth/va/refresh).
+ *   - If refresh succeeds, the request is retried exactly once.
+ *   - If refresh fails or the VA isn't configured for refresh, the 401
+ *     surfaces to the caller and the shell's existing re-auth flow takes
+ *     over (the auth state will flip on the next /api/auth poll).
+ *
+ * The token and baseURL are pulled from the local shell server on every
+ * request, so plugins don't need to subscribe to auth changes — the
+ * latest token is always used.
+ *
+ * Concurrency: a single in-flight refresh promise is shared across all
+ * callers of this client. Concurrent 401s coalesce onto the same refresh,
+ * and outbound requests issued while a refresh is running wait for it to
+ * settle before reading the bearer — otherwise they'd send the stale token
+ * and get a redundant 401.
+ */
+import axios from "axios";
+import { STRATOS_APP_BASE } from "../helpers/server";
+const SHELL_API = `${STRATOS_APP_BASE}/api`;
+async function readAuth() {
+    try {
+        const res = await axios.get(`${SHELL_API}/auth`);
+        return {
+            vaBaseUrl: res.data.data?.vaBaseUrl ?? null,
+            vaToken: res.data.data?.vaToken ?? null,
+        };
+    }
+    catch {
+        return { vaBaseUrl: null, vaToken: null };
+    }
+}
+let refreshInflight = null;
+function ensureRefresh() {
+    if (refreshInflight)
+        return refreshInflight;
+    refreshInflight = (async () => {
+        try {
+            const res = await axios.post(`${SHELL_API}/auth/va/refresh`);
+            return !!res.data.refreshed;
+        }
+        catch {
+            return false;
+        }
+    })().finally(() => {
+        refreshInflight = null;
+    });
+    return refreshInflight;
+}
+class VaApiClient {
+    constructor() {
+        this.axiosInstance = axios.create({
+            timeout: 15000,
+            headers: {
+                "Content-Type": "application/json",
+                Accept: "application/json",
+            },
+        });
+        this.axiosInstance.interceptors.request.use(async (config) => {
+            // Wait for any in-flight refresh so we read the post-refresh bearer
+            // instead of racing the write.
+            if (refreshInflight)
+                await refreshInflight;
+            const auth = await readAuth();
+            if (auth.vaBaseUrl)
+                config.baseURL = auth.vaBaseUrl;
+            if (auth.vaToken)
+                config.headers.Authorization = `Bearer ${auth.vaToken}`;
+            return config;
+        });
+        this.axiosInstance.interceptors.response.use((response) => response, async (error) => {
+            const original = error.config;
+            if (error.response?.status !== 401 ||
+                !original ||
+                original.__vaRetried) {
+                return Promise.reject(error);
+            }
+            original.__vaRetried = true;
+            const refreshed = await ensureRefresh();
+            if (!refreshed)
+                return Promise.reject(error);
+            return await this.axiosInstance.request(original);
+        });
+    }
+    static getInstance() {
+        if (!VaApiClient.instance)
+            VaApiClient.instance = new VaApiClient();
+        return VaApiClient.instance;
+    }
+    get axios() {
+        return this.axiosInstance;
+    }
+}
+/** Singleton axios instance for VA API calls with auto-refresh on 401. */
+export const vaApi = VaApiClient.getInstance().axios;
+export default vaApi;

package/dist/hooks/index.d.ts

@@ -7,6 +7,7 @@ export { useSimData, simDataKeys } from "./useSimData";
 export { useTrackingSession, trackingSessionKeys } from "./useTrackingSession";
 export { usePluginLogger } from "./usePluginLogger";
 export { useShellAuth } from "./useShellAuth";
+export { useVaApi } from "./useVaApi";
 export { useShellConfig } from "./useShellConfig";
 export { useShellNavigation } from "./useShellNavigation";
 export { useShellToast } from "./useShellToast";

package/dist/hooks/index.js

@@ -7,6 +7,7 @@ export { useSimData, simDataKeys } from "./useSimData";
 export { useTrackingSession, trackingSessionKeys } from "./useTrackingSession";
 export { usePluginLogger } from "./usePluginLogger";
 export { useShellAuth } from "./useShellAuth";
+export { useVaApi } from "./useVaApi";
 export { useShellConfig } from "./useShellConfig";
 export { useShellNavigation } from "./useShellNavigation";
 export { useShellToast } from "./useShellToast";

package/dist/hooks/useVaApi.d.ts

@@ -0,0 +1,27 @@
+import type { AxiosInstance } from "axios";
+/**
+ * Returns the shared axios instance for the bound airline's API.
+ *
+ * The shell provides a single instance through PluginShellProvider so all
+ * plugin UIs (and the shell itself) coalesce concurrent 401s onto one
+ * refresh — the in-flight refresh promise lives on the shared instance,
+ * so a 401 in plugin A and plugin B at the same time fires exactly one
+ * `POST /api/auth/va/refresh`.
+ *
+ * Behaviour (set up by the shell):
+ *   - baseURL is the airline's base_url (resolved per request).
+ *   - Authorization is the current pilot's VA bearer.
+ *   - On 401, the shell refreshes the access token at the VA's refresh URL.
+ *     Success → request retried once. Failure → 401 propagates and the
+ *     shell's existing re-auth flow takes over.
+ *
+ * Must be used inside a PluginShellProvider tree. For non-React callers
+ * (helpers, services, tests), import the standalone `vaApi` export instead.
+ *
+ * Example:
+ *
+ *   const va = useVaApi();
+ *   const { data } = await va.get<{ pilotID: string }>("/pilot/verify");
+ */
+export declare function useVaApi(): AxiosInstance;
+//# sourceMappingURL=useVaApi.d.ts.map

package/dist/hooks/useVaApi.js

@@ -0,0 +1,28 @@
+import { usePluginContext } from "./context";
+/**
+ * Returns the shared axios instance for the bound airline's API.
+ *
+ * The shell provides a single instance through PluginShellProvider so all
+ * plugin UIs (and the shell itself) coalesce concurrent 401s onto one
+ * refresh — the in-flight refresh promise lives on the shared instance,
+ * so a 401 in plugin A and plugin B at the same time fires exactly one
+ * `POST /api/auth/va/refresh`.
+ *
+ * Behaviour (set up by the shell):
+ *   - baseURL is the airline's base_url (resolved per request).
+ *   - Authorization is the current pilot's VA bearer.
+ *   - On 401, the shell refreshes the access token at the VA's refresh URL.
+ *     Success → request retried once. Failure → 401 propagates and the
+ *     shell's existing re-auth flow takes over.
+ *
+ * Must be used inside a PluginShellProvider tree. For non-React callers
+ * (helpers, services, tests), import the standalone `vaApi` export instead.
+ *
+ * Example:
+ *
+ *   const va = useVaApi();
+ *   const { data } = await va.get<{ pilotID: string }>("/pilot/verify");
+ */
+export function useVaApi() {
+    return usePluginContext().vaApi;
+}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export type { PluginAuthor, PluginManifest } from "./types/manifest";
-export type { PluginAirline, PluginAirlineAccessor, PluginAuthAccessor, 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, 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, HistoryReportEntry, LandingAnalysis, LandingAnalysisSnapshot, LandingAnalyzerDebugState, LandingSample, PendingPhaseTransition, SimDataSnapshot, SimulatorStatus, } from "./shared-types/simulator";
@@ -7,6 +7,7 @@ export type { ThemeMode } from "./shared-types/theme";
 export type { FlightPlan, FlightStatus, CurrentFlight, FlightComment, PreflightCheck, PreflightCheckResult, StartFlightOptions, FlightManagerPayload, StartFlightResult, RecoverableFlight, } from "./shared-types/flight-manager";
 export { createPlugin } from "./helpers/createPlugin";
 export { STRATOS_APP_PORT, STRATOS_APP_BASE } from "./helpers/server";
+export { vaApi } from "./api/vaApi";
 export { weightToLbs, weightFromLbs, altitudeToFt, altitudeFromFt, verticalSpeedFromFpm, verticalSpeedToFpm, distanceToNm, distanceFromNm, formatWeight, formatAltitude, formatDistance, formatVerticalSpeed, } from "./helpers/units";
 export type { WeightUnit, AltitudeUnit, DistanceUnit, UnitPreferences, } from "./helpers/units";
 export { PluginUICtx, usePluginContext } from "./hooks/context";
@@ -18,6 +19,7 @@ export { useSimData, simDataKeys } from "./hooks/useSimData";
 export { useTrackingSession, trackingSessionKeys, } from "./hooks/useTrackingSession";
 export { usePluginLogger } from "./hooks/usePluginLogger";
 export { useShellAuth } from "./hooks/useShellAuth";
+export { useVaApi } from "./hooks/useVaApi";
 export { useShellConfig } from "./hooks/useShellConfig";
 export { useShellNavigation } from "./hooks/useShellNavigation";
 export { useShellToast } from "./hooks/useShellToast";

package/dist/index.js

@@ -3,6 +3,7 @@ export { FlightPhase, SimulatorType, EventCategory, } from "./shared-types/simul
 // ── Helper Functions ───────────────────────────────────────────────────
 export { createPlugin } from "./helpers/createPlugin";
 export { STRATOS_APP_PORT, STRATOS_APP_BASE } from "./helpers/server";
+export { vaApi } from "./api/vaApi";
 export { weightToLbs, weightFromLbs, altitudeToFt, altitudeFromFt, verticalSpeedFromFpm, verticalSpeedToFpm, distanceToNm, distanceFromNm, formatWeight, formatAltitude, formatDistance, formatVerticalSpeed, } from "./helpers/units";
 // ── React Hooks ────────────────────────────────────────────────────────
 export { PluginUICtx, usePluginContext } from "./hooks/context";
@@ -14,6 +15,7 @@ export { useSimData, simDataKeys } from "./hooks/useSimData";
 export { useTrackingSession, trackingSessionKeys, } from "./hooks/useTrackingSession";
 export { usePluginLogger } from "./hooks/usePluginLogger";
 export { useShellAuth } from "./hooks/useShellAuth";
+export { useVaApi } from "./hooks/useVaApi";
 export { useShellConfig } from "./hooks/useShellConfig";
 export { useShellNavigation } from "./hooks/useShellNavigation";
 export { useShellToast } from "./hooks/useShellToast";

package/dist/types/context.d.ts

@@ -4,6 +4,7 @@
  * Defines the context objects the shell provides to plugins
  * for both background (main process) and UI (renderer) usage.
  */
+import type { AxiosInstance } from "axios";
 /** All supported setting control types */
 export type PluginSettingType = "boolean" | "text" | "longtext" | "number" | "range" | "list" | "radio" | "date" | "json";
 /** Option entry for list and radio settings */
@@ -129,10 +130,32 @@ export type PluginAirline = {
     /** Bearer for this airline's API. Null if the VA session has expired. */
     token: string | null;
 };
+/**
+ * Pre-configured axios instance for the bound airline's API.
+ *
+ * - baseURL is the airline's base_url
+ * - Authorization header is the current VA bearer (resolved per-request)
+ * - On 401, the shell refreshes the VA access token if a refresh URL is
+ *   configured, then retries the request exactly once. If refresh fails
+ *   or isn't supported, the 401 surfaces to the caller.
+ *
+ * Use this instead of raw fetch(`${airline.baseUrl}/...`) so plugins get
+ * refresh-token handling for free.
+ *
+ * Aliased here for clarity at the plugin contract surface — at runtime
+ * this is the same shape as an axios `AxiosInstance`.
+ */
+export type PluginVaApiClient = AxiosInstance;
 /** Read-only accessor for the currently-bound airline. */
 export type PluginAirlineAccessor = {
     /** Returns the current airline, or null if no VA session is active. */
     getCurrent(): Promise<PluginAirline | null>;
+    /**
+     * Returns an axios instance pre-configured for this airline's API
+     * with auto-refresh on 401. Safe to cache for the lifetime of the
+     * background module.
+     */
+    createClient(): PluginVaApiClient;
 };
 /** Express route registration helper for background plugins */
 export type PluginServerRegistrar = {
@@ -203,6 +226,13 @@ export type PluginToastAPI = {
  * 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 */
@@ -229,7 +259,19 @@ export type PluginUIContext = {
         get<T>(key: string): T | undefined;
         get<T>(key: string, defaultValue: T): T;
     };
-    /** Socket/real-time connection state */
+    /**
+     * 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;

package/dist/ui/button.d.ts

@@ -1,14 +1,14 @@
 import * as React from "react";
 import { type VariantProps } from "class-variance-authority";
 declare const buttonVariants: (props?: ({
-    variant?: "default" | "destructive" | "outline" | "secondary" | "ghost" | "link" | "pill-pause" | "pill-resume" | "pill-end" | "pill-submit" | null | undefined;
+    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;
 export type ButtonProps = React.ButtonHTMLAttributes<HTMLButtonElement> & VariantProps<typeof buttonVariants> & {
     asChild?: boolean;
 };
 declare const Button: React.ForwardRefExoticComponent<React.ButtonHTMLAttributes<HTMLButtonElement> & VariantProps<(props?: ({
-    variant?: "default" | "destructive" | "outline" | "secondary" | "ghost" | "link" | "pill-pause" | "pill-resume" | "pill-end" | "pill-submit" | null | undefined;
+    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> & {
     asChild?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyvexsoftware/stratos-sdk",
-  "version": "0.7.7",
+  "version": "0.8.0",
   "description": "Plugin SDK for Stratos — types, hooks, and UI components",
   "author": {
     "name": "Skyvex Software Pty Ltd",
@@ -94,7 +94,7 @@
     "@radix-ui/react-switch": "^1.2.0",
     "@radix-ui/react-tabs": "^1.1.0",
     "@radix-ui/react-tooltip": "^1.1.0",
-    "@tanstack/react-query": "^5.0.0",
+    "@tanstack/react-query": "^5.99.0",
     "@vitejs/plugin-react": "^5.0.0",
     "class-variance-authority": "^0.7.0",
     "lucide-react": ">=0.300.0",
@@ -103,6 +103,7 @@
     "vite": "^7.0.0"
   },
   "dependencies": {
+    "axios": "^1.15.0",
     "clsx": "^2.1.1",
     "magic-string": "^0.30.21",
     "tailwind-merge": "^3.2.0"