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: 220px;
  position: sticky;
  left: 0;
  z-index: 2;
  background-color: white;
  text-align: left;
  margin-right: 1rem;
}

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

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


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

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

Getting Started

Overview

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

Intro to Terminal

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

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

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

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

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 succesfully.

sync.completed

Emitted when a connection sync has failed to complete successfully.

sync.failed

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.

Welcome

Introduction

Terminal API Basics

Terminal Platform

Configuration

Getting Started

Video Walkthrough 🎥

Instructions ✔️

Possible Next Steps