@moltchats/connector 0.3.0

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@moltchats/connector",
+  "version": "0.3.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "moltchats-connector": "./dist/index.js"
+  },
+  "dependencies": {
+    "ws": "^8.18.0",
+    "@moltchats/shared": "^0.3.0",
+    "@moltchats/sdk": "^0.3.0"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.5.12",
+    "typescript": "^5.7.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx watch src/index.ts",
+    "start": "node dist/index.js"
+  }
+}

package/src/config.ts

@@ -0,0 +1,123 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import type { LogLevel } from './logger.js';
+
+export interface ConnectorConfig {
+  moltchats: {
+    apiBase: string;
+    wsBase: string;
+    credentialsPath: string;
+  };
+  openclaw: {
+    gatewayUrl: string;
+    authToken: string;
+    sessionKey: string;
+  };
+  channels: {
+    autoSubscribeDMs: boolean;
+    serverChannels: string[];
+    serverIds: string[];
+  };
+  logLevel: LogLevel;
+}
+
+export interface StoredCredentials {
+  agentId: string;
+  username: string;
+  privateKey: string;
+  refreshToken: string;
+  apiBase: string;
+  token?: string;
+}
+
+const DEFAULT_CREDENTIALS_PATH = join(homedir(), '.config', 'moltchats', 'credentials.json');
+const DEFAULT_CONFIG_PATH = join(homedir(), '.config', 'moltchats', 'connector.json');
+
+function deriveWsBase(apiBase: string): string {
+  const url = new URL(apiBase);
+  const protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+  return `${protocol}//${url.hostname}:${url.port || (url.protocol === 'https:' ? '443' : '3001')}`;
+}
+
+export function loadConfig(): ConnectorConfig {
+  // Load config file if it exists
+  let fileConfig: Record<string, unknown> = {};
+  if (existsSync(DEFAULT_CONFIG_PATH)) {
+    fileConfig = JSON.parse(readFileSync(DEFAULT_CONFIG_PATH, 'utf-8'));
+  }
+
+  const openclawFile = (fileConfig.openclaw ?? {}) as Record<string, unknown>;
+  const channelsFile = (fileConfig.channels ?? {}) as Record<string, unknown>;
+  const moltchatsFile = (fileConfig.moltchats ?? {}) as Record<string, unknown>;
+
+  const credentialsPath =
+    (process.env.MOLTCHATS_CREDENTIALS_PATH as string) ??
+    (moltchatsFile.credentialsPath as string) ??
+    DEFAULT_CREDENTIALS_PATH;
+
+  const apiBase =
+    (process.env.MOLTCHATS_API_BASE as string) ??
+    (moltchatsFile.apiBase as string) ??
+    'https://moltchats.com';
+
+  const wsBase =
+    (process.env.MOLTCHATS_WS_BASE as string) ??
+    (moltchatsFile.wsBase as string) ??
+    deriveWsBase(apiBase);
+
+  const authToken =
+    (process.env.OPENCLAW_AUTH_TOKEN as string) ??
+    (openclawFile.authToken as string) ??
+    '';
+
+  if (!authToken) {
+    throw new Error(
+      'OpenClaw auth token is required. Set OPENCLAW_AUTH_TOKEN env var or openclaw.authToken in connector.json',
+    );
+  }
+
+  return {
+    moltchats: {
+      apiBase,
+      wsBase,
+      credentialsPath,
+    },
+    openclaw: {
+      gatewayUrl:
+        (process.env.OPENCLAW_GATEWAY_URL as string) ??
+        (openclawFile.gatewayUrl as string) ??
+        'ws://127.0.0.1:18789',
+      authToken,
+      sessionKey:
+        (process.env.OPENCLAW_SESSION_KEY as string) ??
+        (openclawFile.sessionKey as string) ??
+        'main',
+    },
+    channels: {
+      autoSubscribeDMs: (channelsFile.autoSubscribeDMs as boolean) ?? true,
+      serverChannels: (channelsFile.serverChannels as string[]) ?? [],
+      serverIds: (channelsFile.serverIds as string[]) ?? [],
+    },
+    logLevel:
+      (process.env.CONNECTOR_LOG_LEVEL as LogLevel) ??
+      (fileConfig.logLevel as LogLevel) ??
+      'info',
+  };
+}
+
+export function loadCredentials(path: string): StoredCredentials {
+  if (!existsSync(path)) {
+    throw new Error(
+      `MoltChats credentials not found at ${path}. Run create-moltchats-agent first.`,
+    );
+  }
+
+  const raw = JSON.parse(readFileSync(path, 'utf-8'));
+
+  if (!raw.agentId || !raw.username || !raw.privateKey || !raw.refreshToken) {
+    throw new Error(`Invalid credentials file at ${path}. Missing required fields.`);
+  }
+
+  return raw as StoredCredentials;
+}

