@openeld/openeld 0.1.0

package/README.md

@@ -0,0 +1,40 @@
+# openeld
+
+`openeld` is a protobuf-first package for a universal logistics data interface across ELD and telematics providers.
+
+## Repository Shape
+
+- `proto/` contains the canonical message and service definitions.
+- `src/` contains the thin TypeScript package surface and hand-written integration scaffolding.
+- `gen/` is reserved for generated language bindings.
+- `buf/` contains protobuf linting and generation configuration.
+- `docs/`, `examples/`, and `tests/fixtures/` support schema evolution and provider onboarding.
+
+## Source Of Truth
+
+All shared types are intended to be defined in Protocol Buffers so TypeScript and Python bindings can be generated from the same contracts.
+
+## Current Schema Coverage
+
+The `v1` schema currently includes:
+
+- common primitives for IDs, dates, time ranges, locations, measurements, source metadata, and audit metadata
+- normalized logistics entities for carriers, drivers, vehicles, vehicle assignments, HOS events, HOS daily summaries, GPS locations, DVIRs, data consents, safety events, IFTA trips, assets, and asset locations
+- provider payload contracts for Samsara, Motive, Geotab, KeepTruckin, Project44, FourKites, Verizon Connect, and Fleet Complete
+- service definitions for ingestion, normalization, query, and sync workflows
+
+The aggregate import surface is `proto/v1/openeld.proto`.
+
+## Generation
+
+The default Buf generation template produces:
+
+- TypeScript output in `gen/ts`
+- Python output in `gen/py`
+
+## Next Steps
+
+- Refine provider-native record coverage as more provider field mappings are confirmed.
+- Widen normalization outputs for consent, safety, IFTA, and asset tracking once provider mappings for those domains are mature.
+- Add validation and contract tests around the `v1` schema.
+- Decide whether query and sync service APIs should remain generic or split further by domain area.

package/buf/buf.gen.yaml

@@ -0,0 +1,8 @@
+version: v2
+plugins:
+  - remote: buf.build/bufbuild/es
+    out: gen/ts
+  - remote: buf.build/protocolbuffers/python
+    out: gen/py
+  - remote: buf.build/grpc/python
+    out: gen/py

package/buf/buf.work.yaml

@@ -0,0 +1,3 @@
+version: v1
+directories:
+  - ../proto

package/docs/architecture/README.md

@@ -0,0 +1,3 @@
+# Architecture Notes
+
+Use this directory for repository structure decisions, normalization flow diagrams, and provider integration architecture.

package/docs/decisions/README.md

@@ -0,0 +1,3 @@
+# Decision Records
+
+Use this directory for architecture decision records related to schema versioning, provider boundaries, and generation strategy.

package/docs/protobuf/README.md

@@ -0,0 +1,28 @@
+# Protobuf Notes
+
+`proto/` is the source of truth for the package.
+
+## Package Layout
+
+- `common/` contains reusable primitives, units, source metadata, and audit metadata.
+- `logistics/` contains the normalized canonical model for carriers, drivers, vehicles, assignments, HOS, GPS, DVIR, consent, safety, IFTA, and assets.
+- `providers/` contains provider-native payload contracts grouped by ELD and telematics source.
+- `services/` contains RPC-ready ingestion, normalization, query, and sync APIs.
+- `v1/openeld.proto` is the aggregate import surface for the current schema version.
+
+## Generation
+
+`buf/buf.gen.yaml` is configured to generate:
+
+- TypeScript via `buf.build/bufbuild/es` into `gen/ts`
+- Python message types via `buf.build/protocolbuffers/python` into `gen/py`
+- Python gRPC stubs via `buf.build/grpc/python` into `gen/py`
+
+## Design Rules
+
+- All identifiers are modeled as strings for cross-language ergonomics.
+- Provider payloads stay separate from normalized logistics messages.
+- Source metadata is attached to records for traceability back to native provider payloads.
+- Distances, speed, engine hours, timestamps, and coordinates use normalized units defined in the schema.
+- Consent, safety, IFTA, and asset tracking are part of the canonical `v1` model.
+- The new Catena-inspired domains are currently exposed through the canonical schema and query APIs without widening provider normalization responses yet.

