TypeScript SDK

Installation

npm

npm install @tracktile/sdk

pnpm

pnpm add @tracktile/sdk

yarn

yarn add @tracktile/sdk

bun

bun add @tracktile/sdk

Quick Start

import { TracktileClient, TracktileEnvironment } from "@tracktile/sdk";

const client = new TracktileClient({
  environment: TracktileEnvironment.Production,
  token: process.env.TRACKTILE_TOKEN,
});

const suppliers = await client.suppliers.list();

Authentication

Pass your API token via the token option. It is sent as a Bearer token on every request. The value may be a string or a function/promise that resolves a string, which is useful for refreshing tokens.

const client = new TracktileClient({
  environment: TracktileEnvironment.Production,
  token: "api-YOUR_TOKEN_HERE",
});

// Dynamic token (resolved per request)
const client = new TracktileClient({
  environment: TracktileEnvironment.Production,
  token: async () => await getFreshToken(),
});

Available Resources

Resource	Methods
client.carriers	list, create, get, update, delete
client.customers	list, get, getRecentActivity, create, update, patch, delete
client.forms	list, create, get, update, delete
client.inventory	receive, move, update, waste, assign, unassign, bundle, merge, unmerge
client.orders	list, create, get, update, delete, getProductAttributes
client.purchaseOrders	list, create, get, update, delete
client.recipes	list, create, get, update, delete, getEntitiesForInput
client.shipments	list, create, get, update, patch, delete, getItems, getByOrder, getCapturedEntities, completeShipmentSync
client.suppliers	list, create, get, update, patch, delete, getDefaultOrder

Error Handling

import { TracktileError } from "@tracktile/sdk";

try {
  await client.suppliers.get({ id: "invalid-id" });
} catch (error) {
  if (error instanceof TracktileError) {
    console.error(error.statusCode); // HTTP status code
    console.error(error.message);
    console.error(error.body); // Response body, if any
  }
}

TracktileTimeoutError is thrown when a request exceeds its configured timeout and is also exported from the package root.

Retries & Timeouts

Retries and timeouts are configured directly on the client options. The client retries failed requests up to maxRetries times (defaults to 2) with exponential backoff.

const client = new TracktileClient({
  environment: TracktileEnvironment.Production,
  token: process.env.TRACKTILE_TOKEN,
  maxRetries: 3,
  timeoutInSeconds: 30,
});

Both options can also be overridden per request:

await client.suppliers.list({
  maxRetries: 0,
  timeoutInSeconds: 5,
});

Custom Fetch & Headers

Provide a custom fetch implementation (for proxies, instrumentation, or runtimes without a built-in fetch) and additional default headers via the client options.

const client = new TracktileClient({
  environment: TracktileEnvironment.Production,
  token: process.env.TRACKTILE_TOKEN,
  fetch: (url, init) => {
    console.log("Request:", url);
    return fetch(url, init);
  },
  headers: {
    "X-Custom-Header": "value",
  },
});

Per-request options also accept headers, queryParams, and an abortSignal:

const controller = new AbortController();

await client.suppliers.list({
  abortSignal: controller.signal,
  headers: { "X-Request-Id": "abc123" },
});

Logging

const client = new TracktileClient({
  environment: TracktileEnvironment.Production,
  token: process.env.TRACKTILE_TOKEN,
  logging: console,
});

Module Support

@tracktile/sdk ships both CommonJS and ESM builds, so it works with import and require out of the box. TypeScript type definitions are included.

// ESM
import { TracktileClient } from "@tracktile/sdk";

// CommonJS
const { TracktileClient } = require("@tracktile/sdk");

Runtime Support

Runtime	Version
Node.js	18+
Deno	1.39+
Bun	1.0+