fleetpull 0.1.0__py3-none-any.whl

fleetpull/endpoints/motive/vehicle_utilizations.py

@@ -0,0 +1,122 @@
+# src/fleetpull/endpoints/motive/vehicle_utilizations.py
+"""The Motive vehicle_utilizations binding: the window-grain rollup
+surface -- Motive's arm of the fixed-unit-width watermark family
+(probe-settled 2026-07-21, DESIGN section 8). The legacy hub's
+``vehicle_utilization``, shipped under the wire's own plural envelope
+vocabulary (model ``VehicleUtilization``).
+
+``GET /v2/vehicle_utilization`` carries the standard Motive
+wrapped-list envelope (wrapper ``vehicle_utilizations`` /
+``vehicle_utilization``) and offset pagination at the configured page
+size (``per_page`` 50 and 100 both honored live). The population is the
+WHOLE vehicle fleet regardless of window (1,466 on the 1-day and the
+6-day probe alike -- inactive vehicles ride with zeroed metrics and a
+``message`` status string), fleet-wide with per-record vehicle
+attribution, so there is NO fan-out -- the default ``SingleFetch``
+shape, declared by declaring nothing, and no roster is sourced or
+consumed.
+
+**THE ROLLUP GRAIN IS THE REQUEST WINDOW** (a 1-day and a 6-day request
+each returned one rollup row per vehicle), so the binding declares
+``fixed_unit_days=1`` on its ``WatermarkMode`` -- the unit width is
+part of the ROW'S MEANING and never floats with
+``sync.backfill_chunk_days`` (the Samsara fuel-energy machinery, its
+second consumer; additivity was not probed here, and the family
+precedent's do-not-sum posture rides the model docstring). Rows carry
+NO date or time identity; the ``MotiveWindowReportPageDecoder`` stamps
+each with the sent window and ``event_time_column='window_start'``
+routes each day's rollup to its own partition.
+
+**The window mapping and the company-local caveat.** The shared
+``MotiveFleetDateRangeSpecBuilder`` maps the half-open unit
+``DateWindow`` ``[start, end)`` to the INCLUSIVE date-label pair the
+wire takes -- ``start_date`` is ``start``'s date and ``end_date`` the
+last covered date (``end`` minus a day) -- proven inclusive on both
+ends live (``start_date=end_date`` returned exactly one day's rollup).
+With the fixed 1-day unit both labels are the unit's day. The labels
+are interpreted in COMPANY-LOCAL days (the account's ``/v1/companies``
+zone at a UTC-5 offset -- DESIGN section 8), so each unit's rows are
+the provider's company-local-day rollups, mirrored verbatim: no pad, no
+trim, the caveat documented on the model, never converted.
+"""
+
+from datetime import timedelta
+from typing import Final
+
+from fleetpull.config import MotiveConfig
+from fleetpull.endpoints.motive._spec_builders import MotiveFleetDateRangeSpecBuilder
+from fleetpull.endpoints.shared import (
+    EndpointDefinition,
+    StorageKind,
+    WatermarkMode,
+)
+from fleetpull.models.motive import VehicleUtilization
+from fleetpull.network.decoders import MotiveWindowReportPageDecoder
+from fleetpull.vocabulary import Provider, QuotaScope
+
+__all__: list[str] = ['build_endpoint']
+
+_VEHICLE_UTILIZATIONS_PATH: Final[str] = '/v2/vehicle_utilization'
+
+# The wire's own envelope vocabulary -- plural list key, singular item
+# key, exactly the sibling wrapped-list convention (captured 2026-07-21).
+_VEHICLE_UTILIZATIONS_LIST_KEY: Final[str] = 'vehicle_utilizations'
+_VEHICLE_UTILIZATIONS_ITEM_KEY: Final[str] = 'vehicle_utilization'
+
+# The fixed work-unit width, in whole days. The rollup grain is the
+# request window (a 1-day and a 6-day request each returned one rollup
+# row per vehicle, captured 2026-07-21), so the unit width is part of
+# the row's meaning and is pinned here rather than left to
+# sync.backfill_chunk_days (the fuel-energy machinery, DESIGN section 5).
+_FIXED_UNIT_DAYS: Final[int] = 1
+
+
+def build_endpoint(config: MotiveConfig) -> EndpointDefinition[VehicleUtilization]:
+    """Build the Motive vehicle_utilizations watermark binding.
+
+    Whole-fleet per-vehicle utilization 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 window-grain proof),
+    each unit's rows 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. Records arrive wrapped
+    (``{"vehicle_utilizations": [{"vehicle_utilization": {...}}]}``)
+    under page-numbered pagination at the page size the config requests,
+    the ``start_date``/``end_date`` labels persisting across the walk.
+
+    Args:
+        config: The validated Motive configuration; supplies the base
+            URL the spec-builder joins to the utilization path, the page
+            size the decoder requests, and the lookback and cutoff the
+            watermark mode carries.
+
+    Returns:
+        The frozen vehicle_utilizations ``EndpointDefinition``.
+        Construction validates the ``WatermarkMode`` /
+        ``DATE_PARTITIONED`` / ``event_time_column`` triple against the
+        response model.
+    """
+    return EndpointDefinition(
+        provider=Provider.MOTIVE,
+        name='vehicle_utilizations',
+        spec_builder=MotiveFleetDateRangeSpecBuilder(
+            base_url=config.base_url,
+            path=_VEHICLE_UTILIZATIONS_PATH,
+        ),
+        page_decoder=MotiveWindowReportPageDecoder(
+            list_key=_VEHICLE_UTILIZATIONS_LIST_KEY,
+            item_key=_VEHICLE_UTILIZATIONS_ITEM_KEY,
+            per_page=config.records_per_page,
+        ),
+        response_model=VehicleUtilization,
+        quota_scope=QuotaScope.MOTIVE,
+        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',
+    )

