rol-websocket-channel 1.4.9 → 1.5.2

package/dist/index.js

@@ -12,6 +12,21 @@ let pluginRuntime = null;
 export function getPluginRuntime() {
     return pluginRuntime;
 }
+export function formatCliErrorPayload(error) {
+    const data = error?.data;
+    const dataObject = data && typeof data === "object" && !Array.isArray(data)
+        ? data
+        : {};
+    const code = dataObject.code ?? error?.code;
+    return {
+        ok: false,
+        error: {
+            message: error instanceof Error ? error.message : String(error),
+            ...dataObject,
+            ...(code === undefined ? {} : { code }),
+        },
+    };
+}
 // ============================================
 // 4. 插件主体定义
 // ============================================
@@ -554,13 +569,7 @@ function registerAdminBridgeCli(api) {
             }
             catch (error) {
                 process.exitCode = 1;
-                process.stderr.write(JSON.stringify({
-                    ok: false,
-                    error: {
-                        message: error instanceof Error ? error.message : String(error),
-                        code: error?.data?.code,
-                    },
-                }, null, 2) + "\n");
+                process.stderr.write(JSON.stringify(formatCliErrorPayload(error), null, 2) + "\n");
             }
         });
         const mem9 = root

package/dist/src/admin/cli-manifest.test.js

@@ -1,7 +1,7 @@
 import assert from 'node:assert/strict';
 import { readFileSync } from 'node:fs';
 import test from 'node:test';
