@tailuge/messaging 1.2.0 → 1.4.0

package/MESSAGING_SPEC.md

@@ -131,29 +131,27 @@ interface Table<T = any> {
 
 ## Data Models
 
-### `_meta` (Server-Enriched Metadata)
+### `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.
+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`).
 
 ```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")
+  city: string; // City from IP geolocation
 }
 ```
 
-**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.
+**Note**: The client should NOT include `ua` in published messages — the server adds this 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`.
+Information about a user in the lobby. The `ua` field is **not** set by the client — it is provided by the server via `meta`.
 
 ```typescript
 interface PresenceMessage {
@@ -164,8 +162,8 @@ interface PresenceMessage {
   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)
+  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)
@@ -187,7 +185,7 @@ interface ChallengeMessage {
   recipientId: string;
   ruleType: string;
   tableId?: string; // Optional: table created by challenger
-  _meta?: Meta; // Server-enriched metadata (received messages only)
+  meta?: Meta; // Server-enriched metadata (received messages only)
 }
 ```
 
@@ -215,7 +213,7 @@ interface TableMessage<T = any> {
   type: string;
   senderId: string;
   data: T; // Application-specific payload
-  _meta?: Meta; // Server-enriched metadata (received messages only)
+  meta?: Meta; // Server-enriched metadata (received messages only)
 }
 ```
 
@@ -363,7 +361,7 @@ table.onMessage((msg) => {
   if (msg.type === "MOVE") {
     // msg.data is typed as Move
     applyMove(msg.data);
-    console.log("Move received at:", msg._meta?.ts);
+    console.log("Move received at:", msg.meta?.ts);
   }
 });
 

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/dist/types.d.ts

@@ -1,15 +1,12 @@
 /**
  * Server-enriched metadata added to all messages by Nchan.
- * This is the absolute source of truth for timing and origin.
+ * This is the absolute source of truth for timing.
  */
 export interface Meta {
     ts: string;
-    locale: string;
     ua: string;
     ip: string;
-    origin: string;
     host: string;
-    path: string;
     method: string;
     country: string;
 }
@@ -32,7 +29,7 @@ export interface PresenceMessage {
     opponentId?: string | null;
     seek?: Seek;
     lastSeen?: number;
-    _meta?: Meta;
+    meta?: Meta;
     tableId?: string;
 }
 /**
@@ -46,7 +43,7 @@ export interface ChallengeMessage {
     recipientId: string;
     ruleType: string;
     tableId?: string;
-    _meta?: Meta;
+    meta?: Meta;
 }
 /**
  * Generic structure for table/game events
@@ -55,7 +52,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/dist/types.js

@@ -12,17 +12,14 @@ export function isChallengeMessage(msg) {
  * Returns true if target is not self, not in a game, and not seeking
  */
 export function canChallenge(target, currentUserId) {
-    return (target.userId !== currentUserId &&
-        !target.tableId &&
-        !target.seek);
+    return target.userId !== currentUserId && !target.tableId && !target.seek;
 }
 /**
  * Predicate: can the current user spectate this target's game?
  * Returns true if target is at a table and it's not the current user's table
  */
 export function canSpectate(target, currentTableId) {
-    return (!!target.tableId &&
-        target.tableId !== currentTableId);
+    return !!target.tableId && target.tableId !== currentTableId;
 }
 /**
  * Filter: derive active games from presence list

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AA2FA;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAQ;IACxC,OAAO,GAAG,EAAE,WAAW,KAAK,UAAU,CAAC;AACzC,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,GAAQ;IACzC,OAAO,GAAG,EAAE,WAAW,KAAK,WAAW,CAAC;AAC1C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,MAAuB,EAAE,aAAqB;IACzE,OAAO,CACL,MAAM,CAAC,MAAM,KAAK,aAAa;QAC/B,CAAC,MAAM,CAAC,OAAO;QACf,CAAC,MAAM,CAAC,IAAI,CACb,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,MAAuB,EAAE,cAAuB;IAC1E,OAAO,CACL,CAAC,CAAC,MAAM,CAAC,OAAO;QAChB,MAAM,CAAC,OAAO,KAAK,cAAc,CAClC,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,KAAwB;IAClD,MAAM,OAAO,GAAG,IAAI,GAAG,EAAsB,CAAC;IAE9C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC/B,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE;oBACxB,OAAO,EAAE,IAAI,CAAC,OAAO;oBACrB,OAAO,EAAE,EAAE;oBACX,QAAQ,EAAE,IAAI,CAAC,QAAQ;iBACxB,CAAC,CAAC;YACL,CAAC;YACD,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAE,CAAC,OAAO,CAAC,IAAI,CAAC;gBACtC,EAAE,EAAE,IAAI,CAAC,MAAM;gBACf,IAAI,EAAE,IAAI,CAAC,QAAQ;aACpB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;AACtC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAI,IAAY;IAC1C,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAC7C,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAM,CAAC;IAC/B,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,CAAC,KAAK,CAAC,gCAAgC,EAAE,CAAC,CAAC,CAAC;QACnD,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAwFA;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAQ;IACxC,OAAO,GAAG,EAAE,WAAW,KAAK,UAAU,CAAC;AACzC,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,GAAQ;IACzC,OAAO,GAAG,EAAE,WAAW,KAAK,WAAW,CAAC;AAC1C,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,MAAuB,EAAE,aAAqB;IACzE,OAAO,MAAM,CAAC,MAAM,KAAK,aAAa,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;AAC5E,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,MAAuB,EAAE,cAAuB;IAC1E,OAAO,CAAC,CAAC,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,OAAO,KAAK,cAAc,CAAC;AAC/D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,KAAwB;IAClD,MAAM,OAAO,GAAG,IAAI,GAAG,EAAsB,CAAC;IAE9C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;gBAC/B,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE;oBACxB,OAAO,EAAE,IAAI,CAAC,OAAO;oBACrB,OAAO,EAAE,EAAE;oBACX,QAAQ,EAAE,IAAI,CAAC,QAAQ;iBACxB,CAAC,CAAC;YACL,CAAC;YACD,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAE,CAAC,OAAO,CAAC,IAAI,CAAC;gBACtC,EAAE,EAAE,IAAI,CAAC,MAAM;gBACf,IAAI,EAAE,IAAI,CAAC,QAAQ;aACpB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;AACtC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAI,IAAY;IAC1C,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IAC7C,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAM,CAAC;IAC/B,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,OAAO,CAAC,KAAK,CAAC,gCAAgC,EAAE,CAAC,CAAC,CAAC;QACnD,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/package.json

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