OSIT-AE-API-FastAPI/documentation/GUIDE__V3_FRONTEND_API.md

# Aether API V3 Frontend Integration Guide (Svelte/TypeScript)

This guide explains how to update or create frontend functions to interact with the new **Aether API V3 CRUD** and **Action** endpoints. V3 introduces a nested URL structure, a powerful POST-based search, and specialized "Action" routes for binary data.

---

## 1. Key Differences (V2 vs V3)

| Feature            | CRUD V2 (Legacy)      | CRUD V3 (Modern)                                     |
| ------------------ | --------------------- | ---------------------------------------------------- |
| **Base Prefix**    | `/v2/crud`            | `/v3/crud`                                           |
| **List Suffix**    | Uses `/list`          | **No suffix** (e.g., `/v3/crud/journal/`)            |
| **Nested Path**    | Not supported in URL  | **Supported** (e.g., `/v3/crud/journal/{id}/entry/`) |
| **View Selection** | `tbl_alt`, `mdl_alt`  | **`view` parameter** (e.g., `?view=enriched`)        |
| **Complex Search** | Limited to GET `jp`   | **POST `/search`** (Unlimited size + Hybrid params)  |
| **Full-Text**      | Manual column names   | **Reserved `q` property** in SearchQuery             |

---

## 2. Authentication and Security (Mandatory)

As of January 2026, the V3 architecture enforces strict **Multi-Tenant Isolation** and **Machine Authorization**. Most requests require two levels of validation.

### A. The "Entry Ticket" (API Key)
**Mandatory for all requests.** Every request must provide a valid `x-aether-api-key` in the header. This identifies the application or script.

*   **Header:** `x-aether-api-key: <your_app_key>`
*   **Status Code:** `403 Forbidden` if missing, invalid, or expired.

### B. The "Visa" (Account Context)
Once the API Key is validated, you must specify the context of your request.

1.  **Standard User Access**: Provide the `x-account-id` (the random string ID).
    *   **Header:** `x-account-id: <account_id_random>`
2.  **Administrative Bypass**: For authorized scripts needing global access.
    *   **Header:** `x-no-account-id: bypass`
3.  **Guest / Anonymous Access**: Provide a **Safe Guest JWT**.
    *   **Header:** `x-aether-api-key: <your_app_key>` (No Account Header)
    *   **Query Param:** `?jwt=<guest_token>`

---

## 3. Implementing V3 CRUD Functions

### A. List & Single Object (GET)
```ts
// GET /v3/crud/journal/{id}?view=enriched
export async function get_ae_obj_v3({ api_cfg, obj_type, obj_id, view = 'default' }) {
    const endpoint = `/v3/crud/${obj_type}/${obj_id}`;
    return await get_object({ api_cfg, endpoint, params: { view } });
}
```

### B. Advanced & Hybrid Search (POST)
```ts
// POST /v3/crud/{obj_type}/search
export async function search_ae_obj_v3({ api_cfg, obj_type, search_query, enabled = 'enabled' }) {
    const endpoint = `/v3/crud/${obj_type}/search`;
    return await post_object({ api_cfg, endpoint, params: { enabled }, data: search_query });
}
```

---

## 4. Hosted File Management (Modern V3 Actions)

V3 uses specialized **"Action"** routes for binary operations to separate processing logic from standard metadata CRUD.

### A. Upload Action
**Path**: `POST /v3/action/hosted_file/upload`
**Format**: `multipart/form-data`

| Field | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `file_list` | File[] | Yes | One or more files to upload. |
| `account_id` | String | Yes | Random ID of the owner account. |
| `link_to_type`| String | Yes | Object type to link (e.g., `archive_content`). |
| `link_to_id`  | String | Yes | Random ID of the object to link. |

**Query Parameters:**
- `allowed_extensions`: Whitelist check (e.g., `?allowed_extensions=png&allowed_extensions=jpg`).
- `delay_ms`: Simulate network delay for UI testing.

**Features:**
- **Automatic Deduplication:** API checks SHA256 hashes. If a file exists on the server, it reuses the record and creates a new link instead of a duplicate upload.
- **Relational Integrity:** Automatically creates `hosted_file_link` records.

