@tracktile/sdk

v0.4.0

Published

a month ago

TypeScript SDK for the Tracktile API.

Downloads

0High
0Medium
0Low

jarredkenny

@tracktile/sdk

TypeScript SDK for the Tracktile API.

Note: This package is auto-generated by Speakeasy from our OpenAPI specification.

Installation

npm install @tracktile/sdk
# or
pnpm add @tracktile/sdk
# or
yarn add @tracktile/sdk

Usage

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

const client = new Tracktile({
  bearerAuth: "your-api-token",
  serverURL: "https://api.tracktile.io", // optional
});

// List products
const products = await client.products.list({
  page: 1,
  limit: 20,
});

// Create an order
const order = await client.orders.create({
  customerId: "cust_123",
  lineItems: [
    { productId: "prod_456", quantity: 10 },
  ],
});

Authentication

The SDK uses Bearer token authentication. Obtain an API token from your Tracktile dashboard.

Development

This SDK is regenerated automatically when the OpenAPI spec changes. Do not edit generated files directly.

To regenerate locally:

speakeasy run --target typescript

Summary

@tracktile/sdk

SDK Installation

[!TIP] To finish publishing your SDK to npm and others you must run your first generation action.

The SDK can be installed with either npm, pnpm, bun or yarn package managers.

NPM

npm add <UNSET>

PNPM

pnpm add <UNSET>

Bun

bun add <UNSET>

Yarn

yarn add <UNSET>

[!NOTE] This package is published as an ES Module (ESM) only. For applications using CommonJS, use await import() to import and use this package.

Requirements

For supported JavaScript runtimes, please consult RUNTIMES.md.

SDK Example Usage

Example

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

const tracktile = new Tracktile();

async function run() {
  const result = await tracktile.inventory.receive({
    jwt: "<YOUR_BEARER_TOKEN_HERE>",
  }, {
    locationId: "loc_01H5QXYZ123456789ABCDEF",
    items: [],
    note: "Received from supplier delivery #12345",
  });

  console.log(result);
}

run();

Authentication

Per-Client Security Schemes

This SDK supports the following security scheme globally:

| Name | Type | Scheme | | ----- | ---- | ----------- | | jwt | http | HTTP Bearer |

To authenticate with the API the jwt parameter must be set when initializing the SDK client instance. For example:

Per-Operation Security Schemes

Some operations in this SDK require the security scheme to be specified at the request level. For example:

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

const tracktile = new Tracktile();

async function run() {
  const result = await tracktile.inventory.receive({}, {
    locationId: "loc_01H5QXYZ123456789ABCDEF",
    items: [],
    note: "Received from supplier delivery #12345",
  });

  console.log(result);
}

run();

Available Resources and Operations

Carriers

list - List Carriers
create - Create Carrier
get - Get Carrier Details
update - Update Carrier
delete - Delete Carrier

Customers

listCustomers - List Customers
createCustomer - Create Customer
getCustomerById - Get Customer Details
updateCustomer - Update Customer
deleteCustomer - Delete Customer

Forms

list - List Forms
create - Create Form
get - Get Form Details
update - Update Form
delete - Delete Form

Inventory

receive - Receive Inventory
move - Move Inventory
update - Update Entity
waste - Waste Inventory
assign - Assign Entity
unassign - Unassign Entity
bundle - Bundle Entities
merge - Merge Entities
unmerge - Unmerge Entity

Orders

list - List Orders
create - Create Order
get - Get Order Details
update - Update Order
delete - Delete Order
getProductAttributes - Get Order Product Attributes

Products

get - Get Product Details
update - Update Product
delete - Delete Product
list - List Products
create - Create Product
batchUpdate - Batch Update Products
fetchByIds - Fetch Products by IDs

PurchaseOrders

list - List Purchase Orders
create - Create Purchase Order
get - Get Purchase Order Details
update - Update Purchase Order
delete - Delete Purchase Order

Recipes

list - List Recipes
create - Create Recipe
get - Get Recipe Details
update - Update Recipe
delete - Delete Recipe
getEntitiesForInput - Get Entities for Recipe Input

Shipments

list - List Shipments
create - Create Shipment
get - Get Shipment Details
update - Update Shipment
patch - Patch Shipment
delete - Delete Shipment
getByOrder - Get Shipments For Order
getItems - Get Shipment Items
getCapturedEntities - Get Captured Entities and Nodes
completeShipmentSync - Complete Shipment Synchronously (Test Only)

Suppliers

list - List Suppliers
create - Create Supplier
get - Get Supplier Details
update - Update Supplier
delete - Delete Supplier
getDefaultOrder - Get Supplier Default Order

Standalone functions

All the methods listed above are available as standalone functions. These functions are ideal for use in applications running in the browser, serverless runtimes or other environments where application bundle size is a primary concern. When using a bundler to build your application, all unused functionality will be either excluded from the final bundle or tree-shaken away.

