fleetpull 0.1.0__py3-none-any.whl

fleetpull/network/decoders/samsara.py

@@ -0,0 +1,343 @@
+# src/fleetpull/network/decoders/samsara.py
+"""Samsara page decoders: the cursor walk and its series-unnesting
+composition for the vehicle-stats surfaces
+(sources: scrubbed provider-behavior verification, June 2026; cursor
+contract from provider documentation, proven live 2026-07-17 -- the
+advance continued across a real page boundary with no overlap or loss,
+and the terminal page carried ``hasNextPage: false`` beside an
+EMPTY-STRING ``endCursor``, the shape the continuation guard below is
+calibrated against).
+
+Records arrive as a top-level list under a per-endpoint key; the
+``pagination`` block carries ``endCursor``/``hasNextPage``. The first
+page sends ``limit`` and no ``after``; subsequent pages send
+``after=<endCursor>`` (merged onto the sent spec, so ``limit``
+persists). Decoder logic deliberately resembles its siblings without
+sharing code; the cursor verdict is written once here
+(``cursor_page_advance``, exported so ``samsara_reports.py`` shares it)
+and consumed by every decoder that walks the cursor.
+The one deliberate cross-module share is the window stamp
+(``_window_stamp.py``): the synthesized keys are our own
+provider-uniform vocabulary, not envelope logic.
+
+``SamsaraVehicleSeriesPageDecoder`` composes the cursor decoder by
+delegation for ``/fleet/vehicles/stats/history``, whose cursor walks
+the VEHICLE axis while each vehicle record nests a per-type reading
+series (probe-settled 2026-07-20, DESIGN section 8).
+
+The window-stamping report family for the fuel-energy report surfaces
+(``SamsaraWindowReportPageDecoder``) lives in ``samsara_reports.py``,
+sharing this module's cursor verdict and first-page shape.
+"""
+
+from dataclasses import dataclass
+from typing import Final
+
+from pydantic import Field
+
+from fleetpull.exceptions import ProviderResponseError
+from fleetpull.network.contract import (
+    DecodedPage,
+    PageAdvance,
+    RequestSpec,
+    StrictEnvelopeSlice,
+    require_record_list,
+    validated_envelope_slice,
+)
+from fleetpull.vocabulary import JsonObject, JsonValue
+
+__all__: list[str] = [
+    'SamsaraCursorPageDecoder',
+    'SamsaraVehicleSeriesPageDecoder',
+    'cursor_page_advance',
+    'first_page_spec',
+]
+
+# Wire-protocol tokens: Final constants, not an enum. Deliberately unshared.
+_AFTER_PARAM: Final[str] = 'after'
+_LIMIT_PARAM: Final[str] = 'limit'
+
+
+class _SamsaraPageEcho(StrictEnvelopeSlice):
+    """The pagination block Samsara returns on every page."""
+
+    has_next_page: bool = Field(alias='hasNextPage')
+    end_cursor: str | None = Field(default=None, alias='endCursor')
+
+
+class _SamsaraEnvelope(StrictEnvelopeSlice):
+    """Envelope slice: locates the echo; the record key is ignored."""
+
+    pagination: _SamsaraPageEcho
+
+
+def cursor_page_advance(sent: RequestSpec, envelope: JsonValue) -> PageAdvance:
+    """Compute one page's cursor verdict from its ``pagination`` echo.
+
+    The one cursor contract every Samsara walk shares, written once for
+    the decoders in this module and the report family beside it
+    (``samsara_reports.py`` -- a same-provider extraction, not a
+    cross-provider abstraction): terminal on ``hasNextPage: false``;
+    otherwise ``after=<endCursor>`` merges onto the SENT spec, so every
+    first-request parameter (``limit``, a window, a fixed selector)
+    persists across the whole walk. ``durable_progress`` is always
+    ``None`` -- Samsara cursors are fetch-private.
+
+    Args:
+        sent: The spec that produced this page.
+        envelope: The parsed response body.
+
+    Returns:
+        The page's pagination verdict.
+
+    Raises:
+        ProviderResponseError: The ``pagination`` block is structurally
+            violating, including continuation promised without a cursor.
+    """
+    echo = validated_envelope_slice(_SamsaraEnvelope, envelope).pagination
+    if not echo.has_next_page:
+        return PageAdvance(next_spec=None, durable_progress=None)
+    if echo.end_cursor is None or echo.end_cursor == '':
+        # Continuation promised without a cursor: silently finishing
+        # here would truncate data -- the one failure mode a fetch
+        # library must never have.
+        raise ProviderResponseError(
+            detail='hasNextPage is true but endCursor is missing or empty'
+        )
+    next_spec = sent.with_merged_params({_AFTER_PARAM: echo.end_cursor})
+    return PageAdvance(next_spec=next_spec, durable_progress=None)
+
+
+def first_page_spec(spec: RequestSpec, results_limit: int) -> RequestSpec:
+    """Page one's spec: ``limit`` merged, and deliberately NO ``after``.
+
+    The first-request shape every Samsara cursor walk sends, written once
+    for this module's decoders and the report family beside it: the shared
+    cursor verdict's ``after`` merge layers onto this spec, so the limit
+    persists across every subsequent page.
+
+    Args:
+        spec: The endpoint's base first request.
+        results_limit: The per-page record count to request via ``limit``.
+
+    Returns:
+        The first request with ``limit`` merged.
+    """
+    return spec.with_merged_params({_LIMIT_PARAM: str(results_limit)})
+
+
+@dataclass(frozen=True, slots=True)
+class SamsaraCursorPageDecoder:
+    """Decode Samsara's top-level-list pages and cursor.
+
+    Attributes:
+        records_key: The top-level key holding the record list.
+        results_limit: The per-page record count requested via the
+            ``limit`` query parameter (pagination parameters are the
+            decoder's, per the ``StaticGetSpecBuilder`` seam).
+    """
+
+    records_key: str
+    results_limit: int
+
+    def first_request(self, spec: RequestSpec) -> RequestSpec:
+        """Send page one via the shared first-page shape (``first_page_spec``)."""
+        return first_page_spec(spec, self.results_limit)
+
+    def decode_page(self, sent: RequestSpec, envelope: JsonValue) -> DecodedPage:
+        """Extract the records and compute the cursor verdict.
+
+        Args:
+            sent: The spec that produced this page.
+            envelope: The parsed response body.
+
+        Returns:
+            The records and the pagination verdict; ``durable_progress``
+            is always None -- Samsara cursors are fetch-private.
+
+        Raises:
+            ProviderResponseError: When the record-bearing shape or the
+                cursor block is structurally violating, including
+                continuation promised without a cursor.
+        """
+        records = require_record_list(envelope, self.records_key)
+        return DecodedPage(records=records, advance=cursor_page_advance(sent, envelope))
+
+
+# The vehicle-stats wire keys the unnesting reads (2026-07-20 capture):
+# per-vehicle identity is `id`/`name` plus the `externalIds` object's
+# literal DOTTED keys `samsara.serial`/`samsara.vin`.
+_VEHICLE_ID_SOURCE_KEY: Final[str] = 'id'
+_VEHICLE_NAME_SOURCE_KEY: Final[str] = 'name'
+_EXTERNAL_IDS_KEY: Final[str] = 'externalIds'
+_SERIAL_SOURCE_KEY: Final[str] = 'samsara.serial'
+_VIN_SOURCE_KEY: Final[str] = 'samsara.vin'
+
+# The synthesized identity keys merged onto each emitted reading. Chosen
+# to be collision-free against every series key observed in the
+# 2026-07-20 census (`time`, `value`, `latitude`, `longitude`,
+# `headingDegrees`, `speedMilesPerHour`, `isEcuSpeed`, `reverseGeo`,
+# `address`), so the reading-keys-win merge order below never actually
+# discards an identity key.
+_VEHICLE_ID_KEY: Final[str] = 'vehicleId'
+_VEHICLE_NAME_KEY: Final[str] = 'vehicleName'
+_VEHICLE_SERIAL_KEY: Final[str] = 'vehicleSerial'
+_VEHICLE_VIN_KEY: Final[str] = 'vehicleVin'
+
+
+def _synthesized_identity(vehicle: JsonObject) -> JsonObject:
+    """The identity keys one vehicle record contributes to its readings.
+
+    Every key is synthesized ONLY when its source is present -- the
+    omit-absent-keys posture: a vehicle without ``externalIds`` (or
+    without a dotted key inside it) contributes readings without the
+    corresponding synthesized key, never a null.
+
+    Args:
+        vehicle: One vehicle record from the page's record list.
+
+    Returns:
+        The synthesized identity keys, wire values verbatim.
+
+    Raises:
+        ProviderResponseError: ``externalIds`` is present but not a JSON
+            object -- silently dropping serial/vin there would hide the
+            malformation.
+    """
+    identity: JsonObject = {}
+    if _VEHICLE_ID_SOURCE_KEY in vehicle:
+        identity[_VEHICLE_ID_KEY] = vehicle[_VEHICLE_ID_SOURCE_KEY]
+    if _VEHICLE_NAME_SOURCE_KEY in vehicle:
+        identity[_VEHICLE_NAME_KEY] = vehicle[_VEHICLE_NAME_SOURCE_KEY]
+    if _EXTERNAL_IDS_KEY not in vehicle:
+        return identity
+    external_ids = vehicle[_EXTERNAL_IDS_KEY]
+    if not isinstance(external_ids, dict):
+        raise ProviderResponseError(
+            detail=f'vehicle {_EXTERNAL_IDS_KEY!r} is not a JSON object'
+        )
+    if _SERIAL_SOURCE_KEY in external_ids:
+        identity[_VEHICLE_SERIAL_KEY] = external_ids[_SERIAL_SOURCE_KEY]
+    if _VIN_SOURCE_KEY in external_ids:
+        identity[_VEHICLE_VIN_KEY] = external_ids[_VIN_SOURCE_KEY]
+    return identity
+
+
+@dataclass(frozen=True, slots=True)
+class SamsaraVehicleSeriesPageDecoder:
+    """Decode vehicle-stats pages into flat per-reading records.
+
+    The series-unnesting composition over ``SamsaraCursorPageDecoder``
+    for ``GET /fleet/vehicles/stats/history`` (probe-settled
+    2026-07-20): the cursor walks the VEHICLE axis within the fixed
+    window (three consecutive live pages showed zero vehicle-id
+    overlap), and each vehicle record nests one reading series under
+    the requested stat type's key. Composition is by DELEGATION: an
+    inner cursor decoder handles ``first_request`` and the whole
+    pagination verdict verbatim -- this class only unnests the inner
+    page's vehicle records.
+
+    The unnesting contract: for each vehicle record, for each element
+    of ``vehicle[series_key]``, emit one flat record carrying the
+    reading's keys verbatim plus the SYNTHESIZED identity keys
+    ``vehicleId``/``vehicleName``/``vehicleSerial``/``vehicleVin``
+    (sourced from ``id``/``name`` and the ``externalIds`` object's
+    literal dotted ``samsara.serial``/``samsara.vin`` keys). Identity
+    keys are synthesized only when their source is present; reading
+    keys win any collision -- impossible by census, since the
+    synthesized names were chosen collision-free against every observed
+    series key. A vehicle whose series array is missing or empty
+    contributes zero records.
+
+    This decoder is Samsara-stats-specific by evidence, not a generic
+    flattener: the identity-key sourcing, the dotted ``externalIds``
+    keys, and the one-series-per-record shape are this surface's
+    captured facts, and generalizing beyond them would encode structure
+    no probe has shown.
+
+    Attributes:
+        records_key: The top-level key holding the vehicle-record list
+            (forwarded to the inner cursor decoder).
+        results_limit: The per-page vehicle count requested via
+            ``limit`` (forwarded to the inner cursor decoder).
+        series_key: The per-vehicle key holding this endpoint's reading
+            series -- the requested stat type's wire name.
+    """
+
+    records_key: str
+    results_limit: int
+    series_key: str
+
+    def _cursor_decoder(self) -> SamsaraCursorPageDecoder:
+        """The inner cursor decoder pagination delegates to."""
+        return SamsaraCursorPageDecoder(
+            records_key=self.records_key, results_limit=self.results_limit
+        )
+
+    def first_request(self, spec: RequestSpec) -> RequestSpec:
+        """Delegate page one verbatim to the inner cursor decoder."""
+        return self._cursor_decoder().first_request(spec)
+
+    def decode_page(self, sent: RequestSpec, envelope: JsonValue) -> DecodedPage:
+        """Unnest the inner page's vehicles into flat reading records.
+
+        Args:
+            sent: The spec that produced this page.
+            envelope: The parsed response body.
+
+        Returns:
+            One record per reading (the unnesting contract, class
+            docstring); the pagination advance passes through the inner
+            decoder untouched.
+
+        Raises:
+            ProviderResponseError: When the inner decode raises (the
+                cursor contract's guards, including continuation
+                promised without a cursor), or when a present series
+                value or element is structurally violating.
+        """
+        inner_page = self._cursor_decoder().decode_page(sent, envelope)
+        readings = [
+            reading
+            for vehicle in inner_page.records
+            for reading in self._unnest_vehicle(vehicle)
+        ]
+        return DecodedPage(records=readings, advance=inner_page.advance)
+
+    def _unnest_vehicle(self, vehicle: JsonObject) -> list[JsonObject]:
+        """One vehicle record's flat reading records (possibly none).
+
+        Args:
+            vehicle: One vehicle record from the inner page.
+
+        Returns:
+            One flat record per series element; empty when the series
+            is missing or empty (only carriers are returned per
+            requested type in capture, but absence stays a zero-record
+            vehicle, never an error).
+
+        Raises:
+            ProviderResponseError: A present series value is not a
+                list, or a series element is not a JSON object.
+        """
+        if self.series_key not in vehicle:
+            return []
+        series = vehicle[self.series_key]
+        if not isinstance(series, list):
+            raise ProviderResponseError(
+                detail=f'vehicle series {self.series_key!r} is not a list'
+            )
+        identity = _synthesized_identity(vehicle)
+        readings: list[JsonObject] = []
+        for element in series:
+            if not isinstance(element, dict):
+                raise ProviderResponseError(
+                    detail=(
+                        f'vehicle series {self.series_key!r} element is not a '
+                        'JSON object'
+                    )
+                )
+            # Reading keys win the merge (collision-free by census; the
+            # class docstring records the naming choice).
+            readings.append({**identity, **element})
+        return readings

