# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is bennc-js, a TypeScript implementation of the BENNCv1 (Butlersaurus Ephemeral No NONCEnse Chat) protocol specification. It provides client functionality for a binary pub/sub messaging protocol with encryption and compression support.

## Development Commands

- `npm run build` - Compile TypeScript to JavaScript (outputs to `dist/`)
- `npm run test` - Run Jest test suite
- `npm run lint` - Check code formatting with Prettier
- `npm run format` - Format code with Prettier
- `npm install` - Install dependencies (automatically runs `tsc` via postinstall)

## Architecture

The codebase implements the BENNC protocol specification with the following structure:

### Core Files

- `src/index.ts` - Main entry point exporting all public APIs
- `src/mapping.ts` - Central registry mapping message types (0x0000-0xFFFF) to their pack/unpack functions
- `src/common.ts` - Protocol constants including `MAX_DATA_LENGTH` (1000 bytes), `DEFAULT_KEY`, and `MessageTypes` enum
- `src/messages/packet.ts` - Core packet handling with `packOutgoingPacket` and `unpackIncomingPacket` functions

### Message Types Implementation

Each BENNC message type has its own module in `src/messages/`:

- `subscribe.ts` (0x0000) - Subscribe to message types
- `basic.ts` (0x0001) - Basic encrypted chat messages  
- `userDataRequest.ts` (0x0002) - Request user information
- `userDataResponse.ts` (0x0003) - Respond with user information
- `keepalive.ts` (0x0005) - Connection keepalive messages
- `history.ts` (0xFFFE) - Message history requests
- `unsubscribe.ts` (0xFFFF) - Unsubscribe from message types

### Protocol Implementation Details

- **Binary Protocol**: Big-endian integers, UTF-8 strings
- **Message Structure**: Client sends [Type(2)|Length(2)|Data(0-1000)], Server responds [Type(2)|SenderId(4)|Length(2)|Data(0-1000)]
- **Encryption**: Uses Romulus-M AEAD (via `romulus-js` dependency) with 16-byte nonces for message types 0x0001, 0x0002, 0x0003
- **Max Data Size**: 1000 bytes including nonce for encrypted messages
- **Dependencies**: Includes local `romulus-js` cryptography implementation and `color` library for user data

### Utilities

- `src/utilities/number.ts` - Big-endian number conversion functions (`numberToUint16BE`, `numberToUint32BE`)  
- `src/utilities/smart-buffer.ts` - Buffer manipulation utility for packet construction/parsing

### Key Architecture Patterns

- **Mapping System**: Central `packers` and `unpackers` objects in `mapping.ts` provide type-safe message handling
- **Interface Separation**: `IncomingPacket` vs `OutgoingPacket` interfaces handle client/server message structure differences
- **Encryption Integration**: Encrypted message types automatically handle nonce generation and Romulus-M encryption
- **Protocol Compliance**: Strict adherence to BENNC specification including reserved sender IDs (0xFFFFFF00-0xFFFFFFFF)

The codebase serves as a complete client-side implementation for connecting to BENNC chat servers via TCP or WebSocket protocols.