-import register from '../../index.js';
+import register, { formatCliErrorPayload } from '../../index.js';
 const manifest = JSON.parse(readFileSync(new URL('../../openclaw.plugin.json', import.meta.url), 'utf8'));
 test('manifest declares OpenClaw 2026 command ownership for admin bridge CLI', () => {
     assert.deepEqual(manifest.activation?.onCommands, ['admin-bridge', 'rol-websocket-channel']);
@@ -60,3 +60,26 @@ test('runtime CLI registrar exposes admin-bridge and rol-websocket-channel comma
     assert.equal(commands[0], 'admin-bridge');
     assert.equal(aliases[0], 'rol-websocket-channel');
 });
+test('CLI error formatter preserves diagnostic data for pairing failures', () => {
+    const error = new Error('mqttUrl is missing from pairing payload');
+    error.data = {
+        code: 'PAIR_CHANNEL_CONFIG_INVALID',
+        debug: {
+            rootKeys: ['channel'],
+            channelConfigKeys: ['mqtt_topic'],
+            hasExistingMqttUrl: false
+        }
+    };
+    assert.deepEqual(formatCliErrorPayload(error), {
+        ok: false,
+        error: {
+            message: 'mqttUrl is missing from pairing payload',
+            code: 'PAIR_CHANNEL_CONFIG_INVALID',
+            debug: {
+                rootKeys: ['channel'],
+                channelConfigKeys: ['mqtt_topic'],
+                hasExistingMqttUrl: false
+            }
+        }
+    });
+});

package/dist/src/admin/methods/pairing.js

@@ -69,28 +69,55 @@ async function exchangePairKey(key, endpoint, authOverride, existingMqttUrl) {
 }
 function normalizePairingPayload(raw, endpoint, existingMqttUrl) {
     const root = unwrapPayload(raw);
-    const pluginId = pickString(root.pluginId) ?? DEFAULT_PLUGIN_ID;
-    const apiCoreBotValue = isRecord(root.apiCoreBot) ? root.apiCoreBot : {};
-    const channelValue = isRecord(root.channel) ? root.channel : {};
+    const pluginId = pickString(root.pluginId) ?? pickString(root.plugin_id) ?? DEFAULT_PLUGIN_ID;
+    const apiCoreBotValue = pickRecord(root.apiCoreBot, root.api_core_bot);
+    const channelValue = pickRecord(root.channel);
+    const channelConfigValue = pickRecord(channelValue.config);
     const apiCoreBotAuthToken = pickString(apiCoreBotValue.authToken)
+        ?? pickString(apiCoreBotValue.auth_token)
         ?? pickString(root.authToken)
+        ?? pickString(root.auth_token)
         ?? pickString(root.token);
-    const rawValue = pickString(root.value);
+    const rawValue = pickString(root.value)
+        ?? pickString(root.rawValue)
+        ?? pickString(root.raw_value);
     const mqttUrl = pickString(channelValue.mqttUrl)
+        ?? pickString(channelValue.mqtt_url)
+        ?? pickString(channelConfigValue.mqttUrl)
+        ?? pickString(channelConfigValue.mqtt_url)
         ?? pickString(root.mqttUrl)
+        ?? pickString(root.mqtt_url)
         ?? existingMqttUrl
         ?? null;
     if (!mqttUrl) {
-        throwPairingError('PAIR_CHANNEL_CONFIG_INVALID', 'mqttUrl is missing from pairing payload');
+        throwPairingError('PAIR_CHANNEL_CONFIG_INVALID', 'mqttUrl is missing from pairing payload', {
+            endpoint,
+            rootKeys: Object.keys(root),
+            channelKeys: Object.keys(channelValue),
+            channelConfigKeys: Object.keys(channelConfigValue),
+            hasExistingMqttUrl: Boolean(existingMqttUrl)
+        });
     }
     const mqttTopic = pickString(channelValue.mqttTopic)
+        ?? pickString(channelValue.mqtt_topic)
+        ?? pickString(channelConfigValue.mqttTopic)
+        ?? pickString(channelConfigValue.mqtt_topic)
         ?? pickString(root.mqttTopic)
+        ?? pickString(root.mqtt_topic)
         ?? rawValue
         ?? 'announcement/tester';
     const groupPolicy = normalizeGroupPolicy(pickString(channelValue.groupPolicy)
+        ?? pickString(channelValue.group_policy)
         ?? pickString(channelValue.dmPolicy)
+        ?? pickString(channelValue.dm_policy)
+        ?? pickString(channelConfigValue.groupPolicy)
+        ?? pickString(channelConfigValue.group_policy)
+        ?? pickString(channelConfigValue.dmPolicy)
+        ?? pickString(channelConfigValue.dm_policy)
         ?? pickString(root.groupPolicy)
+        ?? pickString(root.group_policy)
         ?? pickString(root.dmPolicy)
+        ?? pickString(root.dm_policy)
         ?? 'pairing');
     return {
         pluginId,
@@ -98,7 +125,7 @@ function normalizePairingPayload(raw, endpoint, existingMqttUrl) {
             ...(rawValue ? { rawValue } : {})
         },
         apiCoreBot: {
-            baseUrl: pickString(apiCoreBotValue.baseUrl) ?? inferBaseUrl(endpoint),
+            baseUrl: pickString(apiCoreBotValue.baseUrl) ?? pickString(apiCoreBotValue.base_url) ?? inferBaseUrl(endpoint),
             ...(apiCoreBotAuthToken ? { authToken: apiCoreBotAuthToken } : {})
         },
         channel: {
@@ -260,9 +287,20 @@ function pickString(value) {
     const trimmed = value.trim();
     return trimmed.length > 0 ? trimmed : null;
 }
+function pickRecord(...values) {
+    for (const value of values) {
+        if (isRecord(value)) {
+            return value;
+        }
+    }
+    return {};
+}
 function isRecord(value) {
     return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
 }
-function throwPairingError(code, message) {
-    throw new JsonRpcException(JSON_RPC_ERRORS.invalidParams, message, { code });
+function throwPairingError(code, message, debug) {
+    throw new JsonRpcException(JSON_RPC_ERRORS.invalidParams, message, {
+        code,
+        ...(debug ? { debug } : {})
+    });
 }

package/dist/src/admin/methods/pairing.test.js

@@ -0,0 +1,114 @@
+import { afterEach, describe, test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import http from 'node:http';
+import os from 'node:os';
+import path from 'node:path';
+import { pairWithKey } from './pairing.js';
+import { JsonRpcException } from '../jsonrpc.js';
+const tempDirs = [];
+const servers = [];
+afterEach(async () => {
+    while (servers.length > 0) {
+        const server = servers.pop();
+        if (server) {
+            await new Promise((resolve, reject) => {
+                server.close((error) => error ? reject(error) : resolve());
+            });
+        }
+    }
+    while (tempDirs.length > 0) {
+        const dir = tempDirs.pop();
+        if (dir) {
+            await fs.rm(dir, { recursive: true, force: true });
+        }
+    }
+});
+describe('pairWithKey payload compatibility', () => {
+    test('accepts snake_case channel config from the pairing endpoint', async () => {
+        const context = await createMethodContext();
+        const endpoint = await createPairingEndpoint({
+            data: {
+                plugin_id: 'rol-websocket-channel',
+                api_core_bot: {
+                    base_url: 'https://api.example.test',
+                    auth_token: 'secret-token'
+                },
+                value: 'announcement/user/agent/#',
+                channel: {
+                    config: {
+                        mqtt_url: 'ws://mqtt.example.test:8083/mqtt',
+                        mqtt_topic: 'announcement/user/agent/#',
+                        group_policy: 'pairing'
+                    }
+                }
+            }
+        });
+        const result = await pairWithKey({ key: 'abc123456', endpoint }, context);
+        const savedConfig = JSON.parse(await fs.readFile(path.join(context.openclawRoot, 'openclaw.json'), 'utf8'));
+        assert.equal(result.ok, true);
+        assert.equal(result.channel.mqttUrl, 'ws://mqtt.example.test:8083/mqtt');
+        assert.equal(result.channel.mqttTopic, 'announcement/user/agent/#');
+        assert.equal(result.channel.groupPolicy, 'pairing');
+        assert.deepEqual(savedConfig.plugins.allow, ['rol-websocket-channel']);
+        assert.equal(savedConfig.channels['rol-websocket-channel'].config.mqttUrl, 'ws://mqtt.example.test:8083/mqtt');
+        assert.equal(savedConfig.plugins.entries['rol-websocket-channel'].config.apiCoreBot.authToken, 'secret-token');
+    });
+    test('reports payload keys when mqttUrl is missing', async () => {
+        const context = await createMethodContext();
+        const endpoint = await createPairingEndpoint({
+            data: {
+                plugin_id: 'rol-websocket-channel',
+                channel: {
+                    config: {
+                        mqtt_topic: 'announcement/user/agent/#'
+                    }
+                }
+            }
+        });
+        await assert.rejects(() => pairWithKey({ key: 'abc123456', endpoint }, context), (error) => {
+            assert.ok(error instanceof JsonRpcException);
+            assert.equal(error.message, 'mqttUrl is missing from pairing payload');
+            assert.deepEqual(error.data, {
+                code: 'PAIR_CHANNEL_CONFIG_INVALID',
+                debug: {
+                    endpoint,
+                    rootKeys: ['plugin_id', 'channel'],
+                    channelKeys: ['config'],
+                    channelConfigKeys: ['mqtt_topic'],
+                    hasExistingMqttUrl: false
+                }
+            });
+            return true;
+        });
+    });
+});
+async function createMethodContext() {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'rol-pairing-'));
+    tempDirs.push(dir);
+    await fs.writeFile(path.join(dir, 'openclaw.json'), '{}\n', 'utf8');
+    return {
+        projectRoot: dir,
+        openclawRoot: dir
+    };
+}
+async function createPairingEndpoint(payload) {
+    const server = http.createServer(async (request, response) => {
+        if (request.method !== 'POST') {
+            response.writeHead(405).end();
+            return;
+        }
+        for await (const _chunk of request) {
+            // Drain request body so Node can close the connection cleanly.
+        }
+        response.writeHead(200, { 'Content-Type': 'application/json' });
+        response.end(JSON.stringify(payload));
+    });
+    await new Promise((resolve) => {
+        server.listen(0, '127.0.0.1', resolve);
+    });
+    servers.push(server);
+    const address = server.address();
+    assert.ok(address && typeof address === 'object');
+    return `http://127.0.0.1:${address.port}/pair`;
+}

package/index.ts

@@ -38,6 +38,28 @@ export function getPluginRuntime(): any {
   return pluginRuntime;
 }
 
+export function formatCliErrorPayload(error: unknown): {
+  ok: false;
+  error: Record<string, unknown>;
+} {
+  const data = (error as { data?: unknown } | null | undefined)?.data;
+  const dataObject =
+    data && typeof data === "object" && !Array.isArray(data)
+      ? (data as Record<string, unknown>)
+      : {};
+  const code =
+    dataObject.code ?? (error as { code?: unknown } | null | undefined)?.code;
+
+  return {
+    ok: false,
+    error: {
+      message: error instanceof Error ? error.message : String(error),
+      ...dataObject,
+      ...(code === undefined ? {} : { code }),
+    },
+  };
+}
+
 // ============================================
 // 4. 插件主体定义
 // ============================================
@@ -725,18 +747,7 @@ function registerAdminBridgeCli(api: any) {
             } catch (error) {
               process.exitCode = 1;
               process.stderr.write(
-                JSON.stringify(
-                  {
-                    ok: false,
-                    error: {
-                      message:
-                        error instanceof Error ? error.message : String(error),
-                      code: (error as any)?.data?.code,
-                    },
-                  },
-                  null,
-                  2,
-                ) + "\n",
+                JSON.stringify(formatCliErrorPayload(error), null, 2) + "\n",
               );
             }
           },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rol-websocket-channel",
-  "version": "1.4.9",
+  "version": "1.5.2",
   "description": "Unified OpenClaw plugin: MQTT Channel + Admin Bridge for remote management",
   "license": "MIT",
   "author": "nixgnehc",

package/src/admin/cli-manifest.test.ts

@@ -1,7 +1,7 @@
 import assert from 'node:assert/strict';
 import { readFileSync } from 'node:fs';
 import test from 'node:test';
-import register from '../../index.js';
+import register, { formatCliErrorPayload } from '../../index.js';
 
 const manifest = JSON.parse(readFileSync(new URL('../../openclaw.plugin.json', import.meta.url), 'utf8'));
 
@@ -65,3 +65,30 @@ test('runtime CLI registrar exposes admin-bridge and rol-websocket-channel comma
   assert.equal(commands[0], 'admin-bridge');
   assert.equal(aliases[0], 'rol-websocket-channel');
 });
+
+test('CLI error formatter preserves diagnostic data for pairing failures', () => {
+  const error = new Error('mqttUrl is missing from pairing payload') as Error & {
+    data: Record<string, unknown>;
+  };
+  error.data = {
+    code: 'PAIR_CHANNEL_CONFIG_INVALID',
+    debug: {
+      rootKeys: ['channel'],
+      channelConfigKeys: ['mqtt_topic'],
+      hasExistingMqttUrl: false
+    }
+  };
+
+  assert.deepEqual(formatCliErrorPayload(error), {
+    ok: false,
+    error: {
+      message: 'mqttUrl is missing from pairing payload',
+      code: 'PAIR_CHANNEL_CONFIG_INVALID',
+      debug: {
+        rootKeys: ['channel'],
+        channelConfigKeys: ['mqtt_topic'],
+        hasExistingMqttUrl: false
+      }
+    }
+  });
+});

package/src/admin/methods/pairing.test.ts

@@ -0,0 +1,149 @@
+import { afterEach, describe, test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import http from 'node:http';
+import os from 'node:os';
+import path from 'node:path';
+
+import { pairWithKey } from './pairing.js';
+import { JsonRpcException } from '../jsonrpc.js';
+import type { MethodContext } from '../types.js';
+
+const tempDirs: string[] = [];
+const servers: http.Server[] = [];
+
+afterEach(async () => {
+  while (servers.length > 0) {
+    const server = servers.pop();
+    if (server) {
+      await new Promise<void>((resolve, reject) => {
+        server.close((error) => error ? reject(error) : resolve());
+      });
+    }
+  }
+
+  while (tempDirs.length > 0) {
+    const dir = tempDirs.pop();
+    if (dir) {
+      await fs.rm(dir, { recursive: true, force: true });
+    }
+  }
+});
+
+describe('pairWithKey payload compatibility', () => {
+  test('accepts snake_case channel config from the pairing endpoint', async () => {
+    const context = await createMethodContext();
+    const endpoint = await createPairingEndpoint({
+      data: {
+        plugin_id: 'rol-websocket-channel',
+        api_core_bot: {
+          base_url: 'https://api.example.test',
+          auth_token: 'secret-token'
+        },
+        value: 'announcement/user/agent/#',
+        channel: {
+          config: {
+            mqtt_url: 'ws://mqtt.example.test:8083/mqtt',
+            mqtt_topic: 'announcement/user/agent/#',
+            group_policy: 'pairing'
+          }
+        }
+      }
+    });
+
+    const result = await pairWithKey({ key: 'abc123456', endpoint }, context) as {
+      ok: boolean;
+      channel: {
+        mqttUrl: string;
+        mqttTopic: string;
+        groupPolicy: string;
+      };
+    };
+    const savedConfig = JSON.parse(
+      await fs.readFile(path.join(context.openclawRoot, 'openclaw.json'), 'utf8')
+    );
+
+    assert.equal(result.ok, true);
+    assert.equal(result.channel.mqttUrl, 'ws://mqtt.example.test:8083/mqtt');
+    assert.equal(result.channel.mqttTopic, 'announcement/user/agent/#');
+    assert.equal(result.channel.groupPolicy, 'pairing');
+    assert.deepEqual(savedConfig.plugins.allow, ['rol-websocket-channel']);
+    assert.equal(
+      savedConfig.channels['rol-websocket-channel'].config.mqttUrl,
+      'ws://mqtt.example.test:8083/mqtt'
+    );
+    assert.equal(
+      savedConfig.plugins.entries['rol-websocket-channel'].config.apiCoreBot.authToken,
+      'secret-token'
+    );
+  });
+
+  test('reports payload keys when mqttUrl is missing', async () => {
+    const context = await createMethodContext();
+    const endpoint = await createPairingEndpoint({
+      data: {
+        plugin_id: 'rol-websocket-channel',
+        channel: {
+          config: {
+            mqtt_topic: 'announcement/user/agent/#'
+          }
+        }
+      }
+    });
+
+    await assert.rejects(
+      () => pairWithKey({ key: 'abc123456', endpoint }, context),
+      (error: unknown) => {
+        assert.ok(error instanceof JsonRpcException);
+        assert.equal(error.message, 'mqttUrl is missing from pairing payload');
+        assert.deepEqual(error.data, {
+          code: 'PAIR_CHANNEL_CONFIG_INVALID',
+          debug: {
+            endpoint,
+            rootKeys: ['plugin_id', 'channel'],
+            channelKeys: ['config'],
+            channelConfigKeys: ['mqtt_topic'],
+            hasExistingMqttUrl: false
+          }
+        });
+        return true;
+      }
+    );
+  });
+});
+
+async function createMethodContext(): Promise<MethodContext> {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'rol-pairing-'));
+  tempDirs.push(dir);
+  await fs.writeFile(path.join(dir, 'openclaw.json'), '{}\n', 'utf8');
+  return {
+    projectRoot: dir,
+    openclawRoot: dir
+  };
+}
+
+async function createPairingEndpoint(payload: unknown): Promise<string> {
+  const server = http.createServer(async (request, response) => {
+    if (request.method !== 'POST') {
+      response.writeHead(405).end();
+      return;
+    }
+
+    for await (const _chunk of request) {
+      // Drain request body so Node can close the connection cleanly.
+    }
+
+    response.writeHead(200, { 'Content-Type': 'application/json' });
+    response.end(JSON.stringify(payload));
+  });
+
+  await new Promise<void>((resolve) => {
+    server.listen(0, '127.0.0.1', resolve);
+  });
+  servers.push(server);
+
+  const address = server.address();
+  assert.ok(address && typeof address === 'object');
+
+  return `http://127.0.0.1:${address.port}/pair`;
+}

package/src/admin/methods/pairing.ts

@@ -46,6 +46,14 @@ interface PairingPayload {
   };
 }
 
