> ## Documentation Index
> Fetch the complete documentation index at: https://docs.skyvexsoftware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# useTrackingSession

> High-level flight tracking state and controls.

`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`](/sdk/hooks/use-flight-manager) only when you need the raw `CurrentFlight` object without derived fields, or want to avoid the extra effect for the elapsed timer.

## Import

```ts theme={null}
import { useTrackingSession } from "@skyvexsoftware/stratos-sdk";
```

## Signature

```ts theme={null}
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`](/sdk/type-reference#recoverableflight) for the full shape.

## Usage

### Basic tracking display

```tsx theme={null}
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

```tsx theme={null}
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

```tsx theme={null}
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.