fleetpull 0.1.0__py3-none-any.whl

fleetpull/models/motive/user.py

@@ -0,0 +1,217 @@
+# src/fleetpull/models/motive/user.py
+"""The Motive user response model (``GET /v1/users``, captured 2026-07-21).
+
+One record per account — driver or otherwise. Written from a
+whole-population walk (2,665 records, 27 pages at ``per_page`` 100) whose
+shape is perfectly role-partitioned: ``role='driver'`` records (2,359)
+carry a driver-only key block on top of the shared keys, while ``admin``
+(32) and ``fleet_user`` (274) records carry exactly the shared keys —
+zero partial-presence keys within any role. This is the Samsara drivers
+decision-1 posture with the split inverted: one population and ONE
+dataset, but a role-dependent shape rather than a provider filter quirk —
+the ``role`` column carries the split, and the driver-only block is
+ABSENT, not null, on non-driver records.
+
+Requiredness mirrors the census: the shared keys, present on every one of
+the 2,665 records, are required (nullable exactly where the census
+observed null); the driver-only keys are optional on the model — absent
+for non-drivers — with nullability per the census inside the driver role.
+``role`` (``driver``/``admin``/``fleet_user`` observed) and ``status``
+(``active``: 1,020 / ``deactivated``: 1,645) are census-closed
+vocabularies only, not API-enforced on output, so they mirror as plain
+strings; likewise ``duty_status`` (observed ``on_duty``/``off_duty``/
+``driving``), ``eld_mode`` (``logs``/``none``/``exempt``),
+``violation_alerts`` (``never``/``1_hour``/``45_minutes``/
+``30_minutes``/``15_minutes``), and the HOS cycle pair (``cycle2``
+observed values like ``70_8_2020``/``60_7_o_2020`` on 37 drivers).
+``joined_at`` is a DATE-ONLY wire value (``YYYY-MM-DD``, 34 of 2,359
+drivers populated -- the whole-population value census), recovered as a
+``date``; null on the rest.
+
+The always-present key partition, exactly: 22 keys ride every record
+(20 modeled; ``external_ids`` and ``phone_ext`` never populated
+anywhere); ``admin``/``fleet_user`` records add 3 keys of their own
+(``expires_at``, ``phone2``, ``phone_country_code2`` -- never populated
+among them); driver records add 39 (38 modeled;
+``associated_dispatcher_id`` never populated).
+
+Excluded fields, per capture discipline: the six never-populated keys
+named above were present but always null/empty across all 2,665
+records -- the value types are unobservable (the value-unobservable
+exclusion rule); they join the model when a capture types them
+(``extra='ignore'`` makes exclusion exactly "don't model it"). Contrast
+``joined_at``: value-OBSERVED (34 dates), hence modeled.
+"""
+
+from datetime import date, datetime
+
+from pydantic import Field
+
+from fleetpull.model_contract import ResponseModel
+
+__all__: list[str] = ['User']
+
+
+class User(ResponseModel):
+    """One Motive user account: a driver, admin, or fleet_user.
+
+    A pure mirror of the role-partitioned census. Groups below follow
+    the partition: the shared block first (required on every record),
+    then the driver-only block (absent, not null, on non-driver
+    records — every field there defaults to ``None``). Field semantics
+    are Motive's; no value is derived or interpreted here.
+
+    Attributes:
+        user_id: Motive's internal user identifier (wire key ``id``).
+        first_name: User's first name.
+        last_name: User's last name.
+        email: User's email address; null when unset.
+        phone: Contact phone number; null when unset.
+        phone_country_code: Phone country code; null when unset.
+        company_reference_id: Company-assigned reference identifier;
+            null when unset.
+        role: Free-form user-role string; ``driver`` / ``admin`` /
+            ``fleet_user`` observed — the column that carries the
+            shape partition.
+        status: Free-form account-status string; ``active`` /
+            ``deactivated`` observed.
+        group_ids: Identifiers of the groups the user belongs to;
+            often empty.
+        metric_units: Whether the account displays metric units.
+        time_zone: Rails-style time-zone display name; null when unset.
+        created_at: When the account was created.
+        updated_at: Last modification timestamp.
+        mobile_current_sign_in_at: Current mobile-session sign-in;
+            null when none.
+        mobile_last_active_at: Last mobile activity; null when none.
+        mobile_last_sign_in_at: Previous mobile sign-in; null when none.
+        web_current_sign_in_at: Current web-session sign-in; null when
+            none.
+        web_last_active_at: Last web activity; null when none.
+        web_last_sign_in_at: Previous web sign-in; null when none.
+        username: Login username; driver-only; null when unset.
+        driver_company_id: Company-assigned driver identifier;
+            driver-only; null when unset.
+        drivers_license_number: Driver's license number; driver-only;
+            null when unset.
+        drivers_license_state: Driver's license state/province;
+            driver-only; null when unset.
+        joined_at: Driver-only; the driver's join date -- a DATE-ONLY
+            wire value (``YYYY-MM-DD``; 34 of 2,359 populated), null on
+            the rest.
+            conservative nullable-str posture (see module docstring).
+        duty_status: Free-form HOS duty-status string; driver-only.
+        eld_mode: Free-form ELD-mode string; driver-only.
+        cycle: Free-form HOS cycle string; driver-only; null when
+            unset.
+        cycle2: Second-jurisdiction HOS cycle; driver-only; null when
+            unset.
+        violation_alerts: Free-form violation-alert cadence string;
+            driver-only.
+        carrier_name: Carrier name; driver-only.
+        carrier_street: Carrier street address; driver-only.
+        carrier_city: Carrier city; driver-only.
+        carrier_state: Carrier state; driver-only.
+        carrier_zip: Carrier postal code; driver-only.
+        terminal_street: Home-terminal street; driver-only; null when
+            unset.
+        terminal_city: Home-terminal city; driver-only; null when
+            unset.
+        terminal_state: Home-terminal state; driver-only; null when
+            unset.
+        terminal_zip: Home-terminal postal code; driver-only; null
+            when unset.
+        exception_24_hour_restart: HOS exception flag; driver-only.
+        exception_8_hour_break: HOS exception flag; driver-only.
+        exception_adverse_driving: HOS exception flag; driver-only.
+        exception_ca_farm_school_bus: HOS exception flag; driver-only.
+        exception_short_haul: HOS exception flag; driver-only.
+        exception_wait_time: HOS exception flag; driver-only.
+        exception_24_hour_restart2: Second-jurisdiction HOS exception
+            flag; driver-only (likewise the other ``*2`` flags).
+        exception_8_hour_break2: See above; driver-only.
+        exception_adverse_driving2: See above; driver-only.
+        exception_ca_farm_school_bus2: See above; driver-only.
+        exception_short_haul2: See above; driver-only.
+        exception_wait_time2: See above; driver-only.
+        export_combined: Log-export setting; driver-only.
+        export_odometers: Log-export setting; driver-only.
+        export_recap: Log-export setting; driver-only.
+        manual_driving_enabled: Driving-mode setting; driver-only.
+        minute_logs: Minute-grain logging setting; driver-only.
+        personal_conveyance_enabled: Driving-mode setting; driver-only.
+        yard_moves_enabled: Driving-mode setting; driver-only.
+    """
+
+    # The shared block: present on every record of every role.
+    user_id: int = Field(alias='id')
+    first_name: str
+    last_name: str
+    email: str | None
+    phone: str | None
+    phone_country_code: str | None
+    company_reference_id: str | None
+    role: str
+    status: str
+    group_ids: list[int]
+    metric_units: bool
+    time_zone: str | None
+    created_at: datetime
+    updated_at: datetime
+    mobile_current_sign_in_at: datetime | None
+    mobile_last_active_at: datetime | None
+    mobile_last_sign_in_at: datetime | None
+    web_current_sign_in_at: datetime | None
+    web_last_active_at: datetime | None
+    web_last_sign_in_at: datetime | None
+
+    # The driver-only block: absent, not null, on non-driver records.
+    # Identity and licensing.
+    username: str | None = None
+    driver_company_id: str | None = None
+    drivers_license_number: str | None = None
+    drivers_license_state: str | None = None
+    joined_at: date | None = None
+
+    # HOS configuration.
+    duty_status: str | None = None
+    eld_mode: str | None = None
+    cycle: str | None = None
+    cycle2: str | None = None
+    violation_alerts: str | None = None
+
+    # Carrier and home-terminal identity.
+    carrier_name: str | None = None
+    carrier_street: str | None = None
+    carrier_city: str | None = None
+    carrier_state: str | None = None
+    carrier_zip: str | None = None
+    terminal_street: str | None = None
+    terminal_city: str | None = None
+    terminal_state: str | None = None
+    terminal_zip: str | None = None
+
+    # HOS exception flags (the *2 variants are the second jurisdiction).
+    exception_24_hour_restart: bool | None = None
+    exception_8_hour_break: bool | None = None
+    exception_adverse_driving: bool | None = None
+    exception_ca_farm_school_bus: bool | None = None
+    exception_short_haul: bool | None = None
+    exception_wait_time: bool | None = None
+    exception_24_hour_restart2: bool | None = None
+    exception_8_hour_break2: bool | None = None
+    exception_adverse_driving2: bool | None = None
+    exception_ca_farm_school_bus2: bool | None = None
+    exception_short_haul2: bool | None = None
+    exception_wait_time2: bool | None = None
+
+    # Log-export settings.
+    export_combined: bool | None = None
+    export_odometers: bool | None = None
+    export_recap: bool | None = None
+
+    # Driving-mode settings.
+    manual_driving_enabled: bool | None = None
+    minute_logs: bool | None = None
+    personal_conveyance_enabled: bool | None = None
+    yard_moves_enabled: bool | None = None