package/docs/providers/README.md

@@ -0,0 +1,73 @@
+# Provider Notes
+
+This directory is the source of truth for onboarding and maintaining direct U.S. ELD providers.
+
+## Required Documents
+
+Every provider should have:
+
+- a provider note file describing auth, sync, supported domains, and quirks
+- an entry in the capability matrix
+- an entry in the verification matrix
+- a fixture source record tied to authoritative API examples
+
+## Provider Onboarding Playbook
+
+For each provider, complete the same sequence:
+
+1. Confirm provider relevance.
+   Accept only providers that materially help U.S. FMCSA fleet coverage and expose enough API surface to justify direct support.
+2. Capture authoritative API truth.
+   Collect official docs, sandbox responses, or sanitized production payloads for the provider's key endpoints.
+3. Define provider-native protobuf contracts.
+   Represent native records faithfully before mapping them into the canonical logistics schema.
+4. Write failing high-signal tests first.
+   Start with provider contract tests, canonical normalization snapshot tests, and sync-state tests.
+5. Implement normalization and sync logic.
+   Convert provider-native payloads to canonical protobuf messages and model the provider's real checkpoint behavior.
+6. Document fidelity and gaps.
+   Record unsupported fields, inferred mappings, rate limits, auth caveats, and known differences from the canonical model.
+7. Promote maturity deliberately.
+   Move from `planned` to `experimental`, `beta`, and `production` only when the verification matrix supports it.
+
+## High-Signal Fixture Policy
+
+Fixture sources are ranked in this order:
+
+1. official provider examples or schemas
+2. sandbox responses
+3. sanitized production captures
+4. hand-crafted inferred fixtures only when clearly marked and scheduled for replacement
+
+Every fixture set should carry metadata for:
+
+- source URL or endpoint
+- provider API version or doc version
+- capture date
+- auth context
+- sanitization notes
+- supported domains covered by the fixture
+
+## Quality Gates
+
+A provider is not production-ready until:
+
+- provider-native protobuf contracts exist
+- authoritative fixtures exist for the supported domains
+- contract tests pass against those fixtures
+- normalization golden tests pass for those fixtures
+- sync behavior tests cover the provider's real pagination/checkpoint model
+- unsupported or degraded fields are explicitly documented
+
+## Matrix Files
+
+- `capability-matrix.md` tracks what each provider supports and how it behaves operationally
+- `verification-matrix.md` tracks how well each provider has been proven against real API truth
+- `provider-template.md` is the template for adding new provider notes
+
+## Current Provider Notes
+
+- `samsara.md`
+- `motive.md`
+- `geotab.md`
+- `keeptruckin.md`

package/docs/providers/capability-matrix.md

@@ -0,0 +1,13 @@
+# Provider Capability Matrix
+
+| Provider | Auth | Sync Model | Rate Limits | Driver | Vehicle | HOS Events | HOS Clocks | GPS | DVIR | Safety | IFTA | Assets | Maturity | Notes |
+|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
+| Samsara | Bearer token | Feed + webhook + cursor | Documented | Planned | Planned | Planned | Planned | Planned | Planned | Planned | Unknown | Unknown | Planned | Priority direct provider |
+| Motive | API key / OAuth | Page-based polling | Partially documented | Planned | Planned | Planned | Unknown | Planned | Unknown | Unknown | Unknown | Unknown | Planned | Priority direct provider |
+| Geotab | Session auth | `GetFeed` + version token | Documented per database | Planned | Planned | Planned | Planned | Planned | Unknown | Unknown | Unknown | Unknown | Planned | Priority direct provider |
+| KeepTruckin | Legacy compatibility | Legacy polling | Legacy / variable | Planned | Planned | Planned | Unknown | Planned | Unknown | Unknown | Unknown | Unknown | Planned | Maintain only where legacy data matters |
+| TT ELD | API key | Time-window polling | Unknown | Planned | Planned | Planned | Unknown | Planned | Unknown | Unknown | Unknown | Unknown | Planned | Candidate for later expansion |
+| EZLOGZ | API key | Unknown | Unknown | Planned | Planned | Planned | Unknown | Planned | Unknown | Unknown | Unknown | Unknown | Planned | Candidate for later expansion |
+| Verizon Connect | OAuth | Unknown | Unknown | Partial | Partial | Partial | Unknown | Planned | Unknown | Unknown | Unknown | Planned | Planned | Verify ELD/HOS depth before prioritizing |
+
+Update this file as soon as a provider moves beyond planning. Replace `Unknown` and `Partial` with documented facts backed by provider notes and fixtures.

