typescript-sdk

Terminal49 TypeScript SDK

Typed, server-side client for the Terminal49 JSON:API, built with openapi-fetch, generated OpenAPI types, and JSONA deserialization. Can be used standalone or inside the MCP server.

Installation

# install from npm (recommended)
npm install @terminal49/sdk

# or inside this repo
cd sdks/typescript-sdk
npm install

Usage

import { Terminal49Client } from '@terminal49/sdk';

const client = new Terminal49Client({ apiToken: process.env.T49_API_TOKEN! });
const container = await client.getContainer('container-uuid', ['shipment']);
console.log(container); // raw JSON:API document

// Optional: deserialize JSON:API to plain objects
const simplified = client.deserialize<any>(container);

Guide

For a full walkthrough (track a container, list shipments, pull events, and routing), see the SDK quickstart in the docs site: docs/api-docs/getting-started/sdk-quickstart.mdx.

Methods

• search(query)
• getContainer(id, include?)
• trackContainer({ containerNumber?, bookingNumber?, billOfLading?, scac?, refNumbers? }): sends request_type container, booking_number, or bill_of_lading to match the number you pass
• createTrackingRequest({ requestType, requestNumber, scac?, refNumbers?, shipmentTags? })
• inferTrackingNumber(number)
• createTrackingRequestFromInfer(number, { scac?, numberType?, refNumbers?, shipmentTags? })
• getShipment(id, includeContainers?)
• listShipments(filters?, options?)
• listContainers(filters?, options?)
• listTrackingRequests(filters?, options?) / listTrackRequests(filters?, options?)
• getContainerTransportEvents(id)
• getContainerRoute(id, options?): the route from GET /containers/{id}/map_geojson (Routing Data feature). By default (format: 'raw') it returns the GeoJSON FeatureCollection. With { format: 'mapped' } it returns { ports, currentVessel, totalPorts }, with ports in route order.
• getVesselFuturePositions(id, { portId, previousPortId })
• getVesselFuturePositionsWithCoords(id, { portId, previousPortId, latitude, longitude })
• listShippingLines(search?)
• listWebhooks(options?), getWebhook(id), createWebhook(payload), updateWebhook(id, payload), deleteWebhook(id), getWebhookIps()
• listWebhookEvents(): the event names a webhook can subscribe to
• triggerWebhook({ url, event, secret?, documentType? }): sends a test delivery with an example payload
• listWebhookNotifications(options?), getWebhookNotification(id, options?), getWebhookNotificationExamples(event)
• getVessel(id), getVesselByImo(imo), getPort(id), getTerminal(id), getMetroArea(id)
• listParties(options?), getParty(id), createParty(attributes), updateParty(id, attributes)
• listCustomFieldDefinitions(options?), getCustomFieldDefinition(id), createCustomFieldDefinition(payload), updateCustomFieldDefinition(id, payload), deleteCustomFieldDefinition(id)
• listCustomFieldOptions(definitionId, options?), getCustomFieldOption(definitionId, optionId), createCustomFieldOption(definitionId, payload), updateCustomFieldOption(definitionId, optionId, payload), deleteCustomFieldOption(definitionId, optionId)
• listCustomFields(options?), getCustomField(id), createCustomField(payload), updateCustomField(id, payload), deleteCustomField(id)
• getDemurrage(containerId) (helper)
• getRailMilestones(containerId) (helper)
• deserialize<T>(document) → JSONA-based plain objects

Some methods exist only on a resource namespace, for example containers.update(id, attrs), shippingLines.get(id), the per-entity custom field methods (containers, shipments, trackingRequests), the party role methods (containers, shipments), and the documents, emailSubmissions, and documentSchemas methods. See docs/sdk/methods.mdx for the full list.

Trade intelligence

client.tradeIntel covers US import bill-of-lading records (US Customs manifests), January 2022 onward. Methods return the API's plain JSON body and throw FeatureNotEnabledError when the account lacks the feature.

