fleetpull 0.1.0__py3-none-any.whl

fleetpull/endpoints/samsara/idling_events.py

@@ -0,0 +1,195 @@
+# src/fleetpull/endpoints/samsara/idling_events.py
+"""The Samsara idling_events binding: the fleet-wide windowed cursor walk --
+the first windowed+cursor pairing, composed entirely from existing parts.
+
+``GET /idling/events`` is a modern-envelope surface (``data`` +
+``pagination {endCursor, hasNextPage}``, terminal on ``hasNextPage:
+false`` beside an empty-string ``endCursor``; the cursor walk proven
+live 2026-07-20: 11 pages at limit=200, 2,200/2,200 unique). Events are
+fleet-wide with per-record asset attribution, so there is NO fan-out --
+the default ``SingleFetch`` shape, declared by declaring nothing (the
+Motive driving_periods template on the Samsara cursor decoder).
+
+The windowed leaf builder composes with the existing
+``SamsaraCursorPageDecoder`` because pagination parameters persist by
+construction: the decoder's ``first_request`` merges ``limit`` onto the
+builder's spec, and its ``after`` advance merges onto the SENT spec, so
+the builder's ``startTime``/``endTime`` ride every page of the walk --
+the mechanism proven live on the drivers sweep, now carrying a window
+instead of a status.
+
+The per-endpoint ``limit`` maximum is 200, NOT the 512 of
+vehicles/drivers: limit=512 returns a loud JSON 400 (``"limit must be
+lesser or equal than 200 but got value 512"``) -- the first captured
+instance of Samsara's per-endpoint limit tiers; never assume a
+sibling's limit (DESIGN §8, captured 2026-07-20).
+
+Retrieval is START-anchored on UTC, proven by a discriminating pair on
+a 6.5-hour event: a 60-second window strictly inside its span does NOT
+return it, while a 60-second window straddling only its start DOES
+(the fourth distinct anchoring datum across providers -- notably NOT
+the company-local overlap behavior of Motive's idle_events sibling;
+never assume the rule, per endpoint, ever). Consequence:
+``event_time_column='start_time'``, the retrieval anchor and the
+routing anchor coincide natively, no wire pad exists, and the runner's
+post-fetch window filter is pure hygiene (the driving_periods
+situation).
+
+Records carry NO end key -- the interval is start plus
+``durationMilliseconds``; events were only ever observed complete
+(in-progress idles appear to materialize on completion), and the
+watermark lookback absorbs late materialization (accepted residual).
+
+The provider enforces a loud sub-3-months range cap -- 91 days
+accepted; 180 days returns JSON 400 ``"Total duration must be less
+than 3 months."``. No builder guard exists for it (the Motive
+driving_periods stance): default 7-day backfill chunks sit far inside,
+and a ``backfill_chunk_days`` raised past the cap fails loudly on the
+first request rather than losing data silently -- the fix is a smaller
+chunk width.
+"""
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from datetime import timedelta
+from typing import Final
+
+from fleetpull.config import SamsaraConfig
+from fleetpull.endpoints.shared import (
+    EndpointDefinition,
+    ResumeValue,
+    StorageKind,
+    WatermarkMode,
+    require_date_window,
+)
+from fleetpull.models.samsara import IdlingEvent
+from fleetpull.network.contract import HttpMethod, RequestSpec
+from fleetpull.network.decoders import SamsaraCursorPageDecoder
+from fleetpull.timing import to_iso8601
+from fleetpull.vocabulary import Provider, QuotaScope
+
+__all__: list[str] = [
+    'SamsaraIdlingEventsSpecBuilder',
+    'build_endpoint',
+]
+
+_IDLING_EVENTS_PATH: Final[str] = '/idling/events'
+_RECORDS_KEY: Final[str] = 'data'
+
+# The per-page record count. 200 is THIS endpoint's probed maximum --
+# NOT the 512 of vehicles/drivers: limit=512 earns a loud JSON 400
+# naming the 200 cap (captured 2026-07-20), the first captured instance
+# of Samsara's per-endpoint limit tiers. Never assume a sibling's limit.
+_RESULTS_LIMIT: Final[int] = 200
+
+
+@dataclass(frozen=True, slots=True)
+class SamsaraIdlingEventsSpecBuilder:
+    """Build the fleet-wide, date-windowed first request for idling events.
+
+    The ``SpecBuilder`` for the idling_events single chain: a fixed
+    ``GET base_url + path`` carrying the resume window as RFC3339
+    ``startTime``/``endTime`` (the timing codec's ``to_iso8601``). The
+    decoder owns pagination: its ``first_request`` merges ``limit``
+    onto this spec and its ``after`` advance merges onto the sent spec,
+    so the window parameters persist across the whole cursor walk.
+
+    The canonical half-open ``[start, end)`` window maps to the wire as
+    ``startTime = start`` and ``endTime = end``. Retrieval is
+    START-anchored on UTC (module docstring), so a window's records are
+    exactly those starting inside it; any boundary-instant reading of
+    ``endTime`` the wire might take is absorbed by the runner's
+    post-fetch window filter, which keeps only events whose start lies
+    in ``[start, end)`` -- pure hygiene, never load-bearing.
+
+    Attributes:
+        base_url: Root of the Samsara API, trailing-slash-normalized by
+            the provider config so the leading-slash path joins
+            directly.
+        path: The endpoint's leading-slash request path
+            (``'/idling/events'``).
+    """
+
+    base_url: str
+    path: str
+
+    def build_spec(
+        self, resume: ResumeValue, member_values: Mapping[str, str]
+    ) -> RequestSpec:
+        """Build the fleet-wide, date-windowed GET.
+
+        Args:
+            resume: The run's resume window. Must be a ``DateWindow`` --
+                a watermark endpoint always resumes from one; any other
+                value is a wiring bug.
+            member_values: Accepted to satisfy the protocol; unused -- a
+                fleet-wide single chain binds no member.
+
+        Returns:
+            A credential-less ``GET`` for ``base_url + path`` carrying
+            the window's bounds as RFC3339 ``startTime``/``endTime``.
+            Auth headers are layered on by the client's
+            ``ProviderProfile``; pagination parameters are injected by
+            the page decoder's ``first_request``.
+
+        Raises:
+            TypeError: ``resume`` is not a ``DateWindow``.
+            ValueError: A window bound is not canonical UTC.
+
+        Side Effects:
+            None.
+        """
+        resume_window = require_date_window(resume, type(self).__name__)
+        params = {
+            'startTime': to_iso8601(resume_window.start),
+            'endTime': to_iso8601(resume_window.end),
+        }
+        return RequestSpec(
+            method=HttpMethod.GET,
+            url=f'{self.base_url}{self.path}',
+            params=params,
+        )
+
+
+def build_endpoint(config: SamsaraConfig) -> EndpointDefinition[IdlingEvent]:
+    """Build the Samsara idling_events watermark binding.
+
+    Fleet-wide idling events fetched incrementally: the run resumes
+    from a ``DateWindow`` (watermark with the provider's late-arrival
+    lookback from config -- which also absorbs idles materializing on
+    completion), the fetched events are written to ``date=YYYY-MM-DD``
+    partitions on ``start_time``, and each refetched partition is
+    replaced. Records arrive as a top-level list under ``data``, walked
+    by explicit cursor pages (``limit`` on page one, ``after`` merged
+    thereafter, the window parameters persisting throughout), terminal
+    on ``hasNextPage: false``. No request shape is declared -- the
+    endpoint is a fleet-wide ``SingleFetch``, the default.
+
+    Args:
+        config: The validated Samsara configuration; supplies the base
+            URL the spec-builder joins to the idling-events path and
+            the lookback and cutoff the watermark mode carries.
+
+    Returns:
+        The frozen idling_events ``EndpointDefinition``. Construction
+        validates the ``WatermarkMode`` / ``DATE_PARTITIONED`` /
+        ``event_time_column`` triple against the response model.
+    """
+    return EndpointDefinition(
+        provider=Provider.SAMSARA,
+        name='idling_events',
+        spec_builder=SamsaraIdlingEventsSpecBuilder(
+            base_url=config.base_url, path=_IDLING_EVENTS_PATH
+        ),
+        page_decoder=SamsaraCursorPageDecoder(
+            records_key=_RECORDS_KEY, results_limit=_RESULTS_LIMIT
+        ),
+        response_model=IdlingEvent,
+        quota_scope=QuotaScope.SAMSARA,
+        storage_kind=StorageKind.DATE_PARTITIONED,
+        sync_mode=WatermarkMode(
+            lookback=timedelta(days=config.lookback_days),
+            cutoff=timedelta(days=config.cutoff_days),
+        ),
+        event_time_column='start_time',
+    )

