@jambonz/mrf 0.1.0

package/lib/mrf.js

@@ -0,0 +1,55 @@
+const { EventEmitter } = require('events');
+const Connection = require('./connection');
+const MediaServer = require('./mediaserver');
+
+const noopLogger = {
+  info: () => {},
+  error: () => {},
+  debug: () => {}
+};
+
+/**
+ * Mrf is the entry point, mirroring drachtio-fsmrf's Mrf class. The srf
+ * argument is accepted for drop-in compatibility but unused — mediajam needs
+ * no SIP signaling to allocate endpoints.
+ */
+class Mrf extends EventEmitter {
+  constructor(srf, opts = {}) {
+    super();
+    // allow new Mrf({logger}) without an srf
+    if (srf && !opts.logger && (srf.info || srf.logger)) {
+      if (srf.info) {
+        opts = { logger: srf };
+        srf = null;
+      } else if (srf.logger) {
+        opts = srf;
+        srf = null;
+      }
+    }
+    this.srf = srf;
+    this.logger = opts.logger || noopLogger;
+    this.mediaservers = [];
+  }
+
+  /**
+   * Connect to a mediajam server.
+   * @param {object} opts - {address, port} ('secret'/'listenPort' accepted
+   *   and ignored for fsmrf compatibility)
+   */
+  async connect(opts) {
+    const { address, port = 9090 } = opts;
+    const connection = new Connection(this.logger);
+    const ms = new MediaServer(connection, this.logger, { address, port });
+    const helloData = await connection.connect({ address, port }, clientInfo());
+    ms._onHello(helloData);
+    this.mediaservers.push(ms);
+    return ms;
+  }
+}
+
+function clientInfo() {
+  const { name, version } = require('../package.json');
+  return `${name}/${version}`;
+}
+
+module.exports = Mrf;

package/lib/utils.js

@@ -0,0 +1,40 @@
+/**
+ * Extract {sdp, mediaIp, mediaPort} the way fsmrf exposes endpoint.local /
+ * endpoint.remote.
+ */
+function parseSdp(sdp) {
+  const out = { sdp, mediaIp: null, mediaPort: null };
+  if (!sdp) return out;
+  for (const line of sdp.split(/\r?\n/)) {
+    if (line.startsWith('c=IN IP4 ')) out.mediaIp = line.slice(9).trim();
+    else if (line.startsWith('m=audio ')) {
+      const port = parseInt(line.split(' ')[1], 10);
+      if (!Number.isNaN(port)) out.mediaPort = port;
+    }
+  }
+  return out;
+}
+
+/**
+ * Translate FreeSWITCH play url schemes to mediajam schemes.
+ *   silence_stream://<ms>            -> silence://?duration=<ms>
+ *   tone_stream://...                -> tone:// (best-effort)
+ *   file/http(s) and bare paths pass through
+ */
+function translatePlayUrl(url) {
+  const silence = /^silence_stream:\/\/(-?\d+)/.exec(url);
+  if (silence) {
+    const ms = parseInt(silence[1], 10);
+    return ms < 0 ? 'silence://' : `silence://?duration=${ms}`;
+  }
+  if (url.startsWith('tone_stream://')) {
+    // FS tone_stream syntax is rich; map the common single-frequency form
+    // %(<on-ms>,<off-ms>,<freq>) and fall back to a 440Hz tone
+    const m = /%\(\s*(\d+)\s*,\s*\d+\s*,\s*(\d+)/.exec(url);
+    if (m) return `tone://?freq=${m[2]}&duration=${m[1]}`;
+    return 'tone://';
+  }
+  return url;
+}
+
+module.exports = { parseSdp, translatePlayUrl };

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@jambonz/mrf",
+  "version": "0.1.0",
+  "main": "index.js",
+  "scripts": {
+    "test": "node --test",
+    "jslint": "eslint .",
+    "jslint:fix": "eslint . --fix"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jambonz/mrf.git"
+  },
+  "author": "Dave Horton",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/jambonz/mrf/issues"
+  },
+  "homepage": "https://github.com/jambonz/mrf#readme",
+  "devDependencies": {
+    "eslint": "^9.0.0"
+  }
+}

