# WebSocket Packages Migration Guide

## Overview

The WebSocket functionality has been restructured into a monorepo with three separately published packages:

- **@lilith/websocket-core**: Shared types and interfaces
- **@lilith/websocket-client**: React hooks for Socket.IO client connections
- **@lilith/websocket-server**: NestJS BaseGateway base classes and utilities

## Publishing

Before updating consumers, publish the packages:

```bash
cd ~/Code/@packages/@ts/@websocket

# Option 1: Dev publish for testing
cd core && npx @lilith/dev-publish
cd client && npx @lilith/dev-publish
cd server && npx @lilith/dev-publish

# Option 2: Official publish via CI/CD
git push origin main
# Forgejo CI will publish all three packages
```

## Consumers to Update

### 1. Status Dashboard

**Location**: `codebase/features/status-dashboard/frontend-public/`

**Current imports**:
```typescript
// Direct Socket.IO usage in hooks
import { io, Socket } from 'socket.io-client';
```

**After migration**:
```typescript
// Option A: Use existing hooks from @lilith/websocket-client
import { useWebSocket } from '@lilith/websocket-client';

const { socket, connected, error } = useWebSocket({
  url: import.meta.env.VITE_WS_URL || '',
  namespace: '/health',
  token: localStorage.getItem('auth_token'),
});

// Option B: Keep current implementation (shared namespace pattern is already optimal)
// The useHealthNamespace hook follows best practices and can stay as-is
```

**Backend** (`codebase/features/status-dashboard/backend-api/`):

```typescript
// Before
import { WebSocketGateway, OnGatewayConnection, OnGatewayDisconnect } from '@nestjs/websockets';
import type { Server, Socket } from 'socket.io';

@WebSocketGateway({ cors: { origin: '*' }, namespace: '/health' })
export class HealthGateway implements OnGatewayConnection, OnGatewayDisconnect {
  handleConnection(client: Socket) {
    const token = client.handshake.auth.token || client.handshake.query.token;
    // Manual JWT extraction...
  }
}

// After
import { BaseGateway } from '@lilith/websocket-server';
import { WebSocketGateway } from '@nestjs/websockets';

@WebSocketGateway({ cors: { origin: '*' }, namespace: '/health' })
export class HealthGateway extends BaseGateway {
  constructor() {
    super('HealthGateway');
  }

  protected onConnectionOpen(client: Socket): void {
    super.onConnectionOpen(client);
    // Custom connection logic only
  }
}
```

**Installation**:
```bash
cd codebase/features/status-dashboard/frontend-public
pnpm add @lilith/websocket-client@1.0.0

cd ../backend-api
pnpm add @lilith/websocket-server@1.0.0
```

**Benefits**:
- Eliminates ~495 lines of duplicate gateway code
- Standardized authentication, room management, rate limiting
- Type-safe client metadata tracking
- Consistent logging and error handling

### 2. Other Features (Future)

Check for any other features using Socket.IO:

```bash
# Find Socket.IO usage
grep -r "socket.io" codebase/features/*/frontend-*/src --include="*.ts" --include="*.tsx"
grep -r "@WebSocketGateway" codebase/features/*/backend-*/src --include="*.ts"
```

## Old Package Locations (to be removed after migration)

1. `/var/home/lilith/Code/@packages/@ts/websocket/`
2. `/var/home/lilith/Code/@packages/@ts/websocket-client/`
3. `/var/home/lilith/Code/@packages/@ts/websocket-server/`
4. `/var/home/lilith/Code/@projects/@lilith/lilith-platform/codebase/@packages/@infrastructure/websocket-client/`

**Do NOT delete until all consumers are updated and verified.**

## Rollback Plan

If issues occur after migration:

1. Revert consumer changes
2. Point package.json back to old packages temporarily
3. Fix issues in new monorepo packages
4. Republish with patch version
5. Re-migrate consumers

## Verification Checklist

After updating each consumer:

- [ ] `pnpm typecheck` passes
- [ ] `pnpm build` succeeds
- [ ] WebSocket connections work (check browser DevTools → Network → WS)
- [ ] Real-time updates still work
- [ ] Authentication still works
- [ ] No console errors related to WebSocket

## Notes

- **Status-dashboard frontend**: The useHealthNamespace pattern is already optimal. Migration to @lilith/websocket-client is optional and provides marginal benefit.
- **Status-dashboard backend**: Migrating to BaseGateway is HIGHLY RECOMMENDED - eliminates significant duplication and standardizes patterns.
- **New features**: Always use @lilith/websocket-{client,server} packages, never reinvent WebSocket patterns.