### B. Download & Streaming Action
**Path**: `GET /v3/action/hosted_file/{id}/download`

**Query Parameters:**
| Parameter | Type | Description |
| :--- | :--- | :--- |
| `key` | String | **Temporary V3.0 Auth:** Pass any valid `account_id_random` to bypass headers. |
| `site_key` | String | Bypass headers via `access_key` from the `site` table. |
| `filename` | String | Override the response filename. |

**Features:**
- **ID Vision:** Automatically resolves `{id}` if it belongs to a container object (e.g., `event_file`) instead of a direct `hosted_file`.
- **Streaming:** Supports standard `Range` headers for large files and video seeking.
- **Testing:** Supports `delay_ms` query parameter.

> [!WARNING]
> **TEMPORARY SOLUTION (V3.0):** The `?key=` and `?site_key=` unauthenticated access patterns are intended to unblock the frontend for inline images and direct links where custom headers are not possible. This will be replaced by a standardized Signed URL or Read-Token system in **Version 3.1**. Please do not rely on this pattern for long-term security architecture.

### C. Hash-Based Download (Content-Addressable)
**Path**: `GET /v3/action/hosted_file/hash/{sha256}/download`

**Features:**
- **Local Caching:** Ideal for systems like the Events Launcher that cache files locally by hash.
- **Flexible Auth:** Supports `api_key` in the query parameter (e.g., `?api_key=<key>`) for simple machine-to-machine requests.
- **Zero DB Lookup:** Resolves the physical path deterministically from the hash, bypassing database latency.

### D. Deletion & Cleanup Action
**Path**: `DELETE /v3/action/hosted_file/{id}`

| Parameter | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `link_to_type`| Query | null | The type of the link to remove. |
| `link_to_id`  | Query | null | The random ID of the link to remove. |
| `rm_orphan`   | Query | false | If true, physically delete file if no links remain. |
| `method`      | Query | `hide` | Cleanup method: `hide`, `disable`, or `delete` (hard). |
| `fake_delete` | Query | false | **Testing Mode:** Verifies file/record existence without modification. |

---

## 5. Event File Management (Specialized V3 Actions)

While `hosted_file` handles generic storage, `event_file` actions are context-aware and atomic for the Event module.

### A. Atomic Upload Action
**Path**: `POST /v3/action/event_file/upload`
**Format**: `multipart/form-data`

| Field | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `file_list` | File[] | Yes | Files to upload. |
| `account_id`| String | Yes | Owner account. |
| `for_type`  | String | Yes | Parent object type (e.g., `event_session`). |
| `for_id`    | String | Yes | Random ID of the parent object. |
| `event_id`  | String | No | Optional event context. |
| `title`     | String | No | Display title for the file. |

**Features:**
- **Atomic Creation:** Automatically creates the `hosted_file`, the `hosted_file_link`, AND the `event_file` association in one request.
- **Intelligent Updates:** If the same file is uploaded again for the same object, it updates the metadata instead of creating a duplicate association.
- **Enriched Return:** Returns full `event_file` objects with nested `hosted_file` data.

### B. Specialized Download
**Path**: `GET /v3/action/event_file/{id}/download`
*Semantic alias for the universal hosted_file downloader.*

---

## 6. Hosted File Management (Legacy)

The following endpoints are maintained for backward compatibility but should be migrated to V3 Actions.

| Method | Endpoint | Description |
| :--- | :--- | :--- |
| `POST` | `/hosted_file/upload_files` | Legacy multi-upload. |
| `GET` | `/hosted_file/{id}/download` | Legacy download. |
| `GET` | `/hosted_file/{id}/stream` | Legacy buffered streamer. |
| `DELETE` | `/hosted_file/{id}` | Legacy deletion. |

---

## 6. The "ID Vision" Standard (2026)

V3 uses a **String-Only ID Vision**. The frontend NEVER handles or stores database integers.

