Skip to main content

SDKs

TypeScript​

The TypeScript SDK lives in the AfricaOne repository at sdk/typescript. It includes types generated from this contract, a typed client, the token and PKCE helpers and the webhook verifier, and it runs in browsers, Node 20+, Deno and edge runtimes (WebCrypto only, no Node-specific APIs). It is source-only: it is not published to npm until the owner decides on publishing.

import { clientCredentials, createAfricaOneClient } from '@africaone/developer-sdk';

const token = await clientCredentials({
  tokenUrl: 'https://api.africaone.io/developer/v1/oauth/token',
  clientId: process.env.AO_CLIENT_ID!,
  clientSecret: process.env.AO_CLIENT_SECRET!, // server side only
  scope: 'city.public.read',
});
const api = createAfricaOneClient({
  baseUrl: 'https://api.africaone.io/developer/v1',
  accessToken: token.access_token,
});
const { data } = await api.GET('/cities');

What it includes​

  • Typed client. Every contract operation is typed. A refusal throws AfricaOneApiError, which carries the problem code and requestId. needsReauthorisation tells you when to send the player back to consent.
  • OAuth helpers.
    • clientCredentials for app tokens.
    • createPkcePair, createState, authorizeUrl and exchangeCode for player consent -- PKCE S256 and the exact redirect_uri.
    • refresh. Refresh tokens rotate, so store the new one every time.
  • Webhook verifier. verifyWebhook checks scheme ao1: HMAC-SHA256 over the raw body, a 300-second skew window, rotation-friendly key ids and replay protection. Pass the raw body exactly as received. Persist the replay store in production.

Keeping it in step with the contract​

pnpm --filter @africaone/developer-sdk generate        # after a contract change
pnpm --filter @africaone/developer-sdk check:contract  # fails on drift (also part of `test`)

CONTRACT_VERSION records the contract version and the hashes of the contract and the generated schema.

Other languages​

Not built yet. The TypeScript SDK ships first; other languages will be documented here, with their own source location and generation pipeline, only when they genuinely exist.