To read more about standalone functions, check FUNCTIONS.md.

carriersCreate - Create Carrier
carriersDelete - Delete Carrier
carriersGet - Get Carrier Details
carriersList - List Carriers
carriersUpdate - Update Carrier
customersCreateCustomer - Create Customer
customersDeleteCustomer - Delete Customer
customersGetCustomerById - Get Customer Details
customersListCustomers - List Customers
customersUpdateCustomer - Update Customer
formsCreate - Create Form
formsDelete - Delete Form
formsGet - Get Form Details
formsList - List Forms
formsUpdate - Update Form
inventoryAssign - Assign Entity
inventoryBundle - Bundle Entities
inventoryMerge - Merge Entities
inventoryMove - Move Inventory
inventoryReceive - Receive Inventory
inventoryUnassign - Unassign Entity
inventoryUnmerge - Unmerge Entity
inventoryUpdate - Update Entity
inventoryWaste - Waste Inventory
ordersCreate - Create Order
ordersDelete - Delete Order
ordersGet - Get Order Details
ordersGetProductAttributes - Get Order Product Attributes
ordersList - List Orders
ordersUpdate - Update Order
productsBatchUpdate - Batch Update Products
productsCreate - Create Product
productsDelete - Delete Product
productsFetchByIds - Fetch Products by IDs
productsGet - Get Product Details
productsList - List Products
productsUpdate - Update Product
purchaseOrdersCreate - Create Purchase Order
purchaseOrdersDelete - Delete Purchase Order
purchaseOrdersGet - Get Purchase Order Details
purchaseOrdersList - List Purchase Orders
purchaseOrdersUpdate - Update Purchase Order
recipesCreate - Create Recipe
recipesDelete - Delete Recipe
recipesGet - Get Recipe Details
recipesGetEntitiesForInput - Get Entities for Recipe Input
recipesList - List Recipes
recipesUpdate - Update Recipe
shipmentsCompleteShipmentSync - Complete Shipment Synchronously (Test Only)
shipmentsCreate - Create Shipment
shipmentsDelete - Delete Shipment
shipmentsGet - Get Shipment Details
shipmentsGetByOrder - Get Shipments For Order
shipmentsGetCapturedEntities - Get Captured Entities and Nodes
shipmentsGetItems - Get Shipment Items
shipmentsList - List Shipments
shipmentsPatch - Patch Shipment
shipmentsUpdate - Update Shipment
suppliersCreate - Create Supplier
suppliersDelete - Delete Supplier
suppliersGet - Get Supplier Details
suppliersGetDefaultOrder - Get Supplier Default Order
suppliersList - List Suppliers
suppliersUpdate - Update Supplier

Retries

Some of the endpoints in this SDK support retries. If you use the SDK without any configuration, it will fall back to the default retry strategy provided by the API. However, the default retry strategy can be overridden on a per-operation basis, or across the entire SDK.

To change the default retry strategy for a single API call, simply provide a retryConfig object to the call:

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

const tracktile = new Tracktile();

async function run() {
  const result = await tracktile.inventory.receive({
    jwt: "<YOUR_BEARER_TOKEN_HERE>",
  }, {
    locationId: "loc_01H5QXYZ123456789ABCDEF",
    items: [],
    note: "Received from supplier delivery #12345",
  }, {
    retries: {
      strategy: "backoff",
      backoff: {
        initialInterval: 1,
        maxInterval: 50,
        exponent: 1.1,
        maxElapsedTime: 100,
      },
      retryConnectionErrors: false,
    },
  });

  console.log(result);
}

run();

If you'd like to override the default retry strategy for all operations that support retries, you can provide a retryConfig at SDK initialization:

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

const tracktile = new Tracktile({
  retryConfig: {
    strategy: "backoff",
    backoff: {
      initialInterval: 1,
      maxInterval: 50,
      exponent: 1.1,
      maxElapsedTime: 100,
    },
    retryConnectionErrors: false,
  },
});

async function run() {
  const result = await tracktile.inventory.receive({
    jwt: "<YOUR_BEARER_TOKEN_HERE>",
  }, {
    locationId: "loc_01H5QXYZ123456789ABCDEF",
    items: [],
    note: "Received from supplier delivery #12345",
  });

  console.log(result);
}

run();

Error Handling

TracktileError is the base class for all HTTP error responses. It has the following properties:

| Property | Type | Description | | ------------------- | ---------- | --------------------------------------------------------------------------------------- | | error.message | string | Error message | | error.statusCode | number | HTTP response status code eg 404 | | error.headers | Headers | HTTP response headers | | error.body | string | HTTP body. Can be empty string if no body is returned. | | error.rawResponse | Response | Raw HTTP response | | error.data$ | | Optional. Some errors may contain structured data. See Error Classes. |

