@ughuuu/gamend 1.0.0

package/dist/model/UserStats200Response.js

@@ -0,0 +1,91 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports["default"] = void 0;
+var _ApiClient = _interopRequireDefault(require("../ApiClient"));
+var _UserStats200ResponseData = _interopRequireDefault(require("./UserStats200ResponseData"));
+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 _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, 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); } /**
+ * Gamend API
+ * 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 - **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 - **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 `LIST_QUESTS_ENABLED`) - **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)) ``` Requires the `phoenix` npm package as a peer dependency: `npm install phoenix`  ## **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 })) ``` 
+ *
+ * The version of the OpenAPI document: 1.0.0
+ * 
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ *
+ */
+/**
+ * The UserStats200Response model module.
+ * @module model/UserStats200Response
+ * @version 1.0.0
+ */
+var UserStats200Response = /*#__PURE__*/function () {
+  /**
+   * Constructs a new <code>UserStats200Response</code>.
+   * @alias module:model/UserStats200Response
+   */
+  function UserStats200Response() {
+    _classCallCheck(this, UserStats200Response);
+    UserStats200Response.initialize(this);
+  }
+
+  /**
+   * Initializes the fields of this object.
+   * This method is used by the constructors of any subclasses, in order to implement multiple inheritance (mix-ins).
+   * Only for internal use.
+   */
+  return _createClass(UserStats200Response, null, [{
+    key: "initialize",
+    value: function initialize(obj) {}
+
+    /**
+     * Constructs a <code>UserStats200Response</code> from a plain JavaScript object, optionally creating a new instance.
+     * Copies all relevant properties from <code>data</code> to <code>obj</code> if supplied or a new instance if not.
+     * @param {Object} data The plain JavaScript object bearing properties of interest.
+     * @param {module:model/UserStats200Response} obj Optional instance to populate.
+     * @return {module:model/UserStats200Response} The populated <code>UserStats200Response</code> instance.
+     */
+  }, {
+    key: "constructFromObject",
+    value: function constructFromObject(data, obj) {
+      if (data) {
+        obj = obj || new UserStats200Response();
+        if (data.hasOwnProperty('data')) {
+          obj['data'] = _UserStats200ResponseData["default"].constructFromObject(data['data']);
+        }
+      }
+      return obj;
+    }
+
+    /**
+     * Validates the JSON data with respect to <code>UserStats200Response</code>.
+     * @param {Object} data The plain JavaScript object bearing properties of interest.
+     * @return {boolean} to indicate whether the JSON data is valid with respect to <code>UserStats200Response</code>.
+     */
+  }, {
+    key: "validateJSON",
+    value: function validateJSON(data) {
+      // validate the optional field `data`
+      if (data['data']) {
+        // data not null
+        _UserStats200ResponseData["default"].validateJSON(data['data']);
+      }
+      return true;
+    }
+  }]);
+}();
+/**
+ * @member {module:model/UserStats200ResponseData} data
+ */
+UserStats200Response.prototype['data'] = undefined;
+var _default = exports["default"] = UserStats200Response;

package/dist/model/UserStats200ResponseData.js

