@chittyos/chittyid-client

ChittyID client for minting and validating ChittyOS identifiers.

Installation

npm install @chittyos/chittyid-client

Important: Service or Fail Policy

This client follows ChittyOS "service or fail" policy:

• ✅ All ChittyIDs MUST be minted from https://id.chitty.cc
• ❌ NO local ChittyID generation is permitted
• ❌ NO fallback to local generation on service failure
• ✅ Proper error handling when service is unavailable

Usage

Basic Setup

import { ChittyIDClient } from '@chittyos/chittyid-client';

// Create client (requires CHITTY_ID_TOKEN environment variable)
const client = new ChittyIDClient();

// Or with custom configuration
const client = new ChittyIDClient({
  baseURL: 'https://id.chitty.cc',
  token: 'your-chitty-id-token',
  timeout: 30000,
});

Mint a Single ChittyID

import { mintChittyID } from '@chittyos/chittyid-client';

// Mint with convenience function
const response = await mintChittyID({
  entity: 'PEO',              // Person entity
  trust: 'verified',          // Trust level
  metadata: {
    name: 'John Doe',
    email: '[email protected]'
  }
});

console.log(response.chittyId);  // CHITTY-PEO-123456-ABC123

Mint Multiple ChittyIDs (Batch)

const client = new ChittyIDClient();

const response = await client.batchMint({
  requests: [
    { entity: 'PEO', trust: 'verified' },
    { entity: 'PROP', trust: 'self' },
    { entity: 'EVNT', trust: 'verified' },
  ]
});

console.log(response.ids);
// [
//   'CHITTY-PEO-123456-ABC123',
//   'CHITTY-PROP-789012-DEF456',
//   'CHITTY-EVNT-345678-GHI789'
// ]

Session-Based Minting

const client = new ChittyIDClient();

// Create a minting session
const session = await client.createSession({
  batchSize: 100,
  trust: 'verified',
  entity: 'PEO'
});

console.log(session.sessionId);  // session-abc123

// Use session for minting
const response = await client.mint({
  entity: 'PEO',
  sessionId: session.sessionId
});

Validate ChittyID Format

import { validateChittyID } from '@chittyos/chittyid-client';

// Local format validation (no service call)
const result = await validateChittyID(
  'CHITTY-PEO-123456-ABC123',
  false  // Local validation only
);

console.log(result.valid);  // true

Validate with Service Verification

const client = new ChittyIDClient();

// Verify with service (makes API call)
const result = await client.validate(
  'CHITTY-PEO-123456-ABC123',
  true  // Verify with service
);

console.log(result.valid);    // true
console.log(result.entity);   // 'PEO'
console.log(result.trust);    // 'verified'

Batch Validation

const client = new ChittyIDClient();

const results = await client.batchValidate([
  'CHITTY-PEO-123456-ABC123',
  'CHITTY-PROP-789012-DEF456',
  'invalid-chitty-id',
]);

results.forEach((result, i) => {
  console.log(`ID ${i}: ${result.valid ? 'valid' : 'invalid'}`);
  if (!result.valid) {
    console.log(`  Error: ${result.error}`);
  }
});

Check Service Health

const client = new ChittyIDClient();

const health = await client.health();

console.log(health.status);   // 'healthy'
console.log(health.version);  // '2.0.0'

Entity Types

Supported ChittyID entity types:

| Entity | Description | |--------|-------------| | PEO | Person | | PLACE | Physical location | | PROP | Property/Asset | | EVNT | Event/Occurrence | | AUTH | Authentication/Authorization | | INFO | Information/Data | | FACT | Fact/Claim | | CONTEXT | Context/Environment | | ACTOR | Actor/Agent |

Trust Levels

| Trust | Description | |-------|-------------| | self | Self-attested, no verification | | verified | Verified by ChittyOS authority | | certified | Certified by external authority | | notarized | Notarized with legal standing |

Error Handling

import { ChittyIDError } from '@chittyos/types';

try {
  const response = await client.mint({ entity: 'PEO' });
} catch (error) {
  if (error instanceof ChittyIDError) {
    console.error('ChittyID Error:', error.code);
    console.error('Message:', error.message);
    console.error('Status:', error.statusCode);
    console.error('Metadata:', error.metadata);
  }
}

Environment Variables

Required:

# ChittyID authentication token
CHITTY_ID_TOKEN=your-chitty-id-token

Optional:

# Override service URL (default: https://id.chitty.cc)
CHITTYID_SERVICE=https://custom-id.chitty.cc

Configuration Options

interface ChittyIDClientConfig {
  /** ChittyID service base URL */
  baseURL?: string;
  /** ChittyID token for authentication */
  token?: string;
  /** Request timeout in milliseconds (default: 30000) */
  timeout?: number;
  /** Enable automatic retries (default: true) */
  retryEnabled?: boolean;
}

API Reference

ChittyIDClient

Constructor

new ChittyIDClient(config?: ChittyIDClientConfig)

Methods

• createSession(config?: SessionConfig): Promise<MintSessionResponse>
• mint(request: MintRequest): Promise<MintResponse>
• batchMint(request: BatchMintRequest): Promise<BatchMintResponse>
• validate(chittyId: string, verifyWithService?: boolean): Promise<ValidateResponse>
• batchValidate(chittyIds: string[]): Promise<ValidateResponse[]>
• health(): Promise<{ status: string; version: string }>
• getBaseURL(): string

Convenience Functions

// Mint single ChittyID
mintChittyID(request: MintRequest, config?: ChittyIDClientConfig): Promise<MintResponse>

// Validate ChittyID
validateChittyID(chittyId: string, verifyWithService?: boolean, config?: ChittyIDClientConfig): Promise<ValidateResponse>

// Create client
createChittyIDClient(config?: ChittyIDClientConfig): ChittyIDClient

Features

• ✅ Service-only minting (no local generation)
• ✅ Batch minting support
• ✅ Session-based minting for high-volume operations
• ✅ Format validation (client-side)
• ✅ Service verification (server-side)
• ✅ Batch validation
• ✅ Automatic retry on network errors
• ✅ Type-safe API with TypeScript
• ✅ Comprehensive error handling
• ✅ Health check support

Dependencies

• @chittyos/types - Type definitions
• @chittyos/env - Environment management
• @chittyos/config - Service configuration
• @chittyos/http-client - HTTP client with retry

Package Size

~45 KB (gzipped: ~12 KB)

License

MIT