+interface PairingPayloadDebug {
+  endpoint: string;
+  rootKeys: string[];
+  channelKeys: string[];
+  channelConfigKeys: string[];
+  hasExistingMqttUrl: boolean;
+}
+
 export async function pairWithKey(
   options: PairingCommandOptions,
   context: MethodContext
@@ -134,33 +142,60 @@ function normalizePairingPayload(
   existingMqttUrl?: string | null
 ): PairingPayload {
   const root = unwrapPayload(raw);
-  const pluginId = pickString(root.pluginId) ?? DEFAULT_PLUGIN_ID;
-  const apiCoreBotValue = isRecord(root.apiCoreBot) ? root.apiCoreBot : {};
-  const channelValue = isRecord(root.channel) ? root.channel : {};
+  const pluginId = pickString(root.pluginId) ?? pickString(root.plugin_id) ?? DEFAULT_PLUGIN_ID;
+  const apiCoreBotValue = pickRecord(root.apiCoreBot, root.api_core_bot);
+  const channelValue = pickRecord(root.channel);
+  const channelConfigValue = pickRecord(channelValue.config);
 
   const apiCoreBotAuthToken = pickString(apiCoreBotValue.authToken)
+    ?? pickString(apiCoreBotValue.auth_token)
     ?? pickString(root.authToken)
+    ?? pickString(root.auth_token)
     ?? pickString(root.token);
-  const rawValue = pickString(root.value);
+  const rawValue = pickString(root.value)
+    ?? pickString(root.rawValue)
+    ?? pickString(root.raw_value);
 
   const mqttUrl = pickString(channelValue.mqttUrl)
+    ?? pickString(channelValue.mqtt_url)
+    ?? pickString(channelConfigValue.mqttUrl)
+    ?? pickString(channelConfigValue.mqtt_url)
     ?? pickString(root.mqttUrl)
+    ?? pickString(root.mqtt_url)
     ?? existingMqttUrl
     ?? null;
   if (!mqttUrl) {
-    throwPairingError('PAIR_CHANNEL_CONFIG_INVALID', 'mqttUrl is missing from pairing payload');
+    throwPairingError('PAIR_CHANNEL_CONFIG_INVALID', 'mqttUrl is missing from pairing payload', {
+      endpoint,
+      rootKeys: Object.keys(root),
+      channelKeys: Object.keys(channelValue),
+      channelConfigKeys: Object.keys(channelConfigValue),
+      hasExistingMqttUrl: Boolean(existingMqttUrl)
+    });
   }
 
   const mqttTopic = pickString(channelValue.mqttTopic)
+    ?? pickString(channelValue.mqtt_topic)
+    ?? pickString(channelConfigValue.mqttTopic)
+    ?? pickString(channelConfigValue.mqtt_topic)
     ?? pickString(root.mqttTopic)
+    ?? pickString(root.mqtt_topic)
     ?? rawValue
     ?? 'announcement/tester';
 
   const groupPolicy = normalizeGroupPolicy(
     pickString(channelValue.groupPolicy)
+      ?? pickString(channelValue.group_policy)
       ?? pickString(channelValue.dmPolicy)
+      ?? pickString(channelValue.dm_policy)
+      ?? pickString(channelConfigValue.groupPolicy)
+      ?? pickString(channelConfigValue.group_policy)
+      ?? pickString(channelConfigValue.dmPolicy)
+      ?? pickString(channelConfigValue.dm_policy)
       ?? pickString(root.groupPolicy)
+      ?? pickString(root.group_policy)
       ?? pickString(root.dmPolicy)
+      ?? pickString(root.dm_policy)
       ?? 'pairing'
   );
 
@@ -170,7 +205,7 @@ function normalizePairingPayload(
       ...(rawValue ? { rawValue } : {})
     },
     apiCoreBot: {
-      baseUrl: pickString(apiCoreBotValue.baseUrl) ?? inferBaseUrl(endpoint),
+      baseUrl: pickString(apiCoreBotValue.baseUrl) ?? pickString(apiCoreBotValue.base_url) ?? inferBaseUrl(endpoint),
       ...(apiCoreBotAuthToken ? { authToken: apiCoreBotAuthToken } : {})
     },
     channel: {
@@ -352,10 +387,23 @@ function pickString(value: unknown): string | null {
   return trimmed.length > 0 ? trimmed : null;
 }
 
+function pickRecord(...values: unknown[]): Record<string, any> {
+  for (const value of values) {
+    if (isRecord(value)) {
+      return value;
+    }
+  }
+
+  return {};
+}
+
 function isRecord(value: unknown): value is Record<string, any> {
   return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
 }
 
-function throwPairingError(code: string, message: string): never {
-  throw new JsonRpcException(JSON_RPC_ERRORS.invalidParams, message, { code });
+function throwPairingError(code: string, message: string, debug?: PairingPayloadDebug): never {
+  throw new JsonRpcException(JSON_RPC_ERRORS.invalidParams, message, {
+    code,
+    ...(debug ? { debug } : {})
+  });
 }