fleetpull 0.1.0__py3-none-any.whl

fleetpull/models/samsara/vehicle_fuel_energy_report.py

@@ -0,0 +1,191 @@
+# src/fleetpull/models/samsara/vehicle_fuel_energy_report.py
+"""Samsara VehicleFuelEnergyReport response model
+(``GET /fleet/reports/vehicles/fuel-energy``, post-decoder
+window-stamped grain).
+
+Written from captured live responses (2026-07-20/21 probe session: a
+71/71 total census on the 1-day walk, structurally identical on the
+2-day 267-report walk), never from docs. The model mirrors the record
+``SamsaraWindowReportPageDecoder`` emits, and its two field families
+have different provenance:
+
+- ``window_start`` / ``window_end`` are DECODER-SYNTHESIZED
+  (``windowStartDate``/``windowEndDate``): report rows carry NO
+  event-time key of any kind, so the decoder stamps each row with the
+  window the SENT spec asked for, copied verbatim from its
+  ``startDate``/``endDate`` params. Contrast the stats triple's
+  synthesized identity keys, which are lifted from the RECORD's own
+  nested vehicle block -- these come from the request, because the
+  request window IS the row's time identity.
+- Everything else is WIRE-VERBATIM: the metric core, the cost block,
+  and the ``vehicle`` ref, camelCase keys mirrored via aliases.
+
+**NON-ADDITIVITY -- the rollup grain is the request window, proven
+twice (2026-07-21).** 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).
+Each row is the provider's answer for exactly its window, nothing else:
+day rows MUST NOT be summed to reproduce a wider window's rollup. This
+is why the binding declares ``fixed_unit_days=1`` -- the unit width is
+part of the row's meaning and never floats with configuration.
+
+Requiredness posture: the window stamps, the ``vehicle`` ref, and its
+``id`` are required STRUCTURALLY -- a rollup row without its window or
+its entity is meaningless, so a future record omitting them must fail
+loudly, never land an all-null row. The metric core (all eight metrics
+plus ``estFuelEnergyCost``) is required on the WHOLE-WALK posture: the
+census was total on every walked report (71/71 and, structurally, all
+267 of the 2-day walk), and a rollup surface that computes its metrics
+per window has no absence mechanism to be conservative about -- a
+missing metric would be a contract change worth a loud failure. The
+ref's ``name``/``energyType``/``externalIds`` stay optional per the
+conservative posture (one fleet's walk is not a whole-population oath).
+
+``efficiencyMpge``, ``estCarbonEmissionsKg``, and the cost ``amount``
+are MIXED int|float on the wire -- modeled ``float``, lax coercion
+lifting the int shape. ``energyType`` (observed only ``'fuel'``) and
+``currencyCode`` (observed only ``'USD'``, 100-report samples) are
+census-open plain ``str``\\s, never enums. ``vehicle.externalIds``
+carries the LITERAL DOTTED wire keys ``samsara.serial``/``samsara.vin``
+(both str, 71/71) on the NESTED ref, mirrored via explicit aliases with
+single-key independence -- the assignments precedent.
+
+Wire keys are camelCase; fields are snake_case via the ``to_camel``
+alias generator, except the decoder-synthesized window stamps and the
+dotted external-id keys, which take explicit aliases.
+"""
+
+from datetime import datetime
+
+from pydantic import ConfigDict, Field
+from pydantic.alias_generators import to_camel
+
+from fleetpull.model_contract import ResponseModel
+
+__all__: list[str] = [
+    'VehicleFuelEnergyCost',
+    'VehicleFuelEnergyExternalIds',
+    'VehicleFuelEnergyReport',
+    'VehicleFuelEnergyVehicleRef',
+]
+
+
+class VehicleFuelEnergyCost(ResponseModel):
+    """The ``estFuelEnergyCost`` block: the window's estimated cost.
+
+    Both keys were 71/71 in census and required per the whole-walk
+    posture (module docstring).
+
+    Attributes:
+        amount: The monetary amount -- MIXED int|float on the wire,
+            modeled float.
+        currency_code: The currency code -- observed only ``'USD'`` on
+            a 100-report sample, census-open, so a plain ``str``.
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    amount: float
+    currency_code: str
+
+
+class VehicleFuelEnergyExternalIds(ResponseModel):
+    """The vehicle ref's ``externalIds`` block: namespaced external ids.
+
+    The wire keys are the LITERAL DOTTED ``samsara.serial`` and
+    ``samsara.vin`` (both str, 71/71 in census), mirrored via explicit
+    aliases on this NESTED object -- the assignments precedent. Each key
+    is independently optional (the conservative posture; the vehicles
+    surface proves ``externalIds`` variance exists in this fleet).
+
+    Attributes:
+        samsara_serial: The gateway serial (wire key ``samsara.serial``).
+        samsara_vin: The VIN (wire key ``samsara.vin``).
+    """
+
+    samsara_serial: str | None = Field(default=None, alias='samsara.serial')
+    samsara_vin: str | None = Field(default=None, alias='samsara.vin')
+
+
+class VehicleFuelEnergyVehicleRef(ResponseModel):
+    """The ``vehicle`` block: the rollup's vehicle entity.
+
+    All four keys were 71/71 in census; only ``id`` is required by
+    structural judgment (a ref without an id references nothing), while
+    the rest stays optional per the conservative posture.
+
+    Attributes:
+        id: Samsara's vehicle id -- a string, mirrored as string.
+        name: The vehicle's display name.
+        energy_type: The vehicle's energy type -- observed only
+            ``'fuel'`` on a 100-report sample, census-open, so a plain
+            ``str``, never an enum.
+        external_ids: The dotted-key external-id block (wire key
+            ``externalIds``).
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    id: str
+    name: str | None = None
+    energy_type: str | None = None
+    external_ids: VehicleFuelEnergyExternalIds | None = None
+
+
+class VehicleFuelEnergyReport(ResponseModel):
+    """One vehicle's fuel-energy rollup over exactly one request window.
+
+    A pure mirror of the window-stamped post-decoder record (module
+    docstring: the window stamps are decoder-synthesized from the sent
+    spec; everything else is wire-verbatim). Field semantics and units
+    are Samsara's; no value is derived or interpreted here. Day rows
+    MUST NOT be summed to reproduce a wider window's rollup (89/267
+    mismatched -- module docstring).
+
+    Attributes:
+        window_start: The request window's start (decoder-synthesized
+            ``windowStartDate``, verbatim from the sent ``startDate``)
+            -- the event-time column: the row's time identity is the
+            window that produced it.
+        window_end: The request window's end (decoder-synthesized
+            ``windowEndDate``, verbatim from the sent ``endDate``).
+        vehicle: The rollup's vehicle entity.
+        distance_traveled_meters: Distance traveled in the window, in
+            meters, a bare int.
+        efficiency_mpge: Efficiency in MPGe -- MIXED int|float on the
+            wire, modeled float.
+        energy_used_kwh: Energy used in the window, in kWh, a bare int.
+        engine_idle_time_duration_ms: Engine idle time in the window,
+            in milliseconds, a bare int.
+        engine_run_time_duration_ms: Engine run time in the window, in
+            milliseconds, a bare int.
+        est_carbon_emissions_kg: Estimated carbon emissions in the
+            window, in kilograms -- MIXED int|float on the wire,
+            modeled float.
+        fuel_consumed_ml: Fuel consumed in the window, in milliliters,
+            a bare int.
+        est_fuel_energy_cost: The window's estimated fuel/energy cost
+            block.
+    """
+
+    model_config = ConfigDict(alias_generator=to_camel)
+
+    # Decoder-synthesized window identity (the sent spec's own window).
+    window_start: datetime = Field(alias='windowStartDate')
+    window_end: datetime = Field(alias='windowEndDate')
+
+    # The rollup's entity.
+    vehicle: VehicleFuelEnergyVehicleRef
+
+    # The wire-verbatim metric core (whole-walk required; provider
+    # units mirrored verbatim).
+    distance_traveled_meters: int
+    efficiency_mpge: float
+    energy_used_kwh: int
+    engine_idle_time_duration_ms: int
+    engine_run_time_duration_ms: int
+    est_carbon_emissions_kg: float
+    fuel_consumed_ml: int
+    est_fuel_energy_cost: VehicleFuelEnergyCost

