fleetpull 0.1.0__py3-none-any.whl

fleetpull/endpoints/geotab/log_records.py

@@ -0,0 +1,74 @@
+# src/fleetpull/endpoints/geotab/log_records.py
+"""The GeoTab log_records binding: the first GeoTab feed vertical.
+
+A ``GetFeed`` drive of the ``LogRecord`` entity — the ACTIVE GPS stream:
+records are emitted once, never re-emitted, and carry no per-record
+version, so the append-only cell is trivially complete and the consumer
+reconciles by ``id`` (DESIGN §4). The run resumes from the stored
+``FeedToken`` (or a ``FeedSeed`` at the sync-wide cold-start anchor on
+the tokenless first run), rides the shared ``GeotabGetFeedSpecBuilder``
+and ``GeotabFeedPageDecoder``, spends from the ``geotab_feed``
+method-class budget, and appends every emitted record into its event
+date's partition as numbered part files — stored as emitted, nothing
+ever deleted or replaced.
+
+``resultsLimit`` is the 50,000 protocol maximum: the probed tenant emits
+>50,000 LogRecords/day (a 50,000-record page did not cover one day), so
+anything smaller only multiplies pages against the ~60/min feed budget
+(DESIGN §8, the 2026-07-21 feed wave block).
+
+Every request here is a JSON-RPC POST whose ``params.credentials`` and
+resolved host are the session strategy's injections (the devices-leaf
+convention); the host this module writes is a pre-auth placeholder.
+"""
+
+from typing import Final
+
+from fleetpull.config import GeotabConfig
+from fleetpull.endpoints.geotab._requests import GeotabGetFeedSpecBuilder, server_host
+from fleetpull.endpoints.shared import EndpointDefinition, FeedMode, StorageKind
+from fleetpull.models.geotab import LogRecord
+from fleetpull.network.decoders import GeotabFeedPageDecoder
+from fleetpull.vocabulary import Provider, QuotaScope
+
+__all__: list[str] = ['build_endpoint']
+
+# The GetFeed protocol maximum; the daily volume exceeds one page.
+_RESULTS_LIMIT: Final[int] = 50000
+
+_LOG_RECORD_TYPE_NAME: Final[str] = 'LogRecord'
+
+
+def build_endpoint(config: GeotabConfig) -> EndpointDefinition[LogRecord]:
+    """Build the GeoTab log_records feed binding.
+
+    The GPS stream fetched incrementally as a version-token feed: the
+    run resumes from the stored token (seeded via ``search.fromDate``
+    on the tokenless first run only), each page appends durably before
+    its ``toVersion`` commits, and the fetched records land in
+    ``date=YYYY-MM-DD`` partitions as new numbered part files.
+
+    Args:
+        config: The validated GeoTab configuration; supplies the
+            authentication host the pre-auth spec URLs are built on.
+
+    Returns:
+        The frozen log_records ``EndpointDefinition``. Construction
+        validates the ``FeedMode`` / ``APPEND_LOG`` /
+        ``event_time_column`` triple against the response model.
+    """
+    return EndpointDefinition(
+        provider=Provider.GEOTAB,
+        name='log_records',
+        spec_builder=GeotabGetFeedSpecBuilder(
+            server=server_host(config),
+            type_name=_LOG_RECORD_TYPE_NAME,
+            results_limit=_RESULTS_LIMIT,
+        ),
+        page_decoder=GeotabFeedPageDecoder(),
+        response_model=LogRecord,
+        quota_scope=QuotaScope.GEOTAB_FEED,
+        storage_kind=StorageKind.APPEND_LOG,
+        sync_mode=FeedMode(),
+        event_time_column='date_time',
+    )

fleetpull/endpoints/geotab/media_files.py