package/docs/providers/geotab.md

@@ -0,0 +1,37 @@
+# Geotab
+
+## Summary
+
+- Regulatory scope: U.S. ELD / compliance capable
+- Target maturity: Planned
+- Current status: Doc-verified fixtures and contract tests committed
+
+## Auth
+
+- Session-style authenticate flow
+
+## Sync Model
+
+- `GetFeed` and `fromVersion` style incremental sync
+- Best fit checkpoint types: version token and watermark
+
+## Supported Domains To Target
+
+- Driver
+- Vehicle
+- HOS events
+- HOS clocks / driver regulation
+- GPS
+
+## Known Mapping Notes
+
+- HOS data centers on `DutyStatusLog` and related types
+- event semantics are richer and more system-oriented than some other providers
+- license number availability may depend on custom fields or account configuration
+- initial committed fixtures are schema-derived from official object and method docs because public static payload examples are limited
+
+## Verification Priority
+
+- committed fixtures: `users`, `devices`, `duty-status-logs`, `driver-regulations`, `log-records`, `getfeed`
+- test coverage: fixture provenance, provider contract shape, canonical golden normalization, version-token sync semantics
+- remaining upgrade path: replace schema-derived fixtures with recorded `Get` and `GetFeed` payloads from a sandbox or live tenant

package/docs/providers/keeptruckin.md

@@ -0,0 +1,35 @@
+# KeepTruckin
+
+## Summary
+
+- Regulatory scope: Legacy compatibility for the Motive lineage
+- Target maturity: Legacy compatibility path
+- Current status: Planned
+
+## Auth
+
+- Legacy behavior may differ by account age and migration path
+
+## Sync Model
+
+- Treat as a legacy polling integration unless verified otherwise
+- Best fit checkpoint types: page-based or watermark-based depending on recovered API behavior
+
+## Supported Domains To Target
+
+- Driver
+- Vehicle
+- HOS events
+- GPS
+- limited DVIR and clock support where verified
+
+## Known Mapping Notes
+
+- use only where customer data or migration scenarios require it
+- prefer compatibility rules and fixtures over broad new feature expansion
+
+## Verification Priority
+
+- capture authentic legacy payloads
+- distinguish legacy KeepTruckin behavior from modern Motive behavior
+- mark all inferred mappings clearly until verified

package/docs/providers/motive.md

@@ -0,0 +1,36 @@
+# Motive
+
+## Summary
+
+- Regulatory scope: U.S. ELD / compliance capable
+- Target maturity: Planned
+- Current status: Doc-verified fixtures and contract tests committed
+
+## Auth
+
+- API key or OAuth 2.0 depending on account/application path
+
+## Sync Model
+
+- Page-based polling is the documented sync model
+- Best fit checkpoint types: page token or page counter plus watermark
+
+## Supported Domains To Target
+
+- Driver
+- Vehicle
+- HOS events
+- GPS
+- DVIR where available
+
+## Known Mapping Notes
+
+- odometer may require miles-to-meters conversion
+- engine hours may require hours-to-seconds conversion
+- logs use native `status`, `annotation`, and coordinate fields
+
+## Verification Priority
+
+- committed fixtures: `drivers`, `vehicles`, `hos-logs`, `vehicle-locations`, `page-sync`
+- test coverage: fixture provenance, provider contract shape, canonical golden normalization, page-based sync semantics
+- remaining upgrade path: validate unit conversion assumptions against sandbox or production captures

