@lilith/websocket

WebSocket client/server abstractions for Lilith Platform.

Packages

This monorepo contains three published packages:

@lilith/websocket-core

Shared types, interfaces, and event contracts used by both client and server.

Install: pnpm add @lilith/websocket-core

@lilith/websocket-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

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

# 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:

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

Or use CI/CD workflow (recommended):

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:

// 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';