fleetpull 0.1.0__py3-none-any.whl

fleetpull/endpoints/geotab/driver_changes.py

@@ -0,0 +1,73 @@
+# src/fleetpull/endpoints/geotab/driver_changes.py
+"""The GeoTab driver_changes binding: the driver-assignment feed.
+
+A ``GetFeed`` drive of the ``DriverChange`` entity — driver-to-device
+assignment events carrying a per-record ``version``. DriverChange
+records are user-editable through the provider, so re-emission under
+newer versions is expected, every emitted version is stored, and the
+consumer reconciles by ``(id, max version)`` (DESIGN §4). The proven
+object-or-string driver ref (with its ``isDriver`` object-arm sibling)
+rides the model (``models/geotab/driver_change.py``).
+
+``resultsLimit`` is the 50,000 protocol maximum: the docs list no lower
+per-type cap for this type (verified against the GetFeed reference
+2026-07-21), and the census pulls used small limits, which prove
+nothing about caps (DESIGN §8, the wave two 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 DriverChange
+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
+
+_DRIVER_CHANGE_TYPE_NAME: Final[str] = 'DriverChange'
+
+
+def build_endpoint(config: GeotabConfig) -> EndpointDefinition[DriverChange]:
+    """Build the GeoTab driver_changes feed binding.
+
+    Driver-assignment events 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 driver_changes ``EndpointDefinition``. Construction
+        validates the ``FeedMode`` / ``APPEND_LOG`` /
+        ``event_time_column`` triple against the response model.
+    """
+    return EndpointDefinition(
+        provider=Provider.GEOTAB,
+        name='driver_changes',
+        spec_builder=GeotabGetFeedSpecBuilder(
+            server=server_host(config),
+            type_name=_DRIVER_CHANGE_TYPE_NAME,
+            results_limit=_RESULTS_LIMIT,
+        ),
+        page_decoder=GeotabFeedPageDecoder(),
+        response_model=DriverChange,
+        quota_scope=QuotaScope.GEOTAB_FEED,
+        storage_kind=StorageKind.APPEND_LOG,
+        sync_mode=FeedMode(),
+        event_time_column='date_time',
+    )

fleetpull/endpoints/geotab/duty_status_logs.py

@@ -0,0 +1,75 @@
+# src/fleetpull/endpoints/geotab/duty_status_logs.py
+"""The GeoTab duty_status_logs binding: the HOS duty-status feed.
+
+A ``GetFeed`` drive of the ``DutyStatusLog`` entity — an EDITABLE log:
+``editDateTime`` is the edit trail, past records re-emit under higher
+``version`` tokens as they are edited and verified, every emitted
+version is stored, and the consumer reconciles by ``(id, max version)``
+(DESIGN §4 — the calculated-feed consumer note from the fill_ups
+binding applies verbatim). The wave-two census facts (the proven
+mixed device/driver refs, the annotations id-list reduction, the
+shared nested-location pair) ride the model
+(``models/geotab/duty_status_log.py``).
+
+``resultsLimit`` is the 50,000 protocol maximum: the docs list no lower
+per-type cap for this type (verified against the GetFeed reference
+2026-07-21), and the census pulls used small limits, which prove
+nothing about caps (DESIGN §8, the wave two 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 DutyStatusLog
+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
+
+_DUTY_STATUS_LOG_TYPE_NAME: Final[str] = 'DutyStatusLog'
+
+
+def build_endpoint(config: GeotabConfig) -> EndpointDefinition[DutyStatusLog]:
+    """Build the GeoTab duty_status_logs feed binding.
+
+    HOS duty-status events 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 duty_status_logs ``EndpointDefinition``. Construction
+        validates the ``FeedMode`` / ``APPEND_LOG`` /
+        ``event_time_column`` triple against the response model.
+    """
+    return EndpointDefinition(
+        provider=Provider.GEOTAB,
+        name='duty_status_logs',
+        spec_builder=GeotabGetFeedSpecBuilder(
+            server=server_host(config),
+            type_name=_DUTY_STATUS_LOG_TYPE_NAME,
+            results_limit=_RESULTS_LIMIT,
+        ),
+        page_decoder=GeotabFeedPageDecoder(),
+        response_model=DutyStatusLog,
+        quota_scope=QuotaScope.GEOTAB_FEED,
+        storage_kind=StorageKind.APPEND_LOG,
+        sync_mode=FeedMode(),
+        event_time_column='date_time',
+    )

fleetpull/endpoints/geotab/dvir_logs.py

@@ -0,0 +1,76 @@
+# src/fleetpull/endpoints/geotab/dvir_logs.py
+"""The GeoTab dvir_logs binding: the driver vehicle inspection feed.
+
+A ``GetFeed`` drive of the ``DVIRLog`` entity (the wire's own casing —
+the model is the house-cased ``DvirLog``). DVIRs are certified and
+edited after creation, so past records re-emit under higher ``version``
+tokens, every emitted version is stored, and the consumer reconciles by
+``(id, max version)`` (DESIGN §4). The wave-two census facts (the
+commonly-absent ``device`` trio, the ``defectList`` children exclusion,
+the shared nested-location pair) ride the model
+(``models/geotab/dvir_log.py``).
+
+``resultsLimit`` is the 50,000 protocol maximum: the docs list no lower
+per-type cap for this type (verified against the GetFeed reference
+2026-07-21), and the census pulls used small limits, which prove
+nothing about caps (DESIGN §8, the wave two 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 DvirLog
+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
+
+# The wire typeName keeps the provider's own DVIR casing; only the
+# model class is house-cased.
+_DVIR_LOG_TYPE_NAME: Final[str] = 'DVIRLog'
+
+
+def build_endpoint(config: GeotabConfig) -> EndpointDefinition[DvirLog]:
+    """Build the GeoTab dvir_logs feed binding.
+
+    Inspection reports 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 dvir_logs ``EndpointDefinition``. Construction
+        validates the ``FeedMode`` / ``APPEND_LOG`` /
+        ``event_time_column`` triple against the response model.
+    """
+    return EndpointDefinition(
+        provider=Provider.GEOTAB,
+        name='dvir_logs',
+        spec_builder=GeotabGetFeedSpecBuilder(
+            server=server_host(config),
+            type_name=_DVIR_LOG_TYPE_NAME,
+            results_limit=_RESULTS_LIMIT,
+        ),
+        page_decoder=GeotabFeedPageDecoder(),
+        response_model=DvirLog,
+        quota_scope=QuotaScope.GEOTAB_FEED,
+        storage_kind=StorageKind.APPEND_LOG,
+        sync_mode=FeedMode(),
+        event_time_column='date_time',
+    )

fleetpull/endpoints/geotab/exception_events.py

@@ -0,0 +1,119 @@
+# src/fleetpull/endpoints/geotab/exception_events.py
+"""The GeoTab exception_events binding: the bisected windowed endpoint.
+
+A date-windowed pull of the ``ExceptionEvent`` entity — the UNFILTERED
+stream, every rule (DESIGN §8's 2026-07-15 decision block: no
+server-side rule filter in version one; rule selection is the
+consumer's one-expression job on the delivered stream). The seek walk
+is structurally unavailable here — id-sort is rejected outright for
+this type (captured 2026-07-15: ``ArgumentException``, "Can not sort by
+id"), and any sort composed with a search degrades to the deterministic
+``-32000 GenericException`` — so the leaf composes the shared
+``GeotabWindowedGetSpecBuilder`` (``_requests``) with
+``id_sort=False`` (no ``sort`` member ever written), declares the
+``BisectedWindowFetch`` request shape, and the orchestrator's bisecting
+driver fetches each unit window whole, halving on the exactly-full
+overflow signal down to the floor.
+
+``ExceptionEventSearch`` window matching is OVERLAP-anchored (captured
+2026-07-15): retrieval supersets start-anchored ownership, so
+``active_from`` is the event-time column, the driver's leaf filter and
+the runner's window filter assign every record exactly one owner, and
+no wire-window pad is needed. Events mutate after creation (~1 h
+observed envelope), which the provider-level lookback absorbs.
+
+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 (
+    BisectedWindowFetch,
+    EndpointDefinition,
+    StorageKind,
+    WatermarkMode,
+)
+from fleetpull.models.geotab import ExceptionEvent
+from fleetpull.network.decoders import SinglePageDecoder
+from fleetpull.vocabulary import Provider, QuotaScope
+
+__all__: list[str] = ['build_endpoint']
+
+# The per-request record limit AND the bisection overflow threshold.
+# The silent cap is Captured on this type (2026-07-15: GetCountOf
+# 304,716 vs a bare Get returning exactly 5,000); per-type provenance,
+# not a global GeoTab fact. A strong candidate for a user config knob.
+_RESULTS_LIMIT: Final[int] = 5000
+
+# The bisection floor: a one-minute window still returning a full page
+# fails loudly (sustained >5,000 events/minute fleet-wide, or >5,000
+# events overlapping one instant -- feed territory either way). A
+# strong candidate for a user config knob.
+_FLOOR: Final[timedelta] = timedelta(minutes=1)
+
+# The wire key the bisecting driver anchors leaf ownership by.
+_EVENT_TIME_WIRE_KEY: Final[str] = 'activeFrom'
+
+# The JSON-RPC envelope key the single-page decoder reads records from
+# (the constants-scope precedent: module-private, colocated with the
+# decoder composition that consumes it).
+_RESULT_KEY: Final[str] = 'result'
+
+_EXCEPTION_EVENT_TYPE_NAME: Final[str] = 'ExceptionEvent'
+
+
+def build_endpoint(config: GeotabConfig) -> EndpointDefinition[ExceptionEvent]:
+    """Build the GeoTab exception_events bisected watermark binding.
+
+    The unfiltered ExceptionEvent stream fetched incrementally: the run
+    resumes from a ``DateWindow`` (watermark with the provider's
+    late-arrival lookback from config, which also absorbs the observed
+    post-creation mutation), the bisecting driver fetches each unit
+    window whole (halving on overflow per the declared
+    ``BisectedWindowFetch`` shape), and the kept records land in
+    ``date=YYYY-MM-DD`` partitions on ``active_from``, each refetched
+    partition replaced. Responses are single pages under the JSON-RPC
+    ``result`` key — the cap that once disqualified single-page decoding
+    is the driver's overflow signal now.
+
+    Args:
+        config: The validated GeoTab configuration; supplies the auth
+            host and the lookback and cutoff the watermark mode carries.
+
+    Returns:
+        The frozen exception_events ``EndpointDefinition``. Construction
+        validates the watermark / partitioned / event-time triple and the
+        bisection pairing.
+    """
+    return EndpointDefinition(
+        provider=Provider.GEOTAB,
+        name='exception_events',
+        spec_builder=GeotabWindowedGetSpecBuilder(
+            server=server_host(config),
+            type_name=_EXCEPTION_EVENT_TYPE_NAME,
+            results_limit=_RESULTS_LIMIT,
+            id_sort=False,
+        ),
+        page_decoder=SinglePageDecoder(records_key=_RESULT_KEY),
+        response_model=ExceptionEvent,
+        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='active_from',
+        request_shape=BisectedWindowFetch(
+            results_limit=_RESULTS_LIMIT,
+            floor=_FLOOR,
+            event_time_wire_key=_EVENT_TIME_WIRE_KEY,
+        ),
+    )

fleetpull/endpoints/geotab/fault_data.py

@@ -0,0 +1,72 @@
+# src/fleetpull/endpoints/geotab/fault_data.py
+"""The GeoTab fault_data binding: the engine-fault feed.
+
+A ``GetFeed`` drive of the ``FaultData`` entity — the log_records
+asymmetry stance verbatim: FaultData carries NO per-record ``version``
+(the 2026-07-21 wave two census, DESIGN §8), so the append-only cell is
+trivially complete and the consumer reconciles by ``id`` alone
+(DESIGN §4). The name is the wire's own uncountable vocabulary
+(``FaultData`` → ``fault_data``, the status_data precedent); there is
+no plural to form.
+
+``resultsLimit`` is the 50,000 protocol maximum: the docs list no lower
+per-type cap for this type (verified against the GetFeed reference
+2026-07-21), and the census pulls used small limits, which prove
+nothing about caps (DESIGN §8, the wave two 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 FaultData
+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
+
+_FAULT_DATA_TYPE_NAME: Final[str] = 'FaultData'
+
+
+def build_endpoint(config: GeotabConfig) -> EndpointDefinition[FaultData]:
+    """Build the GeoTab fault_data feed binding.
+
+    The engine-fault 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 fault_data ``EndpointDefinition``. Construction
+        validates the ``FeedMode`` / ``APPEND_LOG`` /
+        ``event_time_column`` triple against the response model.
+    """
+    return EndpointDefinition(
+        provider=Provider.GEOTAB,
+        name='fault_data',
+        spec_builder=GeotabGetFeedSpecBuilder(
+            server=server_host(config),
+            type_name=_FAULT_DATA_TYPE_NAME,
+            results_limit=_RESULTS_LIMIT,
+        ),
+        page_decoder=GeotabFeedPageDecoder(),
+        response_model=FaultData,
+        quota_scope=QuotaScope.GEOTAB_FEED,
+        storage_kind=StorageKind.APPEND_LOG,
+        sync_mode=FeedMode(),
+        event_time_column='date_time',
+    )

fleetpull/endpoints/geotab/fill_ups.py

@@ -0,0 +1,79 @@
+# src/fleetpull/endpoints/geotab/fill_ups.py
+"""The GeoTab fill_ups binding: the first calculated feed vertical.
+
+A ``GetFeed`` drive of the ``FillUp`` entity — provider-detected
+fuel-stop events on a CALCULATED feed: past records re-emit under
+higher versions on reprocessing, every emitted version is stored, and
+the consumer reconciles by ``(id, max version)`` (DESIGN §4). The
+estimates-only-tenant caveat rides the model
+(``models/geotab/fill_up.py``): the probed tenant has no
+fuel-transaction integration, so every fuel value is provider-derived
+and the census cannot speak for integrated tenants.
+
+``resultsLimit`` is 10,000 with DUAL PROVENANCE (DESIGN §8, the
+2026-07-21 feed wave block): 10,000 is the DOCUMENTED per-type cap for
+FillUp, and the probe could not falsify it — a 50,000 request was
+ACCEPTED at this tenant's whole 380-record population, which proves
+nothing about the cap (the population never reaches it). Encoding the
+documented figure is the conservative arm of encode-probed-behavior:
+the probe was structurally unable to test the limit, so the documented
+cap stands until a tenant with >10,000 records probes it.
+
+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 FillUp
+from fleetpull.network.decoders import GeotabFeedPageDecoder
+from fleetpull.vocabulary import Provider, QuotaScope
+
+__all__: list[str] = ['build_endpoint']
+
+# The DOCUMENTED FillUp cap — unprobeable at this tenant's population
+# (module docstring: the dual-provenance record).
+_RESULTS_LIMIT: Final[int] = 10000
+
+_FILL_UP_TYPE_NAME: Final[str] = 'FillUp'
+
+
+def build_endpoint(config: GeotabConfig) -> EndpointDefinition[FillUp]:
+    """Build the GeoTab fill_ups feed binding.
+
+    Fuel-stop detections 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 fill_ups ``EndpointDefinition``. Construction
+        validates the ``FeedMode`` / ``APPEND_LOG`` /
+        ``event_time_column`` triple against the response model.
+    """
+    return EndpointDefinition(
+        provider=Provider.GEOTAB,
+        name='fill_ups',
+        spec_builder=GeotabGetFeedSpecBuilder(
+            server=server_host(config),
+            type_name=_FILL_UP_TYPE_NAME,
+            results_limit=_RESULTS_LIMIT,
+        ),
+        page_decoder=GeotabFeedPageDecoder(),
+        response_model=FillUp,
+        quota_scope=QuotaScope.GEOTAB_FEED,
+        storage_kind=StorageKind.APPEND_LOG,
+        sync_mode=FeedMode(),
+        event_time_column='date_time',
+    )

fleetpull/endpoints/geotab/fuel_and_energy_used.py

@@ -0,0 +1,74 @@
+# src/fleetpull/endpoints/geotab/fuel_and_energy_used.py
+"""The GeoTab fuel_and_energy_used binding: per-trip fuel/energy totals.
+
+A ``GetFeed`` drive of the ``FuelAndEnergyUsed`` entity — a CALCULATED
+feed reconciled by ``(id, max version)`` (DESIGN §4). The name is the
+WIRE'S OWN VOCABULARY, not a plural (the driver_idle_rollups
+precedent): ``FuelAndEnergyUsed`` names a quantity, not a countable
+entity, so no snake-plural exists to form — the endpoint mirrors the
+type name verbatim (DESIGN §8, the 2026-07-21 feed wave block).
+
+``FuelUsed`` is NOT ported: observed identical to this surface on the
+probed tenant (same ids, same values, week-wide) and
+provider-documented as this type's predecessor — the model docstring
+carries the record. The estimates-only-tenant caveat rides the model
+as well (``models/geotab/fuel_and_energy_used.py``).
+
+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 FuelAndEnergyUsed
+from fleetpull.network.decoders import GeotabFeedPageDecoder
+from fleetpull.vocabulary import Provider, QuotaScope
+
+__all__: list[str] = ['build_endpoint']
+
+# The GetFeed protocol maximum (no lower per-type cap documented or
+# observed for this type).
+_RESULTS_LIMIT: Final[int] = 50000
+
+_FUEL_AND_ENERGY_USED_TYPE_NAME: Final[str] = 'FuelAndEnergyUsed'
+
+
+def build_endpoint(config: GeotabConfig) -> EndpointDefinition[FuelAndEnergyUsed]:
+    """Build the GeoTab fuel_and_energy_used feed binding.
+
+    Per-trip fuel/energy totals 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 fuel_and_energy_used ``EndpointDefinition``.
+        Construction validates the ``FeedMode`` / ``APPEND_LOG`` /
+        ``event_time_column`` triple against the response model.
+    """
+    return EndpointDefinition(
+        provider=Provider.GEOTAB,
+        name='fuel_and_energy_used',
+        spec_builder=GeotabGetFeedSpecBuilder(
+            server=server_host(config),
+            type_name=_FUEL_AND_ENERGY_USED_TYPE_NAME,
+            results_limit=_RESULTS_LIMIT,
+        ),
+        page_decoder=GeotabFeedPageDecoder(),
+        response_model=FuelAndEnergyUsed,
+        quota_scope=QuotaScope.GEOTAB_FEED,
+        storage_kind=StorageKind.APPEND_LOG,
+        sync_mode=FeedMode(),
+        event_time_column='date_time',
+    )

fleetpull/endpoints/geotab/fuel_tax_details.py

@@ -0,0 +1,75 @@
+# src/fleetpull/endpoints/geotab/fuel_tax_details.py
+"""The GeoTab fuel_tax_details binding: IFTA jurisdiction segments.
+
+A ``GetFeed`` drive of the ``FuelTaxDetail`` entity — a CALCULATED feed
+of per-jurisdiction travel segments, stored as emitted and reconciled
+by ``(id, max version)``; this type's version identity is the
+``versions`` LIST of component tokens rather than a scalar ``version``
+(the model docstring, DESIGN §8). The estimates-only-tenant caveat
+rides the model (``models/geotab/fuel_tax_detail.py``).
+
+The event-time column is ``enter_time``: a segment materializes where
+the vehicle enters the jurisdiction, so its enter instant is the row's
+one event-time identity (``exit_time`` merely closes the interval —
+the routing choice mirrors the interval-endpoint reasoning the trips
+binding records for ``stop``, at the opposite end because THIS
+entity's identity anchors on entry).
+
+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 FuelTaxDetail
+from fleetpull.network.decoders import GeotabFeedPageDecoder
+from fleetpull.vocabulary import Provider, QuotaScope
+
+__all__: list[str] = ['build_endpoint']
+
+# The GetFeed protocol maximum (no lower per-type cap documented or
+# observed for this type).
+_RESULTS_LIMIT: Final[int] = 50000
+
+_FUEL_TAX_DETAIL_TYPE_NAME: Final[str] = 'FuelTaxDetail'
+
+
+def build_endpoint(config: GeotabConfig) -> EndpointDefinition[FuelTaxDetail]:
+    """Build the GeoTab fuel_tax_details feed binding.
+
+    IFTA jurisdiction segments 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 ``enter_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 fuel_tax_details ``EndpointDefinition``. Construction
+        validates the ``FeedMode`` / ``APPEND_LOG`` /
+        ``event_time_column`` triple against the response model.
+    """
+    return EndpointDefinition(
+        provider=Provider.GEOTAB,
+        name='fuel_tax_details',
+        spec_builder=GeotabGetFeedSpecBuilder(
+            server=server_host(config),
+            type_name=_FUEL_TAX_DETAIL_TYPE_NAME,
+            results_limit=_RESULTS_LIMIT,
+        ),
+        page_decoder=GeotabFeedPageDecoder(),
+        response_model=FuelTaxDetail,
+        quota_scope=QuotaScope.GEOTAB_FEED,
+        storage_kind=StorageKind.APPEND_LOG,
+        sync_mode=FeedMode(),
+        event_time_column='enter_time',
+    )