feat(api): Enhance session events API with pagination, sorting, and filtering

- Added support for pagination (page and limit) in the session events endpoint.
- Implemented sorting functionality based on specified columns and directions.
- Introduced free-text search capability for session events.
- Updated SQL queries to retrieve all events and added a new SQL constant for events.
- Refactored GraphQL types and helpers to support new plugin and event queries.
- Created new GraphQL resolvers for plugins and events with pagination and filtering.
- Added comprehensive tests for new GraphQL endpoints and session events functionality.

Author: jokob-sk

CONTRIBUTING.md

@@ -15,6 +15,21 @@ Before opening a new issue:
 - [Check Common Issues & Debug Tips](https://docs.netalertx.com/DEBUG_TIPS#common-issues)
 - [Search Closed Issues](https://github.com/netalertx/NetAlertX/issues?q=is%3Aissue+is%3Aclosed)
 
+---
+
+## Use of AI
+
+Use of AI-assisted tools is permitted, provided all generated code is reviewed, understood, and verified before submission.
+
+- All AI-generated code must meet the project's **quality, security, and performance standards**.
+- Contributors are responsible for **fully understanding** any code they submit, regardless of how it was produced.
+- Prefer **clarity and maintainability over cleverness or brevity**. Readable code is always favored over dense or obfuscated implementations.
+- Follow the **DRY (Don't Repeat Yourself) principle** where appropriate, without sacrificing readability.
+- Do not submit code that you cannot confidently explain or debug.
+
+All changes must pass the **full test suite** before opening a PR.
+
+
 ---
 
 ## Submitting Pull Requests (PRs)
@@ -28,11 +43,19 @@ Please:
 - Provide a clear title and description for your PR
 - If relevant, add or update tests and documentation
 - For plugins, refer to the [Plugin Dev Guide](https://docs.netalertx.com/PLUGINS_DEV)
+- Switch the PR to DRAFT mode if still being worked on
+- Keep PRs **focused and minimal** — avoid unrelated changes in a single PR
+- PRs that do not meet these guidelines may be closed without review
+
+## Commit Messages
 
+- Use clear, descriptive commit messages
+- Explain *why* a change was made, not just *what* changed
+- Reference related issues where applicable
 
-## Code quality
+## Code Quality
 
-- read and follow the [code-standards](/.github/skills/code-standards/SKILL.md)
+- Read and follow the [code standards](/.github/skills/code-standards/SKILL.md)
 
 ---
 

docs/API_GRAPHQL.md

@@ -4,6 +4,10 @@ GraphQL queries are **read-optimized for speed**. Data may be slightly out of da
 
 * Devices
 * Settings
+* Events
+* PluginsObjects
+* PluginsHistory
+* PluginsEvents
 * Language Strings (LangStrings)
 
 ## Endpoints
@@ -254,11 +258,160 @@ curl 'http://host:GRAPHQL_PORT/graphql' \
 
 ---
 
+## Plugin Tables (Objects, Events, History)
+
+Three queries expose the plugin database tables with server-side pagination, filtering, and search:
+
+* `pluginsObjects` — current plugin object state
+* `pluginsEvents` — unprocessed plugin events
+* `pluginsHistory` — historical plugin event log
+
+All three share the same `PluginQueryOptionsInput` and return the same `PluginEntry` shape.
+
+### Sample Query
+
+```graphql
+query GetPluginObjects($options: PluginQueryOptionsInput) {
+  pluginsObjects(options: $options) {
+    dbCount
+    count
+    entries {
+      index plugin objectPrimaryId objectSecondaryId
+      dateTimeCreated dateTimeChanged
+      watchedValue1 watchedValue2 watchedValue3 watchedValue4
+      status extra userData foreignKey
+      syncHubNodeName helpVal1 helpVal2 helpVal3 helpVal4 objectGuid
+    }
+  }
+}
+```
+
+### Query Parameters (`PluginQueryOptionsInput`)
+
+| Parameter    | Type              | Description                                            |
+| ------------ | ----------------- | ------------------------------------------------------ |
+| `page`       | Int               | Page number (1-based).                                 |
+| `limit`      | Int               | Rows per page (max 1000).                              |
+| `sort`       | [SortOptionsInput] | Sorting options (`field`, `order`).                   |
+| `search`     | String            | Free-text search across key columns.                   |
+| `filters`    | [FilterOptionsInput] | Column-value exact-match filters.                   |
+| `plugin`     | String            | Plugin prefix to scope results (e.g. `"ARPSCAN"`).    |
+| `foreignKey` | String            | Foreign key filter (e.g. device MAC).                  |
+| `dateFrom`   | String            | Start of date range filter on `dateTimeCreated`.       |
+| `dateTo`     | String            | End of date range filter on `dateTimeCreated`.         |
+
+### Response Fields
+
+| Field     | Type          | Description                                                   |
+| --------- | ------------- | ------------------------------------------------------------- |
+| `dbCount` | Int           | Total rows for the requested plugin (before search/filters).  |
+| `count`   | Int           | Total rows after all filters (before pagination).             |
+| `entries` | [PluginEntry] | Paginated list of plugin entries.                             |
+
+### `curl` Example
+
+```sh
+curl 'http://host:GRAPHQL_PORT/graphql' \
+  -X POST \
+  -H 'Authorization: Bearer API_TOKEN' \
+  -H 'Content-Type: application/json' \
+  --data '{
+    "query": "query GetPluginObjects($options: PluginQueryOptionsInput) { pluginsObjects(options: $options) { dbCount count entries { index plugin objectPrimaryId status foreignKey } } }",
+    "variables": {
+      "options": {
+        "plugin": "ARPSCAN",
+        "page": 1,
+        "limit": 25
+      }
+    }
+  }'
+```
+
+### Badge Prefetch (Batched Counts)
+
+Use GraphQL aliases to fetch counts for all plugins in a single request:
+
+```graphql
+query BadgeCounts {
+  ARPSCAN: pluginsObjects(options: {plugin: "ARPSCAN", page: 1, limit: 1}) { dbCount }
+  INTRNT:  pluginsObjects(options: {plugin: "INTRNT",  page: 1, limit: 1}) { dbCount }
+}
+```
+
+---
+
+## Events Query
+
+Access the Events table with server-side pagination, filtering, and search.
+
+### Sample Query
+
+```graphql
+query GetEvents($options: EventQueryOptionsInput) {
+  events(options: $options) {
+    dbCount
+    count
+    entries {
+      eveMac
+      eveIp
+      eveDateTime
+      eveEventType
+      eveAdditionalInfo
+      evePendingAlertEmail
+    }
+  }
+}
+```
+
+### Query Parameters (`EventQueryOptionsInput`)
+
+| Parameter   | Type               | Description                                      |
+| ----------- | ------------------ | ------------------------------------------------ |
+| `page`      | Int                | Page number (1-based).                           |
+| `limit`     | Int                | Rows per page (max 1000).                        |
+| `sort`      | [SortOptionsInput]  | Sorting options (`field`, `order`).              |
+| `search`    | String             | Free-text search across key columns.             |
+| `filters`   | [FilterOptionsInput] | Column-value exact-match filters.              |
+| `eveMac`    | String             | Filter by device MAC address.                    |
+| `eventType` | String             | Filter by event type (e.g. `"New Device"`).      |
+| `dateFrom`  | String             | Start of date range filter on `eveDateTime`.     |
+| `dateTo`    | String             | End of date range filter on `eveDateTime`.       |
+
+### Response Fields
+
+| Field     | Type         | Description                                                  |
+| --------- | ------------ | ------------------------------------------------------------ |
+| `dbCount` | Int          | Total rows in the Events table (before any filters).         |
+| `count`   | Int          | Total rows after all filters (before pagination).            |
+| `entries` | [EventEntry] | Paginated list of event entries.                             |
+
+### `curl` Example
+
+```sh
+curl 'http://host:GRAPHQL_PORT/graphql' \
+  -X POST \
+  -H 'Authorization: Bearer API_TOKEN' \
+  -H 'Content-Type: application/json' \
+  --data '{
+    "query": "query GetEvents($options: EventQueryOptionsInput) { events(options: $options) { dbCount count entries { eveMac eveIp eveDateTime eveEventType } } }",
+    "variables": {
+      "options": {
+        "eveMac": "00:11:22:33:44:55",
+        "page": 1,
+        "limit": 50
+      }
+    }
+  }'
+```
+
+---
+
 ## Notes
 
-* Device, settings, and LangStrings queries can be combined in **one request** since GraphQL supports batching.
+* Device, settings, LangStrings, plugin, and event queries can be combined in **one request** since GraphQL supports batching.
 * The `fallback_to_en` feature ensures UI always has a value even if a translation is missing.
 * Data is **cached in memory** per JSON file; changes to language or plugin files will only refresh after the cache detects a file modification.
 * The `setOverriddenByEnv` flag helps identify setting values that are locked at container runtime.
-* The schema is **read-only** — updates must be performed through other APIs or configuration management. See the other [API](API.md) endpoints for details. 
+* Plugin queries scope `dbCount` to the requested `plugin`/`foreignKey` so badge counts reflect per-plugin totals.
+* The schema is **read-only** — updates must be performed through other APIs or configuration management. See the other [API](API.md) endpoints for details.
 

docs/API_SESSIONS.md

@@ -224,15 +224,33 @@ curl -X GET "http://<server_ip>:<GRAPHQL_PORT>/sessions/AA:BB:CC:DD:EE:FF?period
   * `type` → Event type (`all`, `sessions`, `missing`, `voided`, `new`, `down`)
     Default: `all`
   * `period` → Period to retrieve events (`7 days`, `1 month`, etc.)
+  * `page` → Page number, 1-based (default: `1`)
+  * `limit` → Rows per page, max 1000 (default: `100`)
+  * `search` → Free-text search filter across all columns
+  * `sortCol` → Column index to sort by, 0-based (default: `0`)
+  * `sortDir` → Sort direction: `asc` or `desc` (default: `desc`)
 
   **Example:**
 
   ```
-  /sessions/session-events?type=all&period=7 days
+  /sessions/session-events?type=all&period=7 days&page=1&limit=25&sortCol=3&sortDir=desc
   ```
 
   **Response:**
-  Returns a list of events or sessions with formatted connection, disconnection, duration, and IP information.
+
+  ```json
+  {
+    "data": [...],
+    "total": 150,
+    "recordsFiltered": 150
+  }
+  ```
+
+  | Field             | Type | Description                                       |
+  | ----------------- | ---- | ------------------------------------------------- |
+  | `data`            | list | Paginated rows (each row is a list of values).    |
+  | `total`           | int  | Total rows before search filter.                  |
+  | `recordsFiltered` | int  | Total rows after search filter (before paging).   |
 
 #### `curl` Example
 

front/deviceDetailsEvents.php

@@ -32,51 +32,64 @@
 
 function loadEventsData() {
   const hideConnections = $('#chkHideConnectionEvents')[0].checked;
-  const hideConnectionsStr = hideConnections ? 'true' : 'false';
 
   let period = $("#period").val();
   let { start, end } = getPeriodStartEnd(period);
 
-  const rawSql = `
-    SELECT eveDateTime, eveEventType, eveIp, eveAdditionalInfo
-    FROM Events
-    WHERE eveMac = "${mac}"
-      AND eveDateTime BETWEEN "${start}" AND "${end}"
-      AND (
-        (eveEventType NOT IN ("Connected", "Disconnected", "VOIDED - Connected", "VOIDED - Disconnected"))
-        OR "${hideConnectionsStr}" = "false"
-      )
+  const apiToken  = getSetting("API_TOKEN");
+  const apiBase   = getApiBase();
+  const graphqlUrl = `${apiBase}/graphql`;
+
+  const query = `
+    query Events($options: EventQueryOptionsInput) {
+      events(options: $options) {
+        count
+        entries {
+          eveDateTime
+          eveEventType
+          eveIp
+          eveAdditionalInfo
+        }
+      }
+    }
   `;
 
-  const apiToken = getSetting("API_TOKEN");
-
-  const apiBaseUrl = getApiBase();
-  const url = `${apiBaseUrl}/dbquery/read`;
-
   $.ajax({
-    url: url,
+    url: graphqlUrl,
     method: "POST",
     contentType: "application/json",
     headers: {
       "Authorization": `Bearer ${apiToken}`
     },
     data: JSON.stringify({
-      rawSql: btoa(rawSql)
+      query,
+      variables: {
+        options: {
+          eveMac:   mac,
+          dateFrom: start,
+          dateTo:   end,
+          limit:    500,
+          sort:     [{ field: "eveDateTime", order: "desc" }]
+        }
+      }
     }),
     success: function (data) {
-      // assuming read_query returns rows directly
-      const rows = data["results"].map(row => {
-        const rawDate = row.eveDateTime;
-        const formattedDate = rawDate ? localizeTimestamp(rawDate) : '-';
-
-        return [
-          formattedDate,
-          row.eveDateTime,
-          row.eveEventType,
-          row.eveIp,
-          row.eveAdditionalInfo
-        ];
-      });
+      const CONNECTION_TYPES = ["Connected", "Disconnected", "VOIDED - Connected", "VOIDED - Disconnected"];
+
+      const rows = data.data.events.entries
+        .filter(row => !hideConnections || !CONNECTION_TYPES.includes(row.eveEventType))
+        .map(row => {
+          const rawDate = row.eveDateTime;
+          const formattedDate = rawDate ? localizeTimestamp(rawDate) : '-';
+
+          return [
+            formattedDate,
+            row.eveDateTime,
+            row.eveEventType,
+            row.eveIp,
+            row.eveAdditionalInfo
+          ];
+        });
 
       const table = $('#tableEvents').DataTable();
       table.clear();