npm package: @knock-knock/server
Description: Serverside library for knock-knock
Author: anuragrao04
Latest version: 0.0.1

# @knock-knock/server

Ultrasonic proximity detection library for real-time clustering of nearby users.

## What it does

This server-side library detects which users are physically close to each other using ultrasonic frequencies (17-20 kHz). It manages WebSocket connections, assigns unique frequencies to users, processes proximity data, and clusters users based on mutual frequency detection.

Key features:
- Assigns unique ultrasonic frequencies to users within sessions
- Processes frequency detection data from clients
- Clusters users based on mutual proximity detection
- Real-time WebSocket communication and updates
- Session isolation (different sessions can reuse frequencies)

## Use Cases

**Meeting & Collaboration**
- Automatically group meeting participants by location
- Create breakout rooms based on physical proximity
- Detect when remote participants are actually in the same room

**Events & Networking**
- Connect nearby attendees at conferences or events
- Facilitate spontaneous networking opportunities
- Group people for activities or discussions

**Gaming & Social**
- Proximity-based multiplayer games
- Social apps that connect people in the same space
- Location-aware features without GPS

**Workplace & Education**
- Team formation based on physical proximity
- Classroom interaction and group activities
- Office space utilization and collaboration tracking

## How it works

1. **Session Creation**: Users join sessions via WebSocket connections
2. **Frequency Assignment**: Each user receives a unique ultrasonic frequency (17-20 kHz)
3. **Audio Processing**: Client devices emit assigned frequencies and listen for others
4. **Detection Reporting**: Clients send frequency detection data to the server
5. **Mutual Verification**: Server verifies bidirectional detection between users
6. **Clustering**: Graph-based algorithm groups users who mutually detect each other
7. **Real-time Updates**: Proximity changes are broadcast to all session participants

## Installation

```bash
npm install @knock-knock/server
```

## Basic Usage

```typescript
import { KnockKnockServer } from '@knock-knock/server';

// Initialize server with frequency range (Hz) and spacing
const server = new KnockKnockServer(17800, 19200, 100); // 15 users max

// Handle WebSocket connections
server.handleConnection(websocket, 'user123', 'session-abc');

// Get proximity clusters
const allUsers = server.getUsers('session-abc');          // [['user1'], ['user2', 'user3']]
const nearby = server.getUsersTogetherOnly('session-abc'); // [['user2', 'user3']]
```

## Frontend Integration

> **Note**: A companion frontend library `@knock-knock/browser` is in development to handle audio processing, microphone/speaker operations, and WebSocket communication. This server library is designed to work with that client library.

Your client needs to:

```typescript
// Send frequency detections to server
websocket.send(JSON.stringify({
  type: 'frequency_heard',
  data: {
    frequency: 17900,
    amplitude: 0.8,
    confidence: 0.95
  }
}));

// Receive proximity updates
websocket.on('message', (data) => {
  const message = JSON.parse(data);
  if (message.type === 'proximity_update') {
    console.log('Nearby users:', message.data.nearbyUsers);
  }
});
```

## API Reference

### `KnockKnockServer(frequencyLower, frequencyUpper, spacing)`
- `frequencyLower`: Minimum frequency (Hz)
- `frequencyUpper`: Maximum frequency (Hz)  
- `spacing`: Frequency spacing between users (Hz)

### Methods
- `handleConnection(websocket, userId, sessionId)` - Handle new user connection
- `getUsers(sessionId)` - Get all user clusters in session
- `getUsersTogetherOnly(sessionId)` - Get multi-user clusters only
- `getMaxUsersPerSession()` - Calculate max users based on frequency range

## Requirements

- WebSocket server (ws, socket.io, etc.)
- Client-side audio frequency detection and emission
- Ultrasonic speaker/microphone capability on client devices

## License

MIT