Kronos TypeScript SDK

Official TypeScript/JavaScript client library for Kronos Proof-as-a-Service.

Generate cryptographically verifiable proofs of when something happened, with NTP-synchronized time and optional pulsar-based galactic references.

Installation

npm install @krisadamstv/kronos-paas
# or
yarn add @krisadamstv/kronos-paas

Quick Start

import { KronosClient } from '@krisadamstv/kronos-paas';

// Create client with your API key
const client = new KronosClient({
  apiKey: 'pk_live_your_api_key_here'
});

// Generate a unique temporal proof
const proof = await client.generateKronos();
console.log('Proof ID:', proof.kronos);
console.log('Timestamp:', proof.date_received);
console.log('Human Readable:', proof.human_readable_proof);

Features

• ✅ Unique Temporal Proofs - Generate proofs based on current NTP time (Kronos mode)
• ✅ Deterministic Proofs - Generate consistent proofs from input data (Chronos mode)
• ✅ Proof Verification - Verify proofs and receipts
• ✅ NTP Time Access - Get accurate NTP-synchronized time
• ✅ Crab Pulsar Reference - Galactic time notation (pro/founder tiers) 🦀
• ✅ Automatic Retries - Built-in retry logic with exponential backoff
• ✅ Full TypeScript Support - Complete type definitions included
• ✅ Browser & Node.js - Works in both environments

Usage

Creating a Client

import { KronosClient } from '@krisadamstv/kronos-paas';

// Basic client with default settings
const client = new KronosClient({
  apiKey: 'pk_live_...'
});

// Custom configuration
const customClient = new KronosClient({
  apiKey: 'pk_live_...',
  baseUrl: 'https://proofapi.krisadamstv.com',
  timeout: 60000,
  maxRetries: 5,
});

Generating Proofs

Kronos Mode (Unique Temporal Proofs)

Generate a unique proof based on the current time. Each call produces a different proof:

const proof = await client.generateKronos();

console.log('Unique Proof:', proof.kronos);
console.log('Timestamp:', proof.date_received);
console.log('NTP Time:', proof.receipt.ntp_time);

// Crab Pulsar reference (pro/founder tiers)
if (proof.crab_appendix?.enabled) {
  console.log('Pulsar:', proof.crab_appendix.pulsar);
  console.log('Phase:', proof.crab_appendix.phase);
}

Chronos Mode (Deterministic Proofs)

Generate a deterministic proof from input data. Same input = same proof:

const proof = await client.generateChronos('document-hash-abc123');

console.log('Deterministic Hash:', proof.chronos);
console.log('Same input will always produce this hash!');

Document Proofs (with SHA-256)

import { createHash } from 'crypto';

// Hash your document
const documentData = 'Important contract text...';
const hash = createHash('sha256').update(documentData).digest('hex');

// Generate proof
const proof = await client.generateChronos(hash);
console.log('Document Proof:', proof.chronos);

Verifying Proofs

const proof = await client.generateKronos();
const result = await client.verifyProof(proof);

if (result.valid) {
  console.log('✅ Proof is valid!');
  console.log('Verified fields:', result.verified_fields);
} else {
  console.log('❌ Proof is invalid');
  console.log('Errors:', result.errors);
  if (result.tamper_detected) {
    console.log('Tamper indicators:', result.tamper_indicators);
  }
}

Getting NTP Time

const timeInfo = await client.getTime();

console.log('NTP Time:', timeInfo.ntp_time);
console.log('Time Slip (ms):', timeInfo.time_slip_ms);
console.log('Healthy:', timeInfo.healthy);

Health Check

const status = await client.healthCheck();
console.log('API Status:', status.status);

Error Handling

The SDK provides typed errors for common scenarios:

import { 
  KronosClient, 
  KronosError, 
  AuthenticationError, 
  RateLimitError,
  NetworkError,
  isRetryableError 
} from '@krisadamstv/kronos-paas';

try {
  const proof = await client.generateKronos();
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.log('Check your API key');
  } else if (error instanceof RateLimitError) {
    console.log('Slow down! Rate limit exceeded');
  } else if (error instanceof NetworkError) {
    console.log('Network issue:', error.message);
  } else if (error instanceof KronosError) {
    console.log('API Error:', error.statusCode, error.message);
  }

  // Check if error is retryable
  if (isRetryableError(error)) {
    console.log('This error can be retried');
  }
}

Frontend Usage (React/Vue/etc.)

The SDK works in the browser. For frontend apps, you can generate proof chains:

// React example
import { KronosClient } from '@krisadamstv/kronos-paas';

const client = new KronosClient({
  apiKey: process.env.REACT_APP_KRONOS_API_KEY!
});

// Generate proof when user starts typing
const handleStartTyping = async () => {
  const startProof = await client.generateKronos();
  setStartProof(startProof);
};

// Generate proof when user finishes
const handleSubmit = async (content: string) => {
  const hash = await sha256(content);
  const endProof = await client.generateChronos(hash);
  
  // Send both proofs to your backend for audit trail
  await api.saveDocument({
    content,
    startProof,
    endProof,
  });
};

Type Definitions

All types are exported for TypeScript users:

import type { 
  Proof, 
  Receipt, 
  ProvenanceProof,
  CrabAppendix,
  TimeInfo, 
  VerifyResponse,
  KronosClientOptions 
} from '@krisadamstv/kronos-paas';

License

MIT