table.supported-providers {
  width: 100%;
  display: unset;
  table-layout: fixed;
}

p:has(> table.supported-providers.sticky-header),
p:has(> table.crash-report-table.sticky-header) {
  height: 600px;
  overflow: auto;
}

table.supported-providers.sticky-header thead tr {
  top: 0;
  position: sticky;
  z-index: 3;
  background-color: #fff;
}

.dark table.supported-providers.sticky-header thead tr {
  background-color: rgb(var(--background-dark));
}

table.supported-providers th {
  white-space: nowrap;
  text-align: left;
}

table.supported-providers td {
  white-space: normal;
  word-wrap: break-word;
  overflow: hidden;
  text-overflow: ellipsis;
}

@media (max-width: 640px) {
  table.supported-providers td {
    max-width: 200px;
  }
}

@media (min-width: 641px) and (max-width: 1024px) {
  table.supported-providers td {
    max-width: 300px;
  }
}

@media (min-width: 1025px) {
  table.supported-providers td {
    max-width: 600px;
  }
}

table.supported-providers thead th::after {
  content: '';
  position: absolute;
  left: 0;
  bottom: -1px; /* Adjust this if the scrollbar width is an issue */
  right: 0;
  height: 1px;
  background-color: #ddd;
}

.dark table.supported-providers thead th::after {
  background-color: rgb(var(--background-dark));
}

table.supported-providers th:first-of-type,
table.supported-providers td:first-of-type {
  min-width: 230px;
  position: sticky;
  left: 0;
  background-color: #fff;
  z-index: 2;
  text-align: left;
  margin-right: 1rem;
}

.dark table.supported-providers th:first-of-type,
.dark table.supported-providers td:first-of-type {
  background-color: rgb(var(--background-dark));
}

table.supported-providers th.center-text,
table.supported-providers td.center-text {
  text-align: center;
}

table.supported-providers th:first-of-type::after,
table.supported-providers td:first-of-type::after {
  content: '';
  position: absolute;
  top: 0;
  right: -1px; /* Adjust this if the scrollbar width is an issue */
  bottom: 0;
  width: 1px;
  background-color: #ddd;
}

.dark table.supported-providers th:first-of-type::after,
.dark table.supported-providers td:first-of-type::after {
  background-color: rgb(var(--background-dark));
}

table.supported-providers img,
table.crash-report-table img {
  width: 24px;
  height: 24px;
  display: inline-block;
  margin: 0;
  margin-right: 1rem;
}

table.supported-providers div a {
  text-decoration: none;
  border-bottom: none;
  font-weight: normal;
}

table.supported-providers div a:hover {
  text-decoration: underline;
}

table.crash-report-table th:first-child,
table.crash-report-table td:first-child {
  width: 900px;
  text-align: left;
}

table.crash-report-table th,
table.crash-report-table td {
  text-align: left;
}


import { bundle } from '@apidevtools/json-schema-ref-parser';
import axios from 'axios';
import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
import { readFile } from 'node:fs/promises';
import path from 'node:path';
import { dash, group } from 'radash';
import { fileURLToPath } from 'url';
import mintConfig from './mint-base.json' assert { type: 'json' };

const BASE_URL = 'https://api.withterminal.com';

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

function recursiveClean(spec) {
  if (typeof spec !== 'object' || spec === null) {
    return spec;
  }

  if (Array.isArray(spec)) {
    return spec.map(recursiveClean);
  }

  // replace anyOf with oneOf
  if ('anyOf' in spec) {
    // TODO: this is a hack to fix the spec, we should fix the spec in the source
    // we initially weren't able to use oneOf on our end when setting state
    // to null on IFTA reports so we used anyOf. Nirvana asked us to change to
    // use oneOf instead as it was more correct and didn't break their code-gen
    spec.oneOf = spec.anyOf;
    delete spec.anyOf;
  }

  if ('x-stoplight' in spec) {
    delete spec['x-stoplight'];
  }

  if ('x-internal' in spec) {
    delete spec['x-internal'];
  }

  for (const key in spec) {
    recursiveClean(spec[key]);
  }

  return spec;
}