fleetpull/endpoints/samsara/odometer_readings.py

@@ -0,0 +1,116 @@
+# src/fleetpull/endpoints/samsara/odometer_readings.py
+"""The Samsara odometer_readings binding: the vehicle-stats windowed
+cursor walk for ``types=obdOdometerMeters`` -- one of the three
+endpoints the legacy ``/fleet/vehicles/stats/history`` surface splits
+into (engine_states, gps_readings, odometer_readings; the three stat
+types carry disjoint schemas, so each is its own entity and dataset --
+DESIGN §8).
+
+``GET /fleet/vehicles/stats/history`` is a modern-envelope surface
+(``data`` + ``pagination {endCursor, hasNextPage}``), but its cursor
+walks the VEHICLE axis within the fixed window: three consecutive live
+pages showed zero vehicle-id overlap (captured 2026-07-20). Each
+vehicle record nests one reading series under the requested type's key,
+so the binding pairs the shared windowed builder (which bakes the FIXED
+``types=obdOdometerMeters`` selector into every request -- the
+``types`` vocabulary is API-enforced on input, a loud 400 on any
+unknown value) with ``SamsaraVehicleSeriesPageDecoder``, which unnests
+each vehicle's series into flat per-reading records and delegates
+pagination to the inner cursor decoder untouched.
+
+Only carrier vehicles are returned per requested type (24-hour walk:
+135 vehicles, 135 with data -- no empty-array padding observed), and
+the endpoint is fleet-wide with per-record vehicle attribution
+synthesized by the decoder, so there is NO fan-out -- the default
+``SingleFetch`` shape, declared by declaring nothing, and no roster is
+sourced or consumed.
+
+The per-endpoint ``limit`` maximum is 512, probed directly on THIS
+surface: limit=512 returned HTTP 200 and limit=513 a loud HTTP 400 --
+the vehicles/drivers tier, NOT idling's 200 (the per-endpoint
+limit-tier rule, honored by probing rather than assuming).
+
+Retrieval is READING-TIME anchored on the half-open ``[startTime,
+endTime)`` window, probe-proven: a 12:00-13:00Z window returned
+readings spanning exactly 12:00:03.062Z..12:59:56.881Z. Consequence:
+``event_time_column='time'``, the retrieval anchor and the routing
+anchor coincide natively, no wire pad exists, and the runner's
+post-fetch window filter is pure hygiene.
+"""
+
+from datetime import timedelta
+from typing import Final
+
+from fleetpull.config import SamsaraConfig
+from fleetpull.endpoints.samsara._spec_builders import (
+    RECORDS_KEY,
+    RESULTS_LIMIT,
+    STATS_HISTORY_PATH,
+    SamsaraVehicleStatsSpecBuilder,
+)
+from fleetpull.endpoints.shared import (
+    EndpointDefinition,
+    StorageKind,
+    WatermarkMode,
+)
+from fleetpull.models.samsara import OdometerReading
+from fleetpull.network.decoders import SamsaraVehicleSeriesPageDecoder
+from fleetpull.vocabulary import Provider, QuotaScope
+
+__all__: list[str] = ['build_endpoint']
+
+# The requested stat type -- the verbatim `types` wire value AND the
+# per-vehicle series key the decoder unnests (one name on the wire for
+# both roles, captured 2026-07-20).
+_STAT_TYPE: Final[str] = 'obdOdometerMeters'
+
+
+def build_endpoint(config: SamsaraConfig) -> EndpointDefinition[OdometerReading]:
+    """Build the Samsara odometer_readings watermark binding.
+
+    Fleet-wide OBD odometer readings fetched incrementally: the run
+    resumes from a ``DateWindow`` (watermark with the provider's
+    late-arrival lookback from config), the fetched readings are
+    written to ``date=YYYY-MM-DD`` partitions on ``time``, and each
+    refetched partition is replaced. Vehicle records arrive as a
+    top-level list under ``data``, walked by explicit cursor pages
+    along the VEHICLE axis (``limit`` on page one, ``after`` merged
+    thereafter, the window and ``types`` parameters persisting
+    throughout), and the decoder unnests each vehicle's
+    ``obdOdometerMeters`` series into one flat record per reading. No
+    request shape is declared -- the endpoint is a fleet-wide
+    ``SingleFetch``, the default.
+
+    Args:
+        config: The validated Samsara configuration; supplies the base
+            URL the spec-builder joins to the stats-history path and
+            the lookback and cutoff the watermark mode carries.
+
+    Returns:
+        The frozen odometer_readings ``EndpointDefinition``.
+        Construction validates the ``WatermarkMode`` /
+        ``DATE_PARTITIONED`` / ``event_time_column`` triple against the
+        response model.
+    """
+    return EndpointDefinition(
+        provider=Provider.SAMSARA,
+        name='odometer_readings',
+        spec_builder=SamsaraVehicleStatsSpecBuilder(
+            base_url=config.base_url,
+            path=STATS_HISTORY_PATH,
+            stat_type=_STAT_TYPE,
+        ),
+        page_decoder=SamsaraVehicleSeriesPageDecoder(
+            records_key=RECORDS_KEY,
+            results_limit=RESULTS_LIMIT,
+            series_key=_STAT_TYPE,
+        ),
+        response_model=OdometerReading,
+        quota_scope=QuotaScope.SAMSARA,
+        storage_kind=StorageKind.DATE_PARTITIONED,
+        sync_mode=WatermarkMode(
+            lookback=timedelta(days=config.lookback_days),
+            cutoff=timedelta(days=config.cutoff_days),
+        ),
+        event_time_column='time',
+    )

