chore: update api bash scripts

scripts/api/health.sh

@@ -1,3 +1,14 @@
 #!/bin/bash
+# Health check for the presence server.
+# Returns HTTP 200 with a JSON status payload when the server is up.
+#
+# Usage:
+#   ./api/health.sh
+#   BASE_URL=http://192.168.1.10:1902 ./api/health.sh
+set -e
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+. "${SCRIPT_DIR}/../_common.sh"
 
-curl -X GET http://localhost:1902/reslevis/health
+echo "Health check: GET ${BASE_URL}/reslevis/health"
+curl -s -X GET "${BASE_URL}/reslevis/health"
+echo ""

scripts/api/smoke_test.sh

@@ -1,14 +1,30 @@
 #!/bin/bash
-# Full API smoke test: gateways, zones, trackerzones, trackers (list/update/delete).
-# Usage: ./api/smoke_test.sh   or   BASE_URL=http://host:port ./api/smoke_test.sh
+# Full API smoke test: list, update, and delete for gateways, zones,
+# tracker zones, and trackers. Followed by a pagination showcase for
+# every list endpoint.
+#
+# The script reads existing records from the database and exercises
+# update + delete on them, so it is safe to run against a populated
+# dev environment. Nothing is created — only existing rows are touched.
+#
+# Requires: jq   (https://stedolan.github.io/jq/)
+#
+# Usage:
+#   ./api/smoke_test.sh
+#   BASE_URL=http://host:port ./api/smoke_test.sh
 set -e
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 . "${SCRIPT_DIR}/../_common.sh"
 
+# ---------------------------------------------------------------------------
+# GATEWAYS
+# ---------------------------------------------------------------------------
 echo "=========================================="
 echo "GATEWAY API TESTS"
 echo "=========================================="
 
+# List all gateways. jq -c '.[]' prints one compact JSON object per line
+# so we can iterate and extract the id field.
 echo "1. Listing all Gateways"
 LIST=$(curl -s -X GET "$BASE_URL/reslevis/getGateways" | jq -c '.[]')
 GATEWAY_IDS=()
@@ -19,27 +35,37 @@ for r in $LIST; do
 done
 sleep 1
 