package/test/client.test.js

@@ -0,0 +1,226 @@
+const { test } = require('node:test');
+const assert = require('node:assert');
+const Mrf = require('..');
+const MockMediajam = require('./support/mock-server');
+
+async function setup(t) {
+  const mock = new MockMediajam();
+  const port = await mock.listen();
+  const mrf = new Mrf();
+  const ms = await mrf.connect({ address: '127.0.0.1', port });
+  t.after(() => {
+    ms.destroy();
+    mock.close();
+  });
+  return { mock, ms };
+}
+
+test('connects and exposes server hello', async(t) => {
+  const { ms } = await setup(t);
+  assert.equal(ms.connected, true);
+  assert.equal(ms.maxSessions, 100);
+});
+
+test('createEndpoint returns fsmrf-shaped endpoint', async(t) => {
+  const { ms, mock } = await setup(t);
+  const ep = await ms.createEndpoint({ remoteSdp: 'v=0\r\nc=IN IP4 1.2.3.4\r\nm=audio 5004 RTP/AVP 0\r\n' });
+  assert.ok(ep.uuid);
+  assert.equal(ep.connected, true);
+  assert.equal(ep.local.mediaIp, '127.0.0.1');
+  assert.equal(ep.local.mediaPort, 41000);
+  assert.equal(ep.remote.mediaIp, '1.2.3.4');
+  assert.equal(ep.remote.mediaPort, 5004);
+  const createReq = mock.requests.find((r) => r.cmd === 'endpoint.create');
+  assert.ok(createReq.data.remoteSdp);
+});
+
+test('media_timeout option maps to mediaTimeoutMs', async(t) => {
+  const { ms, mock } = await setup(t);
+  await ms.createEndpoint({ media_timeout: '30000' });
+  const createReq = mock.requests.find((r) => r.cmd === 'endpoint.create');
+  assert.equal(createReq.data.options.mediaTimeoutMs, 30000);
+});
+
+test('play resolves on play.done with fsmrf-style result', async(t) => {
+  const { ms } = await setup(t);
+  const ep = await ms.createEndpoint({});
+  const events = [];
+  ep.on('playback-start', () => events.push('start'));
+  ep.on('playback-stop', () => events.push('stop'));
+  const result = await ep.play('silence_stream://1000');
+  assert.equal(result.reason, 'completed');
+  assert.equal(result.playbackSeconds, 0);
+  assert.equal(result.playbackMilliseconds, 100);
+  assert.equal(result.playbackLastOffsetPos, 800);
+  assert.deepEqual(events, ['start', 'stop']);
+});
+
+test('play PlaybackOptions form passes seekOffset', async(t) => {
+  const { ms, mock } = await setup(t);
+  const ep = await ms.createEndpoint({});
+  await ep.play({ file: '/tmp/foo.wav', seekOffset: 8000 });
+  const playReq = mock.requests.find((r) => r.cmd === 'play.start');
+  assert.deepEqual(playReq.data.urls, ['/tmp/foo.wav']);
+  assert.equal(playReq.data.seekOffset, 8000);
+});
+
+test('play url translation', async(t) => {
+  const { ms, mock } = await setup(t);
+  const ep = await ms.createEndpoint({});
+  await ep.play(['silence_stream://500', 'tone_stream://L=1;%(250, 0, 440)', 'https://x.test/a.wav']);
+  const playReq = mock.requests.find((r) => r.cmd === 'play.start');
+  assert.deepEqual(playReq.data.urls, [
+    'silence://?duration=500',
+    'tone://?freq=440&duration=250',
+    'https://x.test/a.wav'
+  ]);
+});
+
+test('api uuid_break maps to play.stop', async(t) => {
+  const { ms, mock } = await setup(t);
+  const ep = await ms.createEndpoint({});
+  await ep.api('uuid_break', ep.uuid);
+  assert.ok(mock.requests.find((r) => r.cmd === 'play.stop' && r.ep === ep.uuid));
+});
+
+test('execute send_dtmf maps digits and duration', async(t) => {
+  const { ms, mock } = await setup(t);
+  const ep = await ms.createEndpoint({});
+  await ep.execute('send_dtmf', '1234#@150');
+  const req = mock.requests.find((r) => r.cmd === 'dtmf.send');
+  assert.equal(req.data.digits, '1234#');
+  assert.equal(req.data.durationMs, 150);
+});
+
+test('bridge and unbridge', async(t) => {
+  const { ms, mock } = await setup(t);
+  const a = await ms.createEndpoint({});
+  const b = await ms.createEndpoint({});
+  await a.bridge(b);
+  const req = mock.requests.find((r) => r.cmd === 'bridge.create');
+  assert.equal(req.ep, a.uuid);
+  assert.equal(req.data.otherEndpointId, b.uuid);
+  await a.unbridge();
+  assert.ok(mock.requests.find((r) => r.cmd === 'bridge.destroy'));
+});
+
+test('self-initiated destroy does NOT emit destroy (fsmrf parity)', async(t) => {
+  const { ms } = await setup(t);
+  const ep = await ms.createEndpoint({});
+  let emitted = false;
+  ep.once('destroy', () => emitted = true);
+  await ep.destroy();
+  await new Promise((r) => setTimeout(r, 50));
+  assert.equal(emitted, false, 'destroy event must not fire for app-initiated destroy');
+  assert.equal(ep.connected, false);
+  assert.equal(ms.endpointCount, 0);
+});
+
+test('server-initiated destruction emits destroy', async(t) => {
+  const { ms, mock } = await setup(t);
+  const ep = await ms.createEndpoint({});
+  const destroyed = new Promise((resolve) => ep.once('destroy', resolve));
+  mock.pushEvent(ep.uuid, 'endpoint.destroyed', { reason: 'mediaTimeout' });
+  const evt = await destroyed;
+  assert.equal(evt.reason, 'mediaTimeout');
+  assert.equal(ep.connected, false);
+});
+
+test('dtmf events surface in fsmrf shape', async(t) => {
+  const { ms, mock } = await setup(t);
+  const ep = await ms.createEndpoint({});
+  const dtmf = new Promise((resolve) => ep.once('dtmf', resolve));
+  mock.pushEvent(ep.uuid, 'dtmf', { digit: '5', durationMs: 120, source: 'rfc2833' });
+  const evt = await dtmf;
+  assert.deepEqual(evt, { dtmf: '5', duration: 120, source: 'rfc2833' });
+});
+
+test('custom event listeners receive normalized events with fsmrf contract', async(t) => {
+  const { ms, mock } = await setup(t);
+  const ep = await ms.createEndpoint({});
+  const got = new Promise((resolve) => ep.addCustomEventListener('stt.transcription',
+    (payload, evtObj) => resolve({payload, evtObj})));
+  mock.pushEvent(ep.uuid, 'stt.transcription',
+    { vendor: 'deepgram', bugname: 'default', json: '{"text":"hi"}' });
+  const {payload, evtObj} = await got;
+  assert.equal(payload.text, 'hi', 'json payload is parsed');
+  assert.equal(evtObj.getHeader('media-bugname'), 'default');
+});
+
+test('fork.play_audio delivers parsed file payload', async(t) => {
+  const { ms, mock } = await setup(t);
+  const ep = await ms.createEndpoint({});
+  const got = new Promise((resolve) => ep.addCustomEventListener('fork.play_audio',
+    (payload, evtObj) => resolve({payload, evtObj})));
+  mock.pushEvent(ep.uuid, 'fork.play_audio',
+    { bugname: 'b1', json: '{"file":"/tmp/x.tmp.r16","audioContentType":"raw"}' });
+  const {payload, evtObj} = await got;
+  assert.equal(payload.file, '/tmp/x.tmp.r16');
+  assert.equal(evtObj.getHeader('media-bugname'), 'b1');
+});
+
+test('stats update mediaserver gauges', async(t) => {
+  const { ms, mock } = await setup(t);
+  const updated = new Promise((resolve) => {
+    const iv = setInterval(() => {
+      if (ms.currentSessions === 42) {
+        clearInterval(iv);
+        resolve();
+      }
+    }, 5);
+  });
+  mock.pushStats({ sessions: 42, maxSessions: 100, cpuIdle: 88 });
+  await updated;
+  assert.equal(ms.cpuIdle, 88);
+});
+
+test('connection loss destroys endpoints with connectionLost', async() => {
+  const mock = new MockMediajam();
+  const port = await mock.listen();
+  const mrf = new Mrf();
+  const ms = await mrf.connect({ address: '127.0.0.1', port });
+  const ep = await ms.createEndpoint({});
+  const destroyed = new Promise((resolve) => ep.once('destroy', resolve));
+  const ended = new Promise((resolve) => ms.conn.once('esl::end', resolve));
+  mock.close();
+  for (const socket of mock.sockets) socket.destroy();
+  const evt = await destroyed;
+  await ended;
+  assert.equal(evt.reason, 'connectionLost');
+});
+
+test('setLogLevel changes and queries server log level', async(t) => {
+  const { ms } = await setup(t);
+  assert.equal(await ms.setLogLevel('debug'), 'debug');
+  assert.equal(await ms.setLogLevel(), 'debug');
+});
+
+test('startTranscription forwards channel vars as options', async(t) => {
+  const { ms, mock } = await setup(t);
+  const ep = await ms.createEndpoint({});
+  await ep.set({DEEPGRAM_API_KEY: 'k123', DEEPGRAM_SPEECH_MODEL: 'nova-2', UNRELATED: ''});
+  await ep.startTranscription({vendor: 'deepgram', locale: 'en-US', interim: true});
+  const req = mock.requests.find((r) => r.cmd === 'stt.start');
+  assert.equal(req.data.vendor, 'deepgram');
+  assert.equal(req.data.language, 'en-US');
+  assert.equal(req.data.interim, true);
+  assert.equal(req.data.bugname, 'deepgram_transcribe');
+  assert.equal(req.data.options.DEEPGRAM_API_KEY, 'k123');
+  assert.equal(req.data.options.DEEPGRAM_SPEECH_MODEL, 'nova-2');
+  assert.ok(!('UNRELATED' in req.data.options), 'empty vars are cleared');
+});
+
+test('stt events deliver fsmrf header aliases', async(t) => {
+  const { ms, mock } = await setup(t);
+  const ep = await ms.createEndpoint({});
+  const got = new Promise((resolve) => ep.addCustomEventListener('stt.transcription',
+    (payload, evtObj) => resolve({payload, evtObj})));
+  mock.pushEvent(ep.uuid, 'stt.transcription', {
+    vendor: 'deepgram', bugname: 'deepgram_transcribe', finished: 'true',
+    json: '{"is_final":true}'
+  });
+  const {payload, evtObj} = await got;
+  assert.equal(payload.is_final, true);
+  assert.equal(evtObj.getHeader('transcription-vendor'), 'deepgram');
+  assert.equal(evtObj.getHeader('transcription-session-finished'), 'true');
+});