@@ -0,0 +1,74 @@
+# src/fleetpull/endpoints/geotab/media_files.py
+"""The GeoTab media_files binding: the media-attachment feed.
+
+A ``GetFeed`` drive of the ``MediaFile`` entity — media attachments
+(images, video, ...) carrying a per-record ``version``; the consumer
+reconciles by ``(id, max version)`` (DESIGN §4). MediaFile carries NO
+``dateTime`` key: the event-time identity is ``fromDate`` (the media
+start, 55/55), so this leaf anchors ``event_time_column='from_date'``
+rather than the ``date_time`` its feed siblings use
+(``models/geotab/media_file.py``). Thin evidence at the probed tenant —
+55 records over 730 days — so the model is conservative.
+
+``resultsLimit`` is the 50,000 protocol maximum: the docs list no lower
+per-type cap for this type (the SCALE census cannot probe a cap the
+55-record population never reaches — the FillUp dual-provenance lesson's
+other arm, DESIGN §8), so the protocol maximum stands.
+
+Every request here is a JSON-RPC POST whose ``params.credentials`` and
+resolved host are the session strategy's injections (the devices-leaf
+convention); the host this module writes is a pre-auth placeholder.
+"""
+
+from typing import Final
+
+from fleetpull.config import GeotabConfig
+from fleetpull.endpoints.geotab._requests import GeotabGetFeedSpecBuilder, server_host
+from fleetpull.endpoints.shared import EndpointDefinition, FeedMode, StorageKind
+from fleetpull.models.geotab import MediaFile
+from fleetpull.network.decoders import GeotabFeedPageDecoder
+from fleetpull.vocabulary import Provider, QuotaScope
+
+__all__: list[str] = ['build_endpoint']
+
+# The GetFeed protocol maximum; no lower documented per-type cap.
+_RESULTS_LIMIT: Final[int] = 50000
+
+_MEDIA_FILE_TYPE_NAME: Final[str] = 'MediaFile'
+
+
+def build_endpoint(config: GeotabConfig) -> EndpointDefinition[MediaFile]:
+    """Build the GeoTab media_files feed binding.
+
+    Media attachments fetched incrementally as a version-token feed: the
+    run resumes from the stored token (seeded via ``search.fromDate`` on
+    the tokenless first run only), each page appends durably before its
+    ``toVersion`` commits, and the fetched records land in
+    ``date=YYYY-MM-DD`` partitions (by ``fromDate``, the event time) as
+    new numbered part files — re-emitted versions accumulate for the
+    consumer's ``(id, max version)`` reconcile.
+
+    Args:
+        config: The validated GeoTab configuration; supplies the
+            authentication host the pre-auth spec URLs are built on.
+
+    Returns:
+        The frozen media_files ``EndpointDefinition``. Construction
+        validates the ``FeedMode`` / ``APPEND_LOG`` /
+        ``event_time_column`` triple against the response model.
+    """
+    return EndpointDefinition(
+        provider=Provider.GEOTAB,
+        name='media_files',
+        spec_builder=GeotabGetFeedSpecBuilder(
+            server=server_host(config),
+            type_name=_MEDIA_FILE_TYPE_NAME,
+            results_limit=_RESULTS_LIMIT,
+        ),
+        page_decoder=GeotabFeedPageDecoder(),
+        response_model=MediaFile,
+        quota_scope=QuotaScope.GEOTAB_FEED,
+        storage_kind=StorageKind.APPEND_LOG,
+        sync_mode=FeedMode(),
+        event_time_column='from_date',
+    )

fleetpull/endpoints/geotab/shipment_logs.py