fleetpull/models/motive/vehicle.py

@@ -0,0 +1,162 @@
+# src/fleetpull/models/motive/vehicle.py
+"""Motive vehicles-endpoint response model (``/v1/vehicles``).
+
+Holds the ``Vehicle`` record and the shapes used only by it —
+``AvailabilityDetails`` and the ``VehicleStatus`` / ``AvailabilityStatus``
+enums. Cross-endpoint embedded shapes (``UserSummary``, ``EldDeviceInfo``)
+are imported from ``fleetpull.models.motive.shared``.
+
+Pure API mirrors — typed fields and nothing else. No use-case logic, no
+derived properties, no normalizing validators: flattening and schema
+derivation are the records layer's generic concern (DESIGN §9), and
+fleetpull assumes no end use, so a field is mirrored, never interpreted.
+The response *wrapper* (the ``{"vehicles": [{"vehicle": {...}}]}`` envelope)
+is not modeled here — the endpoints layer's extractor and paginator own it,
+so this module mirrors only the inner per-vehicle object.
+"""
+
+from datetime import datetime
+from enum import StrEnum
+
+from pydantic import Field
+
+from fleetpull.model_contract import ResponseModel
+from fleetpull.models.motive.shared import EldDeviceInfo, UserSummary
+
+__all__: list[str] = [
+    'AvailabilityDetails',
+    'AvailabilityStatus',
+    'Vehicle',
+    'VehicleStatus',
+]
+
+
+class VehicleStatus(StrEnum):
+    """Operational status for a Motive vehicle.
+
+    A closed mirror of Motive's documented status vocabulary. Kept as an
+    enum (not downgraded to ``str``) because the wire values match the
+    member values exactly — no normalizing logic is needed to land them,
+    so the enum stays a faithful mirror while adding documentation and
+    membership validation. Live responses show ``active`` and
+    ``deactivated``; ``inactive`` is documented.
+    """
+
+    ACTIVE = 'active'
+    INACTIVE = 'inactive'
+    DEACTIVATED = 'deactivated'
+
+
+class AvailabilityStatus(StrEnum):
+    """In-service / out-of-service availability for a Motive vehicle.
+
+    Closed mirror of Motive's documented availability vocabulary; an exact
+    wire-to-member match, so it stays an enum for the same reason as
+    ``VehicleStatus``.
+    """
+
+    IN_SERVICE = 'in_service'
+    OUT_OF_SERVICE = 'out_of_service'
+
+
+class AvailabilityDetails(ResponseModel):
+    """Availability status block embedded in the vehicle record.
+
+    Tracks whether a vehicle is in or out of service and when the status
+    last changed.
+
+    Attributes:
+        availability_status: Current in-service / out-of-service value.
+        updated_at: Timestamp of the last status change.
+    """
+
+    availability_status: AvailabilityStatus
+    updated_at: datetime
+
+
+class Vehicle(ResponseModel):
+    """Complete vehicle record from Motive's vehicles endpoint.
+
+    A single fleet vehicle with its metadata, current and permanent driver
+    references, ELD device, and availability block. A pure mirror: every
+    field maps a Motive response field, with no derived or interpreted
+    values.
+
+    Attributes:
+        vehicle_id: Motive's internal vehicle identifier (wire key ``id``).
+        company_id: Parent company identifier.
+        number: User-assigned fleet/unit number.
+        status: Vehicle operational status.
+        ifta: Whether the vehicle is IFTA-reportable.
+        vin: Vehicle Identification Number; null when unset.
+        make: Manufacturer; null when unset.
+        model: Model name; null when unset.
+        year: Model year, mirrored as a string (Motive's convention); null
+            when unset.
+        license_plate_state: Registration state/province; null when unset.
+        license_plate_number: License plate number; null when unset.
+        license_plate_country_code: Registration country code; null when
+            unset. Present in live responses but absent from the predecessor
+            model — added here so the mirror is faithful to the wire.
+        metric_units: Whether the vehicle displays metric units.
+        fuel_type: Primary fuel type, mirrored as a free-form ``str``
+            rather than a constrained enum — Motive's casing varies and
+            fleetpull does not interpret the value, so a string mirror
+            avoids carrying a normalizing validator on an otherwise pure
+            model; null when unset.
+        prevent_auto_odometer_entry: Whether automatic odometer capture is
+            disabled.
+        notes: Free-form notes; null when unset.
+        incab_alert_live_stream_enable: Motive camera-config field; ``-1``
+            is Motive's "not configured" sentinel and the default.
+        driver_facing_camera: Camera-config field; ``-1`` sentinel default.
+        incab_audio_recording: Camera-config field; ``-1`` sentinel default.
+        group_ids: Identifiers of the groups the vehicle belongs to.
+        created_at: When the vehicle was added to Motive.
+        updated_at: Last modification timestamp.
+        permanent_driver: Permanently assigned driver; null when none.
+        availability_details: Current availability block; null when absent.
+        eld_device: Installed ELD hardware; null when none.
+        current_driver: Currently logged-in driver; null when none.
+        carb_ctc_test_enabled: CARB compliance flag; null when absent.
+        carb_ctc_emission_status: CARB emission status string; null when
+            absent.
+        registration_expiry_date: Registration expiry, mirrored as a string
+            (Motive's convention); null when absent.
+    """
+
+    vehicle_id: int = Field(alias='id')
+    company_id: int
+    number: str
+    status: VehicleStatus
+    ifta: bool
+    vin: str | None = None
+    make: str | None = None
+    model: str | None = None
+    year: str | None = None
+    license_plate_state: str | None = None
+    license_plate_number: str | None = None
+    license_plate_country_code: str | None = None
+    metric_units: bool = False
+    fuel_type: str | None = None
+    prevent_auto_odometer_entry: bool = False
+    notes: str | None = None
+
+    # Motive uses -1 as a "not configured" sentinel for these camera ints.
+    incab_alert_live_stream_enable: int = -1
+    driver_facing_camera: int = -1
+    incab_audio_recording: int = -1
+
+    group_ids: list[int] = Field(default_factory=list)
+
+    created_at: datetime
+    updated_at: datetime
+
+    permanent_driver: UserSummary | None = None
+    availability_details: AvailabilityDetails | None = None
+    eld_device: EldDeviceInfo | None = None
+    current_driver: UserSummary | None = None
+
+    carb_ctc_test_enabled: bool | None = None
+    carb_ctc_emission_status: str | None = None
+    registration_expiry_date: str | None = None

