fleetpull 0.1.0__py3-none-any.whl

fleetpull/models/motive/__init__.py

@@ -0,0 +1,43 @@
+"""Motive response models; the face re-exports each endpoint module's models."""
+
+from fleetpull.models.motive.driver_idle_rollup import DriverIdleRollup
+from fleetpull.models.motive.driving_period import DrivingPeriod
+from fleetpull.models.motive.group import Group
+from fleetpull.models.motive.idle_event import IdleEvent
+from fleetpull.models.motive.shared import (
+    EldDeviceInfo,
+    MotiveWindowStamp,
+    UserSummary,
+    VehicleSummary,
+)
+from fleetpull.models.motive.user import User
+from fleetpull.models.motive.vehicle import (
+    AvailabilityDetails,
+    AvailabilityStatus,
+    Vehicle,
+    VehicleStatus,
+)
+from fleetpull.models.motive.vehicle_location import (
+    VehicleLocation,
+    VehicleLocationType,
+)
+from fleetpull.models.motive.vehicle_utilization import VehicleUtilization
+
+__all__: list[str] = [
+    'AvailabilityDetails',
+    'AvailabilityStatus',
+    'DriverIdleRollup',
+    'DrivingPeriod',
+    'EldDeviceInfo',
+    'Group',
+    'IdleEvent',
+    'MotiveWindowStamp',
+    'User',
+    'UserSummary',
+    'Vehicle',
+    'VehicleLocation',
+    'VehicleLocationType',
+    'VehicleStatus',
+    'VehicleSummary',
+    'VehicleUtilization',
+]

fleetpull/models/motive/driver_idle_rollup.py