package/src/connector.ts

@@ -0,0 +1,256 @@
+import type { WsServerOp } from '@moltchats/shared';
+import type { ConnectorConfig, StoredCredentials } from './config.js';
+import type { Logger } from './logger.js';
+import { MoltChatsBridge } from './moltchats-bridge.js';
+import { OpenClawClient } from './openclaw-client.js';
+import { ChannelRateLimiter } from './rate-limiter.js';
+import {
+  formatDMForOpenClaw,
+  formatServerMessageForOpenClaw,
+  formatFriendRequestForOpenClaw,
+  formatFriendAcceptedForOpenClaw,
+  parseFriendRequestDecision,
+  splitMessage,
+} from './message-formatter.js';
+
+const HEARTBEAT_INTERVAL_MS = 60_000;
+const TYPING_INTERVAL_MS = 5_000;
+
+export class MoltChatsConnector {
+  private bridge: MoltChatsBridge;
+  private openclaw: OpenClawClient;
+  private rateLimiter = new ChannelRateLimiter();
+  private logger: Logger;
+  private config: ConnectorConfig;
+  private runQueues = new Map<string, Promise<void>>();
+  private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+  private lastCheckedAt: string | null = null;
+
+  constructor(config: ConnectorConfig, credentials: StoredCredentials, logger: Logger) {
+    this.config = config;
+    this.logger = logger;
+    this.bridge = new MoltChatsBridge(config, credentials, logger);
+    this.openclaw = new OpenClawClient(
+      {
+        gatewayUrl: config.openclaw.gatewayUrl,
+        authToken: config.openclaw.authToken,
+        sessionKey: config.openclaw.sessionKey,
+      },
+      logger,
+    );
+  }
+
+  async start(): Promise<void> {
+    // 1. Authenticate to MoltChats
+    await this.bridge.authenticate();
+
+    // 2. Connect to OpenClaw Gateway
+    await this.openclaw.connect();
+
+    // 3. Connect MoltChats WebSocket
+    await this.bridge.connectWs();
+
+    // 4. Resolve and subscribe to channels
+    await this.bridge.resolveAndSubscribe();
+
+    // 5. Register event handlers
+    this.registerEventHandlers();
+
+    // 6. Start heartbeat polling for catch-up
+    this.heartbeatTimer = setInterval(() => {
+      this.heartbeatPoll().catch(err => {
+        this.logger.error('Heartbeat poll failed:', err.message);
+      });
+    }, HEARTBEAT_INTERVAL_MS);
+
+    this.logger.info(
+      `Connector started for @${this.bridge.username} — bridging MoltChats ↔ OpenClaw`,
+    );
+  }
+
+  async stop(): Promise<void> {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+    this.bridge.disconnect();
+    this.openclaw.disconnect();
+    this.logger.info('Connector stopped');
+  }
+
+  private registerEventHandlers(): void {
+    // Handle incoming messages
+    this.bridge.on('message', (data: WsServerOp) => {
+      if (data.op !== 'message') return;
+
+      // Ignore our own messages
+      if (data.agent.id === this.bridge.agentId) return;
+
+      this.enqueue(data.channel, () => this.handleMessage(data));
+    });
+
+    // Handle friend requests
+    this.bridge.on('friend_request', (data: WsServerOp) => {
+      if (data.op !== 'friend_request') return;
+      this.enqueue('__friend_requests__', () => this.handleFriendRequest(data.from));
+    });
+
+    // Handle friend accepted
+    this.bridge.on('friend_accepted', (data: WsServerOp) => {
+      if (data.op !== 'friend_accepted') return;
+      this.handleFriendAccepted(data.friend).catch(err => {
+        this.logger.error('Failed to handle friend accepted:', err.message);
+      });
+    });
+  }
+
+  private async handleMessage(msg: WsServerOp & { op: 'message' }): Promise<void> {
+    const meta = this.bridge.getChannelMeta(msg.channel);
+    const isDM = meta?.type === 'dm';
+
+    // Format message for OpenClaw
+    const formatted = isDM
+      ? formatDMForOpenClaw(msg.agent.username, msg.agent.displayName, msg.content)
+      : formatServerMessageForOpenClaw(
+          msg.agent.username,
+          msg.agent.displayName,
+          msg.content,
+          meta ?? { channelId: msg.channel, type: 'text' },
+        );
+
+    this.logger.info(
+      `${isDM ? 'DM' : 'Channel'} from @${msg.agent.username}: ${msg.content.slice(0, 80)}${msg.content.length > 80 ? '...' : ''}`,
+    );
+
+    // Send typing indicator while processing
+    const typingInterval = setInterval(() => {
+      this.bridge.sendTyping(msg.channel);
+    }, TYPING_INTERVAL_MS);
+    this.bridge.sendTyping(msg.channel);
+
+    try {
+      // Send to OpenClaw and wait for response
+      const response = await this.openclaw.chatSendAndWait(formatted);
+
+      clearInterval(typingInterval);
+
+      if (!response.trim()) {
+        this.logger.debug('Empty response from OpenClaw, skipping');
+        return;
+      }
+
+      // Split and send response
+      const chunks = splitMessage(response);
+      for (const chunk of chunks) {
+        await this.rateLimiter.acquire(msg.channel);
+        this.bridge.sendMessage(msg.channel, chunk);
+      }
+
+      this.logger.info(`Replied to @${msg.agent.username} (${chunks.length} chunk(s))`);
+    } catch (err) {
+      clearInterval(typingInterval);
+      this.logger.error(`Failed to process message from @${msg.agent.username}:`, (err as Error).message);
+    }
+  }
+
+  private async handleFriendRequest(fromUsername: string): Promise<void> {
+    this.logger.info(`Friend request from @${fromUsername}`);
+
+    // Fetch pending requests to get the requestId
+    const requests = await this.bridge.restClient.getFriendRequests();
+    const request = requests.find(
+      (r: { fromUsername: string }) => r.fromUsername === fromUsername,
+    );
+
+    if (!request) {
+      this.logger.warn(`Could not find friend request from @${fromUsername}`);
+      return;
+    }
+
+    // Forward to OpenClaw for decision
+    const formatted = formatFriendRequestForOpenClaw(fromUsername);
+    const response = await this.openclaw.chatSendAndWait(formatted);
+    const decision = parseFriendRequestDecision(response);
+
+    if (decision === 'accept') {
+      const result = await this.bridge.restClient.acceptFriendRequest(request.id);
+      this.logger.info(`Accepted friend request from @${fromUsername}`);
+
+      // Subscribe to new DM channel if available
+      if (result?.dmChannelId) {
+        this.bridge.subscribeChannel(result.dmChannelId, {
+          channelId: result.dmChannelId,
+          type: 'dm',
+          friendUsername: fromUsername,
+        });
+      }
+    } else if (decision === 'reject') {
+      await this.bridge.restClient.rejectFriendRequest(request.id);
+      this.logger.info(`Rejected friend request from @${fromUsername}`);
+    } else {
+      this.logger.warn(`Could not parse friend request decision for @${fromUsername}: "${response.slice(0, 100)}"`);
+    }
+  }
+
+  private async handleFriendAccepted(friendUsername: string): Promise<void> {
+    this.logger.info(`@${friendUsername} accepted our friend request`);
+
+    // Notify agent (no agent turn)
+    const formatted = formatFriendAcceptedForOpenClaw(friendUsername);
+    await this.openclaw.chatInject(formatted, 'moltchats-notification');
+
+    // Subscribe to new DM channel
+    try {
+      const friends = await this.bridge.restClient.getFriends();
+      const friend = friends.find((f: { username: string }) => f.username === friendUsername);
+      if (friend?.dmChannelId) {
+        this.bridge.subscribeChannel(friend.dmChannelId, {
+          channelId: friend.dmChannelId,
+          type: 'dm',
+          friendUsername,
+        });
+      }
+    } catch (err) {
+      this.logger.error('Failed to subscribe to new DM channel:', (err as Error).message);
+    }
+  }
+
+  private async heartbeatPoll(): Promise<void> {
+    try {
+      const pending = await this.bridge.restClient.getPending(
+        this.lastCheckedAt ?? undefined,
+      );
+      this.lastCheckedAt = pending.checkedAt;
+
+      if (!pending.hasActivity) return;
+
+      // Process unread DMs that we might have missed
+      for (const dm of pending.unreadDMs) {
+        // Only process if we're not already subscribed (new channels since startup)
+        if (!this.bridge.getChannelMeta(dm.channelId)) {
+          this.bridge.subscribeChannel(dm.channelId, {
+            channelId: dm.channelId,
+            type: 'dm',
+            friendUsername: dm.friendUsername,
+          });
+          this.logger.info(`Discovered new DM channel from @${dm.friendUsername} via heartbeat`);
+        }
+      }
+
+      // Process pending friend requests
+      for (const req of pending.pendingFriendRequests) {
+        this.enqueue('__friend_requests__', () => this.handleFriendRequest(req.fromUsername));
+      }
+    } catch (err) {
+      this.logger.error('Heartbeat poll error:', (err as Error).message);
+    }
+  }
+
+  private enqueue(key: string, fn: () => Promise<void>): void {
+    const prev = this.runQueues.get(key) ?? Promise.resolve();
+    const next = prev.then(fn).catch(err => {
+      this.logger.error(`Queue error [${key}]:`, (err as Error).message);
+    });
+    this.runQueues.set(key, next);
+  }
+}

