fleetpull 0.1.0__py3-none-any.whl

fleetpull/models/samsara/__init__.py

@@ -0,0 +1,108 @@
+# src/fleetpull/models/samsara/__init__.py
+"""Samsara response models; the face re-exports each endpoint module's models."""
+
+from fleetpull.models.samsara.address import (
+    Address,
+    AddressGeofence,
+    AddressGeofenceCircle,
+    AddressGeofenceSettings,
+)
+from fleetpull.models.samsara.asset_location import (
+    AssetLocation,
+    AssetLocationAssetRef,
+    AssetLocationFix,
+)
+from fleetpull.models.samsara.driver import (
+    Driver,
+    DriverActivationStatus,
+    DriverCarrierSettings,
+    DriverHosSetting,
+    DriverStaticAssignedVehicleRef,
+    DriverTagRef,
+)
+from fleetpull.models.samsara.driver_fuel_energy_report import (
+    DriverFuelEnergyCost,
+    DriverFuelEnergyDriverRef,
+    DriverFuelEnergyReport,
+)
+from fleetpull.models.samsara.driver_vehicle_assignment import (
+    AssignmentDriverRef,
+    AssignmentVehicleExternalIds,
+    AssignmentVehicleRef,
+    DriverVehicleAssignment,
+)
+from fleetpull.models.samsara.engine_state import EngineState
+from fleetpull.models.samsara.gps_reading import (
+    GpsReading,
+    GpsReadingAddressRef,
+    GpsReadingReverseGeo,
+)
+from fleetpull.models.samsara.idling_event import (
+    AssetRef,
+    FuelCost,
+    IdlingAddress,
+    IdlingEvent,
+    OperatorRef,
+)
+from fleetpull.models.samsara.odometer_reading import OdometerReading
+from fleetpull.models.samsara.trip import (
+    Trip,
+    TripAddress,
+    TripCoordinates,
+)
+from fleetpull.models.samsara.vehicle import (
+    Vehicle,
+    VehicleExternalIds,
+    VehicleGatewayRef,
+    VehicleStaticAssignedDriverRef,
+)
+from fleetpull.models.samsara.vehicle_fuel_energy_report import (
+    VehicleFuelEnergyCost,
+    VehicleFuelEnergyExternalIds,
+    VehicleFuelEnergyReport,
+    VehicleFuelEnergyVehicleRef,
+)
+
+__all__: list[str] = [
+    'Address',
+    'AddressGeofence',
+    'AddressGeofenceCircle',
+    'AddressGeofenceSettings',
+    'AssetLocation',
+    'AssetLocationAssetRef',
+    'AssetLocationFix',
+    'AssetRef',
+    'AssignmentDriverRef',
+    'AssignmentVehicleExternalIds',
+    'AssignmentVehicleRef',
+    'Driver',
+    'DriverActivationStatus',
+    'DriverCarrierSettings',
+    'DriverFuelEnergyCost',
+    'DriverFuelEnergyDriverRef',
+    'DriverFuelEnergyReport',
+    'DriverHosSetting',
+    'DriverStaticAssignedVehicleRef',
+    'DriverTagRef',
+    'DriverVehicleAssignment',
+    'EngineState',
+    'FuelCost',
+    'GpsReading',
+    'GpsReadingAddressRef',
+    'GpsReadingReverseGeo',
+    'IdlingAddress',
+    'IdlingEvent',
+    'OdometerReading',
+    'OperatorRef',
+    'Trip',
+    'TripAddress',
+    'TripCoordinates',
+    'Vehicle',
+    'VehicleExternalIds',
+    'VehicleFuelEnergyCost',
+    'VehicleFuelEnergyExternalIds',
+    'VehicleFuelEnergyReport',
+    'VehicleFuelEnergyVehicleRef',
+    'VehicleGatewayRef',
+    'VehicleStaticAssignedDriverRef',
+]

fleetpull/models/samsara/address.py

