fleetpull 0.1.0__tar.gz → 0.1.2__tar.gz

{fleetpull-0.1.0 → fleetpull-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fleetpull
-Version: 0.1.0
+Version: 0.1.2
 Summary: Pull fleet telematics data from provider APIs (Motive, Samsara, GeoTab) into typed polars DataFrames and parquet: retrieval, dtype coercion, and light structural normalization — no assumed end use.
 Author-email: Andrew Jordan <andrewjordan3@gmail.com>
 Maintainer-email: Andrew Jordan <andrewjordan3@gmail.com>

{fleetpull-0.1.0 → fleetpull-0.1.2}/pyproject.toml

@@ -9,7 +9,7 @@ build-backend = "setuptools.build_meta"
 ###############################################################################
 [project]
 name = "fleetpull"
-version = "0.1.0"
+version = "0.1.2"
 description = "Pull fleet telematics data from provider APIs (Motive, Samsara, GeoTab) into typed polars DataFrames and parquet: retrieval, dtype coercion, and light structural normalization — no assumed end use."
 readme = "README.md"
 authors = [{ name = "Andrew Jordan", email = "andrewjordan3@gmail.com" }]

{fleetpull-0.1.0 → fleetpull-0.1.2}/src/fleetpull/__init__.py

@@ -21,7 +21,7 @@ from fleetpull.exceptions import (
     SyncFailuresError,
 )
 
-__version__: str = '0.1.0'
+__version__: str = '0.1.2'
 
 __all__: list[str] = [
     'AuthenticationError',

{fleetpull-0.1.0 → fleetpull-0.1.2}/src/fleetpull/endpoints/samsara/trips.py

@@ -14,8 +14,12 @@ member merges as a QUERY parameter -- the drivers-leaf precedent, not
 the Motive path-template one.
 
 The envelope is ``{"trips": [...]}`` with no pagination of any kind:
-one response per (vehicle, window), so the shared ``SinglePageDecoder``
-fits (the GeoTab exception_events pairing precedent). Retrieval is
+one response per (vehicle, window). The wire record does NOT echo the
+requested ``vehicleId``, so the binding pairs it with
+``SamsaraTripsPageDecoder``, which stamps every trip with the fan-out
+member's ``vehicleId`` copied off the sent spec (the report family's
+sent-spec stamp applied to a fan-out member) -- without it the stored
+row carries no vehicle identity. Retrieval is
 OVERLAP-anchored, re-verified per-type 2026-07-20 (a 60-second window
 strictly inside a trip's span returned that trip; start- and
 end-anchoring falsified -- DESIGN §4's historical record for this exact
@@ -50,7 +54,7 @@ from fleetpull.endpoints.shared import (
 )
 from fleetpull.models.samsara import Trip
 from fleetpull.network.contract import HttpMethod, RequestSpec
-from fleetpull.network.decoders import SinglePageDecoder
+from fleetpull.network.decoders import SamsaraTripsPageDecoder
 from fleetpull.roster import RosterKey
 from fleetpull.timing import require_utc
 from fleetpull.vocabulary import Provider, QuotaScope
@@ -201,7 +205,9 @@ def build_endpoint(config: SamsaraConfig) -> EndpointDefinition[Trip]:
         spec_builder=SamsaraTripsSpecBuilder(
             base_url=config.base_url, path=_TRIPS_PATH
         ),
-        page_decoder=SinglePageDecoder(records_key=_RECORDS_KEY),
+        page_decoder=SamsaraTripsPageDecoder(
+            records_key=_RECORDS_KEY, member_key=_VEHICLE_ID_PARAM
+        ),
         response_model=Trip,
         quota_scope=QuotaScope.SAMSARA,
         storage_kind=StorageKind.DATE_PARTITIONED,

{fleetpull-0.1.0 → fleetpull-0.1.2}/src/fleetpull/models/motive/idle_event.py

@@ -9,6 +9,15 @@ the provider's reverse-geocode metadata; when ``rg_match`` is false,
 ``location`` carries a distance-direction prefix (``"2.6 mi NW of …"``)
 instead of a bare place name — both formats mirror verbatim.
 
+The reverse-geocode PLACE fields (``city``/``state``/``rg_brg``/``rg_km``)
+are OPTIONAL: the 2026-07-15 census saw them on every record (including
+the ``rg_match: false`` ones, which still carry a nearby place), but a
+larger live pull (2026-07-22) returned all four null when the geocoder
+matched NO nearby place at all — the census-scope lesson (a bounded
+census proves a shape present, never absent). So a no-place record
+validates and mirrors the nulls rather than failing the sync loudly (the
+``veh_fuel`` null-counter precedent).
+
 The endpoint's date window is interpreted on company-local day boundaries
 and matched by overlap (DESIGN §8, captured 2026-07-15) — the reason its
 endpoint leaf pads the wire window; nothing about that reaches this
@@ -43,11 +52,14 @@ class IdleEvent(ResponseModel):
             when the vehicle reports no fuel counters.
         lat: Event latitude.
         lon: Event longitude.
-        city: Reverse-geocoded place name.
-        state: Reverse-geocoded state / province code.
-        rg_brg: Reverse-geocode bearing from the matched place, degrees.
+        city: Reverse-geocoded place name; null when the geocoder matched
+            no nearby place (live-observed 2026-07-22).
+        state: Reverse-geocoded state / province code; null when no place
+            matched.
+        rg_brg: Reverse-geocode bearing from the matched place, degrees;
+            null when no place matched.
         rg_km: Reverse-geocode distance from the matched place,
-            kilometers.
+            kilometers; null when no place matched.
         rg_match: Whether the reverse geocoder matched a place directly.
         end_type: Free-form interval-end reason (``"engine_stop"`` /
             ``"vehicle_moving"`` observed), mirrored, never interpreted.
@@ -65,10 +77,10 @@ class IdleEvent(ResponseModel):
     veh_fuel_end: float | None = None
     lat: float
     lon: float
-    city: str
-    state: str
-    rg_brg: float
-    rg_km: float
+    city: str | None = None
+    state: str | None = None
+    rg_brg: float | None = None
+    rg_km: float | None = None
     rg_match: bool
     end_type: str
     driver: UserSummary | None = None

{fleetpull-0.1.0 → fleetpull-0.1.2}/src/fleetpull/models/samsara/trip.py

@@ -26,17 +26,26 @@ Everything else mirrors verbatim: the unit-suffixed int family
 (``distanceMeters``, ``fuelConsumedMl``, ``tollMeters``) and the
 odometer pair keep provider units untouched; ``driverId`` is an int
 whose ``0`` is the UNASSIGNED sentinel (110/725) -- mirrored verbatim,
-never nulled or interpreted. ``assetIds``/``codriverIds`` were observed
-ONLY EMPTY across all 725 records; they are typed ``list[int]`` --
-the int-id family, in the ``list[scalar]`` form the records layer's
-schema derivation represents (DESIGN §9; the §9 pipeline has no tuple
-form) -- so a first non-empty capture lands as data, not a crash.
-
-The record does NOT echo the requested ``vehicleId``: per-vehicle
-attribution lives in the request parameter (the roster fan-out member),
-not on the wire record. The response *wrapper* (the ``{"trips": [...]}``
-envelope, unpaginated) is the endpoints layer's decoder concern; this
-module mirrors only the inner per-trip object.
+never nulled or interpreted. ``assetIds``/``codriverIds`` are typed
+``list[int]`` -- the int-id family, in the ``list[scalar]`` form the
+records layer's schema derivation represents (DESIGN §9; the §9
+pipeline has no tuple form). The 725-trip census observed both EMPTY on
+every record; a larger live pull (2026-07-22) then returned ``assetIds``
+populated on a substantial minority of trips (its elements are attached
+assets -- trailers/equipment -- not the trip's own vehicle), while
+``codriverIds`` stayed empty. The ``list[int]`` typing anticipated
+exactly that, so a non-empty capture lands as data, not a crash -- the
+census sized the shape, it never bounded the population.
+
+The wire record does NOT echo the requested ``vehicleId``: per-vehicle
+attribution is the request parameter (the roster fan-out member), not a
+wire field. So ``vehicle_id`` is the one SYNTHESIZED field on this
+otherwise-pure mirror -- ``SamsaraTripsPageDecoder`` stamps it off the
+sent spec before validation, mirrored as a string to match
+``Vehicle.id`` for a direct join to the vehicles listing. The response
+*wrapper* (the ``{"trips": [...]}`` envelope, unpaginated) is the
+endpoints layer's decoder concern; this module mirrors only the inner
+per-trip object, plus that one synthesized identity.
 
 Wire keys are camelCase; fields are snake_case via the ``to_camel``
 alias generator (``startMs``/``endMs`` carry explicit aliases, since
@@ -133,12 +142,16 @@ class TripAddress(ResponseModel):
 class Trip(ResponseModel):
     """One Samsara vehicle trip, overlap-retrieved per (vehicle, window).
 
-    A pure mirror of the captured fields (module docstring). Field
-    semantics and units are Samsara's; no value is derived or
-    interpreted here. The requested ``vehicleId`` is not echoed on the
-    record.
+    A near-pure mirror of the captured fields (module docstring): field
+    semantics and units are Samsara's, no value derived or interpreted
+    -- the one exception is ``vehicle_id``, synthesized because the wire
+    record does not echo the requested ``vehicleId`` (stamped off the
+    sent spec by ``SamsaraTripsPageDecoder``).
 
     Attributes:
+        vehicle_id: The fan-out vehicle this trip belongs to, stamped
+            from the request's ``vehicleId`` -- the wire record never
+            echoes it; a numeric string, matching ``Vehicle.id``.
         start_time: Trip start, recovered from the wire's epoch-ms
             ``startMs`` -- the endpoint's event time (start-anchored
             ownership, DESIGN §4).
@@ -158,10 +171,11 @@ class Trip(ResponseModel):
         end_location: Reverse-geocoded end location string.
         start_coordinates: The start ``{latitude, longitude}`` block.
         end_coordinates: The end ``{latitude, longitude}`` block.
-        asset_ids: Attached asset ids; observed ONLY EMPTY across all
-            725 census records.
-        codriver_ids: Co-driver ids; observed ONLY EMPTY across all 725
-            census records.
+        asset_ids: Attached asset ids (trailers/equipment, not the
+            trip's own vehicle); empty across the 725-trip census, then
+            populated on a minority of trips in a larger live pull.
+        codriver_ids: Co-driver ids; empty across the 725-trip census
+            and the larger live pull alike.
         start_address: The matched start address/geofence block
             (177/725); null when no defined address matched.
         end_address: The matched end address/geofence block (185/725);
@@ -170,6 +184,14 @@ class Trip(ResponseModel):
 
     model_config = ConfigDict(alias_generator=to_camel)
 
+    # The fan-out vehicle, synthesized: the wire record does not echo the
+    # requested vehicleId, so SamsaraTripsPageDecoder stamps it off the
+    # sent spec before validation (module docstring). Mirrored as a
+    # string, matching Vehicle.id, so it joins the vehicles listing
+    # directly; the to_camel generator aliases vehicle_id -> vehicleId,
+    # which is the decoder's stamp key.
+    vehicle_id: str
+
     # The trip interval (epoch-ms recovered, module docstring).
     start_time: _EpochMillisecondsDatetime = Field(alias='startMs')
     end_time: _EpochMillisecondsDatetime = Field(alias='endMs')

{fleetpull-0.1.0 → fleetpull-0.1.2}/src/fleetpull/network/decoders/__init__.py

@@ -25,6 +25,7 @@ from fleetpull.network.decoders.samsara import (
     SamsaraVehicleSeriesPageDecoder,
 )
 from fleetpull.network.decoders.samsara_reports import SamsaraWindowReportPageDecoder
+from fleetpull.network.decoders.samsara_trips import SamsaraTripsPageDecoder
 from fleetpull.network.decoders.single_page import SinglePageDecoder
 
 __all__: list[str] = [
@@ -34,6 +35,7 @@ __all__: list[str] = [
     'MotiveWrappedListPageDecoder',
     'MotiveWrappedSinglePageDecoder',
     'SamsaraCursorPageDecoder',
+    'SamsaraTripsPageDecoder',
     'SamsaraVehicleSeriesPageDecoder',
     'SamsaraWindowReportPageDecoder',
     'SinglePageDecoder',

fleetpull-0.1.2/src/fleetpull/network/decoders/samsara_trips.py

@@ -0,0 +1,105 @@
+# src/fleetpull/network/decoders/samsara_trips.py
+"""The Samsara trips page decoder: unpaginated records, vehicle-stamped.
+
+The trips surface (``GET /v1/fleet/trips``) is a per-vehicle fan-out
+whose response does NOT echo the requested ``vehicleId`` -- the inner
+per-trip object carries no vehicle field of any kind (2026-07-20
+census; re-proven at scale 2026-07-22, where every stored trip lacked a
+vehicle identity). The vehicle a trip belongs to is therefore the
+fan-out member the request asked for, not anything on the wire, so this
+decoder STAMPS every trip with the ``vehicleId`` copied VERBATIM from
+the SENT spec's own query param. It is the report family's
+sent-spec-sourced stamp (``SamsaraWindowReportPageDecoder``) applied to
+a fan-out member instead of a window: without it the stored row cannot
+be attributed to a vehicle.
+
+The envelope is ``{"trips": [...]}`` with no pagination of any kind --
+one response per (vehicle, window) -- so the page is always terminal
+(the ``SinglePageDecoder`` shape it supersedes for this surface, now
+that the terminal page must also carry the member stamp). Decoder logic
+deliberately resembles its siblings without sharing code.
+"""
+
+from dataclasses import dataclass
+
+from fleetpull.exceptions import ProviderResponseError
+from fleetpull.network.contract import (
+    DecodedPage,
+    PageAdvance,
+    RequestSpec,
+    require_record_list,
+)
+from fleetpull.vocabulary import JsonValue
+
+__all__: list[str] = ['SamsaraTripsPageDecoder']
+
+
+@dataclass(frozen=True, slots=True)
+class SamsaraTripsPageDecoder:
+    """Decode Samsara's unpaginated trips page, stamping the fan-out vehicle.
+
+    The trips surface returns a top-level list under ``records_key`` with
+    no pagination, so every page is terminal. The per-trip wire object
+    carries no vehicle identity; the vehicle is the fan-out member the
+    request asked for, so each record is stamped with ``member_key``
+    copied verbatim from the SENT spec's own query param -- the
+    ``SamsaraWindowReportPageDecoder`` sent-spec stamp, sourcing a
+    fan-out member rather than a window.
+
+    The stamp wins any (census-impossible) key collision: it is the
+    row's REQUIRED vehicle identity, exactly the vehicle asked of the
+    provider, and a colliding future wire key must never silently
+    supplant it -- the report family's stamp-wins order, the inverse of
+    the series decoder's reading-keys-win.
+
+    Attributes:
+        records_key: The top-level key holding the trip record list.
+        member_key: The fan-out member's query-param name (the roster
+            ``member_key``); read off the SENT spec and stamped onto
+            every record under the SAME key, which is also the response
+            model's alias for the stamped ``vehicle_id`` field. One
+            token binds the request param, the stamp, and the model
+            alias, so no translation seam can drift.
+    """
+
+    records_key: str
+    member_key: str
+
+    def first_request(self, spec: RequestSpec) -> RequestSpec:
+        """Return the base spec unchanged; the trips surface is unpaginated."""
+        return spec
+
+    def decode_page(self, sent: RequestSpec, envelope: JsonValue) -> DecodedPage:
+        """Extract the records, stamp each with the sent vehicle; terminal.
+
+        Args:
+            sent: The spec that produced this page; supplies the fan-out
+                member (``member_key``) stamped onto every record.
+            envelope: The parsed response body.
+
+        Returns:
+            One record per trip, each carrying the ``member_key`` stamp,
+            and a terminal verdict -- there is no continuation.
+
+        Raises:
+            ProviderResponseError: The sent spec lacks the ``member_key``
+                param (a wiring bug -- a fan-out request always carries
+                its member -- never silently unstamped, vehicle-less
+                rows), or the record-bearing shape is structurally
+                violating.
+        """
+        params = sent.params or {}
+        if self.member_key not in params:
+            raise ProviderResponseError(
+                detail=(
+                    f'sent spec lacks the {self.member_key!r} fan-out member '
+                    'to stamp trip rows with'
+                )
+            )
+        vehicle_stamp = {self.member_key: params[self.member_key]}
+        records = require_record_list(envelope, self.records_key)
+        stamped = [{**record, **vehicle_stamp} for record in records]
+        return DecodedPage(
+            records=stamped,
+            advance=PageAdvance(next_spec=None, durable_progress=None),
+        )

{fleetpull-0.1.0 → fleetpull-0.1.2}/src/fleetpull.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fleetpull
-Version: 0.1.0
+Version: 0.1.2
 Summary: Pull fleet telematics data from provider APIs (Motive, Samsara, GeoTab) into typed polars DataFrames and parquet: retrieval, dtype coercion, and light structural normalization — no assumed end use.
 Author-email: Andrew Jordan <andrewjordan3@gmail.com>
 Maintainer-email: Andrew Jordan <andrewjordan3@gmail.com>

{fleetpull-0.1.0 → fleetpull-0.1.2}/src/fleetpull.egg-info/SOURCES.txt

@@ -169,6 +169,7 @@ src/fleetpull/network/decoders/motive.py
 src/fleetpull/network/decoders/motive_reports.py
 src/fleetpull/network/decoders/samsara.py
 src/fleetpull/network/decoders/samsara_reports.py
+src/fleetpull/network/decoders/samsara_trips.py
 src/fleetpull/network/decoders/single_page.py
 src/fleetpull/network/limits/__init__.py
 src/fleetpull/network/limits/bucket_math.py