Skip to content

Bridge Integration

M3rcena edited this page Nov 1, 2026 · 3 revisions

πŸŒ‰ Dashboard Bridge Integration

This guide details how @m3rcena/eco connects with @m3rcena/bridge to power real-time web dashboards, headless banking operations, and canvas card generation.


πŸš€ Unified Connection Patterns

Connecting @m3rcena/eco to @m3rcena/bridge is done in one line:

Pattern A: Constructor Injection (Recommended)

import { M3rcenaBridge } from "@m3rcena/bridge";
import { EcoManager } from "@m3rcena/eco";

export const bridge = new M3rcenaBridge();
export const eco = new EcoManager({
  bridge,
  database: "sqlite",
});

Pattern B: Fluent Chaining (bridge.use)

export const bridge = new M3rcenaBridge();
export const eco = new EcoManager();

bridge.use(eco);

Both patterns automatically register the /api/eco gateway routes and establish the bidirectional state synchronization handshake.


πŸ“‘ Complete REST API Route Reference (/api/eco/*)

When mounted on @m3rcena/bridge, the economy engine automatically exposes the following REST routes:

Method Endpoint Description Query / Body Parameters
GET /api/eco/account/:userId Get full user account ledger (wallet, bank, net worth, vault, credit score). None
GET /api/eco/cards/debit/:userId Returns rendered PNG buffer of user's holographic debit card. ?bankName=...
GET /api/eco/market/overview Returns live prices and 24h metrics for all stocks and crypto. None
GET /api/eco/market/chart/:symbol Returns rendered PNG sparkline / candlestick chart buffer. None
GET /api/eco/leaderboard Returns top accounts ranked by net worth, wallet, or bank. ?sortBy=netWorth&limit=10
GET /api/eco/vault/:userId Returns current bank vault tier and upgrade pricing. None
GET /api/eco/loans/:userId Returns FICO credit score, active debt, and loan offers. None
GET /api/eco/bills/:userId Returns pending municipal utility bills and wealth taxes. None
POST /api/eco/action/transfer Execute peer-to-peer money transfer. { toUserId, amount }
POST /api/eco/action/gamble Place bets on coinflip, slots, dice, or roulette. { game, amount, choice }
POST /api/eco/action/trade-stock Execute stock/crypto buy or sell orders. { symbol, shares, action }

πŸ”Š Scoped Audio Cues Dispatched to Dashboard

The bridge dispatches audio cues to web dashboards when financial events take place:

Sound Key Trigger Event Target Audience
coin_drop Cash earned from work, beg, crime, or daily claims. Specific User
cash_register Shop item purchases and bill settlements. Specific User
jackpot Slot machine 50x Mega Jackpots. All Online Users
alarm Bank robbery attempts and syndicate heists. Specific / Target
upgrade_ding Bank vault tier upgrades and job promotions. Specific User

πŸ’» Web Dashboard Example (@m3rcena/bridge/client)

import { createBridgeClient } from "@m3rcena/bridge/client";

const client = createBridgeClient({
  url: "ws://localhost:3001/bridge",
  userId: "web_admin_1",
});

// Listen for audio cues
client.onAudioCue((cue) => {
  if (cue.soundKey === "coin_drop") {
    new Audio("/sounds/coin.mp3").play();
  }
});

// Listen for real-time economy events
client.onAction((action) => {
  if (action.module === "eco") {
    console.log(`Financial event: ${action.action} by ${action.playerId}`);
  }
});

Clone this wiki locally