# SDK reference [#sdk-reference]

Use this page when you need the stable SDK names after you have chosen an
integration path.

## Entry points [#entry-points]

| Import                  | Use                                                                                                  |
| ----------------------- | ---------------------------------------------------------------------------------------------------- |
| `@taxkit/sdk`           | Use `TaxKit.calculate`, `TaxKit.safe.calculate` and `TaxKit.createClient`.                           |
| `@taxkit/sdk/au`        | Use Australian calculator helpers such as `au.incomeTax.annual`.                                     |
| `@taxkit/sdk/effect`    | Use `calculateRunRequest`, `calculateReportRequest`, `calculateReport` and the Effect client helper. |
| `@taxkit/sdk/au/effect` | Use Australian calculation descriptors in Effect programs.                                           |
| `@taxkit/sdk/schemas`   | Import schema-facing types that are re-exported for SDK consumers.                                   |

The SDK package remains private until release approval. The public import
shape is still the developer contract used by docs and examples.

## Plain SDK [#plain-sdk]

Use `TaxKit.calculate` when you already have descriptor-typed input and want a
Promise for the report:

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

const report = await TaxKit.calculate(au.calculations.annualIncomeTax, {
  taxableIncome: aud(Cents.make(9_000_000)),
});
```

Use the AU helper when you do not need to pass the descriptor yourself:

```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)),
});
```

## Safe SDK [#safe-sdk]

Use `TaxKit.safe.calculate` when expected calculator failures should be values:

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

const result = await TaxKit.safe.calculate(au.calculations.annualIncomeTax, {
  taxableIncome: aud(Cents.make(9_000_000)),
});

if (result._tag === "TaxKitSuccess") {
  console.log(result.value.liability.cents);
}
```

## Effect SDK [#effect-sdk]

Use `calculateRunRequest` when you need a full `CalculatorRunResponse` with the
descriptor-decoded report:

```ts
import { audFromCents } from "@taxkit/core/primitives";
import { AuAnnualIncomeTaxCalculation } from "@taxkit/sdk/au/effect";
import { calculateRunRequest } from "@taxkit/sdk/effect";
import { Effect, Option } from "effect";

const effect = Effect.gen(function* () {
  const taxableIncome = yield* audFromCents(9_000_000);
  return yield* calculateRunRequest(AuAnnualIncomeTaxCalculation, {
    payload: {
      facts: { taxableIncome },
      jurisdiction: Option.some(
        Option.some(AuAnnualIncomeTaxCalculation.jurisdiction)
      ),
      taxYear: Option.some(Option.some(AuAnnualIncomeTaxCalculation.taxYear)),
    },
  });
});
```

Use `calculateReportRequest` when you have a full request and only need the
report. Use `calculateReport` when you already have descriptor-typed facts.

## Owning sources [#owning-sources]

* SDK facade: [`packages/sdk/typescript/src/index.ts`](https://github.com/crcorbett/taxkit/blob/a151e51e8a30247526fa93412df046955846eca4/packages/sdk/typescript/src/index.ts)
* AU helpers: [`packages/sdk/typescript/src/au.ts`](https://github.com/crcorbett/taxkit/blob/a151e51e8a30247526fa93412df046955846eca4/packages/sdk/typescript/src/au.ts)
* Effect helpers: [`packages/sdk/typescript/src/effect.ts`](https://github.com/crcorbett/taxkit/blob/a151e51e8a30247526fa93412df046955846eca4/packages/sdk/typescript/src/effect.ts)

## Used by [#used-by]

* [Run your first calculation](/start/run-your-first-calculation)
* [Plain SDK](/sdk/plain-sdk)
* [Effect SDK](/sdk/effect-sdk)
* [Examples](/reference/examples)