fleetpull 0.1.0__py3-none-any.whl

fleetpull/models/geotab/shipment_log.py

@@ -0,0 +1,105 @@
+# src/fleetpull/models/geotab/shipment_log.py
+"""GeoTab ShipmentLog response model (``GetFeed`` on ``typeName: ShipmentLog``).
+
+Written from the 2026-07-21 feed wave three SCALE census (walked at
+scale at the probed tenant), never from docs. A ShipmentLog is one
+shipment-manifest record attached to a driver and device over an active
+window — a versioned feed, 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 (2,771 records), so structural
+requiredness is limited to the record identity — ``id``, ``dateTime``
+(the event time), ``version``, and the primary entity ref (``driver``,
+consistent with the log family) — and every other field is optional
+EVEN where the census was total. The observed arms:
+
+- ``device`` and ``driver`` were object-only (``{id}``) at scale; both
+  ride the shared ``bare_id_to_reference`` lift regardless (the
+  census-scope lesson, DESIGN §8: a tenant census cannot prove the
+  string arm absent).
+
+``activeFrom``/``activeTo`` (the shipment's active window) and
+``dateTime`` are recovered tz-aware by validation, the GeoTab sibling
+idiom. ``commodity``, ``documentNumber``, and ``shipperName`` are
+census-open free-text strings.
+"""
+
+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] = [
+    'ShipmentLog',
+    'ShipmentLogDeviceRef',
+    'ShipmentLogDriverRef',
+]
+
+
+class ShipmentLogDeviceRef(ResponseModel):
+    """The shipment's device reference.
+
+    Census-observed as an ``{id}`` object at scale; the shared coercion
+    lifts a bare string defensively (the census-scope lesson).
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    id: str
+
+
+class ShipmentLogDriverRef(ResponseModel):
+    """The shipment's driver reference.
+
+    Census-observed as an ``{id}`` object at scale; the shared coercion
+    lifts a bare string defensively (the census-scope lesson).
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    id: str
+
+
+class ShipmentLog(ResponseModel):
+    """One GeoTab shipment-manifest record from the ShipmentLog 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:
+        active_from: The shipment window's UTC start.
+        active_to: The shipment window's UTC end.
+        commodity: The shipped commodity (census-open str).
+        date_time: The record's UTC instant — the endpoint's event time.
+        device: The shipment's device reference (object-only at scale;
+            defensively lifted).
+        document_number: The manifest document number (census-open str).
+        driver: The shipment's driver reference (object-only at scale;
+            defensively lifted).
+        id: GeoTab's record id.
+        shipper_name: The shipper company name (census-open str).
+        version: The record's version token — the reconcile key beside
+            ``id``.
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    active_from: datetime | None = None
+    active_to: datetime | None = None
+    commodity: str | None = None
+    date_time: datetime
+    device: Annotated[
+        ShipmentLogDeviceRef | None, BeforeValidator(bare_id_to_reference)
+    ] = None
+    document_number: str | None = None
+    driver: Annotated[ShipmentLogDriverRef, BeforeValidator(bare_id_to_reference)]
+    id: str
+    shipper_name: str | None = None
+    version: str

fleetpull/models/geotab/status_data.py

@@ -0,0 +1,108 @@
+# src/fleetpull/models/geotab/status_data.py
+"""GeoTab StatusData response model (``GetFeed`` on ``typeName: StatusData``).
+
+Written from the 2026-07-21 live probe session, never from docs. A
+StatusData record is one engine-diagnostic reading — the LogRecord
+stream's sibling ACTIVE feed, with one deliberate asymmetry: StatusData
+DOES carry a per-record ``version`` (LogRecord carries none), observed on
+every census record and mirrored — the consumer still reconciles this
+active feed by ``id``, the version riding along as wire truth
+(DESIGN §4).
+
+Requiredness posture: the census is a large uniform whole-page total —
+2,000/2,000 records carried every key — so every field is required with
+no nullable arm (none was observed). The census is a TENANT-SCOPED
+observation (DESIGN §8). Volume on the probed tenant is ~24,500
+records/hour, which is why the leaf declares the 50,000
+protocol-maximum ``resultsLimit``.
+
+``dateTime`` (the event time) is recovered tz-aware by validation, the
+GeoTab sibling idiom. ``data`` — the diagnostic's value — is MIXED
+int-or-float on the wire and modeled ``float`` (the one dtype that
+carries both arms losslessly). ``controller`` is STRING-OR-OBJECT:
+the ``"ControllerNoneId"`` sentinel string on 49,745 of a 50,000-record
+live full-page census (2026-07-21) and an ``{id}`` reference on the
+other 255 — the Trip ``UnknownDriverId`` mechanism verbatim (the
+initial one-hour census saw only the sentinel arm; the live proof's
+full walk surfaced the object arm — a census-scope lesson recorded in
+the section 8 block). The shared ``bare_id_to_reference`` coercion
+lifts the sentinel to ``{"id": <string>}``.
+"""
+
+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] = [
+    'StatusData',
+    'StatusDataControllerRef',
+    'StatusDataDeviceRef',
+    'StatusDataDiagnosticRef',
+]
+
+
+class StatusDataControllerRef(ResponseModel):
+    """The source controller reference.
+
+    Arrives as an ``{id}`` object (255 of the 50,000-record live
+    census) or the bare ``"ControllerNoneId"`` sentinel string
+    (49,745), which the shared coercion lifts to ``{"id": <string>}``.
+    """
+
+    id: str | None = None
+
+
+class StatusDataDeviceRef(ResponseModel):
+    """The reading's device reference: the id alone, on every record."""
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    id: str
+
+
+class StatusDataDiagnosticRef(ResponseModel):
+    """The reading's diagnostic reference: the id alone, on every record."""
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    id: str
+
+
+class StatusData(ResponseModel):
+    """One GeoTab diagnostic reading from the StatusData feed.
+
+    A pure mirror of the 2,000/2,000 whole-page census: seven keys, all
+    present and non-null on every record, so all seven are required.
+
+    Attributes:
+        controller: The source controller reference — an ``{id}``
+            object or the bare ``"ControllerNoneId"`` sentinel string,
+            lifted by the shared coercion so the sentinel lands as
+            ``controller__id`` (census-open
+            plain str).
+        data: The diagnostic's value — mixed int-or-float on the wire,
+            modeled float.
+        date_time: The reading's UTC instant — the endpoint's event time.
+        device: The emitting vehicle unit's reference.
+        diagnostic: The diagnostic definition's reference.
+        id: GeoTab's record id.
+        version: The record's version token — present on this active
+            feed (unlike LogRecord), mirrored as wire truth.
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    controller: Annotated[
+        StatusDataControllerRef, BeforeValidator(bare_id_to_reference)
+    ]
+    data: float
+    date_time: datetime
+    device: StatusDataDeviceRef
+    diagnostic: StatusDataDiagnosticRef
+    id: str
+    version: str

fleetpull/models/geotab/text_message.py

@@ -0,0 +1,125 @@
+# src/fleetpull/models/geotab/text_message.py
+"""GeoTab TextMessage response model (``GetFeed`` on ``typeName: TextMessage``).
+
+Written from the 2026-07-21 feed wave three SCALE census (walked at
+scale at the probed tenant), never from docs. A TextMessage is one
+dispatch message between the office and a vehicle.
+
+NO per-record ``version`` key AND NO ``dateTime`` key — the append-only
+asymmetry (FaultData/LogRecord): append-only storage is trivially
+complete and the consumer reconciles by ``id`` alone (DESIGN §4). The
+event-time identity is ``sent`` (the send instant, 25,000/25,000), so
+the binding anchors ``event_time_column='sent'`` and ``sent`` is a
+REQUIRED datetime — storage partitions on it. The feed's own
+``toVersion`` still advances (delivered/read receipts re-emit a message
+under a newer FEED version); those re-emissions are stored-as-emitted,
+the feed's versioning rather than a per-record ``version`` key.
+
+Requiredness posture (the wave-two conservative stance, DESIGN §8): the
+census is a TENANT-SCOPED observation (25,000 records), so structural
+requiredness is limited to the record identity — ``id`` and ``sent``
+(the event time) — and every other field is optional EVEN where the
+census was total. The observed arms:
+
+- ``device`` was object-only (``{id}``) at scale; it rides the shared
+  ``bare_id_to_reference`` lift (the census-scope lesson). It is
+  OPTIONAL — a text message has no required primary entity ref.
+- ``messageContent`` is a NESTED block ``{contentType, ids}``; both
+  keys are required WITHIN the block on the nested-block-required
+  convention (200/200 nested, 25,000/25,000 present). ``ids`` is a
+  PLAIN ``list[str]`` — the elements ARE strings on the wire, so this
+  is a §9 list-of-scalar direct field, NOT the DutyStatusLog
+  ``annotations`` id-object reduction (there the elements were
+  ``{id}`` objects needing a strict lift).
+- ``delivered`` and ``read`` are receipt datetimes present on
+  24,995/25,000 — optional.
+
+``activeFrom``/``activeTo``, ``delivered``, ``read``, and ``sent`` are
+recovered tz-aware by validation, the GeoTab sibling idiom.
+``contentType`` and ``recipient`` are census-open strings;
+``isDirectionToVehicle`` is a bool, ``messageSize`` an int.
+"""
+
+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] = [
+    'TextMessage',
+    'TextMessageContent',
+    'TextMessageDeviceRef',
+]
+
+
+class TextMessageDeviceRef(ResponseModel):
+    """The message's device reference (the vehicle end of the exchange).
+
+    Census-observed as an ``{id}`` object at scale; the shared coercion
+    lifts a bare string defensively (the census-scope lesson).
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    id: str
+
+
+class TextMessageContent(ResponseModel):
+    """The ``messageContent`` block: the message payload descriptor.
+
+    Both keys are required WITHIN the block (the nested-block-required
+    convention): a present ``messageContent`` block missing either is a
+    shape change and must fail loudly. ``ids`` is a direct
+    ``list[str]`` (the elements are strings on the wire, a §9
+    list-of-scalar), NOT the ``annotations`` id-object reduction.
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    content_type: str
+    ids: list[str]
+
+
+class TextMessage(ResponseModel):
+    """One GeoTab dispatch message from the TextMessage feed.
+
+    The wave-two conservative mirror with the append-only asymmetry (the
+    module docstring's posture): ``id`` / ``sent`` required, NO
+    per-record ``version``, everything else optional even where
+    census-total.
+
+    Attributes:
+        active_from: The message window's UTC start.
+        active_to: The message window's UTC end.
+        delivered: The delivery-receipt UTC instant (24,995/25,000).
+        device: The message's device reference (object-only at scale;
+            defensively lifted). Optional — no required primary ref.
+        id: GeoTab's record id.
+        is_direction_to_vehicle: Whether the message is office→vehicle.
+        message_content: The message payload descriptor block.
+        message_size: The message payload size.
+        read: The read-receipt UTC instant (24,995/25,000).
+        recipient: The message recipient address (census-open str).
+        sent: The send UTC instant — the endpoint's event time (the
+            event-time identity, in place of the absent ``dateTime``).
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    active_from: datetime | None = None
+    active_to: datetime | None = None
+    delivered: datetime | None = None
+    device: Annotated[
+        TextMessageDeviceRef | None, BeforeValidator(bare_id_to_reference)
+    ] = None
+    id: str
+    is_direction_to_vehicle: bool | None = None
+    message_content: TextMessageContent | None = None
+    message_size: int | None = None
+    read: datetime | None = None
+    recipient: str | None = None
+    sent: datetime

