docs

docs/API.md

@@ -51,6 +51,10 @@ http://<server>:<GRAPHQL_PORT>/
 
 ## Endpoints
 
+
+> [!TIP]
+> When retrieving devices try using the GraphQL API endpoint first as it is read-optimized.
+
 * [Device API Endpoints](API_DEVICE.md) – Manage individual devices
 * [Devices Collection](API_DEVICES.md) – Bulk operations on multiple devices
 * [Events](API_EVENTS.md) – Device event logging and management

docs/API_EVENTS.md

@@ -82,7 +82,7 @@ The Events API provides access to **device event logs**, allowing creation, retr
 ```json
 {
   "success": true,
-  "message": "Deleted events older than 30 days"
+  "message": "Deleted events older than <days> days"
 }
 ```
 

docs/API_ONLINEHISTORY.md

@@ -29,31 +29,4 @@ Manage the **online history records** of devices. Currently, the API supports de
 ```bash
 curl -X DELETE "http://<server_ip>:<GRAPHQL_PORT>/history" \
   -H "Authorization: Bearer <API_TOKEN>"
-```
+```
-
----
-
-### Implementation Details
-
-The endpoint calls the helper function `delete_online_history()`:
-
-```python
-def delete_online_history():
-    """Delete all online history activity"""
-
-    conn = get_temp_db_connection()
-    cur = conn.cursor()
-
-    # Remove all entries from Online_History table
-    cur.execute("DELETE FROM Online_History")
-
-    conn.commit()
-    conn.close()
-
-    return jsonify({"success": True, "message": "Deleted online history"})
-```
-
-* Opens a temporary database connection for the request.
-* Executes a **full table delete** (`DELETE FROM Online_History`).
-* Commits the transaction and closes the connection.
-* Returns a JSON confirmation message.

docs/API_SESSIONS.md

@@ -1,18 +1,181 @@
-# SEssions API Endpoints
+# Sessions API Endpoints
 
-Track device connection sessions.
+Track and manage device connection sessions. Sessions record when a device connects or disconnects on the network.
 
-* **POST** `/sessions/create` → Create a new session
+### Create a Session
+
+* **POST** `/sessions/create` → Create a new session for a device
+
+  **Request Body:**
 
   ```json
-  { "mac": "AA:BB:CC:DD:EE:FF", "ip": "192.168.1.10", "start_time": "2025-08-01T10:00:00" }
+  {
+    "mac": "AA:BB:CC:DD:EE:FF",
+    "ip": "192.168.1.10",
+    "start_time": "2025-08-01T10:00:00",
+    "end_time": "2025-08-01T12:00:00",      // optional
+    "event_type_conn": "Connected",         // optional, default "Connected"
+    "event_type_disc": "Disconnected"       // optional, default "Disconnected"
+  }
   ```
-* **DELETE** `/sessions/delete` → Delete session by MAC
+
+  **Response:**
 
   ```json
