@supernick135/face-scanner-client/README.md

Node.js client library for ZKTeco face scanning devices integration with comprehensive API support

# 🔐 Face Scanner WebSocket Client Library

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

![Node.js](https://img.shields.io/badge/node-%3E%3D16.0.0-brightgreen.svg)
![WebSocket](https://img.shields.io/badge/WebSocket-RFC%206455-blue.svg)
![License](https://img.shields.io/badge/license-MIT-green.svg)

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

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

### Configuration

Copy the environment template:
```bash
cp .env.example .env
```

Update `.env` with your configuration:
```env
# 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
```javascript
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
```javascript
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
```bash
# 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
```bash
# 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](./COMPLETE-TEST-REPORT.md)** - Comprehensive testing guide
- **[Testing Guide](./TESTING-GUIDE.md)** - Step-by-step testing instructions  
- **[Examples README](./examples/README.md)** - All example implementations
- **[Migration Guide](./migrate-to-api-keys.js)** - Upgrade from password auth

## 🔧 API Reference

### WebSocketClient Methods

```javascript
// 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

```javascript
// 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:
```bash
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)
```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](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!**