Build a browser app with the HTTP API

Use this guide when a browser client needs the server to run a calculation. The browser-safe SDK can run calculations on the device instead; compare the choices in Choose SDK or HTTP API.

Before you start

Run the API app locally or point at your deployed API base URL.
Read Authentication and deployment assumptions.
Use canonical JSON values for tagged facts.

Steps

Supply your API base URL as a URL value.
Construct canonical facts and explicit context/help Options for the typed API client.
Run the returned Effect at your application host.
Render the report or handle its typed failure channel.

Example

import { createTaxKitApiClient } from "@taxkit/api-http/client";
import { audFromCents } from "@taxkit/core/primitives";
import { GrossPay } from "@taxkit/rules-au-pay";
import { AuPayTakeHomeCalculation } from "@taxkit/sdk/au/effect";
import { Effect, Option } from "effect";
import * as FetchHttpClient from "effect/http/FetchHttpClient";

export const calculateTakeHomePay = (baseUrl: URL) =>
  Effect.gen(function* () {
    const client = yield* createTaxKitApiClient({ baseUrl });
    const amount = yield* audFromCents(346_200);
    return yield* client.calculatorApi.calculate({
      params: { calculatorId: AuPayTakeHomeCalculation.calculatorId },
      payload: {
        facts: {
          grossPay: new GrossPay({
            amount,
            period: "fortnightly",
          }),
          taxFreeThresholdClaimed: true,
        },
        jurisdiction: Option.some(
          Option.some(AuPayTakeHomeCalculation.jurisdiction)
        ),
        taxYear: Option.some(Option.some(AuPayTakeHomeCalculation.taxYear)),
      },
      query: { help: Option.some(Option.some("errors")) },
    });
  }).pipe(Effect.provide(FetchHttpClient.layer));

Verify the result

Call calculateTakeHomePay(new URL("http://127.0.0.1:4000")) for your local API, or supply your deployed URL explicitly. The example has no default server and reads no browser environment variables. The returned response contains report.netPay.cents with the expected value:

txt

Handle errors

For invalid facts, the API returns CalculatorApiErrorEnvelope with a CalculatorServiceError in error. Add ?help=errors when you want descriptor-backed field help.

Read this page as Markdown