package/docs/providers/provider-template.md

@@ -0,0 +1,56 @@
+# Provider Template
+
+## Provider Summary
+
+- Provider:
+- Regulatory scope:
+- Maturity:
+- Last reviewed:
+
+## Auth
+
+- Auth method:
+- Token/session refresh behavior:
+- Required scopes or account setup:
+
+## Sync Model
+
+- Primary sync mechanism:
+- Checkpoint type:
+- Pagination model:
+- Time-window constraints:
+- Webhook support:
+
+## Supported Domains
+
+- Driver:
+- Vehicle:
+- HOS events:
+- HOS clocks:
+- GPS:
+- DVIR:
+- Safety:
+- IFTA:
+- Assets:
+
+## Mapping Notes
+
+- Native payload identifiers:
+- Unit normalization rules:
+- Enum mapping quirks:
+- Known missing or degraded fields:
+
+## Fixture Provenance
+
+- Fixture source:
+- Source URL or endpoint:
+- API/doc version:
+- Capture date:
+- Sanitization notes:
+
+## Test Coverage
+
+- Contract tests:
+- Normalization snapshot tests:
+- Sync behavior tests:
+- Remaining inferred mappings:

package/docs/providers/samsara.md

@@ -0,0 +1,38 @@
+# Samsara
+
+## Summary
+
+- Regulatory scope: U.S. ELD / compliance capable
+- Target maturity: Planned
+- Current status: Doc-verified fixtures and contract tests committed
+
+## Auth
+
+- Bearer API token
+
+## Sync Model
+
+- Feed endpoints with cursor semantics
+- Webhook support is available
+- Best fit checkpoint types: cursor and time watermark
+
+## Supported Domains To Target
+
+- Driver
+- Vehicle
+- HOS events
+- HOS clocks
+- GPS
+- DVIR
+
+## Known Mapping Notes
+
+- `driver.name` may need splitting into first and last name
+- speed may be reported in mph and should normalize to km/h
+- HOS logs expose native `hosStatusType`, `origin`, `remark`, and location details
+
+## Verification Priority
+
+- committed fixtures: `drivers`, `vehicles`, `hos-logs`, `hos-clocks`, `vehicle-locations`, `dvirs`, `feed-cursor`
+- test coverage: fixture provenance, provider contract shape, canonical golden normalization, cursor sync semantics
+- remaining upgrade path: replace doc-derived fixture set with sandbox or production captures when credentials are available

package/docs/providers/verification-matrix.md

@@ -0,0 +1,13 @@
+# Provider Verification Matrix
+
+| Provider | Fixture Source | Last Verified | Auth Tested | Sync Tested | Driver | Vehicle | HOS Events | HOS Clocks | GPS | DVIR | Safety | IFTA | Assets | Inferred Mappings Remaining | Status |
+|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
+| Samsara | Official docs examples and sync docs | 2026-03-14 | No | Yes | Yes | Yes | Yes | Yes | Yes | Yes | No | No | No | Yes | Doc-verified fixtures |
+| Motive | Official docs examples | 2026-03-14 | No | Yes | Yes | Yes | Yes | Yes | Yes | Yes | No | No | No | Yes | Doc-verified fixtures |
+| Geotab | Official object and method docs (schema-derived fixtures) | 2026-03-14 | No | Yes | Yes | Yes | Yes | Yes | Yes | No | No | No | No | Yes | Doc-verified fixtures |
+| KeepTruckin | Not captured yet | Not verified | No | No | No | No | No | No | No | No | No | No | No | Yes | Planned |
+| TT ELD | Not captured yet | Not verified | No | No | No | No | No | No | No | No | No | No | No | Yes | Planned |
+| EZLOGZ | Not captured yet | Not verified | No | No | No | No | No | No | No | No | No | No | No | Yes | Planned |
+| Verizon Connect | Not captured yet | Not verified | No | No | No | No | No | No | No | No | No | No | No | Yes | Planned |
+
+A provider must not be promoted to production-ready if the fixture source is inferred-only or if core supported domains remain unverified.