fleetpull/endpoints/samsara/trips.py

@@ -0,0 +1,217 @@
+# src/fleetpull/endpoints/samsara/trips.py
+"""The Samsara trips binding: the per-vehicle windowed fan-out -- the
+roster machinery's first cross-provider consumer.
+
+The trips surface is the LEGACY v1 API only: ``GET /v1/fleet/trips``
+(the modern candidates 404 -- ``/fleet/trips``, ``/beta/fleet/trips``,
+``/preview/fleet/trips``; captured 2026-07-20). ``vehicleId`` is
+REQUIRED -- omitting it is a loud HTTP 400 text/plain rpc-error, so the
+endpoint is structurally per-vehicle and the binding declares
+``request_shape=RosterFanOut`` over the Samsara ``vehicle_ids`` roster
+(declared beside its feeder in ``endpoints/samsara/vehicles.py``; this
+module knows only the ``RosterKey``, never the feeder). The fan-out
+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
+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
+endpoint, confirmed live). Per §4: overlap retrieval supersets
+start-anchored ownership, so ``event_time_column='start_time'``, the
+runner's post-fetch window filter assigns each trip to the single chunk
+owning its start, and no wire pad is needed (the exception_events
+reasoning verbatim).
+
+The provider enforces a LOUD, exactly-90-day range cap -- HTTP 400
+text/plain ``rpc error: ... requested time range cannot exceed 90
+days``; a 90-day window succeeded. No builder guard exists for it (the
+Motive driving_periods stance): default 7-day backfill chunks sit far
+inside, and a ``backfill_chunk_days`` raised past 90 fails loudly on
+the first request rather than losing data silently -- the fix is a
+smaller chunk width.
+"""
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from datetime import UTC, datetime, timedelta
+from typing import Final
+
+from fleetpull.config import SamsaraConfig
+from fleetpull.endpoints.shared import (
+    EndpointDefinition,
+    ResumeValue,
+    RosterFanOut,
+    StorageKind,
+    WatermarkMode,
+    require_date_window,
+)
+from fleetpull.models.samsara import Trip
+from fleetpull.network.contract import HttpMethod, RequestSpec
+from fleetpull.network.decoders import SinglePageDecoder
+from fleetpull.roster import RosterKey
+from fleetpull.timing import require_utc
+from fleetpull.vocabulary import Provider, QuotaScope
+
+__all__: list[str] = [
+    'SamsaraTripsSpecBuilder',
+    'build_endpoint',
+]
+
+_TRIPS_PATH: Final[str] = '/v1/fleet/trips'
+_RECORDS_KEY: Final[str] = 'trips'
+
+# The integer-arithmetic epoch origin: float `.timestamp()` math can land
+# a millisecond-precision bound one ms low (float rounding + int()
+# truncation), so the conversion below is exact integer division --
+# symmetric with the model's no-float-epoch-math decode stance.
+_UNIX_EPOCH: Final[datetime] = datetime(1970, 1, 1, tzinfo=UTC)
+_ONE_MILLISECOND: Final[timedelta] = timedelta(milliseconds=1)
+
+# The fan-out member key IS the wire query parameter, verbatim: the spec
+# builder merges member_values into params unchanged, so declaring the
+# exact wire token here leaves no translation seam to drift (the drivers
+# sweep-param stance). The RosterFanOut declaration below carries it.
+_VEHICLE_ID_PARAM: Final[str] = 'vehicleId'
+
+
+def _to_epoch_milliseconds(bound: datetime) -> int:
+    """Render one window bound as the epoch-millisecond int the wire takes.
+
+    The UTC guard is the codec-boundary discipline ``DateWindow`` defers
+    to its serialization point (DESIGN §4): a naive or non-UTC bound
+    reaching a request is a missed ingress, failed loudly.
+
+    Args:
+        bound: A window bound; must be canonical UTC.
+
+    Returns:
+        Milliseconds since the Unix epoch.
+
+    Raises:
+        ValueError: ``bound`` is naive or not canonical UTC.
+
+    Side Effects:
+        None.
+    """
+    return (require_utc(bound) - _UNIX_EPOCH) // _ONE_MILLISECOND
+
+
+@dataclass(frozen=True, slots=True)
+class SamsaraTripsSpecBuilder:
+    """Build the per-vehicle, date-windowed first request for trips.
+
+    The ``SpecBuilder`` for the trips ``RosterFanOut``: a fixed
+    ``GET base_url + path`` carrying the chain's member binding as query
+    parameters, verbatim (``{'vehicleId': <member>}`` -- the drivers-leaf
+    precedent), plus the resume window as ``startMs``/``endMs`` epoch
+    milliseconds. The endpoint is not paginated, so this first request
+    is the chain's only request; the page decoder returns no successor.
+
+    The canonical half-open ``[start, end)`` window maps to the wire as
+    ``startMs = start`` and ``endMs = end`` in epoch milliseconds. At
+    the millisecond boundary the wire's inclusive reading of ``endMs``
+    mismatches the half-open convention (a trip touching the exact end
+    instant may be returned) -- deliberately unadjusted: retrieval is
+    overlap-anchored and supersets start-anchored ownership anyway, and
+    the runner's post-fetch window filter keeps only trips whose start
+    lies in ``[start, end)``, so each trip lands in exactly the one
+    chunk owning its start and the boundary duplicate never persists.
+
+    Attributes:
+        base_url: Root of the Samsara API, trailing-slash-normalized by
+            the provider config so the leading-slash path joins
+            directly.
+        path: The endpoint's leading-slash request path
+            (``'/v1/fleet/trips'``).
+    """
+
+    base_url: str
+    path: str
+
+    def build_spec(
+        self, resume: ResumeValue, member_values: Mapping[str, str]
+    ) -> RequestSpec:
+        """Build one vehicle chain's windowed GET.
+
+        Args:
+            resume: The run's resume window. Must be a ``DateWindow`` --
+                a watermark endpoint always resumes from one; any other
+                value is a wiring bug.
+            member_values: The fan-out member binding, merged verbatim
+                as query parameters -- ``{'vehicleId': <id>}`` for a
+                roster chain (``vehicleId`` is REQUIRED by the wire; an
+                empty binding would earn the provider's own loud 400).
+
+        Returns:
+            A credential-less ``GET`` for ``base_url + path`` carrying
+            the member binding plus ``startMs``/``endMs`` epoch
+            milliseconds for the window's bounds. Auth headers are
+            layered on by the client's ``ProviderProfile``.
+
+        Raises:
+            TypeError: ``resume`` is not a ``DateWindow``.
+            ValueError: A window bound is not canonical UTC.
+
+        Side Effects:
+            None.
+        """
+        resume_window = require_date_window(resume, type(self).__name__)
+        params = dict(member_values)
+        params['startMs'] = str(_to_epoch_milliseconds(resume_window.start))
+        params['endMs'] = str(_to_epoch_milliseconds(resume_window.end))
+        return RequestSpec(
+            method=HttpMethod.GET,
+            url=f'{self.base_url}{self.path}',
+            params=params,
+        )
+
+
+def build_endpoint(config: SamsaraConfig) -> EndpointDefinition[Trip]:
+    """Build the Samsara trips watermark binding.
+
+    Per-vehicle trip history fetched incrementally: the run resumes from
+    a ``DateWindow`` (watermark with the provider's late-arrival
+    lookback from config -- which also absorbs trips materializing on
+    completion), the fetched trips are written to ``date=YYYY-MM-DD``
+    partitions on ``start_time``, and each refetched partition is
+    replaced. Records arrive as a top-level list under ``trips``,
+    unpaginated -- one response per (vehicle, window). The
+    ``request_shape`` declaration (``RosterFanOut``) names the Samsara
+    ``vehicle_ids`` roster; the orchestration entry resolves it to
+    members and fans one request chain per vehicle, passing each id to
+    the spec-builder's ``member_values`` -- this binding only declares
+    the strategies and the roster key, never the roster's feeder.
+
+    Args:
+        config: The validated Samsara configuration; supplies the base
+            URL the spec-builder joins to the trips path and the
+            lookback and cutoff the watermark mode carries.
+
+    Returns:
+        The frozen trips ``EndpointDefinition``. Construction validates
+        the ``WatermarkMode`` / ``DATE_PARTITIONED`` /
+        ``event_time_column`` triple against the response model.
+    """
+    return EndpointDefinition(
+        provider=Provider.SAMSARA,
+        name='trips',
+        spec_builder=SamsaraTripsSpecBuilder(
+            base_url=config.base_url, path=_TRIPS_PATH
+        ),
+        page_decoder=SinglePageDecoder(records_key=_RECORDS_KEY),
+        response_model=Trip,
+        quota_scope=QuotaScope.SAMSARA,
+        storage_kind=StorageKind.DATE_PARTITIONED,
+        sync_mode=WatermarkMode(
+            lookback=timedelta(days=config.lookback_days),
+            cutoff=timedelta(days=config.cutoff_days),
+        ),
+        event_time_column='start_time',
+        request_shape=RosterFanOut(
+            roster=RosterKey(Provider.SAMSARA, 'vehicle_ids'),
+            member_key=_VEHICLE_ID_PARAM,
+        ),
+    )

