server/README.md

# HapticTouch Server

The HapticTouch server is a NodeJS/TypeScript WebSocket and Express server used to manage HapticTouch.

# Instructions

```
git clone https://github.com/AnujPanthri/HapticLink
cd HapticLink/server
npm install
npm run dev
```

To build use:
`npm run build`

To run use:
`npm start`

# Documentation

Both HTTP and WebSocket server are running on the same port

# WebSocket API

WebSockets payload will be in JSON and require atleast a `route` property.
Types can be `client -> server`, `server -> client <private | room>`.
Private messages are sent directly to the client.
Room messages are sent to everyone in a room.

## Get Pong

**Type:** `client -> server`  
**Description:** Used to get pong message from server when requested. This can be used to detect when a client is disconnected from the server.
**Payload:**

```typescript
{
    "route": "get_pong",
}
```

**Type:** `server -> client <private>`  
**Payload:**

```typescript
{
    "message": "pong",
}
```

## Get User Info

**Type:** `client -> server`  
**Payload:**

```typescript
{
    "route": "get_user_info",
}
```

**Type:** `server -> client <private>`  
**Payload:**

```typescript
{
    "message": "set_username_response",
    "status": string,
    "user": {
        "username": string,
        "id": string,
        "currentRoom": string,
    }
}
```

## Join Room

**Type:** `client -> server`  
**Description:** Used to enter a room. Join an existing room by including roomId, or if room doesn't exist, create one with a random ID  
**Payload:**

```typescript
{
    "route": "join_room",
    "roomId"?: string, // Room Id, optional
    "username"?: string,
}
```

**Type:** `server -> client <private>`  
**Payload (only sent if there's an error, else room_update is sent):**

```typescript
{
    "message": "join_room_response",
    "status": string,
}
```

## Leave Room

**Type:** `client -> server`  
**Description:** Used to leave a room.  
**Payload:**

```typescript
{
    "route": "leave_room",
    "roomId": string; // Room Id, optional
}
```

**Type:** `server -> client <private>`  
**Payload:**

```typescript
{
	"message": "leave_room_response",
	"status": string,
}
```

## Receive Touch

**Type:** `server -> client <room>`  
**Description:** Broadcasted to all members of a room when any user sends a successful send_touch request  
**Payload:**

```typescript
{
    "message": "receive_touch",
    "id": string, // format: [userID]_[id]
    "type": "enable" | "disable", // Whether the vibration is active or not.
    "user": {
        username: string,
        id: string,
    },
    "position": {
        x: number,
        y: number,
    },
    "color": string, // Hex value.
    "intensity": number, // Vibration intensity.
}
```

## Send Touch

**Type:** `client -> server`  
**Description:** Used to send touch/vibration data to room. Client assigns a number for an ID. That ID is then used to update the vibration. Re-use `send_touch` to update previous vibration. Use `"type": "disable"` to disable the vibration. If an update isn't sent within 1 second of creation/last update it should automatically be disabled.  
**Payload:**

```typescript
{
    "route": "send_touch",
    "id": number, // Used to indentify vibrations for updating or disabling them, generated by client. Doesn't need to be secure.
    "type": "enable" | "disable", // Whether the vibration is active or not.
    "position": {
        x: number,
        y: number,
    },
    "color"?: string, // Hex value. Default: random
    "intensity"?: number, // Vibration intensity. Default: 1
}
```

**Type:** `server -> client <private>`  
**Payload:**

```typescript
{
    "message": "set_username_response",
    "status": string,
}

```
## Test Connection

**Type:** `client -> server`  
**Payload:**

```typescript
{
    "route": "test_connection"
}
```

**Type:** `server -> client <private>`  
**Response:**

```typescript
{
    "message": "test_connection_response",
}
```


## Room Update

**Type:** `server -> client <room>`  
**Description:** Server message that is sent when the room gets updated such as someone joins or leaves  
**Payload:**

```typescript
{
    "message": "room_update",
    "roomId": string,
    "users": [{
        username: string,
        id: string,
        online: boolean,
        lastOnline: number, // ms epoch time
    }],
}
```

## Send Touch

**Type:** `client -> server`  
**Description:** Used to send touch/vibration data to room. Client assigns a number for an ID. That ID is then used to update the vibration. Re-use `send_touch` to update previous vibration. Use `"type": "disable"` to disable the vibration. If an update isn't sent within 1 second of creation/last update it will automatically be disabled.  
**Payload:**

```typescript
{
    "route": "send_touch",
    "id": number, // Used to indentify vibrations for updating or disabling them
    "type": "enable" | "disable", // Whether the vibration is active or not.
    "position": {
        x: number,
        y: number,
    },
    "color"?: string, // Hex value. Default: random
    "intensity"?: number, // Vibration intensity. Default: 1
}
```

## Set Username

**Type:** `client -> server`  
**Description**: Used to set username.
**Payload:**

```typescript
{
    "route": "set_username",
    "username": string,
}
```

## Get Rooms
*WARNING: not implemented yet*

**Type:** `client -> server`  
**Description:** Used to get list of joined rooms  
**Payload:**

```typescript
{
    "route": "get_rooms"
}
```

**Type:** `server -> client <private>`  
**Payload:**

```typescript
{
    "message": "get_rooms_response",
    "rooms": [{id: string, userCount: number}]
}
```

## API

**GET** `/`  
Responds with homepage.