@tailuge/messaging 1.3.0 → 1.5.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

@@ -40,7 +40,7 @@ const lobby = await client.joinLobby({
 lobby.onUsersChange((users) => {
   console.log(`Online: ${users.length}`);
   users.forEach(u => {
-    const flag = countryToFlag(u._meta?.country);
+    const flag = countryToFlag(u.meta?.country);
     console.log(`${flag} ${u.userName}`);
   });
 });
@@ -66,7 +66,7 @@ const table = await client.joinTable<Move>("table-xyz", "user-123");
 
 table.onMessage((msg) => {
   if (msg.type === "MOVE") {
-    console.log(`Move at: ${msg._meta?.ts}`);
+    console.log(`Move at: ${msg.meta?.ts}`);
   }
 });
 

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

@@ -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.3.0",
+  "version": "1.5.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/",