@@ -0,0 +1,71 @@
+# src/fleetpull/endpoints/geotab/shipment_logs.py
+"""The GeoTab shipment_logs binding: the shipment-manifest feed.
+
+A ``GetFeed`` drive of the ``ShipmentLog`` entity — shipment-manifest
+records attached to a driver and device, carrying a per-record
+``version``. Shipment logs are user-editable, so re-emission under newer
+versions is expected, every emitted version is stored, and the consumer
+reconciles by ``(id, max version)`` (DESIGN §4).
+
+``resultsLimit`` is the 50,000 protocol maximum: the docs list no lower
+per-type cap for this type (the SCALE census cannot probe a cap the
+population never reaches — the FillUp dual-provenance lesson's other
+arm, DESIGN §8), so the protocol maximum stands.
+
+Every request here is a JSON-RPC POST whose ``params.credentials`` and
+resolved host are the session strategy's injections (the devices-leaf
+convention); the host this module writes is a pre-auth placeholder.
+"""
+
+from typing import Final
+
+from fleetpull.config import GeotabConfig
+from fleetpull.endpoints.geotab._requests import GeotabGetFeedSpecBuilder, server_host
+from fleetpull.endpoints.shared import EndpointDefinition, FeedMode, StorageKind
+from fleetpull.models.geotab import ShipmentLog
+from fleetpull.network.decoders import GeotabFeedPageDecoder
+from fleetpull.vocabulary import Provider, QuotaScope
+
+__all__: list[str] = ['build_endpoint']
+
+# The GetFeed protocol maximum; no lower documented per-type cap.
+_RESULTS_LIMIT: Final[int] = 50000
+
+_SHIPMENT_LOG_TYPE_NAME: Final[str] = 'ShipmentLog'
+
+
+def build_endpoint(config: GeotabConfig) -> EndpointDefinition[ShipmentLog]:
+    """Build the GeoTab shipment_logs feed binding.
+
+    Shipment-manifest records fetched incrementally as a version-token
+    feed: the run resumes from the stored token (seeded via
+    ``search.fromDate`` on the tokenless first run only), each page
+    appends durably before its ``toVersion`` commits, and the fetched
+    records land in ``date=YYYY-MM-DD`` partitions as new numbered part
+    files — re-emitted versions accumulate for the consumer's
+    ``(id, max version)`` reconcile.
+
+    Args:
+        config: The validated GeoTab configuration; supplies the
+            authentication host the pre-auth spec URLs are built on.
+
+    Returns:
+        The frozen shipment_logs ``EndpointDefinition``. Construction
+        validates the ``FeedMode`` / ``APPEND_LOG`` /
+        ``event_time_column`` triple against the response model.
+    """
+    return EndpointDefinition(
+        provider=Provider.GEOTAB,
+        name='shipment_logs',
+        spec_builder=GeotabGetFeedSpecBuilder(
+            server=server_host(config),
+            type_name=_SHIPMENT_LOG_TYPE_NAME,
+            results_limit=_RESULTS_LIMIT,
+        ),
+        page_decoder=GeotabFeedPageDecoder(),
+        response_model=ShipmentLog,
+        quota_scope=QuotaScope.GEOTAB_FEED,
+        storage_kind=StorageKind.APPEND_LOG,
+        sync_mode=FeedMode(),
+        event_time_column='date_time',
+    )

fleetpull/endpoints/geotab/status_data.py

@@ -0,0 +1,71 @@
+# src/fleetpull/endpoints/geotab/status_data.py
+"""The GeoTab status_data binding: the active diagnostic feed.
+
+A ``GetFeed`` drive of the ``StatusData`` entity — the log_records
+binding with the entity swapped: an ACTIVE feed (records emitted once,
+reconciled by ``id``) that, unlike LogRecord, carries a per-record
+``version`` — mirrored as wire truth (DESIGN §4/§8). The name is the
+wire's own uncountable vocabulary (``StatusData`` → ``status_data``);
+there is no plural to form.
+
+``resultsLimit`` is the 50,000 protocol maximum: the probed tenant emits
+~24,500 StatusData records/hour, so anything smaller only multiplies
+pages against the ~60/min feed budget (DESIGN §8, the 2026-07-21 feed
+wave block).
+
+Every request here is a JSON-RPC POST whose ``params.credentials`` and
+resolved host are the session strategy's injections (the devices-leaf
+convention); the host this module writes is a pre-auth placeholder.
+"""
+
+from typing import Final
+
+from fleetpull.config import GeotabConfig
+from fleetpull.endpoints.geotab._requests import GeotabGetFeedSpecBuilder, server_host
+from fleetpull.endpoints.shared import EndpointDefinition, FeedMode, StorageKind
+from fleetpull.models.geotab import StatusData
+from fleetpull.network.decoders import GeotabFeedPageDecoder
+from fleetpull.vocabulary import Provider, QuotaScope
+
+__all__: list[str] = ['build_endpoint']
+
+# The GetFeed protocol maximum; the hourly volume makes pages precious.
+_RESULTS_LIMIT: Final[int] = 50000
+
+_STATUS_DATA_TYPE_NAME: Final[str] = 'StatusData'
+
+
+def build_endpoint(config: GeotabConfig) -> EndpointDefinition[StatusData]:
+    """Build the GeoTab status_data feed binding.
+
+    The diagnostic stream fetched incrementally as a version-token
+    feed: the run resumes from the stored token (seeded via
+    ``search.fromDate`` on the tokenless first run only), each page
+    appends durably before its ``toVersion`` commits, and the fetched
+    records land in ``date=YYYY-MM-DD`` partitions as new numbered part
+    files.
+
+    Args:
+        config: The validated GeoTab configuration; supplies the
+            authentication host the pre-auth spec URLs are built on.
+
+    Returns:
+        The frozen status_data ``EndpointDefinition``. Construction
+        validates the ``FeedMode`` / ``APPEND_LOG`` /
+        ``event_time_column`` triple against the response model.
+    """
+    return EndpointDefinition(
+        provider=Provider.GEOTAB,
+        name='status_data',
+        spec_builder=GeotabGetFeedSpecBuilder(
+            server=server_host(config),
+            type_name=_STATUS_DATA_TYPE_NAME,
+            results_limit=_RESULTS_LIMIT,
+        ),
+        page_decoder=GeotabFeedPageDecoder(),
+        response_model=StatusData,
+        quota_scope=QuotaScope.GEOTAB_FEED,
+        storage_kind=StorageKind.APPEND_LOG,
+        sync_mode=FeedMode(),
+        event_time_column='date_time',
+    )

