@ughuuu/gamend 1.1.1325 → 1.1.1328

package/dist/session.js

@@ -0,0 +1,496 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.GamendSession = void 0;
+var _ApiClient2 = _interopRequireDefault(require("./ApiClient"));
+var _AuthenticationApi = _interopRequireDefault(require("./api/AuthenticationApi"));
+var _realtime = require("./realtime");
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { "default": e }; }
+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 _callSuper(t, o, e) { return o = _getPrototypeOf(o), _possibleConstructorReturn(t, _isNativeReflectConstruct() ? Reflect.construct(o, e || [], _getPrototypeOf(t).constructor) : o.apply(t, e)); }
+function _possibleConstructorReturn(t, e) { if (e && ("object" == _typeof(e) || "function" == typeof e)) return e; if (void 0 !== e) throw new TypeError("Derived constructors may only return object or undefined"); return _assertThisInitialized(t); }
+function _assertThisInitialized(e) { if (void 0 === e) throw new ReferenceError("this hasn't been initialised - super() hasn't been called"); return e; }
+function _isNativeReflectConstruct() { try { var t = !Boolean.prototype.valueOf.call(Reflect.construct(Boolean, [], function () {})); } catch (t) {} return (_isNativeReflectConstruct = function _isNativeReflectConstruct() { return !!t; })(); }
+function _getPrototypeOf(t) { return _getPrototypeOf = Object.setPrototypeOf ? Object.getPrototypeOf.bind() : function (t) { return t.__proto__ || Object.getPrototypeOf(t); }, _getPrototypeOf(t); }
+function _inherits(t, e) { if ("function" != typeof e && null !== e) throw new TypeError("Super expression must either be null or a function"); t.prototype = Object.create(e && e.prototype, { constructor: { value: t, writable: !0, configurable: !0 } }), Object.defineProperty(t, "prototype", { writable: !1 }), e && _setPrototypeOf(t, e); }
+function _setPrototypeOf(t, e) { return _setPrototypeOf = Object.setPrototypeOf ? Object.setPrototypeOf.bind() : function (t, e) { return t.__proto__ = e, t; }, _setPrototypeOf(t, e); }
+function _readOnlyError(r) { throw new TypeError('"' + r + '" is read-only'); }
+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); }
+function asyncGeneratorStep(n, t, e, r, o, a, c) { try { var i = n[a](c), u = i.value; } catch (n) { return void e(n); } i.done ? t(u) : Promise.resolve(u).then(r, o); }
+function _asyncToGenerator(n) { return function () { var t = this, e = arguments; return new Promise(function (r, o) { var a = n.apply(t, e); function _next(n) { asyncGeneratorStep(a, r, o, _next, _throw, "next", n); } function _throw(n) { asyncGeneratorStep(a, r, o, _next, _throw, "throw", n); } _next(void 0); }); }; }
+function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
+function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
+function _defineProperty(e, r, t) { return (r = _toPropertyKey(r)) in e ? Object.defineProperty(e, r, { value: t, enumerable: !0, configurable: !0, writable: !0 }) : e[r] = t, e; }
+function _classCallCheck(a, n) { if (!(a instanceof n)) throw new TypeError("Cannot call a class as a function"); }
+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, e) { if ("object" != _typeof(t) || !t) return t; var r; if ("undefined" != typeof Symbol && void 0 !== (r = t[Symbol.toPrimitive])) { var i = r.call(t, e || "default"); if ("object" != _typeof(i)) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === e ? String : Number)(t); } /**
+ * GamendSession — keeps a player signed in.
+ *
+ * Holds the access and refresh tokens, sends the access token with every API
+ * call made through `session.client`, refreshes it shortly before it expires
+ * (and once after a 401), and gives GameRealtime a token function, so a socket
+ * that reconnects hours later still carries a valid token. The JS counterpart
+ * of the token handling in the Godot client's GamendApi.
+ *
+ * Usage:
+ *
+ *   import { GamendSession, AuthenticationApi, UsersApi } from '@ughuuu/gamend'
+ *
+ *   const gamend = new GamendSession('https://your-server.com')
+ *   gamend.on('session', (session) => session ? save(session) : forget())
+ *   gamend.on('authFailed', () => showLogin())
+ *   gamend.restore(loadSaved())  // optional: a session saved earlier
+ *
+ *   // Any sign-in made through gamend.client is picked up: email, device, a provider.
+ *   await new AuthenticationApi(gamend.client).login({ loginRequest: { email, password } })
+ *   const me = await new UsersApi(gamend.client).getCurrentUser()
+ *
+ *   const realtime = gamend.realtime()
+ *   realtime.joinUserChannel(gamend.userId)
+ *
+ *   await gamend.signOut()
+ */
+// Refresh this long before the access token expires, so a request sent just
+// before the deadline does not arrive just after it.
+var REFRESH_MARGIN_MS = 60 * 1000;
+var LOGOUT_PATH = '/api/v1/logout';
+var GamendSession = exports.GamendSession = /*#__PURE__*/function () {
+  /**
+   * @param {string} serverUrl - Base HTTP(S) server URL, e.g. "https://game.example.com"
+   */
+  function GamendSession(serverUrl) {
+    _classCallCheck(this, GamendSession);
+    this._serverUrl = serverUrl.replace(/\/$/, '');
+    this._session = null;
+    this._generation = 0;
+    this._refreshing = null;
+    this._listeners = {
+      session: new Set(),
+      authFailed: new Set()
+    };
+    this._realtimes = new Set();
+    /** The ApiClient to hand every generated API class: `new LobbiesApi(gamend.client)`. */
+    this.client = new SessionApiClient(this._serverUrl, this);
+    // Refreshes bypass `client`, so their answer is adopted only when no
+    // sign-in or sign-out happened while they were in flight.
+    this._plainClient = new _ApiClient2["default"](this._serverUrl);
+  }
+
+  /** Whether a session is held. */
+  return _createClass(GamendSession, [{
+    key: "signedIn",
+    get: function get() {
+      return this._session !== null;
+    }
+
+    /** The signed-in user's id, or null. */
+  }, {
+    key: "userId",
+    get: function get() {
+      return this._session ? this._session.user_id : null;
+    }
+
+    /**
+     * The session to save for `restore`: `{access_token, refresh_token,
+     * expires_at, user_id}`, `expires_at` in unix ms; null when signed out. The
+     * refresh token signs in for 30 days, so store it as you would a password.
+     * @returns {Object|null}
+     */
+  }, {
+    key: "session",
+    get: function get() {
+      return this._session ? _objectSpread({}, this._session) : null;
+    }
+
+    /**
+     * Resumes a session saved from `session` or the 'session' event. A missing
+     * or past `expires_at` makes the first call refresh the access token.
+     * @param {Object|null} saved
+     */
+  }, {
+    key: "restore",
+    value: function restore(saved) {
+      this._set(saved && saved.refresh_token ? saved : null);
+    }
+
+    /**
+     * Listens for 'session' (signed in, refreshed or signed out: the new
+     * `session`, or null) or 'authFailed' (the server refused the refresh token,
+     * as after a sign-out elsewhere or a password change; the session is gone).
+     * @param {'session'|'authFailed'} event
+     * @param {Function} listener
+     * @returns {Function} Call it to stop listening
+     */
+  }, {
+    key: "on",
+    value: function on(event, listener) {
+      var listeners = this._listeners[event];
+      if (!listeners) throw new Error("GamendSession: unknown event \"".concat(event, "\""));
+      listeners.add(listener);
+      return function () {
+        return listeners["delete"](listener);
+      };
+    }
+
+    /**
+     * A valid access token, refreshed first when it expires within a minute;
+     * null when signed out. Sockets from `realtime()` call this.
+     * @returns {Promise<string|null>}
+     */
+  }, {
+    key: "getAccessToken",
+    value: (function () {
+      var _getAccessToken = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee() {
+        var session;
+        return _regenerator().w(function (_context) {
+          while (1) switch (_context.n) {
+            case 0:
+              session = this._session;
+              if (session) {
+                _context.n = 1;
+                break;
+              }
+              return _context.a(2, null);
+            case 1:
+              if (!(Date.now() < session.expires_at - REFRESH_MARGIN_MS)) {
+                _context.n = 2;
+                break;
+              }
+              return _context.a(2, session.access_token);
+            case 2:
+              _context.n = 3;
+              return this.refresh();
+            case 3:
+              return _context.a(2, this._session ? this._session.access_token : null);
+          }
+        }, _callee, this);
+      }));
+      function getAccessToken() {
+        return _getAccessToken.apply(this, arguments);
+      }
+      return getAccessToken;
+    }()
+    /**
+     * Exchanges the refresh token for a new access token now; concurrent calls
+     * share one request. Resolves true when refreshed, false when signed out,
+     * offline (the session is kept for the next try) or refused (the session is
+     * dropped and 'authFailed' fires).
+     * @returns {Promise<boolean>}
+     */
+    )
+  }, {
+    key: "refresh",
+    value: function refresh() {
+      var _this = this;
+      if (!this._refreshing) {
+        this._refreshing = this._refresh()["finally"](function () {
+          _this._refreshing = null;
+        });
+      }
+      return this._refreshing;
+    }
+
+    /**
+     * A GameRealtime socket that asks this session for its token, disconnected
+     * when the session ends or another user signs in.
+     * @param {Object} socketOpts - As for GameRealtime, e.g. `{ format: 'protobuf' }`
+     * @returns {GameRealtime}
+     */
+  }, {
+    key: "realtime",
+    value: function realtime() {
+      var _this2 = this;
+      var socketOpts = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+      if (!this._session) throw new Error('GamendSession: sign in before opening a realtime socket');
+      var realtime = new _realtime.GameRealtime(this._serverUrl, function () {
+        return _this2.getAccessToken();
+      }, socketOpts);
+      this._realtimes.add(realtime);
+      return realtime;
+    }
+
+    /**
+     * Revokes the tokens on the server (on every device: revocation is per
+     * account) and drops the session here, even when the server cannot be reached.
+     */
+  }, {
+    key: "signOut",
+    value: (function () {
+      var _signOut = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee2() {
+        var _t;
+        return _regenerator().w(function (_context2) {
+          while (1) switch (_context2.p = _context2.n) {
+            case 0:
+              if (this._session) {
+                _context2.n = 1;
+                break;
+              }
+              return _context2.a(2);
+            case 1:
+              _context2.p = 1;
+              _context2.n = 2;
+              return new _AuthenticationApi["default"](this.client).logout();
+            case 2:
+              _context2.n = 4;
+              break;
+            case 3:
+              _context2.p = 3;
+              _t = _context2.v;
+            case 4:
+              return _context2.a(2);
+          }
+        }, _callee2, this, [[1, 3]]);
+      }));
+      function signOut() {
+        return _signOut.apply(this, arguments);
+      }
+      return signOut;
+    }() // ── Private ────────────────────────────────────────────────────────────────
+    )
+  }, {
+    key: "_refresh",
+    value: function () {
+      var _refresh2 = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee3() {
+        var session, generation, body, _yield$Authentication, response, _t2;
+        return _regenerator().w(function (_context3) {
+          while (1) switch (_context3.p = _context3.n) {
+            case 0:
+              session = this._session;
+              if (session) {
+                _context3.n = 1;
+                break;
+              }
+              return _context3.a(2, false);
+            case 1:
+              generation = this._generation;
+              _context3.p = 2;
+              _context3.n = 3;
+              return new _AuthenticationApi["default"](this._plainClient).refreshTokenWithHttpInfo({
+                refreshTokenRequest: {
+                  refresh_token: session.refresh_token
+                }
+              });
+            case 3:
+              _yield$Authentication = _context3.v;
+              response = _yield$Authentication.response;
+              body = response.body;
+              _context3.n = 5;
+              break;
+            case 4:
+              _context3.p = 4;
+              _t2 = _context3.v;
+              if (generation === this._generation && _t2.status === 401) {
+                this._set(null);
+                this._emit('authFailed');
+              }
+              return _context3.a(2, false);
+            case 5:
+              return _context3.a(2, generation === this._generation && this._adopt(body));
+          }
+        }, _callee3, this, [[2, 4]]);
+      }));
+      function _refresh() {
+        return _refresh2.apply(this, arguments);
+      }
+      return _refresh;
+    }() // After a 401 on a call that sent `sentToken`: true when there is a newer
+    // token to retry with.
+  }, {
+    key: "_recover",
+    value: function () {
+      var _recover2 = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee4(sentToken) {
+        return _regenerator().w(function (_context4) {
+          while (1) switch (_context4.n) {
+            case 0:
+              if (this._session) {
+                _context4.n = 1;
+                break;
+              }
+              return _context4.a(2, false);
+            case 1:
+              if (!(this._session.access_token !== sentToken)) {
+                _context4.n = 2;
+                break;
+              }
+              return _context4.a(2, true);
+            case 2:
+              return _context4.a(2, this.refresh());
+          }
+        }, _callee4, this);
+      }));
+      function _recover(_x) {
+        return _recover2.apply(this, arguments);
+      }
+      return _recover;
+    }() // Takes the session from a sign-in or refresh answer: `data` is a Session,
+    // or, for a polled provider sign-in, holds one under `data.session`.
+  }, {
+    key: "_adopt",
+    value: function _adopt(body) {
+      var data = body && body.data;
+      var session = data && (data.access_token ? data : data.session);
+      if (!session || !session.access_token || !session.refresh_token) return false;
+      this._set({
+        access_token: session.access_token,
+        refresh_token: session.refresh_token,
+        expires_at: Date.now() + (session.expires_in || 0) * 1000,
+        user_id: session.user_id || this.userId
+      });
+      return true;
+    }
+  }, {
+    key: "_set",
+    value: function _set(saved) {
+      var previous = this._session;
+      this._generation++;
+      this._session = saved ? {
+        access_token: saved.access_token || null,
+        refresh_token: saved.refresh_token,
+        expires_at: saved.expires_at || 0,
+        user_id: saved.user_id || null
+      } : null;
+      this.client.authentications.authorization.accessToken = this._session ? this._session.access_token : null;
+      if (!this._session || previous && previous.user_id !== this._session.user_id) {
+        this._realtimes.forEach(function (realtime) {
+          return realtime.disconnect();
+        });
+        this._realtimes.clear();
+      }
+      this._emit('session', this.session);
+    }
+  }, {
+    key: "_emit",
+    value: function _emit(event, value) {
+      this._listeners[event].forEach(function (listener) {
+        try {
+          listener(value);
+        } catch (err) {
+          console.error("GamendSession: a '".concat(event, "' listener failed"), err);
+        }
+      });
+    }
+  }]);
+}(); // The ApiClient behind `GamendSession.client`: sends the session's access
+// token (refreshed first when due, and once more after a 401), adopts the
+// session a sign-in answers, and signs out with the refresh token.
+var SessionApiClient = /*#__PURE__*/function (_ApiClient) {
+  function SessionApiClient(basePath, gamendSession) {
+    var _this3;
+    _classCallCheck(this, SessionApiClient);
+    _this3 = _callSuper(this, SessionApiClient, [basePath]);
+    _this3._gamendSession = gamendSession;
+    return _this3;
+  }
+  _inherits(SessionApiClient, _ApiClient);
+  return _createClass(SessionApiClient, [{
+    key: "callApi",
+    value: function () {
+      var _callApi = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee5() {
+        var _this4 = this;
+        var _len,
+          args,
+          _key,
+          gamend,
+          path,
+          headerParams,
+          authNames,
+          call,
+          authed,
+          sentToken,
+          result,
+          _args5 = arguments,
+          _t3,
+          _t4;
+        return _regenerator().w(function (_context5) {
+          while (1) switch (_context5.p = _context5.n) {
+            case 0:
+              for (_len = _args5.length, args = new Array(_len), _key = 0; _key < _len; _key++) {
+                args[_key] = _args5[_key];
+              }
+              gamend = this._gamendSession;
+              path = args[0], headerParams = args[4], authNames = args[7];
+              call = function call() {
+                return _ApiClient2["default"].prototype.callApi.apply(_this4, args);
+              }; // Logout reads the token itself, so that an expired one can still sign
+              // out, and its route is unauthenticated: the generated call sends no
+              // token. Send the refresh token, which outlives the access token.
+              if (!(path === LOGOUT_PATH)) {
+                _context5.n = 5;
+                break;
+              }
+              if (gamend.signedIn) {
+                _context5.n = 1;
+                break;
+              }
+              return _context5.a(2, call());
+            case 1:
+              args[4] = _objectSpread({
+                Authorization: "Bearer ".concat(gamend._session.refresh_token)
+              }, headerParams);
+              _context5.p = 2;
+              _context5.n = 3;
+              return call();
+            case 3:
+              return _context5.a(2, _context5.v);
+            case 4:
+              _context5.p = 4;
+              gamend._set(null);
+              return _context5.f(4);
+            case 5:
+              authed = authNames.includes('authorization') && gamend.signedIn;
+              if (!authed) {
+                _context5.n = 6;
+                break;
+              }
+              _context5.n = 6;
+              return gamend.getAccessToken();
+            case 6:
+              sentToken = this.authentications.authorization.accessToken;
+              _context5.p = 7;
+              _context5.n = 8;
+              return call();
+            case 8:
+              result = _context5.v;
+              _context5.n = 14;
+              break;
+            case 9:
+              _context5.p = 9;
+              _t3 = _context5.v;
+              _t4 = !authed || _t3.status !== 401;
+              if (_t4) {
+                _context5.n = 11;
+                break;
+              }
+              _context5.n = 10;
+              return gamend._recover(sentToken);
+            case 10:
+              _t4 = !_context5.v;
+            case 11:
+              if (!_t4) {
+                _context5.n = 12;
+                break;
+              }
+              throw _t3;
+            case 12:
+              _context5.n = 13;
+              return call();
+            case 13:
+              result = _context5.v;
+            case 14:
+              gamend._adopt(result.response && result.response.body);
+              return _context5.a(2, result);
+          }
+        }, _callee5, this, [[7, 9], [2,, 4, 5]]);
+      }));
+      function callApi() {
+        return _callApi.apply(this, arguments);
+      }
+      return callApi;
+    }()
+  }]);
+}(_ApiClient2["default"]);

