@beta-gamer/angular 0.1.1 → 0.1.3

package/README.md

@@ -0,0 +1,185 @@
+# @beta-gamer/angular
+
+Angular SDK for [Beta Gamer](https://beta-gamer.com) — embed multiplayer games into your app as standalone components. You control the layout, we handle the game logic, matchmaking, and real-time sync.
+
+## Installation
+
+```bash
+npm install @beta-gamer/angular
+```
+
+## Requirements
+
+- Angular 16+
+- A Beta Gamer tenant account and API key → [beta-gamer.com](https://beta-gamer.com)
+
+## Quick start
+
+**1. Create a session from your backend** (never expose your API key on the client)
+
+```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' }],
+  }),
+});
+const { sessionToken } = await res.json();
+```
+
+**2. Initialise the service and render a board**
+
+```ts
+// app.component.ts
+import { Component, inject, OnInit } from '@angular/core';
+import { BetaGamerService, ChessBoardComponent } from '@beta-gamer/angular';
+
+@Component({
+  standalone: true,
+  imports: [ChessBoardComponent],
+  template: `
+    <bg-chess-board
+      style="width:100%;height:500px"
+      [showCoords]="true"
+      [showLastMove]="true"
+      [showLegalMoves]="true"
+      orientation="auto"
+      (onLeave)="handleLeave()"
+    />
+  `,
+})
+export class AppComponent implements OnInit {
+  private svc = inject(BetaGamerService);
+
+  ngOnInit() {
+    this.svc.init('<SESSION_TOKEN>', 'https://api.beta-gamer.com');
+  }
+
+  handleLeave() {
+    // navigate away or show a lobby screen
+  }
+}
+```
+
+## Service
+
+### `BetaGamerService`
+
+Injectable service — call `init()` once with the session token.
+
+```ts
+svc.init(token: string, serverUrl?: string, socketPath?: string, connectSocket?: boolean)
+```
+
+> **`connectSocket`** (default `true`) — set to `false` when using only board components. Board components load the game in an iframe with their own socket. A second socket with the same token causes duplicate connections and AFK/turn bugs.
+
+| Signal | Type | Description |
+|--------|------|-------------|
+| `svc.session` | `Signal<Session>` | Current session (game, matchType, players) |
+| `svc.gameState` | `Signal<GameState>` | Live game state (status, winner, reason) |
+| `svc.token` | `string` | Raw JWT session token |
+| `svc.socket` | `Socket` | Raw Socket.IO socket for custom events |
+
+## Components
+
+All components are standalone — import only what you need.
+
+### Shared (all games)
+
+| Component | Selector | Inputs | Description |
+|-----------|----------|--------|-------------|
+| `PlayerCardComponent` | `<bg-player-card>` | `[player]` (`"self"` \| `"opponent"`) | Player name + active-turn indicator |
+| `TimerComponent` | `<bg-timer>` | `[player]`, `[initialSeconds]?` | Live countdown clock |
+
+### Chess — `ChessBoardComponent`
+
+Selector: `<bg-chess-board>`
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `[serverUrl]` | `string` | `'https://api.beta-gamer.com'` | Base URL of the Beta Gamer server |
+| `[showAfkWarning]` | `boolean` | `true` | Show the built-in AFK countdown banner |
+| `[showCoords]` | `boolean` | `true` | Show rank/file labels (a–h, 1–8) around the board |
+| `[showLastMove]` | `boolean` | `true` | Highlight the from/to squares of the last move |
+| `[showLegalMoves]` | `boolean` | `true` | Show dots on squares where the selected piece can legally move |
+| `[orientation]` | `'white' \| 'black' \| 'auto'` | `'auto'` | Which color is at the bottom. `'auto'` uses the color assigned in `game:started` |
+| `(onLeave)` | `EventEmitter<void>` | — | Emitted when the player taps Leave or exits the game-over modal |
+
+### Checkers — `CheckersBoardComponent`
+
+Selector: `<bg-checkers-board>`
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `[serverUrl]` | `string` | `'https://api.beta-gamer.com'` | Base URL of the Beta Gamer server |
+| `[showAfkWarning]` | `boolean` | `true` | Show the built-in AFK countdown banner |
+| `[showLastMove]` | `boolean` | `true` | Highlight the from/to squares of the last move |
+| `[orientation]` | `'red' \| 'black' \| 'auto'` | `'auto'` | Which color is at the bottom. `'auto'` uses the color assigned in `game:started` |
+| `(onLeave)` | `EventEmitter<void>` | — | Emitted when the player taps Leave or exits the game-over modal |
+
+### Connect 4 — `Connect4BoardComponent`
+
+Selector: `<bg-connect4-board>`
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `[serverUrl]` | `string` | `'https://api.beta-gamer.com'` | Base URL of the Beta Gamer server |
+| `[showAfkWarning]` | `boolean` | `true` | Show the built-in AFK countdown banner |
+| `(onLeave)` | `EventEmitter<void>` | — | Emitted when the player taps Leave or exits the game-over modal |
+
+### Tic-tac-toe — `TictactoeBoardComponent`
+
+Selector: `<bg-tictactoe-board>`
+
+| Input | Type | Default | Description |
+|-------|------|---------|-------------|
+| `[serverUrl]` | `string` | `'https://api.beta-gamer.com'` | Base URL of the Beta Gamer server |
+| `[showAfkWarning]` | `boolean` | `true` | Show the built-in AFK countdown banner |
+| `(onLeave)` | `EventEmitter<void>` | — | Emitted when the player taps Leave or exits the game-over modal |
+
+### Other components
+
+| Component | Selector | Inputs | Game |
+|-----------|----------|--------|------|
+| `ChessMoveHistoryComponent` | `<bg-chess-move-history>` | — | chess |
+| `ChessCapturedPiecesComponent` | `<bg-chess-captured-pieces>` | `[player]` | chess |
+| `Connect4ScoreComponent` | `<bg-connect4-score>` | — | connect4 |
+| `SubwayRunnerGameComponent` | `<bg-subway-runner-game>` | — | subway-runner |
+| `SubwayRunnerScoreComponent` | `<bg-subway-runner-score>` | — | subway-runner |
+| `SubwayRunnerLivesComponent` | `<bg-subway-runner-lives>` | — | subway-runner |
+
+> **`[showAfkWarning]`** (default `true`) — set to `false` to hide the built-in AFK countdown banner and implement your own using the `{game}:afk_warning` / `{game}:afk_warning_cleared` socket events via `svc.socket`.
+
+## Listening to game events
+
+```ts
+import { inject, OnInit } from '@angular/core';
+import { BetaGamerService } from '@beta-gamer/angular';
+
+export class MyComponent implements OnInit {
+  private svc = inject(BetaGamerService);
+
+  ngOnInit() {
+    this.svc.socket.on('chess:afk_warning', ({ playerId, secondsRemaining }) => {
+      console.log('AFK warning for', playerId, secondsRemaining);
+    });
+  }
+}
+```
+
+## 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)
+- [React Native SDK](https://www.npmjs.com/package/@beta-gamer/react-native)

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import * as _socket_io_component_emitter from '@socket.io/component-emitter';
 import * as _angular_core from '@angular/core';
-import { OnDestroy, OnInit, AfterViewInit, ElementRef } from '@angular/core';
+import { OnDestroy, OnInit, AfterViewInit, EventEmitter, ElementRef } from '@angular/core';
 import { Socket } from 'socket.io-client';
 
 type GameType = 'chess' | 'checkers' | 'connect4' | 'tictactoe' | 'subway-runner';
@@ -41,23 +41,55 @@ interface GameState {
 declare class BetaGamerService implements OnDestroy {
     private _socket;
     private _token;
+    /** Decoded session token payload — null until `init()` is called */
     readonly session: _angular_core.WritableSignal<SessionTokenPayload | null>;
+    /** Live game state updated by server events */
     readonly gameState: _angular_core.WritableSignal<GameState>;
     get token(): string;
+    /** The active socket.io connection — available after `init()` with `connectSocket=true` */
     get socket(): Socket<_socket_io_component_emitter.DefaultEventsMap, _socket_io_component_emitter.DefaultEventsMap> | null;
-    init(token: string, serverUrl?: string, socketPath?: string): void;
+    /**
+     * @description Initialises the service with a session token.
+     * Decodes the token, sets up reactive state, and optionally connects the socket.
+     *
+     * @param token - JWT session token from your backend
+     * @param serverUrl - Base URL of the Beta Gamer server
+     * @param socketPath - socket.io path (default `/socket.io`)
+     * @param connectSocket - Set false to skip socket connection (e.g. for SSR or testing)
+     */
+    init(token: string, serverUrl?: string, socketPath?: string, connectSocket?: boolean): void;
     ngOnDestroy(): void;
 }
 
+/**
+ * @description Displays a player's display name and active-turn indicator.
+ * Styled entirely by the consumer via `data-active` and `data-player` attributes.
+ *
+ * @example
+ * <bg-player-card player="self" />
+ * <bg-player-card player="opponent" />
+ */
 declare class PlayerCardComponent {
+    /** Which player to display — `self` = players[0], `opponent` = players[1] */
     player: 'self' | 'opponent';
     private svc;
     get displayName(): string;
     get isActive(): boolean;
 }
 
+/**
+ * @description Live countdown clock that syncs with the server via `game:clock` socket events.
+ * Falls back to a local 1s interval when the game is active.
+ * Renders a `data-low` attribute when under 30 seconds for easy CSS targeting.
+ *
+ * @example
+ * <bg-timer player="self" [initialSeconds]="600" />
+ */
+
 declare class TimerComponent implements OnInit, OnDestroy {
+    /** Which player's clock to display */
     player: 'self' | 'opponent';
+    /** Starting value in seconds (e.g. 600 = 10 min) */
     initialSeconds: number;
     seconds: number;
     private interval;
@@ -67,62 +99,131 @@ declare class TimerComponent implements OnInit, OnDestroy {
     ngOnDestroy(): void;
 }
 
-declare class ChessBoardComponent implements AfterViewInit {
+/**
+ * @description Shared base class for all iframe-based game board components.
+ *
+ * Handles the full iframe lifecycle:
+ * - Injects the session token into the iframe on load via postMessage
+ * - Listens for `bg:leave` messages from the embed and emits `onLeave`
+ * - Cleans up the message listener on destroy
+ *
+ * Subclasses only need to define their embed URL and any game-specific inputs.
+ */
+
+declare abstract class EmbedBoardBase implements AfterViewInit, OnDestroy {
+    /** Base URL of the Beta Gamer server hosting the embed pages */
     serverUrl: string;
+    /** Emitted when the player clicks Leave inside the embed */
+    onLeave: EventEmitter<void>;
     iframeRef: ElementRef<HTMLIFrameElement>;
-    svc: BetaGamerService;
-    get embedUrl(): string;
+    protected svc: BetaGamerService;
+    /** Subclasses return the full embed URL including query params */
+    abstract get embedUrl(): string;
+    private messageHandler;
     ngAfterViewInit(): void;
+    ngOnDestroy(): void;
+    /** Builds a query string from a params object, omitting undefined values */
+    protected buildQuery(params: Record<string, string | undefined>): string;
+}
+
+/**
+ * @description Chess board embed component.
+ * Renders the chess game inside an iframe served by the Beta Gamer embed server.
+ * Supports orientation, coordinate display, last-move highlight, and legal move hints.
+ */
+
+declare class ChessBoardComponent extends EmbedBoardBase {
+    showAfkWarning: boolean;
+    showCoords: boolean;
+    showLastMove: boolean;
+    showLegalMoves: boolean;
+    orientation: 'white' | 'black' | 'auto';
+    get embedUrl(): string;
 }
+
+/**
+ * @description Displays the chess move history in algebraic notation.
+ * Styled entirely by the consumer via the `data-role="move-history"` attribute.
+ */
 declare class ChessMoveHistoryComponent {
 }
+
+/**
+ * @description Displays pieces captured by a given player.
+ * Styled entirely by the consumer via the `data-role="captured-pieces"` attribute.
+ */
 declare class ChessCapturedPiecesComponent {
 }
 
-declare class CheckersBoardComponent implements AfterViewInit {
-    serverUrl: string;
-    iframeRef: ElementRef<HTMLIFrameElement>;
-    svc: BetaGamerService;
+/**
+ * @description Checkers board embed component.
+ * Supports orientation (red/black/auto) and last-move highlight toggle.
+ */
+
+declare class CheckersBoardComponent extends EmbedBoardBase {
+    showAfkWarning: boolean;
+    showLastMove: boolean;
+    orientation: 'red' | 'black' | 'auto';
     get embedUrl(): string;
-    ngAfterViewInit(): void;
 }
 
-declare class Connect4BoardComponent implements AfterViewInit {
-    serverUrl: string;
-    iframeRef: ElementRef<HTMLIFrameElement>;
-    svc: BetaGamerService;
+/**
+ * @description Connect 4 board embed component.
+ */
+
+declare class Connect4BoardComponent extends EmbedBoardBase {
+    showAfkWarning: boolean;
     get embedUrl(): string;
-    ngAfterViewInit(): void;
 }
+
+/**
+ * @description Displays the current score for each player in a Connect 4 session.
+ * Reads from `gameState().scores` — styled entirely by the consumer via data attributes.
+ */
 declare class Connect4ScoreComponent {
-    svc: BetaGamerService;
+    private svc;
     get scores(): {
         id: string;
         score: unknown;
     }[];
 }
 
-declare class TictactoeBoardComponent implements AfterViewInit {
-    serverUrl: string;
-    iframeRef: ElementRef<HTMLIFrameElement>;
-    svc: BetaGamerService;
+/**
+ * @description Tic-tac-toe board embed component.
+ */
+
+declare class TictactoeBoardComponent extends EmbedBoardBase {
+    showAfkWarning: boolean;
     get embedUrl(): string;
-    ngAfterViewInit(): void;
 }
 
+/**
+ * @description Subway Runner game embed component.
+ */
+
 declare class SubwayRunnerGameComponent implements AfterViewInit {
     serverUrl: string;
     iframeRef: ElementRef<HTMLIFrameElement>;
-    svc: BetaGamerService;
+    protected svc: BetaGamerService;
     get embedUrl(): string;
     ngAfterViewInit(): void;
 }
+
+/**
+ * @description Displays the current score in a Subway Runner session.
+ * Reads from `gameState().score`. Style via `data-role="score"`.
+ */
 declare class SubwayRunnerScoreComponent {
-    svc: BetaGamerService;
+    private svc;
     get score(): any;
 }
+
+/**
+ * @description Displays the remaining lives in a Subway Runner session.
+ * Reads from `gameState().lives`. Style via `data-role="lives"`.
+ */
 declare class SubwayRunnerLivesComponent {
-    svc: BetaGamerService;
+    private svc;
     get lives(): any;
 }
 

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as _socket_io_component_emitter from '@socket.io/component-emitter';
 import * as _angular_core from '@angular/core';
-import { OnDestroy, OnInit, AfterViewInit, ElementRef } from '@angular/core';
+import { OnDestroy, OnInit, AfterViewInit, EventEmitter, ElementRef } from '@angular/core';
 import { Socket } from 'socket.io-client';
 
 type GameType = 'chess' | 'checkers' | 'connect4' | 'tictactoe' | 'subway-runner';
@@ -41,23 +41,55 @@ interface GameState {
 declare class BetaGamerService implements OnDestroy {
     private _socket;
     private _token;
+    /** Decoded session token payload — null until `init()` is called */
     readonly session: _angular_core.WritableSignal<SessionTokenPayload | null>;
+    /** Live game state updated by server events */
     readonly gameState: _angular_core.WritableSignal<GameState>;
     get token(): string;
+    /** The active socket.io connection — available after `init()` with `connectSocket=true` */
     get socket(): Socket<_socket_io_component_emitter.DefaultEventsMap, _socket_io_component_emitter.DefaultEventsMap> | null;
-    init(token: string, serverUrl?: string, socketPath?: string): void;
+    /**
+     * @description Initialises the service with a session token.
+     * Decodes the token, sets up reactive state, and optionally connects the socket.
+     *
+     * @param token - JWT session token from your backend
+     * @param serverUrl - Base URL of the Beta Gamer server
+     * @param socketPath - socket.io path (default `/socket.io`)
+     * @param connectSocket - Set false to skip socket connection (e.g. for SSR or testing)
+     */
+    init(token: string, serverUrl?: string, socketPath?: string, connectSocket?: boolean): void;
     ngOnDestroy(): void;
 }
 
+/**
+ * @description Displays a player's display name and active-turn indicator.
+ * Styled entirely by the consumer via `data-active` and `data-player` attributes.
+ *
+ * @example
+ * <bg-player-card player="self" />
+ * <bg-player-card player="opponent" />
+ */
 declare class PlayerCardComponent {
+    /** Which player to display — `self` = players[0], `opponent` = players[1] */
     player: 'self' | 'opponent';
     private svc;
     get displayName(): string;
     get isActive(): boolean;
 }
 
+/**
+ * @description Live countdown clock that syncs with the server via `game:clock` socket events.
+ * Falls back to a local 1s interval when the game is active.
+ * Renders a `data-low` attribute when under 30 seconds for easy CSS targeting.
+ *
+ * @example
+ * <bg-timer player="self" [initialSeconds]="600" />
+ */
+
 declare class TimerComponent implements OnInit, OnDestroy {
+    /** Which player's clock to display */
     player: 'self' | 'opponent';
+    /** Starting value in seconds (e.g. 600 = 10 min) */
     initialSeconds: number;
     seconds: number;
     private interval;
@@ -67,62 +99,131 @@ declare class TimerComponent implements OnInit, OnDestroy {
     ngOnDestroy(): void;
 }
 
-declare class ChessBoardComponent implements AfterViewInit {
+/**
+ * @description Shared base class for all iframe-based game board components.
+ *
+ * Handles the full iframe lifecycle:
+ * - Injects the session token into the iframe on load via postMessage
+ * - Listens for `bg:leave` messages from the embed and emits `onLeave`
+ * - Cleans up the message listener on destroy
+ *
+ * Subclasses only need to define their embed URL and any game-specific inputs.
+ */
+
+declare abstract class EmbedBoardBase implements AfterViewInit, OnDestroy {
+    /** Base URL of the Beta Gamer server hosting the embed pages */
     serverUrl: string;
+    /** Emitted when the player clicks Leave inside the embed */
+    onLeave: EventEmitter<void>;
     iframeRef: ElementRef<HTMLIFrameElement>;
-    svc: BetaGamerService;
-    get embedUrl(): string;
+    protected svc: BetaGamerService;
+    /** Subclasses return the full embed URL including query params */
+    abstract get embedUrl(): string;
+    private messageHandler;
     ngAfterViewInit(): void;
+    ngOnDestroy(): void;
+    /** Builds a query string from a params object, omitting undefined values */
+    protected buildQuery(params: Record<string, string | undefined>): string;
+}
+
+/**
+ * @description Chess board embed component.
+ * Renders the chess game inside an iframe served by the Beta Gamer embed server.
+ * Supports orientation, coordinate display, last-move highlight, and legal move hints.
+ */
+
+declare class ChessBoardComponent extends EmbedBoardBase {
+    showAfkWarning: boolean;
+    showCoords: boolean;
+    showLastMove: boolean;
+    showLegalMoves: boolean;
+    orientation: 'white' | 'black' | 'auto';
+    get embedUrl(): string;
 }
+
+/**
+ * @description Displays the chess move history in algebraic notation.
+ * Styled entirely by the consumer via the `data-role="move-history"` attribute.
+ */
 declare class ChessMoveHistoryComponent {
 }
+
+/**
+ * @description Displays pieces captured by a given player.
+ * Styled entirely by the consumer via the `data-role="captured-pieces"` attribute.
+ */
 declare class ChessCapturedPiecesComponent {
 }
 
-declare class CheckersBoardComponent implements AfterViewInit {
-    serverUrl: string;
-    iframeRef: ElementRef<HTMLIFrameElement>;
-    svc: BetaGamerService;
+/**
+ * @description Checkers board embed component.
+ * Supports orientation (red/black/auto) and last-move highlight toggle.
+ */
+
+declare class CheckersBoardComponent extends EmbedBoardBase {
+    showAfkWarning: boolean;
+    showLastMove: boolean;
+    orientation: 'red' | 'black' | 'auto';
     get embedUrl(): string;
-    ngAfterViewInit(): void;
 }
 
-declare class Connect4BoardComponent implements AfterViewInit {
-    serverUrl: string;
-    iframeRef: ElementRef<HTMLIFrameElement>;
-    svc: BetaGamerService;
+/**
+ * @description Connect 4 board embed component.
+ */
+
+declare class Connect4BoardComponent extends EmbedBoardBase {
+    showAfkWarning: boolean;
     get embedUrl(): string;
-    ngAfterViewInit(): void;
 }
+
+/**
+ * @description Displays the current score for each player in a Connect 4 session.
+ * Reads from `gameState().scores` — styled entirely by the consumer via data attributes.
+ */
 declare class Connect4ScoreComponent {
-    svc: BetaGamerService;
+    private svc;
     get scores(): {
         id: string;
         score: unknown;
     }[];
 }
 
-declare class TictactoeBoardComponent implements AfterViewInit {
-    serverUrl: string;
-    iframeRef: ElementRef<HTMLIFrameElement>;
-    svc: BetaGamerService;
+/**
+ * @description Tic-tac-toe board embed component.
+ */
+
+declare class TictactoeBoardComponent extends EmbedBoardBase {
+    showAfkWarning: boolean;
     get embedUrl(): string;
-    ngAfterViewInit(): void;
 }
 
+/**
+ * @description Subway Runner game embed component.
+ */
+
 declare class SubwayRunnerGameComponent implements AfterViewInit {
     serverUrl: string;
     iframeRef: ElementRef<HTMLIFrameElement>;
-    svc: BetaGamerService;
+    protected svc: BetaGamerService;
     get embedUrl(): string;
     ngAfterViewInit(): void;
 }
+
+/**
+ * @description Displays the current score in a Subway Runner session.
+ * Reads from `gameState().score`. Style via `data-role="score"`.
+ */
 declare class SubwayRunnerScoreComponent {
-    svc: BetaGamerService;
+    private svc;
     get score(): any;
 }
+
+/**
+ * @description Displays the remaining lives in a Subway Runner session.
+ * Reads from `gameState().lives`. Style via `data-role="lives"`.
+ */
 declare class SubwayRunnerLivesComponent {
-    svc: BetaGamerService;
+    private svc;
     get lives(): any;
 }