@skyvexsoftware/stratos-sdk 0.17.0 → 0.19.1

package/dist/helpers/attach-file.d.ts

@@ -0,0 +1,23 @@
+import type { PluginFileAttachment } from "../types/context";
+/**
+ * Mark a file on disk for attachment to the PIREP.
+ *
+ * This only records the path. It doesn't open or read the file, so it never
+ * throws and never slows the handler. Stratos reads the file later, when the
+ * PIREP is sent, streaming it from disk. A file that can't be read at that
+ * point is skipped with the reason recorded, and the flight still files.
+ *
+ * @example
+ * ```ts
+ * ctx.flight.attachToPirepSubmission(async (sub) => {
+ *   const receipts = await groundOps.receiptsFor(sub.flightId);
+ *   if (!receipts.length) return null;
+ *   return { receipts: receipts.map((r) => attachFile(r.path)) };
+ * });
+ * ```
+ */
+export declare function attachFile(path: string, opts?: {
+    filename?: string;
+    contentType?: string;
+}): PluginFileAttachment;
+//# sourceMappingURL=attach-file.d.ts.map

package/dist/helpers/attach-file.js

@@ -0,0 +1,27 @@
+/**
+ * Mark a file on disk for attachment to the PIREP.
+ *
+ * This only records the path. It doesn't open or read the file, so it never
+ * throws and never slows the handler. Stratos reads the file later, when the
+ * PIREP is sent, streaming it from disk. A file that can't be read at that
+ * point is skipped with the reason recorded, and the flight still files.
+ *
+ * @example
+ * ```ts
+ * ctx.flight.attachToPirepSubmission(async (sub) => {
+ *   const receipts = await groundOps.receiptsFor(sub.flightId);
+ *   if (!receipts.length) return null;
+ *   return { receipts: receipts.map((r) => attachFile(r.path)) };
+ * });
+ * ```
+ */
+export function attachFile(path, opts) {
+    return {
+        __stratosFile: true,
+        path,
+        ...(opts?.filename !== undefined ? { filename: opts.filename } : {}),
+        ...(opts?.contentType !== undefined
+            ? { contentType: opts.contentType }
+            : {}),
+    };
+}

package/dist/helpers/index.d.ts

@@ -1,4 +1,5 @@
 export { createPlugin } from "./createPlugin";
+export { attachFile } from "./attach-file";
 export { STRATOS_APP_PORT, STRATOS_APP_BASE } from "./server";
 export { weightToLbs, weightFromLbs, altitudeToFt, altitudeFromFt, verticalSpeedFromFpm, verticalSpeedToFpm, distanceToNm, distanceFromNm, formatWeight, formatAltitude, formatDistance, formatVerticalSpeed, } from "./units";
 export type { WeightUnit, AltitudeUnit, DistanceUnit, UnitPreferences, } from "./units";

package/dist/helpers/index.js

@@ -1,4 +1,5 @@
 export { createPlugin } from "./createPlugin";