+# Update and delete only when there are at least 2 gateways so we don't
+# accidentally destroy the only one in the system.
 if [ ${#GATEWAY_IDS[@]} -gt 1 ]; then
   echo -e "\n\n2. Updating Gateway ${GATEWAY_IDS[1]}"
+  # PUT replaces the full record — all fields must be supplied.
   curl -s -X PUT "$BASE_URL/reslevis/updateGateway/${GATEWAY_IDS[1]}" \
     -H "Content-Type: application/json" \
     -d "{\"id\": \"${GATEWAY_IDS[1]}\", \"name\": \"GU-100-Updated\", \"mac\": \"AA:BB:CC:DD:EE:FF\", \"status\": \"online\", \"model\": \"MG3\", \"ip\": \"127.0.0.1\", \"position\": \"unknown\", \"x\": 1, \"y\": 1, \"notes\": \"some description\", \"floor\": \"second\", \"building\": \"hospital\"}"
   sleep 1
-  echo -e "\n\n3. Listing Gateways after update"
+
+  echo -e "\n\n3. Listing Gateways after update (verify name changed)"
   curl -s -X GET "$BASE_URL/reslevis/getGateways" | jq -c '.[]'
   sleep 1
+
   echo -e "\n\n4. Deleting Gateway ${GATEWAY_IDS[1]}"
   curl -s -X DELETE "$BASE_URL/reslevis/removeGateway/${GATEWAY_IDS[1]}"
   sleep 1
-  echo -e "\n\n5. Verifying Delete (List again)..."
+
+  echo -e "\n\n5. Verifying delete — Gateway ${GATEWAY_IDS[1]} should be gone"
   curl -s -X GET "$BASE_URL/reslevis/getGateways" | jq -c '.[]'
 else
-  echo "Not enough gateways to test update/delete"
+  echo "Not enough gateways to test update/delete (need at least 2)"
 fi
 
+# ---------------------------------------------------------------------------
+# ZONES
+# ---------------------------------------------------------------------------
 echo -e "\n\n=========================================="
 echo "ZONE API TESTS"
 echo "=========================================="
+
 echo "6. Listing all Zones"
 LIST=$(curl -s -X GET "$BASE_URL/reslevis/getZones" | jq -c '.[]')
 ZONE_IDS=()
@@ -51,24 +77,32 @@ sleep 1
 
 if [ ${#ZONE_IDS[@]} -gt 0 ]; then
   echo -e "\n\n7. Updating Zone ${ZONE_IDS[0]}"
+  # updateZone takes the id inside the body (no path parameter).
   curl -s -X PUT "$BASE_URL/reslevis/updateZone" -H "Content-Type: application/json" \
     -d "{\"id\": \"${ZONE_IDS[0]}\", \"name\": \"Zone-Updated\", \"groups\": [\"security\", \"logistics\"]}"
   sleep 1
-  echo -e "\n\n8. Listing Zones after update"
+
+  echo -e "\n\n8. Listing Zones after update (verify name and groups changed)"
   curl -s -X GET "$BASE_URL/reslevis/getZones" | jq -c '.[]'
   sleep 1
+
   echo -e "\n\n9. Deleting Zone ${ZONE_IDS[0]}"
   curl -s -X DELETE "$BASE_URL/reslevis/removeZone/${ZONE_IDS[0]}"
   sleep 1
-  echo -e "\n\n10. Verifying Delete..."
+
+  echo -e "\n\n10. Verifying delete — Zone ${ZONE_IDS[0]} should be gone"
   curl -s -X GET "$BASE_URL/reslevis/getZones" | jq -c '.[]'
 else
-  echo "No zones to test update/delete"
+  echo "No zones found — skipping update/delete tests"
 fi
 
+# ---------------------------------------------------------------------------
+# TRACKER ZONES
+# ---------------------------------------------------------------------------
 echo -e "\n\n=========================================="
 echo "TRACKERZONE API TESTS"
 echo "=========================================="
+
 echo "11. Listing all TrackerZones"
 LIST=$(curl -s -X GET "$BASE_URL/reslevis/getTrackerZones" | jq -c '.[]')
 TRACKERZONE_IDS=()
@@ -80,24 +114,32 @@ sleep 1
 
 if [ ${#TRACKERZONE_IDS[@]} -gt 0 ]; then
   echo -e "\n\n12. Updating TrackerZone ${TRACKERZONE_IDS[0]}"
+  # updateTrackerZone also takes the id inside the body.
   curl -s -X PUT "$BASE_URL/reslevis/updateTrackerZone" -H "Content-Type: application/json" \
     -d "{\"id\": \"${TRACKERZONE_IDS[0]}\", \"name\": \"TrackerZone-Updated\"}"
   sleep 1
+
   echo -e "\n\n13. Listing TrackerZones after update"
   curl -s -X GET "$BASE_URL/reslevis/getTrackerZones" | jq -c '.[]'
   sleep 1
+
   echo -e "\n\n14. Deleting TrackerZone ${TRACKERZONE_IDS[0]}"
   curl -s -X DELETE "$BASE_URL/reslevis/removeTrackerZone/${TRACKERZONE_IDS[0]}"
   sleep 1
-  echo -e "\n\n15. Verifying Delete..."
+
+  echo -e "\n\n15. Verifying delete — TrackerZone ${TRACKERZONE_IDS[0]} should be gone"
   curl -s -X GET "$BASE_URL/reslevis/getTrackerZones" | jq -c '.[]'
 else
-  echo "No trackerzones to test update/delete"
+  echo "No tracker zones found — skipping update/delete tests"
 fi
 
+# ---------------------------------------------------------------------------
+# TRACKERS
+# ---------------------------------------------------------------------------
 echo -e "\n\n=========================================="
 echo "TRACKER API TESTS"
 echo "=========================================="
+
 echo "16. Listing all Trackers"
 LIST=$(curl -s -X GET "$BASE_URL/reslevis/getTrackers" | jq -c '.[]')
 TRACKER_IDS=()
@@ -109,21 +151,69 @@ sleep 1
 
 if [ ${#TRACKER_IDS[@]} -gt 0 ]; then
   echo -e "\n\n17. Updating Tracker ${TRACKER_IDS[0]}"
+  # Only the fields provided are updated; omitted fields retain their values
+  # because the server does a full Save (not a partial patch).
   curl -s -X PUT "$BASE_URL/reslevis/updateTracker" -H "Content-Type: application/json" \
     -d "{\"id\": \"${TRACKER_IDS[0]}\", \"name\": \"Tracker-Updated\", \"battery\": 85, \"status\": \"inactive\"}"
   sleep 1
-  echo -e "\n\n18. Listing Trackers after update"
+
+  echo -e "\n\n18. Listing Trackers after update (verify name/status changed)"
   curl -s -X GET "$BASE_URL/reslevis/getTrackers" | jq -c '.[]'
   sleep 1
+
   echo -e "\n\n19. Deleting Tracker ${TRACKER_IDS[0]}"
+  # Deleting a tracker also publishes a DELETE event to Kafka so the
+  # location and decoder services stop tracking that MAC address.
   curl -s -X DELETE "$BASE_URL/reslevis/removeTracker/${TRACKER_IDS[0]}"
   sleep 1
-  echo -e "\n\n20. Verifying Delete..."
+
+  echo -e "\n\n20. Verifying delete — Tracker ${TRACKER_IDS[0]} should be gone"
   curl -s -X GET "$BASE_URL/reslevis/getTrackers" | jq -c '.[]'
 else
-  echo "No trackers to test update/delete"
+  echo "No trackers found — skipping update/delete tests"
 fi
 
+# ---------------------------------------------------------------------------
+# PAGINATION SHOWCASE
+# All list endpoints accept ?limit=N&offset=N query parameters.
+# Default: limit=100, offset=0.
+# Use limit + offset to page through large result sets.
+# ---------------------------------------------------------------------------
+echo -e "\n\n=========================================="
+echo "PAGINATION SHOWCASE"
+echo "All list endpoints support ?limit=N&offset=N"
+echo "Default: limit=100, offset=0"
+echo "=========================================="
+
+echo -e "\n--- Gateways: first page (limit=5, offset=0) ---"
+curl -s -X GET "$BASE_URL/reslevis/getGateways?limit=5&offset=0" | jq '.'
+
+echo -e "\n--- Gateways: second page (limit=5, offset=5) ---"
+# offset moves the window forward by the page size; combine with the same
+# limit to get the next batch of results.
+curl -s -X GET "$BASE_URL/reslevis/getGateways?limit=5&offset=5" | jq '.'
+
+echo -e "\n--- Trackers: first page (limit=3, offset=0) ---"
+curl -s -X GET "$BASE_URL/reslevis/getTrackers?limit=3&offset=0" | jq '.'
+
+echo -e "\n--- Trackers: second page (limit=3, offset=3) ---"
+curl -s -X GET "$BASE_URL/reslevis/getTrackers?limit=3&offset=3" | jq '.'
+
+echo -e "\n--- Zones: first page (limit=10, offset=0) ---"
+curl -s -X GET "$BASE_URL/reslevis/getZones?limit=10&offset=0" | jq '.'
+
+echo -e "\n--- TrackerZones: first page (limit=10, offset=0) ---"
+curl -s -X GET "$BASE_URL/reslevis/getTrackerZones?limit=10&offset=0" | jq '.'
+
+echo -e "\n--- Alerts: first page (limit=10, offset=0) ---"
+# Alerts are created automatically when a tracker enters a restricted zone.
+# Use offset to page through the alert history.
+curl -s -X GET "$BASE_URL/reslevis/alerts?limit=10&offset=0" | jq '.'
+
+echo -e "\n--- Latest tracker positions: first page (limit=5, offset=0) ---"
+# getTracks (no uuid) returns the most recent position record per tracker.
+curl -s -X GET "$BASE_URL/reslevis/getTracks?limit=5&offset=0" | jq '.'
+
 echo -e "\n\n=========================================="
 echo "ALL TESTS COMPLETED"
 echo "=========================================="

scripts/api/tracks.sh

@@ -1,6 +1,27 @@
 #!/bin/bash
-# Tracks API query examples (getTracks with limit, from, to).
-# Usage: ./api/tracks.sh [TRACKER_UUID]
+# Tracks API query examples.
+#
+# Two endpoints are available:
+#
+#   GET /reslevis/getTracks/{uuid}
+#     Returns historical track records for a single tracker.
+#     Query params:
+#       limit  - max records to return (default: 10)
+#       from   - start of time window, RFC3339 (default: 24 h ago)
+#       to     - end of time window,   RFC3339 (default: now)
+#
+#   GET /reslevis/getTracks
+#     Returns the single latest track record for every known tracker.
+#     Useful for a "current positions" overview.
+#     Query params:
+#       limit  - max trackers to return (default: 100)
+#       offset - number of trackers to skip, for paging (default: 0)
+#
+# Usage:
+#   ./api/tracks.sh [TRACKER_UUID]
+#   BASE_URL=http://host:port ./api/tracks.sh [TRACKER_UUID]
+#
+# Get tracker UUIDs from: GET /reslevis/getTrackers
 set -e
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 . "${SCRIPT_DIR}/../_common.sh"
@@ -8,35 +29,52 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 TRACKER_UUID="${1:-1a6c6f1e-9a3d-4a66-9f0b-6d5f0e1c1a01}"
 
 echo "==================================="
-echo "Tracks API Query Examples"
+echo "Single-tracker history: GET /reslevis/getTracks/{uuid}"
 echo "==================================="
 echo ""
 
-echo "1. Basic query (default: last 10 tracks from last 24 hours):"
-echo "GET /reslevis/getTracks/${TRACKER_UUID}"
+# Default call — returns last 10 records from the past 24 hours.
+echo "1. Basic query (default: last 10 tracks from the last 24 hours):"
 curl -s -X GET "${BASE_URL}/reslevis/getTracks/${TRACKER_UUID}" | jq '.'
 echo -e "\n"
 
-echo "2. Get last 50 tracks:"
+# Raise the limit to retrieve more records in a single call.
+echo "2. Get last 50 tracks (raise limit):"
 curl -s -X GET "${BASE_URL}/reslevis/getTracks/${TRACKER_UUID}?limit=50" | jq '.'
 echo -e "\n"
 
-echo "3. Get tracks with date range (from/to in RFC3339):"
+# Explicit time window — both from and to accept RFC3339 timestamps.
+# The date command falls back gracefully between GNU/Linux (-d) and macOS (-v).
 TO_DATE=$(date -u +%Y-%m-%dT%H:%M:%SZ)
-FROM_DATE=$(date -u -d '7 days ago' +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -v-7d +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || echo "2020-01-01T00:00:00Z")
+FROM_DATE=$(date -u -d '7 days ago' +%Y-%m-%dT%H:%M:%SZ 2>/dev/null \
+  || date -u -v-7d +%Y-%m-%dT%H:%M:%SZ 2>/dev/null \
+  || echo "2020-01-01T00:00:00Z")
+
+echo "3. Get up to 20 tracks from the last 7 days (explicit time window):"
+echo "   from=${FROM_DATE}  to=${TO_DATE}"
 curl -s -X GET "${BASE_URL}/reslevis/getTracks/${TRACKER_UUID}?from=${FROM_DATE}&to=${TO_DATE}&limit=20" | jq '.'
 echo -e "\n"
 
 echo "==================================="
-echo "Query Parameters: limit, from (RFC3339), to (RFC3339)"
-echo "Get tracker UUIDs from: GET /reslevis/getTrackers"
+echo "All-trackers latest positions: GET /reslevis/getTracks"
 echo "==================================="
+echo ""
 
-echo "4. Get all latest positions for all trackers:"
+# No parameters — returns the most recent record for each tracker, up to 100.
+echo "4. All latest positions (default limit=100, offset=0):"
 curl -s -X GET "${BASE_URL}/reslevis/getTracks" | jq '.'
 echo -e "\n"
 
+# Reduce the page size to 5 — useful when there are many trackers.
+echo "5. First page — limit to 5 trackers:"
+curl -s -X GET "${BASE_URL}/reslevis/getTracks?limit=5&offset=0" | jq '.'
+echo -e "\n"
+
+# Move to the second page by setting offset=5.
+echo "6. Second page — next 5 trackers (offset=5):"
+curl -s -X GET "${BASE_URL}/reslevis/getTracks?limit=5&offset=5" | jq '.'
+echo -e "\n"
+
 echo "==================================="
-echo "Query Parameters: limit, from (RFC3339), to (RFC3339)"
-echo "Get tracker UUIDs from: GET /reslevis/getTrackers"
+echo "Done."
 echo "==================================="