# Specification: Aether V3 API Device Config Payload

**Endpoint:** `GET /v3/crud/event_device/{id_random}?view=native_bootstrap`
**Goal:** Provide full operational context to an Electron instance with zero local configuration.

## 1. Response Structure (Draft)

```json
{
  "status": "success",
  "data": {
    "identity": {
      "device_id_random": "GZvFjgIIZQg",
      "device_code": "macbook_air_scott_idem",
      "account_id_random": "xFP7AhU8Zlc",
      "event_id_random": "UFu-gF-rZ-ws",
      "location_id_random": "PFGP-37-81-80"
    },
    "network": {
      "api_base_url": "https://api.oneskyit.com",
      "file_server_url": "https://files.oneskyit.com",
      "heartbeat_interval_ms": 30000
    },
    "filesystem": {
      "cache_path": "[home]/Library/Caches/OSIT/file_cache",
      "temp_path": "[home]/tmp/OSIT/temp",
      "use_sharding": true,
      "verify_on_launch": true
    },
    "launcher": {
      "app_mode": "native",
      "auto_start_slideshow": true,
      "prevent_sleep": true,
      "whitelisted_apps": ["PowerPoint", "Keynote", "Acrobat Reader"]
    },
    "ui_prefs": {
      "theme_name": "cerberus",
      "theme_mode": "dark",
      "show_clock": true,
      "show_admin_tools": false
    }
  }
}
```

## 2. Key Payload Fields

### 2.1 Identity & Scoping
- `account_id_random`: Automatically scopes all subsequent V3 API calls for the SvelteKit UI.
- `location_id_random`: Locks the UI to a specific room/podium.

### 2.2 Filesystem Strategy
- `cache_path`: Uses the `[home]` placeholder. The Electron Main process will resolve this to the local user profile.
- `use_sharding`: Tells the Sync Engine to use the `/ab/abcdef...` directory structure.

### 2.3 Automation Whitelist
- To prevent security risks, the `launcher` object defines exactly which applications the native shell is allowed to "Kill" or "Open".

## 3. Telemetry & Heartbeat (Push Strategy)
To support the onsite dashboard (`src/routes/events/.../device`), the Electron app must push its status back to the server.

### 3.1 Heartbeat Payload (`PATCH /v3/crud/event_device/{id}`)
```json
{
  "heartbeat": "2026-01-20T14:30:00Z",
  "status": "Online",
  "status_msg": "Presentation: 'Introduction to AE.pptx' (Slide 4/20)",
  "record_status": "Idle",
  "info_ip_list": "192.168.1.10, 10.0.0.5",
  "meta_json": {
    "cpu_usage": 12,
    "memory_free_gb": 4.2,
    "sync_progress": 100,
    "foreground_app": "PowerPoint",
    "is_fullscreen": true
  }
}
```

## 4. The "Bootstrap Paradox" Resolution
To allow unauthenticated config fetching for new devices:
1.  **Device API Key:** Each device record in the DB has an `api_secret_key`.
2.  **Initial Header:** The Electron app sends `x-aether-device-key: <key>` in the bootstrap request.
3.  **JWT Hand-off:** The response `meta` will contain a short-lived JWT that the app uses to authenticate its first "Real" V3 requests.

## 5. Database Mapping (V3 Enriched View)
The `v_event_device` SQL view must be updated to include:
- `account_id_random` (joined from `account`)
- `event_id_random` (joined from `event`)
- `location_id_random` (joined from `event_location`)
- `theme_name` (joined from `site_cfg_json` via `account`)