From 6fb86c6568da2c08b5f8e691d4fc810e3ab09a44 Mon Sep 17 00:00:00 2001
From: Quasky <JacobMLewis@live.com>
Date: Thu, 17 Apr 2025 21:02:18 -0500
Subject: [PATCH] capitialization changes

---
 WebHostLib/api/room.py | 30 ++++++++++++++++++
 docs/webhost api.md    | 72 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 102 insertions(+)
 create mode 100644 docs/webhost api.md

diff --git a/WebHostLib/api/room.py b/WebHostLib/api/room.py
index 9337975695..0c1edfaddf 100644
--- a/WebHostLib/api/room.py
+++ b/WebHostLib/api/room.py
@@ -6,6 +6,7 @@ from flask import abort, url_for
 import worlds.Files
 from . import api_endpoints, get_players
 from ..models import Room
+from .. import tracker
 
 
 @api_endpoints.route('/room_status/<suuid:room_id>')
@@ -40,3 +41,32 @@ def room_info(room_id: UUID) -> Dict[str, Any]:
         "timeout": room.timeout,
         "downloads": downloads,
     }
+
+# TODO: Modify endpoint when teams are implimented.
+#       Right now it'll just have a flat listing of all received items for a slot.
+@api_endpoints.route('/room_received_items/<suuid:room_id>')
+def room_received_items(room_id: UUID) -> Dict[str, Any]:
+    room = Room.get(id=room_id)
+    if room is None:
+        return abort(404)
+
+    instancetrackerData = tracker.trackertata(room)
+    multisavedata: Dict[str, Any] = instancetrackerData._multisave
+    if(multiSavedata == None):
+        return None
+
+    receiveditemdata: Dict[str, Any] = multisavedata["received_items"]
+
+    finalitemdata = []
+    for key in receiveditemdata:
+        for slot in sorted(room.seed.slots.player_id):
+            if str(key[1]) == str(slot) and str(key[2]) == "True":
+                Data = {
+                    "slot": slot,
+                    "items": receiveditemdata[key],
+                }
+                finalitemdata.append(Data)
+
+    return {
+        "room_received_items": finalitemdata,
+    }
\ No newline at end of file
diff --git a/docs/webhost api.md b/docs/webhost api.md
new file mode 100644
index 0000000000..d147b3b04c
--- /dev/null
+++ b/docs/webhost api.md	
@@ -0,0 +1,72 @@
+# API Guide
+
+Archipelago has a rudementary API that is able to be queried by endpoints.
+The API is a work-in-progress and should be improved over time.
+
+All API requests will be formatted as: `https://<Archipelago URL>/api/<endpoint>`
+
+## Datapackage Endpoints
+These endpoints are used by applications to aquire and validate they have a current datapackage for item and location IDs.
+
+`/datapackage`  
+Fetches the current datapackage from the WebHost.
+
+`/datapackage/<string:checksum>`    
+Fetches databackage by checksum.
+
+`/datapackage_checksum`  
+Fetches checksum of current datapackage.
+
+## Generation Endpoint
+These endpoints are used internaly for the WebHost to generate games, and validate their generation.
+
+`(POST)` `/generate`  
+Submits a game to the WebHost for generation.
+
+`/status/<suuid:seed>`  
+Retreives the status of the seed's generation.
+
+## Room Endpoints
+Room endpoints will fetch foom information of the supplied room_ID.
+
+`/room_status/<suuid:room_id>`  
+Retreives:
+- Tracker UUID (`tracker`)
+- Player List (Slot name, and Game) (`players`)
+- Last known hosted port (`last_port`)
+- Last activity timestamp (`last_activity`)
+- Timeout counter (`timeout`)
+- Downloads for files required for gameplay (`downloads`)
+
+`/room_received_items/<suuid:room_id>`  
+Retreives all items received by players in the current room.  
+Fetches an array of objects formatted as:
+- Receiving Slot ID (`slot`)
+- Items (`items`)
+  - `0`: Item ID
+  - `1`: Location ID
+  - `2`: Sending Slot ID
+  - `3`: Item Flags
+
+## User Endpoints
+User endpoints can get room and seed details from the current session tokens (cookies)
+
+`/get_rooms`  
+Retreives all rooms currently owned by the session token.  
+Each room will have:
+- Room ID (`room_ID`)
+- Seed ID (`seed_id`)
+- Creation Timestamp (`creation_time`)
+- Last activity timestamp (`last_activity`)
+- Last known AP Port (`last_port`)
+- Room tiumeout counter (`timeout`)
+- Room tracker UUID (`tracker`)
+
+`/get_seeds`  
+Retreives all seeds currently owned by the session token.  
+Each seed will have:
+- Seed ID (`seed_id`)
+- Creation timestamp (`creation_time`)
+- Player Slots (`players`)
+
+