@tailuge/messaging 1.4.0 → 1.7.0

package/MESSAGING_SPEC.md

@@ -140,7 +140,7 @@ interface Meta {
   ts: string; // ISO timestamp of the request (Source of Truth for time)
   ua: string; // User-Agent header
   ip: string; // Client remote address
-  host: string; // Host header value
+  origin: string; // Origin header value
   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
@@ -172,6 +172,56 @@ interface PresenceMessage {
 }
 ```
 
+#### External Game Integration
+
+When users are redirected from the lobby to an external game page (e.g., billiards), the game page can maintain the user's presence as "in a table" by passing `tableId` when joining the lobby:
+
+```typescript
+// In the external game page
+const client = new MessagingClient({ baseUrl: nchanUrl });
+
+// Join lobby with tableId already set - lobby users see this player as "in game"
+const lobby = await client.joinLobby({
+  messageType: "presence",
+  type: "join",
+  userId: "player1",
+  userName: "Player One",
+  tableId: "table-123",  // Marks user as at table-123
+});
+```
+
+This is useful when:
+- The game was launched from a URL with tableId (e.g., after challenge acceptance)
+- The new page creates a fresh MessagingClient but wants to preserve presence state
+- Other lobby users should see this player as "currently in a game"
+
+To clear the table status (e.g., when the game ends):
+```typescript
+await lobby.updatePresence({ tableId: undefined });
+```
+
+**Page unload:** When the lobby page unloads, a `leave` message is sent automatically. The external game page is expected to call `joinLobby()` with `tableId` to re-establish presence as "in game". This ensures no ghost users if the redirect fails.
+
+#### Minimal Presence for Games
+
+Games that only need online user count (no table joining):
+
+```typescript
+// Join without tableId - user appears as "available" in lobby
+await client.joinLobby({
+  messageType: "presence",
+  type: "join",
+  userId: "player1",
+  userName: "Player One",
+});
+
+// Add tableId when starting a multiplayer game
+await lobby.updatePresence({ tableId: "table-123" });
+
+// Remove tableId when game ends
+await lobby.updatePresence({ tableId: undefined });
+```
+
 ### `ChallengeMessage`
 
 Represents a peer-to-peer challenge request.

package/dist/index.js

@@ -1,6 +1,6 @@
-export * from "./messagingclient";
-export * from "./lobby";
-export * from "./table";
-export * from "./types";
-export * from "./nchanclient";
+export * from "./messagingclient.js";
+export * from "./lobby.js";
+export * from "./table.js";
+export * from "./types.js";
+export * from "./nchanclient.js";
 //# sourceMappingURL=index.js.map

package/dist/lobby.js

@@ -1,6 +1,6 @@
-import { parseMessage } from "./types";
-import { Table } from "./table";
-import { getUID } from "./utils/uid";
+import { parseMessage } from "./types.js";
+import { Table } from "./table.js";
+import { getUID } from "./utils/uid.js";
 /**
  * Manages the global lobby state, including real-time presence tracking and challenge flows.
  */

package/dist/messagingclient.js

@@ -1,6 +1,6 @@
-import { NchanClient } from "./nchanclient";
-import { Lobby } from "./lobby";
-import { Table } from "./table";
+import { NchanClient } from "./nchanclient.js";
+import { Lobby } from "./lobby.js";
+import { Table } from "./table.js";
 /**
  * The main messaging client library entry point.
  * Encapsulates transport logic and provides access to lobby and table functionality.

package/dist/table.js

@@ -1,4 +1,4 @@
-import { parseMessage } from "./types";
+import { parseMessage } from "./types.js";
 /**
  * Represents a specific communication channel for a 2-player/spectator scenario at a table.
  * Uses `any` as default for internal storage flexibility; consumers should use `unknown` or specific types.

package/dist/types.d.ts

@@ -6,7 +6,7 @@ export interface Meta {
     ts: string;
     ua: string;
     ip: string;
-    host: string;
+    origin: string;
     method: string;
     country: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tailuge/messaging",
-  "version": "1.4.0",
+  "version": "1.7.0",
   "type": "module",
   "description": "A stateful messaging library for Nchan-powered real-time applications.",
   "main": "./dist/index.js",
@@ -23,7 +23,7 @@
     "test:debug": "npm run playwright",
     "lint": "tsc --noEmit && npx oxlint src test",
     "prettify": "npx oxfmt src test",
-    "build": "tsc --declaration",
+    "build": "tsc --declaration && node scripts/add-js-extensions.js",
     "release": "npm version minor --no-git-tag-version && npm run build",
     "build:all": "npm run build && npm run build:example && npm run docker:start",
     "build:example": "mkdir -p docker/html/example && npx esbuild example/src/client.ts --bundle --outfile=docker/html/example/client.js && cp example/*.html docker/html/example/",