@ughuuu/game_server 1.0.1034 → 1.0.1039

package/dist/webrtc.js

@@ -4,6 +4,7 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports["default"] = exports.GameWebRTC = void 0;
+var _gamend_proto = require("./gamend_proto.js");
 function _typeof(o) { "@babel/helpers - typeof"; return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (o) { return typeof o; } : function (o) { return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o; }, _typeof(o); }
 function _regenerator() { /*! regenerator-runtime -- Copyright (c) 2014-present, Facebook, Inc. -- license (MIT): https://github.com/babel/babel/blob/main/packages/babel-helpers/LICENSE */ var e, t, r = "function" == typeof Symbol ? Symbol : {}, n = r.iterator || "@@iterator", o = r.toStringTag || "@@toStringTag"; function i(r, n, o, i) { var c = n && n.prototype instanceof Generator ? n : Generator, u = Object.create(c.prototype); return _regeneratorDefine2(u, "_invoke", function (r, n, o) { var i, c, u, f = 0, p = o || [], y = !1, G = { p: 0, n: 0, v: e, a: d, f: d.bind(e, 4), d: function d(t, r) { return i = t, c = 0, u = e, G.n = r, a; } }; function d(r, n) { for (c = r, u = n, t = 0; !y && f && !o && t < p.length; t++) { var o, i = p[t], d = G.p, l = i[2]; r > 3 ? (o = l === n) && (u = i[(c = i[4]) ? 5 : (c = 3, 3)], i[4] = i[5] = e) : i[0] <= d && ((o = r < 2 && d < i[1]) ? (c = 0, G.v = n, G.n = i[1]) : d < l && (o = r < 3 || i[0] > n || n > l) && (i[4] = r, i[5] = n, G.n = l, c = 0)); } if (o || r > 1) return a; throw y = !0, n; } return function (o, p, l) { if (f > 1) throw TypeError("Generator is already running"); for (y && 1 === p && d(p, l), c = p, u = l; (t = c < 2 ? e : u) || !y;) { i || (c ? c < 3 ? (c > 1 && (G.n = -1), d(c, u)) : G.n = u : G.v = u); try { if (f = 2, i) { if (c || (o = "next"), t = i[o]) { if (!(t = t.call(i, u))) throw TypeError("iterator result is not an object"); if (!t.done) return t; u = t.value, c < 2 && (c = 0); } else 1 === c && (t = i["return"]) && t.call(i), c < 2 && (u = TypeError("The iterator does not provide a '" + o + "' method"), c = 1); i = e; } else if ((t = (y = G.n < 0) ? u : r.call(n, G)) !== a) break; } catch (t) { i = e, c = 1, u = t; } finally { f = 1; } } return { value: t, done: y }; }; }(r, o, i), !0), u; } var a = {}; function Generator() {} function GeneratorFunction() {} function GeneratorFunctionPrototype() {} t = Object.getPrototypeOf; var c = [][n] ? t(t([][n]())) : (_regeneratorDefine2(t = {}, n, function () { return this; }), t), u = GeneratorFunctionPrototype.prototype = Generator.prototype = Object.create(c); function f(e) { return Object.setPrototypeOf ? Object.setPrototypeOf(e, GeneratorFunctionPrototype) : (e.__proto__ = GeneratorFunctionPrototype, _regeneratorDefine2(e, o, "GeneratorFunction")), e.prototype = Object.create(u), e; } return GeneratorFunction.prototype = GeneratorFunctionPrototype, _regeneratorDefine2(u, "constructor", GeneratorFunctionPrototype), _regeneratorDefine2(GeneratorFunctionPrototype, "constructor", GeneratorFunction), GeneratorFunction.displayName = "GeneratorFunction", _regeneratorDefine2(GeneratorFunctionPrototype, o, "GeneratorFunction"), _regeneratorDefine2(u), _regeneratorDefine2(u, o, "Generator"), _regeneratorDefine2(u, n, function () { return this; }), _regeneratorDefine2(u, "toString", function () { return "[object Generator]"; }), (_regenerator = function _regenerator() { return { w: i, m: f }; })(); }
 function _regeneratorDefine2(e, r, n, t) { var i = Object.defineProperty; try { i({}, "", {}); } catch (e) { i = 0; } _regeneratorDefine2 = function _regeneratorDefine(e, r, n, t) { function o(r, n) { _regeneratorDefine2(e, r, function (e) { return this._invoke(r, n, e); }); } r ? i ? i(e, r, { value: n, enumerable: !t, configurable: !t, writable: !t }) : e[r] = n : (o("next", 0), o("throw", 1), o("return", 2)); }, _regeneratorDefine2(e, r, n, t); }