fleetpull/endpoints/samsara/vehicle_fuel_energy_reports.py

@@ -0,0 +1,139 @@
+# src/fleetpull/endpoints/samsara/vehicle_fuel_energy_reports.py
+"""The Samsara vehicle_fuel_energy_reports binding: the window-grain
+rollup surface -- the first fixed-unit-width watermark endpoint
+(probe-settled 2026-07-21, DESIGN section 8). The legacy hub's
+``vehicle_fuel_energy``, renamed per the name=snake-plural-of-model
+invariant (model ``VehicleFuelEnergyReport``).
+
+``GET /fleet/reports/vehicles/fuel-energy`` carries the standard
+``pagination {endCursor, hasNextPage}`` cursor contract, but the record
+list is NESTED: ``data`` is an OBJECT whose only key is
+``vehicleReports``, a list of report objects -- the
+``SamsaraWindowReportPageDecoder``'s shape. Reports are fleet-wide with
+per-record vehicle attribution, so there is NO fan-out -- the default
+``SingleFetch`` shape, declared by declaring nothing, and no roster is
+sourced or consumed.
+
+**THE ROLLUP GRAIN IS THE REQUEST WINDOW, proven twice:** widening a
+1-day window to 2 days GREW per-vehicle metrics (36 of 47 vehicles
+shared between the 1-day walk and the 2-day window's first page grew),
+and summing two adjacent day rollups reproduced the two-day
+rollup on only 178 of 267 vehicles (89/267 MISMATCHED across distance,
+engine run time, fuel, and energy). Day rows are NOT a lossless
+decomposition of wider windows -- each row is the provider's answer for
+exactly its window. Consequence: the binding declares
+``fixed_unit_days=1`` on its ``WatermarkMode`` -- the unit width is
+part of the ROW'S MEANING, so it must never float with
+``sync.backfill_chunk_days``. Rows carry NO event-time key of any kind;
+the decoder stamps each with the sent window, and
+``event_time_column='window_start'`` routes each day's rollup to its
+own partition (the vehicle-presence union across day windows holds:
+the two day windows' 145- and 242-vehicle sets union to exactly the
+two-day walk's 267, so per-day fetches lose no vehicle).
+
+The ``limit`` param is PROVEN IGNORED (the assignments placebo
+posture): limit=512, 513, and 10 on the 2-day window all returned
+identical paging (3 pages, 267 reports), and 513 was NOT rejected -- no
+enforced tier. The declared ``results_limit=100`` is
+documentation-by-declaration of the server's OWN observed ~100-report
+page size, not a working knob.
+
+The window rides this surface family's own ``startDate``/``endDate``
+param NAMES (full RFC3339 datetimes accepted despite the names --
+unlike every other probed Samsara vertical's ``startTime``/``endTime``;
+the shared ``SamsaraFuelEnergyReportSpecBuilder`` carries the
+provenance).
+"""
+
+from datetime import timedelta
+from typing import Final
+
+from fleetpull.config import SamsaraConfig
+from fleetpull.endpoints.samsara._spec_builders import (
+    SamsaraFuelEnergyReportSpecBuilder,
+)
+from fleetpull.endpoints.shared import (
+    EndpointDefinition,
+    StorageKind,
+    WatermarkMode,
+)
+from fleetpull.models.samsara import VehicleFuelEnergyReport
+from fleetpull.network.decoders import SamsaraWindowReportPageDecoder
+from fleetpull.vocabulary import Provider, QuotaScope
+
+__all__: list[str] = ['build_endpoint']
+
+_VEHICLE_FUEL_ENERGY_PATH: Final[str] = '/fleet/reports/vehicles/fuel-energy'
+_RECORDS_KEY: Final[str] = 'data'
+
+# The nested report key: `data` is an OBJECT whose only key is this
+# arm's report list (captured 2026-07-21).
+_REPORT_KEY: Final[str] = 'vehicleReports'
+
+# The per-page record count. ~100 is the server's OWN observed page
+# size, and the `limit` param is PROVEN IGNORED on this surface:
+# limit=512, 513, and 10 on the same 2-day window all returned
+# identical paging (3 pages, 267 reports); 513 was NOT rejected (no
+# enforced tier, captured 2026-07-21). Declaring 100 documents the
+# server's paging; it is not a working knob.
+_RESULTS_LIMIT: Final[int] = 100
+
+# The fixed work-unit width, in whole days. The rollup grain is the
+# request window (metrics GREW when the window widened) and day rollups
+# are NON-ADDITIVE into wider windows (89/267 mismatched, captured
+# 2026-07-21), so the unit width is part of the row's meaning and is
+# pinned here rather than left to sync.backfill_chunk_days.
+_FIXED_UNIT_DAYS: Final[int] = 1
+
+
+def build_endpoint(
+    config: SamsaraConfig,
+) -> EndpointDefinition[VehicleFuelEnergyReport]:
+    """Build the Samsara vehicle_fuel_energy_reports watermark binding.
+
+    Fleet-wide per-vehicle fuel-energy rollups fetched incrementally at
+    the fixed 1-day unit width: the run resumes from a ``DateWindow``
+    (watermark with the provider's late-arrival lookback from config),
+    the planner tiles it into exactly-one-day units (the declared
+    ``fixed_unit_days`` -- module docstring for the non-additivity
+    proof), each unit's reports are stamped with its window by the
+    decoder and written to the ``date=YYYY-MM-DD`` partition on
+    ``window_start``, and each refetched partition is replaced. Reports
+    arrive nested under ``data.vehicleReports``, walked by explicit
+    cursor pages (``limit`` on page one, ``after`` merged thereafter,
+    the ``startDate``/``endDate`` window persisting throughout),
+    terminal on ``hasNextPage: false``. No request shape is declared --
+    the endpoint is a fleet-wide ``SingleFetch``, the default.
+
+    Args:
+        config: The validated Samsara configuration; supplies the base
+            URL the spec-builder joins to the report path and the
+            lookback and cutoff the watermark mode carries.
+
+    Returns:
+        The frozen vehicle_fuel_energy_reports ``EndpointDefinition``.
+        Construction validates the ``WatermarkMode`` /
+        ``DATE_PARTITIONED`` / ``event_time_column`` triple against the
+        response model.
+    """
+    return EndpointDefinition(
+        provider=Provider.SAMSARA,
+        name='vehicle_fuel_energy_reports',
+        spec_builder=SamsaraFuelEnergyReportSpecBuilder(
+            base_url=config.base_url, path=_VEHICLE_FUEL_ENERGY_PATH
+        ),
+        page_decoder=SamsaraWindowReportPageDecoder(
+            records_key=_RECORDS_KEY,
+            report_key=_REPORT_KEY,
+            results_limit=_RESULTS_LIMIT,
+        ),
+        response_model=VehicleFuelEnergyReport,
+        quota_scope=QuotaScope.SAMSARA,
+        storage_kind=StorageKind.DATE_PARTITIONED,
+        sync_mode=WatermarkMode(
+            lookback=timedelta(days=config.lookback_days),
+            cutoff=timedelta(days=config.cutoff_days),
+            fixed_unit_days=_FIXED_UNIT_DAYS,
+        ),
+        event_time_column='window_start',
+    )