package/test/integration.test.js

@@ -0,0 +1,201 @@
+// Integration tests against a real mediajam server binary.
+//
+//   go build -o /tmp/mediajam ./cmd/mediajam   (in the mediajam repo)
+//   MEDIAJAM_BIN=/tmp/mediajam npm test
+//
+// Skipped when MEDIAJAM_BIN is unset (e.g. in CI without the binary).
+
+const { test } = require('node:test');
+const assert = require('node:assert');
+const { spawn } = require('node:child_process');
+const dgram = require('node:dgram');
+const net = require('node:net');
+const Mrf = require('..');
+const { buildRtp, parseRtp } = require('./support/rtp');
+
+const BIN = process.env.MEDIAJAM_BIN;
+const skip = BIN ? false : 'set MEDIAJAM_BIN to run integration tests';
+
+const CONTROL_PORT = 19090 + (process.pid % 1000);
+
+let serverProc;
+let mrf;
+let ms;
+
+async function startServer() {
+  serverProc = spawn(BIN, [
+    '-addr', `127.0.0.1:${CONTROL_PORT}`,
+    '-rtp-ip', '127.0.0.1',
+    '-advertise-ip', '127.0.0.1',
+    '-rtp-port-min', '46000',
+    '-rtp-port-max', '46998',
+    '-log-level', 'warn'
+  ], { stdio: ['ignore', 'inherit', 'inherit'] });
+
+  // wait for the control port to accept
+  for (let i = 0; i < 50; i++) {
+    const ok = await new Promise((resolve) => {
+      const s = net.connect({ host: '127.0.0.1', port: CONTROL_PORT }, () => {
+        s.destroy();
+        resolve(true);
+      });
+      s.on('error', () => resolve(false));
+    });
+    if (ok) return;
+    await new Promise((r) => setTimeout(r, 100));
+  }
+  throw new Error('mediajam did not start');
+}
+
+function makeCaller() {
+  return new Promise((resolve) => {
+    const sock = dgram.createSocket('udp4');
+    sock.bind(0, '127.0.0.1', () => resolve(sock));
+  });
+}
+
+function sdpFor(sock) {
+  const { port } = sock.address();
+  return 'v=0\r\no=- 1 1 IN IP4 127.0.0.1\r\ns=t\r\nc=IN IP4 127.0.0.1\r\nt=0 0\r\n' +
+    `m=audio ${port} RTP/AVP 0 101\r\na=rtpmap:0 PCMU/8000\r\n` +
+    'a=rtpmap:101 telephone-event/8000\r\na=fmtp:101 0-16\r\n';
+}
+
+/** stream caller RTP at 20ms cadence until stopped; returns stop fn */
+function pumpRtp(sock, destPort, fillByte) {
+  const payload = Buffer.alloc(160, fillByte);
+  let seq = 1, ts = 0;
+  const iv = setInterval(() => {
+    sock.send(buildRtp({ pt: 0, seq: seq++, ts: ts += 160, ssrc: 0x1234, payload }), destPort, '127.0.0.1');
+  }, 20);
+  return () => clearInterval(iv);
+}
+
+/** collect RTP packets arriving at a caller socket until pred matches */
+function waitForPacket(sock, pred, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      sock.removeListener('message', onMsg);
+      reject(new Error('timed out waiting for RTP'));
+    }, timeoutMs);
+    const onMsg = (msg) => {
+      const pkt = parseRtp(msg);
+      if (pkt && pred(pkt)) {
+        clearTimeout(timer);
+        sock.removeListener('message', onMsg);
+        resolve(pkt);
+      }
+    };
+    sock.on('message', onMsg);
+  });
+}
+
+test('integration: connect', { skip }, async() => {
+  await startServer();
+  mrf = new Mrf();
+  ms = await mrf.connect({ address: '127.0.0.1', port: CONTROL_PORT });
+  assert.equal(ms.connected, true);
+  assert.ok(ms.serverVersion.startsWith('mediajam/'));
+});
+
+test('integration: createEndpoint answer mode', { skip }, async(t) => {
+  const caller = await makeCaller();
+  t.after(() => caller.close());
+  const ep = await ms.createEndpoint({ remoteSdp: sdpFor(caller) });
+  assert.equal(ep.local.mediaIp, '127.0.0.1');
+  assert.ok(ep.local.mediaPort >= 46000 && ep.local.mediaPort <= 46998);
+  // server ticks silence toward the caller immediately
+  await waitForPacket(caller, (p) => p.pt === 0 && p.payload.length === 160, 2000);
+  await ep.destroy();
+});
+
+test('integration: play tone resolves with duration and renders audio', { skip }, async(t) => {
+  const caller = await makeCaller();
+  t.after(() => caller.close());
+  const ep = await ms.createEndpoint({ remoteSdp: sdpFor(caller) });
+  t.after(() => ep.destroy());
+
+  const nonSilence = waitForPacket(caller,
+    (p) => p.pt === 0 && p.payload.some((b) => b !== 0xff && b !== 0x7f), 2000);
+  const result = await ep.play('tone://?freq=800&duration=200');
+  assert.equal(result.reason, 'completed');
+  assert.ok(result.playbackMilliseconds >= 160 && result.playbackMilliseconds <= 260,
+    `playbackMilliseconds = ${result.playbackMilliseconds}`);
+  await nonSilence;
+});
+
+test('integration: uuid_break stops playback', { skip }, async(t) => {
+  const caller = await makeCaller();
+  t.after(() => caller.close());
+  const ep = await ms.createEndpoint({ remoteSdp: sdpFor(caller) });
+  t.after(() => ep.destroy());
+
+  const playDone = ep.play('silence://?duration=10000');
+  await new Promise((r) => setTimeout(r, 100));
+  await ep.api('uuid_break', ep.uuid);
+  const result = await playDone;
+  assert.equal(result.reason, 'stopped');
+});
+
+test('integration: bridge carries audio between endpoints', { skip }, async(t) => {
+  const callerA = await makeCaller();
+  const callerB = await makeCaller();
+  t.after(() => {
+    callerA.close();
+    callerB.close();
+  });
+  const epA = await ms.createEndpoint({ remoteSdp: sdpFor(callerA) });
+  const epB = await ms.createEndpoint({ remoteSdp: sdpFor(callerB) });
+  t.after(async() => {
+    await epA.destroy();
+    await epB.destroy();
+  });
+
+  await epA.bridge(epB);
+  const stopPump = pumpRtp(callerA, epA.local.mediaPort, 0x12);
+  t.after(stopPump);
+
+  // caller B hears caller A's pattern
+  await waitForPacket(callerB,
+    (p) => p.pt === 0 && p.payload[0] === 0x12 && p.payload[80] === 0x12, 3000);
+
+  // unbridge reverts B to silence
+  await epA.unbridge();
+});
+
+test('integration: outbound DTMF arrives as RFC2833', { skip }, async(t) => {
+  const caller = await makeCaller();
+  t.after(() => caller.close());
+  const ep = await ms.createEndpoint({ remoteSdp: sdpFor(caller) });
+  t.after(() => ep.destroy());
+
+  const dtmfPkt = waitForPacket(caller, (p) => p.pt === 101, 3000);
+  await ep.execute('send_dtmf', '7@120');
+  const pkt = await dtmfPkt;
+  assert.equal(pkt.payload[0], 7); // event code for digit 7
+});
+
+test('integration: inbound RFC2833 emits dtmf event', { skip }, async(t) => {
+  const caller = await makeCaller();
+  t.after(() => caller.close());
+  const ep = await ms.createEndpoint({ remoteSdp: sdpFor(caller) });
+  t.after(() => ep.destroy());
+
+  const dtmf = new Promise((resolve) => ep.once('dtmf', resolve));
+  // event 5, end bit set, duration 960 samples (120ms @8k)
+  const payload = Buffer.from([5, 0x8a, 0x03, 0xc0]);
+  for (let i = 0; i < 3; i++) {
+    caller.send(buildRtp({ pt: 101, seq: 100 + i, ts: 5000, ssrc: 0x99, payload }),
+      ep.local.mediaPort, '127.0.0.1');
+  }
+  const evt = await dtmf;
+  assert.equal(evt.dtmf, '5');
+  assert.equal(evt.duration, 120);
+  assert.equal(evt.source, 'rfc2833');
+});
+
+test('integration: teardown', { skip }, async() => {
+  ms.destroy();
+  serverProc.kill('SIGTERM');
+  await new Promise((r) => serverProc.once('exit', r));
+});

