Guides

JavaScript SDK

@skilledcrow/itoka is a typed client for the whole API. It has no dependencies and runs in Node 20+, Bun, Deno and Cloudflare Workers.

npm install @skilledcrow/itoka

import { Itoka } from '@skilledcrow/itoka';

const itoka = new Itoka({ apiKey: process.env.ITOKA_API_KEY });
await itoka.records.create('ojaara.com', { type: 'A', name: 'www', value: '192.0.2.7', ttl: 300 });

apiKey defaults to the ITOKA_API_KEY environment variable. Other options: baseUrl (default https://api.itoka.ng), maxRetries (default 2), timeoutMs (default 60000) and fetch.

What's in it

Namespace	Methods
`zones`	list, get, create, checkVerification, remove, delegation, checkDelegation, propagation, setup
`records`	list, validate, create, update, delete, upsert
`freeSubdomains`	info, check, claim
`presets`	list, preview, apply
`imports`	scan, zoneFile, apply
`domains`	search, list, get, update, buy
`contacts`	list, create
`quotes`	create
`promoCodes`	check
`orders`	list, get, create, checkout, wait
`webhooks`	eventTypes, list, get, create, update, delete, rollSecret, test, deliveries, redeliver

Every method returns the API's own shapes, typed. Some helpers do more than one call:

records.upsert(zone, record) updates the one record of that type at that name, or adds it if there's none. Handy for dynamic DNS.
domains.buy({ name, contactId, years?, promoCode?, useCredit?, clientEmail? }) quotes and orders in one go.
orders.wait(id) polls until the order is settled (completed, failed, refunded, credited or cancelled).
itoka.request(method, path, { body, query }) calls any endpoint the client doesn't wrap.

Errors and retries

import { ItokaError } from '@skilledcrow/itoka';

try {
  await itoka.records.create('ojaara.com', { type: 'MX', name: '@', priority: 10, value: '192.0.2.1' });
} catch (err) {
  if (err instanceof ItokaError) {
    console.log(err.status, err.code, err.field); // 422 invalid_record value
    console.log(err.message); // the API's message, then "Fix: …"
  }
}

ItokaError carries status, code, reason, fix, field and, on a 429, retryAfter. GETs, PUTs and DELETEs, and orders (always sent with an idempotency key), are retried on network errors, short 429s and 502/503/504. Other POSTs aren't, so a record create is never sent twice.

Webhooks

import { verifyWebhook, signWebhook } from '@skilledcrow/itoka';

const event = await verifyWebhook({ payload: rawBody, signature: header, secret }); // typed by event.type
const header2 = await signWebhook(secret, rawBody); // for testing your handler

See Webhooks for the events and what to do with them.