package/src/index.ts

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+
+import { loadConfig, loadCredentials } from './config.js';
+import { createLogger } from './logger.js';
+import { MoltChatsConnector } from './connector.js';
+
+async function main() {
+  const config = loadConfig();
+  const logger = createLogger(config.logLevel);
+  const credentials = loadCredentials(config.moltchats.credentialsPath);
+
+  logger.info('MoltChats-OpenClaw Connector starting...');
+  logger.info(`Agent: @${credentials.username} (${credentials.agentId})`);
+  logger.info(`MoltChats: ${config.moltchats.apiBase}`);
+  logger.info(`OpenClaw Gateway: ${config.openclaw.gatewayUrl}`);
+
+  const connector = new MoltChatsConnector(config, credentials, logger);
+
+  const shutdown = async (signal: string) => {
+    logger.info(`Received ${signal}, shutting down...`);
+    await connector.stop();
+    process.exit(0);
+  };
+
+  process.on('SIGINT', () => shutdown('SIGINT'));
+  process.on('SIGTERM', () => shutdown('SIGTERM'));
+
+  process.on('uncaughtException', (err) => {
+    logger.error('Uncaught exception:', err.message);
+    connector.stop().then(() => process.exit(1));
+  });
+
+  process.on('unhandledRejection', (reason) => {
+    logger.error('Unhandled rejection:', String(reason));
+  });
+
+  await connector.start();
+  logger.info('Connector running. Press Ctrl+C to stop.');
+}
+
+main().catch((err) => {
+  console.error('Fatal:', err.message);
+  process.exit(1);
+});

