fleetpull 0.1.0__py3-none-any.whl

fleetpull/endpoints/samsara/driver_vehicle_assignments.py

@@ -0,0 +1,211 @@
+# src/fleetpull/endpoints/samsara/driver_vehicle_assignments.py
+"""The Samsara driver_vehicle_assignments binding: the fleet-wide
+windowed cursor walk with a fixed ``filterBy`` param -- the
+idling_events species carrying the trips overlap-anchoring decisions.
+
+``GET /fleet/driver-vehicle-assignments`` is a modern-envelope surface
+(``data`` + ``pagination {endCursor, hasNextPage}`` -- the standard
+cursor contract). Assignments are fleet-wide with per-record driver AND
+vehicle attribution, so there is NO fan-out -- the default
+``SingleFetch`` shape, declared by declaring nothing.
+
+``filterBy`` is REQUIRED and API-enforced to a two-value vocabulary:
+omitting it is HTTP 400, and ``filterBy=bogus`` is HTTP 400 naming the
+vocabulary (``value of filterBy must be one of "drivers", "vehicles"
+but got value "bogus"``) -- loud, never silent-empty. The two sweeps
+are ONE DATASET: full 24-hour walks under ``filterBy=vehicles`` and
+``filterBy=drivers`` returned IDENTICAL row sets (216 = 216, proven
+equal as tuple sets; captured 2026-07-20), so the axis is a traversal
+choice, not a data partition -- one endpoint, ``filterBy=vehicles``
+baked into every request as a FIXED param (the stats triple's ``types``
+builder idiom), no sweep, no second endpoint (DESIGN section 8).
+
+The server pages at a FIXED 50 records and the ``limit`` param is
+PROVEN IGNORED: limit=1, 5, 100, 512, 513 -- and no limit at all --
+each returned a 50-record first page with ``hasNextPage: true``, and
+513 was NOT rejected (no enforced tier on this surface, unlike every
+probed sibling). The declared ``results_limit=50`` is
+documentation-by-declaration of the server's OWN observed page size,
+not a working knob.
+
+Retrieval is OVERLAP-anchored, probe-proven on adjacent day windows:
+two neighboring 24-hour windows shared 5 midnight-spanning assignments
+(identical tuples in both), and the later window carried 5 rows whose
+``startTime`` precedes the window start plus 2 whose ``endTime`` is
+at/after the window end. Per DESIGN section 4 (the trips decisions,
+mirrored): overlap retrieval supersets start-anchored ownership, so
+``event_time_column='start_time'``, the runner's post-fetch window
+filter assigns each assignment to the single chunk owning its start,
+no wire pad is needed, and wholesale partition replacement handles
+midnight-spanning intervals exactly as it does for trips.
+
+No range cap was probed on this surface; the default 7-day chunk
+width is live-proven (a 7-day unit fetched 6,897 records clean,
+2026-07-21).
+"""
+
+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 DriverVehicleAssignment
+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] = [
+    'SamsaraDriverVehicleAssignmentsSpecBuilder',
+    'build_endpoint',
+]
+
+_ASSIGNMENTS_PATH: Final[str] = '/fleet/driver-vehicle-assignments'
+_RECORDS_KEY: Final[str] = 'data'
+
+# The per-page record count. 50 is the server's OWN observed page size,
+# and the `limit` param is PROVEN IGNORED on this surface: limit=1, 5,
+# 100, 512, 513 -- and no limit at all -- each returned a 50-record
+# first page with hasNextPage: true; 513 was NOT rejected (no enforced
+# tier, captured 2026-07-20). Declaring 50 documents the server's
+# paging; it is not a working knob.
+_RESULTS_LIMIT: Final[int] = 50
+
+# The traversal-axis selector, REQUIRED and API-enforced on input to a
+# two-value vocabulary (missing -> HTTP 400; filterBy=bogus -> HTTP 400
+# naming 'drivers'/'vehicles'; captured 2026-07-20). Both sweeps return
+# the IDENTICAL row set, so one value is baked into every request --
+# the axis is traversal, not partition (DESIGN section 8).
+_FILTER_BY_PARAM: Final[str] = 'filterBy'
+_FILTER_BY_VALUE: Final[str] = 'vehicles'
+
+
+@dataclass(frozen=True, slots=True)
+class SamsaraDriverVehicleAssignmentsSpecBuilder:
+    """Build the fleet-wide, date-windowed first request for assignments.
+
+    The ``SpecBuilder`` for the driver_vehicle_assignments 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 ``filterBy=vehicles`` selector baked
+    into every request (the stats triple's ``types`` idiom -- module
+    docstring for the one-dataset proof). 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
+    selector 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
+    OVERLAP-anchored (module docstring), so a window also returns
+    assignments merely straddling its bounds -- deliberately unpadded:
+    overlap retrieval supersets start-anchored ownership, and the
+    runner's post-fetch window filter keeps only assignments whose
+    start lies in ``[start, end)``, so each assignment lands in exactly
+    the one chunk owning its start and boundary straddlers never
+    persist twice.
+
+    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/driver-vehicle-assignments'``).
+    """
+
+    base_url: str
+    path: str
+
+    def build_spec(
+        self, resume: ResumeValue, member_values: Mapping[str, str]
+    ) -> RequestSpec:
+        """Build the fleet-wide, date-windowed, fixed-filter 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
+            ``filterBy=vehicles`` 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 = {
+            _FILTER_BY_PARAM: _FILTER_BY_VALUE,
+            '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[DriverVehicleAssignment]:
+    """Build the Samsara driver_vehicle_assignments watermark binding.
+
+    Fleet-wide driver-vehicle assignment intervals fetched
+    incrementally: the run resumes from a ``DateWindow`` (watermark
+    with the provider's late-arrival lookback from config), the fetched
+    assignments are written to ``date=YYYY-MM-DD`` partitions on
+    ``start_time``, and each refetched partition is replaced --
+    absorbing the overlap-retrieved midnight straddlers exactly as
+    trips does (module docstring). Records arrive as a top-level list
+    under ``data``, walked by explicit cursor pages (``limit`` on page
+    one, ``after`` merged thereafter, the window and ``filterBy``
+    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 assignments path and the
+            lookback and cutoff the watermark mode carries.
+
+    Returns:
+        The frozen driver_vehicle_assignments ``EndpointDefinition``.
+        Construction validates the ``WatermarkMode`` /
+        ``DATE_PARTITIONED`` / ``event_time_column`` triple against the
+        response model.
+    """
+    return EndpointDefinition(
+        provider=Provider.SAMSARA,
+        name='driver_vehicle_assignments',
+        spec_builder=SamsaraDriverVehicleAssignmentsSpecBuilder(
+            base_url=config.base_url, path=_ASSIGNMENTS_PATH
+        ),
+        page_decoder=SamsaraCursorPageDecoder(
+            records_key=_RECORDS_KEY, results_limit=_RESULTS_LIMIT
+        ),
+        response_model=DriverVehicleAssignment,
+        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/drivers.py

@@ -0,0 +1,169 @@
+# src/fleetpull/endpoints/samsara/drivers.py
+"""The Samsara drivers binding: the two-sweep activation-status snapshot,
+the first ``ParamSweep`` consumer.
+
+The default ``/fleet/drivers`` listing IS the active set exactly -- the
+2026-07-20 probe matched it record-for-record against
+``driverActivationStatus=active`` (460 ids, identical) -- while the
+deactivated sweep returned 372 fully disjoint records INVISIBLE to the
+default listing: 45% of the 832-driver population. The one complete
+driver dataset is therefore the union of both sweeps, so this binding
+declares ``request_shape=ParamSweep`` over the two statuses; the shared
+shape-resolution seam fans one request chain per value through the
+member-agnostic ``FanOutRequestDriver``, and the
+``driver_activation_status`` column carries the split in the one stored
+dataset.
+
+No completeness check is declared, on two proofs. Continuation is
+explicit per page (the vehicles cursor contract, proven per-type on
+drivers: a limit=5 walk of 92 pages returned 460/460 unique ascending
+ids with no boundary overlap or loss), and the sweep vocabulary is
+API-enforced: ``driverActivationStatus`` is a strict closed enum whose
+every probed variant -- case changes, comma-joins, repeated keys, bogus
+values -- returned HTTP 400 naming the two admissible values, loudly,
+never a silent empty listing. A typo'd sweep value can therefore never
+masquerade as an empty partition.
+
+The existing ``SamsaraCursorPageDecoder`` needed NO change for the
+sweep: its advance merges ``after`` onto the SENT spec, so a
+first-request query parameter persists across the whole walk -- proven
+live by a limit=50 deactivated walk (8 pages, 50x7+22, 372/372 unique,
+every record deactivated, a fresh cursor per page, the standard
+terminal). The spec builder below exists because the shared
+``StaticGetSpecBuilder`` deliberately ignores ``member_values`` (a
+single-chain snapshot binds no member); a sweep chain binds one query
+parameter, so this endpoint's builder merges the member binding
+verbatim as query parameters (the Motive vehicle_locations
+leaf-builder precedent, which renders its member into the URL path
+instead).
+"""
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Final
+
+from fleetpull.config import SamsaraConfig
+from fleetpull.endpoints.shared import (
+    EndpointDefinition,
+    ParamSweep,
+    ResumeValue,
+    SnapshotMode,
+    StorageKind,
+)
+from fleetpull.models.samsara import Driver
+from fleetpull.network.contract import HttpMethod, RequestSpec
+from fleetpull.network.decoders import SamsaraCursorPageDecoder
+from fleetpull.vocabulary import Provider, QuotaScope
+
+__all__: list[str] = [
+    'SamsaraDriversSpecBuilder',
+    'build_endpoint',
+]
+
+_DRIVERS_PATH: Final[str] = '/fleet/drivers'
+_RECORDS_KEY: Final[str] = 'data'
+
+# The per-page record count. 512 is Samsara's documented list-endpoint
+# maximum, accepted on /fleet/drivers (captured 2026-07-20); the cursor
+# mechanics behind it were proven per-type by a limit=5 walk -- 92
+# pages, 460/460 unique ascending ids, no boundary overlap or loss.
+_RESULTS_LIMIT: Final[int] = 512
+
+# The sweep's 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 value
+# set is API-closed -- any other value is a loud HTTP 400 (captured
+# 2026-07-20), never a silent empty listing.
+_ACTIVATION_STATUS_PARAM: Final[str] = 'driverActivationStatus'
+_ACTIVATION_STATUS_VALUES: Final[tuple[str, ...]] = ('active', 'deactivated')
+
+
+@dataclass(frozen=True, slots=True)
+class SamsaraDriversSpecBuilder:
+    """Build the per-sweep first request for drivers.
+
+    The ``SpecBuilder`` for the drivers ``ParamSweep``: a fixed
+    ``GET base_url + path`` carrying the chain's member binding as query
+    parameters, verbatim -- each sweep chain's ``member_values`` is
+    ``{'driverActivationStatus': <value>}``, and the decoder's ``after``
+    advance merges onto this spec, so the status parameter persists
+    across every page of the chain's walk (module docstring). Exists
+    because the shared ``StaticGetSpecBuilder`` deliberately ignores
+    ``member_values``; this endpoint's member IS a query parameter.
+
+    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/drivers'``).
+    """
+
+    base_url: str
+    path: str
+
+    def build_spec(
+        self, resume: ResumeValue, member_values: Mapping[str, str]
+    ) -> RequestSpec:
+        """Build one sweep chain's first request.
+
+        Args:
+            resume: Accepted to satisfy the protocol; unused -- a
+                snapshot resumes from nothing.
+            member_values: The chain's member binding, merged verbatim
+                as query parameters -- ``{'driverActivationStatus':
+                <value>}`` for a sweep chain.
+
+        Returns:
+            A credential-less ``GET`` for ``base_url + path`` carrying
+            the member binding as query parameters. Auth headers are
+            layered on by the client's ``ProviderProfile``; pagination
+            parameters are injected by the page decoder's
+            ``first_request``.
+
+        Side Effects:
+            None.
+        """
+        return RequestSpec(
+            method=HttpMethod.GET,
+            url=f'{self.base_url}{self.path}',
+            params=dict(member_values),
+        )
+
+
+def build_endpoint(config: SamsaraConfig) -> EndpointDefinition[Driver]:
+    """Build the Samsara drivers two-sweep snapshot binding.
+
+    A full-listing snapshot of the fleet's drivers, complete only as the
+    union of the two activation-status sweeps (module docstring): the
+    declared ``ParamSweep`` fans one cursor-walked chain per status, and
+    every run fully replaces the single parquet file with that union.
+    Records arrive as a top-level list under ``data``, walked by
+    explicit cursor pages (``limit`` on page one, ``after`` merged
+    thereafter, the status parameter persisting throughout), terminal on
+    ``hasNextPage: false``.
+
+    Args:
+        config: The validated Samsara configuration; supplies the base
+            URL the spec-builder joins to the drivers path.
+
+    Returns:
+        The frozen drivers ``EndpointDefinition``.
+    """
+    return EndpointDefinition(
+        provider=Provider.SAMSARA,
+        name='drivers',
+        spec_builder=SamsaraDriversSpecBuilder(
+            base_url=config.base_url, path=_DRIVERS_PATH
+        ),
+        page_decoder=SamsaraCursorPageDecoder(
+            records_key=_RECORDS_KEY, results_limit=_RESULTS_LIMIT
+        ),
+        response_model=Driver,
+        quota_scope=QuotaScope.SAMSARA,
+        storage_kind=StorageKind.SINGLE,
+        sync_mode=SnapshotMode(),
+        request_shape=ParamSweep(
+            param=_ACTIVATION_STATUS_PARAM, values=_ACTIVATION_STATUS_VALUES
+        ),
+    )

fleetpull/endpoints/samsara/engine_states.py

@@ -0,0 +1,114 @@
+# src/fleetpull/endpoints/samsara/engine_states.py
+"""The Samsara engine_states binding: the vehicle-stats windowed cursor
+walk for ``types=engineStates`` -- 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=engineStates`` 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:
+138 vehicles, 138 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 EngineState
+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] = 'engineStates'
+
+
+def build_endpoint(config: SamsaraConfig) -> EndpointDefinition[EngineState]:
+    """Build the Samsara engine_states watermark binding.
+
+    Fleet-wide engine-state 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
+    ``engineStates`` 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 engine_states ``EndpointDefinition``. Construction
+        validates the ``WatermarkMode`` / ``DATE_PARTITIONED`` /
+        ``event_time_column`` triple against the response model.
+    """
+    return EndpointDefinition(
+        provider=Provider.SAMSARA,
+        name='engine_states',
+        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=EngineState,
+        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/gps_readings.py

@@ -0,0 +1,113 @@
+# src/fleetpull/endpoints/samsara/gps_readings.py
+"""The Samsara gps_readings binding: the vehicle-stats windowed cursor
+walk for ``types=gps`` -- 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=gps`` 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 (the 24-hour gps
+sample: 569 vehicles, 569 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 GpsReading
+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] = 'gps'
+
+
+def build_endpoint(config: SamsaraConfig) -> EndpointDefinition[GpsReading]:
+    """Build the Samsara gps_readings watermark binding.
+
+    Fleet-wide GPS 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 ``gps`` 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 gps_readings ``EndpointDefinition``. Construction
+        validates the ``WatermarkMode`` / ``DATE_PARTITIONED`` /
+        ``event_time_column`` triple against the response model.
+    """
+    return EndpointDefinition(
+        provider=Provider.SAMSARA,
+        name='gps_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=GpsReading,
+        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',
+    )