fleetpull/network/decoders/samsara_reports.py

@@ -0,0 +1,119 @@
+# src/fleetpull/network/decoders/samsara_reports.py
+"""The Samsara window-report decoder family: the fuel-energy report surfaces.
+
+``SamsaraWindowReportPageDecoder`` decodes the fuel-energy report surfaces
+(``/fleet/reports/{vehicles,drivers}/fuel-energy``; probe-settled 2026-07-21,
+DESIGN section 8), whose record list nests one level deeper (``data`` is an
+OBJECT holding the list under ``vehicleReports``/``driverReports``) and whose
+rows carry NO event-time key of any kind -- each row is the provider's rollup
+over exactly the requested window, so the decoder stamps every report with the
+window the SENT spec asked for. Pagination and the first-page shape are the
+sibling cursor module's (``samsara.py``: ``cursor_page_advance`` /
+``first_page_spec``); the window stamp is the shared provider-uniform
+vocabulary (``_window_stamp.py``).
+"""
+
+from dataclasses import dataclass
+from typing import Final
+
+from fleetpull.network.contract import (
+    DecodedPage,
+    RequestSpec,
+    require_child_object,
+    require_record_list,
+)
+from fleetpull.network.decoders._window_stamp import window_stamp_from_sent_spec
+from fleetpull.network.decoders.samsara import cursor_page_advance, first_page_spec
+from fleetpull.vocabulary import JsonValue
+
+__all__: list[str] = ['SamsaraWindowReportPageDecoder']
+
+# The fuel-energy report surfaces' window wire params (2026-07-21
+# capture): these surfaces take startDate/endDate NAMES -- unlike every
+# other probed Samsara vertical's startTime/endTime -- while accepting
+# full RFC3339 datetimes despite the names. The shared window-stamp
+# helper (`_window_stamp.py`) reads them back off the SENT spec to stamp
+# each report row with the provider-uniform synthesized keys.
+_WINDOW_START_PARAM: Final[str] = 'startDate'
+_WINDOW_END_PARAM: Final[str] = 'endDate'
+
+
+@dataclass(frozen=True, slots=True)
+class SamsaraWindowReportPageDecoder:
+    """Decode fuel-energy report pages into window-stamped records.
+
+    The decoder for ``GET /fleet/reports/{vehicles,drivers}/fuel-energy``
+    (probe-settled 2026-07-21, DESIGN section 8), whose envelope differs
+    from the flat cursor surfaces twice over:
+
+    - **The record list is NESTED.** ``data`` is an OBJECT whose only
+      key is the per-surface report key (``vehicleReports`` /
+      ``driverReports``), each a list of report objects -- extracted
+      with the same structural-violation loudness ``require_record_list``
+      gives flat lists.
+    - **The rollup grain is the request window.** Report rows carry NO
+      event-time key of any kind; each row is the provider's aggregate
+      over exactly the requested window (widening the window GREW
+      per-entity metrics, and day rollups are NOT additive into wider
+      windows -- 89/267 mismatched). So the decoder stamps every report
+      with the synthesized keys ``windowStartDate``/``windowEndDate``,
+      copied verbatim from the SENT spec's own ``startDate``/``endDate``
+      params -- the stats triple's synthesized-identity-keys precedent,
+      sourced from the sent spec rather than the record. The stamp wins
+      any (census-impossible) key collision: it is the row's REQUIRED
+      time identity, and a colliding future wire key must never silently
+      supplant what was actually asked of the provider -- the inverse of
+      the series decoder's reading-keys-win order, where the synthesized
+      keys are auxiliary attribution.
+
+    Pagination is the standard cursor contract, shared via the sibling
+    module's ``cursor_page_advance`` (real at scale: a 2-day
+    vehicle window walked 3 pages/267 reports); ``first_request``
+    injects ``limit`` exactly as the cursor decoder does.
+
+    Attributes:
+        records_key: The top-level key holding the report container
+            object (``'data'``).
+        report_key: The container key holding this surface's report
+            list (``'vehicleReports'`` / ``'driverReports'``).
+        results_limit: The per-page record count requested via the
+            ``limit`` query parameter (pagination parameters are the
+            decoder's, per the ``StaticGetSpecBuilder`` seam).
+    """
+
+    records_key: str
+    report_key: str
+    results_limit: int
+
+    def first_request(self, spec: RequestSpec) -> RequestSpec:
+        """Send page one via the shared first-page shape (``first_page_spec``)."""
+        return first_page_spec(spec, self.results_limit)
+
+    def decode_page(self, sent: RequestSpec, envelope: JsonValue) -> DecodedPage:
+        """Extract the nested reports, stamp each with the sent window.
+
+        Args:
+            sent: The spec that produced this page.
+            envelope: The parsed response body.
+
+        Returns:
+            One record per report, each carrying the synthesized
+            ``windowStartDate``/``windowEndDate`` keys (class
+            docstring); the pagination verdict is the shared cursor
+            contract's.
+
+        Raises:
+            ProviderResponseError: The sent spec lacks a window param
+                (a wiring bug -- never silently unstamped rows), the
+                nested record-bearing shape is structurally violating,
+                or the cursor block is (including continuation promised
+                without a cursor).
+        """
+        window_stamp = window_stamp_from_sent_spec(
+            sent, start_param=_WINDOW_START_PARAM, end_param=_WINDOW_END_PARAM
+        )
+        reports = require_record_list(
+            require_child_object(envelope, self.records_key), self.report_key
+        )
+        stamped = [{**report, **window_stamp} for report in reports]
+        return DecodedPage(records=stamped, advance=cursor_page_advance(sent, envelope))

