🔐 Face Scanner WebSocket Client Library

A comprehensive Node.js client library for integrating with Face Scanner WebSocket servers using secure API key authentication.

✨ Features

• 🔑 Secure API Key Authentication - Replace password-based auth with scoped API keys
• 👥 Multiple Client Types - Support for student, device, monitor, service, and admin clients
• 🔄 Auto-Reconnection - Intelligent reconnection with exponential backoff
• 📡 Real-time Events - Face scan events, device status, and system alerts
• 🏠 Smart Room Management - Automatic room joining based on client type
• ❤️ Health Monitoring - Built-in ping/pong heartbeat mechanism
• 🛡️ Security Features - Rate limiting, scoped permissions, audit logging

🚀 Quick Start

Installation

git clone https://github.com/Narakornnick135/lib-facescan-ws.git
cd lib-facescan-ws
npm install

Configuration

Copy the environment template:

cp .env.example .env

Update .env with your configuration:

# WebSocket Server
WS_URL=ws://localhost:8080/ws

# Your API tokens (get from admin interface)
STUDENT_TOKEN=your-student-token-here
DEVICE_TOKEN=your-device-token-here

# Client Information
STUDENT_ID=your-student-id
SCHOOL_ID=your-school-id

Basic Usage

Student Client

const WebSocketClient = require('./lib/client/WebSocketClient');

const studentClient = WebSocketClient.createStudentClient({
  wsUrl: process.env.WS_URL,
  apiKey: process.env.STUDENT_TOKEN,
  schoolId: process.env.SCHOOL_ID,
  studentId: process.env.STUDENT_ID
});

studentClient.on('authenticated', () => {
  console.log('✅ Connected and ready to receive notifications');
});

studentClient.on('faceDetected', (data) => {
  console.log('👤 Your face was detected!', data);
});

await studentClient.connect();

Device Client

const deviceClient = WebSocketClient.createDeviceClient({
  wsUrl: process.env.WS_URL,
  apiKey: process.env.DEVICE_TOKEN,
  schoolId: process.env.SCHOOL_ID,
  deviceId: process.env.DEVICE_ID
});

// Send face scan event
deviceClient.sendFaceScanEvent('face_detected', {
  studentId: 'student123',
  confidence: 0.95,
  timestamp: Date.now()
});

📚 Client Types

| Client Type | Purpose | Authentication | Permissions | |-------------|---------|----------------|-------------| | Student | Receive personal notifications | API Key | Own events only | | Device | Face scanning devices | API Key | Send scan events | | Monitor | Real-time dashboards | API Key | School monitoring | | Service | Backend integrations | API Key | Cross-school events | | Admin | System management | JWT Token | Full system access |

🧪 Testing

Run Tests

# Individual tests
npm run test:student:simple
npm run test:student:listen

# Direct execution
node examples/student-client.js
node tests/test-student-simple.js

Run All Examples

# Student notifications
node examples/student-client.js

# Device scanner simulation  
node examples/device-client.js

# Real-time monitoring
node examples/monitor-client.js

# Complete integration demo
node examples/complete-integration.js

📖 Documentation

• Complete Test Report - Comprehensive testing guide
• Testing Guide - Step-by-step testing instructions
• Examples README - All example implementations
• Migration Guide - Upgrade from password auth

🔧 API Reference

WebSocketClient Methods

// Factory methods for different client types
WebSocketClient.createStudentClient(options)
WebSocketClient.createDeviceClient(options) 
WebSocketClient.createMonitorClient(options)
WebSocketClient.createServiceClient(options)
WebSocketClient.createAdminClient(options)

// Connection management
await client.connect()
client.disconnect()
client.getConnectionStatus()

// Messaging
client.send(message)
client.sendPingMessage()
client.sendFaceScanEvent(type, data) // Device clients

// Room management (non-student clients)
client.joinRoom(roomName)
client.leaveRoom(roomName)

// Admin functions
client.requestStats() // Admin only
client.kickClient(clientId, reason) // Admin only

Events

// Connection events
client.on('connected', () => {})
client.on('authenticated', () => {})
client.on('disconnected', ({ code, reason }) => {})
client.on('authError', (error) => {})

// Face scan events
client.on('faceDetected', (data) => {})
client.on('scanComplete', (data) => {})
client.on('noFace', (data) => {})
client.on('faceError', (data) => {})

// System events
client.on('systemAlert', (data) => {})
client.on('roomUpdate', (data) => {})
client.on('pong', () => {})

🔐 Security Features

API Key Scoping

• Each client type has specific permissions
• Keys can be scoped to specific schools/devices
• Automatic expiration support

Student Privacy Protection

• Students only receive events for their own ID
• Cannot manually join other rooms
• All connections logged for audit

Rate Limiting

• Automatic rate limiting per API key
• Configurable limits per client type
• Prevents abuse and DoS attacks

🏗️ Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Student App   │    │  Device Scanner │    │   Dashboard     │
│                 │    │                 │    │                 │
└─────────┬───────┘    └─────────┬───────┘    └─────────┬───────┘
          │                      │                      │
          │ Student Client       │ Device Client        │ Monitor Client
          │                      │                      │
          └──────────────────────┼──────────────────────┘
                                 │
                    ┌─────────────▼──────────────┐
                    │                            │
                    │   WebSocket Server         │
                    │   (Face Scanner API)       │
                    │                            │
                    └────────────────────────────┘

🚦 Room Structure

• global - Public events for all clients
• school:{schoolId} - School-specific events
• device:{schoolId}:{deviceId} - Device-specific events
• student:{schoolId}:{studentId} - Student-specific events (auto-joined)

🔄 Migration from Password Auth

Use the interactive migration tool:

node migrate-to-api-keys.js

This will:

1. Analyze your existing clients
2. Generate API key creation commands
3. Create updated configuration files
4. Provide step-by-step migration guide

📊 Configuration

Environment Variables (.env)

# Server Configuration
WS_URL=ws://localhost:8080/ws

# Authentication Tokens
STUDENT_TOKEN=your-token-here
DEVICE_TOKEN=your-token-here
MONITOR_TOKEN=your-token-here

# Client Information
STUDENT_ID=std12345
SCHOOL_ID=sch001
DEVICE_ID=device456

# Connection Settings
HEARTBEAT_INTERVAL=30000
RECONNECT=true
MAX_RECONNECT_ATTEMPTS=10

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

📝 License

MIT License - see LICENSE file for details.

🛠️ Built With

• Node.js - JavaScript runtime
• ws - WebSocket client implementation
• dotenv - Environment variable management
• Claude Code - AI-assisted development

📞 Support

• GitHub Issues - Bug reports and feature requests
• Documentation - Check the /docs folder
• Examples - See /examples for usage patterns

🎯 Roadmap

• [ ] TypeScript definitions
• [ ] React/Vue.js integration examples
• [ ] Metrics and monitoring dashboard
• [ ] Mobile SDK (React Native)
• [ ] Load balancing support

⭐ Star this repo if it helps you!

Built with ❤️ using Claude Code