fleetpull 0.1.0__py3-none-any.whl

fleetpull/__init__.py

@@ -0,0 +1,36 @@
+"""fleetpull: Pull fleet telematics data from provider APIs into typed Polars output.
+
+Retrieval, dtype coercion, and light structural normalization only. Output
+stays as close to the raw API responses as is reasonable. No cross-endpoint
+merging, no unified schema, no assumed end use.
+
+The public data API: ``fetch(Endpoints.Motive.vehicles, auth=...)`` returns
+an eager typed DataFrame, and ``Sync(config_path).run()`` executes a
+config-driven parquet/state sync. Consumers catch ``FleetpullError`` or its
+five public subclasses, all importable here; every other exception type is
+internal.
+"""
+
+from fleetpull.api import Endpoints, Sync, fetch
+from fleetpull.exceptions import (
+    AuthenticationError,
+    ConfigurationError,
+    FleetpullError,
+    ProviderResponseError,
+    RetriesExhaustedError,
+    SyncFailuresError,
+)
+
+__version__: str = '0.1.0'
+
+__all__: list[str] = [
+    'AuthenticationError',
+    'ConfigurationError',
+    'Endpoints',
+    'FleetpullError',
+    'ProviderResponseError',
+    'RetriesExhaustedError',
+    'Sync',
+    'SyncFailuresError',
+    'fetch',
+]

fleetpull/api/__init__.py

@@ -0,0 +1,32 @@
+# src/fleetpull/api/__init__.py
+"""The public data API: the ``Endpoints`` catalog, its identities, ``fetch``, and ``Sync``.
+
+The top tier of the package vertical: it composes everything below
+(config, endpoints, network, records, orchestrator) behind DESIGN §10's
+two-verb surface. ``Sync``, the config-driven verb, composes the
+orchestrator entry -- which is why this tier sits above ``orchestrator``,
+not beside it.
+"""
+
+from fleetpull.api.auth_ingress import AuthInput
+from fleetpull.api.catalog import Endpoints, available_endpoints
+from fleetpull.api.fetch import fetch
+from fleetpull.api.identity import (
+    EndpointIdentity,
+    FeedEndpoint,
+    SnapshotEndpoint,
+    WindowedEndpoint,
+)
+from fleetpull.api.sync import Sync
+
+__all__: list[str] = [
+    'AuthInput',
+    'EndpointIdentity',
+    'Endpoints',
+    'FeedEndpoint',
+    'SnapshotEndpoint',
+    'Sync',
+    'WindowedEndpoint',
+    'available_endpoints',
+    'fetch',
+]

fleetpull/api/auth_ingress.py