@@ -16,8 +17,7 @@ function _classCallCheck(a, n) { if (!(a instanceof n)) throw new TypeError("Can
 function _defineProperties(e, r) { for (var t = 0; t < r.length; t++) { var o = r[t]; o.enumerable = o.enumerable || !1, o.configurable = !0, "value" in o && (o.writable = !0), Object.defineProperty(e, _toPropertyKey(o.key), o); } }
 function _createClass(e, r, t) { return r && _defineProperties(e.prototype, r), t && _defineProperties(e, t), Object.defineProperty(e, "prototype", { writable: !1 }), e; }
 function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == _typeof(i) ? i : i + ""; }
-function _toPrimitive(t, r) { if ("object" != _typeof(t) || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != _typeof(i)) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
-/**
+function _toPrimitive(t, r) { if ("object" != _typeof(t) || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != _typeof(i)) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); } /**
  * GameWebRTC — Browser WebRTC DataChannel client for game_server.
  *
  * Uses an existing Phoenix channel (e.g. from GameRealtime.joinUserChannel)
@@ -49,7 +49,6 @@ function _toPrimitive(t, r) { if ("object" != _typeof(t) || !t) return t; var e
  *   webrtc.send('events', JSON.stringify({ type: 'player_move', x: 10, y: 20 }))
  *   webrtc.close()
  */
-
 /**
  * Default DataChannel definitions.
  * - "events": reliable, ordered — important game events
@@ -85,6 +84,12 @@ var GameWebRTC = exports.GameWebRTC = /*#__PURE__*/function () {
     this.opts = opts;
     this.iceServers = opts.iceServers || DEFAULT_ICE_SERVERS;
     this.dataChannelDefs = opts.dataChannels || DEFAULT_DATA_CHANNELS;
+    // 'protobuf' negotiates the RtcEnvelope RPC protocol (with request ids)
+    // on the "events" DataChannel via the DataChannel protocol field.
+    this.format = opts.format === 'protobuf' ? 'protobuf' : 'json';
+    /** @type {Map<number|string, {resolve: Function, reject: Function, timer: any}>} */
+    this._pendingCalls = new Map();
+    this._nextCallId = 1;
 
     /** @type {RTCPeerConnection|null} */
     this.pc = null;
@@ -135,6 +140,7 @@ var GameWebRTC = exports.GameWebRTC = /*#__PURE__*/function () {
                   };
                   if (def.maxRetransmits !== undefined) dcOpts.maxRetransmits = def.maxRetransmits;
                   if (def.maxPacketLifeTime !== undefined) dcOpts.maxPacketLifeTime = def.maxPacketLifeTime;
+                  if (this.format === 'protobuf') dcOpts.protocol = 'protobuf';
                   dc = this.pc.createDataChannel(def.label, dcOpts);
                   this._wireDataChannel(dc);
                   this.channels.set(def.label, dc);
@@ -196,6 +202,113 @@ var GameWebRTC = exports.GameWebRTC = /*#__PURE__*/function () {
       return true;
     }
 
+    /**
+     * Call a server-side plugin hook over the "events" DataChannel.
+     *
+     * In protobuf mode replies are correlated by request id, so concurrent
+     * calls (including to the same function) are safe. In JSON mode replies
+     * are matched by plugin+fn (legacy protocol), first pending call wins.
+     *
+     * @param {string} plugin
+     * @param {string} fn
+     * @param {Array}  args
+     * @param {number} timeoutMs
+     * @returns {Promise<any>} the hook result
+     */
+  }, {
+    key: "callHook",
+    value: function callHook(plugin, fn) {
+      var _this2 = this;
+      var args = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : [];
+      var timeoutMs = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : 10000;
+      var dc = this.channels.get('events');
+      if (!dc || dc.readyState !== 'open') {
+        return Promise.reject(new Error('events DataChannel is not open'));
+      }
+      return new Promise(function (resolve, reject) {
+        var key;
+        if (_this2.format === 'protobuf') {
+          var id = _this2._nextCallId++;
+          key = id;
+          var envelope = _gamend_proto.PB.RtcEnvelope.encode({
+            call_hook: {
+              id: id,
+              plugin: plugin,
+              fn: fn,
+              args_json: new TextEncoder().encode(JSON.stringify(args))
+            }
+          }).finish();
+          dc.send(envelope);
+        } else {
+          key = "".concat(plugin, " ").concat(fn);
+          dc.send(JSON.stringify({
+            type: 'call_hook',
+            plugin: plugin,
+            fn: fn,
+            args: args
+          }));
+        }
+        var timer = setTimeout(function () {
+          _this2._pendingCalls["delete"](key);
+          reject(new Error("callHook ".concat(plugin, ".").concat(fn, " timed out")));
+        }, timeoutMs);
+        _this2._pendingCalls.set(key, {
+          resolve: resolve,
+          reject: reject,
+          timer: timer
+        });
+      });
+    }
+
+    /**
+     * Call a typed (protobuf) plugin hook over the "events" DataChannel.
+     *
+     * Encode the bytes with your game's schema (convention: <FnName>Request /
+     * <FnName>Reply, registered by the plugin) — the server decodes them into
+     * the request struct, so a hook without a registered schema errors with
+     * hook_schema_missing. Requires format: 'protobuf'.
+     *
+     * @param {string} plugin
+     * @param {string} fn
+     * @param {Uint8Array} bytes - encoded request message
+     * @param {number} timeoutMs
+     * @returns {Promise<Uint8Array>} the raw reply bytes
+     */
+  }, {
+    key: "callHookRaw",
+    value: function callHookRaw(plugin, fn, bytes) {
+      var _this3 = this;
+      var timeoutMs = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : 10000;
+      if (this.format !== 'protobuf') {
+        return Promise.reject(new Error('callHookRaw requires format: "protobuf"'));
+      }
+      var dc = this.channels.get('events');
+      if (!dc || dc.readyState !== 'open') {
+        return Promise.reject(new Error('events DataChannel is not open'));
+      }
+      return new Promise(function (resolve, reject) {
+        var id = _this3._nextCallId++;
+        var envelope = _gamend_proto.PB.RtcEnvelope.encode({
+          call_hook: {
+            id: id,
+            plugin: plugin,
+            fn: fn,
+            args_raw: bytes
+          }
+        }).finish();
+        dc.send(envelope);
+        var timer = setTimeout(function () {
+          _this3._pendingCalls["delete"](id);
+          reject(new Error("callHookRaw ".concat(plugin, ".").concat(fn, " timed out")));
+        }, timeoutMs);
+        _this3._pendingCalls.set(id, {
+          resolve: resolve,
+          reject: reject,
+          timer: timer
+        });
+      });
+    }
+
     /**
      * Check if a specific DataChannel is open.
      * @param {string} label
@@ -261,11 +374,11 @@ var GameWebRTC = exports.GameWebRTC = /*#__PURE__*/function () {
   }, {
     key: "_setupChannelListeners",
     value: function _setupChannelListeners() {
-      var _this2 = this;
+      var _this4 = this;
       // Server sends SDP answer
       this._answerRef = this.channel.on('webrtc:answer', function (payload) {
-        if (_this2.pc) {
-          _this2.pc.setRemoteDescription(new RTCSessionDescription({
+        if (_this4.pc) {
+          _this4.pc.setRemoteDescription(new RTCSessionDescription({
             sdp: payload.sdp,
             type: payload.type
           }));
@@ -274,28 +387,28 @@ var GameWebRTC = exports.GameWebRTC = /*#__PURE__*/function () {
 
       // Server sends ICE candidate
       this._iceRef = this.channel.on('webrtc:ice', function (payload) {
-        if (_this2.pc && payload.candidate) {
-          _this2.pc.addIceCandidate(new RTCIceCandidate(payload))["catch"](function (err) {
-            return _this2._emitError(err);
+        if (_this4.pc && payload.candidate) {
+          _this4.pc.addIceCandidate(new RTCIceCandidate(payload))["catch"](function (err) {
+            return _this4._emitError(err);
           });
         }
       });
 
       // Server notifies about connection state changes
       this._stateRef = this.channel.on('webrtc:state', function (payload) {
-        var cb = _this2.opts.onStateChange;
+        var cb = _this4.opts.onStateChange;
         if (cb) cb(payload.state);
       });
 
       // Server relays DataChannel data back via WebSocket (fallback)
       this._dataRef = this.channel.on('webrtc:data', function (payload) {
-        var cb = _this2.opts.onData;
+        var cb = _this4.opts.onData;
         if (cb) cb(payload.channel, payload.data);
       });
 
       // Server confirms channel open
       this._openRef = this.channel.on('webrtc:channel_open', function (payload) {
-        var cb = _this2.opts.onChannelOpen;
+        var cb = _this4.opts.onChannelOpen;
         if (cb) cb(payload.channel);
       });
     }
@@ -340,30 +453,83 @@ var GameWebRTC = exports.GameWebRTC = /*#__PURE__*/function () {
   }, {
     key: "_wireDataChannel",
     value: function _wireDataChannel(dc) {
-      var _this3 = this;
+      var _this5 = this;
       dc.onopen = function () {
-        var cb = _this3.opts.onChannelOpen;
+        var cb = _this5.opts.onChannelOpen;
         if (cb) cb(dc.label);
 
         // Resolve connect() promise when the FIRST channel opens
-        if (_this3._resolveConnect) {
-          _this3._resolveConnect();
-          _this3._resolveConnect = null;
-          _this3._rejectConnect = null;
+        if (_this5._resolveConnect) {
+          _this5._resolveConnect();
+          _this5._resolveConnect = null;
+          _this5._rejectConnect = null;
         }
       };
       dc.onclose = function () {
-        var cb = _this3.opts.onChannelClose;
+        var cb = _this5.opts.onChannelClose;
         if (cb) cb(dc.label);
       };
       dc.onmessage = function (event) {
-        var cb = _this3.opts.onData;
+        if (dc.label === 'events' && _this5._handleRpcReply(event.data)) return;
+        var cb = _this5.opts.onData;
         if (cb) cb(dc.label, event.data);
       };
       dc.onerror = function (event) {
-        _this3._emitError(event.error || event);
+        _this5._emitError(event.error || event);
       };
     }
+
+    // Routes hook replies to pending callHook promises. Returns true when the
+    // message was an RPC reply and has been consumed.
+  }, {
+    key: "_handleRpcReply",
+    value: function _handleRpcReply(data) {
+      try {
+        if (this.format === 'protobuf') {
+          if (typeof data === 'string') return false;
+          var bin = data instanceof Uint8Array ? data : new Uint8Array(data);
+          var env = _gamend_proto.PB.RtcEnvelope.decode(bin);
+          if (env.hook_reply) {
+            var _pending = this._takePending(env.hook_reply.id);
+            if (_pending) {
+              if (env.hook_reply.data === 'data_raw') {
+                _pending.resolve(env.hook_reply.data_raw);
+              } else {
+                var _env$hook_reply$data_;
+                var json = new TextDecoder().decode((_env$hook_reply$data_ = env.hook_reply.data_json) !== null && _env$hook_reply$data_ !== void 0 ? _env$hook_reply$data_ : new Uint8Array());
+                _pending.resolve(json.length ? JSON.parse(json) : null);
+              }
+            }
+            return true;
+          }
+          if (env.hook_error) {
+            var _pending2 = this._takePending(env.hook_error.id);
+            if (_pending2) _pending2.reject(new Error(env.hook_error.error));
+            return true;
+          }
+          return false;
+        }
+        if (typeof data !== 'string') return false;
+        var msg = JSON.parse(data);
+        if (msg.type !== 'hook_reply' && msg.type !== 'hook_error') return false;
+        var pending = this._takePending("".concat(msg.plugin, " ").concat(msg.fn));
+        if (!pending) return false;
+        if (msg.type === 'hook_reply') pending.resolve(msg.data);else pending.reject(new Error(msg.error));
+        return true;
+      } catch (_) {
+        return false;
+      }
+    }
+  }, {
+    key: "_takePending",
+    value: function _takePending(key) {
+      var pending = this._pendingCalls.get(key);
+      if (pending) {
+        clearTimeout(pending.timer);
+        this._pendingCalls["delete"](key);
+      }
+      return pending;
+    }
   }, {
     key: "_emitError",
     value: function _emitError(error) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ughuuu/game_server",
-  "version": "1.0.1034",
-  "description": "API for the Gamend Game Server. Provides HTTP REST API, real-time WebSocket channels, and WebRTC DataChannels for low-latency game data. Features authentication, users, lobbies, groups, parties, friends, chat, notifications, achievements, leaderboards, payments, server scripting, and admin portal.  ## **1. Authentication**  This API uses JWT (JSON Web Tokens) with access and refresh tokens:  ### **1.1 Getting Tokens** - **Email/Password**: POST to `/api/v1/login` with email and password - **Device (SDK)**: POST to `/api/v1/login` with a `device_id` string (creates/returns a device user) - **Discord OAuth**: Use `/api/v1/auth/discord` flow - **Google OAuth**: Use `/api/v1/auth/google` flow - **Facebook OAuth**: Use `/api/v1/auth/facebook` flow - **Apple Sign In**: Use `/auth/apple` browser flow or apple sdk flow - **Steam (OpenID)**: Use `/api/v1/auth/steam` flow  Both methods return: - `access_token` - Short-lived (15 min), use for API requests - `refresh_token` - Long-lived (30 days), use to get new access tokens  ### **1.2 Using Tokens** Include the access token in the Authorization header: ``` Authorization: Bearer <access_token> ```  ### **1.3 Refreshing Tokens** When your access token expires, use POST `/api/v1/refresh` with your refresh token to get a new access token.  ## **2. Users** Users endpoints cover the user lifecycle and profile features. Key highlights:  - **Registration and login** (email/password, device token for SDKs, and OAuth providers) - **Profile metadata** (JSON blob per user) and editable profile fields - **Account lifecycle**: password reset, email confirmation, and account deletion - **Sessions & tokens**: both browser sessions and JWT-based API tokens are supported  ## **3. Friends** The Friends domain offers lightweight social features:  - **Friend requests** (send / accept / reject / block flows) - **Friend listing & pagination**, with basic privacy controls - **Domain helpers** to manage and query friend relationships from API or UI contexts  ## **4. Lobbies** Lobbies provide matchmaking / room management primitives. Highlights:  - **Create / list / update / delete** lobbies with rich metadata (mode, region, tags) - **Host-managed or hostless** modes (hostless allowed internally, not creatable via public API) - **Membership management**: join, leave, kick users, and automatic host transfer - **Controls & protection**: max users, hidden/locked states, and optional password protection - **Hidden lobbies** are excluded from public listings; public listing endpoints are paginated  ## **5. Notifications** Persistent user-to-user notifications that survive across sessions:  - **Send notifications** to accepted friends with a title, optional content, and optional metadata - **List own notifications** with pagination (ordered oldest-first) - **Delete notifications** by ID (single or batch) - **Real-time delivery** via the user WebSocket channel (`\"notification\"` events) - **Offline delivery**: undeleted notifications are replayed on WebSocket reconnect  ## **6. Groups** Groups provide persistent community management for players:  - **Three group types**: `public` (anyone joins directly), `private` (users request to join, admins approve), `hidden` (invite-only, never listed) - **Membership roles**: `admin` and `member`, with promote/demote capabilities - **Join requests**: for private groups, users submit requests that admins approve or reject - **Invitations**: admins can invite users directly (blocked users are rejected) - **CRUD operations**: create, update, delete groups with metadata support - **Group chat**: integrated via the Chat API with `chat_type: \"group\"`  ## **7. Parties** Ephemeral groups of users for short-lived sessions (e.g., matchmaking squads):  - **Invite-only joining**: the party leader sends invites by user ID to friends or shared-group members - **Invite flow**: `POST /parties/invite` → recipient accepts via `POST /parties/invite/accept` or declines via `POST /parties/invite/decline`; leader can cancel via `POST /parties/invite/cancel` - **Invite visibility**: leader can list sent invites (`GET /parties/invitations/sent`); recipient can list received invites (`GET /parties/invitations`) - **Connection requirement**: invites can only be sent to users who are friends or share at least one group with the leader - **One party at a time**: a user can only be in one party; accepting an invite while already in a party is rejected - **Leader management**: the creator is the leader; leadership can be transferred - **Lobby integration**: parties can create or join lobbies as a group - **Party chat**: integrated via the Chat API with `chat_type: \"party\"` - **Real-time events** via the party WebSocket channel  ## **8. Chat** Real-time messaging across multiple conversation types:  - **Chat types**: `lobby` (within a lobby), `group` (within a group), `party` (within a party), `friend` (DMs between friends) - **Send messages** with content, optional metadata, and automatic access validation - **List messages** with pagination (newest first) - **Read tracking**: mark messages as read and get unread counts per conversation - **Real-time delivery** via PubSub and WebSocket channels - **Moderation hooks**: `before_chat_message` pipeline hook for filtering/blocking  ## **9. Leaderboards** Server-managed ranked scoreboards:  - **Multiple leaderboards**: create named leaderboards with configurable sort order - **Score submission**: submit scores with optional metadata - **Rankings**: retrieve paginated rankings with user details - **Reset support**: leaderboards can be reset periodically  ## **10. Key-Value Storage** Per-user persistent key-value storage for game state, preferences, and settings:  - **Get/set/delete** key-value pairs scoped to the authenticated user - **List keys** with optional prefix filtering - **Metadata support**: values can include arbitrary JSON metadata  ## **11. Achievements** Track player accomplishments with progress-based or instant-unlock achievements:  - **Achievement definitions**: admin-created with slug, title, description, icon, sort order, and optional progress target - **Progress tracking**: increment progress toward a target; auto-unlocks when progress reaches the target - **Instant unlock**: directly unlock achievements without progress tracking - **Hidden achievements**: details obscured (\"???\") until unlocked by the user - **Public listings**: paginated, optionally filtered; authenticated users see their own progress - **Admin management**: create, update, delete, grant, revoke, unlock, and increment achievements  ## **12. Real-time: WebSocket Channels** The server provides real-time communication via Phoenix WebSocket channels. Connect to the WebSocket endpoint and join topic-based channels for live updates.  ### **12.1 Connection** Connect to `wss://your-server.com/socket` with your JWT token as a parameter: ``` const socket = new Socket(\"wss://your-server.com/socket\", { params: { token: \"<access_token>\" } }) socket.connect() ```  ### **12.2 Available Channels** - **User channel** (`user:<user_id>`): notifications, friend events, achievement unlocks, party/group invites - **Lobby channel** (`lobby:<lobby_id>`): lobby member joins/leaves, lobby updates, lobby chat - **Lobbies channel** (`lobbies`): global lobby list changes (created, updated, deleted) - **Group channel** (`group:<group_id>`): group member changes, group updates, group chat - **Groups channel** (`groups`): global group list changes - **Party channel** (`party:<party_id>`): party member changes, party updates, party chat  ### **12.3 JS SDK Helper** The `GameRealtime` class (included in this SDK) wraps Phoenix.Socket with convenient channel helpers: ```javascript import { GameRealtime } from '@ughuuu/game_server' const realtime = new GameRealtime('https://your-server.com', accessToken) const userChannel = realtime.joinUserChannel(userId) userChannel.on('notification', payload => console.log(payload)) ``` Requires the `phoenix` npm package as a peer dependency: `npm install phoenix`  ## **13. Real-time: WebRTC DataChannels** For low-latency game data, the server supports WebRTC DataChannels alongside WebSocket. The server acts as a WebRTC peer (not P2P between clients).  ### **13.1 How It Works** 1. Client connects via WebSocket and joins the **User channel** 2. Client sends an SDP offer over the channel (`webrtc:offer` event) 3. Server responds with an SDP answer (`webrtc:answer` event) 4. ICE candidates are exchanged (`webrtc:ice` events) 5. Once connected, named DataChannels carry game data at low latency  ### **13.2 Default DataChannels** - **`events`** (reliable, ordered): important game events (player actions, state changes) - **`state`** (unreliable, unordered): high-frequency position/state sync  ### **13.3 JS SDK Helper** The `GameWebRTC` class (included in this SDK, browser-only) handles signaling automatically: ```javascript import { GameRealtime, GameWebRTC } from '@ughuuu/game_server' const realtime = new GameRealtime('https://your-server.com', token) const userChannel = realtime.joinUserChannel(userId) const webrtc = new GameWebRTC(userChannel, {   onData: (label, data) => console.log(label, data) }) await webrtc.connect() webrtc.send('events', JSON.stringify({ type: 'move', x: 10, y: 20 })) ``` ",
+  "version": "1.0.1039",
+  "description": "API for the Gamend Game Server. Provides HTTP REST API, real-time WebSocket channels, and WebRTC DataChannels for low-latency game data. Features authentication, users, lobbies, groups, parties, friends, chat, notifications, achievements, leaderboards, tournaments, payments, server scripting, and admin portal.  ## **1. Authentication**  This API uses JWT (JSON Web Tokens) with access and refresh tokens:  ### **1.1 Getting Tokens** - **Email/Password**: POST to `/api/v1/login` with email and password - **Device (SDK)**: POST to `/api/v1/login` with a `device_id` string (creates/returns a device user) - **Discord OAuth**: Use `/api/v1/auth/discord` flow - **Google OAuth**: Use `/api/v1/auth/google` flow - **Facebook OAuth**: Use `/api/v1/auth/facebook` flow - **Apple Sign In**: Use `/auth/apple` browser flow or apple sdk flow - **Steam (OpenID)**: Use `/api/v1/auth/steam` flow  Both methods return: - `access_token` - Short-lived (15 min), use for API requests - `refresh_token` - Long-lived (30 days), use to get new access tokens  ### **1.2 Using Tokens** Include the access token in the Authorization header: ``` Authorization: Bearer <access_token> ```  ### **1.3 Refreshing Tokens** When your access token expires, use POST `/api/v1/refresh` with your refresh token to get a new access token.  ## **2. Users** Users endpoints cover the user lifecycle and profile features. Key highlights:  - **Registration and login** (email/password, device token for SDKs, and OAuth providers) - **Profile metadata** (JSON blob per user) and editable profile fields - **Account lifecycle**: password reset, email confirmation, and account deletion - **Sessions & tokens**: both browser sessions and JWT-based API tokens are supported  ## **3. Friends** The Friends domain offers lightweight social features:  - **Friend requests** (send / accept / reject / block flows) - **Friend listing & pagination**, with basic privacy controls - **Domain helpers** to manage and query friend relationships from API or UI contexts  ## **4. Lobbies** Lobbies provide matchmaking / room management primitives. Highlights:  - **Create / list / update / delete** lobbies with rich metadata (mode, region, tags) - **Host-managed or hostless** modes (hostless allowed internally, not creatable via public API) - **Membership management**: join, leave, kick users, and automatic host transfer - **Controls & protection**: max users, hidden/locked states, and optional password protection - **Hidden lobbies** are excluded from public listings; public listing endpoints are paginated  ## **5. Notifications** Persistent user-to-user notifications that survive across sessions:  - **Send notifications** to accepted friends with a title, optional content, and optional metadata - **List own notifications** with pagination (ordered oldest-first) - **Delete notifications** by ID (single or batch) - **Real-time delivery** via the user WebSocket channel (`\"notification\"` events) - **Offline delivery**: undeleted notifications are replayed on WebSocket reconnect  ## **6. Groups** Groups provide persistent community management for players:  - **Three group types**: `public` (anyone joins directly), `private` (users request to join, admins approve), `hidden` (invite-only, never listed) - **Membership roles**: `admin` and `member`, with promote/demote capabilities - **Join requests**: for private groups, users submit requests that admins approve or reject - **Invitations**: admins can invite users directly (blocked users are rejected) - **CRUD operations**: create, update, delete groups with metadata support - **Group chat**: integrated via the Chat API with `chat_type: \"group\"`  ## **7. Parties** Ephemeral groups of users for short-lived sessions (e.g., matchmaking squads):  - **Invite-only joining**: the party leader sends invites by user ID to friends or shared-group members - **Invite flow**: `POST /parties/invite` → recipient accepts via `POST /parties/invite/accept` or declines via `POST /parties/invite/decline`; leader can cancel via `POST /parties/invite/cancel` - **Invite visibility**: leader can list sent invites (`GET /parties/invitations/sent`); recipient can list received invites (`GET /parties/invitations`) - **Connection requirement**: invites can only be sent to users who are friends or share at least one group with the leader - **One party at a time**: a user can only be in one party; accepting an invite while already in a party is rejected - **Leader management**: the creator is the leader; leadership can be transferred - **Lobby integration**: parties can create or join lobbies as a group - **Party chat**: integrated via the Chat API with `chat_type: \"party\"` - **Real-time events** via the party WebSocket channel  ## **8. Chat** Real-time messaging across multiple conversation types:  - **Chat types**: `lobby` (within a lobby), `group` (within a group), `party` (within a party), `friend` (DMs between friends) - **Send messages** with content, optional metadata, and automatic access validation - **List messages** with pagination (newest first) - **Read tracking**: mark messages as read and get unread counts per conversation - **Real-time delivery** via PubSub and WebSocket channels - **Moderation hooks**: `before_chat_message` pipeline hook for filtering/blocking  ## **9. Leaderboards** Server-managed ranked scoreboards:  - **Multiple leaderboards**: create named leaderboards with configurable sort order - **Score submission**: submit scores with optional metadata - **Rankings**: retrieve paginated rankings with user details - **Reset support**: leaderboards can be reset periodically  ## **10. Key-Value Storage** Per-user persistent key-value storage for game state, preferences, and settings:  - **Get/set/delete** key-value pairs scoped to the authenticated user - **List keys** with optional prefix filtering - **Metadata support**: values can include arbitrary JSON metadata  ## **11. Achievements** Track player accomplishments with progress-based or instant-unlock achievements:  - **Achievement definitions**: admin-created with slug, title, description, icon, sort order, and optional progress target - **Progress tracking**: increment progress toward a target; auto-unlocks when progress reaches the target - **Instant unlock**: directly unlock achievements without progress tracking - **Hidden achievements**: details obscured (\"???\") until unlocked by the user - **Public listings**: paginated, optionally filtered; authenticated users see their own progress - **Admin management**: create, update, delete, grant, revoke, unlock, and increment achievements  ## **12. Tournaments** Single-elimination bracket tournaments, server-structured and game-judged:  - **Registration window → seeded draw → timed rounds → champions**; recurring tournaments (cron) create one occurrence per cycle sharing a slug; a nil starts_at keeps registration open until an admin draws manually - **Join/leave** as an entry leader (`POST`/`DELETE /tournaments/:id/join`); team composition is game policy - **Browse**: list/filter tournaments, standings, full bracket view, and the caller's current match (`GET /tournaments/:id/my-match`) - **Match verdicts are server-side** (game hooks) — no public resolve endpoint; clients get `tournament_match_ready` / `tournament_match_resolved` / `tournament_updated` / `tournament_finished` on the user channel - **Admin management** over HTTP: create/update/delete, cancel, draw now, finish, and force match verdicts under `/api/v1/admin/tournaments`  ## **13. Real-time: WebSocket Channels** The server provides real-time communication via Phoenix WebSocket channels. Connect to the WebSocket endpoint and join topic-based channels for live updates.  ### **13.1 Connection** Connect to `wss://your-server.com/socket` with your JWT token as a parameter: ``` const socket = new Socket(\"wss://your-server.com/socket\", { params: { token: \"<access_token>\" } }) socket.connect() ```  ### **13.2 Available Channels** - **User channel** (`user:<user_id>`): notifications, friend events, achievement unlocks, party/group invites, tournament events, KV subscriptions - **Lobby channel** (`lobby:<lobby_id>`): lobby member joins/leaves, lobby updates, lobby chat - **Lobbies channel** (`lobbies`): global lobby list changes (created, updated, deleted) - **Group channel** (`group:<group_id>`): group member changes, group updates, group chat - **Groups channel** (`groups`): global group list changes - **Party channel** (`party:<party_id>`): party member changes, party updates, party chat  ### **13.3 JS SDK Helper** The `GameRealtime` class (included in this SDK) wraps Phoenix.Socket with convenient channel helpers: ```javascript import { GameRealtime } from '@ughuuu/game_server' const realtime = new GameRealtime('https://your-server.com', accessToken) const userChannel = realtime.joinUserChannel(userId) userChannel.on('notification', payload => console.log(payload)) ``` Requires the `phoenix` npm package as a peer dependency: `npm install phoenix`  ## **14. Real-time: WebRTC DataChannels** For low-latency game data, the server supports WebRTC DataChannels alongside WebSocket. The server acts as a WebRTC peer (not P2P between clients).  ### **14.1 How It Works** 1. Client connects via WebSocket and joins the **User channel** 2. Client sends an SDP offer over the channel (`webrtc:offer` event) 3. Server responds with an SDP answer (`webrtc:answer` event) 4. ICE candidates are exchanged (`webrtc:ice` events) 5. Once connected, named DataChannels carry game data at low latency  ### **14.2 Default DataChannels** - **`events`** (reliable, ordered): important game events (player actions, state changes) - **`state`** (unreliable, unordered): high-frequency position/state sync  ### **14.3 JS SDK Helper** The `GameWebRTC` class (included in this SDK, browser-only) handles signaling automatically: ```javascript import { GameRealtime, GameWebRTC } from '@ughuuu/game_server' const realtime = new GameRealtime('https://your-server.com', token) const userChannel = realtime.joinUserChannel(userId) const webrtc = new GameWebRTC(userChannel, {   onData: (label, data) => console.log(label, data) }) await webrtc.connect() webrtc.send('events', JSON.stringify({ type: 'move', x: 10, y: 20 })) ``` ",
   "license": "MIT",
   "main": "dist/index.js",
   "scripts": {