• tradeIntel.meta()
• tradeIntel.searchCompanies({ name?, imports?, state?, port_of_discharge?, origin_country?, min_containers?, limit? })
• tradeIntel.companyProfile({ company_name, company_state?, months? })
• tradeIntel.searchCommodities({ query, limit? })
• tradeIntel.topImporters({ hs4?, port_of_discharge?, origin_country?, months?, limit? })
• tradeIntel.trends({ measure?, group_by?, filters?, interval?, since?, until?, top? })
• tradeIntel.breakdown({ dims, measure?, filters?, since?, until?, top? })
• tradeIntel.lookupContainer(containerNumber)
• tradeIntel.lookupBillOfLading(bolNumber, { months? })

Examples

After building, run:

cd sdks/typescript-sdk
export T49_API_TOKEN=your_token
export T49_CONTAINER_ID=valid_container_uuid
npm run build
npm run example

example.ts prints the raw JSON:API response and a simplified view using deserialize.

Development

# Generate types from OpenAPI
npm run generate:types

# Generate Mintlify-compatible TypeDoc pages
npm run docs

# Type-check
npm run type-check

# Tests
npm test

# Lint (oxlint + oxfmt)
npm run lint

# Build
npm run build

Testing

Unit tests:

cd sdks/typescript-sdk
npm test

Type checks and lint:

cd sdks/typescript-sdk
npm run type-check
npm run lint

Smoke tests (optional, require a token):

cd sdks/typescript-sdk
export T49_API_TOKEN=your_token
export T49_API_BASE_URL=https://api.terminal49.com/v2
export T49_INFER_NUMBER=your_tracking_number
export T49_RUN_SMOKE=1
npm run smoke

Fixtures

Generate sanitized, production-based fixtures for tests:

cd sdks/typescript-sdk
export T49_API_TOKEN=your_token
export T49_API_BASE_URL=https://api.terminal49.com/v2
npm run fixtures:generate

This writes JSON:API fixtures to src/fixtures/ with redacted IDs and numbers. Numeric identifiers keep their original prefix while the last few characters are obfuscated to preserve shape without exposing real values. List endpoints are captured without include for performance guidance. Single-resource fixtures include both base and include variants where supported.

Documentation generation

The SDK uses TypeDoc with typedoc-plugin-markdown to generate Mintlify-compatible MDX pages.

cd sdks/typescript-sdk
npm run docs

Generated files are written to ../../docs/sdk/reference/ and are included in the Mintlify navigation in docs/docs.json.

From the repo root, you can also run:

npm run sdk:docs

Releasing a new version

Releases are automated via release-please.

Automated flow (default)

1. Merge PRs to main with conventional commit prefixes (feat:, fix:, docs:, chore:, etc.) that touch sdks/typescript-sdk/.
2. Release-please automatically opens a release PR that bumps package.json, updates CHANGELOG.md, and updates the manifest.
3. Merge the release PR.
4. Release-please creates a GitHub release with the sdk-v-v<version> tag.
5. The publish workflow builds, tests, and publishes to npm automatically via npm Trusted Publishing.

Manual release (fallback)

If you need to release without release-please:

1. Update CHANGELOG.md and bump version:

   cd sdks/typescript-sdk
   npm version patch   # or minor / major

   From a workspace directory, npm version updates the root package-lock.json and does not create a commit or tag.
2. Commit and push:

   git add package.json ../../package-lock.json CHANGELOG.md
   git commit -m "chore: release @terminal49/sdk v$(node -p "require('./package.json').version")"
   git push

3. Create a GitHub release with tag sdk-v<version> (e.g. sdk-v0.2.0). The publish workflow will build, test, and publish to npm via npm Trusted Publishing.

Post-release

Regenerate docs if the public API changed:

npm run sdk:docs

Notes

• Server-only: uses Node fetch (undici types) and targets Node 18+.
• Returns raw JSON:API documents by default; use deserialize for flattened objects or add your own mappers.