+export { attachFile } from "./attach-file";
 export { STRATOS_APP_PORT, STRATOS_APP_BASE } from "./server";
 export { weightToLbs, weightFromLbs, altitudeToFt, altitudeFromFt, verticalSpeedFromFpm, verticalSpeedToFpm, distanceToNm, distanceFromNm, formatWeight, formatAltitude, formatDistance, formatVerticalSpeed, } from "./units";
 export { classifyAircraft } from "./aircraft";

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export type { PluginAuthor, PluginManifest } from "./types/manifest";
-export type { PluginAirline, PluginAirlineAccessor, PluginAuthAccessor, PluginVaApiClient, PluginConfigStore, PluginContext, PluginDatabaseAccessor, PluginIPCRegistrar, PluginLogger, PluginServerRegistrar, PluginFlightAccessor, PluginFlightLogWriter, PluginFlightLogInput, PluginFlightLogPatch, PluginStartGuard, PluginStartContext, PluginStartDecision, PluginNotifier, PluginToastInput, BuiltInSound, PluginAlertSound, PluginDialogApi, PluginPromptApi, PluginDialogAlertInput, PluginDialogConfirmInput, PluginPromptTextInput, PluginPromptNumberInput, PluginPromptSelectInput, PluginIndicatorType, PluginIndicatorInput, PluginSelfApi, } from "./types/context";
+export type { PluginAirline, PluginAirlineAccessor, PluginAuthAccessor, PluginVaApiClient, PluginConfigStore, PluginContext, PluginDatabaseAccessor, PluginIPCRegistrar, PluginLogger, PluginServerRegistrar, PluginFlightAccessor, PluginFlightLogWriter, PluginFlightLogInput, PluginFlightLogPatch, PluginStartGuard, PluginStartContext, PluginStartDecision, PluginPirepSubmissionContext, PluginPirepAttachment, PluginPirepAttachHandler, PluginFileAttachment, PluginNotifier, PluginToastInput, BuiltInSound, PluginAlertSound, PluginDialogApi, PluginPromptApi, PluginDialogAlertInput, PluginDialogConfirmInput, PluginPromptTextInput, PluginPromptNumberInput, PluginPromptSelectInput, PluginIndicatorType, PluginIndicatorInput, PluginSelfApi, } from "./types/context";
 export type { PluginNavigationHelper, PluginPilotUser, PluginToastAPI, PluginUIContext, } from "./types/context-ui";
 export type { PluginSettingType, PluginSettingOption, PluginSettingDefinition, PluginAvailableSettings, BooleanSettingDef, TextSettingDef, LongtextSettingDef, NumberSettingDef, RangeSettingDef, ListSettingDef, RadioSettingDef, DateSettingDef, JsonSettingDef, } from "./types/settings";
 export type { PluginBackgroundModule, PluginRouteComponent, PluginUIModule, } from "./types/module";
@@ -13,6 +13,7 @@ export { ADDITIONAL_FIELD_PHASES, toPhaseKey, } from "./shared-types/additional-
 export type { AdditionalFieldsConfig, FieldDelivery, } from "./shared-types/additional-fields";
 export type { FlightPlan, FlightStatus, CurrentFlight, FlightComment, PreflightCheck, PreflightCheckResult, StartFlightOptions, FlightManagerPayload, StartFlightResult, RecoverableFlight, } from "./shared-types/flight-manager";
 export { createPlugin } from "./helpers/createPlugin";
+export { attachFile } from "./helpers/attach-file";
 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";

package/dist/index.js

@@ -4,6 +4,7 @@ export { EventCategory } from "./shared-types/flight-events";
 export { ADDITIONAL_FIELD_PHASES, toPhaseKey, } from "./shared-types/additional-fields";
 // ── Helper Functions ───────────────────────────────────────────────────
 export { createPlugin } from "./helpers/createPlugin";
+export { attachFile } from "./helpers/attach-file";
 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";

package/dist/types/context.d.ts

