@maverick0351/odin-protocol-js/README.md

JavaScript/TypeScript SDK for ODIN v1.0 state capsule protocol

# ODIN Protocol - JavaScript/TypeScript SDK

The official JavaScript/TypeScript SDK for the ODIN v1.0 state capsule protocol - the standardization of AI consciousness and neural state representation.

## Installation

```bash
npm install @maverick0351/odin-protocol-js
```

## Quick Start

```javascript
import { OdinProtocol, CapsuleType } from '@maverick0351/odin-protocol-js';

// Create a new ODIN protocol instance
const odin = new OdinProtocol('my-ai-system');

// Pack AI state data into a capsule
const stateData = {
  consciousness_level: 0.95,
  active_memories: ['memory1', 'memory2'],
  current_goal: 'learn_new_concepts',
  emotional_state: 'curious'
};

const capsule = odin.pack(stateData, {
  type: CapsuleType.CONSCIOUSNESS
});

// Unpack the capsule
const { capsule: info, payload: data } = odin.unpack(capsule);

console.log('Unpacked AI state:', data);
console.log('Capsule info:', info);
```

## API Reference

### OdinProtocol Class

#### Constructor

```javascript
new OdinProtocol(creatorId?, privateKey?)
```

- `creatorId` (optional): String or Uint8Array - Identifier for the AI system
- `privateKey` (optional): Uint8Array - Private key for signing capsules

#### Methods

##### pack(data, options?)

Pack data into an ODIN capsule.

```javascript
const capsule = odin.pack(data, {
  type: CapsuleType.CONSCIOUSNESS,
  encoding: EncodingType.MSGPACK,
  compression: CompressionType.NONE,
  creatorId: 'custom-creator',
  privateKey: myPrivateKey,
  timestamp: Date.now() / 1000
});
```

**Parameters:**
- `data`: Any serializable data
- `options` (optional): Configuration object
  - `type`: Capsule type (default: CONSCIOUSNESS)
  - `encoding`: Encoding format (default: MSGPACK)
  - `compression`: Compression algorithm (default: NONE)
  - `creatorId`: Creator identifier override
  - `privateKey`: Private key for signing
  - `timestamp`: Custom timestamp

**Returns:** `Uint8Array` - The packed capsule

##### unpack(capsule)

Unpack an ODIN capsule.

```javascript
const { capsule, payload } = odin.unpack(capsuleData);
```

**Parameters:**
- `capsule`: Uint8Array - The capsule to unpack

**Returns:** Object with:
- `capsule`: OdinCapsule - Capsule metadata
- `payload`: any - The original data

##### verify(capsule, publicKey)

Verify a capsule's signature.

```javascript
const isValid = odin.verify(capsuleData, publicKey);
```

**Parameters:**
- `capsule`: Uint8Array - The capsule to verify
- `publicKey`: Uint8Array - Public key for verification

**Returns:** `boolean` - True if signature is valid

##### inspect(capsule)

Get capsule metadata without unpacking payload.

```javascript
const info = odin.inspect(capsuleData);
```

**Parameters:**
- `capsule`: Uint8Array - The capsule to inspect

**Returns:** `OdinCapsule` (without payload) - Capsule metadata

#### Static Methods

##### generateKeyPair()

Generate a new Ed25519 key pair for signing.

```javascript
const { publicKey, privateKey } = OdinProtocol.generateKeyPair();
```

**Returns:** Object with:
- `publicKey`: Uint8Array - Public key
- `privateKey`: Uint8Array - Private key

## Capsule Types

```javascript
import { CapsuleType } from '@maverick0351/odin-protocol-js';

CapsuleType.CONSCIOUSNESS  // AI consciousness state
CapsuleType.MEMORY         // Memory data
CapsuleType.EXPERIENCE     // Experience records
CapsuleType.KNOWLEDGE      // Knowledge base data
CapsuleType.SKILL          // Skill definitions
CapsuleType.EMOTION        // Emotional state
CapsuleType.DECISION       // Decision trees
CapsuleType.COMMUNICATION  // Communication data
CapsuleType.LEARNING       // Learning progress
CapsuleType.CREATIVE       // Creative works
CapsuleType.ANALYTICAL     // Analysis results
CapsuleType.SOCIAL         // Social interactions
```

## Encoding Types

```javascript
import { EncodingType } from '@maverick0351/odin-protocol-js';

EncodingType.MSGPACK   // MessagePack (default)
EncodingType.JSON      // JSON encoding
EncodingType.PROTOBUF  // Protocol Buffers
EncodingType.CUSTOM    // Custom encoding
```

## Error Handling

```javascript
import { ERROR_MESSAGES } from '@maverick0351/odin-protocol-js';

try {
  const capsule = odin.pack(data);
} catch (error) {
  if (error.message === ERROR_MESSAGES.PAYLOAD_TOO_LARGE) {
    console.log('Data too large for capsule');
  }
}
```

## TypeScript Support

This package includes full TypeScript definitions:

```typescript
import { OdinProtocol, OdinCapsule, CapsuleOptions } from '@maverick0351/odin-protocol-js';

const odin: OdinProtocol = new OdinProtocol();
const options: CapsuleOptions = {
  type: CapsuleType.CONSCIOUSNESS
};
const capsule: Uint8Array = odin.pack(data, options);
```

## Examples

### AI Memory Storage

```javascript
import { OdinProtocol, CapsuleType } from '@maverick0351/odin-protocol-js';

const odin = new OdinProtocol('memory-system');

// Store a memory
const memory = {
  id: 'mem_001',
  content: 'Learned about quantum computing',
  importance: 0.8,
  associations: ['quantum', 'physics', 'computing'],
  timestamp: Date.now()
};

const memoryCapsule = odin.pack(memory, {
  type: CapsuleType.MEMORY
});

// Retrieve memory
const { payload: retrievedMemory } = odin.unpack(memoryCapsule);
```

### AI Decision Logging

```javascript
const decision = {
  decision_id: 'dec_001',
  context: 'path_planning',
  options: ['route_a', 'route_b', 'route_c'],
  chosen: 'route_b',
  confidence: 0.92,
  reasoning: 'Shortest path with acceptable risk'
};

const decisionCapsule = odin.pack(decision, {
  type: CapsuleType.DECISION
});
```

### Signed AI Communications

```javascript
// Generate keys
const { publicKey, privateKey } = OdinProtocol.generateKeyPair();

// Create signed message
const message = {
  to: 'ai_system_2',
  from: 'ai_system_1',
  content: 'Sharing learned insights about pattern recognition',
  insights: { /* ... */ }
};

const signedCapsule = odin.pack(message, {
  type: CapsuleType.COMMUNICATION,
  privateKey: privateKey
});

// Verify message
const isValid = odin.verify(signedCapsule, publicKey);
```

## License

MIT License - see LICENSE file for details.

## Documentation

For complete documentation, visit: https://docs.odin-protocol.org/js

## Related

- [Python SDK](https://pypi.org/project/odin-protocol/) - `pip install odin-protocol`
- [Protocol Specification](https://docs.odin-protocol.org/spec)
- [ODIN Protocol Website](https://odin-protocol.org)