fleetpull/endpoints/geotab/text_messages.py

@@ -0,0 +1,77 @@
+# src/fleetpull/endpoints/geotab/text_messages.py
+"""The GeoTab text_messages binding: the dispatch-message feed.
+
+A ``GetFeed`` drive of the ``TextMessage`` entity — office↔vehicle
+dispatch messages. TextMessage carries NO per-record ``version`` (the
+FaultData/LogRecord asymmetry, DESIGN §8): the append-only cell is
+trivially complete and the consumer reconciles by ``id`` alone
+(DESIGN §4). Delivered/read receipts re-emit a message under newer FEED
+``toVersion`` tokens and are stored-as-emitted — the feed's own
+versioning, not a per-record ``version`` key.
+
+TextMessage also carries NO ``dateTime`` key: the event-time identity is
+``sent`` (the send instant, 25,000/25,000), so this leaf anchors
+``event_time_column='sent'`` rather than the ``date_time`` its feed
+siblings use (``models/geotab/text_message.py``).
+
+``resultsLimit`` is the 50,000 protocol maximum: the docs list no lower
+per-type cap for this type (the SCALE census cannot probe a cap the
+population never reaches — the FillUp dual-provenance lesson's other
+arm, DESIGN §8), so the protocol maximum stands.
+
+Every request here is a JSON-RPC POST whose ``params.credentials`` and
+resolved host are the session strategy's injections (the devices-leaf
+convention); the host this module writes is a pre-auth placeholder.
+"""
+
+from typing import Final
+
+from fleetpull.config import GeotabConfig
+from fleetpull.endpoints.geotab._requests import GeotabGetFeedSpecBuilder, server_host
+from fleetpull.endpoints.shared import EndpointDefinition, FeedMode, StorageKind
+from fleetpull.models.geotab import TextMessage
+from fleetpull.network.decoders import GeotabFeedPageDecoder
+from fleetpull.vocabulary import Provider, QuotaScope
+
+__all__: list[str] = ['build_endpoint']
+
+# The GetFeed protocol maximum; no lower documented per-type cap.
+_RESULTS_LIMIT: Final[int] = 50000
+
+_TEXT_MESSAGE_TYPE_NAME: Final[str] = 'TextMessage'
+
+
+def build_endpoint(config: GeotabConfig) -> EndpointDefinition[TextMessage]:
+    """Build the GeoTab text_messages feed binding.
+
+    Dispatch messages fetched incrementally as a version-token feed: the
+    run resumes from the stored token (seeded via ``search.fromDate`` on
+    the tokenless first run only), each page appends durably before its
+    ``toVersion`` commits, and the fetched records land in
+    ``date=YYYY-MM-DD`` partitions (by ``sent``, the event time) as new
+    numbered part files.
+
+    Args:
+        config: The validated GeoTab configuration; supplies the
+            authentication host the pre-auth spec URLs are built on.
+
+    Returns:
+        The frozen text_messages ``EndpointDefinition``. Construction
+        validates the ``FeedMode`` / ``APPEND_LOG`` /
+        ``event_time_column`` triple against the response model.
+    """
+    return EndpointDefinition(
+        provider=Provider.GEOTAB,
+        name='text_messages',
+        spec_builder=GeotabGetFeedSpecBuilder(
+            server=server_host(config),
+            type_name=_TEXT_MESSAGE_TYPE_NAME,
+            results_limit=_RESULTS_LIMIT,
+        ),
+        page_decoder=GeotabFeedPageDecoder(),
+        response_model=TextMessage,
+        quota_scope=QuotaScope.GEOTAB_FEED,
+        storage_kind=StorageKind.APPEND_LOG,
+        sync_mode=FeedMode(),
+        event_time_column='sent',
+    )