@@ -0,0 +1,149 @@
+# src/fleetpull/models/samsara/address.py
+"""Samsara Address response model (``GET /addresses``).
+
+Written from captured live responses (2026-07-20 probe session: a
+full-population walk -- one page, all 25 records), never from docs. The
+walk observed no null value anywhere -- Samsara omits absent keys
+rather than nulling them (the vehicles posture). Because the walk was
+the whole population, the vehicles optionality posture applies: the
+seven 25/25 keys (``id``, ``name``, ``createdAtTime``,
+``formattedAddress``, ``latitude``, ``longitude``, ``geofence``) are
+required; ``addressTypes`` (20/25) is optional. ``createdAtTime`` is
+UTC ISO-8601 with milliseconds, recovered as a tz-aware datetime by
+Pydantic's standard parse.
+
+Within the required ``geofence`` block (presence out of 25 blocks):
+``circle`` 1/25 (``{latitude, longitude, radiusMeters}``, all three in
+the one carrying block), ``polygon`` 24/25, ``settings`` 13/25
+(``{showAddresses}``, present in every carrying block). ``circle`` and
+``polygon`` were mutually exclusive in capture (1 vs 24, never both) --
+both are mirrored as independent optionals with NO XOR enforcement
+(mirror, never interpret).
+
+Excluded fields (``extra='ignore'`` makes exclusion exactly "don't
+model it"):
+
+- ``tags`` -- a list of tag objects (9/25); the records layer's schema
+  derivation supports scalars, enums, ``list[scalar]``, and nested
+  models only (the GeoTab Device/User exclusion precedent, same as the
+  vehicles/drivers models) -- modeled when the list-of-structs
+  derivation vertical lands.
+- ``geofence.polygon`` -- excluded WHOLESALE (24/25): its ONLY key is
+  ``vertices``, a list of ``{latitude, longitude}`` objects, so the
+  same exclusion precedent applies one level down and an empty polygon
+  model would mirror nothing. The top-level ``latitude``/``longitude``
+  still carry the address's center point on every record, so a
+  polygon-fenced address keeps its location while the boundary awaits
+  the list-of-structs vertical.
+
+Wire keys are camelCase; fields are snake_case via the ``to_camel``
+alias generator.
+"""
+
+from datetime import datetime
+
+from pydantic import ConfigDict
+from pydantic.alias_generators import to_camel
+
+from fleetpull.model_contract import ResponseModel
+
+__all__: list[str] = [
+    'Address',
+    'AddressGeofence',
+    'AddressGeofenceCircle',
+    'AddressGeofenceSettings',
+]
+
+
+class AddressGeofenceCircle(ResponseModel):
+    """The ``geofence.circle`` block: a circular boundary (1/25).
+
+    All three keys were present in the one carrying block. Mutually
+    exclusive with ``polygon`` in capture, mirrored without enforcement
+    (module docstring).
+
+    Attributes:
+        latitude: The circle center's latitude, decimal degrees.
+        longitude: The circle center's longitude, decimal degrees.
+        radius_meters: The circle's radius in meters, a bare int.
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    latitude: float
+    longitude: float
+    radius_meters: int
+
+
+class AddressGeofenceSettings(ResponseModel):
+    """The ``geofence.settings`` block: geofence display settings (13/25).
+
+    Attributes:
+        show_addresses: Whether the geofence displays addresses --
+            present in every carrying block.
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    show_addresses: bool
+
+
+class AddressGeofence(ResponseModel):
+    """The ``geofence`` block: boundary and settings (present on all 25).
+
+    Models ``circle`` and ``settings`` only -- ``polygon`` is excluded
+    wholesale because its only content is a list-of-objects vertex list
+    (module docstring), so a polygon-fenced address validates to a
+    geofence with both modeled fields ``None`` while its center point
+    survives on the parent's ``latitude``/``longitude``.
+
+    Attributes:
+        circle: The circular boundary (1/25; mutually exclusive with
+            the unmodeled ``polygon`` in capture, not enforced).
+        settings: The display-settings block (13/25).
+    """
+
+    circle: AddressGeofenceCircle | None = None
+    settings: AddressGeofenceSettings | None = None
+
+
+class Address(ResponseModel):
+    """One Samsara defined address (a named location with a geofence).
+
+    A pure mirror of the captured fields (``tags`` and
+    ``geofence.polygon`` excluded, module docstring). Field semantics
+    are Samsara's; no value is derived or interpreted here. The walk
+    was the whole 25-record population, so the always-present keys are
+    required (the vehicles posture).
+
+    Attributes:
+        id: Samsara's address id -- a string, mirrored as string.
+        name: The address's display name.
+        created_at_time: Record creation (UTC, millisecond ISO-8601).
+        formatted_address: The full street address, one formatted
+            string.
+        latitude: The address's center-point latitude, decimal degrees
+            -- carried on every record, polygon-fenced ones included.
+        longitude: The address's center-point longitude, decimal
+            degrees.
+        geofence: The geofence block (circle/settings modeled; polygon
+            excluded).
+        address_types: The address's type tags, a list of strings
+            (20/25).
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    # Identity and lifecycle.
+    id: str
+    name: str
+    created_at_time: datetime
+
+    # Location.
+    formatted_address: str
+    latitude: float
+    longitude: float
+
+    # Boundary and classification.
+    geofence: AddressGeofence
+    address_types: list[str] | None = None

fleetpull/models/samsara/asset_location.py

@@ -0,0 +1,131 @@
+# src/fleetpull/models/samsara/asset_location.py
+"""Samsara AssetLocation response model
+(``GET /assets/location-and-speed/stream``).
+
+Written from captured live responses (2026-07-20 probe session: a
+454-record page census with every nested block censused over 300
+records; a 50-id one-hour walk of 2 pages / 701 records), never from
+docs. The legacy hub called this surface ``location_stream``; the
+catalog name is ``asset_locations`` per the name=plural-of-entity
+invariant -- the stored entity is the asset-location reading, one row
+per fix.
+
+The record census (454/454 unless noted): ``happenedAtTime`` (RFC3339
+str, recovered tz-aware UTC -- the event-time column; readings fall
+strictly inside the requested half-open ``[startTime, endTime)``
+window, probe-proven on a 12:00-13:00Z window returning min 12:00:03Z /
+max 12:59:56Z), ``asset`` (an object whose ONLY observed key is ``id``,
+a STRING on the wire, 300/300 -- note the contrast with idling_events'
+bare-int ``asset.id``: per-endpoint wire truth, mirrored per endpoint),
+and ``location`` (300/300 census within the block: ``accuracyMeters``
+int on every censused record but FLOAT on the live walk -- the
+2026-07-20 full-day live proof failed validation on a float value at
+record 351, so the field is float, the census sample proven narrower
+than the wire; ``headingDegrees`` int, ``latitude`` float,
+``longitude`` float).
+
+Requiredness posture: 300/300 on a 454-record page is NOT a
+whole-population oath (the drivers conservative posture would leave
+everything optional), but the location core is required anyway by
+structural judgment -- a location record without coordinates mirrors
+nothing and is structurally meaningless, so a future record omitting
+them should fail loudly rather than land an all-null coordinate row.
+The same judgment covers ``asset``/``asset.id`` (an unattributed
+reading cannot be a reading of anything) and ``happenedAtTime`` (the
+event-time column the watermark routes on). This is the one deliberate
+departure from the pure conservative posture, recorded here and in
+DESIGN section 8.
+
+Not modeled, with different provenance:
+
+- ``location.geofence`` -- OBSERVED-EMPTY, not excluded: present
+  300/300 but an empty object with ZERO keys on every censused record,
+  so there is nothing to mirror (``extra='ignore'`` drops it). Revisit
+  on a capture showing content.
+- Any speed key -- UNOBSERVED despite the surface's name
+  (``location-and-speed``): no speed key appeared anywhere in the
+  census. Unmodeled as unobserved (never excluded); revisit on a
+  capture that shows one.
+
+Wire keys are camelCase; fields are snake_case via the ``to_camel``
+alias generator.
+"""
+
+from datetime import datetime
+
+from pydantic import ConfigDict
+from pydantic.alias_generators import to_camel
+
+from fleetpull.model_contract import ResponseModel
+
+__all__: list[str] = [
+    'AssetLocation',
+    'AssetLocationAssetRef',
+    'AssetLocationFix',
+]
+
+
+class AssetLocationAssetRef(ResponseModel):
+    """The ``asset`` block: the reading's asset reference.
+
+    Its ONLY observed key is ``id`` (300/300) -- a STRING on the wire,
+    unlike idling_events' bare-int ``asset.id`` (per-endpoint wire
+    truth, mirrored per endpoint).
+
+    Attributes:
+        id: Samsara's asset id -- a string, mirrored as string.
+    """
+
+    id: str
+
+
+class AssetLocationFix(ResponseModel):
+    """The ``location`` block: one position fix.
+
+    All four modeled keys were 300/300 in the block census and are
+    required by structural judgment (module docstring): a fix without
+    coordinates mirrors nothing. The block's ``geofence`` key is
+    observed-empty (an empty object on every censused record) and is
+    not modeled -- there is nothing to mirror.
+
+    Attributes:
+        accuracy_meters: The fix's reported accuracy in meters --
+            float: the census saw only bare ints (300/300), but the
+            live full-day walk carried floats (proven 2026-07-20, the
+            validation failure that widened this field).
+        heading_degrees: Heading in degrees, a bare int.
+        latitude: Fix latitude, decimal degrees.
+        longitude: Fix longitude, decimal degrees.
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    accuracy_meters: float
+    heading_degrees: int
+    latitude: float
+    longitude: float
+
+
+class AssetLocation(ResponseModel):
+    """One location reading of one asset, at the reading grain.
+
+    A pure mirror of the captured record (``location.geofence``
+    observed-empty and any speed key unobserved -- module docstring).
+    Field semantics and units are Samsara's; no value is derived or
+    interpreted here.
+
+    Attributes:
+        happened_at_time: The reading instant (RFC3339, recovered
+            tz-aware UTC) -- the event-time column; readings fall
+            strictly inside the requested window.
+        asset: The asset reference (string id) -- the per-record
+            attribution that makes the batched fan-out pure transport
+            packing.
+        location: The position fix block.
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    happened_at_time: datetime
+    asset: AssetLocationAssetRef
+    location: AssetLocationFix

fleetpull/models/samsara/driver.py

@@ -0,0 +1,232 @@
+# src/fleetpull/models/samsara/driver.py
+"""Samsara Driver response model (``GET /fleet/drivers``).
+
+Written from captured live responses (2026-07-20 probe session: the
+full two-sweep census over all 832 records -- 460 active plus 372
+deactivated, fully disjoint -- plus captured record variants), never
+from docs. The census observed no null value anywhere -- Samsara omits
+absent keys rather than nulling them (the vehicles posture), while
+also using empty strings (``homeTerminalName`` / ``homeTerminalAddress``
+are ``""`` on 204 and 268 of the 460 active records), which mirror
+verbatim and normalize to null at the DataFrame boundary.
+
+Optionality is conservative: only ``id`` is required. The per-key
+presence counts were fully enumerated on the active sweep only (the
+attribute docs cite them, out of 460); the deactivated sweep matched
+structurally but was not per-key sworn, so unlike the vehicles model
+(whose one sweep was the whole population) the always-present-in-capture
+keys stay optional here rather than required.
+
+``driverActivationStatus`` is a strict CLOSED enum, proven by the API
+itself: any other value -- case variants, comma-joins, repeated keys,
+bogus strings -- returns HTTP 400 naming the two admissible values
+(captured 2026-07-20), so the two-member ``DriverActivationStatus``
+mirror is closed by evidence, not assumption. ``dotNumber`` is a BARE
+integer on the wire (not quoted). ``eldExemptReason`` is a free-text
+reason string on the wire (282/460 presence, captured 2026-07-20).
+
+Excluded fields (``extra='ignore'`` makes exclusion exactly "don't
+model it"):
+
+- ``tags`` -- a list of ``{id, name, parentTagId}`` objects (441/460);
+  the records layer's schema derivation supports scalars, enums,
+  ``list[scalar]``, and nested models only (the GeoTab Device/User
+  exclusion precedent) -- modeled when the list-of-structs derivation
+  vertical lands.
+- ``eldSettings`` -- ``{rulesets: [{break, cycle, restart, shift}]}``,
+  a list-of-objects block (190/460); same exclusion precedent.
+
+``externalIds`` was NEVER observed on any of the 832 swept records --
+deliberately not modeled (unobserved, not excluded); revisit only on a
+capture that shows one, per the union-of-observed discipline.
+
+Wire keys are camelCase; fields are snake_case via the ``to_camel``
+alias generator.
+"""
+
+from datetime import datetime
+from enum import StrEnum
+
+from pydantic import ConfigDict
+from pydantic.alias_generators import to_camel
+
+from fleetpull.model_contract import ResponseModel
+
+__all__: list[str] = [
+    'Driver',
+    'DriverActivationStatus',
+    'DriverCarrierSettings',
+    'DriverHosSetting',
+    'DriverStaticAssignedVehicleRef',
+    'DriverTagRef',
+]
+
+
+class DriverActivationStatus(StrEnum):
+    """Activation status for a Samsara driver.
+
+    A closed mirror whose closure is API-enforced: every probed variant
+    outside these two values returned HTTP 400 naming exactly this
+    vocabulary (captured 2026-07-20), so the enum is evidence-closed.
+    Kept as an enum (not downgraded to ``str``) because the wire values
+    match the member values exactly -- membership validation for free on
+    a faithful mirror (the Motive ``VehicleStatus`` precedent).
+    """
+
+    ACTIVE = 'active'
+    DEACTIVATED = 'deactivated'
+
+
+class DriverCarrierSettings(ResponseModel):
+    """The ``carrierSettings`` block: carrier identity and home terminal.
+
+    Present on every captured record, with all five keys present in
+    every carrying block; the home-terminal pair frequently carries
+    empty strings (204/460 and 268/460 active), mirrored verbatim.
+
+    Attributes:
+        carrier_name: The carrier's display name.
+        dot_number: The carrier's USDOT number -- a BARE integer on the
+            wire (captured six-digit), never quoted.
+        main_office_address: The carrier's main office address.
+        home_terminal_name: The driver's home terminal name; ``""`` on
+            204/460 active records.
+        home_terminal_address: The home terminal address; ``""`` on
+            268/460 active records.
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    carrier_name: str
+    dot_number: int
+    main_office_address: str
+    home_terminal_name: str
+    home_terminal_address: str
+
+
+class DriverHosSetting(ResponseModel):
+    """The ``hosSetting`` block: hours-of-service configuration flags.
+
+    Attributes:
+        heavy_haul_exemption_toggle_enabled: Whether the heavy-haul
+            exemption toggle is enabled for the driver.
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    heavy_haul_exemption_toggle_enabled: bool
+
+
+class DriverStaticAssignedVehicleRef(ResponseModel):
+    """The statically assigned vehicle reference: id and display name."""
+
+    id: str
+    name: str
+
+
+class DriverTagRef(ResponseModel):
+    """A tag reference: the shared ``{id, name, parentTagId}`` shape.
+
+    The one shape both singular tag references (``peerGroupTag``,
+    ``vehicleGroupTag``) carry -- all three keys present in every
+    captured block. Deliberately NOT reused for the ``tags`` list, which
+    stays excluded wholesale (module docstring).
+
+    Attributes:
+        id: The tag's id.
+        name: The tag's display name.
+        parent_tag_id: The parent tag's id.
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    id: str
+    name: str
+    parent_tag_id: str
+
+
+class Driver(ResponseModel):
+    """One Samsara fleet driver, active or deactivated.
+
+    A pure mirror of the captured fields (``tags`` and ``eldSettings``
+    excluded, ``externalIds`` unobserved -- module docstring). Field
+    semantics are Samsara's; no value is derived or interpreted here.
+    The one complete driver dataset is the union of the two activation
+    sweeps; ``driver_activation_status`` carries the split.
+
+    Presence counts below are out of the 460 active records; keys with
+    no count were present on every one (the deactivated sweep matched
+    structurally). Only ``id`` is required (module docstring).
+
+    Attributes:
+        id: Samsara's driver id -- a numeric string, mirrored as string.
+        name: The driver's display name.
+        username: The driver-app login name.
+        driver_activation_status: ``active`` / ``deactivated`` -- the
+            API-enforced closed enum, and the two-sweep split column.
+        timezone: The driver's IANA timezone (e.g.
+            ``America/Chicago``).
+        created_at_time: Record creation (UTC, millisecond ISO-8601).
+        updated_at_time: Last record update (UTC).
+        has_vehicle_unpinning_enabled: Vehicle-unpinning flag.
+        carrier_settings: Carrier identity and home terminal block.
+        hos_setting: Hours-of-service configuration block.
+        static_assigned_vehicle: Statically assigned vehicle reference
+            (102/460).
+        peer_group_tag: Peer-group tag reference (4/460).
+        vehicle_group_tag: Vehicle-group tag reference (8/460).
+        license_number: Driving license number (172/460).
+        license_state: License issuing state (269/460).
+        phone: Contact phone number (7/460).
+        locale: Display locale (1/460).
+        notes: Free-form notes (1/460).
+        profile_image_url: Profile image URL (1/460).
+        eld_exempt: ELD exemption flag (270/460).
+        eld_exempt_reason: Free-text exemption reason (282/460).
+        eld_adverse_weather_exemption_enabled: ELD adverse-weather
+            exemption flag (191/460).
+        eld_big_day_exemption_enabled: ELD big-day exemption flag
+            (186/460).
+        eld_pc_enabled: ELD personal-conveyance flag (77/460).
+        eld_ym_enabled: ELD yard-move flag (100/460).
+        waiting_time_duty_status_enabled: Waiting-time duty-status flag
+            (8/460).
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    # Identity and lifecycle.
+    id: str
+    name: str | None = None
+    username: str | None = None
+    driver_activation_status: DriverActivationStatus | None = None
+    timezone: str | None = None
+    created_at_time: datetime | None = None
+    updated_at_time: datetime | None = None
+    has_vehicle_unpinning_enabled: bool | None = None
+
+    # Carrier and HOS configuration blocks.
+    carrier_settings: DriverCarrierSettings | None = None
+    hos_setting: DriverHosSetting | None = None
+
+    # Assignment and grouping references.
+    static_assigned_vehicle: DriverStaticAssignedVehicleRef | None = None
+    peer_group_tag: DriverTagRef | None = None
+    vehicle_group_tag: DriverTagRef | None = None
+
+    # Person and contact.
+    license_number: str | None = None
+    license_state: str | None = None
+    phone: str | None = None
+    locale: str | None = None
+    notes: str | None = None
+    profile_image_url: str | None = None
+
+    # ELD and duty-status flags.
+    eld_exempt: bool | None = None
+    eld_exempt_reason: str | None = None
+    eld_adverse_weather_exemption_enabled: bool | None = None
+    eld_big_day_exemption_enabled: bool | None = None
+    eld_pc_enabled: bool | None = None
+    eld_ym_enabled: bool | None = None
+    waiting_time_duty_status_enabled: bool | None = None