npm package: @skyvexsoftware/stratos-sdk
Description: Plugin SDK for Stratos — types, hooks, and UI components
Author: Skyvex Software
Latest version: 0.5.8

# @skyvexsoftware/stratos-sdk

The Stratos Plugin SDK provides typed access to shell APIs, shared UI components, and utility functions for building Stratos plugins.

## Installation

```bash
pnpm add @skyvexsoftware/stratos-sdk
```

## Getting Started

Scaffold a new plugin project:

```bash
pnpx create-stratos-plugin
```

This generates a ready-to-develop plugin with Tailwind CSS, TypeScript, and Vite preconfigured.

### Development

1. Open the Stratos app with `--dev` flag
2. In your plugin directory, run:

```bash
pnpm dev
```

Your plugin auto-connects to the running Stratos app and appears in the sidebar. Code changes auto-reload.

### Project Structure

```
my-plugin/
├── plugin.json           # Plugin manifest (name, version, author, settings)
├── package.json
├── vite.config.ts        # Uses createPluginConfig from SDK
├── tsconfig.json
├── src/
│   ├── ui/
│   │   ├── index.tsx     # UI entry (default export: React component)
│   │   └── global.css    # Tailwind CSS
│   └── background/       # Optional: main process module
│       └── index.ts      # export default createPlugin({...})
└── assets/
    ├── icon-light.svg    # Sidebar icon (dark theme)
    └── icon-dark.svg     # Sidebar icon (light theme)
```

### Building

```bash
pnpm build                # Build for distribution
```

Produces `dist/` with bundled UI, background module (if any), manifest, and assets. Zip and upload to the Skyvex website.

## Vite Config

The SDK provides `createPluginConfig` which handles bundling, externals, dev server auto-connect, and asset copying:

```ts
import { createPluginConfig } from "@skyvexsoftware/stratos-sdk/vite";
import tailwindcss from "@tailwindcss/vite";

export default createPluginConfig({
  ui: { entry: "src/ui/index.tsx" },
  background: { entry: "src/background/index.ts" }, // optional
  vite: {
    plugins: [tailwindcss()],
  },
});
```

The `vite` option accepts any Vite config to merge in (plugins, resolve, css, etc.).

## Plugin Manifest

`plugin.json` defines your plugin's metadata. Background modules don't need manifest configuration — the shell discovers them automatically if `background/index.js` exists in the built output.

```json
{
  "$schema": "https://cdn.skyvexsoftware.com/schemas/stratos-plugin.json",
  "id": "my-plugin",
  "type": "airline",
  "name": "My Plugin",
  "version": "0.1.0",
  "description": "A Stratos plugin",
  "author": { "id": "my-org", "name": "My Organisation" },
  "icon_light": "icon-light.svg",
  "icon_dark": "icon-dark.svg"
}
```

- `type`: `"airline"` (scoped to a virtual airline) or `"user"` (user-installed)
- `availableSettings`: Optional array of setting definitions (boolean, text, number, list, etc.)

## API Reference

### UI Context

Access shell services from plugin components:

```tsx
import { usePluginContext } from "@skyvexsoftware/stratos-sdk";

function MyComponent() {
  const {
    pluginId,
    auth,        // { isAuthenticated, token, user }
    airline,     // { id, name, icao, logo_light, logo_dark }
    config,      // { get(key, defaultValue?) } — airline-scoped settings
    navigation,  // { navigateTo, navigateToPlugin, navigateToShell }
    toast,       // { success, error, info, warning }
    logger,      // { info, warn, error, debug }
  } = usePluginContext();
}
```

Individual hooks are also available:

| Hook                   | Description                                    |
| ---------------------- | ---------------------------------------------- |
| `usePluginContext()`   | All shell services combined                    |
| `useSimData()`         | Real-time simulator data (RAF-throttled)       |
| `useFlightPhase()`     | Current flight phase with selector support     |
| `useFlightEvents()`    | Flight event log with comment mutations        |
| `useFlightManager()`   | Low-level flight lifecycle control             |
| `useTrackingSession()` | High-level tracking state with derived fields  |
| `useLandingAnalysis()` | Landing rate, bounces, and settled analysis    |
| `useShellAuth()`       | Authentication state and token                 |
| `useShellConfig()`     | Scoped configuration access                    |
| `useShellNavigation()` | Route navigation utilities                     |
| `useShellToast()`      | Toast/notification functions                   |
| `usePluginLogger()`    | Scoped renderer-side logger                    |

### 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:

```ts
import { createPlugin } from "@skyvexsoftware/stratos-sdk/helpers";

export default createPlugin({
  async onStart(ctx) {
    // ctx.logger   — scoped logger
    // ctx.config   — per-plugin config store (async)
    // ctx.ipc      — IPC handler registration
    // ctx.auth     — read-only auth token access (async)
    // ctx.server   — Express router registration
    // ctx.database — SQLite database access
    ctx.logger.info("MyPlugin", "Started");
  },
  async onStop(ctx) {
    ctx.logger.info("MyPlugin", "Stopped");
  },
});
```

Named exports are not supported — the shell requires the `createPlugin` default export pattern for type safety and validation.

### UI Components

Pre-styled shadcn/ui components that match the Stratos design system:

```tsx
import { Button, Card, CardContent, Input, Dialog } from "@skyvexsoftware/stratos-sdk";
```

Available: Button, Card, Dialog, Input, Label, Select, Badge, Separator, Tabs, Tooltip, AlertDialog, RadioGroup, Slider, Switch, Textarea.

### Icons

The full [Lucide](https://lucide.dev) icon set is available via `STRATOS_ICONS`:

```tsx
import { STRATOS_ICONS, STRATOS_ICON_NAMES } from "@skyvexsoftware/stratos-sdk";

const Icon = STRATOS_ICONS["Helicopter"];
```

Or import icons directly from `lucide-react` in your plugin.

### Types

```ts
import { FlightPhase, EventCategory } from "@skyvexsoftware/stratos-sdk";
import type { FlightData, PluginManifest, PluginContext } from "@skyvexsoftware/stratos-sdk";
```

### Utilities

```ts
// Tailwind class merging
import { cn } from "@skyvexsoftware/stratos-sdk";
cn("bg-red-500", isActive && "text-white", className);

// Unit conversion helpers
import { weightFromLbs, formatAltitude } from "@skyvexsoftware/stratos-sdk/helpers";
```

## Documentation

Full documentation is available at [docs.skyvexsoftware.com](https://docs.skyvexsoftware.com).

## Licence

MIT