feat(api): add WebSocket transfer subscription endpoint

[0xDeon]

Summary

Closes #33

Real-time push notifications for token transfers via WebSocket. Clients subscribe to an address and receive a JSON payload for every new transfer that is indexed where that address appears as sender or recipient.

What was implemented

New files

File	Purpose
src/events.ts	Singleton EventEmitter that publishes transfer:new events. setMaxListeners(0) prevents Node.js warnings with many concurrent subscribers.
src/ws.ts	WebSocket server using noServer: true + manual upgrade event handling. Parses address from URL, registers a per-socket handler, forwards matching events, removes handler on close/error to prevent memory leaks.

Modified files

File	Change
src/indexer.ts	Calls emitTransfer(record) for every record after a successful upsertTransfers batch.
src/index.ts	Replaces app.listen() with http.createServer(app) so the HTTP server can handle WebSocket upgrade requests on the same port. Calls attachWebSocketServer(server).

Endpoint

ws://host/subscribe/:address

• :address — any Stellar address (sender or recipient)
• Server pushes JSON on every new matching transfer; payload is identical to the REST /transfers response shape, including displayAmount
• Non-matching /subscribe/... paths receive an HTTP 404 and the socket is destroyed
• Connecting to an address with no incoming/outgoing traffic works fine — client simply waits until a matching event is indexed

Payload shape (example)

{
  "contractId": "CABC...",
  "eventType": "transfer",
  "fromAddress": "GBOB...",
  "toAddress": "GALICE...",
  "amount": "10000000",
  "displayAmount": "1.0000000",
  "ledger": 12345,
  "ledgerClosedAt": "2025-01-01T00:00:00.000Z",
  "txHash": "abc123",
  "eventId": "evt-001"
}

How it was tested

Build verification:

npm run build   # → zero TypeScript errors

Manual test steps:

1. Start the server: npm run dev
2. Open a WebSocket client (e.g. wscat):

   wscat -c ws://localhost:3000/subscribe/GALICE...

3. Trigger an indexed transfer to/from that address
4. Observe JSON payload pushed in real-time to the client
5. Disconnect the client and confirm no memory leak (listener count stays bounded)

Memory safety check:
Connect and disconnect many clients rapidly — the listener count on transferEmitter returns to 0 after all sockets close because transferEmitter.off(handler) is called in both the close and error handlers.

[drips-wave]

@0xDeon Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits