Working by name

If you don’t keep uuids, these functions look them up for you. They take the client as their first argument, and a zone as returned by zones.get (anything with uuid and name).

import {
  addGeoBans,
  addRecordValue,
  qualifyName,
  removeRecordValue,
  updateRecordValue,
} from '@dinio/sdk';

const zone = await dinio.zones.get('example.com');
const www = qualifyName('www', zone.name); // "www.example.com"

await addRecordValue(dinio, zone, www, 'A', { data: '192.0.2.1', ttl: 300 });
await updateRecordValue(dinio, zone, www, 'A', { data: '192.0.2.1' }, { data: '192.0.2.2' });
await addGeoBans(dinio, zone, www, 'A', { data: '192.0.2.2' }, ['RU', 'Eastern Asia']);
await removeRecordValue(dinio, zone, www, 'A', { data: '192.0.2.2' });

Names

The API takes full names. qualifyName turns a zone-file style name into one; relativeName goes back.

qualifyName('www', 'example.com');             // "www.example.com"
qualifyName('@', 'example.com');               // "example.com"
qualifyName('www.example.com', 'example.com'); // "www.example.com"
qualifyName('other.org.', 'example.com');      // "other.org" — trailing dot = absolute

relativeName('www.example.com', 'example.com'); // "www"
relativeName('example.com', 'example.com');     // "@"

Picking a value

Functions that act on one value take a selector: { data } or { id }. Data is compared in the API’s canonical form with sameData, so 2001:DB8::0001 finds 2001:db8::1 and mail.example.com finds mail.example.com..

When nothing matches, the function throws DinioNotFoundError, and its message lists the values that do exist, with their uuids.

Records

Function
`groupRecordValues(values)`	Groups a flat list from `records.list` / `listAll` into record sets, without a request.
`findRecordGroup(dinio, zone, name, type)`	The record set, or `undefined`.
`findRecordValue(dinio, zone, name, type, selector)`	`{ group, value }`.
`findRecordValueWithGeoBans(…)`	The same, with the value’s `geoBans`.
`addRecordValue(dinio, zone, name, type, add)`	Adds a value; creates the set if needed. Returns `{ value, ttl, newGroup }`.
`updateRecordValue(dinio, zone, name, type, selector, patch)`	Changes one value.
`removeRecordValue(dinio, zone, name, type, selector)`	Removes one value; returns it.
`removeRecordGroup(dinio, group)`	Removes every value of a set; returns them. Refuses up front, with `DinioInputError`, a set with values Dinio keeps for a redirect or certificate issuance.

add is { data, ttl?, geo_routing?, balance_ratio?, host_health? }. ttl applies only to a new record set and defaults to DEFAULT_TTL (3600). For an existing set, a different ttl throws DinioInputError — change the TTL with records.setTtl. host_health is 'None', 'Up' or 'Down'; a value gets 'Auto' when a health check is created for it.

Zones

Function
`findZoneForName(dinio, name)`	The most specific zone you can access that `name` is in (`go.shop.example.com` → `shop.example.com` before `example.com`), or `undefined`. Use it for the `zone_id` of a redirect or a certificate.
`zoneFileFormatFromName(fileName)`	`'json'`, `'bind'` or `'csv'` from a file’s extension (`.json`; `.zone`, `.bind`, `.db`; `.csv`), or `undefined`.

Geo areas

Areas resolve through the catalog Dinio publishes — the same list it checks ban codes against, listed in Geo areas. Read it once with dinio.geo.catalog() and pass it in.

import { parseGeoArea } from '@dinio/sdk';

const catalog = await dinio.geo.catalog();
parseGeoArea(catalog, 'HR'); // { level: 'Country', code: 191 }

Function
`parseGeoArea(catalog, input)`	`'HR'`, `'HRV'`, `'Croatia'`, `'Europe'`, `'country:191'` → `{ level, code }`.
`knownAreas(catalog)`	Every country, sub-region and region, with codes and ISO letters.
`geoAreaName(catalog, area)`	`{ level: 'Country', code: 191 }` → `"Croatia"`.
`describeGeoArea(catalog, area)`	A label for people, e.g. `"Country Croatia (191)"`.
`geoBanArea(ban)` / `sameGeoArea(a, b)`	Read and compare the area of a ban.

A bare number is rejected — region and country codes overlap — so write country:191 or region:150. A code that is not in the catalog is rejected too.

Geo bans

Function
`addGeoBans(dinio, zone, name, type, selector, areas, { catalog? })`	Bans each area; areas already banned are skipped. Returns `{ value, created, skipped }`.
`removeGeoBans(dinio, zone, name, type, selector, areas \| 'all', { catalog? })`	Removes the bans on these areas, or all of them. Every area must be banned, or nothing is removed. Returns `{ value, removed }`.

areas are names, codes or { level, code } objects. All of them are parsed before the first request, so a typo never leaves half of the bans applied. Without catalog, a call that is given names reads the catalog itself; pass it when you make several calls.

Client identities and lists

Function
`findClientIdentity(dinio, reference)`	One of your client identities by uuid, `identify` value or name. Names are compared ignoring case; an ambiguous name throws `DinioInputError`, no match `DinioNotFoundError`.
`matchClientIdentity(identities, reference)`	The same over a list you already have, without a request; `undefined` if nothing matches.
`findSinkholeList(dinio, reference, { includeShared? })`	A sinkhole list by uuid or name: your own first, then, with `includeShared`, other users’ shared lists.
`matchSinkholeList(lists, reference)`	The same over a list you already have, without a request.

import { findClientIdentity, findSinkholeList } from '@dinio/sdk';

const phone = await findClientIdentity(dinio, 'phone');
const malware = await findSinkholeList(dinio, 'malware', { includeShared: true });
await dinio.sinkholeLinks.create(phone.uuid, malware.uuid);