fleetpull/network/decoders/single_page.py

@@ -0,0 +1,55 @@
+# src/fleetpull/network/decoders/single_page.py
+"""Single-page decoder: top-level-list records, no pagination.
+
+For unpaginated endpoints -- replaces any is-paginated flag. The first
+request is the base spec unchanged and every page is terminal. Decoder
+logic deliberately resembles its siblings without sharing code.
+"""
+
+from dataclasses import dataclass
+
+from fleetpull.network.contract import (
+    DecodedPage,
+    PageAdvance,
+    RequestSpec,
+    require_record_list,
+)
+from fleetpull.vocabulary import JsonValue
+
+__all__: list[str] = ['SinglePageDecoder']
+
+
+@dataclass(frozen=True, slots=True)
+class SinglePageDecoder:
+    """Decode a single unpaginated page of top-level-list records.
+
+    Attributes:
+        records_key: The top-level key holding the record list.
+    """
+
+    records_key: str
+
+    def first_request(self, spec: RequestSpec) -> RequestSpec:
+        """Return the base spec unchanged."""
+        return spec
+
+    def decode_page(self, sent: RequestSpec, envelope: JsonValue) -> DecodedPage:
+        """Extract the records; the page is always terminal.
+
+        Args:
+            sent: The spec that produced this page (unused; there is no
+                continuation).
+            envelope: The parsed response body.
+
+        Returns:
+            The records and a terminal verdict.
+
+        Raises:
+            ProviderResponseError: When the record-bearing shape is
+                structurally violating.
+        """
+        records = require_record_list(envelope, self.records_key)
+        return DecodedPage(
+            records=records,
+            advance=PageAdvance(next_spec=None, durable_progress=None),
+        )

