websocket/README.md

# @lilith/websocket

WebSocket client/server abstractions for Lilith Platform.

## Packages

This monorepo contains three published packages:

### [@lilith/websocket-core](./core)
Shared types, interfaces, and event contracts used by both client and server.

**Install**: `pnpm add @lilith/websocket-core`

### [@lilith/websocket-client](./client)
React hooks and utilities for Socket.IO client connections.

**Install**: `pnpm add @lilith/websocket-client`

**Features**:
- Shared namespace connection management
- Auto-reconnection with exponential backoff
- JWT authentication
- TypeScript event contracts

### [@lilith/websocket-server](./server)
NestJS WebSocket gateway base classes and utilities.

**Install**: `pnpm add @lilith/websocket-server`

**Features**:
- BaseGateway abstract class (lifecycle, auth, broadcasting)
- Client metadata tracking
- Rate limiting per-client, per-event
- JWT token extraction

## Development

```bash
# Install dependencies
pnpm install

# Build all packages
pnpm build

# Watch mode (all packages in parallel)
pnpm dev

# Type checking
pnpm typecheck

# Run tests
pnpm test
```

## Publishing

Each package publishes independently to `forge.black.lan`:

```bash
# From package directory
cd core && pnpm publish
cd client && pnpm publish
cd server && pnpm publish
```

Or use CI/CD workflow (recommended):

```bash
git push origin master  # Triggers publish.yml workflow
# Requires NPM_TOKEN secret configured in repository settings
```

## Architecture

```
@websocket/
├── core/          → @lilith/websocket-core (types)
├── client/        → @lilith/websocket-client (React hooks)
└── server/        → @lilith/websocket-server (NestJS gateways)
```

## Migration from Old Packages

**Old locations** (deprecated):
- `codebase/@packages/@infrastructure/websocket-client/`
- `@packages/@ts/websocket/`
- `@packages/@ts/websocket-server/`

**New imports**:
```typescript
// Core types
import type { HealthEvents, ClientMetadata } from '@lilith/websocket-core';

// Client hooks (React)
import { useNamespace } from '@lilith/websocket-client';

// Server gateway (NestJS)
import { BaseGateway } from '@lilith/websocket-server';
```