@beta-gamer/react-native 0.1.18 → 0.1.21

package/README.md

@@ -5,132 +5,228 @@ React Native SDK for [Beta Gamer](https://beta-gamer.com) — embed multiplayer
 ## Installation
 
 ```bash
-npm install @beta-gamer/react-native react-native-webview
+npm install @beta-gamer/react-native
 ```
 
-Then link the native module:
+> `react-native-webview` is only required for subway-runner. Chess, Checkers, Connect4, and Tictactoe are fully native.
 
 ```bash
-# iOS
-cd ios && pod install
-
-# Android — no extra steps needed
+# Only if using subway-runner:
+npx expo install react-native-webview          # Expo
+npm install react-native-webview && cd ios && pod install  # Bare RN
 ```
 
 ## Requirements
 
-- React Native 0.73+
-- `react-native-webview` 13+
-- A Beta Gamer tenant account and API key → [beta-gamer.com](https://beta-gamer.com)
+- React Native 0.73+ or Expo SDK 50+
+- A Beta Gamer account and API key → [beta-gamer.com](https://beta-gamer.com)
+
+---
+
+## Quick start — Chess (fully native)
 
-## Quick start
+`ChessBoard` is a self-contained native component. It manages its own socket, renders with RN primitives, and handles matchmaking, clocks, AFK warnings, pawn promotion, and game-over automatically.
 
-**1. Create a session from your backend** (never expose your API key on the client)
+**1. Create a session on your backend** (never call the Beta Gamer API from the app)
 
 ```ts
-const res = await fetch('https://api.beta-gamer.com/v1/sessions', {
-  method: 'POST',
-  headers: {
-    'Authorization': 'Bearer bg_live_xxxx',
-    'Content-Type': 'application/json',
-  },
-  body: JSON.stringify({
-    game: 'chess',
-    matchType: 'matchmaking',
-    players: [{ id: 'user_123', displayName: 'Alex' }],
-  }),
+// Your server — e.g. Express, Next.js API route, Cloudflare Worker
+app.post('/api/game/start', async (req, res) => {
+  const { userId, userName, matchType } = req.body;
+  const response = await fetch('https://api.beta-gamer.com/v1/sessions', {
+    method: 'POST',
+    headers: {
+      'Authorization': 'Bearer bg_live_xxxx',
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      game: 'chess',
+      matchType,
+      players: [{ id: userId, displayName: userName }],
+    }),
+  });
+  const data = await response.json();
+  res.json({ sessionToken: data.sessionToken });
 });
-const { sessionToken } = await res.json();
 ```
 
-**2. Pass the token to your screen and render**
+> ⚠️ **Never call the Beta Gamer API from your app.** Your API key would be bundled into the binary and is trivially extractable from any APK or IPA.
 
-```tsx
-import {
-  BetaGamerProvider,
-  ChessBoard,
-  ChessMoveHistory,
-  PlayerCard,
-  Timer,
-} from '@beta-gamer/react-native';
-import { View, StyleSheet } from 'react-native';
+**2. Lobby screen — fetch the token**
 
-export default function GameScreen({ sessionToken }: { sessionToken: string }) {
+```tsx
+import { useState } from 'react';
+import { View, Button, ActivityIndicator } from 'react-native';
+import { useNavigation } from '@react-navigation/native';
+
+export function ChessLobbyScreen() {
+  const navigation = useNavigation<any>();
+  const [loading, setLoading] = useState(false);
+
+  const startGame = async (matchType: 'matchmaking' | 'bot') => {
+    setLoading(true);
+    const res = await fetch('https://your-api.com/api/game/start', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ game: 'chess', matchType }),
+    });
+    const { sessionToken } = await res.json();
+    navigation.navigate('ChessGame', { sessionToken });
+  };
+
+  if (loading) return <ActivityIndicator />;
   return (
-    <BetaGamerProvider token={sessionToken}>
-      <View style={styles.layout}>
-        <PlayerCard player="opponent" style={styles.card} nameStyle={styles.name} />
-        <Timer player="opponent" style={styles.timer} textStyle={styles.clock} />
+    <View>
+      <Button title="Find opponent" onPress={() => startGame('matchmaking')} />
+      <Button title="vs Bot"        onPress={() => startGame('bot')} />
+    </View>
+  );
+}
+```
 
-        <ChessBoard style={styles.board} />
-        <ChessMoveHistory style={styles.history} textStyle={styles.move} />
+**3. Game screen — drop in `ChessBoard`**
 
-        <PlayerCard player="self" style={styles.card} nameStyle={styles.name} />
-        <Timer player="self" style={styles.timer} textStyle={styles.clock} />
+```tsx
+import { View, StyleSheet } from 'react-native';
+import { useRoute, useNavigation } from '@react-navigation/native';
+import { BetaGamerProvider, ChessBoard } from '@beta-gamer/react-native';
+
+export function ChessGameScreen() {
+  const { sessionToken } = useRoute<any>().params;
+  const navigation = useNavigation();
+
+  return (
+    <BetaGamerProvider
+      token={sessionToken}
+      serverUrl="https://api.beta-gamer.com"
+      connectSocket={false}   // ChessBoard manages its own socket
+    >
+      <View style={styles.screen}>
+        <ChessBoard
+          style={styles.board}
+          onLeave={() => navigation.goBack()}
+        />
       </View>
     </BetaGamerProvider>
   );
 }
 
 const styles = StyleSheet.create({
-  layout: { flex: 1, backgroundColor: '#0f0f0f' },
+  screen: { flex: 1, backgroundColor: '#0a0a0f' },
   board:  { flex: 1 },
-  // ... your styles
 });
 ```
 
+That's it. The board handles everything — no extra components needed.
+
+---
+
+## `BetaGamerProvider` props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `token` | `string` | required | Session token from your backend |
+| `serverUrl` | `string` | `'https://api.beta-gamer.com'` | Your Beta Gamer server URL |
+| `socketPath` | `string` | `'/socket.io'` | Socket.IO path (change if self-hosting) |
+| `connectSocket` | `boolean` | `true` | Set `false` when using board components — they manage their own socket. Using `true` with a board component creates a duplicate connection causing AFK and turn bugs. |
+
+---
+
 ## Components
 
-### Shared (all games)
+### Chess, Checkers, Connect4, Tictactoe (fully native — no WebView)
 
 | Component | Props | Description |
 |-----------|-------|-------------|
-| `BetaGamerProvider` | `token`, `serverUrl?` | Wrap your game UI with this. Handles socket connection and theme. |
-| `PlayerCard` | `player`, `style?`, `nameStyle?`, `indicatorStyle?` | Player name + active-turn indicator |
-| `Timer` | `player`, `initialSeconds?`, `style?`, `textStyle?` | Live countdown clock, syncs with server |
+| `ChessBoard` | `style?`, `showAfkWarning?`, `onLeave?` | Full chess game — socket, board, clocks, AFK, promotion, game-over all built in |
+| `ChessMoveHistory` | `style?`, `textStyle?`, `rowStyle?` | Scrollable move list in algebraic notation |
+| `CheckersBoard` | `style?`, `showAfkWarning?`, `onLeave?` | Full checkers game — piece selection, valid moves, captures, king promotion |
+| `Connect4Board` | `style?`, `showAfkWarning?`, `onLeave?` | Full connect4 game — column drop, winning cell highlight |
+| `TictactoeBoard` | `style?`, `showAfkWarning?`, `onLeave?` | Full tictactoe game — mark placement, winning line highlight |
+
+### Subway Runner (WebView-based)
+
+| Component | Props | Game |
+|-----------|-------|------|
+| `SubwayRunnerGame`, `SubwayRunnerScore`, `SubwayRunnerLives` | `style?` | subway-runner |
 
-### Chess
+### Shared
 
 | Component | Props | Description |
 |-----------|-------|-------------|
-| `ChessBoard` | `style?` | Interactive chess board (WebView) |
-| `ChessMoveHistory` | `style?`, `textStyle?`, `rowStyle?` | Scrollable move list in algebraic notation |
+| `PlayerCard` | `player` (`'self'`\|`'opponent'`), `style?`, `nameStyle?` | Player name + active-turn indicator |
+| `Timer` | `player`, `initialSeconds?`, `style?`, `textStyle?` | Live countdown clock |
+
+---
+
+## Board component props (all 4 games)
+
+All native board components share the same props:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `style` | `ViewStyle` | — | Style for the outer container |
+| `showAfkWarning` | `boolean` | `true` | Show built-in AFK countdown banner. Set `false` to implement your own |
+| `onLeave` | `() => void` | — | Called when player taps Leave or Play again after game over |
+
+---
 
-### Other games
+## `showAfkWarning` — custom AFK UI
 
-| Component | Game |
-|-----------|------|
-| `CheckersBoard` | checkers |
-| `Connect4Board` | connect4 |
-| `TictactoeBoard` | tictactoe |
-| `SubwayRunnerGame`, `SubwayRunnerScore`, `SubwayRunnerLives` | subway-runner |
+If you want to render your own AFK banner, pass `showAfkWarning={false}` and listen to socket events manually:
+
+```tsx
+import { useEffect } from 'react';
+import { useSocket } from '@beta-gamer/react-native';
+
+function MyAfkBanner() {
+  const socket = useSocket();
+
+  useEffect(() => {
+    if (!socket) return;
+    socket.on('chess:afk_warning', ({ playerId, secondsRemaining }) => {
+      // show your own banner
+    });
+    socket.on('chess:afk_warning_cleared', () => {
+      // hide banner
+    });
+    return () => {
+      socket.off('chess:afk_warning');
+      socket.off('chess:afk_warning_cleared');
+    };
+  }, [socket]);
+
+  return null;
+}
+```
+
+> Note: custom AFK UI only works when using hooks (`useSocket`) with `connectSocket={true}`. `ChessBoard` manages its own internal socket — use `showAfkWarning={false}` on the component itself instead.
+
+---
 
 ## Hooks
 
+Available when `connectSocket={true}` (default) and building a fully custom game UI:
+
 ```tsx