fleetpull/network/limits/__init__.py

@@ -0,0 +1,13 @@
+"""Rate limiting: token-bucket limiter and registry, one per quota scope."""
+
+from fleetpull.network.limits.limiter import QuotaScopeLimiter
+from fleetpull.network.limits.registry import (
+    RateLimiterRegistry,
+    rate_limits_from_configs,
+)
+
+__all__: list[str] = [
+    'QuotaScopeLimiter',
+    'RateLimiterRegistry',
+    'rate_limits_from_configs',
+]

fleetpull/network/limits/bucket_math.py

@@ -0,0 +1,58 @@
+# src/fleetpull/network/limits/bucket_math.py
+"""Pure token-bucket arithmetic.
+
+Stateless functions with no clock, no threading, and no state — just math.
+They exist so the bucket arithmetic is exhaustively testable single-threaded
+with plain assertions, leaving ``limiter.py`` to hold only state and thread
+choreography.
+"""
+
+__all__: list[str] = ['refill_tokens', 'seconds_until_available']
+
+
+def refill_tokens(
+    current_tokens: float,
+    elapsed_seconds: float,
+    refill_rate_per_second: float,
+    capacity: float,
+) -> float:
+    """Compute the token count after lazily refilling for elapsed time.
+
+    Args:
+        current_tokens: Tokens in the bucket before the refill.
+        elapsed_seconds: Seconds since the last refill (must be >= 0).
+        refill_rate_per_second: Tokens added per second.
+        capacity: Maximum tokens the bucket holds.
+
+    Returns:
+        ``min(capacity, current_tokens + elapsed_seconds * refill_rate_per_second)``.
+
+    Raises:
+        ValueError: If ``elapsed_seconds`` is negative. A monotonic clock can
+            never produce one; if it appears, something upstream is broken
+            and must fail loudly.
+    """
+    if elapsed_seconds < 0:
+        raise ValueError(f'elapsed_seconds must be non-negative, got {elapsed_seconds}')
+    return min(capacity, current_tokens + elapsed_seconds * refill_rate_per_second)
+
+
+def seconds_until_available(
+    current_tokens: float,
+    refill_rate_per_second: float,
+    tokens_needed: float = 1.0,
+) -> float:
+    """Compute the exact wait until the bucket holds ``tokens_needed`` tokens.
+
+    Args:
+        current_tokens: Tokens currently in the bucket.
+        refill_rate_per_second: Tokens added per second.
+        tokens_needed: Tokens required before proceeding.
+
+    Returns:
+        0.0 if ``current_tokens >= tokens_needed``; otherwise the seconds
+        needed for the deficit to refill at ``refill_rate_per_second``.
+    """
+    if current_tokens >= tokens_needed:
+        return 0.0
+    return (tokens_needed - current_tokens) / refill_rate_per_second