refactor: enhance test framework with automated resource tracking and scripted error capture capabilities

server/nakama/lua/utils.lua

@@ -50,4 +50,34 @@ function utils.require_admin_or_host(context, match_id)
     end
 end
 
+-- Channel type constants for nk.channel_id_build (Nakama Lua runtime).
+-- NOTE: these differ from the Godot client's NakamaSocket.ChannelType enum.
+utils.CHANNEL_TYPE_ROOM = 1
+utils.CHANNEL_TYPE_DIRECT = 2
+utils.CHANNEL_TYPE_GROUP = 3
+
+-- Resolve a chat channel identifier for admin chat RPCs.
+--
+-- The client may send either an already-hashed Nakama channel ID, or a friendly
+-- room name (e.g. "social_global"). A raw room name is NOT a valid channel ID for
+-- nk.channel_messages_list, so we build the canonical hashed ID via the
+-- authoritative nk.channel_id_build API (system user as sender → global room).
+-- Returns the resolved channel ID, or the original value if it already looks
+-- hashed / can't be built.
+function utils.resolve_channel_id(channel_id)
+    if not channel_id or channel_id == "" then
+        return ""
+    end
+    -- A hashed Nakama channel ID contains a '.' separator; a plain room name does
+    -- not. Only treat dot-free values as room names needing resolution.
+    if string.find(channel_id, "%.") then
+        return channel_id
+    end
+    local status, built = pcall(nk.channel_id_build, "", channel_id, utils.CHANNEL_TYPE_ROOM)
+    if status and built and built ~= "" then
+        return built
+    end
+    return channel_id
+end
+
 return utils