@@ -0,0 +1,109 @@
+# src/fleetpull/models/motive/driver_idle_rollup.py
+"""Motive DriverIdleRollup response model
+(``GET /v2/driver_utilization``, post-decoder window-stamped grain).
+
+Written from captured live responses (2026-07-21 probe session: 100
+records sampled, structurally uniform), never from docs. NOTE THE
+NAMING: the wire's OWN envelope vocabulary is
+``driver_idle_rollups``/``driver_idle_rollup`` -- different from its
+``/v2/driver_utilization`` path -- and the model mirrors the wire's
+vocabulary (the endpoint records the legacy-name mapping in
+``ENDPOINTS.md``).
+
+The model mirrors the record ``MotiveWindowReportPageDecoder`` emits:
+``window_start`` / ``window_end`` are DECODER-SYNTHESIZED
+(``windowStartDate``/``windowEndDate``) -- rollup rows carry NO date or
+time identity of any kind, so the decoder stamps each row with the
+window the SENT spec asked for, copied verbatim from its
+``start_date``/``end_date`` date labels, and ``MotiveWindowStamp``
+lifts each label to its UTC-midnight instant (``shared.py``);
+everything else is wire-verbatim.
+
+**THE COMPANY-LOCAL CAVEAT (the documented obligation on this
+mirror).** The date labels are interpreted in COMPANY-LOCAL days -- the
+account's ``/v1/companies`` capture carries a company-local zone at a
+UTC-5 offset (DESIGN section 8) -- so each row is the provider's rollup
+over its company-local day(s), mirrored verbatim. The window stamps
+carry the day LABELS, not UTC day boundaries; nothing here converts
+anything.
+
+**THE ROLLUP GRAIN IS THE REQUEST WINDOW -- proven on this surface;
+do not sum day rows (precedent-based).** A quiet single day returned 13
+rows and a six-day window 653 -- one rollup row per driver with
+activity in the window, per window (contrast the vehicle arm's
+whole-fleet-every-window population). The grain forces the binding's
+``fixed_unit_days=1``. Additivity was NOT probed here; on the provider
+family's only probed rollup surfaces (the Samsara fuel-energy pair) day
+rollups were NON-ADDITIVE into wider windows (89/267 mismatched), so
+the same posture applies as precedent: day rows MUST NOT be summed to
+reproduce a wider window's rollup.
+
+``driver`` is the shared 8-key ``UserSummary`` (its fourth carrying
+surface) and NULLABLE: the census found it populated on 99 of 100
+sampled rows and NULL on one -- an UNATTRIBUTED rollup bucket the
+provider emits alongside the per-driver rows, mirrored as a null ref,
+never dropped. The metric core is REQUIRED (every key on every sampled
+record; the rollup-surface reasoning -- metrics are computed per
+window, with no absence mechanism to be conservative about), and the
+window stamps are required STRUCTURALLY. ``idle_time`` and
+``driving_time`` are bare INTS on this arm -- floats on the vehicle
+arm -- and each arm mirrors its own wire.
+"""
+
+from pydantic import Field
+
+from fleetpull.model_contract import ResponseModel
+from fleetpull.models.motive.shared import MotiveWindowStamp, UserSummary
+
+__all__: list[str] = ['DriverIdleRollup']
+
+
+class DriverIdleRollup(ResponseModel):
+    """One driver's idle rollup over exactly one request window.
+
+    A pure mirror of the window-stamped post-decoder record (module
+    docstring: the window stamps are decoder-synthesized from the sent
+    spec's date labels; everything else is wire-verbatim). Field
+    semantics and units are Motive's; no value is derived or
+    interpreted here. Day rows MUST NOT be summed to reproduce a wider
+    window's rollup (module docstring -- the provider-family
+    precedent).
+
+    Attributes:
+        window_start: The request window's start-date label
+            (decoder-synthesized ``windowStartDate``, verbatim from the
+            sent ``start_date``) at UTC midnight -- the event-time
+            column: the row's time identity is the window that produced
+            it. A COMPANY-LOCAL day label (module docstring).
+        window_end: The request window's end-date label
+            (decoder-synthesized ``windowEndDate``, verbatim from the
+            sent ``end_date``) at UTC midnight. INCLUSIVE: at the fixed
+            1-day unit it equals ``window_start``.
+        driver: The rollup's driver entity (the shared ``UserSummary``);
+            NULL on the unattributed rollup bucket row (module
+            docstring), populated with the full 8-key shape otherwise.
+        utilization: The provider's utilization figure for the window,
+            mirrored uninterpreted.
+        driving_time: Time spent driving in the window, a bare int
+            (contrast the vehicle arm's float durations -- each arm
+            mirrors its own wire).
+        idle_time: Time spent idling in the window, a bare int.
+        driving_fuel: Fuel used while driving in the window, provider
+            units mirrored verbatim.
+        idle_fuel: Fuel used while idling in the window.
+    """
+
+    # Decoder-synthesized window identity (the sent spec's own labels).
+    window_start: MotiveWindowStamp = Field(alias='windowStartDate')
+    window_end: MotiveWindowStamp = Field(alias='windowEndDate')
+
+    # The rollup's entity; null on the unattributed bucket row.
+    driver: UserSummary | None = None
+
+    # The wire-verbatim metric core (required -- rollup surfaces have no
+    # absence arm; int durations on THIS arm, provider units verbatim).
+    utilization: float
+    driving_time: int
+    idle_time: int
+    driving_fuel: float
+    idle_fuel: float

fleetpull/models/motive/driving_period.py