@@ -0,0 +1,216 @@
+# src/fleetpull/api/auth_ingress.py
+"""The auth ingress: the one public ``auth=`` shape, coerced immediately.
+
+The public verbs take a single lax ``auth=`` value -- a bare string for
+single-credential providers (Motive, Samsara), named fields (a plain
+mapping or ``GeotabAuthConfig``) for GeoTab's four-field credential.
+Tuples are rejected in both directions: the 1-tuple requires the
+trailing-comma trap and the 4-tuple invites transposed fields discovered
+only at auth-failure time (DESIGN §10). Ingress coerces every accepted
+shape into the internal ``SecretStr``-carrying auth at this boundary, so
+no bare secret survives past it -- not into a repr, an exception
+message, or a log line.
+
+Dispatch keys off the endpoint identity's provider, never off the auth
+value's shape: a shape that happens to fit another provider is still a
+``ConfigurationError`` here. The provider → (auth strategy, classifier)
+knowledge lives in this module because it can live nowhere lower: the
+ingress sits in the top tier and may import both ``config`` and
+``network``, while ``config`` cannot import ``network``, so the mapping
+cannot ride on provider configs.
+
+Profile construction takes a ``ProviderProfileContext`` alongside the
+identity and the credential: the composition-root collaborators a
+provider's auth machinery draws on. Motive's static header needs none of
+them and ignores the context; GeoTab's session stack consumes all three
+(the authenticator's HTTP posture and limiter slot, the session
+manager's clock). The context grows only when a provider's auth
+machinery demands a new collaborator -- it is not a general-purpose bag.
+"""
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+from pydantic import SecretStr, ValidationError
+
+from fleetpull.api.identity import EndpointIdentity
+from fleetpull.config import GeotabAuthConfig, HttpConfig
+from fleetpull.exceptions import ConfigurationError
+from fleetpull.network.auth import (
+    GeotabSessionAuth,
+    GeotabSessionManager,
+    StaticHeaderAuth,
+    build_geotab_authenticator,
+)
+from fleetpull.network.classifiers import (
+    GeotabResponseClassifier,
+    MotiveResponseClassifier,
+    SamsaraResponseClassifier,
+)
+from fleetpull.network.client import ProviderProfile
+from fleetpull.network.limits import RateLimiterRegistry
+from fleetpull.timing import Clock
+from fleetpull.vocabulary import Provider, QuotaScope
+
+__all__: list[str] = ['AuthInput', 'ProviderProfileContext', 'build_provider_profile']
+
+# The §10 auth union. SecretStr is accepted alongside the bare string so
+# the config path (Sync) hands its already-wrapped credential straight
+# through -- the raw value never needs unwrapping just to be re-wrapped
+# at the boundary. GeoTab's arms carry the four-field credential whole.
+type AuthInput = str | SecretStr | Mapping[str, str] | GeotabAuthConfig
+
+# Provider knowledge no consumer should type: the header a Motive
+# static key travels in.
+_MOTIVE_AUTH_HEADER: str = 'X-API-Key'
+
+# Samsara's bearer credential: the header and the value prefix. The
+# ingress pre-formats 'Bearer <token>' before wrapping in SecretStr --
+# StaticHeaderAuth documents pre-formatting as the composition root's
+# job, and this is that site.
+_SAMSARA_AUTH_HEADER: str = 'Authorization'
+_SAMSARA_BEARER_PREFIX: str = 'Bearer '
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderProfileContext:
+    """Composition-root collaborators provider profile construction draws on.
+
+    Grows only when a provider's auth machinery demands a new
+    collaborator; this is not a general-purpose bag.
+
+    Attributes:
+        http_config: Timeouts and TLS posture for auth-side HTTP calls.
+        limiter_registry: The shared registry; auth calls take limiter
+            slots like any other request (token-per-attempt).
+        clock: The run's shared clock (session-age timestamping). Required
+            -- no default -- because clock identity matters (the one-clock
+            rule): ``Sync`` passes its shared clock, ``fetch`` constructs
+            one at the profile-build site.
+    """
+
+    http_config: HttpConfig
+    limiter_registry: RateLimiterRegistry
+    clock: Clock
+
+
+def build_provider_profile(
+    endpoint: EndpointIdentity, auth: AuthInput, context: ProviderProfileContext
+) -> ProviderProfile:
+    """Coerce the public ``auth=`` value into the provider's client profile.
+
+    Args:
+        endpoint: The identity whose provider selects the credential
+            shape and classifier; the auth value's own shape never
+            drives dispatch.
+        auth: The public credential value. Motive and Samsara each
+            require a bare API-key/token string; GeoTab requires a
+            ``GeotabAuthConfig`` or a mapping with its named fields.
+        context: The composition-root collaborators (HTTP posture,
+            limiter registry, clock) a provider's auth machinery draws
+            on; the static-key providers ignore it, GeoTab consumes it.
+
+    Returns:
+        The ``ProviderProfile`` (``SecretStr``-carrying auth strategy
+        plus response classifier) the transport client is built on.
+
+    Raises:
+        ConfigurationError: ``auth``'s shape mismatches the endpoint's
+            provider (naming the expected shape and the provider, never
+            the value).
+    """
+    match endpoint.provider:
+        case Provider.MOTIVE:
+            if not isinstance(auth, str | SecretStr):
+                raise ConfigurationError(
+                    'auth shape mismatch',
+                    provider=endpoint.provider.value,
+                    endpoint=endpoint.name,
+                    detail=(
+                        f'Motive auth is a bare API-key string (or SecretStr); '
+                        f'got {type(auth).__name__}'
+                    ),
+                )
+            secret = auth if isinstance(auth, SecretStr) else SecretStr(auth)
+            return ProviderProfile(
+                auth=StaticHeaderAuth(_MOTIVE_AUTH_HEADER, secret),
+                classifier=MotiveResponseClassifier(),
+            )
+        case Provider.GEOTAB:
+            credential = _coerced_geotab_credential(endpoint, auth)
+            authenticate_fn = build_geotab_authenticator(
+                context.http_config,
+                context.limiter_registry,
+                QuotaScope.GEOTAB_AUTHENTICATE.value,
+            )
+            manager = GeotabSessionManager(credential, authenticate_fn, context.clock)
+            return ProviderProfile(
+                auth=GeotabSessionAuth(manager),
+                classifier=GeotabResponseClassifier(),
+            )
+        case Provider.SAMSARA:
+            if not isinstance(auth, str | SecretStr):
+                raise ConfigurationError(
+                    'auth shape mismatch',
+                    provider=endpoint.provider.value,
+                    endpoint=endpoint.name,
+                    detail=(
+                        f'Samsara auth is a bare API-token string (or SecretStr); '
+                        f'got {type(auth).__name__}'
+                    ),
+                )
+            raw_token = auth.get_secret_value() if isinstance(auth, SecretStr) else auth
+            bearer = SecretStr(f'{_SAMSARA_BEARER_PREFIX}{raw_token}')
+            return ProviderProfile(
+                auth=StaticHeaderAuth(_SAMSARA_AUTH_HEADER, bearer),
+                classifier=SamsaraResponseClassifier(),
+            )
+
+
+def _coerced_geotab_credential(
+    endpoint: EndpointIdentity, auth: AuthInput
+) -> GeotabAuthConfig:
+    """Coerce the GeoTab ``auth=`` shapes into the internal credential.
+
+    A ``GeotabAuthConfig`` passes through as-is; a plain mapping is
+    validated into one (Pydantic wraps the password into ``SecretStr``).
+    Every rejection names the provider and the expected shapes and the
+    received type -- never the value.
+
+    Args:
+        endpoint: The GeoTab identity being fetched (error context).
+        auth: The public credential value.
+
+    Returns:
+        The ``SecretStr``-carrying credential.
+
+    Raises:
+        ConfigurationError: The shape is neither accepted form, or the
+            mapping's fields fail credential validation.
+    """
+    if isinstance(auth, GeotabAuthConfig):
+        return auth
+    shape_detail = (
+        'GeoTab auth is a GeotabAuthConfig or a mapping with '
+        'username/password/database and optional server; '
+        f'got {type(auth).__name__}'
+    )
+    if not isinstance(auth, Mapping):
+        raise ConfigurationError(
+            'auth shape mismatch',
+            provider=endpoint.provider.value,
+            endpoint=endpoint.name,
+            detail=shape_detail,
+        )
+    try:
+        return GeotabAuthConfig.model_validate(dict(auth))
+    except ValidationError as error:
+        field_names = ', '.join(
+            '.'.join(str(item) for item in entry['loc']) for entry in error.errors()
+        )
+        raise ConfigurationError(
+            'auth shape mismatch',
+            provider=endpoint.provider.value,
+            endpoint=endpoint.name,
+            detail=f'{shape_detail} (invalid fields: {field_names})',
+        ) from None