@@ -0,0 +1,117 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports["default"] = void 0;
+var _ApiClient = _interopRequireDefault(require("../ApiClient"));
+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 _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, 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); } /**
+ * Gamend API
+ * 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 - **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 - **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 `LIST_QUESTS_ENABLED`) - **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)) ``` Requires the `phoenix` npm package as a peer dependency: `npm install phoenix`  ## **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 })) ``` 
+ *
+ * The version of the OpenAPI document: 1.0.0
+ * 
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ *
+ */
+/**
+ * The UserStats200ResponseData model module.
+ * @module model/UserStats200ResponseData
+ * @version 1.0.0
+ */
+var UserStats200ResponseData = /*#__PURE__*/function () {
+  /**
+   * Constructs a new <code>UserStats200ResponseData</code>.
+   * @alias module:model/UserStats200ResponseData
+   */
+  function UserStats200ResponseData() {
+    _classCallCheck(this, UserStats200ResponseData);
+    UserStats200ResponseData.initialize(this);
+  }
+
+  /**
+   * Initializes the fields of this object.
+   * This method is used by the constructors of any subclasses, in order to implement multiple inheritance (mix-ins).
+   * Only for internal use.
+   */
+  return _createClass(UserStats200ResponseData, null, [{
+    key: "initialize",
+    value: function initialize(obj) {}
+
+    /**
+     * Constructs a <code>UserStats200ResponseData</code> from a plain JavaScript object, optionally creating a new instance.
+     * Copies all relevant properties from <code>data</code> to <code>obj</code> if supplied or a new instance if not.
+     * @param {Object} data The plain JavaScript object bearing properties of interest.
+     * @param {module:model/UserStats200ResponseData} obj Optional instance to populate.
+     * @return {module:model/UserStats200ResponseData} The populated <code>UserStats200ResponseData</code> instance.
+     */
+  }, {
+    key: "constructFromObject",
+    value: function constructFromObject(data, obj) {
+      if (data) {
+        obj = obj || new UserStats200ResponseData();
+        if (data.hasOwnProperty('players_in_lobbies')) {
+          obj['players_in_lobbies'] = _ApiClient["default"].convertToType(data['players_in_lobbies'], 'Number');
+        }
+        if (data.hasOwnProperty('players_in_parties')) {
+          obj['players_in_parties'] = _ApiClient["default"].convertToType(data['players_in_parties'], 'Number');
+        }
+        if (data.hasOwnProperty('players_offline')) {
+          obj['players_offline'] = _ApiClient["default"].convertToType(data['players_offline'], 'Number');
+        }
+        if (data.hasOwnProperty('players_online')) {
+          obj['players_online'] = _ApiClient["default"].convertToType(data['players_online'], 'Number');
+        }
+        if (data.hasOwnProperty('players_total')) {
+          obj['players_total'] = _ApiClient["default"].convertToType(data['players_total'], 'Number');
+        }
+      }
+      return obj;
+    }
+
+    /**
+     * Validates the JSON data with respect to <code>UserStats200ResponseData</code>.
+     * @param {Object} data The plain JavaScript object bearing properties of interest.
+     * @return {boolean} to indicate whether the JSON data is valid with respect to <code>UserStats200ResponseData</code>.
+     */
+  }, {
+    key: "validateJSON",
+    value: function validateJSON(data) {
+      return true;
+    }
+  }]);
+}();
+/**
+ * @member {Number} players_in_lobbies
+ */
+UserStats200ResponseData.prototype['players_in_lobbies'] = undefined;
+
+/**
+ * @member {Number} players_in_parties
+ */
+UserStats200ResponseData.prototype['players_in_parties'] = undefined;
+
+/**
+ * @member {Number} players_offline
+ */
+UserStats200ResponseData.prototype['players_offline'] = undefined;
+
+/**
+ * @member {Number} players_online
+ */
+UserStats200ResponseData.prototype['players_online'] = undefined;
+
+/**
+ * @member {Number} players_total
+ */
+UserStats200ResponseData.prototype['players_total'] = undefined;
+var _default = exports["default"] = UserStats200ResponseData;

package/dist/realtime.js

