Proud winners of the 2026 CFIN Foodtech Frontier Awards. Learn more →

TypeScript SDK

Official TypeScript SDK for the Tracktile API

#Installation

npm install @tracktile/sdk

#Quick Start

 
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

ResourceMethods
client.carrierslist, create, get, update, delete
client.customerForecastscustomers, productCustomers, trainingJob, predictions
client.customerslist, create, get, update, patch, delete, getRecentActivity
client.formslist, create, get, update, delete
client.inventoryreceive, move, make, split, adjust, update, waste, assign, unassign, bundle, merge, unmerge
client.labelslist, create, update, get, delete
client.orderslist, create, get, update, delete, getProductAttributes, getProgress
client.plansget, update, delete, list, create
client.productslinkGtin, unlinkGtin, listSupplierPlanningRules, updateSupplierPlanningRule, deleteSupplierPlanningRule, get, update, delete, list, create, batchUpdate, fetchByIds
client.purchaseOrderslist, create, get, update, delete
client.recipeslist, create, get, update, delete, getEntitiesForInput
client.shipmentslist, create, get, update, patch, delete, getByOrder, getItems, getCapturedEntities, completeSync
client.supplierslist, create, get, update, patch, delete, getDefaultOrder, getProducts
client.taskslist, get

#Error Handling

 
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
// CommonJS
const { TracktileClient } = require("@tracktile/sdk");

#Runtime Support

RuntimeVersion
Node.js18+
Deno1.39+
Bun1.0+