definite-ts

TypeScript client for the Definite Assurance motor insurance API — onboard clients and intermediaries, quote premiums, submit proposals, and initiate payments in Kenya.

Features

• Full coverage of the documented Definite Assurance API (/api/v1)
• HTTP Basic authentication applied to every request
• Reference-data caching (products, makes & models) with TTL — in-memory or file-backed
• Input validation for every write operation before anything leaves your process
• Automatic YYYY-MM-DD HH:MM:SS.mmm timestamp formatting from native Date values
• Typed request/response interfaces
• Structured error handling with numeric error codes
• Zero runtime dependencies — uses only Node.js built-ins

Installation

npm install definite-ts

Quick Start

import { DefiniteClient } from "definite-ts";

const client = new DefiniteClient({
  environment: "uat", // or 'production'
  credentials: {
    username: "your-username",
    password: "your-password",
  },
});

// Look up a client before creating one
const existing = await client.checkClient("33669600");

// Quote a premium
const quote = await client.calculatePremium({
  sumInsured: 1_500_000,
  capacity: 5,
  tonnage: 0,
  coverPeriod: "Annually",
  product: 3617,
  coverOption: 3378,
});

Credentials are issued separately by your Definite Assurance administrator — they are not part of the published API documentation.

Configuration

interface DefiniteConfig {
  environment?: "uat" | "production"; // default: 'uat'
  baseURL?: string; // override the default endpoint
  credentials: {
    username: string;
    password: string;
  };
  apiUser?: string; // default APIUser on payments; falls back to credentials.username
  timeout?: number; // default: 30000 ms
  debug?: boolean; // enable debug logging
  cacheStorage?: "FILE" | "MEMORY" | "NONE"; // default: 'FILE'
  cacheTTL?: number; // default: 3600000 ms (1h)
  headers?: Record<string, string>; // merged into every request
}

The published documentation covers the UAT environment (https://uat.definiteassurance.com). Confirm the production host with your Definite administrator and pass it as baseURL if it differs from the default.

API Reference

Clients

// Look up an existing client by national ID number
const found = await client.checkClient("33669600");

// Onboard a new client
const created = await client.createClient({
  firstName: "Yawote",
  lastName: "Application",
  otherNames: "App",
  idNumber: "123789456112",
  pin: "A01014044J1",
  email: "[email protected]",
  phone: "0713156000",
});

// `data.id` is the client record ID used as `Client` on a proposal
const clientRecordId = created.data?.id;

Reference data

// Products and their cover options (cached)
const products = await client.getProducts();

// Vehicle makes and models (cached)
const makes = await client.getMakes();

// Bypass the cache
const fresh = await client.getProducts(true);

// Drop cached reference data
client.clearCache();

Premium calculation

const quote = await client.calculatePremium({
  sumInsured: 1_500_000,
  capacity: 5,
  tonnage: 0,
  coverPeriod: "2installments",
  product: 3617,
  coverOption: 3378,
  transactionType: 1, // query-string only
});

The API reads these values from both the query string and the JSON body, so the client sends them in both places.

Intermediaries

// Look up an agent / broker
const agent = await client.checkIntermediary("218378");

// Optionally send contact details alongside the lookup
await client.checkIntermediary("218378", {
  firstName: "Salam",
  lastName: "Salmini",
  email: "[email protected]",
  phone: "0713256545",
});

// Onboard a new intermediary
await client.registerIntermediary({
  name: "Yawote Insurance Agency",
  email: "[email protected]",
  phone: "07101433113",
  identification: "248378311",
  krapin: "A0101241848H",
});

Policies

const policy = await client.checkPolicy("KBS264M");

Proposals

const proposal = await client.createProposal({
  Client: 71864, // client record ID, not the national ID number
  agent: 71702, // intermediary record ID
  CommencementDate: new Date(), // formatted automatically
  PaymentInterval: "Annually",
  Product: 3617,
  CoverOption: 3378,
  Registration: "KPM641L",
  MakeCode: 1,
  ModelCode: 10,
  Capacity: 5,
  YOM: 2007,
  SumInsured: 0,
  ChassisNumber: "ETwwYUHFJF",
  EngineNumber: "33uwwruiru",
  EngineRating: 1500,
  ClientID: "33669600",
  Tonnage: 0,
});

Payments

import { addPolicyYear, normalizeKenyanPhone } from "definite-ts";

const commencement = new Date();

await client.initiatePayment({
  InsuredItem: proposal.data?.insuredItem!,
  Proposal: proposal.data?.id!,
  CommencementDate: commencement,
  ExpiryDate: addPolicyYear(commencement),
  PhoneNumber: normalizeKenyanPhone("0797083661"),
  PaymentMethod: 0, // M-Pesa
  MpesaTransaction: "UF3ER6U9X0",
  AmountPaid: 1,
  note: "Policy KPM641L",
});

APIUser is filled in from apiUser (or the basic-auth username) when you omit it.

Integration workflow

The documented end-to-end flow:

1. checkClient — does the client already exist?
2. createClient — onboard them if not.
3. getProducts — pick a product and cover option.
4. getMakes — resolve the vehicle make and model codes.
5. calculatePremium — quote the risk.
6. createProposal — submit the proposal.
7. initiatePayment — settle it and issue the policy.

Utilities

import {
  addPolicyYear,
  formatDefiniteDate,
  getPaymentIntervalDescription,
  getPaymentMethodDescription,
  isValidEmail,
  isValidKraPin,
  normalizeKenyanPhone,
  parseDefiniteDate,
} from "definite-ts";

formatDefiniteDate(new Date()); // '2026-06-02 14:09:01.350'
parseDefiniteDate("2026-06-02 14:09:01.350"); // Date
addPolicyYear(new Date()); // one day short of the anniversary
normalizeKenyanPhone("0713156000"); // '254713156000'
isValidKraPin("A0101401976H"); // true

Error handling

Every failure is a DefiniteError carrying a type, numeric code, message, and optional details.

import { DefiniteError, ERROR_CODES } from "definite-ts";

try {
  await client.checkClient("33669600");
} catch (error) {
  if (error instanceof DefiniteError) {
    console.error(error.type); // 'InternalError' | 'ExternalError'
    console.error(error.code); // e.g. 3000 (ERROR_CODES.CHECK_CLIENT)
    console.error(error.message); // message returned by the API
    console.error(error.details); // original response payload
  }
}

| Range | Category | | ----------- | --------------------- | | 1000–1099 | Configuration errors | | 2000–2099 | Authentication errors | | 3000–8999 | API operation errors | | 9000–9099 | Transport / parsing |

InternalError means the client rejected the call (bad input, network failure, unparseable response). ExternalError means Definite responded with a failure.

Caching

Reference data is cached because the product catalogue and makes list change rarely. The default FILE backend persists entries under the system temp directory, keyed by credentials and base URL, so UAT and production never collide:

<tmpdir>/definite-cache/<base64url(username)>/<base64url(baseURL:password)>.json

Use cacheStorage: "MEMORY" for in-process-only caching, or "NONE" to disable it.

Development

npm install
npm run build     # compile to dist/
npm test          # run the test suite
npm run docs      # generate TypeDoc API docs

License

ISC © Morgan Okumu