-import { useGameState, useSession, useSocket, useTheme } from '@beta-gamer/react-native';
+import { useGameState, useSession, useSocket } from '@beta-gamer/react-native';
 
 const { status, winner, reason } = useGameState();
-const { game, mode, matchType, players } = useSession();
-const socket = useSocket(); // raw Socket.IO socket for custom events
-const theme = useTheme();   // active theme tokens
+const { game, matchType, players } = useSession();
+const socket = useSocket(); // raw Socket.IO socket
 ```
 
-## Differences from `@beta-gamer/react`
-
-| React | React Native |
-|-------|-------------|
-| `className` prop | `style` / `textStyle` / `rowStyle` props |
-| CSS variables for theming | Theme injected via WebView script |
-| `<div>`, `<span>` | `<View>`, `<Text>` |
-| Move history scrolls via CSS | Wrapped in `<ScrollView>` |
+---
 
 ## Supported games
 
 `chess` · `checkers` · `connect4` · `tictactoe` · `subway-runner`
 
+---
+
 ## Links
 
 - [Documentation](https://beta-gamer.com/docs)
 - [Dashboard](https://beta-gamer.com/dashboard)
 - [React SDK](https://www.npmjs.com/package/@beta-gamer/react)
+- [Angular SDK](https://www.npmjs.com/package/@beta-gamer/angular)

package/dist/index.d.mts

@@ -52,9 +52,10 @@ interface BetaGamerProviderProps {
     token: string;
     serverUrl?: string;
     socketPath?: string;
+    connectSocket?: boolean;
     children: React.ReactNode;
 }
-declare function BetaGamerProvider({ token, serverUrl, socketPath, children }: BetaGamerProviderProps): react_jsx_runtime.JSX.Element;
+declare function BetaGamerProvider({ token, serverUrl, socketPath, connectSocket, children }: BetaGamerProviderProps): react_jsx_runtime.JSX.Element;
 declare function useBetaGamer(): BetaGamerContextValue;
 
 /** Returns the current game state (status, players, winner, etc.) */
@@ -82,9 +83,12 @@ interface TimerProps {
 }
 declare function Timer({ player, initialSeconds, style, textStyle }: TimerProps): react_jsx_runtime.JSX.Element;
 
-declare function ChessBoard({ style }: {
+interface Props$3 {
     style?: ViewStyle;
-}): react_jsx_runtime.JSX.Element;
+    showAfkWarning?: boolean;
+    onLeave?: () => void;
+}
+declare function ChessBoard({ style, showAfkWarning, onLeave }: Props$3): react_jsx_runtime.JSX.Element | null;
 
 interface ChessMoveHistoryProps {
     style?: ViewStyle;
@@ -93,17 +97,26 @@ interface ChessMoveHistoryProps {
 }
 declare function ChessMoveHistory({ style, rowStyle, textStyle }: ChessMoveHistoryProps): react_jsx_runtime.JSX.Element;
 
-declare function CheckersBoard({ style }: {
+interface Props$2 {
     style?: ViewStyle;
-}): react_jsx_runtime.JSX.Element;
+    showAfkWarning?: boolean;
+    onLeave?: () => void;
+}
+declare function CheckersBoard({ style, showAfkWarning, onLeave }: Props$2): react_jsx_runtime.JSX.Element | null;
 
-declare function Connect4Board({ style }: {
+interface Props$1 {
     style?: ViewStyle;
-}): react_jsx_runtime.JSX.Element;
+    showAfkWarning?: boolean;
+    onLeave?: () => void;
+}
+declare function Connect4Board({ style, showAfkWarning, onLeave }: Props$1): react_jsx_runtime.JSX.Element | null;
 
-declare function TictactoeBoard({ style }: {
+interface Props {
     style?: ViewStyle;
-}): react_jsx_runtime.JSX.Element;
+    showAfkWarning?: boolean;
+    onLeave?: () => void;
+}
+declare function TictactoeBoard({ style, showAfkWarning, onLeave }: Props): react_jsx_runtime.JSX.Element | null;
 
 declare function SubwayRunnerGame({ style }: {
     style?: ViewStyle;

package/dist/index.d.ts

@@ -52,9 +52,10 @@ interface BetaGamerProviderProps {
     token: string;
     serverUrl?: string;
     socketPath?: string;
+    connectSocket?: boolean;
     children: React.ReactNode;
 }
-declare function BetaGamerProvider({ token, serverUrl, socketPath, children }: BetaGamerProviderProps): react_jsx_runtime.JSX.Element;
+declare function BetaGamerProvider({ token, serverUrl, socketPath, connectSocket, children }: BetaGamerProviderProps): react_jsx_runtime.JSX.Element;
 declare function useBetaGamer(): BetaGamerContextValue;
 
 /** Returns the current game state (status, players, winner, etc.) */
@@ -82,9 +83,12 @@ interface TimerProps {
 }
 declare function Timer({ player, initialSeconds, style, textStyle }: TimerProps): react_jsx_runtime.JSX.Element;
 
-declare function ChessBoard({ style }: {
+interface Props$3 {
     style?: ViewStyle;
-}): react_jsx_runtime.JSX.Element;
+    showAfkWarning?: boolean;
+    onLeave?: () => void;
+}
+declare function ChessBoard({ style, showAfkWarning, onLeave }: Props$3): react_jsx_runtime.JSX.Element | null;
 
 interface ChessMoveHistoryProps {
     style?: ViewStyle;
@@ -93,17 +97,26 @@ interface ChessMoveHistoryProps {
 }
 declare function ChessMoveHistory({ style, rowStyle, textStyle }: ChessMoveHistoryProps): react_jsx_runtime.JSX.Element;
 
-declare function CheckersBoard({ style }: {
+interface Props$2 {
     style?: ViewStyle;
-}): react_jsx_runtime.JSX.Element;
+    showAfkWarning?: boolean;
+    onLeave?: () => void;
+}
+declare function CheckersBoard({ style, showAfkWarning, onLeave }: Props$2): react_jsx_runtime.JSX.Element | null;
 
-declare function Connect4Board({ style }: {
+interface Props$1 {
     style?: ViewStyle;
-}): react_jsx_runtime.JSX.Element;
+    showAfkWarning?: boolean;
+    onLeave?: () => void;
+}
+declare function Connect4Board({ style, showAfkWarning, onLeave }: Props$1): react_jsx_runtime.JSX.Element | null;
 
-declare function TictactoeBoard({ style }: {
+interface Props {
     style?: ViewStyle;
-}): react_jsx_runtime.JSX.Element;
+    showAfkWarning?: boolean;
+    onLeave?: () => void;
+}
+declare function TictactoeBoard({ style, showAfkWarning, onLeave }: Props): react_jsx_runtime.JSX.Element | null;
 
 declare function SubwayRunnerGame({ style }: {
     style?: ViewStyle;