Migrate from raw HTTP to SDK

Use this guide when a server-side TypeScript caller currently uses raw HTTP but can import the SDK directly.

Before you start

  • Confirm the caller runs in a TypeScript runtime that can import workspace or published packages.
  • Keep HTTP when calculation belongs on the server or the caller cannot import TypeScript packages. Browser callers can use the SDK's browser-safe exports when calculation should run on their device.
  • Read Plain SDK.

Steps

  1. Replace the fetch request with an SDK helper.
  2. Replace JSON tagged values with constructors such as aud and GrossPay.
  3. Replace HTTP error envelope handling with TaxKit.safe.calculate where you need result values.
  4. Keep integration tests for the same input and expected cents.

Example

Before:

ts
const response = await fetch(
  "http://127.0.0.1:4000/api/v1/calculators/au.income-tax.annual/calculate",
  {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({
      facts: {
        taxableIncome: { _tag: "Money", cents: 9000000, currency: "AUD" },
      },
      jurisdiction: "AU",
      taxYear: "2025-26",
    }),
  }
);

const body = await response.json();

After:

ts
import { Cents, aud } from "@taxkit/core/primitives";
import { au } from "@taxkit/sdk/au";

const report = await au.incomeTax.annual({
  taxableIncome: aud(Cents.make(9_000_000)),
});

Verify the result

Both calls should produce annual tax liability of 1958800 cents for taxable income of $90,000.00 in the retained 2025–26 fixture. See the annual calculation guide for the pending Medicare threshold review and the limit on current-law claims.

Handle errors

Raw HTTP returns CalculatorApiErrorEnvelope. The SDK safe facade returns TaxKitFailure:

ts
const result = await au.incomeTax.safe.annual({
  taxableIncome: aud(Cents.make(9_000_000)),
});

if (result._tag === "TaxKitFailure") {
  console.error(result.error.message);
}

Read this page as Markdown