@tailuge/messaging 1.1.0 → 1.2.0

package/MESSAGING_SPEC.md

@@ -0,0 +1,391 @@
+# Multi-User Messaging Library Specification
+
+## Overview
+
+This document outlines the requirements and contract for a unified messaging library designed to handle presence and real-time synchronization. The library uses the existing `NchanClient` as a transport layer (WebSockets for subscribe, POST for publish) and provides a semantic, stateful API for turn-based multi-user applications.
+
+## Goals
+
+- **Zero WebSocket Dependencies**: The consumer project should not interact with WebSockets directly.
+- **Unified Client**: A single entry point for both global presence (lobby) and specific table messaging.
+- **Stateful Presence**: Internal management of online users, including heartbeats and stale user pruning.
+- **Semantic API**: Interaction through high-level methods rather than raw channel/URL manipulation.
+- **Platform Agnostic**: Compatible with both Browser and Node.js environments.
+- **Transport Reuse**: Leverages existing `NchanClient` from `src/lobby/nchanclient.ts` as the underlying transport.
+
+---
+
+## Core API Contract
+
+### `MessagingClient`
+
+The main class exposed by the library. Uses `NchanClient` internally for all transport operations.
+
+```typescript
+interface MessagingClient {
+  /**
+   * Initialize and start the client.
+   * Handles initial connection and automatic reconnection logic.
+   * In browser environments, attaches lifecycle event listeners.
+   */
+  start(): void;
+
+  /**
+   * Stop all connections, timers (heartbeats), and clean up resources.
+   */
+  stop(): Promise<void>;
+
+  /**
+   * Joins the global lobby to broadcast presence and see other online users.
+   */
+  joinLobby(user: PresenceMessage, options?: LobbyOptions): Promise<Lobby>;
+
+  /**
+   * Joins a specific table (game room) for 2-player/spectator communication.
+   */
+  joinTable<T = any>(tableId: string, userId: string): Promise<Table<T>>;
+}
+```
+
+### `Lobby`
+
+Represents the global presence state and matchmaking.
+
+```typescript
+interface Lobby {
+  /**
+   * Stream of the current online users.
+   * Emits the full list whenever users join, leave, or time out.
+   * The list must be sorted alphabetically by `userName` (case-insensitive).
+   */
+  onUsersChange(callback: (users: PresenceMessage[]) => void): void;
+
+  /**
+   * Update the current user's presence information (e.g., change name).
+   */
+  updatePresence(update: Partial<PresenceMessage>): Promise<void>;
+
+  /**
+   * Challenge another user to a game.
+   * Returns the ID of the table created for the challenge.
+   */
+  challenge(userId: string, ruleType: string): Promise<string>;
+
+  /**
+   * Accept an incoming challenge.
+   * Returns the Table instance for the accepted game.
+   */
+  acceptChallenge(userId: string, ruleType: string, tableId: string): Promise<Table>;
+
+  /**
+   * Decline an incoming challenge.
+   */
+  declineChallenge(userId: string, ruleType: string): Promise<void>;
+
+  /**
+   * Cancel an outgoing challenge.
+   */
+  cancelChallenge(userId: string, ruleType: string): Promise<void>;
+
+  /**
+   * Subscribe to incoming challenges directed at the current user.
+   */
+  onChallenge(callback: (challenge: ChallengeMessage) => void): void;
+
+  /**
+   * Leave the lobby.
+   */
+  leave(): Promise<void>;
+}
+```
+
+### `Table`
+
+Represents a specific communication channel for a 2-player/spectator scenario at a table.
+
+```typescript
+interface Table<T = any> {
+  /**
+   * Broadcast an event to all participants at the table.
+   */
+  publish(type: string, data: T): Promise<void>;
+
+  /**
+   * Subscribe to events published by other participants.
+   */
+  onMessage(callback: (event: TableMessage<T>) => void): void;
+
+  /**
+   * Subscribe to changes in the spectator list.
+   */
+  onSpectatorChange(callback: (spectators: PresenceMessage[]) => void): void;
+
+  /**
+   * Leave the table.
+   */
+  leave(): Promise<void>;
+}
+```
+
+---
+
+## Data Models
+
+### `_meta` (Server-Enriched Metadata)
+
+All messages published through the transport layer are automatically enriched by the server with metadata from HTTP headers and connection info. This `_meta` object is **added by the server** and should be used by clients as the absolute source of truth for timing (`ts`) and origin.
+
+```typescript
+interface Meta {
+  ts: string; // ISO timestamp of the request (Source of Truth for time)
+  locale: string; // Accept-Language header (use for flag rendering)
+  ua: string; // User-Agent header
+  ip: string; // Client remote address
+  origin: string; // Origin header value
+  host: string; // Host header value
+  path: string; // Request URI path
+  method: string; // HTTP method (always POST for publish)
+  country: string; // Country code from IP (e.g., "US", "GB", "XX")
+}
+```
+
+**Note**: The client should NOT include `locale` or `ua` in published messages — the server adds these automatically from HTTP headers. This ensures reliable, tamper-resistant metadata for UI features like flag rendering.
+
+### `PresenceMessage`
+
+Information about a user in the lobby. The `locale` and `ua` fields are **not** set by the client — they are provided by the server via `_meta`.
+
+```typescript
+interface PresenceMessage {
+  messageType: "presence";
+  type: "join" | "heartbeat" | "leave";
+  userId: string;
+  userName: string;
+  ruleType?: string;
+  opponentId?: string | null;
+  seek?: Seek;
+  lastSeen?: number; // Managed internally for pruning (derived from _meta.ts)
+  _meta?: Meta; // Server-enriched metadata (received messages only)
+
+  // Current game state:
+  // - If present: user is playing or spectating at that table (available for spectating)
+  // - If absent: user is available for new games
+  tableId?: string;
+}
+```
+
+### `ChallengeMessage`
+
+Represents a peer-to-peer challenge request.
+
+```typescript
+interface ChallengeMessage {
+  messageType: "challenge";
+  type: "offer" | "accept" | "decline" | "cancel";
+  challengerId: string;
+  challengerName: string;
+  recipientId: string;
+  ruleType: string;
+  tableId?: string; // Optional: table created by challenger
+  _meta?: Meta; // Server-enriched metadata (received messages only)
+}
+```
+
+### `TableInfo` (UNDER REVIEW)
+
+Lobby-level information about an active game table.
+
+```typescript
+interface TableInfo {
+  tableId: string;
+  ruleType: string;
+  players: { id: string; name: string }[];
+  spectatorCount: number;
+  status: "waiting" | "playing" | "finished";
+  createdAt: number;
+}
+```
+
+### `TableMessage`
+
+A generic structure for table/game events. Replaces raw payloads with a structured, meta-aware event.
+
+```typescript
+interface TableMessage<T = any> {
+  type: string;
+  senderId: string;
+  data: T; // Application-specific payload
+  _meta?: Meta; // Server-enriched metadata (received messages only)
+}
+```
+
+---
+
+## Derived State & Logic
+
+Clients can derive additional state from the presence data provided by the `Lobby`.
+
+### 1. Active Games List
+
+#### `activeGames(users: PresenceMessage[]): ActiveGame[]`
+
+Filters users with a `tableId` and returns one entry per unique table.
+
+```typescript
+interface ActiveGame {
+  tableId: string;
+  players: { id: string; name: string }[];
+  ruleType?: string;
+}
+```
+
+**Note**: Spectator vs player distinction is not available in presence data - all users with `tableId` are included as "players".
+
+### 2. Predicates
+
+Exported helper functions for consumer use.
+
+#### `canChallenge(target: PresenceMessage, currentUserId: string): boolean`
+Returns true if:
+- `target.userId !== currentUserId` (not self)
+- `!target.tableId` (not already at a table)
+- `!target.seek` (not seeking a game)
+
+#### `canSpectate(target: PresenceMessage, currentTableId?: string): boolean`
+Returns true if:
+- `target.tableId` exists (is at a table)
+- `target.tableId !== currentTableId` (not already at this table)
+
+---
+
+## Internal Requirements
+
+### 1. Presence Management
+
+- **Heartbeat**: The library must automatically send periodic "heartbeat" messages (e.g., every 60 seconds) to the lobby while active.
+- **Pruning**: The library must maintain an internal map of users and automatically remove users who haven't sent a heartbeat within a specific TTL (e.g., 90 seconds).
+- **Unload Handling**: In browser environments, the library should attempt to send a "leave" message on `beforeunload` or `pagehide`.
+
+### 2. Transport & Reconnection
+
+- **Transport Layer**: Uses `NchanClient` from `src/lobby/nchanclient.ts` as the underlying transport. The WebSocket/POST abstraction is handled internally. `NchanClient` remains transport-agnostic and platform-neutral (Browser + Node.js).
+- **Resilience**:
+  - Automatic exponential backoff for reconnection on WebSocket failure.
+  - Transparently handle transition between online/offline states.
+- **Concurrency**: Ensure multiple `Table` instances can coexist if needed (though typically one game at a time).
+
+### 3. Message Retention
+
+The Nchan server retains presence messages for a configurable duration (default: 90 seconds, 2000 messages). This ensures:
+- Late subscribers receive buffered presence messages from existing users
+- Clients reconnecting can see active users without waiting for the next heartbeat
+- The system is resilient to brief network interruptions
+
+**Note**: This is handled by the Nchan server configuration (`nchan_message_timeout` and `nchan_message_buffer_length`).
+
+### 3. Page Visibility & Browser Lifecycle
+
+Page visibility handling (`pagehide`, `pageshow`, `visibilitychange`) is the responsibility of `MessagingClient` (application layer), **not** `NchanClient` (transport layer). This keeps the transport layer platform-agnostic.
+
+`MessagingClient` should:
+
+- Listen for `pagehide` to close connections and send a "leave" presence message
+- Listen for `pageshow` (with `event.persisted`) to restore connections from bfcache
+- Track `document.hidden` state to pause/resume heartbeats
+
+```typescript
+// Example pattern for MessagingClient
+// Note: MessagingClient does NOT have direct socket access.
+// It calls stop() on subscriptions returned by NchanClient, or exposes its own stop() method.
+
+private handlePageHide = (): void => {
+  this.stop(); // Stops all subscriptions and sends "leave" presence
+};
+
+private handlePageShow = (event: PageTransitionEvent): void => {
+  if (event.persisted) {
+    this.start().then(() => this.joinLobby(this.currentUser));
+  }
+};
+```
+
+### 3. State Synchronization
+
+- The library should ensure that when a user joins a lobby, they receive the current "state of the world" or quickly populate it via incoming heartbeats.
+- For tables, it should provide a reliable pipe for sequence-sensitive events (optionally implementing sequence numbering if required by the transport).
+
+---
+
+## Accepted Concerns
+
+### 1. Race Conditions in Matchmaking
+
+### 2. Presence Scaling ($O(N^2)$)
+
+### 3. State Reconstruction
+
+Since the transport retains messages server-side, a new client joining the lobby will receive buffered presence messages from existing users.
+
+---
+
+## Usage Example (Conceptual)
+
+```typescript
+const client = new MessagingClient({
+  baseUrl: "billiards-network.onrender.com",
+});
+
+await client.start();
+
+// Lobby interaction
+const lobby = await client.joinLobby({
+  messageType: "presence",
+  type: "join",
+  userId: "user-123",
+  userName: "Alice",
+});
+
+lobby.onUsersChange((users) => {
+  console.log("Online users:", users.length);
+});
+
+lobby.onChallenge((challenge) => {
+  if (confirm(`Accept challenge from ${challenge.challengerName}?`)) {
+    lobby.acceptChallenge(challenge.challengerId, challenge.ruleType, challenge.tableId);
+  }
+});
+
+// Table interaction with a generic move type
+interface Move { x: number; y: number }
+const table = await client.joinTable<Move>("table-xyz", "user-123");
+
+table.onMessage((msg) => {
+  if (msg.type === "MOVE") {
+    // msg.data is typed as Move
+    applyMove(msg.data);
+    console.log("Move received at:", msg._meta?.ts);
+  }
+});
+
+table.publish("MOVE", { x: 10, y: 20 });
+```
+
+---
+
+## Future Considerations
+
+### 1. `beforeunload` Handler
+
+The current implementation uses `pagehide` to handle browser page dismissal. An alternative approach is to use `beforeunload` to send a synchronous (or near-synchronous) "leave" presence message before the page unloads. This provides a fallback for browsers where `pagehide` may not fire reliably.
+
+Trade-offs:
+- `beforeunload` is synchronous and may delay page dismissal
+- Not supported in all browsers (e.g., Safari iOS)
+- `pagehide` is the modern recommended approach, but may not send network requests in some cases
+
+### 2. `joinTable` Behavior
+
+The current `joinTable` method automatically updates the user's presence to include `tableId` (marking them as "at a table"). Future iterations could:
+- Make this behavior optional via a configuration flag
+- Allow spectating without affecting the user's availability status
+- Provide separate methods: `joinTableAsPlayer()` vs. `joinTableAsSpectator()`

