fleetpull 0.1.0__py3-none-any.whl

fleetpull/models/geotab/dvir_log.py

@@ -0,0 +1,184 @@
+# src/fleetpull/models/geotab/dvir_log.py
+"""GeoTab DVIRLog response model (``GetFeed`` on ``typeName: DVIRLog``).
+
+Written from the 2026-07-21 feed wave two census (30-day seeded pulls at
+the probed tenant), never from docs. A DVIRLog is one driver vehicle
+inspection report. The house class casing is ``DvirLog``; the wire
+``typeName`` stays ``'DVIRLog'`` (the binding's constant). DVIRs are
+certified and edited after creation, so re-emission under newer
+``version`` tokens is expected and the consumer reconciles by
+``(id, max version)`` (DESIGN §4).
+
+Requiredness posture (the wave-two conservative stance, DESIGN §8): the
+census is a TENANT-SCOPED observation (500 records), so structural
+requiredness is limited to the record identity — ``id``, ``dateTime``
+(the event time), ``version``, and the primary entity ref (``driver``,
+500/500; ``device`` is only 205/500 and could not be it) — and every
+other field is optional EVEN where the census was total. The observed
+arms and exclusions:
+
+- ``device`` is OPTIONAL and commonly absent (205/500 carriers) — a
+  plain wire fact of this census, recorded without speculation.
+  ``engineHours`` and ``odometer`` travel with it (205/500 each);
+  ``engineHours`` was int-only on its carriers, but its sibling
+  surface (``DutyStatusLog``) proved the same physical quantity MIXED
+  int-or-float, so it models ``float`` here too (cross-surface dtype
+  consistency over a thin single-surface census).
+- ``defectList`` is a WIRE-PLURAL NAME carrying ONE defect node
+  ``{children, id, name}``. The node models ``id`` + ``name`` ONLY:
+  ``children`` is EXCLUDED under the documented-exclusion doctrine —
+  an EMPTY list on every one of the 200 ``defectList`` nodes the
+  census sampled (the nested-block sample depth; ``defectList`` itself
+  was present 500/500), so its element shape is unobservable at this
+  tenant, and the records layer deliberately supports only observable
+  shapes; ``extra='ignore'`` absorbs it wire-side (a record with
+  populated children still validates — the pinned absorption test).
+  REVISIT when a tenant shows populated ``children``: capture the
+  element shape and model it then.
+- ``location`` (496/500) is the shared ``GeotabAddressedLocation``
+  wrapper (DutyStatusLog is the co-consumer; DESIGN §8): a
+  ``{location: {x, y}}`` coordinate arm or an
+  ``{address: {formattedAddress}}`` arm. This surface showed only the
+  coordinate arm on the live-proof walk, but rides the shared wrapper
+  whose address arm DutyStatusLog proved.
+- ``duration`` is an opaque duration STRING mirrored verbatim, NOT
+  parsed through ``GeotabTimeSpan`` despite that sharing GeoTab's
+  provider. The census observed only the wire TYPE (``str``, 500/500),
+  never the value FORMAT — unlike ``Trip.duration``, whose TimeSpan
+  grammar was probe-confirmed (2026-07-13). Applying the strict
+  TimeSpan parser to an unobserved format would crash every record if
+  it differs, so the conservative mirror holds until a probe settles
+  the format. ``trailer`` (295/500) is an ``{id}`` ref.
+- Every reference field (``device``, ``driver``, ``trailer``) rides
+  the shared ``bare_id_to_reference`` lift (the census-scope lesson: a
+  tenant census cannot prove the string arm absent).
+
+``dateTime`` is recovered tz-aware by validation, the GeoTab sibling
+idiom. ``logType`` is a census-open vocabulary — a plain str, never an
+enum.
+"""
+
+from datetime import datetime
+from typing import Annotated
+
+from pydantic import BeforeValidator, ConfigDict
+from pydantic.alias_generators import to_camel
+
+from fleetpull.model_contract import ResponseModel
+from fleetpull.models.geotab.shared import GeotabAddressedLocation, bare_id_to_reference
+
+__all__: list[str] = [
+    'DvirLog',
+    'DvirLogDefectList',
+    'DvirLogDeviceRef',
+    'DvirLogDriverRef',
+    'DvirLogTrailerRef',
+]
+
+
+class DvirLogDefectList(ResponseModel):
+    """The ``defectList`` block: a WIRE-PLURAL NAME, ONE defect node.
+
+    Despite the plural wire key, the census shows ONE object —
+    ``{children, id, name}`` — mirrored as a single nested model, never
+    a list. ``children`` is excluded (never populated on the whole
+    census; the module docstring's documented-exclusion record); ``id``
+    and ``name`` are required within the block — a defect node without
+    its identity is a shape change and must fail loudly.
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    id: str
+    name: str
+
+
+class DvirLogDeviceRef(ResponseModel):
+    """The inspected vehicle unit's reference.
+
+    Census-observed as an ``{id}`` object on every carrier; the shared
+    coercion lifts a bare string defensively (the census-scope lesson).
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    id: str
+
+
+class DvirLogDriverRef(ResponseModel):
+    """The inspecting driver's reference: the id alone, on every record."""
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    id: str
+
+
+class DvirLogTrailerRef(ResponseModel):
+    """The inspected trailer's reference: the id alone, on every carrier."""
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    id: str
+
+
+class DvirLog(ResponseModel):
+    """One GeoTab driver vehicle inspection report from the DVIRLog feed.
+
+    The wave-two conservative mirror (the module docstring's posture):
+    ``id`` / ``date_time`` / ``version`` / ``driver`` required,
+    everything else optional even where census-total.
+
+    Attributes:
+        authority_address: The certifying authority's address.
+        authority_name: The certifying authority's name.
+        certify_remark: The certification remark.
+        date_time: The inspection's UTC instant — the endpoint's event
+            time.
+        defect_list: The plural-named single defect node (``children``
+            excluded — the module docstring's record).
+        device: The inspected vehicle unit's reference (205/500 — the
+            observed wire fact).
+        driver: The inspecting driver's reference.
+        driver_remark: The driver's remark.
+        duration: The inspection duration — an opaque wire string
+            mirrored verbatim (the value format is unobserved, so it is
+            not parsed through ``GeotabTimeSpan`` the way ``Trip`` is;
+            module docstring).
+        engine_hours: The engine-hours reading (205/500; modeled float
+            per the cross-surface mixed-numeric proof).
+        id: GeoTab's record id.
+        is_inspected_by_driver: Whether the driver performed the
+            inspection.
+        location: The inspection's nested location (496/500; the shared
+            wrapper — a ``{x, y}`` coordinate arm, x longitude / y
+            latitude, or a ``formattedAddress`` arm).
+        log_type: The inspection-type token (census-open plain str).
+        odometer: The odometer reading (205/500; modeled float).
+        trailer: The inspected trailer's reference (295/500).
+        version: The record's version token — the certified/edited-log
+            reconcile key beside ``id``.
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    authority_address: str | None = None
+    authority_name: str | None = None
+    certify_remark: str | None = None
+    date_time: datetime
+    defect_list: DvirLogDefectList | None = None
+    device: Annotated[
+        DvirLogDeviceRef | None, BeforeValidator(bare_id_to_reference)
+    ] = None
+    driver: Annotated[DvirLogDriverRef, BeforeValidator(bare_id_to_reference)]
+    driver_remark: str | None = None
+    duration: str | None = None
+    engine_hours: float | None = None
+    id: str
+    is_inspected_by_driver: bool | None = None
+    location: GeotabAddressedLocation | None = None
+    log_type: str | None = None
+    odometer: float | None = None
+    trailer: Annotated[
+        DvirLogTrailerRef | None, BeforeValidator(bare_id_to_reference)
+    ] = None
+    version: str

fleetpull/models/geotab/exception_event.py

@@ -0,0 +1,135 @@
+# src/fleetpull/models/geotab/exception_event.py
+"""The GeoTab ExceptionEvent response model (captured 2026-07-13).
+
+One record per continuous rule-violation interval per device per rule:
+the interval opens at ``active_from`` and closes at ``active_to``, and
+``duration = active_to - active_from`` holds exactly on every captured
+record, including a fractional-second span reproducing a fractional
+``active_from`` (DESIGN §8). Records mutate after creation
+(``last_modified_date_time`` observed ~17 minutes past
+``created_date_time``) — the provider-level lookback absorbs it.
+
+A pure mirror of the union of captured fields, everything optional.
+``driver`` and ``diagnostic`` arrive as either a reference object or a
+bare sentinel string (``"UnknownDriverId"``, ``"NoDiagnosticId"``) —
+the shared ``bare_id_to_reference`` coercion lifts the bare form to
+``{"id": <string>}`` verbatim, so the sentinel lands as the reference's
+``id`` and its other fields null exactly on sentinel rows. The
+object-form ``driver`` shape is inferred from Trip's captured grammar
+(these captures carry only the sentinel); the first object-form capture
+upgrades it to Captured.
+"""
+
+from datetime import datetime
+from typing import Annotated
+
+from pydantic import BeforeValidator, ConfigDict
+from pydantic.alias_generators import to_camel
+
+from fleetpull.model_contract import ResponseModel
+from fleetpull.models.geotab.shared import GeotabTimeSpan, bare_id_to_reference
+
+__all__: list[str] = [
+    'ExceptionEvent',
+    'ExceptionEventDeviceRef',
+    'ExceptionEventDiagnosticRef',
+    'ExceptionEventDriverRef',
+    'ExceptionEventRuleRef',
+]
+
+
+class ExceptionEventRuleRef(ResponseModel):
+    """The event's rule reference: state, reason, and the rule id."""
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    state: str | None = None
+    reason: str | None = None
+    id: str | None = None
+
+
+class ExceptionEventDeviceRef(ResponseModel):
+    """The event's device reference: the id alone."""
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    id: str | None = None
+
+
+class ExceptionEventDriverRef(ResponseModel):
+    """The event's driver reference.
+
+    Arrives as an object or the bare ``"UnknownDriverId"`` sentinel
+    string; the ``ExceptionEvent.driver`` field's coercion lifts the
+    bare form to ``{"id": <string>}``, so ``is_driver`` is null exactly
+    on sentinel rows. The object-form shape mirrors Trip's captured
+    driver grammar (inferred; no object-form ExceptionEvent capture
+    exists yet).
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    id: str | None = None
+    is_driver: bool | None = None
+
+
+class ExceptionEventDiagnosticRef(ResponseModel):
+    """The event's diagnostic reference.
+
+    Arrives as the bare ``"NoDiagnosticId"`` sentinel string in every
+    capture; the coercion lifts it to ``{"id": <string>}``.
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    id: str | None = None
+
+
+class ExceptionEvent(ResponseModel):
+    """One GeoTab ExceptionEvent: a rule-violation interval.
+
+    Attributes:
+        id: GeoTab's event id (an ``a``-prefixed GUID-like string — a
+            different id space from the ``b``-hex entities).
+        version: The record's version token.
+        rule: The violated rule's reference (state, reason, rule id).
+        device: The vehicle reference.
+        driver: The driver reference; the bare ``"UnknownDriverId"``
+            sentinel lands as ``driver.id`` verbatim.
+        diagnostic: The diagnostic reference; the bare
+            ``"NoDiagnosticId"`` sentinel lands as ``diagnostic.id``.
+        active_from: Interval start (UTC) — the endpoint's event time
+            and partition anchor.
+        active_to: Interval end (UTC).
+        duration: The interval length (.NET TimeSpan on the wire);
+            reproduces ``active_to - active_from`` exactly in capture.
+        distance: Distance traveled during the interval, km.
+        state: The event's lifecycle state token, mirrored verbatim.
+        created_date_time: When the provider materialized the record.
+        last_modified_date_time: The record's last mutation.
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    # Identity.
+    id: str | None = None
+    version: str | None = None
+    rule: ExceptionEventRuleRef | None = None
+    device: ExceptionEventDeviceRef | None = None
+    driver: Annotated[
+        ExceptionEventDriverRef | None, BeforeValidator(bare_id_to_reference)
+    ] = None
+    diagnostic: Annotated[
+        ExceptionEventDiagnosticRef | None, BeforeValidator(bare_id_to_reference)
+    ] = None
+
+    # The interval.
+    active_from: datetime | None = None
+    active_to: datetime | None = None
+    duration: GeotabTimeSpan = None
+
+    # Measures and state.
+    distance: float | None = None
+    state: str | None = None
+    created_date_time: datetime | None = None
+    last_modified_date_time: datetime | None = None

fleetpull/models/geotab/fault_data.py

@@ -0,0 +1,168 @@
+# src/fleetpull/models/geotab/fault_data.py
+"""GeoTab FaultData response model (``GetFeed`` on ``typeName: FaultData``).
+
+Written from the 2026-07-21 feed wave two census (30-day seeded pulls at
+the probed tenant), never from docs. A FaultData record is one
+engine-fault observation — an ACTIVE feed with NO per-record
+``version`` (the LogRecord asymmetry: append-only storage is trivially
+complete and the consumer reconciles by ``id`` alone, DESIGN §4).
+
+Requiredness posture (the wave-two conservative stance, DESIGN §8): the
+census is a TENANT-SCOPED observation, so structural requiredness is
+limited to the record identity — ``id``, ``dateTime`` (the event
+time), and the primary entity ref (``device``, the faulting unit) —
+and every other field is optional EVEN where the census was total
+(2,000/2,000): a tenant census cannot promise another tenant's
+presence. The observed arms:
+
+- ``failureMode`` is MIXED object-or-string on this census (the one
+  proven mixed ref here); EVERY reference field — ``controller``,
+  ``device``, ``diagnostic``, ``failureMode`` — rides the shared
+  ``bare_id_to_reference`` lift regardless, because the census-scope
+  lesson (DESIGN §8, StatusData's ``controller``) is that a tenant
+  census cannot prove the string arm absent and the lift is structural
+  and sentinel-agnostic.
+- The RARE QUARTET — ``diagnosticSeverity`` (str), ``riskOfBreakdown``
+  (float), ``severity`` (str), ``sourceAddress`` (int) — appeared on
+  2/2,000 records each: optional scalars.
+- ``faultStates`` is a WIRE-PLURAL NAME carrying a SINGULAR object
+  shape (``{effectiveStatus}``) — mirrored as one nested model, the
+  plural-name/singular-shape wire fact recorded on it.
+
+``dateTime`` is recovered tz-aware by validation, the GeoTab sibling
+idiom. ``faultState`` and ``faultStates.effectiveStatus`` are
+census-open vocabularies — plain strs, never enums.
+"""
+
+from datetime import datetime
+from typing import Annotated
+
+from pydantic import BeforeValidator, ConfigDict
+from pydantic.alias_generators import to_camel
+
+from fleetpull.model_contract import ResponseModel
+from fleetpull.models.geotab.shared import bare_id_to_reference
+
+__all__: list[str] = [
+    'FaultData',
+    'FaultDataControllerRef',
+    'FaultDataDeviceRef',
+    'FaultDataDiagnosticRef',
+    'FaultDataFailureModeRef',
+    'FaultDataFaultStates',
+]
+
+
+class FaultDataControllerRef(ResponseModel):
+    """The source controller reference.
+
+    Census-observed as an ``{id}`` object on every carrier; the shared
+    coercion lifts a bare string defensively (the StatusData
+    census-scope lesson — an unobserved sentinel arm still lands as
+    ``controller__id``).
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    id: str
+
+
+class FaultDataDeviceRef(ResponseModel):
+    """The faulting vehicle unit's reference: the id alone, on every record."""
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    id: str
+
+
+class FaultDataDiagnosticRef(ResponseModel):
+    """The fault's diagnostic-definition reference: the id alone."""
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    id: str
+
+
+class FaultDataFailureModeRef(ResponseModel):
+    """The failure-mode reference.
+
+    The one PROVEN mixed ref on this census: an ``{id}`` object or a
+    bare id string, the bare form lifted by the shared coercion so both
+    arms land as ``failure_mode__id``.
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    id: str
+
+
+class FaultDataFaultStates(ResponseModel):
+    """The ``faultStates`` block: a WIRE-PLURAL NAME, a SINGULAR shape.
+
+    Despite the plural wire key, the census shows ONE object carrying
+    ``effectiveStatus`` (census-open plain str) — mirrored as a single
+    nested model, never a list. Required within the block: a
+    ``faultStates`` block without its one observed key is a shape
+    change and must fail loudly.
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    effective_status: str
+
+
+class FaultData(ResponseModel):
+    """One GeoTab engine-fault observation from the FaultData feed.
+
+    The wave-two conservative mirror (the module docstring's posture):
+    ``id`` / ``date_time`` / ``device`` required, everything else
+    optional even where census-total.
+
+    Attributes:
+        amber_warning_lamp: The amber-warning lamp state.
+        controller: The source controller reference (object-only on
+            this census; defensively lifted).
+        count: The fault's occurrence count.
+        date_time: The fault's UTC instant — the endpoint's event time.
+        device: The faulting vehicle unit's reference.
+        diagnostic: The fault's diagnostic-definition reference.
+        diagnostic_severity: Rare-quartet severity token (2/2,000;
+            census-open plain str).
+        failure_mode: The failure-mode reference — proven
+            object-or-string, both arms landing as ``failure_mode__id``.
+        fault_state: The fault-state token (census-open plain str).
+        fault_states: The plural-named singular status block.
+        id: GeoTab's record id.
+        malfunction_lamp: The malfunction-indicator lamp state.
+        protect_warning_lamp: The protect-warning lamp state.
+        red_stop_lamp: The red-stop lamp state.
+        risk_of_breakdown: Rare-quartet breakdown-risk score (2/2,000).
+        severity: Rare-quartet severity token (2/2,000; census-open).
+        source_address: Rare-quartet source address (2/2,000).
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    amber_warning_lamp: bool | None = None
+    controller: Annotated[
+        FaultDataControllerRef | None, BeforeValidator(bare_id_to_reference)
+    ] = None
+    count: int | None = None
+    date_time: datetime
+    device: Annotated[FaultDataDeviceRef, BeforeValidator(bare_id_to_reference)]
+    diagnostic: Annotated[
+        FaultDataDiagnosticRef | None, BeforeValidator(bare_id_to_reference)
+    ] = None
+    diagnostic_severity: str | None = None
+    failure_mode: Annotated[
+        FaultDataFailureModeRef | None, BeforeValidator(bare_id_to_reference)
+    ] = None
+    fault_state: str | None = None
+    fault_states: FaultDataFaultStates | None = None
+    id: str
+    malfunction_lamp: bool | None = None
+    protect_warning_lamp: bool | None = None
+    red_stop_lamp: bool | None = None
+    risk_of_breakdown: float | None = None
+    severity: str | None = None
+    source_address: int | None = None

fleetpull/models/geotab/fill_up.py

@@ -0,0 +1,189 @@
+# src/fleetpull/models/geotab/fill_up.py
+"""GeoTab FillUp response model (``GetFeed`` on ``typeName: FillUp``).
+
+Written from the 2026-07-21 live probe session, never from docs. A
+FillUp is one provider-detected fuel-stop event — a CALCULATED feed:
+past records re-emit under a higher ``version`` on reprocessing, stored
+as emitted and reconciled by ``(id, max version)`` (DESIGN §4).
+
+THE ESTIMATES-ONLY-TENANT CAVEAT (DESIGN §8): the probed tenant has NO
+fuel-transaction (fuel-card) integration, so every fuel value on this
+surface is provider-derived from telemetry — estimates, not
+transactions. The census cannot speak for integrated tenants: ``cost``
+was 0.0 on ALL records, ``fuelTransactions`` was an EMPTY list on ALL
+records (excluded below as value-unobservable — on tenants with
+fuel-card integration it populates with a shape never captured; it
+joins the model when a capture types it), and ``productType`` was
+``'Unknown'`` throughout.
+
+Requiredness posture: the census is a uniform whole-page total —
+100/100 records carried every modeled key — so every field is required,
+with the sentinel arms exactly as observed. The census is a
+TENANT-SCOPED observation. The observed arms:
+
+- ``driver`` arrives as either the object reference (``{"id": ...,
+  "isDriver": true}``, 87/100) or the bare ``"UnknownDriverId"``
+  sentinel string; the shared ``bare_id_to_reference`` coercion (the
+  shipped Trip mechanism) lifts the bare form to ``{"id": <string>}``,
+  so the sentinel lands as ``driver.id`` and ``is_driver`` is null
+  exactly on sentinel rows.
+- ``derivedVolume`` carries an observed ``-1.0`` sentinel (the
+  provider's could-not-derive marker) beside real volumes — mirrored
+  VERBATIM, never nulled: reshaping a sentinel would be interpretation.
+- ``confidence`` is a comma-joined detection-method token list carried
+  as ONE plain string (e.g. ``'FuelLevel, TripStop'``) — splitting it
+  would presume a use case; the observed vocabulary is census-open.
+- ``tankCapacity.source`` observed vocabulary: ``EstimateFuelLevel`` /
+  ``DiagnosticTankCapacity`` / ``Unknown`` — census-open plain str.
+
+Mixed int-or-float wire numerics (``derivedVolume``, ``distance``,
+``odometer``, ``tankCapacity.volume``, ``volume``) are modeled
+``float``. ``dateTime`` (the event time) and each extrema point's
+``dateTime`` are recovered tz-aware by validation, the GeoTab sibling
+idiom.
+"""
+
+from datetime import datetime
+from typing import Annotated
+
+from pydantic import BeforeValidator, ConfigDict
+from pydantic.alias_generators import to_camel
+
+from fleetpull.model_contract import ResponseModel
+from fleetpull.models.geotab.shared import bare_id_to_reference
+
+__all__: list[str] = [
+    'FillUp',
+    'FillUpDeviceRef',
+    'FillUpDriverRef',
+    'FillUpLocation',
+    'FillUpTankCapacity',
+    'FillUpTankLevelExtrema',
+    'FillUpTankLevelPoint',
+]
+
+
+class FillUpDeviceRef(ResponseModel):
+    """The fill-up's device reference: the id alone, on every record."""
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    id: str
+
+
+class FillUpDriverRef(ResponseModel):
+    """The fill-up's driver reference.
+
+    Arrives as an object or the bare ``"UnknownDriverId"`` sentinel
+    string; the ``FillUp.driver`` field's coercion lifts the bare form
+    to ``{"id": <string>}``, so ``is_driver`` is null exactly on
+    sentinel rows.
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    id: str
+    is_driver: bool | None = None
+
+
+class FillUpLocation(ResponseModel):
+    """The fill-up's coordinate: ``x`` longitude, ``y`` latitude."""
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    x: float
+    y: float
+
+
+class FillUpTankCapacity(ResponseModel):
+    """The provider's tank-capacity estimate and its derivation source.
+
+    Attributes:
+        source: How the capacity was derived — observed vocabulary
+            ``EstimateFuelLevel`` / ``DiagnosticTankCapacity`` /
+            ``Unknown``, census-open plain str.
+        volume: The estimated capacity in liters (mixed int-or-float on
+            the wire, modeled float).
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    source: str
+    volume: float
+
+
+class FillUpTankLevelPoint(ResponseModel):
+    """One tank-level extremum: its source, instant, and level reading."""
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    source: str
+    date_time: datetime
+    data: float
+
+
+class FillUpTankLevelExtrema(ResponseModel):
+    """The tank-level extrema pair bracketing the detected fill-up."""
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    maxima_point: FillUpTankLevelPoint
+    minima_point: FillUpTankLevelPoint
+
+
+class FillUp(ResponseModel):
+    """One GeoTab provider-detected fuel-stop event.
+
+    A pure mirror of the 100/100 whole-page census: every modeled key
+    present on every record, so everything is required; the sentinel
+    arms (``driver`` string-or-object, the ``-1.0`` ``derived_volume``)
+    are exactly as observed. The estimates-only-tenant caveat is the
+    module docstring's.
+
+    Attributes:
+        confidence: The comma-joined detection-method token list, one
+            plain string (census-open).
+        cost: The transaction cost — 0.0 on ALL census records (no fuel
+            transaction integration on the probed tenant).
+        currency_code: The cost's currency code (census-open plain str).
+        date_time: The detected fill-up's UTC instant — the endpoint's
+            event time.
+        derived_volume: The provider-derived fill volume in liters;
+            ``-1.0`` is the observed could-not-derive sentinel, mirrored
+            verbatim.
+        device: The vehicle unit's reference.
+        distance: Distance since the prior fill-up, km.
+        driver: The driver reference; the bare ``"UnknownDriverId"``
+            sentinel lands as ``driver.id`` verbatim.
+        id: GeoTab's record id.
+        location: The detected stop's coordinate.
+        odometer: The odometer reading at the fill-up.
+        product_type: The fuel product type — ``'Unknown'`` on all
+            census records (census-open plain str).
+        tank_capacity: The tank-capacity estimate and its source.
+        tank_level_extrema: The level extrema bracketing the fill-up.
+        total_fuel_used: Cumulative fuel used at the fill-up, liters.
+        version: The record's version token — the calculated-feed
+            reconcile key beside ``id``.
+        volume: The fill volume in liters (unit reasoning, recorded: the sibling wire key totalIdlingFuelUsedL carries the L suffix, and the probed value range -- median 299, max 848 -- is truck-tank plausible in liters and absurd in gallons).
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    confidence: str
+    cost: float
+    currency_code: str
+    date_time: datetime
+    derived_volume: float
+    device: FillUpDeviceRef
+    distance: float
+    driver: Annotated[FillUpDriverRef, BeforeValidator(bare_id_to_reference)]
+    id: str
+    location: FillUpLocation
+    odometer: float
+    product_type: str
+    tank_capacity: FillUpTankCapacity
+    tank_level_extrema: FillUpTankLevelExtrema
+    total_fuel_used: float
+    version: str
+    volume: float