# Kiiroo Device Protocol

> Integration documentation for Kiiroo interactive devices via FeelConnect.

**Platform:** FeelConnect API **Connection:** Bluetooth Low Energy (BLE) via
FeelConnect

---

## Overview

Kiiroo manufactures premium interactive devices with bi-directional feedback
capabilities. Integration is typically done via the FeelConnect platform.

### Supported Devices

| Device       | Type     | Features                 |
| ------------ | -------- | ------------------------ |
| Onyx+        | Stroker  | Contracting rings        |
| Keon         | Stroker  | Linear stroke            |
| Pearl 2      | Vibrator | Touch-sensitive vibrator |
| Titan        | Stroker  | 9 contracting rings      |
| OhMiBod Fuse | Vibrator | Dual motors              |

---

## FeelConnect Integration

### Connection Flow

1. User connects device via FeelConnect app
2. FeelConnect provides connection token
3. Aphrodite uses token to control device

### Authentication

```http
POST https://api.feelconnect.io/auth/token
Content-Type: application/json

{
  "apiKey": "<kiiroo_api_key>",
  "userId": "user_abc123"
}
```

**Response:**

```json
{
  "token": "fc_token_abc123",
  "expiresIn": 3600
}
```

---

## Device Control

### Send Command

```http
POST https://api.feelconnect.io/device/command
Authorization: Bearer <fc_token>
Content-Type: application/json

{
  "deviceId": "dev_keon_abc123",
  "command": {
    "type": "stroke",
    "speed": 50,
    "position": 75,
    "duration": 500
  }
}
```

### Command Types

| Command   | Parameters                      | Description       |
| --------- | ------------------------------- | ----------------- |
| `stroke`  | `speed`, `position`, `duration` | Linear movement   |
| `vibrate` | `intensity`, `duration`         | Vibration (Pearl) |
| `stop`    | -                               | Stop all movement |

---

## Aphrodite Integration

```typescript
// libs/aphrodite/devices/src/kiiroo/service.ts
export class KiirooService extends EventEmitter {
  private baseUrl = 'https://api.feelconnect.io';
  private token: string | null = null;

  async authenticate(apiKey: string, userId: string): Promise<void> {
    const response = await fetch(`${this.baseUrl}/auth/token`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ apiKey, userId }),
    });

    const data = await response.json();
    this.token = data.token;
    this.emit('kiiroo.authenticated');
  }

  async stroke(
    deviceId: string,
    speed: number,
    position: number,
    duration: number
  ): Promise<void> {
    await this.sendCommand(deviceId, {
      type: 'stroke',
      speed: Math.min(100, Math.max(0, speed)),
      position: Math.min(100, Math.max(0, position)),
      duration,
    });
  }

  async vibrate(
    deviceId: string,
    intensity: number,
    duration: number
  ): Promise<void> {
    await this.sendCommand(deviceId, {
      type: 'vibrate',
      intensity: Math.min(100, Math.max(0, intensity)),
      duration,
    });
  }

  async stop(deviceId: string): Promise<void> {
    await this.sendCommand(deviceId, { type: 'stop' });
  }

  private async sendCommand(
    deviceId: string,
    command: Record<string, unknown>
  ): Promise<void> {
    await fetch(`${this.baseUrl}/device/command`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${this.token}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ deviceId, command }),
    });
  }
}
```

---

## Document History

| Date       | Version | Changes                      |
| ---------- | ------- | ---------------------------- |
| 2026-01-18 | 1.0.0   | Initial Kiiroo Protocol docs |
