hotel_pi/API.md

# API Reference

## Frontend Environment Variables

```bash
# Directus CMS endpoint
VITE_API_URL=http://localhost:8055

# Control service WebSocket
VITE_WS_URL=ws://localhost:3001

# Welcome message on idle screen
VITE_WELCOME_NAME=Guest

# Auto-return to idle after (minutes)
VITE_IDLE_TIMEOUT=5
```

## Control Service API

### WebSocket Messages

The control service listens on `ws://localhost:3001`

#### Client → Server

```json
{
  "type": "launch-plex",
  "payload": {}
}
```

```json
{
  "type": "return-to-kiosk",
  "payload": {}
}
```

```json
{
  "type": "restart-kiosk",
  "payload": {}
}
```

```json
{
  "type": "execute",
  "payload": {
    "command": "ls -la /tmp"
  }
}
```

#### Server → Client

```json
{
  "type": "connected",
  "payload": {
    "timestamp": "2024-03-20T12:34:56Z"
  }
}
```

```json
{
  "type": "input",
  "payload": {
    "type": "up"
  }
}
```

Input event types:
- `up`, `down`, `left`, `right` - Navigation
- `select` - Confirm selection
- `back` - Go back

### HTTP Endpoints

**Health Check**
```bash
GET http://localhost:3001/health

{
  "status": "healthy",
  "timestamp": "2024-03-20T12:34:56Z",
  "processes": ["plex"]
}
```

## Directus API

### Collections

#### Restaurants

```bash
GET http://localhost:8055/items/restaurants?fields=*,image.*

[
  {
    "id": "uuid",
    "name": "La Bella Vita",
    "description": "Italian cuisine",
    "cuisine_type": "Italian",
    "website_url": "https://example.com",
    "phone": "+1-555-0123",
    "image": {
      "id": "file-id",
      "filename_disk": "restaurant.jpg"
    },
    "status": "published"
  }
]
```

#### Attractions

```bash
GET http://localhost:8055/items/attractions?fields=*,image.*

[
  {
    "id": "uuid",
    "name": "City Museum",
    "description": "World-class art",
    "category": "Museum",
    "distance_km": 2.5,
    "image": {
      "id": "file-id",
      "filename_disk": "museum.jpg"
    },
    "website_url": "https://example.com",
    "hours": "10 AM - 6 PM",
    "status": "published"
  }
]
```

### Get Images

```bash
# Direct image URL
http://localhost:8055/assets/{filename}

# Example
http://localhost:8055/assets/restaurant-12345.jpg
```

## Frontend Store API

```javascript
import {
  currentScreen,      // 'idle' | 'home' | 'restaurants' | 'attractions'
  selectedIndex,      // Currently selected menu item index
  restaurants,        // Array of restaurant items
  attractions,        // Array of attraction items
  wsConnected,        // Boolean - WebSocket connection status
  pushScreen,         // (screen) => void
  popScreen,          // () => void
  resetNavigation,    // () => void
} from '$lib/store.js';
```

## CMS Integration

### Fetch Data

```javascript
import { fetchRestaurants, fetchAttractions } from '$lib/api.js';

const restaurants = await fetchRestaurants();
const attractions = await fetchAttractions();
```

### Generate QR Codes

```javascript
import { generateQRCode } from '$lib/qrcode.js';

const qrDataUrl = await generateQRCode('https://example.com');
// Returns: data:image/png;base64,...
```

### WebSocket Connection

```javascript
import WebSocketManager from '$lib/websocket.js';

const ws = new WebSocketManager('ws://localhost:3001');

ws.on('connected', () => console.log('Connected'));
ws.on('input', (data) => console.log('Input:', data));

ws.connect();
ws.send('launch-plex');
```

## System Commands

### Launch Scripts

```bash
# Start kiosk
./scripts/launch-kiosk.sh

# Launch Plex
./scripts/launch-plex.sh

# Return to kiosk
./scripts/return-to-kiosk.sh

# Initialize system (Raspberry Pi)
./scripts/init-system.sh

# Rebuild services
./scripts/rebuild.sh

# Stop services
./scripts/stop.sh

# View logs
./scripts/logs.sh [service]

# Control service CLI
./scripts/control.sh [command]
```

## Docker Compose Services

```bash
# Start all services
docker-compose up -d

# Stop all services
docker-compose down

# View status
docker-compose ps

# View logs
docker-compose logs -f [service]

# Services:
# - postgres       (Database)
# - directus       (CMS)
# - frontend       (Kiosk UI)
# - control-service (Remote control)
```

## Environment Configuration

### Root .env

```bash
# Frontend
VITE_API_URL=http://localhost:8055
VITE_WS_URL=ws://localhost:3001
WELCOME_NAME=Guest
IDLE_TIMEOUT_MINUTES=5

# Control Service
PORT=3001
CEC_DEVICE=/dev/ttyAMA0
PLEX_LAUNCH_COMMAND=/usr/bin/plex-htpc
KIOSK_LAUNCH_COMMAND=/home/pi/scripts/launch-kiosk.sh

# Directus
DATABASE_URL=postgresql://directus:directus123@postgres:5432/directus
SECRET=your-secret-key
AUTH_SECRET=your-auth-secret
DB_CLIENT=postgres
DB_HOST=postgres
DB_PORT=5432
DB_DATABASE=directus
DB_USER=directus
DB_PASSWORD=directus123
CORS_ORIGIN=http://localhost:5173

# Postgres
POSTGRES_USER=directus
POSTGRES_PASSWORD=directus123
POSTGRES_DB=directus
```

## Error Handling

### Common HTTP Status Codes

- `200` - Success
- `404` - Not found (collection doesn't exist)
- `401` - Unauthorized (authentication required)
- `500` - Server error

### WebSocket Errors

```json
{
  "type": "error",
  "payload": {
    "message": "Command failed"
  }
}
```

## Rate Limits

No rate limits configured by default. Configure in production:

**Directus:**
- Settings → Project Settings → Rate Limiting

**Control Service:**
- Implement in `server.js` middleware