SDKs

:::info Coming soon The official TypeScript SDK, @afrihex/sdk, is fully built and tested but not yet published to npm (we're finalizing the npm package scope). This page documents its full surface so you know exactly what's coming. Until it's live, use the plain HTTP endpoints — every example in these docs works with curl and the X-API-Key header.

When it ships, install with:

npm install @afrihex/sdk

:::

The SDK wraps the entire API with typed methods, automatic X-API-Key headers, and typed errors.

Setup

import { AfriHex } from '@afrihex/sdk'

const afrihex = new AfriHex({
  apiKey: process.env.AFRIHEX_API_KEY!,
  // baseURL defaults to the production API; override for self-hosted instances
  baseURL: 'https://api.afrihex.com',
})

Module surface

The SDK groups methods the same way the API is organised:

Module	Methods
afrihex.hex	encode, decode, children, neighbors, parent, distance, path, bulk
afrihex.bridge	fromGPS (GPS code → hex), toGPS (hex → GPS code)
afrihex.landmarks	geocode (name / near-point / anchored search)
afrihex.kyc	verify, proximityVerify
afrihex.collections	register, locate, bulkRegister
afrihex.consent	grant, revoke, status
afrihex.location	ping
afrihex.monitoring	drift, summary, schedule, history, staleness
afrihex.webhooks	configure, deliveries, retry
afrihex.analytics	hotspots, heatmap, cellStats
afrihex.portfolio	risk

Examples

Hex addressing

const hex = await afrihex.hex.encode(5.6037, -0.1870, 7)
console.log(hex.code) // "AF-GH-7-0GXTQD5RFZZZZ"

const loc = await afrihex.hex.decode('AF-GH-7-0GXTQD5RFZZZZ')
console.log(loc.center) // { lat: 5.6041, lng: -0.1953 }

GPS bridge

const bridge = await afrihex.bridge.fromGPS('GA-142-7281')
console.log(bridge.hex_code)

const reverse = await afrihex.bridge.toGPS('AF-GH-7-0GXTQD5RFZZZZ')
console.log(reverse.gps_code)

KYC verification

const result = await afrihex.kyc.verify({
  method: 'gps_code',
  gps_code: 'GA-142-7281',
  customer_id: 'cust_123',
})
console.log(result.verified, result.quality_score)

Monitoring (consent → ping → drift)

await afrihex.consent.grant({
  customer_id: 'cust_123',
  home_hex: 'AF-GH-7-0GXTQD5RFZZZZ',
})

await afrihex.location.ping({
  customer_id: 'cust_123',
  lat: 5.6041,
  lng: -0.1953,
})

const drift = await afrihex.monitoring.drift({ customer_id: 'cust_123' })
console.log(drift.events)

Errors

The SDK throws AfriHexError with .code, .message, and .status mirroring the API response envelope:

import { AfriHex, AfriHexError } from '@afrihex/sdk'

try {
  await afrihex.hex.decode('NOT-A-CODE')
} catch (err) {
  if (err instanceof AfriHexError) {
    console.error(err.code, err.status) // INVALID_HEX_CODE, 400
  }
}

Plain HTTP

No SDK required — every endpoint works with plain curl (as shown throughout these docs). Send your key in the X-API-Key header.