Show calculator help to users

Use this guide when your UI needs labels, required facts or validation help for the selected calculator.

Before you start

  • Choose a calculator ID such as au.pay.take-home.
  • Use HTTP for browser clients that cannot import rule packages.
  • Keep the generated OpenAPI reference as the endpoint field source.

Steps

  1. Fetch calculator schema metadata.
  2. Render fact titles and question metadata.
  3. Call calculate with help=errors when validation fails.
  4. Show returned issue paths beside your fields.

Example

ts
import { TaxKitHttpApiService } from "@taxkit/api-http/client";
import { createTaxKitApiClientLayer } from "@taxkit/api-http/client/live";
import { HelpQuery } from "@taxkit/calculators/schemas";
import { AuPayTakeHomeCalculation } from "@taxkit/sdk/au/effect";
import { Array, Effect, Layer, Option } from "effect";
import * as FetchHttpClient from "effect/http/FetchHttpClient";

export const loadCalculatorHelp = Effect.gen(function* () {
  const client = yield* TaxKitHttpApiService;
  const query = yield* HelpQuery.makeEffect({
    help: Option.some(Option.some("schema")),
  });
  const schema = yield* client.calculatorApi.getCalculatorSchema({
    params: { calculatorId: AuPayTakeHomeCalculation.calculatorId },
    query,
  });
  return Array.map(schema.inputFacts, (fact) => `${fact.id}: ${fact.title}`);
});

// Your application supplies the public API origin and owns Effect execution.
export const program = loadCalculatorHelp.pipe(
  Effect.provide(
    createTaxKitApiClientLayer({ baseUrl: "http://127.0.0.1:4000" }).pipe(
      Layer.provide(FetchHttpClient.layer)
    )
  )
);

Verify the result

Expected output includes fact descriptors for gross pay and the tax-free threshold claim used by the take-home pay calculator.

Handle errors

Let the typed client's expected error channel reach your application error handler. Display the checked issue paths or descriptor help from an input decode failure; API errors explains the envelope and other server failures. A calculation call with help=errors returns field help when its checked request facts do not match the selected calculator.

Read this page as Markdown