npm package: @suhbro/core
Description: Framework-agnostic library for encoding/decoding shareable message chains
Latest version: 1.2.0

# @suhbro/core

A framework-agnostic TypeScript library for encoding/decoding shareable message chains.

## Installation

```bash
npm install @suhbro/core
```

## Features

- **Chain Encoding** - DEFLATE-raw compression + base64url for URL-safe chains
- **Encryption** - AES-256-GCM with PBKDF2 (100k iterations)
- **Signatures** - djb2 hash for content-bound identity
- **Polls** - Distributed voting with vote tallying
- **Chaos Engine** - Seeded random greeting generator

## Requirements

- Node.js 20+ or modern browser with Web Crypto API and CompressionStream support

## Usage

### Chain Encoding/Decoding

```typescript
import { createChain, encodeChain, decodeChain, addReplyToChain } from '@suhbro/core';

// Create a chain (with optional timestamp)
const node = createChain({
  title: 'Hello World',
  description: 'My first chain',
  passphrase: 'secret123',
  timestamp: Date.now()
});

// Encode to URL-safe string
const encoded = await encodeChain([node]);

// Decode back
const { nodes } = await decodeChain(encoded);

// Add a reply
const withReply = await addReplyToChain({
  payload: encoded,
  title: 'Reply',
  description: 'This is a reply'
});
```

### Encryption

```typescript
import { encryptNode, decryptNode } from '@suhbro/core';

const node = { t: 'Secret Message', d: 'Confidential content' };

// Encrypt
const encrypted = await encryptNode(node, 'password123');

// Decrypt
const decrypted = await decryptNode(encrypted, 'password123');
```

### Signatures

```typescript
import { generateNodeSignature, verifyNodeSignature, getAuthorFingerprint } from '@suhbro/core';

const node = { t: 'Signed content' };
const passphrase = 'my-secret';

// Generate signature
node.s = generateNodeSignature(passphrase, node);

// Verify signature
const isValid = verifyNodeSignature(passphrase, node);

// Get author fingerprint (4-char ID)
const fingerprint = getAuthorFingerprint(passphrase);
```

### Polls

```typescript
import { createPoll, addVote, getPollResults, encodeChain } from '@suhbro/core';

// Create a poll
const poll = createPoll('Favorite color?', ['Red', 'Blue', 'Green']);
let encoded = await encodeChain([poll]);

// Add votes
encoded = await addVote(encoded, 0, 'Alice');
encoded = await addVote(encoded, 1, 'Bob');

// Get results
const results = await getPollResults(encoded);
// { question: 'Favorite color?', options: [...], counts: [1, 1, 0], total: 2 }
```

### Chaos Engine

```typescript
import { generateFromSeed, generateFromCategory, getCategories } from '@suhbro/core';

// Generate deterministic greeting from seed
const greeting = generateFromSeed('user-123');

// Generate from specific category
const formalGreeting = generateFromCategory('user-123', 'formal');

// Available categories
const categories = getCategories();
// ['casual', 'warm', 'hype', 'silly', 'formal', 'cosmic', 'internet', 'animal']
```

## API Reference

### Chain

| Function | Description |
|----------|-------------|
| `createChain(options)` | Create a new chain node |
| `encodeChain(nodes)` | Compress nodes to URL-safe string |
| `decodeChain(encoded)` | Decompress back to ChainData |
| `addReplyToChain(options)` | Add a reply to existing chain |

### Encryption

| Function | Description |
|----------|-------------|
| `encryptNode(node, passcode)` | Encrypt a node with AES-256-GCM |
| `decryptNode(node, passcode)` | Decrypt an encrypted node |

### Signatures

| Function | Description |
|----------|-------------|
| `generateNodeSignature(passphrase, node, parentHash?)` | Generate djb2 signature |
| `verifyNodeSignature(passphrase, node, parentHash?)` | Verify signature |
| `getAuthorFingerprint(passphrase)` | Get stable 4-char author ID |

### Polls

| Function | Description |
|----------|-------------|
| `createPoll(question, options, passphrase?)` | Create a poll node |
| `addVote(payload, voteIndex, voterName?, passphrase?)` | Add vote to chain |
| `getPollResults(payload)` | Get vote counts |

### Chaos Engine

| Function | Description |
|----------|-------------|
| `generateFromSeed(seed)` | Deterministic greeting from seed |
| `generateFromCategory(seed, category)` | Greeting from specific category |
| `getCategories()` | List all 8 categories |

## Development

```bash
# Install dependencies
npm install

# Run tests
npm test

# Build
npm run build

# Watch mode
npm run dev
```

## License

MIT