package/dist/webrtc.js

@@ -29,10 +29,10 @@ function _toPrimitive(t, e) { if ("object" != _typeof(t) || !t) return t; var r;
  *
  * Usage:
  *
- *   import { GameRealtime, GameWebRTC } from '@ughuuu/gamend'
+ *   import { GameWebRTC } from '@ughuuu/gamend'
  *
- *   const realtime = new GameRealtime('https://your-server.com', token)
- *   const userChannel = realtime.joinUserChannel(userId)
+ *   const realtime = gamend.realtime()  // gamend: a signed-in GamendSession
+ *   const userChannel = realtime.joinUserChannel(gamend.userId)
  *
  *   const webrtc = new GameWebRTC(userChannel, {
  *     dataChannels: [

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ughuuu/gamend",
-  "version": "1.1.1325",
-  "description": "API for Gamend. 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, quests, leaderboards, tournaments, matchmaking, 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 - **GitHub OAuth**: Use `/api/v1/auth/github` 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 by default), use for API requests; `expires_in` gives its lifetime in seconds - `refresh_token` - Long-lived (30 days by default), 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 - **Push delivery**: notifications also fan out to the recipient's registered mobile devices (see Push notifications)  ## **5b. Push notifications** Mobile/web push delivery to registered devices (FCM for Android/Web, APNs-direct for iOS):  - **Register device tokens** via `POST /me/push_tokens` (`token`, `platform`, optional `provider`/`device_id`); re-registering a `device_id` rotates its token in place - **List/remove own devices** via `GET /me/push_tokens` and `DELETE /me/push_tokens/:id` - **Server-authoritative sending** — no public send endpoint; pushes originate from server hooks (`Gamend.Push.send_to_user/2`) or the admin API - **Per-token routing**: each token's `provider` (\"fcm\" | \"apns\") selects the delivery backend; unconfigured backends log instead of sending (dev-friendly) - **Reliability**: delivery rides the durable job queue with retries; dead tokens reported by the provider are disabled automatically  ## **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 is built in**: an admin-managed word filter (`block` / `mask` / `flag`, matched on a normalized form so leetspeak and padding do not slip through) and mutes are enforced before a message is stored or broadcast; the `before_chat_message` pipeline hook stays available for rules of your own - **Report a message**: `POST /chat/messages/:id/report` with an optional `reason` — one report per player per message, capped per day; reports the filter files itself have no reporter - **Scoped mutes** mirror kick: `POST /lobbies/mute` + `/lobbies/unmute` (lobby host), `POST /groups/:id/mute` + `/groups/:id/unmute` (group admin), `POST /parties/mute` + `/parties/unmute` (party leader), each with a paginated `.../mutes` listing for the same authority. Body is `{target_user_id, expires_at?, reason?}`; omitting `expires_at` mutes permanently - **Global mutes and the blocklist are server-authoritative** — no public endpoint; admin API (`/api/v1/admin/chat`) or a plugin calling `Gamend.Chat.mute_user/4` - **Real-time moderation events**: the muted player receives `chat_muted` / `chat_unmuted` on their user channel  ## **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. Quests / Progression** One event-driven progression engine covering achievements, daily/weekly quests, time-boxed event quests, chains, and groups:  - **Kinds**: `achievement` (permanent one-shot — the replacement for the old achievements system), `daily`/`weekly` (reset per UTC period), `event` (starts_at/ends_at window), `chain` (requires a prerequisite quest) - **Objectives**: each quest lists objectives `{event, target, params}`; server-side `report_event` advances every matching active quest — there is **no public endpoint to advance progress** (server-authoritative) - **Rewards**: currencies (Economy) and items (Inventory), paid **exactly once** per period via idempotent grants; `auto_claim` quests pay on completion, others via `POST /me/quests/:key/claim` - **My quests**: `GET /me/quests` returns active quests, per-period progress, and a claimable flag; hidden quests appear once completed - **Groups**: quests sharing a `group_key` collapse to one entry carrying `group_size`; `?group=<key>` lists that group's members in full - **Catalog**: `GET /quests` and per-user completions `GET /quests/user/:user_id` (gated by `GAMEND_FEATURES_LIST_QUESTS`) - **Admin management**: definitions CRUD plus per-user grant/reset/force-claim under `/api/v1/admin/quests`  ## **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. Matchmaking** Ticket-based queueing that turns waiting players into hidden, locked lobbies:  - **Join over HTTP** (`POST /matchmaking/tickets` with a `match_params` string map); only tickets with identical params match together — encode mode/map/skill band as parameter values - **A match forms** when a group reaches `max_players`, or has at least `min_players` and the oldest ticket outwaited the timeout; the server creates a hidden lobby, seats everyone and locks it - **The result is a push, not a poll**: matched players receive `match_found` (`lobby_id`, `match_params`) on their user channel; disconnecting cancels your tickets - **Inspect**: `GET /matchmaking/tickets/me` for your ticket, `GET /matchmaking/stats` for queue depths - **Admin management** over HTTP: list/filter tickets, force-cancel, and stats under `/api/v1/admin/matchmaking`  ## **14. Ready checks** One primitive for \"everyone must answer before this proceeds\", with one client-facing surface:  - **A player holds at most one check per lane** — the match lane (lobby ready-up or matchmaking accept) and the party lane (the party's standing board) — so answering needs no id: `GET /me/ready_check` returns `{\"lobby\": …, \"party\": …}` (each null when none) and `POST /me/ready_check` with `{\"ready\": true|false, \"scope\": \"lobby\"|\"party\"}` answers one (scope defaults to `lobby`) - **Two kinds.** `ready` (lobby/party board) is a toggle — a \"no\" just leaves the check open, and it lists every participant. `accept` (match confirmation) is final — one decline fails it for everyone — and returns counts plus your own state, so a pending match does not reveal who you were paired with - **Hosts open one** with `POST /lobbies/ready_check` (host-managed lobbies only; hostless matchmaking lobbies belong to the server), **party leaders** with `POST /parties/ready_check`; either call is a **reset** — it quietly replaces an already-open board with a fresh one over the current members, so the same endpoint serves \"ready check!\", \"force ready\" (with `timeout_ms`) and \"start over\". Call it off with `DELETE /lobbies/ready_check` / `DELETE /parties/ready_check`. The opener is pre-marked ready — clicking the button is their answer - **Failure does nothing on its own**: a declined or timed-out check kicks nobody, starts nothing, and moves no lobby state. It reports who did not answer, and the game (or the host, with the kick they already have) decides - **Live**: `ready_check_started` / `ready_check_updated` / `ready_check_passed` / `ready_check_failed` on the lobby channel, the party channel for a party board, or the user channel for an accept check - **Admin management** over HTTP: list/filter checks, force-cancel, and 24h outcome stats under `/api/v1/admin/ready_checks`  ## **15. 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.  ### **15.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() ```  ### **15.2 Available Channels** - **User channel** (`user:<user_id>`): notifications, friend events, quest progress/completions/claims, party/group invites, tournament events, chat mutes (`chat_muted` / `chat_unmuted`), 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  ### **15.3 JS SDK Helper** The `GameRealtime` class (included in this SDK) wraps Phoenix.Socket with convenient channel helpers: ```javascript import { GameRealtime } from '@ughuuu/gamend' const realtime = new GameRealtime('https://your-server.com', accessToken) const userChannel = realtime.joinUserChannel(userId) userChannel.on('notification', payload => console.log(payload)) ``` `phoenix` ships as a dependency of the package, so no extra install is needed.  ## **16. 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).  ### **16.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  ### **16.2 Default DataChannels** - **`events`** (reliable, ordered): important game events (player actions, state changes) - **`state`** (unreliable, unordered): high-frequency position/state sync  ### **16.3 JS SDK Helper** The `GameWebRTC` class (included in this SDK, browser-only) handles signaling automatically: ```javascript import { GameRealtime, GameWebRTC } from '@ughuuu/gamend' 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.1.1328",
+  "description": "API for Gamend. 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, quests, leaderboards, tournaments, matchmaking, 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 - **GitHub OAuth**: Use `/api/v1/auth/github` 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 by default), use for API requests; `expires_in` gives its lifetime in seconds - `refresh_token` - Long-lived (30 days by default), 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.  ### **1.4 Banned Accounts** An admin or the game can ban an account for a while or for good. A banned account still signs in, refreshes and signs out, `GET /api/v1/me` answers with its `ban` (`expires_at`, null when permanent, and `reason`), and `DELETE /api/v1/me` deletes it. Every other authenticated call answers 403 `account_banned`. On the socket it joins only its own user channel, where `account_banned` and `account_unbanned` arrive, and a ban placed while it is connected closes the socket.  ## **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 - **Push delivery**: notifications also fan out to the recipient's registered mobile devices (see Push notifications)  ## **5b. Push notifications** Mobile/web push delivery to registered devices (FCM for Android/Web, APNs-direct for iOS):  - **Register device tokens** via `POST /me/push_tokens` (`token`, `platform`, optional `provider`/`device_id`); re-registering a `device_id` rotates its token in place - **List/remove own devices** via `GET /me/push_tokens` and `DELETE /me/push_tokens/:id` - **Server-authoritative sending** — no public send endpoint; pushes originate from server hooks (`Gamend.Push.send_to_user/2`) or the admin API - **Per-token routing**: each token's `provider` (\"fcm\" | \"apns\") selects the delivery backend; unconfigured backends log instead of sending (dev-friendly) - **Reliability**: delivery rides the durable job queue with retries; dead tokens reported by the provider are disabled automatically  ## **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 is built in**: an admin-managed word filter (`block` / `mask` / `flag`, matched on a normalized form so leetspeak and padding do not slip through) and mutes are enforced before a message is stored or broadcast; the `before_chat_message` pipeline hook stays available for rules of your own - **Report a message**: `POST /chat/messages/:id/report` with an optional `reason` — one report per player per message, capped per day; reports the filter files itself have no reporter - **Scoped mutes** mirror kick: `POST /lobbies/mute` + `/lobbies/unmute` (lobby host), `POST /groups/:id/mute` + `/groups/:id/unmute` (group admin), `POST /parties/mute` + `/parties/unmute` (party leader), each with a paginated `.../mutes` listing for the same authority. Body is `{target_user_id, expires_at?, reason?}`; omitting `expires_at` mutes permanently - **Global mutes and the blocklist are server-authoritative** — no public endpoint; admin API (`/api/v1/admin/chat`) or a plugin calling `Gamend.Chat.mute_user/4` - **Real-time moderation events**: the muted player receives `chat_muted` / `chat_unmuted` on their user channel  ## **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. Quests / Progression** One event-driven progression engine covering achievements, daily/weekly quests, time-boxed event quests, chains, and groups:  - **Kinds**: `achievement` (permanent one-shot — the replacement for the old achievements system), `daily`/`weekly` (reset per UTC period), `event` (starts_at/ends_at window), `chain` (requires a prerequisite quest) - **Objectives**: each quest lists objectives `{event, target, params}`; server-side `report_event` advances every matching active quest — there is **no public endpoint to advance progress** (server-authoritative) - **Rewards**: currencies (Economy) and items (Inventory), paid **exactly once** per period via idempotent grants; `auto_claim` quests pay on completion, others via `POST /me/quests/:key/claim` - **My quests**: `GET /me/quests` returns active quests, per-period progress, and a claimable flag; hidden quests appear once completed - **Groups**: quests sharing a `group_key` collapse to one entry carrying `group_size`; `?group=<key>` lists that group's members in full - **Catalog**: `GET /quests` and per-user completions `GET /quests/user/:user_id` (gated by `GAMEND_FEATURES_LIST_QUESTS`) - **Admin management**: definitions CRUD plus per-user grant/reset/force-claim under `/api/v1/admin/quests`  ## **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. Matchmaking** Ticket-based queueing that turns waiting players into hidden, locked lobbies:  - **Join over HTTP** (`POST /matchmaking/tickets` with a `match_params` string map); only tickets with identical params match together — encode mode/map/skill band as parameter values - **A match forms** when a group reaches `max_players`, or has at least `min_players` and the oldest ticket outwaited the timeout; the server creates a hidden lobby, seats everyone and locks it - **The result is a push, not a poll**: matched players receive `match_found` (`lobby_id`, `match_params`) on their user channel; disconnecting cancels your tickets - **Inspect**: `GET /matchmaking/tickets/me` for your ticket, `GET /matchmaking/stats` for queue depths - **Admin management** over HTTP: list/filter tickets, force-cancel, and stats under `/api/v1/admin/matchmaking`  ## **14. Ready checks** One primitive for \"everyone must answer before this proceeds\", with one client-facing surface:  - **A player holds at most one check per lane** — the match lane (lobby ready-up or matchmaking accept) and the party lane (the party's standing board) — so answering needs no id: `GET /me/ready_check` returns `{\"lobby\": …, \"party\": …}` (each null when none) and `POST /me/ready_check` with `{\"ready\": true|false, \"scope\": \"lobby\"|\"party\"}` answers one (scope defaults to `lobby`) - **Two kinds.** `ready` (lobby/party board) is a toggle — a \"no\" just leaves the check open, and it lists every participant. `accept` (match confirmation) is final — one decline fails it for everyone — and returns counts plus your own state, so a pending match does not reveal who you were paired with - **Hosts open one** with `POST /lobbies/ready_check` (host-managed lobbies only; hostless matchmaking lobbies belong to the server), **party leaders** with `POST /parties/ready_check`; either call is a **reset** — it quietly replaces an already-open board with a fresh one over the current members, so the same endpoint serves \"ready check!\", \"force ready\" (with `timeout_ms`) and \"start over\". Call it off with `DELETE /lobbies/ready_check` / `DELETE /parties/ready_check`. The opener is pre-marked ready — clicking the button is their answer - **Failure does nothing on its own**: a declined or timed-out check kicks nobody, starts nothing, and moves no lobby state. It reports who did not answer, and the game (or the host, with the kick they already have) decides - **Live**: `ready_check_started` / `ready_check_updated` / `ready_check_passed` / `ready_check_failed` on the lobby channel, the party channel for a party board, or the user channel for an accept check - **Admin management** over HTTP: list/filter checks, force-cancel, and 24h outcome stats under `/api/v1/admin/ready_checks`  ## **15. 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.  ### **15.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() ```  ### **15.2 Available Channels** - **User channel** (`user:<user_id>`): notifications, friend events, quest progress/completions/claims, party/group invites, tournament events, chat mutes (`chat_muted` / `chat_unmuted`), account bans (`account_banned` / `account_unbanned`), 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  ### **15.3 JS SDK Helper** The `GameRealtime` class (included in this SDK) wraps Phoenix.Socket with convenient channel helpers. Open it from a `GamendSession`, which keeps the player signed in and gives the socket a valid token whenever it reconnects: ```javascript import { GamendSession, AuthenticationApi } from '@ughuuu/gamend' const gamend = new GamendSession('https://your-server.com') await new AuthenticationApi(gamend.client).login({ loginRequest: { email, password } }) const realtime = gamend.realtime() const userChannel = realtime.joinUserChannel(gamend.userId) userChannel.on('notification', payload => console.log(payload)) ``` `phoenix` ships as a dependency of the package, so no extra install is needed.  ## **16. 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).  ### **16.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  ### **16.2 Default DataChannels** - **`events`** (reliable, ordered): important game events (player actions, state changes) - **`state`** (unreliable, unordered): high-frequency position/state sync  ### **16.3 JS SDK Helper** The `GameWebRTC` class (included in this SDK, browser-only) handles signaling automatically: ```javascript import { GameWebRTC } from '@ughuuu/gamend' const realtime = gamend.realtime() // gamend: a signed-in GamendSession const userChannel = realtime.joinUserChannel(gamend.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": {