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

# useFlightEvents

> Access flight events and manage comments.

`useFlightEvents` provides access to the live flight event log. It hydrates from `GET /api/flight-events` on mount, then subscribes to `flight:event` Socket.io events to append new events as they arrive. Comment mutations (add, edit, delete) use optimistic updates.

## Import

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

## Signature

```ts theme={null}
function useFlightEvents(
  options?: UseFlightEventsOptions
): UseFlightEventsReturn

type UseFlightEventsOptions = {
  flightId?: string | number | null;
  categories?: EventCategory[];
};

type UseFlightEventsReturn = {
  events: FlightLogEvent[];
  isTracking: boolean;
  isLoading: boolean;
  addComment: (message: string) => void;
  editComment: (id: string, message: string) => void;
  deleteComment: (id: string) => void;
};
```

## Parameters

| Parameter            | Type                       | Description                                                                |
| -------------------- | -------------------------- | -------------------------------------------------------------------------- |
| `options.flightId`   | `string \| number \| null` | Filter events to a specific flight. Defaults to the current active flight. |
| `options.categories` | `EventCategory[]`          | Filter events by category. If omitted, all categories are returned.        |

## Return value

| Field           | Type                                    | Description                                                            |
| --------------- | --------------------------------------- | ---------------------------------------------------------------------- |
| `events`        | `FlightLogEvent[]`                      | Ordered array of flight events (filtered if `categories` was provided) |
| `isTracking`    | `boolean`                               | Whether a flight is currently active                                   |
| `isLoading`     | `boolean`                               | True during the initial REST fetch                                     |
| `addComment`    | `(message: string) => void`             | Add a pilot comment event to the current flight                        |
| `editComment`   | `(id: string, message: string) => void` | Edit an existing comment (optimistic update)                           |
| `deleteComment` | `(id: string) => void`                  | Delete a comment (optimistic update)                                   |

## `FlightLogEvent`

See [`FlightLogEvent`](/sdk/type-reference#flightlogevent) for the full shape.

## `EventCategory` enum

See [`EventCategory`](/sdk/type-reference#eventcategory) for all values.

## Usage

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

export function EventLog() {
  const { events, isLoading, addComment } = useFlightEvents();

  if (isLoading) return <p>Loading events...</p>;

  return (
    <div>
      <ul>
        {events.map((event) => (
          <li key={event.eventId}>
            [{event.category}] {event.message}
          </li>
        ))}
      </ul>
      <button onClick={() => addComment("Cruising at FL350")}>
        Add Comment
      </button>
    </div>
  );
}
```

### Filtering by category

```tsx theme={null}
import { useFlightEvents, EventCategory } from "@skyvexsoftware/stratos-sdk";

// Show only phase transitions and warnings
const { events } = useFlightEvents({
  categories: [EventCategory.PHASE, EventCategory.WARNING],
});
```

### Editing and deleting comments

```tsx theme={null}
const { events, editComment, deleteComment } = useFlightEvents();

const commentEvents = events.filter((e) => e.category === EventCategory.COMMENT);

commentEvents.forEach((event) => {
  // Edit: fires a PUT to /api/flight-events/comments/:id with optimistic update
  editComment(event.eventId, "Updated message");

  // Delete: fires a DELETE to /api/flight-events/comments/:id with optimistic removal
  deleteComment(event.eventId);
});
```

## Notes

* New events arriving via Socket.io are appended to the end of the `events` array without invalidating or refetching the full query.
* `addComment` does **not** use an optimistic update — the new comment event arrives via the `flight:event` Socket.io broadcast and is appended automatically.
* `editComment` and `deleteComment` apply optimistic updates immediately and roll back on API error.
* The `staleTime: Infinity` setting means events are never automatically re-fetched in the background.