TypeScript SDK

ai4m-sdk is a small client for TypeScript and JavaScript. It handles authentication, gives every response a type, and throws a clear error for each kind of failure. It has no dependencies and works in Node 18 or newer and in browsers.

Install

npm install https://docs.ai4mproject.com/downloads/ai4m-sdk-0.4.0.tgz

Or download the package and install the file:

npm install ./ai4m-sdk-0.4.0.tgz

The current version is 0.4.0. New versions are announced in the changelog.

Create a client

import { AI4MClient } from 'ai4m-sdk';

const client = new AI4MClient({ apiKey: process.env.AI4M_API_KEY! });

Option	Default	Meaning
`apiKey`	required	Your API key
`baseUrl`	`https://api.ai4mproject.com`	The API’s address
`timeoutMs`	`10000`	Milliseconds to wait for a response
`fetch`	the global `fetch`	A replacement, for tests or older runtimes

Methods

Method	Returns	Endpoint
`getPeriods()`	`Periods`	Periods
`getStateRisk(period?)`	`StateRiskReport`	State risk
`getLgaRisk(state, period?)`	`LgaRiskReport`	LGA risk
`getStateForecasts(months?)`	`StateRiskReport[]`	State forecasts
`getLgaForecasts(state, months?)`	`LgaRiskReport[]`	LGA forecasts
`getTransmission()`	`TransmissionReport`	State transmission
`getLgaSeasons(state)`	`LgaSeasonReport`	LGA transmission
`getTransmissionModel()`	`TransmissionModel`	Transmission model
`getStateContext()`	`StateContextReport`	State context
`getLgaContext(state)`	`LgaContextReport`	LGA context
`getStateBoundaries()`	`FeatureCollection`	State boundaries
`getLgaBoundaries(state)`	`FeatureCollection`	LGA boundaries

Every method returns a promise.

Example

const periods = await client.getPeriods();
console.log(`Estimated to ${periods.last_estimated}, forecast to ${periods.last_forecast}`);

// The five highest-risk states this month.
const report = await client.getStateRisk();
for (const state of [...report.states].sort((a, b) => b.score - a.score).slice(0, 5)) {
  console.log(state.state, state.score.toFixed(2), state.level);
}

// Every LGA in Kano, its forecast, and when cases are expected to be highest.
const kano = await client.getLgaRisk('KN');
const forecasts = await client.getLgaForecasts('KN', 3);
const seasons = await client.getLgaSeasons('KN');

What comes back

Field names are the same as in the API’s JSON, so state.score_low, lga.lga_code and season.peak_month are exactly what the reference describes. See Scores and levels for what they mean.

Errors

Every error is an AI4MError, with statusCode and, where the API sends one, code.

Error	Status	Meaning
`AI4MValidationError`	400	The request was wrong
`AI4MAuthenticationError`	401	The key is missing, wrong, expired or revoked
`AI4MPermissionError`	403	The key lacks the scope
`AI4MNotFoundError`	404	Unknown state, or no data for that month
`AI4MRateLimitError`	429	A limit was reached. Has `retryAfter`, in seconds

import { AI4MPermissionError, AI4MRateLimitError } from 'ai4m-sdk';

try {
  const report = await client.getLgaRisk('KN');
} catch (error) {
  if (error instanceof AI4MRateLimitError && error.code === 'RATE_LIMITED') {
    await new Promise((done) => setTimeout(done, (error.retryAfter ?? 5) * 1000)); // then try again
  } else if (error instanceof AI4MPermissionError) {
    console.error("This key can't read risk scores:", error.message);
  } else {
    throw error;
  }
}