@@ -0,0 +1,82 @@
+# src/fleetpull/models/motive/driving_period.py
+"""The Motive driving-period response model (captured 2026-07-15).
+
+One record per contiguous driving span from ``GET /v1/driving_periods``.
+Completed records reproduce ``duration = end_time - start_time`` exactly
+(float seconds); in-progress records (``status: "in_progress"``) null
+every end-side field — ``end_time``, ``end_kilometers``, ``distance``,
+the destination and its coordinates — while ``duration`` keeps counting
+as a fractional elapsed value. ``distance`` is a provider-formatted
+string (``"42.2 mi"``) mirrored verbatim — the merely-ugly side of the
+coercion boundary; real distance arithmetic uses the kilometer odometer
+fields. ``start_time`` was never observed null and is the endpoint's
+retrieval anchor (start-anchored UTC window matching, DESIGN §8).
+
+Excluded fields, per capture discipline: ``source`` and the four
+``*_hvb_*`` battery fields were never observed non-null (a diesel
+fleet's capture), so no honest dtype exists; they join the model when a
+capture pins their types.
+"""
+
+from datetime import datetime
+
+from pydantic import Field
+
+from fleetpull.model_contract import ResponseModel
+from fleetpull.models.motive.shared import UserSummary, VehicleSummary
+
+__all__: list[str] = ['DrivingPeriod']
+
+
+class DrivingPeriod(ResponseModel):
+    """One contiguous driving span for one vehicle.
+
+    Attributes:
+        period_id: Motive's internal period identifier (wire key ``id``).
+        start_time: UTC start of the span; the retrieval anchor.
+        end_time: UTC end of the span; null while the span is in progress.
+        status: Free-form lifecycle string (``"complete"`` /
+            ``"in_progress"`` observed), mirrored, never interpreted.
+        period_type: Free-form span-type string (wire key ``type``;
+            ``"driving"`` observed), mirrored, never interpreted.
+        annotation_status: Provider annotation state; null when absent.
+        notes: Free-form annotation text; null when absent.
+        duration: Span length in float seconds; on an in-progress record,
+            the elapsed value so far.
+        start_kilometers: Odometer at span start, kilometers.
+        end_kilometers: Odometer at span end; null while in progress.
+        driver: Attributed driver; null when the span is unattributed.
+        vehicle: The vehicle the span belongs to.
+        origin: Provider-formatted start address, mirrored verbatim
+            (empty strings normalize to null at the DataFrame boundary);
+            null when absent.
+        origin_lat: Start latitude; null when the provider has none.
+        origin_lon: Start longitude; null when the provider has none.
+        destination_lat: End latitude; null while in progress.
+        destination_lon: End longitude; null while in progress.
+        destination: Provider-formatted end address, mirrored verbatim —
+            the captured in-progress record carries ``""`` here (nulled
+            at the DataFrame boundary); null when absent.
+        distance: Provider-formatted distance string (``"42.2 mi"``),
+            mirrored verbatim; null while in progress.
+    """
+
+    period_id: int = Field(alias='id')
+    start_time: datetime
+    end_time: datetime | None = None
+    status: str
+    period_type: str = Field(alias='type')
+    annotation_status: int | None = None
+    notes: str | None = None
+    duration: float
+    start_kilometers: float
+    end_kilometers: float | None = None
+    driver: UserSummary | None = None
+    vehicle: VehicleSummary
+    origin: str | None = None
+    origin_lat: float | None = None
+    origin_lon: float | None = None
+    destination_lat: float | None = None
+    destination_lon: float | None = None
+    destination: str | None = None
+    distance: str | None = None

fleetpull/models/motive/group.py

@@ -0,0 +1,49 @@
+# src/fleetpull/models/motive/group.py
+"""The Motive group response model (``GET /v1/groups``, captured 2026-07-21).
+
+One record per organizational group. Written from a whole-population walk
+(152 records, four pages at ``per_page`` 50): every modeled key was present
+on all 152 records, so everything here is required -- nullability is the
+only optionality, and it follows the census exactly. ``parent_id`` is null
+on root groups and an existing group id otherwise (the groups form a
+tree).
+
+``user`` is the group's owner/creator reference -- the compact
+users-endpoint account shape, carried by the shared ``UserSummary`` (the
+``shared.py`` promotion rule: the identical wire shape already rides the
+driving-period and idle-event driver references). On THIS surface the
+census observed ``username`` and ``driver_company_id`` null on all 152
+records and ``role``/``status``/names populated on all 152;
+``UserSummary``'s union-lax optionality absorbs both facts, and the
+sibling surfaces are where the null-here keys carry values.
+"""
+
+from pydantic import Field
+
+from fleetpull.model_contract import ResponseModel
+from fleetpull.models.motive.shared import UserSummary
+
+__all__: list[str] = ['Group']
+
+
+class Group(ResponseModel):
+    """One Motive organizational group.
+
+    A pure mirror of the whole-population census: five keys, all present
+    on every record.
+
+    Attributes:
+        group_id: Motive's internal group identifier (wire key ``id``).
+        company_id: Parent company identifier.
+        name: The group's display name.
+        parent_id: The parent group's id; null on root groups (the
+            groups form a tree).
+        user: The group's owner/creator reference (the shared compact
+            users-endpoint account shape).
+    """
+
+    group_id: int = Field(alias='id')
+    company_id: int
+    name: str
+    parent_id: int | None
+    user: UserSummary