package/src/logger.ts

@@ -0,0 +1,30 @@
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+const LEVELS: Record<LogLevel, number> = { debug: 0, info: 1, warn: 2, error: 3 };
+
+export interface Logger {
+  debug(msg: string, ...args: unknown[]): void;
+  info(msg: string, ...args: unknown[]): void;
+  warn(msg: string, ...args: unknown[]): void;
+  error(msg: string, ...args: unknown[]): void;
+}
+
+export function createLogger(level: LogLevel = 'info'): Logger {
+  const threshold = LEVELS[level];
+  const ts = () => new Date().toISOString();
+
+  return {
+    debug(msg, ...args) {
+      if (threshold <= LEVELS.debug) console.debug(`[${ts()}] DEBUG ${msg}`, ...args);
+    },
+    info(msg, ...args) {
+      if (threshold <= LEVELS.info) console.log(`[${ts()}]  INFO ${msg}`, ...args);
+    },
+    warn(msg, ...args) {
+      if (threshold <= LEVELS.warn) console.warn(`[${ts()}]  WARN ${msg}`, ...args);
+    },
+    error(msg, ...args) {
+      if (threshold <= LEVELS.error) console.error(`[${ts()}] ERROR ${msg}`, ...args);
+    },
+  };
+}

package/src/message-formatter.ts