fleetpull/models/motive/vehicle_location.py

@@ -0,0 +1,127 @@
+# src/fleetpull/models/motive/vehicle_location.py
+"""Motive vehicle-locations-endpoint response model (``/v3/vehicle_locations``).
+
+Holds the ``VehicleLocation`` breadcrumb record and the ``VehicleLocationType``
+enum used only by it. Cross-endpoint embedded shapes (``UserSummary``,
+``EldDeviceInfo``) are imported from ``fleetpull.models.motive.shared``.
+
+Pure API mirrors — typed fields and nothing else. No use-case logic, no derived
+properties, no normalizing validators: flattening and schema derivation are the
+records layer's generic concern (DESIGN §9), and fleetpull assumes no end use, so a
+field is mirrored, never interpreted. The response *wrapper* (the
+``{"vehicle_locations": [{"vehicle_location": {...}}]}`` envelope) is not modeled
+here — the endpoints layer's decoder owns it, so this module mirrors only the inner
+per-location object.
+"""
+
+from datetime import datetime
+from enum import StrEnum
+
+from pydantic import Field
+
+from fleetpull.model_contract import ResponseModel
+from fleetpull.models.motive.shared import EldDeviceInfo, UserSummary
+
+__all__: list[str] = [
+    'VehicleLocation',
+    'VehicleLocationType',
+]
+
+
+class VehicleLocationType(StrEnum):
+    """Type of a Motive vehicle-location (breadcrumb) record.
+
+    A closed mirror of Motive's documented location-type vocabulary. Kept as an
+    enum (not downgraded to ``str``) for the same reason as ``VehicleStatus``: the
+    wire values match the member values exactly, so the enum is a faithful mirror
+    that adds documentation and membership validation with no normalizing logic.
+    The blast radius differs from ``VehicleStatus`` — this endpoint is high-volume
+    per-vehicle breadcrumbs, so a type Motive begins emitting that is not a member
+    fails validation loudly across every affected row rather than a handful of
+    vehicles. That is fail-fast-and-loud as intended (extend the member set,
+    re-fetch); it is also the field most likely to want ``str`` instead if a silent
+    land-as-data is ever preferred on this surface.
+    """
+
+    BREADCRUMB = 'breadcrumb'
+    VEHICLE_STOPPED = 'vehicle_stopped'
+    VEHICLE_MOVING = 'vehicle_moving'
+    IGNITION_ON = 'ignition_on'
+    IGNITION_OFF = 'ignition_off'
+    ENGINE_START = 'engine_start'
+    ENGINE_STOP = 'engine_stop'
+    GPS_MOVING = 'gps_moving'
+    GPS_STOPPED = 'gps_stopped'
+
+
+class VehicleLocation(ResponseModel):
+    """A single vehicle-location (breadcrumb) record from Motive.
+
+    One point-in-time fix of a vehicle's position and telemetry from the
+    ``/v3/vehicle_locations/{vehicle_id}`` endpoint, which returns a vehicle's
+    location history over a date range. A pure mirror: every field maps a Motive
+    response field, with no derived or interpreted values.
+
+    Attributes:
+        location_id: Motive's identifier for this location record, a UUID string
+            (wire key ``id``).
+        located_at: Timestamp the location was recorded -- the endpoint's event
+            time.
+        latitude: GPS latitude in decimal degrees (wire key ``lat``).
+        longitude: GPS longitude in decimal degrees (wire key ``lon``).
+        location_type: The kind of location event (wire key ``type``).
+        description: Human-readable place description (e.g. city, state); null
+            when absent.
+        speed: Vehicle speed in the vehicle's own units; null when absent.
+        bearing: Compass heading in degrees; null when absent.
+        battery_voltage: Vehicle battery voltage; null when absent.
+        odometer: Calculated odometer reading; null when absent.
+        true_odometer: ECM-reported odometer; null when absent.
+        engine_hours: Calculated engine-hours reading; null when absent.
+        true_engine_hours: ECM-reported engine hours; null when absent.
+        fuel: Cumulative fuel consumption; null when absent.
+        fuel_primary_remaining_percentage: Primary tank level, 0-100; null when
+            absent.
+        fuel_secondary_remaining_percentage: Secondary tank level, 0-100; null
+            when absent.
+        veh_range: Estimated remaining range (EV); null for non-EV.
+        hvb_state_of_charge: High-voltage-battery charge state (EV); null for
+            non-EV.
+        hvb_charge_status: High-voltage-battery charge status string (EV); null
+            for non-EV.
+        hvb_charge_source: High-voltage-battery charge source string (EV); null
+            for non-EV.
+        hvb_lifetime_energy_output: High-voltage-battery lifetime energy output
+            (EV); null for non-EV.
+        driver: Driver logged in at capture time; null when none.
+        eld_device: ELD device that captured the location; null when none.
+    """
+
+    location_id: str = Field(alias='id')
+    located_at: datetime
+    latitude: float = Field(alias='lat')
+    longitude: float = Field(alias='lon')
+    location_type: VehicleLocationType = Field(alias='type')
+    description: str | None = None
+
+    speed: float | None = None
+    bearing: float | None = None
+
+    battery_voltage: float | None = None
+    odometer: float | None = None
+    true_odometer: float | None = None
+    engine_hours: float | None = None
+    true_engine_hours: float | None = None
+
+    fuel: float | None = None
+    fuel_primary_remaining_percentage: float | None = None
+    fuel_secondary_remaining_percentage: float | None = None
+
+    veh_range: float | None = None
+    hvb_state_of_charge: float | None = None
+    hvb_charge_status: str | None = None
+    hvb_charge_source: str | None = None
+    hvb_lifetime_energy_output: float | None = None
+
+    driver: UserSummary | None = None
+    eld_device: EldDeviceInfo | None = None

