@ist/identity

Username generation and identity management library for IST.

Provides random username generation (adjective-animal-4char format), validation, and an API client for the IST Identity service.

Installation

glpkg install @ist/identity

Usage

Username Generation

import { generateUsername, isValidUsername } from '@ist/identity';

const name = generateUsername();
// => "bright-fox-7k2m"

isValidUsername('bright-fox-7k2m');  // true
isValidUsername('INVALID');          // false
isValidUsername('too-many-parts-here'); // false

Username format: {adjective}-{animal}-{4 alphanumeric chars}

Regex: /^[a-z]+-[a-z]+-[a-z0-9]{4}$/

Identity Client

import { IdentityClient } from '@ist/identity';

const client = new IdentityClient({
  baseUrl: 'https://ist-identity-api.sisung-kim1.workers.dev',
});

registerUsername(uid, username, token)

Register a username for a uid. Returns RegisterResult.

const result = await client.registerUsername(uid, 'bright-fox-7k2m', token);
if (result.success) {
  console.log('Registered:', result.username);
}

changeUsername(uid, newUsername, token)

Change a uid's username. Returns ChangeResult.

const result = await client.changeUsername(uid, 'calm-wolf-x9a1', token);
if (result.success) {
  console.log(`${result.oldUsername} -> ${result.newUsername}`);
}

getUsername(uid, token)

Get username by uid (authenticated). Returns LookupResult.

const result = await client.getUsername(uid, token);
if (result.found) {
  console.log(result.username);
}

getUserByUsername(username)

Public lookup — resolve uid by username (no auth required). Returns LookupResult.

const result = await client.getUserByUsername('bright-fox-7k2m');
if (result.found) {
  console.log(result.uid);
}

API Reference

Types

interface IdentityConfig {
  baseUrl: string;
}

interface RegisterResult {
  success: boolean;
  username?: string;
  error?: string;
}

interface ChangeResult {
  success: boolean;
  oldUsername?: string;
  newUsername?: string;
  error?: string;
}

interface LookupResult {
  found: boolean;
  uid?: string;
  username?: string;
  error?: string;
}

Exports

| Export | Type | Description | |---|---|---| | generateUsername() | () => string | Generate a random username | | isValidUsername(name) | (string) => boolean | Validate username format | | IdentityClient | class | API client for identity service | | IdentityConfig | interface | Client configuration | | RegisterResult | interface | Result of register operation | | ChangeResult | interface | Result of change operation | | LookupResult | interface | Result of lookup operation |

License

SSPL-1.0