@tailuge/messaging 1.2.0 → 1.3.0

package/SKILL.md

@@ -1,30 +1,33 @@
-# @tailuge/messaging Agent Skill
+---
+name: tailuge-messaging
+description: |
+  Integration guide for @tailuge/messaging library. Use when building applications with:
+  - Real-time presence/lobby systems
+  - User matchmaking via challenges
+  - Game table communication with players and spectators
+  - Nchan-powered transport layer
+---
 
-Use this skill when integrating the `@tailuge/messaging` library into a new project or codebase.
+# @tailuge/messaging
 
-## Installation
+Quick integration guide. See [MESSAGING_SPEC.md](./MESSAGING_SPEC.md) for full API contract.
+
+## Install
 
 ```bash
 npm install @tailuge/messaging
 ```
 
-## Initialization
-
-Create a `MessagingClient` instance with your Nchan server base URL:
+## Quick Start
 
 ```typescript
 import { MessagingClient } from '@tailuge/messaging';
 
-const client = new MessagingClient({
-  baseUrl: "https://your-nchan-server.com",
-});
-
-await client.start();
+const client = new MessagingClient({ baseUrl: "https://your-nchan-server.com" });
+client.start();
 ```
 
-## Getting Online User Count
-
-Join the lobby and listen for user changes:
+## Lobby & Presence
 
 ```typescript
 const lobby = await client.joinLobby({
@@ -35,57 +38,27 @@ const lobby = await client.joinLobby({
 });
 
 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}`);
-    }
+  console.log(`Online: ${users.length}`);
+  users.forEach(u => {
+    const flag = countryToFlag(u._meta?.country);
+    console.log(`${flag} ${u.userName}`);
   });
 });
 ```
 
-## Sending a Challenge
-
-To challenge another user to a game:
+## Challenge Opponent
 
 ```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:
+## Table Messaging
 
 ```typescript
 interface Move { x: number; y: number }
@@ -93,18 +66,14 @@ 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}`);
+    console.log(`Move at: ${msg._meta?.ts}`);
   }
 });
 
-// Send a move
 await table.publish("MOVE", { x: 10, y: 20 });
 ```
 
-## Spectator Updates
-
-Listen for spectator changes at a table:
+## Spectators
 
 ```typescript
 table.onSpectatorChange((spectators) => {
@@ -114,79 +83,31 @@ table.onSpectatorChange((spectators) => {
 
 ## 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;
-}
-```
+## Key Imports
 
-### TableMessage<T>
 ```typescript
-interface TableMessage<T = any> {
-  type: string;
-  senderId: string;
-  data: T;
-  _meta?: Meta;
-}
+import {
+  MessagingClient,
+  canChallenge,
+  canSpectate,
+  activeGames,
+} from '@tailuge/messaging';
 ```
 
-## Helper Predicates
-
-The library exports helper functions:
+## Predicates
 
 ```typescript
-import { canChallenge, canSpectate } from '@tailuge/messaging';
-
-// Check if you can challenge a user
 if (canChallenge(targetUser, currentUserId)) {
-  lobby.challenge(targetUser.userId, "billiards");
+  await lobby.challenge(targetUser.userId, "billiards");
 }
 
-// Check if you can spectate a user
 if (canSpectate(targetUser, currentTableId)) {
-  const table = await client.joinTable(targetUser.tableId, currentUserId);
+  await client.joinTable(targetUser.tableId, currentUserId);
 }
 ```
+
+See [MESSAGING_SPEC.md](./MESSAGING_SPEC.md) for complete interface definitions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailuge/messaging",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "type": "module",
   "description": "A stateful messaging library for Nchan-powered real-time applications.",
   "main": "./dist/index.js",