useTrackingSession

useTrackingSession is the recommended entry point for tracking-aware plugins. It provides derived tracking state — isTracking, isPaused, elapsedTime (ticking locally every second), phase — alongside flight lifecycle controls and crash recovery handling. Use this hook when your plugin needs to know whether a flight is active or wants to show elapsed time. Fall back to useFlightManager only when you need the raw CurrentFlight object without derived fields, or want to avoid the extra effect for the elapsed timer.

Import

import { useTrackingSession } from "@skyvexsoftware/stratos-sdk";

Signature

function useTrackingSession(): UseTrackingSessionReturn

type UseTrackingSessionReturn = {
  isTracking: boolean;
  isPaused: boolean;
  currentFlight: CurrentFlight | null;
  pendingRecovery: RecoverableFlight | null;
  elapsedTime: number;
  phase: FlightPhase;
  startFlight: (
    plan: FlightPlan,
    options?: { skipPreflightWarnings?: boolean; forceStart?: boolean }
  ) => Promise<StartFlightResult>;
  pauseFlight: () => Promise<boolean>;
  resumeFlight: () => Promise<boolean>;
  endFlight: (
    status?: "completed" | "diverted" | "crashed" | "cancelled"
  ) => Promise<{ success: boolean; error?: string }>;
  recoverFlight: () => Promise<boolean>;
  dismissRecovery: () => Promise<boolean>;
  isLoading: boolean;
};

Return value

Field	Type	Description
`isTracking`	`boolean`	`true` when a flight is active or paused
`isPaused`	`boolean`	`true` when the active flight is paused
`currentFlight`	`CurrentFlight \| null`	Full flight state object, or `null` when idle
`pendingRecovery`	`RecoverableFlight \| null`	A previous flight that can be recovered, if one exists
`elapsedTime`	`number`	Elapsed flight time in milliseconds, updating every second
`phase`	`FlightPhase`	Current flight phase (defaults to `FlightPhase.BOARDING` when idle)
`startFlight`	`Function`	Start a new flight; accepts optional start options
`pauseFlight`	`() => Promise<boolean>`	Pause the active flight
`resumeFlight`	`() => Promise<boolean>`	Resume a paused flight
`endFlight`	`(status?) => Promise<{ success, error? }>`	End the active flight
`recoverFlight`	`() => Promise<boolean>`	Recover a previously interrupted flight
`dismissRecovery`	`() => Promise<boolean>`	Dismiss the pending recovery prompt
`isLoading`	`boolean`	`true` during the initial REST hydration

`RecoverableFlight`

When Stratos detects a flight was interrupted (e.g. the app crashed mid-flight), pendingRecovery is populated with a lean summary of that flight. See RecoverableFlight for the full shape.

Usage

Basic tracking display

import { useTrackingSession, FlightPhase } from "@skyvexsoftware/stratos-sdk";

export function TrackingStatus() {
  const { isTracking, isPaused, phase, elapsedTime } = useTrackingSession();

  const formatTime = (ms: number) => {
    const h = Math.floor(ms / 3_600_000);
    const m = Math.floor((ms % 3_600_000) / 60_000);
    const s = Math.floor((ms % 60_000) / 1_000);
    return `${h}:${String(m).padStart(2, "0")}:${String(s).padStart(2, "0")}`;
  };

  if (!isTracking) return <p>No active flight</p>;

  return (
    <div>
      <p>Phase: {phase}</p>
      <p>Elapsed: {formatTime(elapsedTime)}</p>
      <p>{isPaused ? "Paused" : "Active"}</p>
    </div>
  );
}

Start a flight with options

const { startFlight } = useTrackingSession();

const result = await startFlight(
  {
    source: "simbrief",
    sourceId: "12345678",
    callsign: "QFA001",
    departureIcao: "YSSY",
    arrivalIcao: "EGLL",
    route: ["SY", "LL"],
    aircraftIcao: "A388",
  },
  { skipPreflightWarnings: false, forceStart: false },
);

if (result.vaConfirmation) {
  // Show VA confirmation dialog before the flight is fully registered
  console.log(result.vaConfirmation);
}

Recovery handling

const { pendingRecovery, recoverFlight, dismissRecovery } = useTrackingSession();

if (pendingRecovery) {
  return (
    <div>
      <p>Interrupted flight found: {pendingRecovery.callsign}</p>
      <button onClick={recoverFlight}>Recover</button>
      <button onClick={dismissRecovery}>Dismiss</button>
    </div>
  );
}

Notes

elapsedTime is computed locally via a 1-second setInterval so it ticks smoothly between server broadcasts (which occur every ~15 seconds).
The hook uses staleTime: Infinity and refetches on socket reconnect to catch flights started before the UI loaded.
The TanStack Query cache key is ["tracking-session", "state"] — this is the same key used across the shell and all plugins, ensuring consistent state with no duplicate requests.

Getting Started

Plugin Basics

UI Module

Background Module

Deploy

Type Reference

Import

Signature

Return value

`RecoverableFlight`

Usage

Basic tracking display

Start a flight with options

Recovery handling

Notes

​Import

​Signature

​Return value

​RecoverableFlight

​Usage

​Basic tracking display

​Start a flight with options

​Recovery handling

​Notes

Import

Signature

Return value

`RecoverableFlight`

Usage

Basic tracking display

Start a flight with options

Recovery handling

Notes