-  { "mac": "AA:BB:CC:DD:EE:FF" }
+  {
+    "success": true,
+    "message": "Session created for MAC AA:BB:CC:DD:EE:FF"
+  }
   ```
-* **GET** `/sessions/list?mac=<mac>&start_date=2025-08-01&end_date=2025-08-21` → List sessions
+
-* **GET** `/sessions/calendar?start=2025-08-01&end=2025-08-21` → Calendar view of sessions
+---
-* **GET** `/sessions/<mac>?period=1 day` → Sessions for a device
+
-* **GET** `/sessions/session-events?type=all&period=7 days` → Session events summary
+### Delete Sessions
+
+* **DELETE** `/sessions/delete` → Delete all sessions for a given MAC
+
+  **Request Body:**
+
+  ```json
+  {
+    "mac": "AA:BB:CC:DD:EE:FF"
+  }
+  ```
+
+  **Response:**
+
+  ```json
+  {
+    "success": true,
+    "message": "Deleted sessions for MAC AA:BB:CC:DD:EE:FF"
+  }
+  ```
+
+---
+
+### List Sessions
+
+* **GET** `/sessions/list` → Retrieve sessions optionally filtered by device and date range
+
+  **Query Parameters:**
+
+  * `mac` (optional) → Filter by device MAC address
+  * `start_date` (optional) → Filter sessions starting from this date (`YYYY-MM-DD`)
+  * `end_date` (optional) → Filter sessions ending by this date (`YYYY-MM-DD`)
+
+  **Example:**
+
+  ```
+  /sessions/list?mac=AA:BB:CC:DD:EE:FF&start_date=2025-08-01&end_date=2025-08-21
+  ```
+
+  **Response:**
+
+  ```json
+  {
+    "success": true,
+    "sessions": [
+      {
+        "ses_MAC": "AA:BB:CC:DD:EE:FF",
+        "ses_Connection": "2025-08-01 10:00",
+        "ses_Disconnection": "2025-08-01 12:00",
+        "ses_Duration": "2h 0m",
+        "ses_IP": "192.168.1.10",
+        "ses_Info": ""
+      }
+    ]
+  }
+  ```
+
+---
+
+### Calendar View of Sessions
+
+* **GET** `/sessions/calendar` → View sessions in calendar format
+
+  **Query Parameters:**
+
+  * `start` → Start date (`YYYY-MM-DD`)
+  * `end` → End date (`YYYY-MM-DD`)
+
+  **Example:**
+
+  ```
+  /sessions/calendar?start=2025-08-01&end=2025-08-21
+  ```
+
+  **Response:**
+
+  ```json
+  {
+    "success": true,
+    "sessions": [
+      {
+        "resourceId": "AA:BB:CC:DD:EE:FF",
+        "title": "",
+        "start": "2025-08-01T10:00:00",
+        "end": "2025-08-01T12:00:00",
+        "color": "#00a659",
+        "tooltip": "Connection: 2025-08-01 10:00\nDisconnection: 2025-08-01 12:00\nIP: 192.168.1.10",
+        "className": "no-border"
+      }
+    ]
+  }
+  ```
+
+---
+
+### Device Sessions
+
+* **GET** `/sessions/<mac>` → Retrieve sessions for a specific device
+
+  **Query Parameters:**
+
+  * `period` → Period to retrieve sessions (`1 day`, `7 days`, `1 month`, etc.)
+    Default: `1 day`
+
+  **Example:**
+
+  ```
+  /sessions/AA:BB:CC:DD:EE:FF?period=7 days
+  ```
+
+  **Response:**
+
+  ```json
+  {
+    "success": true,
+    "sessions": [
+      {
+        "ses_MAC": "AA:BB:CC:DD:EE:FF",
+        "ses_Connection": "2025-08-01 10:00",
+        "ses_Disconnection": "2025-08-01 12:00",
+        "ses_Duration": "2h 0m",
+        "ses_IP": "192.168.1.10",
+        "ses_Info": ""
+      }
+    ]
+  }
+  ```
+
+---
+
+### Session Events Summary
+
+* **GET** `/sessions/session-events` → Retrieve a summary of session events
+
+  **Query Parameters:**
+
+  * `type` → Event type (`all`, `sessions`, `missing`, `voided`, `new`, `down`)
+    Default: `all`
+  * `period` → Period to retrieve events (`7 days`, `1 month`, etc.)
+
+  **Example:**
+
+  ```
+  /sessions/session-events?type=all&period=7 days
+  ```
+
+  **Response:**
+  Returns a list of events or sessions with formatted connection, disconnection, duration, and IP information.
+

docs/API_SYNC.md

@@ -35,35 +35,71 @@ curl 'http://<server>:<GRAPHQL_PORT>/sync' \
 
 ---
 
-#### 9.2 POST `/sync`
+#### 9.2 POST `/sync` 
 
-Used by a node to send data to the hub. The hub receives **form-encoded data** and stores it for processing.
+The **POST** endpoint is used by nodes to **send data to the hub**. The hub expects the data as **form-encoded fields** (application/x-www-form-urlencoded or multipart/form-data). The hub then stores the data in the plugin log folder for processing.
 
-**Required Form Fields:**
+#### Required Fields
 
-| Field       | Description                         |
+| Field       | Type              | Description                                                                                                                                                                  |
-| ----------- | ----------------------------------- |
+| ----------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `data`      | The payload (plain text or JSON)    |
+| `data`      | string            | The payload from the plugin or devices. Typically **plain text**, **JSON**, or **encrypted Base64** data. In your Python script, `encrypt_data()` is applied before sending. |
-| `node_name` | Name of the node sending the data   |
+| `node_name` | string            | The name of the node sending the data. Matches the node’s `SYNC_node_name` setting. Used to generate the filename on the hub.                                                |
-| `plugin`    | The plugin name generating the data |
+| `plugin`    | string            | The name of the plugin sending the data. Determines the filename prefix (`last_result.<plugin>...`).                                                                         |
+| `file_path` | string (optional) | Path of the local file being sent. Used only for logging/debugging purposes on the hub; **not required for processing**.                                                     |
 
-**Example Request (cURL):**
+---
 
-```sh
+### How the Hub Processes the POST Data
-curl -X POST 'http://<server>:<GRAPHQL_PORT>/sync' \
+
+1. **Receives the data** and validates the API token.
+2. **Stores the raw payload** in:
+
+```
+INSTALL_PATH/log/plugins/last_result.<plugin>.encoded.<node_name>.<sequence>.log
+```
+
+* `<plugin>` → plugin name from the POST request.
+* `<node_name>` → node name from the POST request.
+* `<sequence>` → incremented number for each submission.
+
+3. **Decodes / decrypts the data** if necessary (Base64 or encrypted) before processing.
+4. **Processes JSON payloads** (e.g., device info) to:
+
+   * Avoid duplicates by tracking `devMac`.
+   * Add metadata like `devSyncHubNode`.
+   * Insert new devices into the database.
+5. **Renames files** to indicate they have been processed:
+
+```
+processed_last_result.<plugin>.<node_name>.<sequence>.log
+```
+
+---
+
+### Example POST Payload
+
+If a node is sending device data:
+
+```bash
+curl -X POST 'http://<hub>:<PORT>/sync' \
   -H 'Authorization: Bearer <API_TOKEN>' \
-  -F 'data=<payload here>' \
+  -F 'data={"data":[{"devMac":"00:11:22:33:44:55","devName":"Device 1","devVendor":"Vendor A","devLastIP":"192.168.1.10"}]}' \
   -F 'node_name=NODE-01' \
   -F 'plugin=SYNC'
 ```
 
-**Response Example:**
+* The `data` field contains JSON with a **`data` array**, where each element is a **device object** or **plugin data object**.
+* The `plugin` and `node_name` fields allow the hub to **organize and store the file correctly**.
 
-```json
+---
-{
+
-  "message": "Data received and stored successfully"
+### Key Notes
-}
+
-```
+* **Always use the same `plugin` and `node_name` values** for consistent storage.
+* **Encrypted data**: The Python script uses `encrypt_data()` before sending, and the hub decodes it before processing.
+* **Sequence numbers**: Every submission generates a new sequence, preventing overwriting previous data.
+* **Form-encoded**: The hub expects `multipart/form-data` (cURL `-F`) or `application/x-www-form-urlencoded`.
 
 **Storage Details:**