TypeScript SDK

The package ships CommonJS and ES module builds with full type definitions, and every operation is also available as a standalone, tree shakeable function. RUNTIMES.md lists the supported JavaScript runtimes.

Installation

npm add @kintsugi-tax/tax-platform-sdk

Authentication

The API authenticates with an API key header. Create a key in the Kintsugi app (see Creating and managing API keys), pass it once when you construct the client, and every call that accepts it is authenticated:

import { SDK } from "@kintsugi-tax/tax-platform-sdk";

const sdk = new SDK({
  security: {
    apiKeyHeader: "<YOUR_API_KEY_HERE>",
  },
});

async function run() {
  const result = await sdk.customers.get({
    customerId: "cust_abc123",
  });

  console.log(result);
}

run();

Making a request

Arguments are camelCased and request bodies are plain objects, fully typed, so your editor completes each field and the compiler catches the rest:

import { SDK } from "@kintsugi-tax/tax-platform-sdk";

const sdk = new SDK({
  security: { apiKeyHeader: process.env.KINTSUGI_API_KEY ?? "" },
});

const result = await sdk.customers.create({
  name: "Jane Smith",
  email: "jane.smith@example.com",
  externalId: "cust_002",
  street1: "456 Elm St",
  city: "Metropolis",
  state: "NY",
  postalCode: "10001",
  country: "US",
  status: "ACTIVE",
});

console.log(result);

For the exact call on any endpoint, including arguments, enums and the type it returns, open that endpoint in the API reference and select the TypeScript tab.

Tree-shaking with standalone functions

Each method is also exported as a standalone function taking an SDKCore, so a bundle ships only the operations it actually calls:

import { SDKCore } from "@kintsugi-tax/tax-platform-sdk/core.js";
import { customersList } from "@kintsugi-tax/tax-platform-sdk/funcs/customersList.js";

const sdk = new SDKCore({
  security: { apiKeyHeader: process.env.KINTSUGI_API_KEY ?? "" },
});

const res = await customersList(sdk, { page: 1, size: 50 });
if (res.ok) {
  console.log(res.value);
} else {
  console.error(res.error);
}

Standalone functions return a result object instead of throwing, which suits code that would rather branch than catch.

Error handling

SDKError is the base class for HTTP error responses. It carries message, statusCode, headers, body and rawResponse, and some errors also carry parsed data:

import { SDK } from "@kintsugi-tax/tax-platform-sdk";
import * as errors from "@kintsugi-tax/tax-platform-sdk/models/errors";

const sdk = new SDK({
  security: { apiKeyHeader: process.env.KINTSUGI_API_KEY ?? "" },
});

try {
  const result = await sdk.customers.get({ customerId: "cust_abc123" });
  console.log(result);
} catch (error) {
  if (error instanceof errors.SDKError) {
    console.error(error.statusCode, error.message, error.body);
  }
  throw error;
}

Operations declare their own error types for validation failures, such as errors.BackendSrcCustomersResponsesValidationErrorResponse for a 422. Each method's error table is in the SDK's docs.

Error handling covers what the API returns and when a retry is worthwhile.

Retries

Transient failures are retried with backoff. Configure it per call, or once for the whole client:

import { SDK } from "@kintsugi-tax/tax-platform-sdk";

const sdk = new SDK({
  security: { apiKeyHeader: process.env.KINTSUGI_API_KEY ?? "" },
  retryConfig: {
    strategy: "backoff",
    backoff: {
      initialInterval: 1,
      maxInterval: 50,
      exponent: 1.1,
      maxElapsedTime: 100,
    },
    retryConnectionErrors: false,
  },
});

Overriding the server URL

const sdk = new SDK({
  serverURL: "https://api.trykintsugi.com",
  security: { apiKeyHeader: process.env.KINTSUGI_API_KEY ?? "" },
});

Available resources

AddressValidation   search, suggest
Customers           list, create, get, update, getByExternalId,
                    getTransactions, createTransaction
Exemptions          list, create, get, uploadCertificate, getAttachments
Filings             list, get, getByRegistrationId
Nexus               listPhysical, createPhysical, updatePhysical,
                    deletePhysical, list
Products            getProductsV1ProductsGet, createProductV1ProductsPost,
                    getProductCategoriesV1ProductsCategoriesGet, get, update
Registrations       get, create, getById, update, deregister
TaxEstimation       estimate
Transactions        get, create, getByExternalId, update, getById,
                    getByFilingId, createCreditNote, updateCreditNote