fleetpull/models/motive/idle_event.py

@@ -0,0 +1,77 @@
+# src/fleetpull/models/motive/idle_event.py
+"""The Motive idle-event response model (captured 2026-07-15).
+
+One record per engine-idle interval from ``GET /v1/idle_events``. Both
+timestamps were always present in capture — the endpoint has no
+in-progress shape analogue. ``veh_fuel_start`` / ``veh_fuel_end`` are the
+ELD's cumulative fuel counters, mirrored as-is. The ``rg_*`` fields are
+the provider's reverse-geocode metadata; when ``rg_match`` is false,
+``location`` carries a distance-direction prefix (``"2.6 mi NW of …"``)
+instead of a bare place name — both formats mirror verbatim.
+
+The endpoint's date window is interpreted on company-local day boundaries
+and matched by overlap (DESIGN §8, captured 2026-07-15) — the reason its
+endpoint leaf pads the wire window; nothing about that reaches this
+model, whose ``start_time`` remains the routing anchor.
+"""
+
+from datetime import datetime
+
+from pydantic import Field
+
+from fleetpull.model_contract import ResponseModel
+from fleetpull.models.motive.shared import (
+    EldDeviceInfo,
+    UserSummary,
+    VehicleSummary,
+)
+
+__all__: list[str] = ['IdleEvent']
+
+
+class IdleEvent(ResponseModel):
+    """One engine-idle interval for one vehicle.
+
+    Attributes:
+        event_id: Motive's internal event identifier (wire key ``id``).
+        start_time: UTC start of the idle interval; the routing anchor.
+        end_time: UTC end of the idle interval.
+        veh_fuel_start: ELD cumulative fuel counter at interval start;
+            null when the vehicle reports no fuel counters
+            (live-observed 2026-07-16).
+        veh_fuel_end: ELD cumulative fuel counter at interval end; null
+            when the vehicle reports no fuel counters.
+        lat: Event latitude.
+        lon: Event longitude.
+        city: Reverse-geocoded place name.
+        state: Reverse-geocoded state / province code.
+        rg_brg: Reverse-geocode bearing from the matched place, degrees.
+        rg_km: Reverse-geocode distance from the matched place,
+            kilometers.
+        rg_match: Whether the reverse geocoder matched a place directly.
+        end_type: Free-form interval-end reason (``"engine_stop"`` /
+            ``"vehicle_moving"`` observed), mirrored, never interpreted.
+        driver: Attributed driver; null when the idle is unattributed.
+        vehicle: The vehicle the interval belongs to.
+        eld_device: The ELD hardware that reported the interval.
+        location: Provider-formatted place string; carries a
+            distance-direction prefix when ``rg_match`` is false.
+    """
+
+    event_id: int = Field(alias='id')
+    start_time: datetime
+    end_time: datetime
+    veh_fuel_start: float | None = None
+    veh_fuel_end: float | None = None
+    lat: float
+    lon: float
+    city: str
+    state: str
+    rg_brg: float
+    rg_km: float
+    rg_match: bool
+    end_type: str
+    driver: UserSummary | None = None
+    vehicle: VehicleSummary
+    eld_device: EldDeviceInfo
+    location: str

fleetpull/models/motive/shared.py