Example

import { Tracktile } from "@tracktile/sdk";
import * as errors from "@tracktile/sdk/models/errors";

const tracktile = new Tracktile();

async function run() {
  try {
    const result = await tracktile.inventory.receive({
      jwt: "<YOUR_BEARER_TOKEN_HERE>",
    }, {
      locationId: "loc_01H5QXYZ123456789ABCDEF",
      items: [],
      note: "Received from supplier delivery #12345",
    });

    console.log(result);
  } catch (error) {
    // The base class for HTTP error responses
    if (error instanceof errors.TracktileError) {
      console.log(error.message);
      console.log(error.statusCode);
      console.log(error.body);
      console.log(error.headers);

      // Depending on the method different errors may be thrown
      if (error instanceof errors.FourHundredError) {
        console.log(error.data$.status); // number
        console.log(error.data$.message); // string
      }
    }
  }
}

run();

Error Classes

Primary errors:

TracktileError: The base class for HTTP error responses.
- FourHundredError: Bad Request Error. Status code 400.
- FourHundredAndOneError: Unauthorized. Status code 401.
- FourHundredAndThreeError: Forbidden. Status code 403.
- FiveHundredError: Internal Server Error. Status code 500.

Network errors:

ConnectionError: HTTP client was unable to make a request to a server.
RequestTimeoutError: HTTP request timed out due to an AbortSignal signal.
RequestAbortedError: HTTP request was aborted by the client.
InvalidRequestError: Any input used to create a request is invalid.
UnexpectedClientError: Unrecognised or unexpected error.

Inherit from TracktileError:

ResponseValidationError: Type mismatch between the data returned from the server and the structure expected by the SDK. See error.rawValue for the raw value and error.pretty() for a nicely formatted multi-line string.

Server Selection

Override Server URL Per-Client

The default server can be overridden globally by passing a URL to the serverURL: string optional parameter when initializing the SDK client instance. For example:

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

const tracktile = new Tracktile({
  serverURL: "https://api.tracktile.io",
});

async function run() {
  const result = await tracktile.inventory.receive({
    jwt: "<YOUR_BEARER_TOKEN_HERE>",
  }, {
    locationId: "loc_01H5QXYZ123456789ABCDEF",
    items: [],
    note: "Received from supplier delivery #12345",
  });

  console.log(result);
}

run();

Custom HTTP Client

The TypeScript SDK makes API calls using an HTTPClient that wraps the native Fetch API. This client is a thin wrapper around fetch and provides the ability to attach hooks around the request lifecycle that can be used to modify the request or handle errors and response.

The HTTPClient constructor takes an optional fetcher argument that can be used to integrate a third-party HTTP client or when writing tests to mock out the HTTP client and feed in fixtures.

The following example shows how to:

route requests through a proxy server using undici's ProxyAgent
use the "beforeRequest" hook to add a custom header and a timeout to requests
use the "requestError" hook to log errors

import { Tracktile } from "@tracktile/sdk";
import { ProxyAgent } from "undici";
import { HTTPClient } from "@tracktile/sdk/lib/http";

const dispatcher = new ProxyAgent("http://proxy.example.com:8080");

const httpClient = new HTTPClient({
  // 'fetcher' takes a function that has the same signature as native 'fetch'.
  fetcher: (input, init) =>
    // 'dispatcher' is specific to undici and not part of the standard Fetch API.
    fetch(input, { ...init, dispatcher } as RequestInit),
});

httpClient.addHook("beforeRequest", (request) => {
  const nextRequest = new Request(request, {
    signal: request.signal || AbortSignal.timeout(5000)
  });

  nextRequest.headers.set("x-custom-header", "custom value");

  return nextRequest;
});

httpClient.addHook("requestError", (error, request) => {
  console.group("Request Error");
  console.log("Reason:", `${error}`);
  console.log("Endpoint:", `${request.method} ${request.url}`);
  console.groupEnd();
});

const sdk = new Tracktile({ httpClient: httpClient });

Debugging

You can setup your SDK to emit debug logs for SDK requests and responses.

You can pass a logger that matches console's interface as an SDK option.

[!WARNING] Beware that debug logging will reveal secrets, like API tokens in headers, in log messages printed to a console or files. It's recommended to use this feature only during local development and not in production.

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

const sdk = new Tracktile({ debugLogger: console });

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@tracktile/sdk

Installation

Usage

Authentication

Development

Summary

Table of Contents

SDK Installation

NPM

PNPM

Bun

Yarn

Requirements

SDK Example Usage

Example

Authentication

Per-Client Security Schemes

Per-Operation Security Schemes

Available Resources and Operations

Standalone functions

Retries

Error Handling

Example

Error Classes

Server Selection

Override Server URL Per-Client

Custom HTTP Client

Debugging