fleetpull/models/motive/vehicle_utilization.py

@@ -0,0 +1,128 @@
+# src/fleetpull/models/motive/vehicle_utilization.py
+"""Motive VehicleUtilization response model
+(``GET /v2/vehicle_utilization``, post-decoder window-stamped grain).
+
+Written from captured live responses (2026-07-21 probe session: 120
+records sampled across the 1,466-vehicle listing, structurally uniform
+-- every key on every sampled record), never from docs. The model
+mirrors the record ``MotiveWindowReportPageDecoder`` emits, and its two
+field families have different provenance:
+
+- ``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 (the fuel-energy pair's
+  request-sourced stamp, on Motive wire). ``MotiveWindowStamp`` lifts
+  each label to its UTC-midnight instant -- a representation for
+  partition routing, never a timezone conversion (``shared.py``).
+- Everything else is WIRE-VERBATIM: the metric core, the ``vehicle``
+  ref (the shared ``VehicleSummary``, its third carrying surface), and
+  the ``message`` status string, snake_case keys mirrored directly.
+
+**THE COMPANY-LOCAL CAVEAT (the documented obligation on this
+mirror).** The ``start_date``/``end_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 1-day and a 6-day request
+each returned exactly one rollup row per vehicle over the SAME
+1,466-vehicle population -- the grain is the window, which is why the
+binding declares ``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.
+
+The population is the WHOLE vehicle fleet regardless of window (the
+1-day and 6-day totals were both 1,466): inactive vehicles ride with
+zeroed metrics and a populated ``message`` status string -- there is no
+absence arm on this surface, so the metric core is REQUIRED (the
+fuel-energy whole-walk reasoning: a rollup surface computes its metrics
+per window and has no absence mechanism to be conservative about). The
+window stamps and the ``vehicle`` ref are required STRUCTURALLY -- a
+rollup row without its window or its entity is meaningless.
+
+``last_located_at`` is the one nullable key (str-or-None in census) and
+mirrors VERBATIM as a string: its value format and zone semantics are
+unprobed, and Motive's rollup timestamps are documented company-local,
+so parsing it would presume what no capture has shown. ``message`` is
+free text -- a plain ``str``, no vocabulary claim.
+"""
+
+from pydantic import Field
+
+from fleetpull.model_contract import ResponseModel
+from fleetpull.models.motive.shared import MotiveWindowStamp, VehicleSummary
+
+__all__: list[str] = ['VehicleUtilization']
+
+
+class VehicleUtilization(ResponseModel):
+    """One vehicle's utilization 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``.
+        vehicle: The rollup's vehicle entity (the shared
+            ``VehicleSummary``; ``vin`` null on some rows of this
+            surface, every other key populated in census).
+        driving_fuel: Fuel used while driving in the window, provider
+            units mirrored verbatim.
+        driving_time: Time spent driving in the window, a float
+            (contrast the driver arm's bare-int durations -- each arm
+            mirrors its own wire).
+        idle_fuel: Fuel used while idling in the window.
+        idle_time: Time spent idling in the window, a float.
+        total_distance: Distance covered in the window.
+        total_fuel: Total fuel used in the window.
+        utilization_percentage: The provider's utilization figure for
+            the window, mirrored uninterpreted.
+        last_located_at: The vehicle's last-location timestamp, mirrored
+            VERBATIM as a string (format and zone semantics unprobed;
+            the company-local documentation obligation -- module
+            docstring); null when the provider has none.
+        message: Free-text status string -- populated on inactive
+            zero-metric rows (e.g. a no-data notice), empty otherwise;
+            a plain ``str``, no vocabulary claim.
+    """
+
+    # 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.
+    vehicle: VehicleSummary
+
+    # The wire-verbatim metric core (required -- no absence arm exists
+    # on this surface; provider units mirrored verbatim).
+    driving_fuel: float
+    driving_time: float
+    idle_fuel: float
+    idle_time: float
+    total_distance: float
+    total_fuel: float
+    utilization_percentage: float
+
+    # The wire-verbatim status pair.
+    last_located_at: str | None = None
+    message: str