1.  **Automatic Mapping:** Internal `id_random` fields are mapped to clean names (e.g., `id`, `event_id`, `account_id`) in JSON responses.
2.  **Intelligent Resolution:** You can send random string IDs back to the API in any `*_id` field; the API resolves them to integers before database insertion.
3.  **Suffix Compatibility:** The `_random` suffix (e.g., `event_id_random`) is maintained for backward compatibility with V2 clients. Standard V3 frontend integration should prioritize fields without the suffix.

---

## 9. Real-Time Communication (V3 WebSockets)

V3 WebSockets provide a granular, high-performance messaging layer.

- **Guide**: [Aether API V3 WebSocket Integration Guide](./GUIDE__V3_FRONTEND_WEBSOCKETS.md)
- **Endpoint**: `ws://[api_domain]/v3/ws/group/{group_id}/client/{client_id}`
- **Key Requirement**: All messages must conform to the `WS_Message_V3` schema.

---

## 10. Structured Error Handling

V3 returns machine-readable error objects in `meta.details` for failures.

### HTTP Status Codes
- **`400 Bad Request`**: Used for client-driven errors including invalid search fields, validation failures, and constraint violations.
- **`403 Forbidden`**: Missing or invalid API Key / Account Context.
- **`404 Not Found`**: Object ID does not exist.
- **`500 Internal Server Error`**: Unexpected server crash or database connection failure.

### Common Error Categories
Found in `meta.details.category`:
- `database_duplicate`: Non-unique value (Code 1062). -> **400**
- `database_constraint`: Foreign key violation (Codes 1451, 1452). -> **400**
- `database_schema`: Invalid column name or missing field in the requested `view` (Codes 1054, 1146). -> **400**
- `validation`: Pydantic validation failed (Check `details` for field-specific errors). -> **400**

---

## 8. Data Store Cascading Lookup (V3)

V3 provides a specialized endpoint for retrieving configuration or content snippets by a human-friendly `code`. This uses a **hierarchical fallback** logic to find the "best fit" record for the current user and object context.

### A. The V3 Lookup Endpoint
**Path:** `GET /v3/data_store/code/{code}`

**Query Parameters:**
| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `for_type` | String | No | Parent object type (e.g., `event`, `person`). |
| `for_id` | String | No | Parent object random ID (Vision ID). |
| `limit` | Integer | No | **Dynamic Return:** Default `1` (returns single object). If `> 1`, returns a list. |

### B. Cascading Logic (The Hierarchy of Truth)
The API automatically resolves the most specific record available using the following priority:
**Object Override > Account Override > Global System Default.**

| Specificity | `account_id` | `for_type` | `for_id` | `code` | `Result` |
| :--- | :--- | :--- | :--- | :--- | :--- |
| **Global** | `NULL` | `NULL` | `NULL` | `'site_config'` | System default (blue theme). |
| **Account** | `'abc123_rd'` | `NULL` | `NULL` | `'site_config'` | Acme Corp default (green theme). |
| **Object** | `'abc123_rd'` | `'event'` | `'evt_xyz_rd'` | `'site_config'` | Main Conference override (gold theme). |

### C. Rules for Frontend Agents
1.  **Vision IDs Only:** Always use random string IDs (e.g., `evt_xyz_rd`) for `for_id`. Never use database integers.
2.  **Explicit Context:** If you are within an Event or Person context, always provide `for_type` and `for_id`. The API will handle the fallback if a specific record doesn't exist.
3.  **Automatic JSON Parsing:** If the record `type` is `'json'`, the API returns a structured object/list under the `json` key. You do not need to call `JSON.parse()`.
4.  **Handling the Return:**
    *   `limit=1` (Default): Returns a single **Object** in `data`.
    *   `limit>1`: Returns a **List** of objects in `data`.

### D. Example Implementation
```ts
// GET /v3/data_store/code/event_launcher_main_info?for_type=event&for_id=nmBfuGFeR0k&limit=1
export async function get_data_store_v3({ api_cfg, code, for_type, for_id, limit = 1 }) {
    const endpoint = `/v3/data_store/code/${code}`;
    const params = { for_type, for_id, limit };
    return await get_object({ api_cfg, endpoint, params });
}
```