@@ -162,6 +162,29 @@ export type PluginFlightAccessor = {
      * Multiple guards: the first `allow: false` wins. Returns an unsubscribe.
      */
     registerStartGuard(guard: PluginStartGuard): () => void;
+    /**
+     * Register a handler consulted while the airline PIREP is assembled, after
+     * every milestone capture and immediately before the body is posted.
+     * Whatever it returns is attached to the submission under
+     * `plugin_data["<your-plugin-id>"]`. Return null or undefined to attach
+     * nothing.
+     *
+     * Handlers are fail-open: a throw, a rejection, a timeout (3s), a
+     * non-object return, or returned data over the size cap omits this plugin's
+     * key and the PIREP is submitted regardless. The cap is 256 KB per plugin
+     * and 512 KB across all plugins, measured on the returned JSON. Files
+     * attached with `attachFile()` do not count towards it; each is only a
+     * short reference in the JSON and is sent as its own part, with no size
+     * limit.
+     *
+     * Handlers run only for `completed`, `diverted` and `crashed` flights, never
+     * for cancelled ones, and only when an airline is bound. If the airline
+     * rejects the PIREP the pilot can retry, which runs every handler again, so
+     * a handler must be idempotent and free of side effects. Registering more
+     * than one handler is allowed; their results are shallow-merged under the
+     * single plugin key. Returns an unsubscribe.
+     */
+    attachToPirepSubmission(handler: PluginPirepAttachHandler): () => void;
 };
 /** Context handed to a start guard. */
 export type PluginStartContext = {
@@ -178,6 +201,49 @@ export type PluginStartDecision = {
 };
 /** Guard run inside `startFlight` before the flight is created/persisted. */
 export type PluginStartGuard = (ctx: PluginStartContext) => PluginStartDecision | Promise<PluginStartDecision>;
+/**
+ * Context handed to a PIREP submission attachment handler.
+ * Describes the PIREP that is about to be filed with the airline.
+ */
+export type PluginPirepSubmissionContext = {
+    /** Local (core DB) flight id. */
+    flightId: string;
+    /** Skyvex flight UUID, or null if the flight was never relayed. */
+    stratosFlightId: string | null;
+    /** VA tracking id for the PIREP being filed. */
+    vaTrackingId: string;
+    /** Terminal status being filed. Cancelled flights never reach a handler. */
+    status: "completed" | "diverted" | "crashed";
+    /** The flight plan being filed. */
+    plan: FlightPlan;
+    /** Last simulator snapshot, or null when no sim is connected. */
+    snapshot: SimDataSnapshot | null;
+};
+/**
+ * Data to attach to the PIREP. Returning null or undefined (a bare `return;`
+ * included) attaches nothing for this flight.
+ */
+export type PluginPirepAttachment = Record<string, unknown> | null | undefined;
+/** Handler registered through `ctx.flight.attachToPirepSubmission`. */
+export type PluginPirepAttachHandler = (ctx: PluginPirepSubmissionContext) => PluginPirepAttachment | Promise<PluginPirepAttachment>;
+/**
+ * A file to attach to the PIREP, produced by `attachFile()`. Place one anywhere
+ * inside the object your handler returns; the shell lifts it out into its own
+ * part of a multipart submission and leaves a reference in its place.
+ *
+ * Carries a `__stratosFile` discriminator rather than relying on object
+ * identity, because attachments are JSON round-tripped before the shell walks
+ * them.
+ */
+export type PluginFileAttachment = {
+    readonly __stratosFile: true;
+    /** Absolute path to the file on disk. */
+    path: string;
+    /** Name sent to the airline. Defaults to the basename of `path`. */
+    filename?: string;
+    /** MIME type. Defaults to a lookup on the extension, else application/octet-stream. */
+    contentType?: string;
+};
 /**
  * Toast + sound surface. Backs `ctx.notify`.
  *

package/dist/types/index.d.ts

@@ -1,5 +1,5 @@
 export type { PluginAuthor, PluginManifest } from "./manifest";
-export type { PluginAirline, PluginAirlineAccessor, PluginAuthAccessor, PluginConfigStore, PluginContext, PluginDatabaseAccessor, PluginIPCRegistrar, PluginLogger, PluginServerRegistrar, PluginFlightAccessor, PluginFlightLogWriter, PluginFlightLogInput, PluginFlightLogPatch, PluginStartGuard, PluginStartContext, PluginStartDecision, PluginNotifier, PluginToastInput, BuiltInSound, PluginAlertSound, } from "./context";
+export type { PluginAirline, PluginAirlineAccessor, PluginAuthAccessor, PluginConfigStore, PluginContext, PluginDatabaseAccessor, PluginIPCRegistrar, PluginLogger, PluginServerRegistrar, PluginFlightAccessor, PluginFlightLogWriter, PluginFlightLogInput, PluginFlightLogPatch, PluginStartGuard, PluginStartContext, PluginStartDecision, PluginPirepSubmissionContext, PluginPirepAttachment, PluginPirepAttachHandler, PluginFileAttachment, PluginNotifier, PluginToastInput, BuiltInSound, 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

@@ -44,5 +44,7 @@ export type PluginManifest = {
     availableSettings?: PluginSettingDefinition[];
     /** Whether to include source maps in the published CDN bundle. Defaults to false — source maps are stripped on approval. Set to true if you want end users to have access to source maps for debugging. */
     includeSourceMaps?: boolean;
+    /** Advisory: this plugin attaches files to the PIREP, which changes how flight submissions are encoded for the airline. Surfaced as a warning in the airline's plugin list; the shell does not enforce it. */
+    attachesFilesToPirep?: boolean;
 };
 //# sourceMappingURL=manifest.d.ts.map

package/package.json

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