package/test/support/mock-server.js

@@ -0,0 +1,137 @@
+const net = require('net');
+const { randomUUID } = require('crypto');
+
+/**
+ * A minimal in-process mediajam control-protocol server for testing the
+ * client without the real Go binary. Implements hello, endpoint lifecycle,
+ * play (with timed play.done), dtmf.send, bridge, mute.
+ */
+class MockMediajam {
+  constructor() {
+    this.server = null;
+    this.port = 0;
+    this.endpoints = new Map(); // id -> {socket, playTimers}
+    this.requests = []; // every req frame received, for assertions
+  }
+
+  listen() {
+    return new Promise((resolve) => {
+      this.server = net.createServer((socket) => this._onConnection(socket));
+      this.server.listen(0, '127.0.0.1', () => {
+        this.port = this.server.address().port;
+        resolve(this.port);
+      });
+    });
+  }
+
+  close() {
+    for (const [, ep] of this.endpoints) {
+      for (const t of ep.playTimers) clearTimeout(t);
+    }
+    this.server.close();
+  }
+
+  send(socket, obj) {
+    socket.write(`${JSON.stringify(obj)}\n`);
+  }
+
+  // push an arbitrary event to the connection owning an endpoint
+  pushEvent(epId, evt, data) {
+    const ep = this.endpoints.get(epId);
+    if (ep) this.send(ep.socket, { t: 'evt', ep: epId, evt, data });
+  }
+
+  pushStats(data) {
+    for (const socket of this.sockets || []) {
+      this.send(socket, { t: 'stats', data });
+    }
+  }
+
+  _onConnection(socket) {
+    (this.sockets = this.sockets || new Set()).add(socket);
+    socket.on('close', () => this.sockets.delete(socket));
+    let buf = '';
+    socket.on('data', (chunk) => {
+      buf += chunk.toString();
+      let idx;
+      while ((idx = buf.indexOf('\n')) >= 0) {
+        const line = buf.slice(0, idx);
+        buf = buf.slice(idx + 1);
+        if (line.trim()) this._onFrame(socket, JSON.parse(line));
+      }
+    });
+  }
+
+  _onFrame(socket, frame) {
+    if (frame.t === 'hello') {
+      this.send(socket, { t: 'hello', data: { version: 1, server: 'mock/0.0.0', maxSessions: 100 } });
+      return;
+    }
+    if (frame.t !== 'req') return;
+    this.requests.push(frame);
+    const res = (data) => this.send(socket, { t: 'res', id: frame.id, ok: true, data });
+    const fail = (code, msg) => this.send(socket, { t: 'res', id: frame.id, ok: false, err: { code, msg } });
+
+    switch (frame.cmd) {
+      case 'endpoint.create': {
+        const id = randomUUID();
+        this.endpoints.set(id, { socket, playTimers: new Set() });
+        res({
+          endpointId: id,
+          localSdp: 'v=0\r\no=mock 1 1 IN IP4 127.0.0.1\r\ns=m\r\nc=IN IP4 127.0.0.1\r\nt=0 0\r\n' +
+            'm=audio 41000 RTP/AVP 0 101\r\na=rtpmap:0 PCMU/8000\r\n'
+        });
+        break;
+      }
+      case 'endpoint.destroy': {
+        const ep = this.endpoints.get(frame.ep);
+        if (!ep) return fail('unknown_endpoint', frame.ep);
+        this.endpoints.delete(frame.ep);
+        res({});
+        this.send(socket, { t: 'evt', ep: frame.ep, evt: 'endpoint.destroyed', data: { reason: 'commanded' } });
+        break;
+      }
+      case 'endpoint.modify':
+        res({ localSdp: 'v=0\r\nc=IN IP4 127.0.0.1\r\nm=audio 41002 RTP/AVP 0\r\n' });
+        break;
+      case 'play.start': {
+        const ep = this.endpoints.get(frame.ep);
+        if (!ep) return fail('unknown_endpoint', frame.ep);
+        const playId = randomUUID().slice(0, 8);
+        res({ playId });
+        this.send(socket, { t: 'evt', ep: frame.ep, evt: 'play.start', data: { playId } });
+        const t = setTimeout(() => {
+          ep.playTimers.delete(t);
+          this.send(socket, {
+            t: 'evt', ep: frame.ep, evt: 'play.done',
+            data: { playId, reason: 'completed', durationMs: 100, playbackMs: 100, lastOffsetPos: 800 }
+          });
+        }, 30);
+        ep.playTimers.add(t);
+        break;
+      }
+      case 'play.stop':
+      case 'dtmf.send':
+      case 'stt.start':
+      case 'stt.stop':
+      case 'endpoint.set':
+      case 'endpoint.mute':
+      case 'endpoint.unmute':
+      case 'bridge.create':
+      case 'bridge.destroy':
+        res({});
+        break;
+      case 'endpoint.info':
+        res({ codec: 'PCMU', stats: { packetsIn: 0 } });
+        break;
+      case 'system.logLevel':
+        this.logLevel = (frame.data && frame.data.level) || this.logLevel || 'info';
+        res({ level: this.logLevel });
+        break;
+      default:
+        fail('unknown_command', frame.cmd);
+    }
+  }
+}
+
+module.exports = MockMediajam;