npm package: @krisadamstv/kronos-paas
Description: TypeScript/JavaScript SDK for Kronos Proof-as-a-Service - Generate cryptographic temporal proofs
Author: Kris Adams
Latest version: 1.0.0

# Kronos TypeScript SDK

Official TypeScript/JavaScript client library for [Kronos Proof-as-a-Service](https://proofapi.krisadamstv.com).

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

## Installation

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

## Quick Start

```typescript
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

```typescript
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:

```typescript
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:

```typescript
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)

```typescript
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

```typescript
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

```typescript
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

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

## Error Handling

The SDK provides typed errors for common scenarios:

```typescript
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:

```typescript
// 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:

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

## License

MIT