function memo(fn) {
  let lastArg;
  let lastResult;
  return async (arg) => {
    if (arg === lastArg) {
      return lastResult;
    }

    lastArg = arg;
    lastResult = await fn(arg);
    return lastResult;
  };
}

/**
 * Removes expandable objects from the spec and replaces them with their
 * corresponding ID reference. This will make the specs easier for clients to
 * consume and generate code from without having to deal with the expandable objects.
 *
 * TODO: come up with a better way to handle expandable objects in the spec
 * would ideally want to use expand but we weren't able to get it to work with
 * ajv validation. It would also require a larger refactor to the codebase to
 * ensure we have a consistent way to handle expandable objects.
 */
function removeExpandable(spec) {
  if (typeof spec !== 'object' || spec === null) {
    return spec;
  }

  if (Array.isArray(spec)) {
    return spec.map(removeExpandable);
  }

  if ('$ref' in spec && isString(spec.$ref)) {
    const resource = spec.$ref.match(/#\/components\/schemas\/Expandable(.+)/);

    if (resource) {
      spec.$ref = `#/components/schemas/${resource[1]}Id`;
    }

    return spec;
  }

  for (const key in spec) {
    removeExpandable(spec[key]);
  }

  return spec;
}

async function readSpec() {
  const spec = await readFile(
    path.join(__dirname, '../specs/telematics.openapi.json'),
    'utf8'
  );

  return await bundle(
    JSON.parse(spec.replace(/"\$ref": "\.\//g, `"$ref": "../specs/`))
  );
}

const getSpec = memo(async ({ includeExpandable }) => {
  let spec = await readSpec();
  spec = recursiveClean(spec);
  if (!includeExpandable) {
    spec = removeExpandable(spec);
  }
  return spec;
});

const buildOperationContent = (operation) => {
  const [shortDescription, ...restDescription] = (
    operation.description ?? ''
  ).split('\n');

  const content = `---
title: "${operation.summary}"
${shortDescription ? `description: "${shortDescription}"` : ''}
openapi: "${operation.method.toUpperCase()} ${operation.path}"
---
${restDescription.join('\n').trim()}`;

  return content;
};

const buildSchemaContent = (schemaName, schema) => {
  const [shortDescription, ...restDescription] = (
    schema.description ?? ''
  ).split('\n');

  const content = `---
title: "${schema.title}"
${shortDescription ? `description: "${shortDescription}"` : ''}
openapi-schema: "${schemaName}"
---
${restDescription.join('\n').trim()}`;

  return content;
};

function cleanUpFilepath(filepath) {
  return filepath.replace('./', '').replace('.mdx', '');
}

function writeOperationDocs(operation) {
  const result = [];

  for (const tag of operation.tags ?? []) {
    const tagDir = `./api-reference/${dash(tag)}`;

    if (!existsSync(tagDir)) {
      mkdirSync(tagDir);
    }

    const filename = `${dash(operation.operationId)}.mdx`;
    const filepath = path.join(tagDir, filename);

    const isHiddenOperation =
      operation.hasOwnProperty('x-hidden') && operation['x-hidden'];

    writeFileSync(filepath, buildOperationContent(operation));

    result.push({
      tag,
      operationId: operation.operationId,
      filepath: cleanUpFilepath(filepath),
      isHiddenOperation
    });
  }

  return result;
}

function writeWebhookSchemaDocs(schemaName, schema) {
  const tagDir = `./api-reference/webhook-events`;

  if (!existsSync(tagDir)) {
    mkdirSync(tagDir);
  }

  const filename = `${dash(schemaName)}.mdx`;
  const filepath = path.join(tagDir, filename);

  writeFileSync(filepath, buildSchemaContent(schemaName, schema));

  return cleanUpFilepath(filepath);
}

async function generateReference() {
  const spec = await getSpec({ includeExpandable: true });

  if (!existsSync('./api-reference')) {
    mkdirSync('./api-reference');
  }

  writeFileSync('./terminal.openapi.json', JSON.stringify(spec, null, 2));

  const operations = Object.entries(spec.paths).flatMap(([path, methods]) =>
    Object.entries(methods).map(([method, operation]) => ({
      ...operation,
      path,
      method
    }))
  );

  const outputPages = operations.flatMap((operation) =>
    writeOperationDocs(operation)
  );

  const pagesByTag = group(outputPages, (op) => op.tag);

  const webhookEvents = Object.entries(spec.components.schemas)
    .filter(([_, schema]) => {
      if (!schema['x-tags'] || !Array.isArray(schema['x-tags'])) {
        return false;
      }

      return schema['x-tags'].includes('Webhook Events');
    })
    .map(([schemaName, schema]) => ({
      schemaName,
      type: schema.title,
      schema,
      filepath: writeWebhookSchemaDocs(schemaName, schema)
    }));

  const webhookOverviewPageFilepath =
    './api-reference/webhook-events/overview.mdx';

  const webhookOverviewPageContent = `---
title: "Event Types"
description: "Terminal sends webhook events to your server to notify you of events that happen in your Terminal account."
---
${webhookEvents
  .map(({ type, filepath }) => `- [${type}](/${filepath})`)
  .join('\n')}
`;

  writeFileSync(webhookOverviewPageFilepath, webhookOverviewPageContent);

  const apiReferenceNavItems = Object.entries(pagesByTag)
    .map(([tag, operations]) => ({
      group: tag,
      pages: operations
        .filter((op) => !op.isHiddenOperation)
        .map(({ filepath }) => filepath)
    }))
    .filter(({ pages }) => pages.length > 0);

  const outputConfig = {
    ...mintConfig,
    navigation: mintConfig.navigation.concat(apiReferenceNavItems).concat([
      {
        group: 'Webhook Events',
        pages: [
          cleanUpFilepath(webhookOverviewPageFilepath),
          ...webhookEvents.map(({ filepath }) => filepath)
        ]
      }
    ])
  };

  writeFileSync('mint.json', JSON.stringify(outputConfig));

  console.log('API Reference generated!');
}

function pascalToCapitalCase(str) {
  // add a space before all caps unless it's an acronym
  return str.replace(/([A-Z][a-z])/g, ' $1').trim();
}

function statusIcon(status) {
  switch (status) {
    case 'supported':
      return '🟢';
    case 'not_supported_by_terminal':
      return '🌕';
    case 'not_supported_by_provider':
      return '🔴';

    default:
      throw new Error(`Unknown status: ${status}`);
  }
}

function formatTable(
  rows,
  options = {
    centerData: false
  }
) {
  const columns = Array.from(new Set(rows.flatMap((row) => Object.keys(row))));

  const table = `
<table className="supported-providers"><thead><tr>${columns
    .map(
      (heading, index) =>
        `<th className="${
          index > 0 && options.centerData ? 'center-text' : ''
        }">${heading}</th>`
    )
    .join('')}</tr></thead><tbody>${rows
    .map(
      (row) =>
        `<tr>${columns
          .map(
            (cell, index) =>
              `<td className="${
                index > 0 && options.centerData ? 'center-text' : ''
              }">${row[cell] ?? '-'}</td>`
          )
          .join('')}</tr>`
    )
    .join('')}</tbody></table>
  `.trim();

  return table;
}

function buildSupportedModelsTable(data) {
  const rows = data.map((row) => {
    const { name, icon, supportedModels } = row;

    const support = Object.entries(supportedModels).reduce(
      (acc, [model, modelSupport]) => {
        return {
          ...acc,
          [pascalToCapitalCase(model)]: statusIcon(
            modelSupport.supportedOperations.read
          ),
          ...(model === 'VehicleLocation' && {
            'Historical Locations': modelSupport.availableHistory ? '🟢' : '🔴'
          })
        };
      },
      {}
    );

    return {
      Provider: `<div><img src="${icon}" alt="${name}" /><span>${name}</span></div>`,
      ...support
    };
  });

  return formatTable(rows, { centerData: true });
}

function buildAvailableHistoryTable(data) {
  const rows = data.map((row) => {
    const { name, icon, supportedModels } = row;
    return {
      Provider: `<div><img src="${icon}" alt="${name}" /><span>${name}</span></div>`,
      'Available History':
        supportedModels.VehicleLocation.availableHistory ?? '*Not Supported*'
    };
  });

  return formatTable(rows);
}

function buildSafetyEventsTable(data) {
  const rows = data.map((row) => {
    const { name, icon, supportedModels } = row;
    return {
      Provider: `<div><img src="${icon}" alt="${name}" /><span>${name}</span></div>`,
      ...supportedModels.SafetyEvent.types.reduce((acc, type) => {
        return {
          ...acc,
          ['`' + type + '`']: '✅'
        };
      }, {})
    };
  });

  return formatTable(rows, { centerData: true });
}

function buildSampleRateTable(data) {
  const rows = data.map((row) => {
    const { name, icon, supportedModels } = row;
    return {
      Provider: `<div><img src="${icon}" alt="${name}" /><span>${name}</span></div>`,
      'Sample Rate': supportedModels.VehicleLocation.sampleRate
    };
  });

  return formatTable(rows);
}

async function generateProviderReference() {
  const allProviders = await axios(`${BASE_URL}/tsp/v1/providers`).then(
    (res) => res.data
  );

  const liveProviders = allProviders.filter((p) => p.status === 'live');

  writeFileSync(
    '_snippets/supported-providers-table.mdx',
    buildSupportedModelsTable(liveProviders)
  );

  writeFileSync(
    '_snippets/supported-history.mdx',
    buildAvailableHistoryTable(liveProviders)
  );

  writeFileSync(
    '_snippets/supported-safety-events.mdx',
    buildSafetyEventsTable(liveProviders)
  );

  writeFileSync(
    '_snippets/supported-sample-rate.mdx',
    buildSampleRateTable(liveProviders)
  );

  console.log('Provider Reference generated!');
}

Promise.all([generateReference(), generateProviderReference()]);


Documentation for Terminal's common model schemas.

Overview

Terminal

Let's introduce you to some key features and concepts of the Terminal API.

How Terminal Works

Here's a step-by-step guide to get started integrating telematics data with Terminal.

Getting Started

Terminal provides a hosted 'Link' that makes it easy to authenticate with any telematics provider. With only a few steps you will be able to provide customers/partners an easy self-serve flow to connect their telematics account.

Link Component

Terminal provides SDKs to make it easy to integrate with your application.

Published SDKs

Syncing Data

Vehicle & Driver Filtering

Learn what duplicate connections are and best practices for handling them.

Duplicate Connections

Learn how to configure automated data replication to Amazon S3

AWS S3 Destination

Test your telematics integrations with Terminal's API

Sandbox Environment

Custom Identifiers

Timestamps

Passthrough

Raw Data

Webhooks

Third Party Extensions

Receive detailed reports when crash events are detected across connections

Crash Reports

Receive notifications for key events through your individual account

User Notifications

Access live telematics data from providers through Terminal

Real-Time Data

Terminal polls and caches real-time data from providers

Managed Polling

Environments

Authentication

Rate Limits

Resource Expansion

Pagination

Serialization

Exchange the `publicToken` returned by our hosted authentication flow for a long lived connection token that will be used when requesting data from a customer's TSP.

Public Token Exchange

List all of the vehicles in the connected account

List Vehicles

Get Vehicle

List the latest location of the vehicles in the connected account.

Latest Vehicle Locations

List the historical breadcrumb locations for a vehicle.

Historical Vehicle Locations

List historical stats and logs about the vehicle.

Historical Vehicle Stats

List all of the drivers in the connected account

List Drivers

Get Driver

List available time for the driver. This endpoint provides live access to the driver's available time. Different than most endpoints, this endpoint calls the provider's API in real time to get the latest available time for the driver. This endpoint is useful for building real time applications that need to know the driver's available time.

Available Time for Drivers

List all hours of service logs. Currently, HOS logs are tracked as the distinct changes in duty status. In the future we will be offering endpoints to expose current HOS status and historical daily summaries.

List HOS Logs

List daily summary of hours of service. Each daily log represents the time a driver spent in each duty status for a given day.

List HOS Daily Logs

List all historical trips in the connected account. Trips define a period of time where a vehicle is in motion.

List Historical Trips

List all devices in the connected account.

List Devices

List all safety events detected by the provider.

List Safety Events

Get Safety Event

Get camera media for a given safety event.

Get Event Camera Media

List Groups

List Trailers

Latest Trailer Locations

Get all vehicle IFTA reports for the requested time span.

Get IFTA Summary

List all of the connections you have for your application. Connections represent the authenticated access you have to your customer's TSP data.

List All Connections

Get the details of the current active connection. The current connection is derived from the provided connection token.

Get Current Connection

Update the details of the current active connection. The current connection is derived from the provided connection token.

Update Current Connection

Manually request to sync the current connections data.

Request Sync

List a log of all batch sync jobs for the current connection.

List Sync History

Get Sync Job Status

Retry a failed sync job with the same parameters. This is useful for retrying syncs that failed due to temporary issues.

Retry Sync

Cancel a sync job mid-way through. This is useful for cancelling syncs that are no longer needed. Cancelled syncs will be marked as failed and can be retried.

Cancel Sync

Make an authenticated request to the underlying telematics provider. 

Retrieve a list of the providers Terminal supports. This endpoint will grow to include additional details about the supported capabilities of each provider.

List Providers

List all issues that have been observed by Terminal.

List Issues

Mark an issue's status as `resolved` until the issue is observed again.

Resolve Issue

Terminal sends webhook events to your server to notify you of events that happen in your Terminal account.

Event Types

Emitted when a connection is succesfully created with a provider account.

connection.created

Emitted when a connection is disconnected. This typically happens if credentials are deemed invalid and the user must re-authenticate.

connection.disconnected

Emitted when a connection is succesfully reconnected. This should happen when a customer re-authenticates after being disconnected.

connection.reconnected

This event is emitted when a user successfully completes the authentication process.

connection.completed

Emitted when a connection's details are updated.

connection.updated

Emitted when a connection sync has been requested and is queued to run.

sync.requested

Emitted when a connection sync has started running.

sync.started

Emitted when a connection sync completes successfully.

sync.completed

Emitted when a connection sync has failed to complete successfully.

sync.failed

Emitted when a connection's first successful sync completes.

connection.first_sync_completed

Emitted when an issue with a connection has been reported.

issue.reported

Emitted when an issue has been manually resolved.

issue.resolved

Emitted when a customer requests an unsupported provider using our Link component.

unsupported_provider.requested

vehicle.added

vehicle.modified

vehicle.removed

driver.added

driver.modified

driver.removed

safety_event.added

safety_event.modified

Provider List

This document provides an overview of Terminal's integration with ABC ELD. It shows which data models are currently available in production and which ones are in active development.

ABC ELD

This document provides an overview of Terminal's integration with Action ELD. It shows which data models are currently available in production and which ones are in active development.

Action ELD

This document provides an overview of Terminal's integration with Advantage Knights ELD. It shows which data models are currently available in production and which ones are in active development.

Advantage Knights ELD

This document provides an overview of Terminal's integration with Advantage One. It shows which data models are currently available in production and which ones are in active development.

Advantage One

This document provides an overview of Terminal's integration with AMPM ELD. It shows which data models are currently available in production and which ones are in active development.

AMPM ELD

This document provides an overview of Terminal's integration with Apex Ultima. It shows which data models are currently available in production and which ones are in active development.

Apex Ultima

This document provides an overview of Terminal's integration with Apollo Compass. It shows which data models are currently available in production and which ones are in active development.

Apollo Compass

This document provides an overview of Terminal's integration with Apollo ELD. It shows which data models are currently available in production and which ones are in active development.

Apollo ELD

This document provides an overview of Terminal's integration with Argos Connected Solutions. It shows which data models are currently available in production and which ones are in active development.

Argos Connected Solutions

This document provides an overview of Terminal's integration with Attrix. It shows which data models are currently available in production and which ones are in active development.

Attrix

This document provides an overview of Terminal's integration with Azuga. It shows which data models are currently available in production and which ones are in active development.

Azuga

This document provides an overview of Terminal's integration with BigRoad. It shows which data models are currently available in production and which ones are in active development.

BigRoad

This document provides an overview of Terminal's integration with Bison Elog. It shows which data models are currently available in production and which ones are in active development.

Bison Elog

This document provides an overview of Terminal's integration with Black Bear. It shows which data models are currently available in production and which ones are in active development.

Black Bear

This document provides an overview of Terminal's integration with Blue Arrow Telematics. It shows which data models are currently available in production and which ones are in active development.

Blue Arrow Telematics

This document provides an overview of Terminal's integration with Blue Horse ELD. It shows which data models are currently available in production and which ones are in active development.

Blue Horse ELD

This document provides an overview of Terminal's integration with Blue Ink Tech. It shows which data models are currently available in production and which ones are in active development.

Blue Ink Tech

This document provides an overview of Terminal's integration with Captain ELD. It shows which data models are currently available in production and which ones are in active development.

Captain ELD

This document provides an overview of Terminal's integration with ClearPathGPS. It shows which data models are currently available in production and which ones are in active development.

ClearPathGPS

This document provides an overview of Terminal's integration with Cobra ELD. It shows which data models are currently available in production and which ones are in active development.

Cobra ELD

This document provides an overview of Terminal's integration with Columbus ELD. It shows which data models are currently available in production and which ones are in active development.

Columbus ELD

This document provides an overview of Terminal's integration with Conti-GO. It shows which data models are currently available in production and which ones are in active development.

Conti-GO

This document provides an overview of Terminal's integration with Daily ELD. It shows which data models are currently available in production and which ones are in active development.

Daily ELD

This document provides an overview of Terminal's integration with DFL ELD. It shows which data models are currently available in production and which ones are in active development.

DFL ELD

This document provides an overview of Terminal's integration with Digital ELD. It shows which data models are currently available in production and which ones are in active development.

Digital ELD

This document provides an overview of Terminal's integration with Dream ELD. It shows which data models are currently available in production and which ones are in active development.

Dream ELD

This document provides an overview of Terminal's integration with DY ELD. It shows which data models are currently available in production and which ones are in active development.

DY ELD

This document provides an overview of Terminal's integration with Eagle Wireless. It shows which data models are currently available in production and which ones are in active development.

Eagle Wireless

This document provides an overview of Terminal's integration with Egreen ELD. It shows which data models are currently available in production and which ones are in active development.

Egreen ELD

This document provides an overview of Terminal's integration with ELD Books. It shows which data models are currently available in production and which ones are in active development.

ELD Books

This document provides an overview of Terminal's integration with ELD Connection. It shows which data models are currently available in production and which ones are in active development.

ELD Connection

This document provides an overview of Terminal's integration with ELD for You. It shows which data models are currently available in production and which ones are in active development.

ELD for You

This document provides an overview of Terminal's integration with ELD Mandate HOS. It shows which data models are currently available in production and which ones are in active development.

ELD Mandate HOS

This document provides an overview of Terminal's integration with ELD Mandate Plus. It shows which data models are currently available in production and which ones are in active development.

Common Models