fleetpull/api/catalog.py

@@ -0,0 +1,139 @@
+# src/fleetpull/api/catalog.py
+"""The public ``Endpoints`` catalog: every exposed endpoint identity.
+
+A static, committed module -- never codegen. Provider namespaces are
+CapWords class-like containers (``Endpoints.Motive``, PEP 8's convention
+for public class-like names); endpoint attributes are lowercase
+identities typed snapshot, windowed, or feed, so the type checker
+enforces ``fetch``'s snapshot-only exposure at the call site. The load-bearing
+identity everywhere strings live stays the lowercase ``Provider`` value,
+so the CapWords surface introduces no string drift (DESIGN §10).
+
+The drift protection is the two-way parity discipline test
+(``tests/api/test_catalog.py``) against ``build_endpoint_registry``:
+every identity here must resolve in the discovery registry with a
+matching mode, and every discovered endpoint must appear here with the
+mode-matching identity type.
+"""
+
+from fleetpull.api.identity import (
+    EndpointIdentity,
+    FeedEndpoint,
+    SnapshotEndpoint,
+    WindowedEndpoint,
+)
+from fleetpull.vocabulary import Provider
+
+__all__: list[str] = ['Endpoints', 'available_endpoints']
+
+
+class Endpoints:
+    """Provider-namespaced catalog of every public endpoint identity.
+
+    The namespaces hold inert identities only -- the verbs stay flat and
+    provider-agnostic, so the catalog is organized by provider while the
+    behavior is not (DESIGN §10, the orchestrator-boundary principle).
+    """
+
+    class Motive:
+        """Motive endpoint identities."""
+
+        vehicles: SnapshotEndpoint = SnapshotEndpoint(Provider.MOTIVE, 'vehicles')
+        vehicle_locations: WindowedEndpoint = WindowedEndpoint(
+            Provider.MOTIVE, 'vehicle_locations'
+        )
+        driving_periods: WindowedEndpoint = WindowedEndpoint(
+            Provider.MOTIVE, 'driving_periods'
+        )
+        idle_events: WindowedEndpoint = WindowedEndpoint(Provider.MOTIVE, 'idle_events')
+        groups: SnapshotEndpoint = SnapshotEndpoint(Provider.MOTIVE, 'groups')
+        users: SnapshotEndpoint = SnapshotEndpoint(Provider.MOTIVE, 'users')
+        vehicle_utilizations: WindowedEndpoint = WindowedEndpoint(
+            Provider.MOTIVE, 'vehicle_utilizations'
+        )
+        driver_idle_rollups: WindowedEndpoint = WindowedEndpoint(
+            Provider.MOTIVE, 'driver_idle_rollups'
+        )
+
+    class Samsara:
+        """Samsara endpoint identities."""
+
+        vehicles: SnapshotEndpoint = SnapshotEndpoint(Provider.SAMSARA, 'vehicles')
+        drivers: SnapshotEndpoint = SnapshotEndpoint(Provider.SAMSARA, 'drivers')
+        trips: WindowedEndpoint = WindowedEndpoint(Provider.SAMSARA, 'trips')
+        idling_events: WindowedEndpoint = WindowedEndpoint(
+            Provider.SAMSARA, 'idling_events'
+        )
+        addresses: SnapshotEndpoint = SnapshotEndpoint(Provider.SAMSARA, 'addresses')
+        engine_states: WindowedEndpoint = WindowedEndpoint(
+            Provider.SAMSARA, 'engine_states'
+        )
+        gps_readings: WindowedEndpoint = WindowedEndpoint(
+            Provider.SAMSARA, 'gps_readings'
+        )
+        odometer_readings: WindowedEndpoint = WindowedEndpoint(
+            Provider.SAMSARA, 'odometer_readings'
+        )
+        asset_locations: WindowedEndpoint = WindowedEndpoint(
+            Provider.SAMSARA, 'asset_locations'
+        )
+        driver_vehicle_assignments: WindowedEndpoint = WindowedEndpoint(
+            Provider.SAMSARA, 'driver_vehicle_assignments'
+        )
+        vehicle_fuel_energy_reports: WindowedEndpoint = WindowedEndpoint(
+            Provider.SAMSARA, 'vehicle_fuel_energy_reports'
+        )
+        driver_fuel_energy_reports: WindowedEndpoint = WindowedEndpoint(
+            Provider.SAMSARA, 'driver_fuel_energy_reports'
+        )
+
+    class Geotab:
+        """GeoTab endpoint identities."""
+
+        devices: SnapshotEndpoint = SnapshotEndpoint(Provider.GEOTAB, 'devices')
+        users: SnapshotEndpoint = SnapshotEndpoint(Provider.GEOTAB, 'users')
+        trips: WindowedEndpoint = WindowedEndpoint(Provider.GEOTAB, 'trips')
+        exception_events: WindowedEndpoint = WindowedEndpoint(
+            Provider.GEOTAB, 'exception_events'
+        )
+        log_records: FeedEndpoint = FeedEndpoint(Provider.GEOTAB, 'log_records')
+        status_data: FeedEndpoint = FeedEndpoint(Provider.GEOTAB, 'status_data')
+        fill_ups: FeedEndpoint = FeedEndpoint(Provider.GEOTAB, 'fill_ups')
+        fuel_and_energy_used: FeedEndpoint = FeedEndpoint(
+            Provider.GEOTAB, 'fuel_and_energy_used'
+        )
+        fuel_tax_details: FeedEndpoint = FeedEndpoint(
+            Provider.GEOTAB, 'fuel_tax_details'
+        )
+        fault_data: FeedEndpoint = FeedEndpoint(Provider.GEOTAB, 'fault_data')
+        duty_status_logs: FeedEndpoint = FeedEndpoint(
+            Provider.GEOTAB, 'duty_status_logs'
+        )
+        driver_changes: FeedEndpoint = FeedEndpoint(Provider.GEOTAB, 'driver_changes')
+        dvir_logs: FeedEndpoint = FeedEndpoint(Provider.GEOTAB, 'dvir_logs')
+        annotation_logs: FeedEndpoint = FeedEndpoint(Provider.GEOTAB, 'annotation_logs')
+        shipment_logs: FeedEndpoint = FeedEndpoint(Provider.GEOTAB, 'shipment_logs')
+        audits: FeedEndpoint = FeedEndpoint(Provider.GEOTAB, 'audits')
+        text_messages: FeedEndpoint = FeedEndpoint(Provider.GEOTAB, 'text_messages')
+        media_files: FeedEndpoint = FeedEndpoint(Provider.GEOTAB, 'media_files')
+
+
+def available_endpoints() -> tuple[EndpointIdentity, ...]:
+    """Enumerate the whole catalog -- its manifest, in declaration order.
+
+    Derived from the provider namespaces themselves: each namespace's
+    class ``vars()`` preserves declaration order, so the manifest is the
+    catalog read back, never a hand-kept repeat that could drift from it
+    (the parity test still proves both directions against discovery).
+
+    Returns:
+        Every identity the ``Endpoints`` catalog exposes -- Motive, then
+        Samsara, then GeoTab, each in declaration order.
+    """
+    provider_namespaces = (Endpoints.Motive, Endpoints.Samsara, Endpoints.Geotab)
+    return tuple(
+        attribute
+        for namespace in provider_namespaces
+        for attribute in vars(namespace).values()
+        if isinstance(attribute, (SnapshotEndpoint, WindowedEndpoint, FeedEndpoint))
+    )