fleetpull/endpoints/geotab/trips.py

@@ -0,0 +1,102 @@
+# src/fleetpull/endpoints/geotab/trips.py
+"""The GeoTab trips binding: the first windowed (watermark) GeoTab endpoint.
+
+A date-windowed, seek-paged pull of the ``Trip`` entity: the run resumes
+from a ``DateWindow`` (watermark with the provider's late-arrival
+lookback from config -- for trips, the same margin absorbs GeoTab's Trip
+recalculation), the request shape is the shared
+``GeotabWindowedGetSpecBuilder`` (``_requests``) with
+``id_sort=True`` -- the window rides a ``TripSearch``
+(``search.fromDate`` / ``search.toDate``) beside the id-ascending
+``sort`` of the seek walk -- and the fetched days land in
+``date=YYYY-MM-DD`` partitions replaced wholesale. The decoder is the
+existing ``GeotabGetPageDecoder`` unchanged: its advance spreads the
+sent params when rewriting ``sort.offset``, so ``search`` survives
+every page (live-verified 2026-07-13 -- a windowed, sorted, seeked page
+pair returned strictly-ascending ids across the boundary with every
+record inside the window).
+
+``TripSearch`` matches trips by their STOP time (captured 2026-07-06
+via a discriminating window pair; prediction-confirmed 2026-07-15,
+DESIGN §8): a trip whose start precedes ``fromDate`` returns when its
+stop falls inside, and a trip stopping past ``toDate`` never returns.
+The event-time column is therefore ``stop`` — retrieval (stop in
+window) and routing (the runner's per-batch window filter over the
+event-time column) coincide, so every completed trip belongs to exactly
+one chunk: its stop's day. The watermark advances on stop, which
+matches record-materialization order — a Trip exists only once it has
+stopped. Anchoring on ``start`` instead would drop every
+chunk-boundary-crossing trip: the chunk owning its start never receives
+it, and the chunk that fetches it filters it out.
+
+Every request here is a JSON-RPC POST whose ``params.credentials`` and
+resolved host are the session strategy's injections (the devices-leaf
+convention); the host this module writes is a pre-auth placeholder.
+"""
+
+from datetime import timedelta
+from typing import Final
+
+from fleetpull.config import GeotabConfig
+from fleetpull.endpoints.geotab._requests import (
+    GeotabWindowedGetSpecBuilder,
+    server_host,
+)
+from fleetpull.endpoints.shared import (
+    EndpointDefinition,
+    StorageKind,
+    WatermarkMode,
+)
+from fleetpull.models.geotab import Trip
+from fleetpull.network.decoders import GeotabGetPageDecoder
+from fleetpull.vocabulary import Provider, QuotaScope
+
+__all__: list[str] = ['build_endpoint']
+
+# The largest sound page under Get's silent 5,000-record cap.
+_RESULTS_LIMIT: Final[int] = 5000
+
+_TRIP_TYPE_NAME: Final[str] = 'Trip'
+
+
+def build_endpoint(config: GeotabConfig) -> EndpointDefinition[Trip]:
+    """Build the GeoTab trips watermark binding.
+
+    Movement-interval history fetched incrementally: the run resumes
+    from a ``DateWindow``, each window is walked in id-ascending seek
+    pages under the silent 5,000-record ``Get`` cap with the window
+    filter riding ``search``, and the fetched days are written to
+    ``date=YYYY-MM-DD`` partitions replaced wholesale. No
+    ``completeness_check``: the guard is snapshot-only by construction
+    -- a ``GetCountOf`` compares only against a complete listing, and a
+    date window is not one.
+
+    Args:
+        config: The validated GeoTab configuration; supplies the
+            authentication host the pre-auth spec URLs are built on and
+            the lookback and cutoff the watermark mode carries.
+
+    Returns:
+        The frozen trips ``EndpointDefinition``. Construction validates
+        the ``WatermarkMode`` / ``DATE_PARTITIONED`` /
+        ``event_time_column`` triple against the response model.
+    """
+    return EndpointDefinition(
+        provider=Provider.GEOTAB,
+        name='trips',
+        spec_builder=GeotabWindowedGetSpecBuilder(
+            server=server_host(config),
+            type_name=_TRIP_TYPE_NAME,
+            results_limit=_RESULTS_LIMIT,
+            id_sort=True,
+        ),
+        page_decoder=GeotabGetPageDecoder(),
+        response_model=Trip,
+        quota_scope=QuotaScope.GEOTAB_GET,
+        storage_kind=StorageKind.DATE_PARTITIONED,
+        sync_mode=WatermarkMode(
+            lookback=timedelta(days=config.lookback_days),
+            cutoff=timedelta(days=config.cutoff_days),
+        ),
+        event_time_column='stop',
+    )