@@ -0,0 +1,370 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports["default"] = exports.GameRealtime = void 0;
+var _phoenix = require("phoenix");
+var _gamend_proto = require("./gamend_proto.js");
+var _excluded = ["format"];
+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 _slicedToArray(r, e) { return _arrayWithHoles(r) || _iterableToArrayLimit(r, e) || _unsupportedIterableToArray(r, e) || _nonIterableRest(); }
+function _nonIterableRest() { throw new TypeError("Invalid attempt to destructure non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); }
+function _iterableToArrayLimit(r, l) { var t = null == r ? null : "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"]; if (null != t) { var e, n, i, u, a = [], f = !0, o = !1; try { if (i = (t = t.call(r)).next, 0 === l) { if (Object(t) !== t) return; f = !1; } else for (; !(f = (e = i.call(t)).done) && (a.push(e.value), a.length !== l); f = !0); } catch (r) { o = !0, n = r; } finally { try { if (!f && null != t["return"] && (u = t["return"](), Object(u) !== u)) return; } finally { if (o) throw n; } } return a; } }
+function _arrayWithHoles(r) { if (Array.isArray(r)) return r; }
+function _createForOfIteratorHelper(r, e) { var t = "undefined" != typeof Symbol && r[Symbol.iterator] || r["@@iterator"]; if (!t) { if (Array.isArray(r) || (t = _unsupportedIterableToArray(r)) || e && r && "number" == typeof r.length) { t && (r = t); var _n = 0, F = function F() {}; return { s: F, n: function n() { return _n >= r.length ? { done: !0 } : { done: !1, value: r[_n++] }; }, e: function e(r) { throw r; }, f: F }; } throw new TypeError("Invalid attempt to iterate non-iterable instance.\nIn order to be iterable, non-array objects must have a [Symbol.iterator]() method."); } var o, a = !0, u = !1; return { s: function s() { t = t.call(r); }, n: function n() { var r = t.next(); return a = r.done, r; }, e: function e(r) { u = !0, o = r; }, f: function f() { try { a || null == t["return"] || t["return"](); } finally { if (u) throw o; } } }; }
+function _unsupportedIterableToArray(r, a) { if (r) { if ("string" == typeof r) return _arrayLikeToArray(r, a); var t = {}.toString.call(r).slice(8, -1); return "Object" === t && r.constructor && (t = r.constructor.name), "Map" === t || "Set" === t ? Array.from(r) : "Arguments" === t || /^(?:Ui|I)nt(?:8|16|32)(?:Clamped)?Array$/.test(t) ? _arrayLikeToArray(r, a) : void 0; } }
+function _arrayLikeToArray(r, a) { (null == a || a > r.length) && (a = r.length); for (var e = 0, n = Array(a); e < a; e++) n[e] = r[e]; return n; }
+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 _objectWithoutProperties(e, t) { if (null == e) return {}; var o, r, i = _objectWithoutPropertiesLoose(e, t); if (Object.getOwnPropertySymbols) { var n = Object.getOwnPropertySymbols(e); for (r = 0; r < n.length; r++) o = n[r], -1 === t.indexOf(o) && {}.propertyIsEnumerable.call(e, o) && (i[o] = e[o]); } return i; }
+function _objectWithoutPropertiesLoose(r, e) { if (null == r) return {}; var t = {}; for (var n in r) if ({}.hasOwnProperty.call(r, n)) { if (-1 !== e.indexOf(n)) continue; t[n] = r[n]; } return t; }
+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, 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); } /**
+ * GameRealtime — Phoenix WebSocket client for gamend.
+ *
+ * Wraps Phoenix.Socket to provide helpers for common gamend channel topics.
+ * The `phoenix` npm package is included as a dependency.
+ *
+ * Usage (browser / Node.js with bundler):
+ *
+ *   import { GameRealtime } from '@ughuuu/gamend'
+ *
+ *   const realtime = new GameRealtime('https://your-server.com', accessToken)
+ *
+ *   // Join the authenticated user channel
+ *   const userChannel = realtime.joinUserChannel(userId)
+ *   userChannel.on('notification_created', (payload) => console.log('notification:', payload))
+ *   userChannel.on('updated', (payload) => console.log('user updated:', payload))
+ *
+ *   // Join a lobby channel
+ *   const lobbyChannel = realtime.joinLobbyChannel(lobbyId)
+ *   lobbyChannel.on('updated', (payload) => console.log('lobby event:', payload))
+ *
+ *   realtime.disconnect()
+ *
+ * Dependency: `phoenix` (bundled with @ughuuu/gamend)
+ */
+var GameRealtime = exports.GameRealtime = /*#__PURE__*/function () {
+  /**
+   * @param {string} serverUrl  - Base HTTP(S) or WS(S) server URL,
+   *                              e.g. "https://game.example.com" or "wss://game.example.com"
+   * @param {string} token      - JWT access token from the REST login endpoints
+   * @param {Object} socketOpts - Optional Phoenix.Socket constructor options.
+   *                              Pass `format: 'protobuf'` to receive server
+   *                              events as protobuf binary frames; channels
+   *                              obtained through the join helpers decode them
+   *                              transparently (timestamps become unix-ms
+   *                              numbers, see proto/gamend_realtime.proto).
+   */
+  function GameRealtime(serverUrl, token) {
+    var socketOpts = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : {};
+    _classCallCheck(this, GameRealtime);
+    // Normalise URL: strip trailing slash, ensure ws(s):// scheme, append /socket
+    var wsUrl = serverUrl.replace(/\/$/, '').replace(/^http(s?):\/\//, function (_m, s) {
+      return "ws".concat(s, "://");
+    }) + '/socket';
+    var format = socketOpts.format,
+      opts = _objectWithoutProperties(socketOpts, _excluded);
+    this._token = token;
+    this._format = format === 'protobuf' ? 'protobuf' : 'json';
+    var params = this._format === 'protobuf' ? {
+      token: token,
+      format: 'protobuf'
+    } : {
+      token: token
+    };
+    this._socket = new _phoenix.Socket(wsUrl, _objectSpread({
+      params: params
+    }, opts));
+    this._socket.connect();
+    /** @type {Map<string, Object>} topic → Phoenix Channel */
+    this._channels = new Map();
+  }
+
+  /**
+   * Registers the game's protobuf metadata schema for an entity (mirrors the
+   * server plugin's UserMeta/LobbyMeta/GroupMeta/PartyMeta registration), so
+   * decoded events expose `metadata` as a plain object in protobuf mode.
+   * @param {string} entity - 'user' | 'lobby' | 'group' | 'party'
+   * @param {Object|Function} schema - protobufjs class, or (Uint8Array) => value
+   */
+  return _createClass(GameRealtime, [{
+    key: "registerMetaSchema",
+    value: function registerMetaSchema(entity, schema) {
+      (0, _gamend_proto.registerMetaSchema)(entity, schema);
+    }
+
+    /**
+     * Registers the game's protobuf KV data schema for a key or '*'-suffixed
+     * key prefix (mirrors the server plugin's kv_schemas/0 registration).
+     * @param {string} pattern - e.g. 'loadout' or 'match:*'
+     * @param {Object|Function} schema - protobufjs class, or (Uint8Array) => value
+     */
+  }, {
+    key: "registerKvSchema",
+    value: function registerKvSchema(pattern, schema) {
+      (0, _gamend_proto.registerKvSchema)(pattern, schema);
+    }
+
+    // ── Channel helpers ──────────────────────────────────────────────────────
+
+    /**
+     * Join the user channel for notifications, presence, and real-time events.
+     * Topic: `"user:<userId>"`
+     * @param {string|number} userId
+     * @param {Object} params - Extra join params merged with the auth token
+     * @returns {Object} Phoenix Channel
+     */
+  }, {
+    key: "joinUserChannel",
+    value: function joinUserChannel(userId) {
+      var params = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+      return this._join("user:".concat(userId), params);
+    }
+
+    /**
+     * Join a lobby channel for in-lobby events (member joins/leaves, updates).
+     * Topic: `"lobby:<lobbyId>"`
+     * @param {string|number} lobbyId
+     * @param {Object} params
+     * @returns {Object} Phoenix Channel
+     */
+  }, {
+    key: "joinLobbyChannel",
+    value: function joinLobbyChannel(lobbyId) {
+      var params = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+      return this._join("lobby:".concat(lobbyId), params);
+    }
+
+    /**
+     * Join the global lobbies feed (lobby list changes).
+     * Topic: `"lobbies"`
+     * @param {Object} params
+     * @returns {Object} Phoenix Channel
+     */
+  }, {
+    key: "joinLobbiesChannel",
+    value: function joinLobbiesChannel() {
+      var params = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+      return this._join('lobbies', params);
+    }
+
+    /**
+     * Join a group channel for group events.
+     * Topic: `"group:<groupId>"`
+     * @param {string|number} groupId
+     * @param {Object} params
+     * @returns {Object} Phoenix Channel
+     */
+  }, {
+    key: "joinGroupChannel",
+    value: function joinGroupChannel(groupId) {
+      var params = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+      return this._join("group:".concat(groupId), params);
+    }
+
+    /**
+     * Join the global groups feed.
+     * Topic: `"groups"`
+     * @param {Object} params
+     * @returns {Object} Phoenix Channel
+     */
+  }, {
+    key: "joinGroupsChannel",
+    value: function joinGroupsChannel() {
+      var params = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+      return this._join('groups', params);
+    }
+
+    /**
+     * Join a party channel for party events.
+     * Topic: `"party:<partyId>"`
+     * @param {string|number} partyId
+     * @param {Object} params
+     * @returns {Object} Phoenix Channel
+     */
+  }, {
+    key: "joinPartyChannel",
+    value: function joinPartyChannel(partyId) {
+      var params = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+      return this._join("party:".concat(partyId), params);
+    }
+
+    // ── Push helpers ─────────────────────────────────────────────────────────
+
+    /**
+     * Push an event to a channel by topic. Returns a Phoenix Push object.
+     * If no topic is given, pushes to the user channel.
+     * @param {string} event
+     * @param {Object} [payload={}]
+     * @param {string} [topic] - defaults to the user channel
+     * @returns {Object} Phoenix Push
+     */
+  }, {
+    key: "push",
+    value: function push(event) {
+      var payload = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+      var topic = arguments.length > 2 ? arguments[2] : undefined;
+      var ch = topic ? this._channels.get(topic) : this._findUserChannel();
+      if (!ch) {
+        throw new Error("No channel found".concat(topic ? " for topic \"".concat(topic, "\"") : '', ". Join it first."));
+      }
+      return ch.push(event, payload);
+    }
+
+    /**
+     * Call a plugin hook via the user channel. Returns a Promise.
+     * @param {string} plugin
+     * @param {string} fn
+     * @param {Array}  [args=[]]
+     * @returns {Promise<any>}
+     */
+  }, {
+    key: "callHook",
+    value: function callHook(plugin, fn) {
+      var _this = this;
+      var args = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : [];
+      return new Promise(function (resolve, reject) {
+        _this.push('call_hook', {
+          plugin: plugin,
+          fn: fn,
+          args: args
+        }).receive('ok', function (resp) {
+          return resolve(resp.data);
+        }).receive('error', function (resp) {
+          return reject(new Error(resp.error || 'unknown_error'));
+        }).receive('timeout', function () {
+          return reject(new Error('timeout'));
+        });
+      });
+    }
+
+    /**
+     * Join an arbitrary channel topic.
+     * @param {string} topic  - Full Phoenix channel topic string
+     * @param {Object} params - Join params merged with the auth token
+     * @returns {Object} Phoenix Channel
+     */
+  }, {
+    key: "joinChannel",
+    value: function joinChannel(topic) {
+      var params = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+      return this._join(topic, params);
+    }
+
+    /**
+     * Leave and remove a channel by topic.
+     * @param {string} topic
+     */
+  }, {
+    key: "leaveChannel",
+    value: function leaveChannel(topic) {
+      var ch = this._channels.get(topic);
+      if (ch) {
+        ch.leave();
+        this._channels["delete"](topic);
+      }
+    }
+
+    /**
+     * Retrieve an already-joined channel by topic.
+     * @param {string} topic
+     * @returns {Object|undefined} Phoenix Channel or undefined if not joined
+     */
+  }, {
+    key: "channel",
+    value: function channel(topic) {
+      return this._channels.get(topic);
+    }
+
+    /**
+     * Access the underlying Phoenix.Socket instance.
+     * @returns {Object}
+     */
+  }, {
+    key: "socket",
+    get: function get() {
+      return this._socket;
+    }
+
+    /**
+     * Disconnect the socket and leave all channels.
+     */
+  }, {
+    key: "disconnect",
+    value: function disconnect() {
+      this._channels.forEach(function (ch) {
+        try {
+          ch.leave();
+        } catch (_) {}
+      });
+      this._channels.clear();
+      this._socket.disconnect();
+    }
+
+    // ── Private ────────────────────────────────────────────────────────────────
+  }, {
+    key: "_join",
+    value: function _join(topic) {
+      var extraParams = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+      if (this._channels.has(topic)) {
+        return this._channels.get(topic);
+      }
+      var ch = this._socket.channel(topic, _objectSpread({
+        token: this._token
+      }, extraParams));
+      if (this._format === 'protobuf') this._wrapBinaryDecode(ch);
+      ch.join().receive('error', function (err) {
+        return console.error("GameRealtime: failed to join channel \"".concat(topic, "\""), err);
+      });
+      this._channels.set(topic, ch);
+      return ch;
+    }
+
+    // On protobuf sockets the server delivers mapped events as binary frames;
+    // decode them before they reach `channel.on(...)` handlers so application
+    // code sees plain objects in both formats.
+  }, {
+    key: "_wrapBinaryDecode",
+    value: function _wrapBinaryDecode(ch) {
+      var originalTrigger = ch.trigger.bind(ch);
+      ch.trigger = function (event, payload, ref, joinRef) {
+        var decoded = payload;
+        if (payload instanceof ArrayBuffer || payload instanceof Uint8Array) {
+          try {
+            var _decodeEvent;
+            decoded = (_decodeEvent = (0, _gamend_proto.decodeEvent)(ch.topic, event, payload)) !== null && _decodeEvent !== void 0 ? _decodeEvent : payload;
+          } catch (err) {
+            console.error("GameRealtime: failed to decode \"".concat(event, "\" on ").concat(ch.topic), err);
+          }
+        }
+        return originalTrigger(event, decoded, ref, joinRef);
+      };
+    }
+  }, {
+    key: "_findUserChannel",
+    value: function _findUserChannel() {
+      var _iterator = _createForOfIteratorHelper(this._channels),
+        _step;
+      try {
+        for (_iterator.s(); !(_step = _iterator.n()).done;) {
+          var _step$value = _slicedToArray(_step.value, 2),
+            topic = _step$value[0],
+            ch = _step$value[1];
+          if (topic.startsWith('user:')) return ch;
+        }
+      } catch (err) {
+        _iterator.e(err);
+      } finally {
+        _iterator.f();
+      }
+      return undefined;
+    }
+  }]);
+}();
+var _default = exports["default"] = GameRealtime;