geotab-smart-sdk

A smart, composable Node.js SDK for the MyGeotab API, built on top of mg-api-js. Adaptive feeds, named diagnostics, two complementary trackers, group filtering, and a sandboxed playground — without locking you out of raw call() / multiCall().

Looking for the full guide, comparisons, or an interactive playground? → kunalkamble.github.io/geotab-smart-sdk

Install

npm install geotab-smart-sdk

Requires Node.js ≥ 20. The peer mg-api-js is installed automatically.

Quick start

const { GeotabSDK, Diagnostics } = require('geotab-smart-sdk');

const sdk = new GeotabSDK({
  username: '[email protected]',
  password: 'secret',
  database: 'my_company',
});

async function main() {
  await sdk.connect({ cacheDevices: true });

  // Live tracking with bearing + fuel level — one multiCall per 5s poll
  const tracker = sdk.liveTracker()
    .withDiagnostics([Diagnostics.FUEL_LEVEL])
    .withFaults()
    .pollEvery(5_000);

  tracker.on('update', (vehicles) => {
    for (const v of vehicles) {
      console.log(v.device.name, v.location.bearing, v.diagnostics);
    }
  });

  await tracker.start();
}

main().catch((err) => { console.error(err); process.exit(1); });

What's in the box

| Helper | Purpose | |---|---| | sdk.liveTracker() | Real-time tracking via DeviceStatusInfo (bearing/driver native) | | sdk.realtimeTracker() | High-fidelity tracking via LogRecord GetFeed (derives bearing/isDriving) | | sdk.history() / historyMany() / historyByGroups() | Historical GPS + diagnostics + faults + trips | | sdk.fleetSnapshot() | Whole-fleet point-in-time picture with pre-computed summary | | sdk.feeds() | Adaptive GetFeed streaming with crash-safe version tokens | | sdk.call() / sdk.multiCall() | Direct API access — auto re-auth + rate-limit retry | | Diagnostics.*, DiagnosticGroups.* | Named constants so you never type 'DiagnosticFuelLevelId' again |

Plus: session persistence (skip the password on resume), readOnly: true mode for sandboxed UIs, group filtering across every helper, and a RateLimiter that honors Retry-After.

Full documentation

Everything is on the live docs site:

• Guide — prose reference: setup, sessions, group filtering, errors, GetFeed rules, testing
• Smart SDK Inspector — interactive use cases, helper map, cheat sheet, side-by-side vs raw API
• Raw API Inspector — entity-level reference for mg-api-js users
• Compare — feature-by-feature comparison with raw mg-api-js
• Playground — exercise the SDK against your fleet with credentials you supply; runs in readOnly mode by policy

Examples

Runnable Node examples live in examples/. Each reads credentials from process.env:

export GEOTAB_USER='[email protected]'
export GEOTAB_PASS='secret'
export GEOTAB_DB='my_company'

node examples/live-tracking.js
node examples/realtime-tracking.js
node examples/historical-gps-diagnostics.js
node examples/fleet-snapshot.js
node examples/continuous-feed-sync.js

Requirements

• Node.js ≥ 20 (uses node:test + built-in coverage)
• A valid MyGeotab account
• For high-volume GetFeed, a root-group service account is recommended

Testing

npm test               # spec reporter
npm run test:watch     # dev loop
npm run test:coverage  # 84% lines, 80% branches, 75% functions

89 tests across 8 files using Node 20's built-in test runner — zero test-framework dependencies. CI gates the docs deploy on tests + lint.

Sponsor

If this SDK has saved you time, consider sponsoring on GitHub — open source, MIT licensed, maintained on personal time. A star on the repo is honestly just as appreciated. See the Sponsor page for ways to help.

License

MIT — see LICENSE.