package/docs/services/README.md

@@ -0,0 +1,3 @@
+# Service Notes
+
+Use this directory for protobuf service responsibilities, request and response flow notes, and transport decisions.

package/examples/ts/README.md

@@ -0,0 +1,3 @@
+# TypeScript Examples
+
+Use this directory for consumer-facing TypeScript examples once protobuf generation and package exports are defined.

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@openeld/openeld",
+  "version": "0.1.0",
+  "description": "Universal protobuf-first data interface for logistics ELD and telematics integrations.",
+  "type": "module",
+  "module": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "proto",
+    "src",
+    "buf",
+    "docs",
+    "examples"
+  ],
+  "scripts": {
+    "proto:lint": "buf lint",
+    "proto:breaking": "buf breaking --against '.git#branch=main'",
+    "gen": "buf generate --template buf/buf.gen.yaml",
+    "test": "bun test",
+    "test:contract": "bun test tests/contract",
+    "test:integration": "bun test tests/integration"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "tsup": "^8.5.1"
+  }
+}

package/proto/README.md

@@ -0,0 +1,9 @@
+# Proto Layout
+
+This directory is the source of truth for all shared data contracts.
+
+- `common/` is reserved for reusable primitives, units, and metadata messages.
+- `logistics/` is reserved for normalized cross-provider logistics models.
+- `providers/` is reserved for vendor-specific message contracts.
+- `services/` is reserved for protobuf service definitions.
+- `v1/` is reserved for versioned package entry definitions.

package/proto/common/metadata/audit.proto

@@ -0,0 +1,22 @@
+syntax = "proto3";
+
+package openeld.common.metadata.v1;
+
+import "google/protobuf/timestamp.proto";
+
+// * Stores audit timestamps and actor references for mutable records.
+message AuditMetadata {
+  optional google.protobuf.Timestamp created_at = 1;
+  optional google.protobuf.Timestamp updated_at = 2;
+  optional string created_by = 3;
+  optional string updated_by = 4;
+  uint32 revision = 5;
+}
+
+// * Describes a discrete change or certification action.
+message ChangeRecord {
+  optional string actor_id = 1;
+  optional string actor_role = 2;
+  optional google.protobuf.Timestamp changed_at = 3;
+  optional string reason = 4;
+}

package/proto/common/metadata/source.proto

@@ -0,0 +1,31 @@
+syntax = "proto3";
+
+package openeld.common.metadata.v1;
+
+import "common/primitives/ids.proto";
+
+// * Identifies the upstream provider that originated a record.
+enum SourceProvider {
+  SOURCE_PROVIDER_UNSPECIFIED = 0;
+  SOURCE_PROVIDER_SAMSARA = 1;
+  SOURCE_PROVIDER_MOTIVE = 2;
+  SOURCE_PROVIDER_GEOTAB = 3;
+  SOURCE_PROVIDER_KEEPTRUCKIN = 4;
+  SOURCE_PROVIDER_PROJECT44 = 5;
+  SOURCE_PROVIDER_FOUR_KITES = 6;
+  SOURCE_PROVIDER_VERIZON_CONNECT = 7;
+  SOURCE_PROVIDER_FLEET_COMPLETE = 8;
+  SOURCE_PROVIDER_CUSTOM = 9;
+}
+
+// * Captures traceability back to the upstream payload and identifiers.
+message SourceRecord {
+  SourceProvider provider = 1;
+  optional string provider_account_id = 2;
+  optional string provider_record_type = 3;
+  optional string primary_external_id = 4;
+  repeated openeld.common.primitives.v1.ExternalIdentifier external_ids = 5;
+  optional string native_status = 6;
+  optional string sync_cursor = 7;
+  optional string raw_payload_json = 8;
+}

