Repository navigation
REST and WebSocket API
This document details the HTTP REST endpoints and the real-time WebSocket protocol provided by @m3rcena/bridge.
The bridge gateway runs either as a standalone HTTP + WebSocket server or attached to an existing HTTP server (Express, Fastify, Next.js).
import { BridgeServer } from "@m3rcena/bridge";
const server = new BridgeServer(bridge, {
port: 4000, // Standalone port
path: "/bridge", // WebSocket mount path
heartbeatInterval: 30000, // 30s ping-pong keepalive
secretToken: "secret_123", // Optional API authorization
});
await server.start();-
Endpoint:
GET /health - Response:
{
"status": "ok",
"timestamp": 1761984000000
}-
Endpoint:
GET /overview - Response:
{
"activeModules": ["weky", "eco"],
"activeSessionsCount": 3,
"onlineUsersCount": 12,
"totalActionsDispatched": 1420,
"uptimeSeconds": 3600,
"memoryUsage": {
"rss": 54210560,
"heapTotal": 31200000,
"heapUsed": 24800000
}
}-
Endpoint:
GET /sessions - Response: An array of active session snapshots:
[
{
"id": "ttt-guild-ch",
"module": "weky",
"type": "tictactoe",
"platform": "hybrid",
"players": [
{ "id": "102794864", "username": "M3rcena", "platform": "discord" }
],
"currentTurnId": "102794864",
"isEnded": false,
"createdAt": 1761983000000,
"lastUpdated": 1761983020000
}
]-
Endpoint:
POST /action -
Headers:
Content-Type: application/json - Request Body:
{
"module": "weky",
"sessionId": "ttt-guild-ch",
"playerId": "102794864",
"action": "move",
"payload": { "index": 4 },
"sourcePlatform": "dashboard"
}- Success Response (200 OK):
{
"success": true,
"nextTurnId": "opponent_id",
"isEnded": false,
"state": {
"board": ["", "", "", "", "X", "", "", "", ""],
"turn": "O"
}
}- Failure Response (400 Bad Request):
{
"success": false,
"error": "Not your turn or square already occupied"
}All routes matching package base paths (e.g., /api/weky/*, /api/eco/*) are automatically routed to their respective package routers:
-
GET /api/weky/games$\rightarrow$ Weky game metadata catalog -
GET /api/eco/profile/:userId$\rightarrow$ Eco balance, credit score, vault status -
GET /api/weky/cards/gamer-profile?userId=123$\rightarrow$ Canvas PNG image response
Connect to the WebSocket endpoint at ws://<host>:<port>/bridge. All frames are UTF-8 JSON strings.
Announces the client's user identity to track presence and receive targeted audio cues.
{
"type": "identify",
"userId": "102794864",
"username": "M3rcena",
"platform": "dashboard"
}Subscribes the socket to state updates for an active session.
{
"type": "subscribe_session",
"sessionId": "ttt-guild-ch"
}{
"type": "unsubscribe_session",
"sessionId": "ttt-guild-ch"
}Subscribes to all events occurring in a module (e.g. eco transactions or weky matches).
{
"type": "subscribe_module",
"module": "eco"
}Dispatches an interactive action into the bridge engine.
{
"type": "dispatch_action",
"correlationId": "req_abc123",
"module": "weky",
"sessionId": "ttt-guild-ch",
"playerId": "102794864",
"action": "move",
"payload": { "index": 0 }
}{ "type": "ping" }Broadcast to all sockets subscribed to the session whenever the state changes.
{
"type": "sync",
"sessionId": "ttt-guild-ch",
"module": "weky",
"state": {
"board": ["X", "", "", "", "O", "", "", "", ""],
"turn": "X"
},
"currentTurnId": "102794864",
"isEnded": false,
"winnerId": null,
"lastUpdated": 1761984025000
}Returned directly to the requesting client socket matching the correlationId.
{
"type": "action_result",
"correlationId": "req_abc123",
"result": {
"success": true,
"nextTurnId": "opponent_id",
"isEnded": false
}
}Targeted to specific users or broadcast across all dashboard clients.
{
"type": "audio_cue",
"module": "weky",
"soundKey": "move_placed",
"soundUrl": "https://assets.example.com/click.mp3",
"volume": 0.5,
"userId": "102794864"
}{
"type": "notification",
"id": "notif_789",
"title": "Level Up!",
"message": "You reached Level 50!",
"type": "success",
"timestamp": 1761984030000
}{
"type": "pong",
"timestamp": 1761984035000
}GitHub: M3rcena/m3rcena-bridge • NPM: @m3rcena/bridge
- Connecting @m3rcena/weky
- Connecting @m3rcena/eco
- Mounting Custom Routers
- Universal Mounting Standard
- Standalone HTTP & WebSocket Server
- Attaching to Express / Fastify / Next.js
- Complete REST API Route Reference
- Real-Time WebSocket Frame Specification
- Browser & Node Client
- React Hooks & useBridgeSession
- Handling Audio Cues & Haptics
- Sending Inbound Moves