fleetpull 0.1.0__py3-none-any.whl

fleetpull/models/geotab/device.py

@@ -0,0 +1,217 @@
+# src/fleetpull/models/geotab/device.py
+"""GeoTab Device response model (JSON-RPC ``Get`` on ``typeName: Device``).
+
+Written from captured live responses (2026-07-09 probe session), never
+from docs. The captured schema is polymorphic -- one entity type spans
+at least three shapes: GO7-era hardware, GO9-era hardware (a superset
+with ``vinInfo*`` and continuous-connect fields), and trailer entries
+(``deviceType: "None"``, ``productId: -1``, ``tmpTrailerId``, no
+telematics-parameter fields at all). Two tracked GO9 records also
+arrived without ``deviceFlags``/``devicePlans`` entirely, so shape
+poverty is itself a shape. The model is therefore the union of observed
+fields with every field optional; ``models_to_dataframe`` lands absent
+fields as nulls, one typed schema across all shapes.
+
+Excluded fields (``extra='ignore'`` makes exclusion exactly "don't
+model it"):
+
+- ``ignoreDownloadsUntil`` -- observed live at ``0001-01-01``, which
+  overflows nanosecond-precision timestamp columns (captured
+  2026-07-09). No other captured field carries a year-one datetime.
+- ``wifiHotspotLimits``, ``customProperties``, ``mediaFiles`` --
+  observed only as empty lists, so their element shape is uncaptured
+  and cannot be honestly typed.
+- ``groups``, ``devicePlanBillingInfo``, ``autoGroups``,
+  ``customParameters`` -- lists of objects; the records layer's schema
+  derivation (DESIGN section 9) supports scalars, enums,
+  ``list[scalar]``, and nested models only, so these shapes have no
+  honest column until the ``list[nested model]`` derivation vertical
+  lands. Model them there, or when a consumer forces typed access.
+
+Sentinels are stored as-is, never transformed (interpretation is the
+consumer's concern; the boundary model's job is shape): ``activeTo``
+of ``2050-01-01`` means "still active" (and is ns-safe); the VIN fields
+carry ``""`` and a literal ``"?"`` for unknown VINs; ``productId: -1``
+marks non-telematics (trailer) entries.
+
+Wire keys are camelCase; fields are snake_case via the ``to_camel``
+alias generator rather than 74 hand-written ``Field(alias=...)`` lines
+-- a typo'd hand alias would land silently as ``None`` under
+``extra='ignore'``, while the generator is mechanically exact (the
+model tests validate every captured shape against it). The three
+``DeviceFlags`` acronym keys the generator cannot produce
+(``isHOSAllowed`` / ``isUIAllowed`` / ``isVINAllowed``) carry explicit
+alias overrides, proven non-``None`` against a captured block.
+"""
+
+from datetime import datetime
+
+from pydantic import ConfigDict, Field
+from pydantic.alias_generators import to_camel
+
+from fleetpull.model_contract import ResponseModel
+
+__all__: list[str] = ['CustomFeatures', 'Device', 'DeviceFlags']
+
+
+class DeviceFlags(ResponseModel):
+    """The ``deviceFlags`` block: account-level capability flags.
+
+    A pure mirror of the captured block -- one ``activeFeatures`` string
+    list plus ten capability booleans; absent from two tracked GO9
+    captures and every trailer entry, so the whole block is optional on
+    ``Device`` and its columns land as nulls there. ``ratePlans`` is
+    excluded from this model's interior: observed only as an empty
+    list, its element shape is uncapturable (the same rule as the
+    top-level empty lists).
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    active_features: list[str] | None = None
+    is_active_tracking_allowed: bool | None = None
+    is_continuous_connect_allowed: bool | None = None
+    is_engine_allowed: bool | None = None
+    is_garmin_allowed: bool | None = None
+    # The acronym-alias trap: to_camel would emit isHosAllowed /
+    # isUiAllowed / isVinAllowed, silently landing these as None under
+    # extra='ignore'; the wire capitalizes the acronyms, so the three
+    # carry explicit aliases (an explicit alias beats the generator).
+    is_hos_allowed: bool | None = Field(default=None, alias='isHOSAllowed')
+    is_iridium_allowed: bool | None = None
+    is_odometer_allowed: bool | None = None
+    is_trip_detail_allowed: bool | None = None
+    is_ui_allowed: bool | None = Field(default=None, alias='isUIAllowed')
+    is_vin_allowed: bool | None = Field(default=None, alias='isVINAllowed')
+
+
+class CustomFeatures(ResponseModel):
+    """The ``customFeatures`` block: per-account feature toggles.
+
+    Capture-limited: ``autoHos`` is the one key every tracked capture
+    carries, and the name suggests the block holds per-account keys --
+    any unknown key is absorbed by ``extra='ignore'`` today and gets
+    modeled if a capture ever shows it.
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    auto_hos: bool | None = None
+
+
+class Device(ResponseModel):
+    """One GeoTab Device entity: vehicle-installed GO hardware or a trailer.
+
+    A pure mirror of the union of captured fields, everything optional
+    (the shape polymorphism above). Field semantics are GeoTab's; no
+    value is derived or interpreted here. Groups below follow the
+    captured record layout: identity and lifecycle, vehicle identity,
+    fleet bookkeeping, firmware/parameter state, telematics
+    configuration scalars, and the aux-channel arrays.
+
+    Attributes:
+        id: GeoTab's device id -- the seek-paging sort key (hex-suffixed
+            string, ascending).
+        serial_number: Hardware serial; ``""`` on trailer entries.
+        name: The unit's display name.
+        device_type: Hardware generation (``GO7``, ``GO9``; trailers
+            carry the literal string ``"None"``).
+        product_id: Numeric hardware product code; ``-1`` on trailers.
+        active_from: Start of the device's active window (UTC).
+        active_to: End of the active window; ``2050-01-01`` is GeoTab's
+            still-active sentinel, stored as-is.
+        vehicle_identification_number: Registered VIN; ``""`` and a
+            literal ``"?"`` are captured unknown-VIN sentinels.
+        engine_vehicle_identification_number: ECM-reported VIN; same
+            sentinels.
+        tmp_trailer_id: Trailer-entry identifier; absent on tracked
+            vehicles.
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    # Identity and lifecycle.
+    id: str | None = None
+    serial_number: str | None = None
+    name: str | None = None
+    device_type: str | None = None
+    product_id: int | None = None
+    active_from: datetime | None = None
+    active_to: datetime | None = None
+    comment: str | None = None
+    tmp_trailer_id: str | None = None
+
+    # Vehicle identity (VIN sentinels: "" and a literal "?").
+    vehicle_identification_number: str | None = None
+    engine_vehicle_identification_number: str | None = None
+    vin_info_make: str | None = None
+    vin_info_model: str | None = None
+    vin_info_vehicle_type: int | None = None
+    vin_info_year: str | None = None
+    license_plate: str | None = None
+    license_state: str | None = None
+
+    # Fleet bookkeeping.
+    device_plans: list[str] | None = None
+    device_flags: DeviceFlags | None = None
+    custom_features: CustomFeatures | None = None
+    time_zone_id: str | None = None
+    work_time: str | None = None
+    auto_hos: str | None = None
+    go_talk_language: str | None = None
+    pin_device: bool | None = None
+
+    # Firmware / parameter state.
+    major: int | None = None
+    minor: int | None = None
+    parameter_version: int | None = None
+    parameter_version_on_device: int | None = None
+    enable_must_reprogram: bool | None = None
+    time_to_download: str | None = None
+
+    # Telematics configuration scalars.
+    acceleration_warning_threshold: int | None = None
+    accelerometer_threshold_warning_factor: int | None = None
+    braking_warning_threshold: int | None = None
+    cornering_warning_threshold: int | None = None
+    communication_threshold_interval_moving: int | None = None
+    communication_threshold_interval_stationary: int | None = None
+    disable_buzzer: bool | None = None
+    disable_sleeper_berth: bool | None = None
+    enable_beep_on_dangerous_driving: bool | None = None
+    enable_beep_on_idle: bool | None = None
+    enable_beep_on_rpm: bool | None = None
+    enable_control_external_relay: bool | None = None
+    enable_speed_warning: bool | None = None
+    engine_hour_offset: int | None = None
+    engine_type: str | None = None
+    ensure_hot_start: bool | None = None
+    external_device_shut_down_delay: int | None = None
+    force_active_tracking: bool | None = None
+    fuel_tank_capacity: int | None = None
+    gps_off_delay: int | None = None
+    idle_minutes: int | None = None
+    immobilize_arming: int | None = None
+    immobilize_unit: bool | None = None
+    is_active_tracking_enabled: bool | None = None
+    is_continuous_connect_enabled: bool | None = None
+    is_driver_seatbelt_warning_on: bool | None = None
+    is_iox_connection_enabled: bool | None = None
+    is_passenger_seatbelt_warning_on: bool | None = None
+    is_reverse_detect_on: bool | None = None
+    is_speed_indicator: bool | None = None
+    max_seconds_between_logs: int | None = None
+    min_accident_speed: int | None = None
+    obd_alert_enabled: bool | None = None
+    odometer_factor: float | None = None
+    odometer_offset: float | None = None
+    rpm_value: int | None = None
+    seatbelt_warning_speed: int | None = None
+    speeding_off: int | None = None
+    speeding_on: int | None = None
+
+    # Aux-channel arrays (fixed-width per hardware generation).
+    aux_warning_speed: list[int] | None = None
+    enable_aux_warning: list[bool] | None = None
+    is_aux_ign_trigger: list[bool] | None = None
+    is_aux_inverted: list[bool] | None = None

fleetpull/models/geotab/driver_change.py

@@ -0,0 +1,102 @@
+# src/fleetpull/models/geotab/driver_change.py
+"""GeoTab DriverChange response model (``GetFeed`` on ``typeName: DriverChange``).
+
+Written from the 2026-07-21 feed wave two census (30-day seeded pulls at
+the probed tenant), never from docs. A DriverChange is one
+driver-to-device assignment event. The type carries a per-record
+``version``, and DriverChange records are user-editable through the
+provider, so re-emission under newer versions 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 (1,114 records), so structural
+requiredness is limited to the record identity — ``id``, ``dateTime``
+(the event time), ``version``, and the primary entity ref (``driver``,
+the entity the type names) — and every other field is optional EVEN
+where the census was total. The observed arms:
+
+- ``driver`` is PROVEN mixed object-or-string (1,114/1,114, both arms
+  observed); its object arm carries ``isDriver`` beside the id, so the
+  ref model mirrors it (null exactly on string-arm rows). ``device``
+  was object-only on this census; both refs ride 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. ``type`` 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 bare_id_to_reference
+
+__all__: list[str] = [
+    'DriverChange',
+    'DriverChangeDeviceRef',
+    'DriverChangeDriverRef',
+]
+
+
+class DriverChangeDeviceRef(ResponseModel):
+    """The assignment's device reference.
+
+    Census-observed as an ``{id}`` object on every record; the shared
+    coercion lifts a bare string defensively (the census-scope lesson).
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    id: str
+
+
+class DriverChangeDriverRef(ResponseModel):
+    """The assignment's driver reference.
+
+    PROVEN mixed on this census: an ``{id, isDriver}`` object or a bare
+    id string (e.g. the ``"UnknownDriverId"`` sentinel); the shared
+    coercion lifts the bare form to ``{"id": <string>}``, so
+    ``is_driver`` is null exactly on string-arm rows.
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    id: str
+    is_driver: bool | None = None
+
+
+class DriverChange(ResponseModel):
+    """One GeoTab driver-to-device assignment event.
+
+    The wave-two conservative mirror (the module docstring's posture):
+    ``id`` / ``date_time`` / ``version`` / ``driver`` required,
+    everything else optional even where census-total.
+
+    Attributes:
+        date_time: The change's UTC instant — the endpoint's event time.
+        device: The assignment's device reference (object-only on this
+            census; defensively lifted).
+        driver: The assignment's driver reference — proven
+            object-or-string, ``is_driver`` null exactly on string-arm
+            rows.
+        id: GeoTab's record id.
+        type: The change-type token (census-open plain str).
+        version: The record's version token — the reconcile key beside
+            ``id``.
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    date_time: datetime
+    device: Annotated[
+        DriverChangeDeviceRef | None, BeforeValidator(bare_id_to_reference)
+    ] = None
+    driver: Annotated[DriverChangeDriverRef, BeforeValidator(bare_id_to_reference)]
+    id: str
+    type: str | None = None
+    version: str

fleetpull/models/geotab/duty_status_log.py

@@ -0,0 +1,200 @@
+# src/fleetpull/models/geotab/duty_status_log.py
+"""GeoTab DutyStatusLog response model (``GetFeed`` on ``typeName: DutyStatusLog``).
+
+Written from the 2026-07-21 feed wave two census (30-day seeded pulls at
+the probed tenant), never from docs. A DutyStatusLog is one HOS
+duty-status event — an EDITABLE log: ``editDateTime`` is the edit
+trail, 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, so structural requiredness is
+limited to the record identity — ``id``, ``dateTime`` (the event
+time), ``version``, and the primary entity ref (``driver``, the log's
+subject) — and every other field is optional EVEN where the census was
+total (2,000/2,000). The observed arms:
+
+- ``device`` and ``driver`` are PROVEN mixed object-or-string
+  (2,000/2,000 each, both arms observed); every reference field rides
+  the shared ``bare_id_to_reference`` lift.
+- ``annotations`` (126/2,000) carried elements that are EXACTLY
+  ``{"id": <str>}`` on every sampled record; the records layer supports
+  list-of-scalar only, so the field is an ID-LIST — ``list[str]`` via a
+  STRICT element lift (``_annotation_ids``): a shape change fails
+  loudly, never silently drops sibling keys. The ids join to the
+  ``annotation_logs`` vertical (feed wave three) for the full
+  annotation records.
+- ``location`` (1,859/2,000) is the shared ``GeotabAddressedLocation``
+  wrapper (DVIRLog is the second consumer; DESIGN §8): it carries a
+  double-nested ``{location: {x, y}}`` COORDINATE arm or an
+  ``{address: {formattedAddress}}`` arm. The 200-sample census saw only
+  coordinates; a 24,860-block live-proof walk found 14 address-arm
+  blocks (the census-scope lesson), so both arms are modeled optional.
+- Mixed int-or-float numerics (``distanceSinceValidCoordinates``,
+  ``engineHours``, ``odometer``) model ``float``.
+
+``dateTime``, ``editDateTime``, and ``verifyDateTime`` are recovered
+tz-aware by validation, the GeoTab sibling idiom. ``deferralStatus``,
+``malfunction``, ``origin``, ``state``, and ``status`` 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 GeotabAddressedLocation, bare_id_to_reference
+from fleetpull.vocabulary import JsonValue
+
+__all__: list[str] = [
+    'DutyStatusLog',
+    'DutyStatusLogDeviceRef',
+    'DutyStatusLogDriverRef',
+]
+
+
+def _annotation_ids(value: JsonValue) -> JsonValue:
+    """Strictly lift the ``annotations`` element list to its id list.
+
+    The census shows elements carrying ONLY ``{"id": <str>}``; the lift
+    is deliberately STRICT so a wire-shape change fails validation
+    loudly instead of silently dropping sibling keys the model never
+    saw (the loud-failure doctrine).
+
+    Args:
+        value: The raw ``annotations`` wire value.
+
+    Returns:
+        ``None`` passthrough (the field is optional), or the element
+        ids: a bare-string element passes verbatim, an EXACTLY
+        ``{'id': <str>}`` element becomes its id.
+
+    Raises:
+        ValueError: The value is not a list, or an element is neither a
+            bare string nor exactly ``{'id': <str>}`` (extra keys, other
+            shapes); the message names the offending element.
+    """
+    if value is None:
+        return None
+    if not isinstance(value, list):
+        raise ValueError(f'annotations must be a list, got {type(value).__name__}')
+    lifted: list[JsonValue] = []
+    for element in value:
+        if isinstance(element, str):
+            lifted.append(element)
+            continue
+        if (
+            isinstance(element, dict)
+            and set(element) == {'id'}
+            and isinstance(element['id'], str)
+        ):
+            lifted.append(element['id'])
+            continue
+        raise ValueError(
+            f'annotations element must be a bare id string or exactly '
+            f"{{'id': <str>}}, got {element!r}"
+        )
+    return lifted
+
+
+class DutyStatusLogDeviceRef(ResponseModel):
+    """The recording device's reference.
+
+    PROVEN mixed on this census: an ``{id}`` object or a bare id
+    string, the bare form lifted by the shared coercion so both arms
+    land as ``device__id``.
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    id: str
+
+
+class DutyStatusLogDriverRef(ResponseModel):
+    """The log's driver reference.
+
+    PROVEN mixed on this census: an ``{id}`` object or a bare id
+    string (e.g. the ``"UnknownDriverId"`` sentinel), the bare form
+    lifted by the shared coercion so both arms land as ``driver__id``.
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    id: str
+
+
+class DutyStatusLog(ResponseModel):
+    """One GeoTab HOS duty-status event from the DutyStatusLog 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:
+        annotations: The annotation-log ids attached to the event — the
+            strict id-list reduction (126/2,000 carriers); join to the
+            ``annotation_logs`` vertical for the records.
+        date_time: The event's UTC instant — the endpoint's event time.
+        deferral_minutes: Deferred off-duty minutes.
+        deferral_status: The deferral-status token (census-open).
+        device: The recording device's reference — proven
+            object-or-string.
+        distance_since_valid_coordinates: Distance since the last valid
+            GPS fix (308/2,000; mixed int-or-float, modeled float).
+        driver: The log's driver reference — proven object-or-string.
+        edit_date_time: The last edit's UTC instant — the edit trail.
+        engine_hours: The engine-hours reading (1,844/2,000; mixed
+            int-or-float, modeled float).
+        event_code: The ELD event code (1,623/2,000).
+        event_record_status: The ELD event-record status.
+        event_type: The ELD event type (1,753/2,000).
+        id: GeoTab's record id.
+        is_ignored: Whether the log is ignored.
+        is_transitioning: Whether the log is mid-transition.
+        location: The event's nested location (1,859/2,000; the shared
+            wrapper — a ``{x, y}`` coordinate arm, x longitude / y
+            latitude, or a ``formattedAddress`` arm).
+        malfunction: The malfunction token (census-open plain str).
+        odometer: The odometer reading (1,863/2,000; mixed
+            int-or-float, modeled float).
+        origin: The origin token (census-open plain str).
+        sequence: The ELD sequence token (1,753/2,000).
+        state: The state token (census-open plain str).
+        status: The duty-status token (census-open plain str).
+        verify_date_time: The driver-verification UTC instant
+            (765/2,000).
+        version: The record's version token — the editable-log
+            reconcile key beside ``id``.
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    annotations: Annotated[list[str] | None, BeforeValidator(_annotation_ids)] = None
+    date_time: datetime
+    deferral_minutes: int | None = None
+    deferral_status: str | None = None
+    device: Annotated[
+        DutyStatusLogDeviceRef | None, BeforeValidator(bare_id_to_reference)
+    ] = None
+    distance_since_valid_coordinates: float | None = None
+    driver: Annotated[DutyStatusLogDriverRef, BeforeValidator(bare_id_to_reference)]
+    edit_date_time: datetime | None = None
+    engine_hours: float | None = None
+    event_code: int | None = None
+    event_record_status: int | None = None
+    event_type: int | None = None
+    id: str
+    is_ignored: bool | None = None
+    is_transitioning: bool | None = None
+    location: GeotabAddressedLocation | None = None
+    malfunction: str | None = None
+    odometer: float | None = None
+    origin: str | None = None
+    sequence: str | None = None
+    state: str | None = None
+    status: str | None = None
+    verify_date_time: datetime | None = None
+    version: str