fleetpull/endpoints/motive/vehicles.py

@@ -0,0 +1,106 @@
+# src/fleetpull/endpoints/motive/vehicles.py
+"""The Motive vehicles binding: a factory composing the vehicles snapshot
+EndpointDefinition from resolved Motive configuration, plus the
+``vehicle_ids`` roster the listing feeds.
+
+A binding cannot be a module-level constant because its spec-builder
+needs the run's configured base URL and page size, known only after the
+YAML config loads; capturing config at import time would freeze a
+default, and module-level mutable state is forbidden. So the endpoint is
+a factory taking a validated ``MotiveConfig`` and returning the frozen
+``EndpointDefinition`` the composition root hands to the client.
+
+``VEHICLE_IDS_ROSTER`` is declared here, beside the feeder it describes:
+the roster names this module's endpoint and its frame column, which is
+provider-specific knowledge that belongs in the provider leaf. Unlike the
+endpoint factory it needs no config, so it is a frozen constant -- and a
+public one deliberately: ``build_roster_registry`` discovers public
+module-level ``RosterDefinition`` constants in the same walk that finds
+``build_endpoint``, so declaring the constant IS the registration
+(no hand-maintained list exists to drift).
+The include-inactive guarantee binds at the feeder population, not at
+eviction policy: ``/v1/vehicles`` lists inactive and retired vehicles, so
+a fan-out over this roster covers vehicles that were active during a
+historical window even if they are inactive today.
+"""
+
+from datetime import timedelta
+from typing import Final
+
+from fleetpull.config import MotiveConfig
+from fleetpull.endpoints.shared import (
+    EndpointDefinition,
+    SnapshotMode,
+    StaticGetSpecBuilder,
+    StorageKind,
+)
+from fleetpull.models.motive import Vehicle
+from fleetpull.network.decoders import MotiveWrappedListPageDecoder
+from fleetpull.roster import RosterDefinition, RosterKey
+from fleetpull.vocabulary import Provider, QuotaScope
+
+__all__: list[str] = ['VEHICLE_IDS_ROSTER', 'build_endpoint']
+
+_VEHICLES_PATH: Final[str] = '/v1/vehicles'
+_VEHICLES_LIST_KEY: Final[str] = 'vehicles'
+_VEHICLES_ITEM_KEY: Final[str] = 'vehicle'
+
+# The fleet's membership changes on the order of days, so a daily re-list
+# keeps the roster current without spending a full vehicles listing on
+# every sync.
+_VEHICLE_IDS_MAX_AGE: Final[timedelta] = timedelta(days=1)
+
+# Eviction hysteresis (DESIGN §3): vehicle ids are permanent, absent-means-
+# empty keys, so eviction is an efficiency lever (stop fanning over
+# long-retired vehicles), not a correctness one. Three consecutive absent
+# listings tolerate a transient provider omission before dropping a member.
+_VEHICLE_IDS_EVICTION_THRESHOLD: Final[int] = 3
+
+# The Motive vehicle_ids roster: fed by this module's vehicles listing, read
+# by the vehicle_locations fan-out (which carries only the RosterKey).
+VEHICLE_IDS_ROSTER: RosterDefinition = RosterDefinition(
+    key=RosterKey(Provider.MOTIVE, 'vehicle_ids'),
+    source_endpoint='vehicles',
+    source_column='vehicle_id',
+    max_age=_VEHICLE_IDS_MAX_AGE,
+    eviction_threshold=_VEHICLE_IDS_EVICTION_THRESHOLD,
+)
+
+
+def build_endpoint(config: MotiveConfig) -> EndpointDefinition[Vehicle]:
+    """Build the Motive vehicles snapshot binding.
+
+    A full-dataset snapshot of the fleet's vehicles: no resume, a single
+    parquet file, full replacement each run. Records arrive wrapped
+    (``{"vehicles": [{"vehicle": {...}}]}``) under page-numbered
+    pagination, at the page size the config requests.
+
+    Only the pagination parameters are sent. The endpoint's optional
+    filters -- ``driver_ids[]``, ``fuel_type``, ``updated_after``, and the
+    ``X-Time-Zone`` / ``X-Metric-Units`` / ``X-User-Id`` header params --
+    are deliberately not wired yet.
+
+    Args:
+        config: The validated Motive configuration; supplies the base URL
+            the spec-builder joins to the vehicles path and the page size
+            the decoder requests.
+
+    Returns:
+        The frozen vehicles ``EndpointDefinition``.
+    """
+    return EndpointDefinition(
+        provider=Provider.MOTIVE,
+        name='vehicles',
+        spec_builder=StaticGetSpecBuilder(
+            base_url=config.base_url, path=_VEHICLES_PATH
+        ),
+        page_decoder=MotiveWrappedListPageDecoder(
+            list_key=_VEHICLES_LIST_KEY,
+            item_key=_VEHICLES_ITEM_KEY,
+            per_page=config.records_per_page,
+        ),
+        response_model=Vehicle,
+        quota_scope=QuotaScope.MOTIVE,
+        storage_kind=StorageKind.SINGLE,
+        sync_mode=SnapshotMode(),
+    )