fleetpull/endpoints/geotab/users.py

@@ -0,0 +1,81 @@
+# src/fleetpull/endpoints/geotab/users.py
+"""The GeoTab users binding: a factory composing the users snapshot
+EndpointDefinition from resolved GeoTab configuration.
+
+The devices pattern verbatim, bound to ``User``: id-sort seek paging is
+supported for this type (proven live 2026-07-16 -- first page ascending,
+the offset advance continuing past the boundary with no overlap; never
+assumed from Device, since ExceptionEvent rejects id-sort outright), so
+the leaf composes the shared ``_requests`` machinery with a
+``GetCountOfCheck`` on ``User``. The captured population (157 accounts,
+count == sweep) sits far under the 5,000 silent cap, but the walk is
+cap-agnostic by construction: the seek advance terminates on the empty
+page whatever the per-type cap turns out to be, and the completeness
+check proves the harvest whole either way.
+
+Every request here is a JSON-RPC POST whose ``params.credentials`` and
+resolved host are the session strategy's injections (the devices-leaf
+convention); the host this module writes is a pre-auth placeholder.
+"""
+
+from typing import Final
+
+from fleetpull.config import GeotabConfig
+from fleetpull.endpoints.geotab._requests import (
+    GeotabGetSpecBuilder,
+    GetCountOfCheck,
+    server_host,
+)
+from fleetpull.endpoints.shared import (
+    EndpointDefinition,
+    SnapshotMode,
+    StorageKind,
+)
+from fleetpull.models.geotab import User
+from fleetpull.network.decoders import GeotabGetPageDecoder
+from fleetpull.vocabulary import Provider, QuotaScope
+
+__all__: list[str] = ['build_endpoint']
+
+# The seek-walk page size. The 5,000 silent Get cap is per-type
+# provenance and was never grazed for User (157 captured accounts);
+# the walk is correct under any per-type cap (see module docstring),
+# so 5000 is a page-size choice here, not a proven ceiling. A strong
+# candidate for a user config knob.
+_RESULTS_LIMIT: Final[int] = 5000
+
+_USER_TYPE_NAME: Final[str] = 'User'
+
+
+def build_endpoint(config: GeotabConfig) -> EndpointDefinition[User]:
+    """Build the GeoTab users snapshot binding.
+
+    A full-listing snapshot of the account's User entities (drivers and
+    console accounts alike): no resume, a single parquet file, full
+    replacement each run. Records arrive as a plain list under
+    ``result``, walked by id-ascending seek pages, and every harvest is
+    verified against ``GetCountOf`` before anything flows downstream.
+
+    Args:
+        config: The validated GeoTab configuration; supplies the
+            authentication host the pre-auth spec URLs are built on.
+
+    Returns:
+        The frozen users ``EndpointDefinition``.
+    """
+    server = server_host(config)
+    return EndpointDefinition(
+        provider=Provider.GEOTAB,
+        name='users',
+        spec_builder=GeotabGetSpecBuilder(
+            server=server,
+            type_name=_USER_TYPE_NAME,
+            results_limit=_RESULTS_LIMIT,
+        ),
+        page_decoder=GeotabGetPageDecoder(),
+        response_model=User,
+        quota_scope=QuotaScope.GEOTAB_GET,
+        storage_kind=StorageKind.SINGLE,
+        sync_mode=SnapshotMode(),
+        completeness_check=GetCountOfCheck(server=server, type_name=_USER_TYPE_NAME),
+    )

fleetpull/endpoints/motive/__init__.py