@@ -0,0 +1,192 @@
+# src/fleetpull/models/motive/shared.py
+"""Motive embedded shapes shared across more than one endpoint.
+
+This module holds the per-record building blocks that appear on multiple
+Motive responses — ``UserSummary`` and ``EldDeviceInfo`` on the vehicle
+and vehicle-location records (and the driving-period and idle-event
+records), ``VehicleSummary`` on the driving-period, idle-event, and
+vehicle-utilization records — plus ``MotiveWindowStamp``, the
+decoder-synthesized window-identity type the utilization rollup pair's
+models share. Endpoint-private sub-shapes live in their endpoint module,
+not here; a shape is promoted into this module only once a second
+endpoint actually uses it.
+"""
+
+import re
+from datetime import UTC, date, datetime, time
+from typing import Annotated, Final
+
+from pydantic import BeforeValidator, Field
+
+from fleetpull.model_contract import ResponseModel, empty_str_to_none
+from fleetpull.vocabulary import JsonValue
+
+__all__: list[str] = [
+    'EldDeviceInfo',
+    'MotiveWindowStamp',
+    'UserSummary',
+    'VehicleSummary',
+]
+
+
+# Exactly the dashed calendar-date label the builders render; fullmatch
+# keeps date.fromisoformat's laxer forms (compact YYYYMMDD, ISO week
+# dates) failing loudly as the wiring drift they would be.
+_DATE_LABEL_PATTERN: Final[re.Pattern[str]] = re.compile(r'\d{4}-\d{2}-\d{2}')
+
+
+def _date_label_to_utc_midnight(value: JsonValue | datetime) -> datetime:
+    """The ``MotiveWindowStamp`` ingress: lift a date label to an instant.
+
+    The Motive window-report decoder stamps each rollup row with the
+    sent spec's ``start_date``/``end_date`` values VERBATIM — day-only
+    ``YYYY-MM-DD`` labels, never instants. A date label cannot validate
+    into the timezone-aware datetime the event-time machinery requires
+    (an unzoned event time is never assumed), so this lift is the
+    structural type recovery DESIGN section 9 allows on a mirror: the
+    calendar-day label is preserved exactly (the result's ``.date()`` IS
+    the label) and UTC midnight is attached as the label's canonical
+    instant representation — a labeling convention for partition
+    routing, never a timezone conversion of the data. Strict by design:
+    the builder only ever renders date labels, so any other string —
+    including a full RFC3339 datetime — is a wiring drift that should
+    fail validation loudly, not pass mangled.
+
+    Args:
+        value: The raw stamp value, or an already-recovered datetime on
+            a Pydantic revalidation path.
+
+    Returns:
+        The label's UTC-midnight instant (passthrough for an
+        already-recovered tz-aware value).
+
+    Raises:
+        ValueError: ``value`` is not exactly a dashed ``YYYY-MM-DD``
+            label (the laxer ``date.fromisoformat`` forms -- compact
+            digits, week dates -- reject too), or is a NAIVE datetime.
+    """
+    if isinstance(value, datetime):
+        if value.tzinfo is None:
+            raise ValueError(
+                'window stamp datetime is naive -- an unzoned event time '
+                'is never assumed'
+            )
+        return value
+    if isinstance(value, str) and _DATE_LABEL_PATTERN.fullmatch(value):
+        return datetime.combine(date.fromisoformat(value), time.min, tzinfo=UTC)
+    raise ValueError(f'expected a YYYY-MM-DD window-stamp label, got {value!r}')
+
+
+# The window-stamp field type the utilization rollup models use. Plain
+# assignment, not a `type` statement: Pydantic must evaluate the
+# Annotated form eagerly for the metadata lift (the GeotabTimeSpan
+# precedent).
+MotiveWindowStamp = Annotated[datetime, BeforeValidator(_date_label_to_utc_midnight)]
+
+
+class UserSummary(ResponseModel):
+    """Abbreviated user reference embedded in other Motive records.
+
+    The compact user-account shape that appears when a user is referenced
+    from another entity: the vehicle record's ``permanent_driver`` /
+    ``current_driver``, the driving-period and idle-event ``driver``
+    references, the group record's owner ``user``, and the
+    driver-idle-rollup ``driver`` reference (the fourth carrying
+    surface, captured 2026-07-21: the exact 8-key shape, populated on
+    every attributed rollup and null on the unattributed bucket row).
+    The full record comes from the users endpoint. Optionality is
+    union-lax across the carrying surfaces (a key populated on one
+    surface may be null on another -- e.g. ``username`` carries values
+    on driver references and was null on all 152 group owners); each
+    consumer's docstring pins its own surface's census.
+
+    ``status`` and ``role`` are modeled as free-form ``str`` rather than
+    constrained enums: Motive documents both as plain strings, fleetpull
+    does not interpret them, and mirroring them as strings keeps the model
+    faithful and evolution-safe.
+
+    Attributes:
+        user_id: Motive's internal user identifier (wire key ``id``).
+        first_name: Driver's first name.
+        last_name: Driver's last name.
+        username: Login username; null when unset.
+        email: Driver's email address; null when unset.
+        driver_company_id: Company-assigned driver identifier; null when
+            unset.
+        status: Free-form account-status string; null when absent.
+        role: Free-form user-role string; null when absent.
+    """
+
+    user_id: int = Field(alias='id')
+    first_name: str
+    last_name: str
+    username: str | None = None
+    email: str | None = None
+    driver_company_id: str | None = None
+    status: str | None = None
+    role: str | None = None
+
+
+class VehicleSummary(ResponseModel):
+    """Abbreviated vehicle reference embedded in other Motive records.
+
+    The compact vehicle shape that appears when a vehicle is referenced
+    from another record: the driving-period and idle-event records
+    (captured 2026-07-15) and the vehicle-utilization rollup record
+    (captured 2026-07-21 -- the same seven wire keys exactly, its third
+    carrying surface). The full vehicle record comes from the vehicles
+    endpoint. Optionality is union-lax across the carrying surfaces
+    (the UserSummary posture): ``vin`` carried values on every event
+    record but is null on some utilization rows, so it is nullable
+    here; each consumer's docstring pins its own surface's census.
+
+    ``year`` arrives as a quoted integer (``"2022"``); lax coercion types
+    it, and the captured ``"0"`` not-configured sentinel mirrors as
+    ``0``, never interpreted. The empty-string wire shape (live-observed
+    2026-07-16, failing ``int_parsing``) is lifted by a before-validator
+    — the type-recovery case DESIGN section 9 allows on a mirror, since
+    ``""`` cannot validate as an integer at all. ``make`` and ``model``
+    arrive as empty strings where the provider has no value and mirror
+    verbatim: empty strings normalize to null at the DataFrame boundary,
+    never on a string field of the model.
+
+    Attributes:
+        vehicle_id: Motive's internal vehicle identifier (wire key ``id``).
+        number: Company-assigned unit number.
+        year: Model year; ``0`` is the provider's not-configured
+            sentinel; null when the provider sends an empty string or
+            nothing.
+        make: Manufacturer; the captured empty string mirrors verbatim;
+            null when absent.
+        model: Model name; the captured empty string mirrors verbatim;
+            null when absent.
+        vin: Vehicle identification number; null where the provider has
+            none (observed on the vehicle-utilization surface).
+        metric_units: Whether the vehicle's Motive profile reports metric.
+    """
+
+    vehicle_id: int = Field(alias='id')
+    number: str
+    year: Annotated[int | None, BeforeValidator(empty_str_to_none)] = None
+    make: str | None = None
+    model: str | None = None
+    vin: str | None = None
+    metric_units: bool
+
+
+class EldDeviceInfo(ResponseModel):
+    """ELD hardware embedded in other Motive records.
+
+    Identifies the physical telematics device installed in a vehicle. The
+    source documents this shape on both the vehicle record and the
+    vehicle-location record.
+
+    Attributes:
+        device_id: Motive's internal device identifier (wire key ``id``).
+        identifier: Device serial / hardware identifier.
+        model: Device model name (e.g. the Motive LBB designation).
+    """
+
+    device_id: int = Field(alias='id')
+    identifier: str
+    model: str