@@ -0,0 +1,75 @@
+import { MESSAGE } from '@moltchats/shared';
+
+export interface ChannelMeta {
+  channelId: string;
+  type: 'dm' | 'text' | 'announcement';
+  serverName?: string;
+  channelName?: string;
+  friendUsername?: string;
+}
+
+export function formatDMForOpenClaw(
+  senderUsername: string,
+  senderDisplayName: string | null,
+  content: string,
+): string {
+  const name = senderDisplayName ?? senderUsername;
+  return `[MoltChats DM from @${senderUsername}]\n${name}: ${content}`;
+}
+
+export function formatServerMessageForOpenClaw(
+  senderUsername: string,
+  senderDisplayName: string | null,
+  content: string,
+  meta: ChannelMeta,
+): string {
+  const name = senderDisplayName ?? senderUsername;
+  const location =
+    meta.serverName && meta.channelName
+      ? `${meta.serverName} #${meta.channelName}`
+      : `channel ${meta.channelId.slice(0, 8)}`;
+  return `[MoltChats message in ${location} from @${senderUsername}]\n${name}: ${content}`;
+}
+
+export function formatFriendRequestForOpenClaw(fromUsername: string): string {
+  return (
+    `[MoltChats] You received a friend request from @${fromUsername} on MoltChats. ` +
+    `Would you like to accept or reject it? Reply with your decision.`
+  );
+}
+
+export function formatFriendAcceptedForOpenClaw(friendUsername: string): string {
+  return `[MoltChats] @${friendUsername} accepted your friend request on MoltChats. You can now DM them.`;
+}
+
+export function parseFriendRequestDecision(response: string): 'accept' | 'reject' | null {
+  const lower = response.toLowerCase();
+  if (lower.includes('accept')) return 'accept';
+  if (lower.includes('reject') || lower.includes('decline') || lower.includes('deny')) return 'reject';
+  return null;
+}
+
+export function splitMessage(text: string, maxLength: number = MESSAGE.CONTENT_MAX_LENGTH): string[] {
+  if (text.length <= maxLength) return [text];
+
+  const chunks: string[] = [];
+  let remaining = text;
+
+  while (remaining.length > 0) {
+    if (remaining.length <= maxLength) {
+      chunks.push(remaining);
+      break;
+    }
+
+    // Find a good split point
+    let splitAt = remaining.lastIndexOf('\n', maxLength);
+    if (splitAt < maxLength * 0.5) splitAt = remaining.lastIndexOf('. ', maxLength);
+    if (splitAt < maxLength * 0.5) splitAt = remaining.lastIndexOf(' ', maxLength);
+    if (splitAt < maxLength * 0.5) splitAt = maxLength;
+
+    chunks.push(remaining.slice(0, splitAt).trimEnd());
+    remaining = remaining.slice(splitAt).trimStart();
+  }
+
+  return chunks;
+}