ID Generator JavaScript SDK

Use the ID Generator from Node and TypeScript with the hepgg package. Install, authenticate, and mint every ID flavour with a typed client.

ID Generator SDK#

Prefer JavaScript or TypeScript over raw fetch? The hepgg package wraps the ID Generator in a small, fully typed client. Same endpoint, same flavours, zero boilerplate. It is published to the Hep.gg registry and ships with types and JSDoc, so your editor explains every method as you type.

Install#

The package lives on the Hep.gg registry, so point npm at it once.

npm install hepgg --registry https://npm.hep.gg

echo 'registry=https://npm.hep.gg' >> .npmrc
npm install hepgg

Node 20 or newer. No other dependencies to install.

Quickstart#

Import the ID client from the hepgg/id subpath, construct it with your key, and call a generator. Every method returns { id } (the keypair flavour adds privateID).

import { ID } from "hepgg/id";
 
const id = new ID({ username: "my-bot", token: process.env.ID_TOKEN });
 
const { id: uuid } = await id.generateUUID();
console.log(uuid); // e355b9bf-2726-4309-bc19-c79d1d50edba

const { ID } = require("hepgg/id");
 
const id = new ID({ username: "my-bot", token: process.env.ID_TOKEN });
id.generateUUID().then(({ id }) => console.log(id));

Every Generator#

One method per flavour. The names map one-to-one to the ID types.

await id.generateUUID();                 // RFC 4122 v4
await id.generateNanoID(12);             // length required; optional alphabet
await id.generateNanoID(10, "abc123");   // custom alphabet
await id.generateWords(5, StyleType.Slug); // brave-yellow-otter-...
await id.generate2FA();                  // 6-digit code (length optional)
await id.generateKeyPair();              // { id, privateID }
await id.generateSnowflake();            // "1184526789012345678"
await id.generateLicense();              // AB12C-3DE4F-GH56J-7KL8M-N90PQ
await id.generateCUID(24, "web-1");      // CUID2, optional length + fingerprint

Need a flavour before a helper exists, or many at once? Use the low-level escape hatches.

import { ID, Type } from "hepgg/id";
 
await id.generate(Type.NanoID, { length: 8, alphabet: "abc123" });
const codes = await id.generateMany(Type.TOTP, 3); // three at once, concurrently

Options And Errors#

The constructor takes the shared client options, so you can tune timeouts and retries or inject a custom fetch.

A non-2xx response throws a typed HepError you can catch in one place.

import { HepError } from "hepgg";
 
try {
  await id.generateUUID();
} catch (err) {
  if (err instanceof HepError) console.error(err.status, err.message); // 401 Invalid username or token
}

Full Reference#

The SDK is a thin wrapper, so the API pages are the source of truth: Generate an ID, ID types, and Authentication.