@quaillogistics/adapters

TMS adapter library for fetching and mapping data from external TMS systems. Used internally by QUAIL Logistics.

Install

npm install @quaillogistics/adapters

Usage

Each TMS adapter is a separate subpath export. Import only what you need:

import { ThreePLClient, mapThreePLLoad } from '@quaillogistics/adapters/3pl'
import { TurvoClient } from '@quaillogistics/adapters/turvo'
import { chunkDateRange } from '@quaillogistics/adapters/common'

3PL Systems

const client = new ThreePLClient({
  apiHost: '3pl.hyperiontms.com',
  clientId: '...',
  clientSecret: '...',
  globalClientId: '...',
  globalClientSecret: '...',
})

// Layer 1: typed raw API responses
const rawLoads = await client.getLoads({ startDate, endDate })

// Layer 2: opt-in mapped intermediaries
const loads = rawLoads.map(mapThreePLLoad)

Turvo

const client = new TurvoClient({
  apiHost: 'app.turvo.com',
  username: '...',
  password: '...',
  apiKey: '...',
  clientId: '...',
  clientSecret: '...',
})

const shipment = await client.getShipment(123)

Mock mode

Every adapter supports mock: true for testing without hitting real APIs:

const client = new ThreePLClient({
  ...credentials,
  mock: true,
})

const loads = await client.getLoads({ startDate, endDate }) // deterministic test data

Observability

Pass logging callbacks to see HTTP activity:

const client = new ThreePLClient({
  ...credentials,
  onRequest: (method, path) => console.log(`>> ${method} ${path}`),
  onResponse: (method, path, status, ms) => console.log(`<< ${status} ${path} (${ms}ms)`),
})

Adapters

| Adapter | Import | Capabilities | |---------|--------|-------------| | 3PL Systems | @quaillogistics/adapters/3pl | Pull: loads, carriers, customers, contacts, commissions, AP invoices, vendor payments, tracking, documents | | Turvo | @quaillogistics/adapters/turvo | Push: shipment CRUD. Read: shipments, locations |

Development

npm install
npm run test        # run tests
npm run test:watch  # watch mode
npm run typecheck   # type check
npm run build       # build to dist/
npm run check-deps  # verify zero production dependencies

Publishing

1. Bump version in package.json
2. Commit: git commit -m "v0.1.0"
3. Tag: git tag v0.1.0
4. Push: git push && git push --tags

CI will run checks and publish to npm automatically.