fleetpull/network/__init__.py

@@ -0,0 +1,9 @@
+"""Transport layer: an organizational namespace.
+
+Carries no aggregated surface of its own — the transport machinery lives
+in its subpackages (``auth/``, ``contract/``, ``limits/``, ``retry/``,
+``tls/``), each with its own face. Callers import from those subpackages
+directly.
+"""
+
+__all__: list[str] = []

fleetpull/network/auth/__init__.py

@@ -0,0 +1,15 @@
+"""GeoTab session lifecycle: single-flight authentication state."""
+
+from fleetpull.network.auth.authenticate import build_geotab_authenticator
+from fleetpull.network.auth.manager import GeotabSessionManager
+from fleetpull.network.auth.models import AuthenticationResult, GeotabSession
+from fleetpull.network.auth.strategies import GeotabSessionAuth, StaticHeaderAuth
+
+__all__: list[str] = [
+    'AuthenticationResult',
+    'GeotabSession',
+    'GeotabSessionAuth',
+    'GeotabSessionManager',
+    'StaticHeaderAuth',
+    'build_geotab_authenticator',
+]

fleetpull/network/auth/authenticate.py

@@ -0,0 +1,271 @@
+# src/fleetpull/network/auth/authenticate.py
+"""The real GeoTab ``Authenticate`` call: the manager's injectable.
+
+A single-concern, single-shot, loop-free function behind a factory. The
+session manager's injectable type is single-arg
+(``Callable[[GeotabAuthConfig], AuthenticationResult]``), so the
+transport dependencies — HTTP config, the limiter registry, the quota
+scope — close over via a factory returning a named inner function.
+
+This is the one module in ``network/auth/`` that imports httpx: it IS
+the HTTP attempt the manager keeps at arm's length so the manager
+itself stays pure state and choreography. Two actions only — fix
+credentials (``AuthenticationError``) or fail loud
+(``ProviderResponseError``); the classifier's vocabulary encodes the
+CLIENT's dispatch and is deliberately not reused here. Every inbound
+read flows through a private slice model; transport exceptions
+propagate raw and untyped, because retry semantics for prepare-time
+transport failures are the client's design question, not this
+function's.
+"""
+
+import json
+import logging
+from collections.abc import Callable
+from http import HTTPStatus
+from typing import Final, NoReturn
+
+import httpx
+from pydantic import Field
+
+from fleetpull.config import GeotabAuthConfig, HttpConfig
+from fleetpull.exceptions import AuthenticationError, ProviderResponseError
+from fleetpull.network.auth.models import AuthenticationResult
+from fleetpull.network.contract import (
+    StrictEnvelopeSlice,
+    body_snippet,
+    validated_envelope_slice,
+)
+from fleetpull.network.limits import RateLimiterRegistry
+from fleetpull.network.posture import new_http_client
+from fleetpull.vocabulary import JsonValue
+
+__all__: list[str] = ['build_geotab_authenticator']
+
+logger = logging.getLogger(__name__)
+
+# Wire-protocol tokens: Final constants, not an enum — nothing
+# dispatches over these. Outbound body keys used in logic and the two
+# inbound values we compare against; inbound envelope keys are consumed
+# via the slice models' fields/aliases, never walked.
+_APIV1_PATH: Final[str] = '/apiv1'
+_METHOD_KEY: Final[str] = 'method'
+_PARAMS_KEY: Final[str] = 'params'
+_DATABASE_KEY: Final[str] = 'database'
+_USER_NAME_KEY: Final[str] = 'userName'
+_PASSWORD_KEY: Final[str] = 'password'  # the JSON-RPC field name, not a secret
+_AUTHENTICATE_METHOD: Final[str] = 'Authenticate'
+_THIS_SERVER_PATH: Final[str] = 'ThisServer'
+_INVALID_USER_TYPE: Final[str] = 'InvalidUserException'
+
+
+class _AuthenticateCredentials(StrictEnvelopeSlice):
+    """The credentials block of a successful Authenticate result.
+
+    Only ``sessionId`` is consumed — ``database`` and ``userName`` are
+    carried from config by the manager, so they are deliberately ignored
+    here.
+    """
+
+    session_id: str = Field(alias='sessionId')
+
+
+class _AuthenticateResult(StrictEnvelopeSlice):
+    """A successful Authenticate ``result``: credentials and the host path."""
+
+    credentials: _AuthenticateCredentials
+    path: str
+
+
+class _AuthenticateErrorData(StrictEnvelopeSlice):
+    """The ``error.data`` block; ``type`` is the authoritative discriminator."""
+
+    type: str
+
+
+class _AuthenticateError(StrictEnvelopeSlice):
+    """A failing Authenticate ``error`` envelope (inside HTTP 200)."""
+
+    message: str | None = None
+    data: _AuthenticateErrorData
+
+
+class _AuthenticateEnvelope(StrictEnvelopeSlice):
+    """The JSON-RPC envelope slice: exactly one of error or result is meaningful."""
+
+    error: _AuthenticateError | None = None
+    result: _AuthenticateResult | None = None
+
+
+def _build_authenticate_body(config: GeotabAuthConfig) -> dict[str, JsonValue]:
+    """
+    Build the JSON-RPC ``Authenticate`` body.
+
+    The ``SecretStr`` is extracted HERE and only here (the manager never
+    reads it), placed in the request body, and never logged.
+
+    Args:
+        config: Validated GeoTab authentication configuration.
+
+    Returns:
+        The JSON-RPC request body.
+    """
+    return {
+        _METHOD_KEY: _AUTHENTICATE_METHOD,
+        _PARAMS_KEY: {
+            _DATABASE_KEY: config.database,
+            _USER_NAME_KEY: config.username,
+            _PASSWORD_KEY: config.password.get_secret_value(),
+        },
+    }
+
+
+def _raise_for_authenticate_error(error: _AuthenticateError) -> NoReturn:
+    """
+    Translate a GeoTab Authenticate error envelope into the right raise.
+
+    Args:
+        error: The validated error slice.
+
+    Raises:
+        AuthenticationError: For ``InvalidUserException`` — bad
+            credentials, the context-disambiguation principle (the same
+            type on a data call is a dead session, handled by the auth
+            strategy, not here).
+        ProviderResponseError: For any other error type — fail loud on
+            behavior never met on Authenticate. Trigger:
+            ``OverLimitException`` observed here despite the local
+            limiter would mean revisit.
+    """
+    if error.data.type == _INVALID_USER_TYPE:
+        raise AuthenticationError(detail=error.message)
+    detail: str = f'unexpected Authenticate error type: {error.data.type!r}'
+    if error.message is not None:
+        detail = f'{detail} ({error.message})'
+    raise ProviderResponseError(detail=detail)
+
+
+def _resolve_server(result_path: str, config: GeotabAuthConfig) -> str:
+    """
+    Resolve the session's server from the Authenticate result path.
+
+    Args:
+        result_path: The ``result.path`` value from the envelope.
+        config: The configuration whose ``server`` was actually called.
+
+    Returns:
+        ``config.server`` when ``path`` is the ``ThisServer`` sentinel;
+        otherwise the returned host.
+    """
+    if result_path == _THIS_SERVER_PATH:
+        return config.server
+    # Redirects are handled-not-assumed: no capture shows one, but the
+    # protocol documents path as a possible alternate host.
+    logger.info('GeoTab Authenticate redirected to host %s', result_path)
+    return result_path
+
+
+def _resolve_authenticate_outcome(
+    response: httpx.Response, config: GeotabAuthConfig
+) -> AuthenticationResult:
+    """
+    Turn one Authenticate HTTP response into a result or the right raise.
+
+    Args:
+        response: The completed Authenticate response.
+        config: The configuration that produced the request.
+
+    Returns:
+        The authentication result on success.
+
+    Raises:
+        AuthenticationError: On ``InvalidUserException`` (bad credentials).
+        ProviderResponseError: On a non-200 status, a non-JSON body, a
+            malformed envelope, or any unexpected error type.
+    """
+    if response.status_code != HTTPStatus.OK:
+        # v1 posture: Authenticate outcomes arrive in HTTP 200 per
+        # verification; anything else is the API not speaking its
+        # protocol. Loud-and-typed beats a retry loop against a 10/min
+        # auth quota. Re-litigate on the first observed Authenticate 5xx.
+        raise ProviderResponseError(
+            status_code=response.status_code, detail=body_snippet(response.text)
+        )
+    try:
+        parsed_body: JsonValue = json.loads(response.text)
+    except json.JSONDecodeError as error:
+        raise ProviderResponseError(
+            detail=f'unparseable (non-JSON) Authenticate body: '
+            f'{body_snippet(response.text)}'
+        ) from error
+
+    envelope = validated_envelope_slice(_AuthenticateEnvelope, parsed_body)
+    if envelope.error is not None:
+        _raise_for_authenticate_error(envelope.error)
+    if envelope.result is not None:
+        return AuthenticationResult(
+            session_id=envelope.result.credentials.session_id,
+            resolved_host=_resolve_server(envelope.result.path, config),
+        )
+    raise ProviderResponseError(
+        detail='malformed Authenticate envelope: neither result nor error present'
+    )
+
+
+def build_geotab_authenticator(
+    http_config: HttpConfig,
+    limiter_registry: RateLimiterRegistry,
+    quota_scope: str,
+) -> Callable[[GeotabAuthConfig], AuthenticationResult]:
+    """
+    Build the real ``authenticate_fn`` the session manager consumes.
+
+    The quota scope arrives as a parameter — the composition root names
+    it — preserving the names-at-composition-root rule even inside
+    GeoTab-specific machinery. Authenticate is rate-limited at a fixed
+    10/min outside tiering; the composition root configures a dedicated
+    scope in the registry, and an unconfigured scope propagates the
+    registry's ``UnknownQuotaScopeError`` naturally.
+
+    Args:
+        http_config: Timeouts and TLS posture for the call.
+        limiter_registry: The shared registry; the call takes a slot
+            under ``quota_scope``.
+        quota_scope: The dedicated Authenticate quota scope.
+
+    Returns:
+        A single-arg callable matching the manager's injectable type.
+    """
+
+    def authenticate(config: GeotabAuthConfig) -> AuthenticationResult:
+        """
+        Perform one ``Authenticate`` call and resolve its outcome.
+
+        Args:
+            config: Validated GeoTab authentication configuration.
+
+        Returns:
+            The authentication result on success.
+
+        Raises:
+            AuthenticationError: On bad credentials.
+            ProviderResponseError: On a non-200 status, a non-JSON body,
+                or a malformed/unexpected envelope.
+            UnknownQuotaScopeError: When ``quota_scope`` is unconfigured.
+            httpx.TransportError: On a transport failure — propagated raw
+                and loop-free; retry is the client's design question.
+        """
+        limiter = limiter_registry.get(quota_scope)
+        url: str = f'https://{config.server}{_APIV1_PATH}'
+        request_body: dict[str, JsonValue] = _build_authenticate_body(config)
+        # A fresh, context-managed client per call: Authenticate fires
+        # rarely behind the manager's single-flight, so connection reuse
+        # buys nothing worth a held resource.
+        with (
+            limiter.request_slot(),
+            new_http_client(http_config) as client,
+        ):
+            response = client.post(url, json=request_body)
+        return _resolve_authenticate_outcome(response, config)
+
+    return authenticate