fleetpull 0.1.0__py3-none-any.whl

fleetpull/endpoints/samsara/_spec_builders.py

@@ -0,0 +1,202 @@
+# src/fleetpull/endpoints/samsara/_spec_builders.py
+"""The shared Samsara multi-leaf spec-builders.
+
+Two builder families, each serving one wire family through multiple
+leaves (the Motive ``_spec_builders`` promotion precedent):
+
+- ``SamsaraVehicleStatsSpecBuilder`` for the three
+  ``/fleet/vehicles/stats/history`` leaves (engine_states,
+  gps_readings, odometer_readings) -- one wire surface serving three
+  endpoints, each requesting exactly its own stat type, so the one
+  varying fact (``types``) is a builder field and the window rendering
+  is written once (three users at birth).
+- ``SamsaraFuelEnergyReportSpecBuilder`` for the two
+  ``/fleet/reports/{vehicles,drivers}/fuel-energy`` leaves -- one wire
+  family whose only varying fact is the path, and whose window rides
+  the surface family's own ``startDate``/``endDate`` param NAMES (two
+  users at birth).
+
+The idling_events leaf keeps its own builder: it carries no ``types``
+param and no naming quirk, and folding it in would trade a real
+one-family bundle for a provider-wide window-builder abstraction
+nobody asked for.
+"""
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Final
+
+from fleetpull.endpoints.shared import ResumeValue, require_date_window
+from fleetpull.network.contract import HttpMethod, RequestSpec
+from fleetpull.timing import to_iso8601
+
+__all__: list[str] = [
+    'RECORDS_KEY',
+    'RESULTS_LIMIT',
+    'STATS_HISTORY_PATH',
+    'SamsaraFuelEnergyReportSpecBuilder',
+    'SamsaraVehicleStatsSpecBuilder',
+]
+
+# The one probed wire surface's coinciding facts, stated once for the
+# three leaves (only the stat type varies per leaf). A re-probe that
+# moves any of these lands here and reaches every leaf.
+STATS_HISTORY_PATH: Final[str] = '/fleet/vehicles/stats/history'
+RECORDS_KEY: Final[str] = 'data'
+
+# The per-page vehicle count. 512 is THIS surface's probed maximum
+# (limit=512 -> HTTP 200, limit=513 -> HTTP 400, captured 2026-07-20):
+# the vehicles/drivers tier, NOT idling's 200. Never assume a sibling's
+# limit.
+RESULTS_LIMIT: Final[int] = 512
+
+# The stat-type selector, API-enforced on input: an unknown value is a
+# loud HTTP 400 naming the bogus type ('Invalid stat type(s): ...'),
+# never a silent empty page (captured 2026-07-20).
+_TYPES_PARAM: Final[str] = 'types'
+
+
+@dataclass(frozen=True, slots=True)
+class SamsaraVehicleStatsSpecBuilder:
+    """Build the fleet-wide, date-windowed first request for one stat type.
+
+    The ``SpecBuilder`` for a vehicle-stats single chain: a fixed
+    ``GET base_url + path`` carrying the resume window as RFC3339
+    ``startTime``/``endTime`` (the timing codec's ``to_iso8601``) plus
+    the FIXED ``types=<stat_type>`` selector baked into every request.
+    The decoder owns pagination: its ``first_request`` merges ``limit``
+    onto this spec and its ``after`` advance merges onto the sent spec,
+    so the window and the type selector persist across the whole
+    vehicle-axis cursor walk (the idling_events mechanism).
+
+    The canonical half-open ``[start, end)`` window maps to the wire as
+    ``startTime = start`` and ``endTime = end``. Retrieval is
+    READING-TIME anchored on exactly that half-open window
+    (probe-proven: a 12:00-13:00Z window returned min 12:00:03.062Z,
+    max 12:59:56.881Z), so a window's readings are exactly those
+    timestamped inside it; the runner's post-fetch window filter is
+    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
+            (``'/fleet/vehicles/stats/history'``).
+        stat_type: The one stat type this endpoint requests -- the
+            verbatim ``types`` wire value, which is also the
+            per-vehicle series key the decoder unnests.
+    """
+
+    base_url: str
+    path: str
+    stat_type: str
+
+    def build_spec(
+        self, resume: ResumeValue, member_values: Mapping[str, str]
+    ) -> RequestSpec:
+        """Build the fleet-wide, date-windowed, single-type 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
+            ``types=<stat_type>`` and 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 = {
+            _TYPES_PARAM: self.stat_type,
+            '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,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class SamsaraFuelEnergyReportSpecBuilder:
+    """Build the fleet-wide, date-windowed first request for one report arm.
+
+    The ``SpecBuilder`` for a fuel-energy report single chain: a fixed
+    ``GET base_url + path`` carrying the resume window as RFC3339
+    ``startDate``/``endDate`` (the timing codec's ``to_iso8601``). NOTE
+    the param NAMES: this surface family takes ``startDate``/``endDate``
+    -- unlike every other probed Samsara vertical's
+    ``startTime``/``endTime`` -- while accepting full RFC3339 datetimes
+    despite the names (probed with ``T00:00:00Z`` values, and a 1-hour
+    window returned 200; captured 2026-07-21). The rendering itself is
+    exactly the sibling windowed builders' ``[start, end)`` mapping.
+    The decoder owns pagination AND the window stamp: its
+    ``first_request`` merges ``limit`` onto this spec, its ``after``
+    advance merges onto the sent spec (so the window persists across
+    the whole walk), and it copies these two params back off the sent
+    spec onto every report row.
+
+    Attributes:
+        base_url: Root of the Samsara API, trailing-slash-normalized by
+            the provider config so the leading-slash path joins
+            directly.
+        path: The arm's leading-slash request path
+            (``'/fleet/reports/vehicles/fuel-energy'`` /
+            ``'/fleet/reports/drivers/fuel-energy'``) -- the one fact
+            varying between the two leaves.
+    """
+
+    base_url: str
+    path: str
+
+    def build_spec(
+        self, resume: ResumeValue, member_values: Mapping[str, str]
+    ) -> RequestSpec:
+        """Build the fleet-wide, date-windowed GET for one report arm.
+
+        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 ``startDate``/``endDate``
+            (the surface family's own param names). 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 = {
+            'startDate': to_iso8601(resume_window.start),
+            'endDate': to_iso8601(resume_window.end),
+        }
+        return RequestSpec(
+            method=HttpMethod.GET,
+            url=f'{self.base_url}{self.path}',
+            params=params,
+        )

fleetpull/endpoints/samsara/addresses.py

@@ -0,0 +1,77 @@
+# src/fleetpull/endpoints/samsara/addresses.py
+"""The Samsara addresses binding: a factory composing the addresses
+snapshot EndpointDefinition from resolved Samsara configuration.
+
+A binding cannot be a module-level constant because its spec-builder
+needs the run's configured base URL, known only after the YAML config
+loads; so the endpoint is a factory taking a validated ``SamsaraConfig``
+and returning the frozen ``EndpointDefinition`` the composition root
+hands to the client (the Motive leaf convention).
+
+The vehicles template verbatim (2026-07-20 probe session): a plain
+snapshot on the standard Samsara cursor contract -- ``data`` beside
+``pagination {endCursor, hasNextPage}`` -- with no roster sourced, no
+roster consumed, and no window. The full walk was the whole population
+in one page (25 records), and the walk is complete by construction:
+continuation is explicit on every page and a promised continuation
+without a cursor fails loudly in the decoder, so no completeness check
+is declared.
+"""
+
+from typing import Final
+
+from fleetpull.config import SamsaraConfig
+from fleetpull.endpoints.shared import (
+    EndpointDefinition,
+    SnapshotMode,
+    StaticGetSpecBuilder,
+    StorageKind,
+)
+from fleetpull.models.samsara import Address
+from fleetpull.network.decoders import SamsaraCursorPageDecoder
+from fleetpull.vocabulary import Provider, QuotaScope
+
+__all__: list[str] = ['build_endpoint']
+
+_ADDRESSES_PATH: Final[str] = '/addresses'
+_RECORDS_KEY: Final[str] = 'data'
+
+# The per-page record count. The limit tier was probed directly on THIS
+# endpoint (2026-07-20): limit=512 returned HTTP 200 and limit=513 a
+# loud HTTP 400, so /addresses sits in the vehicles/drivers 512 tier --
+# NOT the 200 tier of /idling/events. Samsara limit maxima are
+# per-endpoint (the idling_events capture's rule): never assume a
+# sibling's tier. A strong candidate for a user config knob.
+_RESULTS_LIMIT: Final[int] = 512
+
+
+def build_endpoint(config: SamsaraConfig) -> EndpointDefinition[Address]:
+    """Build the Samsara addresses snapshot binding.
+
+    A full-listing snapshot of the fleet's defined addresses (named
+    locations with geofences): no resume, a single parquet file, full
+    replacement each run. Records arrive as a top-level list under
+    ``data``, walked by explicit cursor pages (``limit`` on page one,
+    ``after`` merged thereafter), terminal on ``hasNextPage: false``.
+
+    Args:
+        config: The validated Samsara configuration; supplies the base
+            URL the spec-builder joins to the addresses path.
+
+    Returns:
+        The frozen addresses ``EndpointDefinition``.
+    """
+    return EndpointDefinition(
+        provider=Provider.SAMSARA,
+        name='addresses',
+        spec_builder=StaticGetSpecBuilder(
+            base_url=config.base_url, path=_ADDRESSES_PATH
+        ),
+        page_decoder=SamsaraCursorPageDecoder(
+            records_key=_RECORDS_KEY, results_limit=_RESULTS_LIMIT
+        ),
+        response_model=Address,
+        quota_scope=QuotaScope.SAMSARA,
+        storage_kind=StorageKind.SINGLE,
+        sync_mode=SnapshotMode(),
+    )

fleetpull/endpoints/samsara/asset_locations.py

@@ -0,0 +1,217 @@
+# src/fleetpull/endpoints/samsara/asset_locations.py
+"""The Samsara asset_locations binding: the windowed batched roster
+fan-out -- the first ``BatchedRosterFanOut`` consumer.
+
+``GET /assets/location-and-speed/stream`` is a modern-envelope surface
+(``data`` + ``pagination {endCursor, hasNextPage}`` -- the standard
+cursor contract; the ``endCursor`` is a fat composite token, opaque,
+passed back verbatim as ``after`` like every other cursor). The legacy
+hub called this surface ``location_stream``; the shipped endpoint is
+``asset_locations`` per the name=plural-of-entity invariant.
+
+The ``ids`` parameter is REQUIRED: omitting it is a loud HTTP 400
+(``"Need to include asset IDs to filter by."``), and the batch cap is
+API-ENFORCED AT 50 -- 50 comma-joined ids returned 200 while 100,
+200, and 609 each returned HTTP 400 naming the bound (``"Need to
+filter by 50 or less asset IDs or syncTokens."``; captured
+2026-07-20). So the binding declares
+``request_shape=BatchedRosterFanOut`` over the Samsara ``vehicle_ids``
+roster (declared beside its feeder in ``endpoints/samsara/vehicles.py``;
+this module knows only the ``RosterKey``): one cursor-walk chain per
+sorted 50-member batch, the batch comma-joined into the ``ids`` query
+parameter. The batch is transport packing only -- every record carries
+its own ``asset.id`` attribution, so no member attribution rides on the
+request mapping, and the fan-out driver's progress narration counts
+BATCHES for this shape (a deliberate, recorded consequence -- DESIGN
+section 8).
+
+The windowed leaf builder carries the resume window as RFC3339
+``startTime``/``endTime`` (the idling_events builder precedent) and
+merges the batch binding verbatim as a query parameter (the trips
+member-merge precedent); the decoder's ``first_request`` merges
+``limit`` and its ``after`` advance merges onto the SENT spec, so the
+window and the batch ride every page of each chain's walk.
+
+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:03Z..12:59:56Z. Consequence:
+``event_time_column='happened_at_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 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 (
+    BatchedRosterFanOut,
+    EndpointDefinition,
+    ResumeValue,
+    StorageKind,
+    WatermarkMode,
+    require_date_window,
+)
+from fleetpull.models.samsara import AssetLocation
+from fleetpull.network.contract import HttpMethod, RequestSpec
+from fleetpull.network.decoders import SamsaraCursorPageDecoder
+from fleetpull.roster import RosterKey
+from fleetpull.timing import to_iso8601
+from fleetpull.vocabulary import Provider, QuotaScope
+
+__all__: list[str] = [
+    'SamsaraAssetLocationsSpecBuilder',
+    'build_endpoint',
+]
+
+_ASSET_LOCATIONS_PATH: Final[str] = '/assets/location-and-speed/stream'
+_RECORDS_KEY: Final[str] = 'data'
+
+# The per-page record count. 512 is THIS endpoint's probed maximum
+# (limit=512 -> HTTP 200, limit=513 -> HTTP 400, captured 2026-07-20):
+# the vehicles/drivers tier, NOT idling's 200. Never assume a sibling's
+# limit.
+_RESULTS_LIMIT: Final[int] = 512
+
+# 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 trips
+# stance). Each member value is one sorted, comma-joined 50-id batch.
+_IDS_PARAM: Final[str] = 'ids'
+
+# The batch cap is API-ENFORCED AT 50, probed directly: 50 comma-joined
+# ids -> HTTP 200; 100/200/609 -> HTTP 400 '{"message": "Need to filter
+# by 50 or less asset IDs or syncTokens."}' (captured 2026-07-20).
+_BATCH_SIZE: Final[int] = 50
+
+
+@dataclass(frozen=True, slots=True)
+class SamsaraAssetLocationsSpecBuilder:
+    """Build one batch chain's date-windowed first request.
+
+    The ``SpecBuilder`` for the asset_locations ``BatchedRosterFanOut``:
+    a fixed ``GET base_url + path`` carrying the chain's batch binding
+    verbatim as query parameters (``{'ids': '<id>,<id>,...'}`` -- the
+    trips member-merge precedent) plus 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 and the batch 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
+    reading-time anchored on exactly that half-open window (module
+    docstring), so a window's readings are exactly those timestamped
+    inside it; the runner's post-fetch window filter is 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
+            (``'/assets/location-and-speed/stream'``).
+    """
+
+    base_url: str
+    path: str
+
+    def build_spec(
+        self, resume: ResumeValue, member_values: Mapping[str, str]
+    ) -> RequestSpec:
+        """Build one batch 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 batch binding, merged verbatim as query
+                parameters -- ``{'ids': <comma-joined batch>}`` for a
+                batched roster chain (``ids`` 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 batch binding plus 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 = dict(member_values)
+        params['startTime'] = to_iso8601(resume_window.start)
+        params['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[AssetLocation]:
+    """Build the Samsara asset_locations watermark binding.
+
+    Per-asset location 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 ``happened_at_time``, and each
+    refetched partition is replaced. Records arrive as a top-level list
+    under ``data``, already at the reading grain, walked by explicit
+    cursor pages per batch chain (``limit`` on page one, ``after``
+    merged thereafter, the window and batch parameters persisting
+    throughout), terminal on ``hasNextPage: false``. The
+    ``request_shape`` declaration (``BatchedRosterFanOut``) names the
+    Samsara ``vehicle_ids`` roster; the orchestration entry resolves it
+    to members and the shape seam fans one chain per sorted 50-member
+    comma-joined batch, passing each batch string to the spec-builder's
+    ``member_values`` -- this binding only declares the strategies, the
+    roster key, and the probed cap, never the roster's feeder.
+
+    Args:
+        config: The validated Samsara configuration; supplies the base
+            URL the spec-builder joins to the stream path and the
+            lookback and cutoff the watermark mode carries.
+
+    Returns:
+        The frozen asset_locations ``EndpointDefinition``. Construction
+        validates the ``WatermarkMode`` / ``DATE_PARTITIONED`` /
+        ``event_time_column`` triple against the response model.
+    """
+    return EndpointDefinition(
+        provider=Provider.SAMSARA,
+        name='asset_locations',
+        spec_builder=SamsaraAssetLocationsSpecBuilder(
+            base_url=config.base_url, path=_ASSET_LOCATIONS_PATH
+        ),
+        page_decoder=SamsaraCursorPageDecoder(
+            records_key=_RECORDS_KEY, results_limit=_RESULTS_LIMIT
+        ),
+        response_model=AssetLocation,
+        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='happened_at_time',
+        request_shape=BatchedRosterFanOut(
+            roster=RosterKey(Provider.SAMSARA, 'vehicle_ids'),
+            member_key=_IDS_PARAM,
+            batch_size=_BATCH_SIZE,
+        ),
+    )

fleetpull/endpoints/samsara/driver_fuel_energy_reports.py

@@ -0,0 +1,124 @@
+# src/fleetpull/endpoints/samsara/driver_fuel_energy_reports.py
+"""The Samsara driver_fuel_energy_reports binding: the driver arm of
+the window-grain fuel-energy report pair (probe-settled 2026-07-21,
+DESIGN section 8). The legacy hub's ``driver_fuel_energy``, renamed per
+the name=snake-plural-of-model invariant (model
+``DriverFuelEnergyReport``).
+
+``GET /fleet/reports/drivers/fuel-energy`` is the vehicle arm's wire
+family with the entity swapped: the standard cursor contract over the
+NESTED record list (``data`` an OBJECT whose only key is
+``driverReports``), reports fleet-wide with per-record driver
+attribution (``driver {id, name}``; NO ``externalIds`` was ever
+observed on this arm), so no fan-out and no roster -- the default
+``SingleFetch`` shape, declared by declaring nothing.
+
+The window-grain facts are the pair's, proven on the family
+(vehicle_fuel_energy_reports carries the full evidence): the rollup
+grain is the request window and day rollups are NON-ADDITIVE into
+wider windows (89/267 mismatched, captured 2026-07-21), so the binding
+declares ``fixed_unit_days=1`` -- the unit width is part of the ROW'S
+MEANING and never floats with ``sync.backfill_chunk_days``. Rows carry
+NO event-time key; the decoder stamps each with the sent window and
+``event_time_column='window_start'`` routes each day's rollup to its
+own partition. Pagination is real on this arm too: a 1-day driver
+window showed ``hasNextPage: true`` at 100 reports, the same ~100
+server-owned page size the placebo ``limit`` cannot move --
+``results_limit=100`` is documentation-by-declaration.
+
+The window rides the family's own ``startDate``/``endDate`` param
+NAMES (RFC3339 datetimes accepted despite the names; 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 DriverFuelEnergyReport
+from fleetpull.network.decoders import SamsaraWindowReportPageDecoder
+from fleetpull.vocabulary import Provider, QuotaScope
+
+__all__: list[str] = ['build_endpoint']
+
+_DRIVER_FUEL_ENERGY_PATH: Final[str] = '/fleet/reports/drivers/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] = 'driverReports'
+
+# The per-page record count. ~100 is the server's OWN observed page
+# size (a 1-day driver window showed hasNextPage: true at 100 reports)
+# and the `limit` param is PROVEN IGNORED on this surface family
+# (limit=512/513/10 all paged identically; 513 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 pair's window-grain
+# and non-additivity proofs (module docstring; captured 2026-07-21):
+# the unit width is part of the row's meaning, pinned here rather than
+# left to sync.backfill_chunk_days.
+_FIXED_UNIT_DAYS: Final[int] = 1
+
+
+def build_endpoint(
+    config: SamsaraConfig,
+) -> EndpointDefinition[DriverFuelEnergyReport]:
+    """Build the Samsara driver_fuel_energy_reports watermark binding.
+
+    Fleet-wide per-driver 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.driverReports``, 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 driver_fuel_energy_reports ``EndpointDefinition``.
+        Construction validates the ``WatermarkMode`` /
+        ``DATE_PARTITIONED`` / ``event_time_column`` triple against the
+        response model.
+    """
+    return EndpointDefinition(
+        provider=Provider.SAMSARA,
+        name='driver_fuel_energy_reports',
+        spec_builder=SamsaraFuelEnergyReportSpecBuilder(
+            base_url=config.base_url, path=_DRIVER_FUEL_ENERGY_PATH
+        ),
+        page_decoder=SamsaraWindowReportPageDecoder(
+            records_key=_RECORDS_KEY,
+            report_key=_REPORT_KEY,
+            results_limit=_RESULTS_LIMIT,
+        ),
+        response_model=DriverFuelEnergyReport,
+        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',
+    )