fleetpull/models/geotab/trip.py

@@ -0,0 +1,162 @@
+# src/fleetpull/models/geotab/trip.py
+"""GeoTab Trip response model (JSON-RPC ``Get`` on ``typeName: Trip``).
+
+Written from captured live responses (2026-07-13 probe session), never
+from docs. A Trip is one engine-on movement interval plus its trailing
+stop window; the model is the union of observed fields with every field
+optional, a pure mirror -- no value is derived or interpreted here.
+
+Interval semantics (12 of 12 captured records):
+``driving_duration = stop - start``; ``stop_duration = next_trip_start
+- stop``; ``idling_duration`` measures engine-on time WITHIN the
+post-trip stop window, never within the drive. The zero-distance
+degenerate shape has ``start == stop``, ``driving_duration`` of zero,
+and NO ``averageSpeed`` key at all -- absence is a shape, landing as a
+null.
+
+Units (delta-arithmetic confirmed against the captures):
+
+- distances (``distance``, ``after_hours_distance``, ``work_distance``)
+  are kilometers;
+- speeds (``average_speed``, ``maximum_speed``) are km/h;
+- ``odometer`` is METERS (confirmed by delta arithmetic against a
+  trip's own km distance);
+- ``engine_hours`` is SECONDS despite the name -- a captured 26.1M
+  "hours" is 7,251 real engine-hours. The value is stored verbatim;
+  renaming or converting it would break the pure-mirror rule, so the
+  trap is documented here and at every mention instead.
+
+Durations arrive as .NET TimeSpan strings, parsed at the boundary
+through ``GeotabTimeSpan`` (``models/geotab/shared.py``); day-prefixed
+spans (``"4.16:41:16"``) occur whenever a stop window crosses days.
+
+The ``driver`` reference arrives as either an object
+(``{"id": ..., "isDriver": true}``) or the bare known-id sentinel
+string ``"UnknownDriverId"``; the shared ``bare_id_to_reference``
+coercion lifts any bare string to ``{"id": <string>}`` verbatim, so the
+sentinel lands as ``driver__id`` and ``driver__is_driver`` stays null
+on sentinel rows. ``maximum_speed`` and the ``speed_range1/2/3`` trio
+are modeled ``float`` although every captured value is integral: they
+are physical measurements like ``average_speed``, and JSON numbers do
+not distinguish ``94`` from ``94.0`` (``speed_range*`` semantics are
+unconfirmed -- captured all-zero).
+"""
+
+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] = ['Trip', 'TripDeviceRef', 'TripDriverRef', 'TripStopPoint']
+
+
+class TripDeviceRef(ResponseModel):
+    """The trip's device reference: the id alone."""
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    id: str | None = None
+
+
+class TripDriverRef(ResponseModel):
+    """The trip's driver reference.
+
+    Arrives as an object or the bare ``"UnknownDriverId"`` sentinel
+    string; the ``Trip.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 | None = None
+    is_driver: bool | None = None
+
+
+class TripStopPoint(ResponseModel):
+    """The trip's stop coordinate: ``x`` longitude, ``y`` latitude."""
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    x: float | None = None
+    y: float | None = None
+
+
+class Trip(ResponseModel):
+    """One GeoTab Trip: a movement interval and its trailing stop window.
+
+    A pure mirror of the union of captured fields, everything optional.
+    Groups below follow the captured record layout: identity, the
+    interval, durations, distances and speeds, counters, and flags. The
+    unit traps (``engine_hours`` is seconds, ``odometer`` meters) are
+    documented in the module docstring.
+
+    Attributes:
+        id: GeoTab's trip id -- the seek-paging sort key.
+        version: The record's version token (ids and versions share one
+            counter space).
+        device: The vehicle reference.
+        driver: The driver reference; the bare ``"UnknownDriverId"``
+            sentinel lands as ``driver.id`` verbatim.
+        start: Trip start (UTC) -- the endpoint's event time.
+        stop: Trip end (UTC); equals ``start`` on the zero-distance
+            degenerate shape.
+        next_trip_start: The following trip's start; bounds this trip's
+            stop window.
+        engine_hours: Cumulative engine SECONDS despite the name (the
+            module-docstring trap), stored verbatim.
+        odometer: Cumulative odometer in METERS, stored verbatim.
+        average_speed: Mean speed in km/h; the key is absent on
+            zero-distance trips (lands null).
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    # Identity.
+    id: str | None = None
+    version: str | None = None
+    device: TripDeviceRef | None = None
+    driver: Annotated[TripDriverRef | None, BeforeValidator(bare_id_to_reference)] = (
+        None
+    )
+
+    # The interval.
+    start: datetime | None = None
+    stop: datetime | None = None
+    next_trip_start: datetime | None = None
+
+    # Durations (.NET TimeSpan strings on the wire).
+    driving_duration: GeotabTimeSpan = None
+    stop_duration: GeotabTimeSpan = None
+    idling_duration: GeotabTimeSpan = None
+    after_hours_driving_duration: GeotabTimeSpan = None
+    after_hours_stop_duration: GeotabTimeSpan = None
+    work_driving_duration: GeotabTimeSpan = None
+    work_stop_duration: GeotabTimeSpan = None
+    speed_range1_duration: GeotabTimeSpan = None
+    speed_range2_duration: GeotabTimeSpan = None
+    speed_range3_duration: GeotabTimeSpan = None
+
+    # Distances (km) and speeds (km/h).
+    distance: float | None = None
+    after_hours_distance: float | None = None
+    work_distance: float | None = None
+    average_speed: float | None = None
+    maximum_speed: float | None = None
+    speed_range1: float | None = None
+    speed_range2: float | None = None
+    speed_range3: float | None = None
+
+    # Cumulative counters (the unit traps: seconds and meters).
+    engine_hours: float | None = None
+    odometer: float | None = None
+
+    # Flags and the stop coordinate.
+    after_hours_start: bool | None = None
+    after_hours_end: bool | None = None
+    is_seat_belt_off: bool | None = None
+    stop_point: TripStopPoint | None = None

fleetpull/models/geotab/user.py

@@ -0,0 +1,187 @@
+# src/fleetpull/models/geotab/user.py
+"""GeoTab User response model (JSON-RPC ``Get`` on ``typeName: User``).
+
+Written from captured live responses (2026-07-16 probe session: a
+full-population sweep of all 157 accounts plus seven captured record
+variants), never from docs. Drivers ARE users in GeoTab -- ``isDriver``
+splits the population (129/157 captured) and the driver-only key block
+(``licenseNumber``, ``licenseProvince``, ``viewDriversOwnDataOnly``)
+is ABSENT, not null, on non-driver accounts; the sweep observed no null
+value and no type variance on any key, so optionality here is
+absence-shaped. Fields the sweep proved on every record are required;
+the partial-presence fields are optional (presence counts in the
+attribute docs).
+
+Excluded fields (``extra='ignore'`` makes exclusion exactly "don't
+model it"):
+
+- ``activeDashboardReports``, ``activeDefaultDashboards``,
+  ``availableDashboardReports``, ``bookmarks``, ``cannedResponseOptions``,
+  ``companyGroups``, ``driverGroups``, ``jobPriorities``, ``keys``,
+  ``mapViews``, ``mediaFiles``, ``privateUserGroups``, ``reportGroups``,
+  ``securityGroups`` -- lists; the records layer's schema derivation
+  (DESIGN section 9) supports scalars, enums, ``list[scalar]``, and
+  nested models only, and these are UI/grouping plumbing whose struct
+  shapes have no honest column until the ``list[nested model]``
+  derivation vertical lands (the Device exclusion precedent).
+- ``iAMMetadata`` -- identity-provider plumbing (an IAM GUID, a
+  connection name, two provisioning flags), present on only 42/157
+  swept records.
+
+Every value mirrors verbatim, empty strings included -- the model
+preserves ``""`` faithfully from the wire, and empty strings normalize
+to null once, at the DataFrame boundary (DESIGN section 9). Sentinels
+likewise: ``activeTo`` of ``2050-01-01`` is GeoTab's still-active
+sentinel, and ``hosRuleSet`` carries the literal string ``"None"`` on
+non-driving accounts -- the provider's vocabulary, never interpreted.
+
+Wire keys are camelCase; fields are snake_case via the ``to_camel``
+alias generator. The five acronym keys the generator cannot produce
+(``acceptedEULA``, ``isEULAAccepted``, ``isExemptHOSEnabled``,
+``maxPCDistancePerDay``, ``wifiEULA``) carry explicit alias overrides,
+each pinned against a captured value in the model tests (the Device
+acronym-trap precedent).
+"""
+
+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] = ['User', 'UserAccessGroupFilterRef']
+
+
+class UserAccessGroupFilterRef(ResponseModel):
+    """The ``accessGroupFilter`` reference: a data-scope filter by id.
+
+    Observed on exactly one of the 157 swept records (2026-07-16) -- an
+    account whose visibility is restricted to an access group. The id is
+    the ``a``-prefixed GUID-like form (the ExceptionEvent id shape), a
+    pure reference mirrored as-is.
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    id: str
+
+
+class User(ResponseModel):
+    """One GeoTab User entity: a console account, driver or otherwise.
+
+    A pure mirror of the captured scalar fields. Field semantics are
+    GeoTab's; no value is derived or interpreted here. Groups below
+    follow the captured record layout: identity and lifecycle, person
+    and contact, the driver-only block, company/authority identity,
+    locale and display preferences, HOS and driving flags, and the
+    notification/UI flags.
+
+    Attributes:
+        id: GeoTab's user id -- the seek-paging sort key (hex-suffixed
+            string, ascending; the id space trip ``driver`` refs point
+            into).
+        name: The login identifier -- an email address on most captured
+            accounts, a bare username on one.
+        active_from: Start of the account's active window (UTC).
+        active_to: End of the active window; ``2050-01-01`` is GeoTab's
+            still-active sentinel, stored as-is.
+        last_access_date: Last console/app access (UTC); absent on one
+            never-accessed swept account (156/157).
+        is_driver: Whether the account is a driver -- the key whose
+            value predicts the driver-only block's presence.
+        license_number: Driver's license number; driver-only (129/157).
+        license_province: Driver's license state/province; driver-only
+            (129/157).
+        view_drivers_own_data_only: Driver data-visibility restriction;
+            driver-only (129/157).
+        access_group_filter: Data-scope filter reference; observed on
+            one swept record (1/157).
+        max_pc_distance_per_day: Personal-conveyance distance cap;
+            ``0`` captured everywhere it appears (126/157, not aligned
+            with the driver split).
+        hos_rule_set: HOS ruleset name; the literal string ``"None"``
+            on non-driving accounts, mirrored verbatim.
+        carrier_number: Motor-carrier number; captured populated on
+            driver accounts, ``""`` elsewhere, mirrored verbatim.
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    # Identity and lifecycle.
+    id: str
+    name: str
+    active_from: datetime
+    active_to: datetime
+    last_access_date: datetime | None = None
+    is_auto_added: bool
+    user_authentication_type: str
+    change_password: bool
+    access_group_filter: UserAccessGroupFilterRef | None = None
+
+    # Person and contact.
+    first_name: str
+    last_name: str
+    designation: str
+    employee_no: str
+    phone_number: str
+    phone_number_extension: str
+    comment: str
+
+    # Driver-only block (absent, not null, on non-driver accounts).
+    is_driver: bool
+    license_number: str | None = None
+    license_province: str | None = None
+    view_drivers_own_data_only: bool | None = None
+
+    # Company / authority identity.
+    company_name: str
+    company_address: str
+    authority_name: str
+    authority_address: str
+    carrier_number: str
+
+    # Locale and display preferences.
+    language: str
+    country_code: str
+    time_zone_id: str
+    date_format: str
+    first_day_of_week: str
+    display_currency: str
+    is_metric: bool
+    fuel_economy_unit: str
+    electric_energy_economy_unit: str
+    default_page: str
+    default_map_engine: str
+    default_google_map_style: str
+    default_here_map_style: str
+    default_open_street_map_style: str
+    zone_display_mode: str
+    feature_preview: str
+
+    # HOS and driving flags.
+    hos_rule_set: str
+    is_exempt_hos_enabled: bool = Field(alias='isExemptHOSEnabled')
+    is_yard_move_enabled: bool
+    is_personal_conveyance_enabled: bool
+    is_adverse_driving_enabled: bool
+    max_pc_distance_per_day: int | None = Field(
+        default=None, alias='maxPCDistancePerDay'
+    )
+
+    # EULA state.
+    is_eula_accepted: bool = Field(alias='isEULAAccepted')
+    accepted_eula: int = Field(alias='acceptedEULA')
+    wifi_eula: int = Field(alias='wifiEULA')
+
+    # Notification and UI flags.
+    is_email_report_enabled: bool
+    is_maintenance_notification_enabled: bool
+    is_service_disruption_notifications_enabled: bool
+    sms_notifications_opt_in: bool
+    whats_app_notifications_opt_in: bool
+    is_news_enabled: bool
+    is_labs_enabled: bool
+    is_ace_disclaimer_disabled: bool
+    show_click_once_warning: bool
+    show_rate_this_app: bool