@@ -0,0 +1,12 @@
+# src/fleetpull/endpoints/motive/__init__.py
+"""The Motive 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 Motive endpoint is
+a new leaf module here with nothing to register. Import a specific factory
+from its leaf module (``fleetpull.endpoints.motive.vehicles``) when one is
+needed directly.
+"""
+
+__all__: list[str] = []

fleetpull/endpoints/motive/_spec_builders.py

@@ -0,0 +1,94 @@
+# src/fleetpull/endpoints/motive/_spec_builders.py
+"""The shared Motive fleet-wide date-range spec-builder.
+
+The builder for Motive endpoints that take day-granular ``start_date`` /
+``end_date`` query parameters with no per-vehicle fan-out
+(driving_periods, idle_events, and the utilization rollup pair
+vehicle_utilizations / driver_idle_rollups) — the promotion the
+vehicle_locations module anticipated once a real second user arrived.
+vehicle_locations keeps its own builder because it renders a
+per-vehicle path; this one serves the fleet-wide leaves and any future
+sibling. The rendered label pair is INCLUSIVE on both ends; how the
+provider interprets it (UTC vs company-local days) is a per-endpoint
+fact each leaf documents.
+
+``window_pad_days`` exists for endpoints whose server-side window
+matching is not UTC: idle_events interprets its date range on
+company-local day boundaries and matches by overlap (DESIGN §8, captured
+2026-07-15), so its leaf pads the wire window one day on each side and
+the true UTC window — the post-fetch window filter and the writer's
+partition tripwire — does the trimming. A pad only ever widens what is
+fetched, never what is written.
+"""
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from datetime import timedelta
+
+from fleetpull.endpoints.shared import ResumeValue, require_date_window
+from fleetpull.network.contract import HttpMethod, RequestSpec
+from fleetpull.timing import to_utc_date_string
+
+__all__: list[str] = ['MotiveFleetDateRangeSpecBuilder']
+
+
+@dataclass(frozen=True, slots=True)
+class MotiveFleetDateRangeSpecBuilder:
+    """Build the fleet-wide, date-windowed first request.
+
+    The ``SpecBuilder`` for Motive watermark endpoints with no fan-out:
+    injects the resume window as ``start_date`` / ``end_date``, mapped
+    exactly as the vehicle_locations builder maps them — ``start_date``
+    is the UTC date of ``window.start`` and ``end_date`` the window's
+    ``last_covered_date`` (the derivation lives on ``DateWindow``) —
+    then widened by ``window_pad_days`` whole days on each side.
+
+    Attributes:
+        base_url: Root of the Motive API, trailing-slash-normalized by
+            the provider config so the leading-slash path joins directly.
+        path: The endpoint's leading-slash request path.
+        window_pad_days: Whole days added to each side of the wire
+            window. Zero for UTC-matched endpoints; idle_events sets one
+            to cover its company-local overlap matching under any account
+            timezone.
+    """
+
+    base_url: str
+    path: str
+    window_pad_days: int = 0
+
+    def build_spec(
+        self, resume: ResumeValue, member_values: Mapping[str, str]
+    ) -> RequestSpec:
+        """Build the fleet-wide, date-windowed GET.
+
+        Args:
+            resume: The run's resume window. Must be a ``DateWindow`` — a
+                watermark endpoint always resumes from one; any other
+                value is a wiring bug.
+            member_values: Accepted to satisfy the protocol; unused — a
+                fleet-wide single chain binds no member.
+
+        Returns:
+            A credential-less ``GET`` for ``base_url + path`` carrying
+            the padded ``start_date`` / ``end_date``. Auth headers are
+            layered on by the client's ``ProviderProfile``; pagination
+            parameters are injected by the page decoder's
+            ``first_request``.
+
+        Raises:
+            TypeError: ``resume`` is not a ``DateWindow``.
+
+        Side Effects:
+            None.
+        """
+        resume_window = require_date_window(resume, type(self).__name__)
+        pad = timedelta(days=self.window_pad_days)
+        start_date = to_utc_date_string(resume_window.start - pad)
+        end_date = (resume_window.last_covered_date + pad).isoformat()
+        params = {'start_date': start_date, 'end_date': end_date}
+        return RequestSpec(
+            method=HttpMethod.GET,
+            url=f'{self.base_url}{self.path}',
+            params=params,
+        )