package/README.md

@@ -77,5 +77,19 @@ npm run docker:build
 
 - **Linting**: `npm run lint`
 - **Formatting**: `npm run format`
+
+## Publishing
+
+To release a new version to npm:
+
+```bash
+npm run release  # Builds and bumps version
+npm login        # Login to npm (if needed)
+npm publish      # Publish to npm registry
+```
+
+## Additional Documentation
+
 - **Specification**: See [MESSAGING_SPEC.md](./MESSAGING_SPEC.md) for the API contract and data models.
+- **Usage Guide**: See [SKILL.md](./SKILL.md) for a quick reference guide.
 - **Architectural Overview**: See [AGENTS.md](./AGENTS.md) for the design patterns used.

package/SKILL.md

@@ -0,0 +1,192 @@
+# @tailuge/messaging Agent Skill
+
+Use this skill when integrating the `@tailuge/messaging` library into a new project or codebase.
+
+## Installation
+
+```bash
+npm install @tailuge/messaging
+```
+
+## Initialization
+
+Create a `MessagingClient` instance with your Nchan server base URL:
+
+```typescript
+import { MessagingClient } from '@tailuge/messaging';
+
+const client = new MessagingClient({
+  baseUrl: "https://your-nchan-server.com",
+});
+
+await client.start();
+```
+
+## Getting Online User Count
+
+Join the lobby and listen for user changes:
+
+```typescript
+const lobby = await client.joinLobby({
+  messageType: "presence",
+  type: "join",
+  userId: "user-123",
+  userName: "Alice",
+});
+
+lobby.onUsersChange((users) => {
+  console.log("Online users:", users.length);
+});
+```
+
+## Getting User List
+
+The same `onUsersChange` callback provides the full user list:
+
+```typescript
+lobby.onUsersChange((users) => {
+  // Users are sorted alphabetically by userName
+  users.forEach(user => {
+    console.log(`${user.userName} (${user.userId})`);
+    if (user.tableId) {
+      console.log(`  Playing at table: ${user.tableId}`);
+    }
+  });
+});
+```
+
+## Sending a Challenge
+
+To challenge another user to a game:
+
+```typescript
+// challenge(userId, ruleType) returns the table ID
+const tableId = await lobby.challenge(targetUserId, "billiards");
+console.log(`Challenge sent, table created: ${tableId}`);
+```
+
+## Receiving Challenges
+
+Listen for incoming challenges:
+
+```typescript
+lobby.onChallenge((challenge) => {
+  console.log(`${challenge.challengerName} challenged you to ${challenge.ruleType}`);
+  
+  if (challenge.type === "offer") {
+    // Accept the challenge
+    lobby.acceptChallenge(challenge.challengerId, challenge.ruleType, challenge.tableId);
+    
+    // Or decline
+    // lobby.declineChallenge(challenge.challengerId, challenge.ruleType);
+  }
+});
+```
+
+## Joining a Table
+
+Connect to a specific game table:
+
+```typescript
+interface Move { x: number; y: number }
+const table = await client.joinTable<Move>("table-xyz", "user-123");
+
+table.onMessage((msg) => {
+  if (msg.type === "MOVE") {
+    const move = msg.data as Move;
+    console.log(`Move received at: ${msg._meta?.ts}`);
+  }
+});
+
+// Send a move
+await table.publish("MOVE", { x: 10, y: 20 });
+```
+
+## Spectator Updates
+
+Listen for spectator changes at a table:
+
+```typescript
+table.onSpectatorChange((spectators) => {
+  console.log(`Spectators: ${spectators.length}`);
+});
+```
+
+## Cleanup
+
+When done, stop the client:
+
+```typescript
+await client.stop();
+```
+
+## Key Interfaces
+
+### PresenceMessage
+```typescript
+interface PresenceMessage {
+  messageType: "presence";
+  type: "join" | "heartbeat" | "leave";
+  userId: string;
+  userName: string;
+  ruleType?: string;
+  tableId?: string;
+  // ... other fields
+}
+```
+
+### Meta
+```typescript
+interface Meta {
+  ts: string;      // ISO timestamp from server
+  locale: string;  // Accept-Language header
+  ua: string;      // User-Agent header
+  ip: string;      // Client remote address
+  origin: string;  // Origin header value
+  host: string;    // Host header value
+  path: string;    // Request URI path
+  method: string;  // HTTP method
+  country: string; // Country code from IP (e.g., "US", "GB", "XX")
+}
+```
+
+### ChallengeMessage
+```typescript
+interface ChallengeMessage {
+  messageType: "challenge";
+  type: "offer" | "accept" | "decline" | "cancel";
+  challengerId: string;
+  challengerName: string;
+  recipientId: string;
+  ruleType: string;
+  tableId?: string;
+}
+```
+
+### TableMessage<T>
+```typescript
+interface TableMessage<T = any> {
+  type: string;
+  senderId: string;
+  data: T;
+  _meta?: Meta;
+}
+```
+
+## Helper Predicates
+
+The library exports helper functions:
+
+```typescript
+import { canChallenge, canSpectate } from '@tailuge/messaging';
+
+// Check if you can challenge a user
+if (canChallenge(targetUser, currentUserId)) {
+  lobby.challenge(targetUser.userId, "billiards");
+}
+
+// Check if you can spectate a user
+if (canSpectate(targetUser, currentTableId)) {
+  const table = await client.joinTable(targetUser.tableId, currentUserId);
+}
+```