fleetpull/api/fetch.py

@@ -0,0 +1,229 @@
+# src/fleetpull/api/fetch.py
+"""``fetch``: the snapshot-only, in-memory programmatic convenience verb.
+
+The convenience charter (DESIGN §10): an endpoint identity, one
+``auth=`` value, and almost nothing else, returning an eager typed
+DataFrame with no state machinery -- no SQLite, no disk, no cursor, no
+run ledger, no roster. ``fetch`` deliberately limits options; a caller
+who wants windows, incremental resume, partitioned storage, or fan-out
+is a sync user, not a fetch user with missing parameters.
+
+Snapshot-only because the in-memory contract is only honest for
+snapshots: a snapshot result is bounded by entity count, while a
+windowed result grows with window width and fleet activity, unbounded by
+anything the caller controls in memory. The exposure gate is the
+``SnapshotEndpoint`` parameter type; a runtime guard backs it for the
+audiences mypy never covers (notebooks foremost).
+
+No member filtering, by design: ``fetch`` returns the endpoint's full
+current listing. Filtering (by vehicle, by group, by status) presumes a
+use case, and the scope refusal (§10) forbids exactly that presumption
+-- consumers filter the returned frame themselves.
+
+The composition is the state-free fetch trace (established by the
+2026-07-06 pre-API audit):
+provider configs from defaults → the discovery registry → the definition
+by identity key → a ``ClientRuntime`` on internal defaults → the
+auth-ingress profile (its ``ProviderProfileContext`` reusing the
+runtime's HTTP posture and limiter registry, plus a clock held solely
+for GeoTab session aging) → the shape-resolved request driver (the
+shared ``resolve_request_driver`` seam with no roster source: the
+stateless shapes a snapshot can declare -- single fetch, param sweep
+-- resolve (a bisected window is watermark-only by construction and
+never reaches this verb), a roster-backed shape (``RosterFanOut`` /
+``BatchedRosterFanOut``) is refused loudly, and the
+driver honors a declared completeness check, so a guarded snapshot is
+verified on this verb exactly as under sync) → ``TransportClient`` →
+``validate_records`` → ``models_to_dataframe``.
+"""
+
+import logging
+
+import polars as pl
+
+from fleetpull.api.auth_ingress import (
+    AuthInput,
+    ProviderProfileContext,
+    build_provider_profile,
+)
+from fleetpull.api.identity import FeedEndpoint, SnapshotEndpoint, WindowedEndpoint
+from fleetpull.config import (
+    HttpConfig,
+    RetryConfig,
+    default_provider_sections,
+)
+from fleetpull.endpoints import build_endpoint_registry
+from fleetpull.exceptions import ConfigurationError
+from fleetpull.network.client import ClientRuntime, TransportClient
+from fleetpull.network.limits import RateLimiterRegistry, rate_limits_from_configs
+from fleetpull.orchestrator import FetchPoolRegistry, resolve_request_driver
+from fleetpull.records import models_to_dataframe, validate_records
+from fleetpull.timing import SystemClock
+from fleetpull.vocabulary import JsonObject
+
+__all__: list[str] = ['fetch']
+
+logger = logging.getLogger(__name__)
+
+
+# typing-justified: ingress guard; input unknowable by design; object forces narrowing
+def _require_snapshot_identity(endpoint: object) -> None:
+    """Reject a non-snapshot identity before any client construction.
+
+    The static gate (the ``SnapshotEndpoint`` parameter type) protects
+    type-checked callers; this guard is the same gate for the
+    convenience verb's unchecked audience. Typed on ``object`` so the
+    narrowing is real work to the type checker rather than a
+    statically-unreachable branch.
+
+    Args:
+        endpoint: Whatever the caller passed as the endpoint identity.
+
+    Returns:
+        None when ``endpoint`` is a ``SnapshotEndpoint``.
+
+    Raises:
+        ConfigurationError: ``endpoint`` is windowed- or feed-typed (naming
+            the endpoint and its mode) or is no catalog identity at all.
+    """
+    if isinstance(endpoint, SnapshotEndpoint):
+        return
+    if isinstance(endpoint, WindowedEndpoint):
+        raise ConfigurationError(
+            'fetch is snapshot-only',
+            provider=endpoint.provider.value,
+            endpoint=endpoint.name,
+            detail=(
+                'this endpoint is windowed-mode; windowed retrieval is the '
+                'config-driven sync path, not a fetch option'
+            ),
+        )
+    if isinstance(endpoint, FeedEndpoint):
+        raise ConfigurationError(
+            'fetch is snapshot-only',
+            provider=endpoint.provider.value,
+            endpoint=endpoint.name,
+            detail=(
+                'this endpoint is feed-mode; a feed is an unbounded version '
+                'stream with durable cursor state, retrieved only through '
+                'the config-driven sync path'
+            ),
+        )
+    raise ConfigurationError(
+        'fetch requires a snapshot identity from the Endpoints catalog',
+        detail=f'got {type(endpoint).__name__}',
+    )
+
+
+def fetch(
+    endpoint: SnapshotEndpoint,
+    auth: AuthInput,
+    *,
+    use_truststore: bool = False,
+) -> pl.DataFrame:
+    """Fetch one snapshot endpoint's full current listing into a DataFrame.
+
+    End-to-end in memory: no SQLite, no disk, no cursor, no run ledger,
+    no roster. Anything beyond this surface -- windows, incremental
+    resume, partitioned storage, roster fan-out, member filtering -- is
+    the config-driven sync path's territory, not a missing parameter
+    here. The request driver is shape-resolved through the shared seam,
+    so every stateless request shape (single fetch, param sweep) is
+    served; a roster fan-out needs durable roster state and is refused.
+
+    Args:
+        endpoint: A snapshot-typed identity from the ``Endpoints``
+            catalog (``Endpoints.Motive.vehicles``). Windowed identities
+            fail the type checker and, for unchecked callers, the
+            runtime guard.
+        auth: The provider credential. Motive and Samsara take a bare
+            API-key string; GeoTab takes named fields (a plain mapping
+            or a ``GeotabAuthConfig``). Coerced immediately into
+            ``SecretStr``-carrying internals; the raw value never
+            appears in errors or logs.
+        use_truststore: Build TLS contexts from the operating system's
+            trust store -- required behind TLS-intercepting corporate
+            proxies. Default False, coerced into the identically named
+            ``HttpConfig.use_truststore``. Timeouts and any further
+            transport posture are config-phase territory.
+
+    Returns:
+        An eager Polars DataFrame, dtype-coerced per the endpoint's
+        response model. Column order is deliberately unspecified. An
+        empty listing is a zero-row frame carrying the full typed schema
+        -- never ``None``, never a schemaless frame.
+
+    Raises:
+        FleetpullError: Any operational failure -- always one of the
+            four public subclasses below; every other exception type is
+            internal and renameable.
+        ConfigurationError: The identity is not snapshot-typed, the auth
+            shape mismatches the endpoint's provider, the identity
+            resolves to no registered endpoint, or the endpoint declares
+            a roster-backed shape (``RosterFanOut`` /
+            ``BatchedRosterFanOut``: roster state is sync territory;
+            fetch is stateless by contract).
+        AuthenticationError: The provider rejected the credential
+            unfixably.
+        RetriesExhaustedError: A retryable failure category exhausted
+            its attempt budget.
+        ProviderResponseError: A non-retryable or contract-violating
+            provider response, including a 200 whose body is not JSON
+            and records that fail model validation.
+
+    Scope: retrieval, dtype coercion, and light structural normalization
+    only -- no cross-endpoint joins, no unified schema, no assumed end
+    use (DESIGN §10).
+    """
+    _require_snapshot_identity(endpoint)
+    provider_configs = default_provider_sections()
+    registry = build_endpoint_registry(list(provider_configs.values()))
+    definition = registry.get(endpoint.provider, endpoint.name)
+    runtime = ClientRuntime(
+        http_config=HttpConfig(use_truststore=use_truststore),
+        retry_config=RetryConfig(),
+        limiter_registry=RateLimiterRegistry(
+            rate_limits_from_configs(list(provider_configs.values()))
+        ),
+    )
+    # fetch holds a clock solely for GeoTab session aging; the state-free
+    # trace otherwise needs none.
+    profile = build_provider_profile(
+        endpoint,
+        auth,
+        ProviderProfileContext(
+            http_config=runtime.http_config,
+            limiter_registry=runtime.limiter_registry,
+            clock=SystemClock(),
+        ),
+    )
+    fetch_workers = {
+        endpoint.provider: (
+            provider_configs[endpoint.provider].rate_limit.max_concurrency
+        )
+    }
+    with FetchPoolRegistry(fetch_workers) as fetch_pools:
+        # The shared shape seam with no roster source: every stateless
+        # shape resolves; a roster-backed shape is refused loudly before any
+        # transport pool opens. The resolved driver owns the chain (spec
+        # build, page loop) and, when the definition declares a
+        # completeness check, the post-stream count verification -- fetch
+        # must not offer a weaker read of a guarded endpoint than sync
+        # does.
+        driver = resolve_request_driver(
+            definition, fetch_pools=fetch_pools, roster_members=None
+        )
+        with TransportClient(profile, runtime) as client:
+            raw_records: list[JsonObject] = [
+                record
+                for page in driver.record_batches(definition, client, None)
+                for record in page.records
+            ]
+    logger.info(
+        'Fetched %d %s.%s records across the snapshot listing.',
+        len(raw_records),
+        endpoint.provider.value,
+        endpoint.name,
+    )
+    validated_models = validate_records(raw_records, definition.response_model)
+    return models_to_dataframe(validated_models, definition.response_model)