Node.js and TypeScript

Install

Use Node.js 18 or later for the client runtime. Install the official package from npm:

npm install @kuahr/node@0.3.3

Commit your lockfile and review release notes before upgrading. View the public source.

Make a Test request

Create a Test key with payroll:read as described in quickstart, then set KUA_API_KEY in your runtime environment.

import { Kua } from "@kuahr/node";
const kua = new Kua({
  apiKey: process.env.KUA_API_KEY!,
});
const runs = await kua.payrollRuns.list();
console.log(runs);

Expected: an array, including [] when there are no Test runs. The base URL is explicit because the SDK defaults to production. Never embed the key in browser-side JavaScript.

Choose a task

• Create an employee: kua.employees.create(body, { idempotencyKey }) with employees:write.
• Prepare a payroll draft: kua.payrollRuns.create(body, { idempotencyKey }) with payroll:write; read back with payroll:read.
• Receive webhooks: a separately authorised Live key and webhook grants.
• Poll events: a separately authorised Live key with events:read, paired cursor and durable checkpoints.
• Workforce: leave, advances, performance, all Live-key only.

Handle errors and retries

import { KuaError } from "@kuahr/node";
try {
  const runs = await kua.payrollRuns.list();
} catch (error) {
  if (error instanceof KuaError) {
    // Branch on error.code and error.status; don't log the API key.
    console.error(error.status, error.code);
  } else {
    // A transport failure may leave a write's outcome unknown.
    throw error;
  }
}

The client does not automatically retry. Use bounded backoff for reads. For writes, persist the same credential, operation key and exact request before sending; idempotency explains unknown outcomes, retention and rotation boundaries. Do not retry a money-affecting decision merely because its response was interrupted.

Verify webhook signatures

The client exports verifySignature(rawBody, signatureHeader, signingSecret) with a default 300-second timestamp tolerance. Use it on raw bytes before JSON parsing. Signature verification shows a receiver and durable deduplication responsibilities.

Webhook operations include kua.webhooks.history(endpointId, deliveryId) and kua.webhooks.replay(endpointId, deliveryId, { requestKey, reason }). Follow recovery for scopes, stable request keys, eligibility and delivery readback. There is no SDK signing-secret rotation method.

Done when: the official client is installed in your server application and the Test list call succeeds at api.kuahr.com. Continue with your selected task, then go-live readiness.

Recovery availability

Webhook delivery-history and manual-replay methods are available at api.kuahr.com. Use an authorised Live key and recovery prerequisites. SDK installation does not grant replay permission.