Metadata-Version: 2.3
Name: whitebox-plugin-location
Version: 0.1.12
Summary: A plugin for Whitebox that provides location utilities and extensions
License: GNU Affero General Public License v3
Author: Milos
Author-email: hello@klined.org
Requires-Python: >=3.14.0
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Description-Content-Type: text/markdown

# Whitebox Plugin - Location

This is a plugin for [whitebox](https://gitlab.com/whitebox-aero) that provides
location utilities and extensions.

## Installation

Simply install the plugin to whitebox:

```
poetry add whitebox-plugin-location
```

## Observed location

The `location.data` store exposes `lastObservedLocation`, one usable socket
observation seen by this page. It is page-lived, not persisted history or proof of
current GPS freshness. Loading or clearing flight history neither seeds nor clears
it. Consumers still apply their acquisition/status and playback rules; the map
does not require this provider just to mount.

See [state stores](https://docs.whitebox.aero/plugin_guide/#using-state-stores)
for access and [offline preparation](https://docs.whitebox.aero/development_guide/#prepared-offline-environments)
for shared setup.

### Flight history hydration contract

History/latest HTTP rows and newly produced `observation.location.update` payloads
carry the persisted sample's `id` as a decimal string, including above JavaScript's
safe integer range. This is not the socket event's `eid`. Coordinates or timestamps
are not identity: distinct samples at the same place/time must survive. Location
timestamps use UTC ISO with six fractional digits; history orders by timestamp,
then sample ID for exact ties. The handler stamps time before awaiting persistence,
so commit order can differ from sample order: HTTP may include later B while earlier
A is still uncommitted. Appending unmatched live points would put A after B.

`fetchLocationDataForFlightSession(flightSession, mode = "flight")` merges HTTP
rows with arrivals during that request; HTTP wins duplicate string IDs. Live
insertions and same-flight/same-mode pending refetches use the same reconciliation.
Only pending arrivals inherit, not a previously settled snapshot. Another flight,
another mode or `clear()` invalidates the pending record. Failing/non-array HTTP
leaves visible arrivals intact. Ownership retires before publication, so synchronous
subscribers can start newer work without old cleanup erasing it. Publication errors
propagate rather than clearing history as an HTTP failure.

`addPosition(point, owner)` accepts an optional `{ sessionId, mode }` owner (string
session ID); the service supplies it and preserves sample metadata. An explicit
owner mismatch cannot enter another history. Without an owner it appends to the
current history, preserving the existing one-argument API. No active history owner
also permits ordinary append. `clear()` clears history, not the last observation.

Legacy missing/invalid/numeric IDs remain separate occurrences; there is no old-event
backfill or exactly-once promise. Legacy valid timestamps have native-Date
millisecond ordering; unusable/out-of-four-digit-year times follow timed points in
source order. Corrected timestamps retain microsecond ordering, but playback still
uses its existing millisecond clock. The socket's coordinate-only throttle is
unchanged and may suppress stationary samples. Reconciliation covers received
observations, not every persisted row or proof of their selected-flight membership.

## Additional Instructions

- [Plugin Development Guide](https://docs.whitebox.aero/plugin_guide/#plugin-development-workflow)
- [Plugin Testing Guide](https://docs.whitebox.aero/plugin_guide/#testing-plugins)
- [Contributing Guidelines](https://docs.whitebox.aero/development_guide/#contributing)