fleetpull/endpoints/registry.py

@@ -0,0 +1,280 @@
+# src/fleetpull/endpoints/registry.py
+"""The endpoint catalog: ``EndpointRegistry`` and the discovery walk.
+
+``EndpointRegistry`` is a dumb, immutable map from ``(provider, name)`` to the
+endpoint's ``EndpointDefinition``. It answers ``get(provider, name)``; a duplicate
+key at construction is a wiring bug and raises ``ConfigurationError``. It knows
+nothing about providers, discovery, or config -- it is handed a bag of definitions
+and indexes them.
+
+``build_endpoint_registry`` is the one place endpoints are enumerated. It discovers
+every endpoint leaf by walking the ``endpoints.<provider>`` packages (skipping
+``shared``) for modules exposing a ``build_endpoint`` factory, injects each factory's
+provider config by matching the factory's annotated config type against the supplied
+configs, calls it, and indexes the results. Adding an endpoint is adding one leaf
+module: no manifest, no registration, no provider list here.
+
+``build_roster_registry`` is its sibling over the same walk: rosters are declared
+as public module-level ``RosterDefinition`` constants beside their feeders, in
+exactly the leaf modules the endpoint walk visits, so they are discovered the
+same way -- no hand-maintained registration list, no per-provider export
+to drift. Adding a roster is declaring one constant in its feeder's
+module.
+
+Discovery reaches the leaf modules dynamically rather than through each provider
+package's face. That is a deliberate, named exception to the clause-3 face-routing
+rule the import-discipline test enforces: the walk depends only on the
+``build_endpoint`` contract, not on any specific module, so it is generic enumeration
+rather than static coupling. The replacement guardrail is the structural contract
+test (``tests/endpoints/test_endpoint_contract.py``): every endpoint leaf must expose
+a callable ``build_endpoint`` taking one ``ProviderConfig`` subclass, so a typo or a
+missing factory fails loudly there rather than silently vanishing from the catalog.
+"""
+
+import importlib
+import pkgutil
+from collections.abc import Callable, Iterable, Iterator
+from types import ModuleType
+from typing import cast, get_type_hints
+
+import fleetpull.endpoints
+from fleetpull.config import ProviderConfig
+from fleetpull.endpoints.shared import EndpointDefinition
+from fleetpull.exceptions import ConfigurationError
+from fleetpull.model_contract import ResponseModel
+from fleetpull.roster import RosterDefinition, RosterRegistry
+from fleetpull.vocabulary import Provider
+
+__all__: list[str] = [
+    'EndpointRegistry',
+    'build_endpoint_registry',
+    'build_roster_registry',
+]
+
+_FACTORY_NAME: str = 'build_endpoint'
+_SHARED_PACKAGE: str = 'shared'
+
+_EndpointFactory = Callable[[ProviderConfig], EndpointDefinition[ResponseModel]]
+
+
+class EndpointRegistry:
+    """An immutable catalog mapping ``(provider, name)`` to its definition.
+
+    Built once from a bag of definitions, it answers ``get(provider, name)``. The
+    map is private and frozen at construction; a duplicate ``(provider, name)`` is a
+    wiring bug and raises. It holds no provider knowledge and does no discovery.
+
+    Args:
+        definitions: The endpoint definitions to catalog; their ``(provider, name)``
+            keys must be distinct.
+
+    Raises:
+        ConfigurationError: Two definitions share a ``(provider, name)`` key.
+    """
+
+    def __init__(
+        self, definitions: Iterable[EndpointDefinition[ResponseModel]]
+    ) -> None:
+        by_key: dict[tuple[Provider, str], EndpointDefinition[ResponseModel]] = {}
+        for definition in definitions:
+            key = (definition.provider, definition.name)
+            if key in by_key:
+                raise ConfigurationError(
+                    'duplicate endpoint definition',
+                    provider=definition.provider.value,
+                    endpoint=definition.name,
+                    detail=f'endpoint {definition.name!r} is defined twice',
+                )
+            by_key[key] = definition
+        self._by_key = by_key
+
+    def get(self, provider: Provider, name: str) -> EndpointDefinition[ResponseModel]:
+        """Return the definition for a ``(provider, name)`` key.
+
+        Args:
+            provider: The endpoint's provider.
+            name: The endpoint's name (e.g. ``'vehicles'``).
+
+        Returns:
+            The endpoint's definition.
+
+        Raises:
+            ConfigurationError: No definition is registered for the key -- a consumer
+                references an endpoint the catalog does not declare.
+        """
+        try:
+            return self._by_key[(provider, name)]
+        except KeyError:
+            raise ConfigurationError(
+                'unknown endpoint',
+                provider=provider.value,
+                endpoint=name,
+                detail=f'no endpoint definition registered for {name!r}',
+            ) from None
+
+
+def build_endpoint_registry(configs: Iterable[ProviderConfig]) -> EndpointRegistry:
+    """Discover every endpoint leaf, build its definition, and catalog them.
+
+    Walks the ``endpoints.<provider>`` packages for ``build_endpoint`` factories,
+    injects each factory's annotated provider config from ``configs`` (matched by
+    exact type), calls it, and returns the populated registry.
+
+    Args:
+        configs: The resolved provider config instances, one per provider whose
+            endpoints should be built. Matched to each factory by the factory's
+            annotated parameter type.
+
+    Returns:
+        The populated ``EndpointRegistry``.
+
+    Raises:
+        ConfigurationError: A leaf exposes no callable ``build_endpoint``, a factory's
+            parameter is not exactly one ``ProviderConfig`` subclass, or no supplied
+            config matches a factory's annotated type.
+    """
+    config_by_type: dict[type[ProviderConfig], ProviderConfig] = {
+        type(config): config for config in configs
+    }
+    definitions: list[EndpointDefinition[ResponseModel]] = []
+    for module_name in _iter_endpoint_leaf_modules():
+        module = importlib.import_module(module_name)
+        factory = _required_factory(module, module_name)
+        config = _config_for_factory(factory, module_name, config_by_type)
+        definitions.append(factory(config))
+    return EndpointRegistry(definitions)
+
+
+def build_roster_registry() -> RosterRegistry:
+    """Discover every declared roster and catalog them.
+
+    The sibling of ``build_endpoint_registry``, sharing the same leaf walk: a
+    roster is a public module-level ``RosterDefinition`` constant declared
+    beside its feeder, so it is discovered rather than hand-listed. Takes no
+    configs -- roster declarations are constants, not factories.
+
+    Returns:
+        The populated ``RosterRegistry``.
+
+    Raises:
+        ConfigurationError: Two collected definitions share a ``RosterKey``
+            (e.g. a constant re-exported into a second leaf module), from
+            ``RosterRegistry`` construction.
+    """
+    definitions: list[RosterDefinition] = []
+    for module_name in _iter_endpoint_leaf_modules():
+        module = importlib.import_module(module_name)
+        definitions.extend(_module_roster_definitions(module))
+    return RosterRegistry(definitions)
+
+
+def _module_roster_definitions(module: ModuleType) -> list[RosterDefinition]:
+    """The public module-level roster declarations of one endpoint leaf.
+
+    Only non-underscore names register: an underscore-prefixed definition is
+    file-private by the naming rule and stays out of the catalog.
+
+    Args:
+        module: The imported leaf module.
+
+    Returns:
+        The module's declared ``RosterDefinition`` constants, in definition
+        order (module namespace order).
+    """
+    return [
+        value
+        for name, value in vars(module).items()
+        if not name.startswith('_') and isinstance(value, RosterDefinition)
+    ]
+
+
+def _iter_endpoint_leaf_modules() -> Iterator[str]:
+    """Yield the dotted name of every endpoint leaf module.
+
+    Walks the ``endpoints`` package for provider subpackages (skipping ``shared`` and
+    any non-package), then each provider package for leaf modules (skipping
+    ``__init__``, which ``iter_modules`` omits, and any ``_``-prefixed private
+    module). Every yielded module is an endpoint leaf obligated to expose
+    ``build_endpoint``.
+    """
+    root_path = fleetpull.endpoints.__path__
+    root_name = fleetpull.endpoints.__name__
+    for provider in pkgutil.iter_modules(root_path):
+        if not provider.ispkg or provider.name == _SHARED_PACKAGE:
+            continue
+        package_name = f'{root_name}.{provider.name}'
+        package = importlib.import_module(package_name)
+        for leaf in pkgutil.iter_modules(package.__path__):
+            if leaf.ispkg or leaf.name.startswith('_'):
+                continue
+            yield f'{package_name}.{leaf.name}'
+
+
+def _required_factory(module: ModuleType, module_name: str) -> _EndpointFactory:
+    """Return the module's ``build_endpoint``, or raise if it is missing.
+
+    Args:
+        module: The imported leaf module.
+        module_name: Its dotted name, for the error.
+
+    Returns:
+        The module's ``build_endpoint`` callable.
+
+    Raises:
+        ConfigurationError: The module exposes no callable ``build_endpoint``.
+    """
+    factory = getattr(module, _FACTORY_NAME, None)
+    if not callable(factory):
+        raise ConfigurationError(
+            'endpoint leaf missing build_endpoint',
+            detail=f'{module_name!r} must expose a callable {_FACTORY_NAME!r}',
+        )
+    return cast(_EndpointFactory, factory)
+
+
+def _config_for_factory(
+    factory: _EndpointFactory,
+    module_name: str,
+    config_by_type: dict[type[ProviderConfig], ProviderConfig],
+) -> ProviderConfig:
+    """Resolve the config instance a factory's annotation asks for.
+
+    Inspects the factory's single parameter, requires its type to be a
+    ``ProviderConfig`` subclass, and returns the matching supplied instance.
+
+    Args:
+        factory: The leaf's ``build_endpoint`` callable.
+        module_name: Its dotted name, for errors.
+        config_by_type: The supplied configs, keyed by exact type.
+
+    Returns:
+        The config instance matching the factory's annotated parameter type.
+
+    Raises:
+        ConfigurationError: The factory does not take exactly one parameter, its
+            parameter is not a ``ProviderConfig`` subclass, or no supplied config
+            matches its annotated type.
+    """
+    hints = get_type_hints(factory)
+    hints.pop('return', None)
+    if len(hints) != 1:
+        raise ConfigurationError(
+            'endpoint factory arity',
+            detail=f'{module_name!r} build_endpoint must take exactly one '
+            f'annotated parameter',
+        )
+    (annotation,) = hints.values()
+    if not (isinstance(annotation, type) and issubclass(annotation, ProviderConfig)):
+        raise ConfigurationError(
+            'endpoint factory parameter type',
+            detail=f'{module_name!r} build_endpoint must annotate a '
+            f'ProviderConfig subclass',
+        )
+    try:
+        return config_by_type[annotation]
+    except KeyError:
+        raise ConfigurationError(
+            'no config supplied for endpoint',
+            detail=f'{module_name!r} requires {annotation.__name__} but no '
+            f'instance was supplied',
+        ) from None

fleetpull/endpoints/samsara/__init__.py

@@ -0,0 +1,12 @@
+# src/fleetpull/endpoints/samsara/__init__.py
+"""The Samsara endpoints package.
+
+A provider package under the endpoints layer. It exposes no factory gather:
+endpoint leaves are discovered by ``build_endpoint_registry`` walking this
+package for modules exposing ``build_endpoint``, so a new Samsara endpoint is
+a new leaf module here with nothing to register. Import a specific factory
+from its leaf module (``fleetpull.endpoints.samsara.vehicles``) when one is
+needed directly.
+"""
+
+__all__: list[str] = []