From ea117bf2683cf825bbae6147b7d2d928514fb0e1 Mon Sep 17 00:00:00 2001
From: Scott Idem <stidem@gmail.com>
Date: Tue, 3 Feb 2026 12:05:04 -0500
Subject: [PATCH] feat(hosted-file): implement intelligent ID resolution for V3
 download action

- Updates download_file_action to automatically resolve container IDs (like event_file) to the underlying hosted_file.
- Updates GUIDE__V3_FRONTEND_API.md to document the 'ID Vision' standard for downloads.
- Resolves 404 errors observed when frontend passed event_file IDs to the hosted_file download endpoint.
---
 app/routers/api_v3_actions_hosted_file.py | 10 ++++++++++
 documentation/GUIDE__V3_FRONTEND_API.md   |  1 +
 2 files changed, 11 insertions(+)

diff --git a/app/routers/api_v3_actions_hosted_file.py b/app/routers/api_v3_actions_hosted_file.py
index 5da2d3f..18aa29d 100644
--- a/app/routers/api_v3_actions_hosted_file.py
+++ b/app/routers/api_v3_actions_hosted_file.py
@@ -209,7 +209,17 @@ async def download_file_action(
         raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Authentication required or invalid site_key.")
 
     # 2. Resolve File Record
+    # ID Vision: Attempt to resolve the ID. 
+    # If not found in hosted_file, check if it's an event_file ID that we can resolve to a hosted_file.
     resolved_id = redis_lookup_id_random(record_id_random=hosted_file_id, table_name='hosted_file')
+    
+    if not resolved_id:
+        log.info(f"ID {hosted_file_id} not found in hosted_file. Checking event_file...")
+        if ef_id := redis_lookup_id_random(record_id_random=hosted_file_id, table_name='event_file'):
+            if ef_rec := sql_select(sql="SELECT hosted_file_id FROM event_file WHERE id = :id", data={'id': ef_id}):
+                resolved_id = ef_rec.get('hosted_file_id')
+                log.info(f"Resolved event_file {hosted_file_id} to hosted_file {resolved_id}")
+
     if not resolved_id:
         raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Hosted file record not found.")
 
diff --git a/documentation/GUIDE__V3_FRONTEND_API.md b/documentation/GUIDE__V3_FRONTEND_API.md
index 7613e73..24a8871 100644
--- a/documentation/GUIDE__V3_FRONTEND_API.md
+++ b/documentation/GUIDE__V3_FRONTEND_API.md
@@ -89,6 +89,7 @@ V3 uses specialized **"Action"** routes for binary operations to separate proces
 **Path**: `GET /v3/action/hosted_file/{id}/download`
 
 **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.
 - **Auth Bypass:** Use `?site_key=<auth_key>` to download without an API Key header or JWT (useful for public kiosks).
 - **Testing:** Supports `delay_ms` query parameter.