package/dist/types.d.ts

@@ -2,7 +2,7 @@
  * Server-enriched metadata added to all messages by Nchan.
  * This is the absolute source of truth for timing and origin.
  */
-export interface _Meta {
+export interface Meta {
     ts: string;
     locale: string;
     ua: string;
@@ -32,7 +32,7 @@ export interface PresenceMessage {
     opponentId?: string | null;
     seek?: Seek;
     lastSeen?: number;
-    _meta?: _Meta;
+    _meta?: Meta;
     tableId?: string;
 }
 /**
@@ -46,7 +46,7 @@ export interface ChallengeMessage {
     recipientId: string;
     ruleType: string;
     tableId?: string;
-    _meta?: _Meta;
+    _meta?: Meta;
 }
 /**
  * Generic structure for table/game events
@@ -55,7 +55,7 @@ export interface TableMessage<T = unknown> {
     type: string;
     senderId: string;
     data: T;
-    _meta?: _Meta;
+    _meta?: Meta;
 }
 /**
  * Lobby-level information about an active game table

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailuge/messaging",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "type": "module",
   "description": "A stateful messaging library for Nchan-powered real-time applications.",
   "main": "./dist/index.js",
@@ -12,7 +12,9 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "MESSAGING_SPEC.md",
+    "SKILL.md"
   ],
   "scripts": {
     "test": "jest --config test/jest.config.cjs --verbose",