table.supported-providers {
  width: 100%;
}

table.supported-providers th,
table.supported-providers td {
  white-space: nowrap;
}

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 {
  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;
}


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()]);


API Reference

Website

Product Roadmap

Terminal

Get Started

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

Get Current Connection

ConnectionId

Enum values:
- `connected`: active and authenticated connection
- `disconnected`: connection is no longer authenticated - please ask your user to link the account again
- `archived`: connection has been archived from view - attempts to re-connect will cause us to check the connection status again

Connection Status

ErrorPathDetail

Entities in Terminal are expandable. Using the `expand` query parameter you can choose to ingest just an ID or the full entity details.

ExpandableIssue

[ISO 8601](https://www.w3.org/TR/NOTE-datetime) date

ISODateTime

IssueId

Provider Code

The ID used to represent the entity in the source system.

SourceId

An object containing the state of a sync job. This can be polled after connection linking to know when data is available for ingestion.

If the sync failed, this will contain the reason

Issues are problems encountered with a connection that did not result in a failed sync but may require manual intervention. You can see the issues for a given sync by providing `issues` to the `expand` parameter.

The earliest records to sync for those based on time (ex: historical locations and stats)

Sync

SyncId

Enum values:
- `automatic`: Terminal will keep this connections data up to date
- `manual`: Terminal will only sync data upon request

SyncMode

Authorization

The connection your application has with your customer's TSP.

Overview

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

Intro to Terminal

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

Supported Providers

Authentication

Resource Expansion

Terminal provides a sandbox and production environment for you to test and launch your integration with our Unified APIs. The sandbox environment is built to resemble our production environment as much as possible while being limited to mock data.

Environments

Syncing Data

Terminal enforces API Rate Limits to protect against traffic spikes impacting our system and other Terminal customers.

Rate Limits

Pagination

Passthrough

Raw Data

Webhooks

Third Party Extensions

External IDs

Serialization

Receive detailed reports when crash events are detected across connections

Crash Reports

Follow this guide to configure an OAuth2 client for Motive integration

Motive OAuth Configuration

Here's a step-by-step guide to configure an OAuth2 client for Samsara

Samsara OAuth Configuration

Terminal Telematics API

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 trips in the connected account. Trips define a period of time where a vehicle is in motion.

List Trips

List all devices in the connected account.

List Devices

List all safety events detected by the provider.

List Safety Events

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

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

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. This can occur either by creating a new connection or by merging with an existing connection to avoid duplicates. Subscribing to this event allows you to receive details of any successful authentication along with the resulting connection information.

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.

API Reference

Authentication

Vehicles

Drivers

Hours of Service

Trips

Devices

Safety

Groups

Trailers

IFTA

Connections

Data Management

Providers

Issues

Webhook Events

Get Current Connection

Authorizations

Headers

Response