92 lines
3.1 KiB
Markdown
92 lines
3.1 KiB
Markdown
# 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`)
|