package/proto/common/primitives/ids.proto

@@ -0,0 +1,21 @@
+syntax = "proto3";
+
+package openeld.common.primitives.v1;
+
+// * Represents a reusable identifier value.
+message Identifier {
+  string value = 1;
+}
+
+// * References another entity by identifier and logical type.
+message EntityReference {
+  string id = 1;
+  string entity_type = 2;
+}
+
+// * Captures a provider or external system identifier.
+message ExternalIdentifier {
+  string namespace = 1;
+  string value = 2;
+  optional string label = 3;
+}

package/proto/common/primitives/location.proto

@@ -0,0 +1,23 @@
+syntax = "proto3";
+
+package openeld.common.primitives.v1;
+
+// * Stores a geographic point using normalized decimal-degree coordinates.
+message GeoPoint {
+  double latitude = 1;
+  double longitude = 2;
+}
+
+// * Stores a human-readable location label for operational and compliance views.
+message LocationDescription {
+  optional string city = 1;
+  optional string subdivision_code = 2;
+  optional string country_code = 3;
+  optional string description = 4;
+}
+
+// * Combines coordinates with an optional human-readable description.
+message GeoLocation {
+  GeoPoint point = 1;
+  optional LocationDescription description = 2;
+}

package/proto/common/primitives/time.proto

@@ -0,0 +1,24 @@
+syntax = "proto3";
+
+package openeld.common.primitives.v1;
+
+import "google/protobuf/duration.proto";
+import "google/protobuf/timestamp.proto";
+
+// * Represents a calendar date without a timezone.
+message LocalDate {
+  int32 year = 1;
+  int32 month = 2;
+  int32 day = 3;
+}
+
+// * Represents a bounded time window.
+message TimeRange {
+  google.protobuf.Timestamp start_time = 1;
+  optional google.protobuf.Timestamp end_time = 2;
+}
+
+// * Represents a duration summary using protobuf's cross-language duration type.
+message DurationValue {
+  google.protobuf.Duration value = 1;
+}

package/proto/common/units/measurements.proto

@@ -0,0 +1,28 @@
+syntax = "proto3";
+
+package openeld.common.units.v1;
+
+// * Stores a normalized distance measurement in meters.
+message Distance {
+  double meters = 1;
+}
+
+// * Stores a normalized speed measurement in kilometers per hour.
+message Speed {
+  double kilometers_per_hour = 1;
+}
+
+// * Stores a normalized compass heading in degrees.
+message Heading {
+  double degrees = 1;
+}
+
+// * Stores a normalized odometer reading in meters.
+message OdometerReading {
+  double meters = 1;
+}
+
+// * Stores a normalized engine-hour reading in seconds.
+message EngineHours {
+  double seconds = 1;
+}

package/proto/logistics/asset.proto

@@ -0,0 +1,24 @@
+syntax = "proto3";
+
+package openeld.logistics.v1;
+
+import "common/metadata/audit.proto";
+import "common/metadata/source.proto";
+import "logistics/enums.proto";
+
+// * Represents a non-powered or auxiliary asset such as a trailer or chassis.
+message Asset {
+  string asset_id = 1;
+  string carrier_id = 2;
+  AssetType asset_type = 3;
+  string asset_number = 4;
+  optional string vin = 5;
+  optional string make = 6;
+  optional string model = 7;
+  optional int32 year = 8;
+  optional string license_plate = 9;
+  optional string license_state = 10;
+  AssetStatus status = 11;
+  optional openeld.common.metadata.v1.SourceRecord source = 20;
+  optional openeld.common.metadata.v1.AuditMetadata audit = 21;
+}