kodenique-game-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Kodenique
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,172 @@
+# @kodenique/game-sdk
+
+React SDK for real-time game streaming with WebSocket updates and WebRTC video player.
+
+## Features
+
+- 🎮 **Real-time Game Updates** - WebSocket integration with automatic reconnection
+- 📹 **WebRTC Video Streaming** - Ultra-low latency WHEP protocol support
+- 🎯 **Winner Animations** - Automatic full-screen animations when rounds finish
+- 📊 **Live Score Overlays** - Beautiful score displays with team logos and colors
+- 🌐 **Network Monitoring** - Real-time latency and bitrate tracking
+- ⚡ **Auto-Subscribe** - Just pass a game object and SDK handles everything
+- 🎨 **Customizable UI** - Show/hide overlays, custom titles, and styling
+- 📱 **Responsive** - Works on desktop and mobile
+
+## Installation
+
+```bash
+npm install @kodenique/game-sdk
+# or
+yarn add @kodenique/game-sdk
+```
+
+## Quick Start
+
+```tsx
+import { GameProvider, GamePlayer } from '@kodenique/game-sdk';
+
+function App() {
+  return (
+    <GameProvider
+      access_token="your-access-token"
+      socketToken="your-socket-token"
+      environment="production"
+    >
+      <GamePlayer
+        game={gameObject}
+        showScoreOverlay={true}
+        showWinnerAnimation={true}
+        width="100%"
+        height="600px"
+      />
+    </GameProvider>
+  );
+}
+```
+
+## Props
+
+### GamePlayer
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `game` | Game | - | Game object (auto-subscribes to updates) |
+| `gameId` | string | - | Game ID (auto-subscribes to updates) |
+| `streamUrl` | string | - | Direct WHEP stream URL |
+| `showScoreOverlay` | boolean | true | Show score overlay |
+| `showWinnerAnimation` | boolean | true | Show winner animation when round finishes |
+| `showNetworkIndicator` | boolean | true | Show network quality indicator |
+| `showGameTitle` | boolean | true | Show game title |
+| `showRound` | boolean | true | Show round information |
+| `gameTitle` | string | - | Custom game title |
+| `width` | string \| number | "100%" | Player width |
+| `height` | string \| number | "600px" | Player height |
+| `autoPlay` | boolean | true | Auto-play video |
+| `muted` | boolean | true | Mute video by default |
+| `controls` | boolean | true | Show video controls |
+
+## Documentation
+
+- [API Documentation](./API_DOCUMENTATION.md) - Complete API reference
+- [Integration Guide](./INTEGRATION_GUIDE.md) - Implementation details
+
+## Features
+
+### Winner Animations
+
+Automatically shows full-screen animations when rounds finish:
+- Trophy icon for wins, handshake for draws
+- Team color highlights
+- Confetti animation
+- Auto-dismisses after 5 seconds
+- Can be disabled with `showWinnerAnimation={false}`
+
+### WebSocket Integration
+
+Real-time updates via SocketCluster:
+- Automatic decompression of messages
+- Supports multiple message formats
+- Auto-reconnection on disconnect
+- Subscribes to 3 channels per game
+
+### Video Streaming
+
+WebRTC with WHEP protocol:
+- Ultra-low latency streaming
+- Automatic quality detection
+- Network stats monitoring
+- Retry on connection failure
+
+## TypeScript
+
+Fully typed with TypeScript. All interfaces and types are exported.
+
+```tsx
+import type { Game, Team, Round, GamePlayerProps } from '@kodenique/game-sdk';
+```
+
+## Examples
+
+### Disable Winner Animation
+
+```tsx
+<GamePlayer
+  game={game}
+  showWinnerAnimation={false}  // Disable winner animation
+/>
+```
+
+### Custom Title
+
+```tsx
+<GamePlayer
+  game={game}
+  gameTitle="Championship Finals"
+  showGameTitle={true}
+/>
+```
+
+### Hide Score Overlay
+
+```tsx
+<GamePlayer
+  game={game}
+  showScoreOverlay={false}  // Hide all overlays
+/>
+```
+
+### Manual WebSocket Control
+
+```tsx
+import { useGameStream } from '@kodenique/game-sdk';
+
+function CustomComponent() {
+  const { game, isConnected, subscribe, unsubscribe } = useGameStream({
+    gameId: 'game-123',
+    autoSubscribe: true
+  });
+
+  return (
+    <div>
+      <p>Connected: {isConnected ? 'Yes' : 'No'}</p>
+      <p>Round: {game?.rounds.length}</p>
+    </div>
+  );
+}
+```
+
+## Browser Support
+
+- Chrome/Edge (latest)
+- Firefox (latest)
+- Safari (latest)
+- Mobile browsers with WebRTC support
+
+## License
+
+MIT
+
+## Support
+
+For issues or questions, please open an issue on [GitHub](https://github.com/kodenique/game-sdk/issues).

package/dist/GameContext.d.ts

@@ -0,0 +1,4 @@
+import React from "react";
+import { GameProviderProps, GameContextType } from "./types";
+export declare const GameProvider: React.FC<GameProviderProps>;
+export declare const useGameContext: () => GameContextType;

package/dist/GameContext.js

@@ -0,0 +1,327 @@
+var __asyncValues = (this && this.__asyncValues) || function (o) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var m = o[Symbol.asyncIterator], i;
+    return m ? m.call(o) : (o = typeof __values === "function" ? __values(o) : o[Symbol.iterator](), i = {}, verb("next"), verb("throw"), verb("return"), i[Symbol.asyncIterator] = function () { return this; }, i);
+    function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }
+    function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
+};
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+import React, { createContext, useContext, useState, useEffect, useCallback, useRef, } from "react";
+import SocketClient from "socketcluster-wrapper-client";
+import pako from "pako";
+import { API_CONFIG } from "./config";
+const GameContext = createContext(null);
+const options = {
+    secure: true,
+    authType: "ws",
+};
+export const GameProvider = ({ access_token, api_url = "https://game-api.wspo.club/v1/external/games", socketToken, environment = "development", children, }) => {
+    const [activeGames, setActiveGames] = useState([]);
+    const [subscribedGameIds, setSubscribedGameIds] = useState([]);
+    const [isConnected, setIsConnected] = useState(false);
+    const socketRef = useRef(null);
+    const channelsRef = useRef(new Map());
+    // Initialize SocketCluster connection
+    useEffect(() => {
+        console.log("[GameProvider] useEffect triggered");
+        console.log("[GameProvider] socketToken:", socketToken ? "✓ provided" : "✗ MISSING");
+        console.log("[GameProvider] environment:", environment);
+        if (!socketToken) {
+            console.warn("[GameProvider] ⚠️  No socketToken provided - WebSocket connection will NOT be established");
+            return;
+        }
+        const connectSocket = async () => {
+            try {
+                const wsHost = API_CONFIG[environment].websocket_url;
+                if (!socketRef.current) {
+                    console.log("[GameProvider] Creating new SocketClient instance");
+                    socketRef.current = new SocketClient(wsHost, socketToken, options);
+                }
+                else {
+                    console.log("[GameProvider] Reusing existing SocketClient instance");
+                }
+                // Connect
+                const clientSocket = await socketRef.current.connect({
+                    autoConnect: true,
+                    autoReconnect: true,
+                });
+                setIsConnected(true);
+                socketRef.current.clientSocket = clientSocket;
+            }
+            catch (error) {
+                console.error("[GameProvider] ✗ Connection FAILED:", error);
+                console.log("[GameProvider] Connected:", false);
+                setIsConnected(false);
+            }
+        };
+        connectSocket();
+        return () => {
+            // Cleanup channels
+            channelsRef.current.forEach((channel) => {
+                if (channel) {
+                    channel.unsubscribe();
+                }
+            });
+            channelsRef.current.clear();
+            // Close socket
+            if (socketRef.current) {
+                socketRef.current = null;
+            }
+        };
+    }, [socketToken, environment]);
+    // Update game data
+    const updateGame = useCallback((game) => {
+        setActiveGames((prev) => {
+            const existingIndex = prev.findIndex((g) => g.id === game.id);
+            if (existingIndex >= 0) {
+                const updated = [...prev];
+                updated[existingIndex] = game;
+                return updated;
+            }
+            else {
+                return [...prev, game];
+            }
+        });
+    }, []);
+    // Remove game (when ended)
+    const removeGame = useCallback((gameId) => {
+        setActiveGames((prev) => prev.filter((g) => g.id !== gameId));
+    }, []);
+    // Update game score only
+    const updateGameScore = useCallback((gameId, scores) => {
+        setActiveGames((prev) => {
+            return prev.map((game) => {
+                if (game.id === gameId) {
+                    return Object.assign(Object.assign({}, game), { teams: game.teams.map((team, index) => (Object.assign(Object.assign({}, team), { current_score: scores[index] || team.current_score }))) });
+                }
+                return game;
+            });
+        });
+    }, []);
+    const subscribeToGame = useCallback(async (gameId) => {
+        var _a, _b, _c;
+        console.log("[GameProvider] 📡 subscribeToGame called");
+        console.log("[GameProvider] Game ID:", gameId);
+        console.log("[GameProvider] Socket connected:", !!((_a = socketRef.current) === null || _a === void 0 ? void 0 : _a.clientSocket));
+        setSubscribedGameIds((prev) => {
+            if (prev.includes(gameId))
+                return prev;
+            return [...prev, gameId];
+        });
+        if (!((_b = socketRef.current) === null || _b === void 0 ? void 0 : _b.clientSocket)) {
+            console.error("[GameProvider] ⚠️  Cannot subscribe - Socket not connected yet!");
+            console.log("[GameProvider] Current socket state:", socketRef.current);
+            return;
+        }
+        try {
+            const clientSocket = socketRef.current.clientSocket;
+            const prefix = ((_c = clientSocket.authToken) === null || _c === void 0 ? void 0 : _c.prefix) || "game";
+            console.log("[GameProvider] Using channel prefix:", prefix);
+            const channels = [
+                `${prefix}:game:${gameId}`, // Main game channel
+                `${prefix}:game:${gameId}:action`, // Action channel (status changes)
+                `${prefix}:game:${gameId}:rounds`, // Round events channel
+            ];
+            console.log("[GameProvider] Channels to subscribe:", channels);
+            for (const channelName of channels) {
+                if (channelsRef.current.has(channelName)) {
+                    console.log("[GameProvider] ⏭️  Already subscribed to:", channelName);
+                    continue;
+                }
+                console.log("[GameProvider] 🔔 Subscribing to channel:", channelName);
+                // Subscribe to channel
+                const channel = clientSocket.subscribe(channelName);
+                channelsRef.current.set(channelName, channel);
+                console.log("[GameProvider] ✓ Subscribed successfully to:", channelName);
+                // Listen for messages
+                (async () => {
+                    var _a, e_1, _b, _c;
+                    var _d, _e, _f, _g, _h, _j, _k, _l;
+                    console.log("[GameProvider] 👂 Listening for messages on:", channelName);
+                    try {
+                        for (var _m = true, channel_1 = __asyncValues(channel), channel_1_1; channel_1_1 = await channel_1.next(), _a = channel_1_1.done, !_a; _m = true) {
+                            _c = channel_1_1.value;
+                            _m = false;
+                            const data = _c;
+                            try {
+                                console.log("[GameProvider] 📨 Received raw data on:", channelName);
+                                console.log("[GameProvider] Data length:", data === null || data === void 0 ? void 0 : data.length);
+                                // Decompress data (browser-compatible base64 decoding)
+                                const binaryString = atob(data);
+                                const bytes = new Uint8Array(binaryString.length);
+                                for (let i = 0; i < binaryString.length; i++) {
+                                    bytes[i] = binaryString.charCodeAt(i);
+                                }
+                                const decompressed = pako.inflate(bytes, { to: "string" });
+                                const message = JSON.parse(decompressed);
+                                console.log("[GameProvider] 📦 Decompressed message:", message);
+                                // Check if message is a round object directly (has round_number field)
+                                if (message.round_number && message.game_id) {
+                                    // Direct round object from rounds channel
+                                    const roundData = message;
+                                    const action = "direct_update"; // Direct round updates don't have action
+                                    console.log("[GameProvider] 🎯 Round update - Round:", roundData.round_number);
+                                    console.log("[GameProvider] 🎯 Action:", action);
+                                    console.log("[GameProvider] 🎯 Scores - Red:", roundData.red_team_score, "Blue:", roundData.blue_team_score);
+                                    // Update game with round data - preserve existing rounds array
+                                    setActiveGames((prev) => prev.map((g) => {
+                                        if (g.id === gameId) {
+                                            const rounds = g.rounds || [];
+                                            // Update or add the round
+                                            const roundExists = rounds.some((r) => r.id === roundData.id);
+                                            const updatedRounds = roundExists
+                                                ? rounds.map((r) => (r.id === roundData.id ? Object.assign(Object.assign({}, roundData), { _wsAction: action }) : r))
+                                                : [...rounds, Object.assign(Object.assign({}, roundData), { _wsAction: action })];
+                                            // If round has game data with updated teams, merge it (but preserve rounds!)
+                                            if (roundData.game) {
+                                                console.log("[GameProvider] ✨ Merging game data from round (preserving rounds array)");
+                                                const _a = roundData.game, { rounds: _ } = _a, gameDataWithoutRounds = __rest(_a, ["rounds"]);
+                                                return Object.assign(Object.assign(Object.assign({}, g), gameDataWithoutRounds), { rounds: updatedRounds });
+                                            }
+                                            else {
+                                                console.log("[GameProvider] ⚠️  No game data in round, only updating rounds array");
+                                                return Object.assign(Object.assign({}, g), { rounds: updatedRounds });
+                                            }
+                                        }
+                                        return g;
+                                    }));
+                                }
+                                // Handle wrapped message format
+                                else if (message.type === "game_update" || ((_d = message.data) === null || _d === void 0 ? void 0 : _d.game)) {
+                                    // Handle both direct game_update and action channel format
+                                    const gameData = message.game || ((_e = message.data) === null || _e === void 0 ? void 0 : _e.game);
+                                    if (gameData) {
+                                        updateGame(gameData);
+                                    }
+                                }
+                                else if (message.type === "score_update") {
+                                    updateGameScore(gameId, message.scores);
+                                }
+                                else if (message.type === "status_update" ||
+                                    ((_f = message.data) === null || _f === void 0 ? void 0 : _f.action)) {
+                                    // Handle status update from both channels
+                                    const newStatus = message.status || ((_h = (_g = message.data) === null || _g === void 0 ? void 0 : _g.game) === null || _h === void 0 ? void 0 : _h.status);
+                                    if (newStatus) {
+                                        setActiveGames((prev) => prev.map((g) => g.id === gameId
+                                            ? Object.assign(Object.assign({}, g), { status: newStatus }) : g));
+                                    }
+                                }
+                                else if (message.type === "game_ended" ||
+                                    ((_j = message.data) === null || _j === void 0 ? void 0 : _j.action) === "finish" ||
+                                    ((_k = message.data) === null || _k === void 0 ? void 0 : _k.action) === "cancel") {
+                                    removeGame(gameId);
+                                }
+                                else if ((_l = message.data) === null || _l === void 0 ? void 0 : _l.round) {
+                                    // Handle round events: created, status_changed, scores_updated, winner_set, finished
+                                    const roundData = message.data.round;
+                                    const action = message.data.action;
+                                    console.log("[GameProvider] 🎯 Round event:", action, "Round:", roundData.round_number);
+                                    console.log("[GameProvider] 🎯 Scores - Red:", roundData.red_team_score, "Blue:", roundData.blue_team_score);
+                                    // Update game with round data - preserve existing rounds array
+                                    setActiveGames((prev) => prev.map((g) => {
+                                        if (g.id === gameId) {
+                                            const rounds = g.rounds || [];
+                                            // Update or add the round WITH the action type
+                                            let updatedRounds;
+                                            if (action === "created") {
+                                                updatedRounds = [...rounds, Object.assign(Object.assign({}, roundData), { _wsAction: action })];
+                                            }
+                                            else {
+                                                updatedRounds = rounds.map((r) => r.id === roundData.id ? Object.assign(Object.assign({}, roundData), { _wsAction: action }) : r);
+                                            }
+                                            // If round has game data with updated teams, merge it (but preserve rounds!)
+                                            if (roundData.game) {
+                                                console.log("[GameProvider] ✨ Merging game data from round (preserving rounds array)");
+                                                const _a = roundData.game, { rounds: _ } = _a, gameDataWithoutRounds = __rest(_a, ["rounds"]);
+                                                return Object.assign(Object.assign(Object.assign({}, g), gameDataWithoutRounds), { rounds: updatedRounds });
+                                            }
+                                            else {
+                                                console.log("[GameProvider] ⚠️  No game data in round, only updating rounds array");
+                                                return Object.assign(Object.assign({}, g), { rounds: updatedRounds });
+                                            }
+                                        }
+                                        return g;
+                                    }));
+                                }
+                            }
+                            catch (error) {
+                                console.error("[GameProvider] Error processing message:", error);
+                            }
+                        }
+                    }
+                    catch (e_1_1) { e_1 = { error: e_1_1 }; }
+                    finally {
+                        try {
+                            if (!_m && !_a && (_b = channel_1.return)) await _b.call(channel_1);
+                        }
+                        finally { if (e_1) throw e_1.error; }
+                    }
+                })();
+            }
+        }
+        catch (error) {
+            console.error("[GameProvider] Error in subscribeToGame:", error);
+        }
+    }, [updateGame, updateGameScore, removeGame]);
+    // Unsubscribe from a game channel
+    const unsubscribeFromGame = useCallback((gameId) => {
+        var _a, _b;
+        console.log("[GameProvider] Unsubscribing from game:", gameId);
+        setSubscribedGameIds((prev) => prev.filter((id) => id !== gameId));
+        if (!((_a = socketRef.current) === null || _a === void 0 ? void 0 : _a.clientSocket))
+            return;
+        try {
+            const clientSocket = socketRef.current.clientSocket;
+            const prefix = ((_b = clientSocket.authToken) === null || _b === void 0 ? void 0 : _b.prefix) || "game";
+            // Unsubscribe from all channels
+            const channels = [
+                `${prefix}:game:${gameId}`,
+                `${prefix}:game:${gameId}:action`,
+                `${prefix}:game:${gameId}:rounds`,
+            ];
+            for (const channelName of channels) {
+                const channel = channelsRef.current.get(channelName);
+                if (channel) {
+                    channel.unsubscribe();
+                    channelsRef.current.delete(channelName);
+                    console.log("[GameProvider] Unsubscribed from:", channelName);
+                }
+            }
+        }
+        catch (error) {
+            console.error("[GameProvider] Error unsubscribing:", error);
+        }
+    }, []);
+    // Get a specific game
+    const getGame = useCallback((gameId) => {
+        return activeGames.find((game) => game.id === gameId);
+    }, [activeGames]);
+    return (React.createElement(GameContext.Provider, { value: {
+            access_token,
+            api_url,
+            subscribeToGame,
+            unsubscribeFromGame,
+            getGame,
+            updateGame,
+            isConnected,
+            subscribedGameIds,
+            activeGames,
+        } }, children));
+};
+export const useGameContext = () => {
+    const context = useContext(GameContext);
+    if (!context) {
+        throw new Error("useGameContext must be used within a GameProvider");
+    }
+    return context;
+};

package/dist/GameDebug.d.ts

@@ -0,0 +1,5 @@
+import React from 'react';
+export declare const GameDebugPanel: React.FC<{
+    access_token: string;
+}>;
+export declare const GameDebugger: React.FC;