@moltchats/connector 0.3.0

package/src/moltchats-bridge.ts

@@ -0,0 +1,288 @@
+import { writeFileSync } from 'node:fs';
+import { MoltChatsClient, MoltChatsWs } from '@moltchats/sdk';
+import type { WsServerOp } from '@moltchats/shared';
+import type { ConnectorConfig, StoredCredentials } from './config.js';
+import type { Logger } from './logger.js';
+import type { ChannelMeta } from './message-formatter.js';
+
+type MessageHandler = (data: WsServerOp) => void;
+
+const MAX_RECONNECT_ATTEMPTS = 20;
+const RECONNECT_BASE_MS = 1000;
+const RECONNECT_CAP_MS = 30000;
+const TOKEN_REFRESH_BUFFER_MS = 5 * 60 * 1000; // refresh 5 min before expiry
+
+export class MoltChatsBridge {
+  private client: MoltChatsClient;
+  private ws: MoltChatsWs | null = null;
+  private config: ConnectorConfig;
+  private credentials: StoredCredentials;
+  private logger: Logger;
+  private handlers = new Map<string, Set<MessageHandler>>();
+  private subscribedChannels = new Set<string>();
+  private channelMeta = new Map<string, ChannelMeta>();
+  private refreshTimer: ReturnType<typeof setTimeout> | null = null;
+  private reconnectAttempts = 0;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private closed = false;
+
+  constructor(config: ConnectorConfig, credentials: StoredCredentials, logger: Logger) {
+    this.config = config;
+    this.credentials = credentials;
+    this.logger = logger;
+    this.client = new MoltChatsClient({ baseUrl: config.moltchats.apiBase });
+  }
+
+  get agentId(): string {
+    return this.credentials.agentId;
+  }
+
+  get username(): string {
+    return this.credentials.username;
+  }
+
+  get restClient(): MoltChatsClient {
+    return this.client;
+  }
+
+  getChannelMeta(channelId: string): ChannelMeta | undefined {
+    return this.channelMeta.get(channelId);
+  }
+
+  async authenticate(): Promise<void> {
+    // Try existing token first
+    if (this.credentials.token) {
+      try {
+        this.client.setToken(this.credentials.token);
+        await this.client.getProfile();
+        this.logger.debug('Existing token is valid');
+        this.scheduleTokenRefresh(this.credentials.token);
+        return;
+      } catch {
+        this.logger.debug('Existing token expired, trying refresh...');
+      }
+    }
+
+    // Try refresh token
+    try {
+      const auth = await this.client.refreshToken(this.credentials.refreshToken);
+      this.updateCredentials(auth.token, auth.refreshToken);
+      this.logger.info('Authenticated via refresh token');
+      this.scheduleTokenRefresh(auth.token);
+      return;
+    } catch {
+      this.logger.debug('Refresh token failed, falling back to reauth...');
+    }
+
+    // Fall back to challenge-response
+    const auth = await this.client.reauth(this.credentials.agentId, this.credentials.privateKey);
+    this.updateCredentials(auth.token, auth.refreshToken);
+    this.logger.info('Authenticated via challenge-response');
+    this.scheduleTokenRefresh(auth.token);
+  }
+
+  async connectWs(): Promise<void> {
+    this.closed = false;
+    const token = this.credentials.token!;
+    this.ws = new MoltChatsWs({
+      url: this.config.moltchats.wsBase,
+      token,
+      autoReconnect: false, // we handle reconnection ourselves for token refresh
+    });
+
+    // Register event handlers before connecting
+    this.ws.on('*', (data: WsServerOp) => {
+      this.emit(data.op, data);
+    });
+
+    this.ws.on('error', (data: WsServerOp) => {
+      if ('code' in data && data.code === 'MAX_RECONNECT') {
+        this.logger.warn('MoltChats WS max reconnect reached, handling manually');
+        this.handleDisconnect();
+      }
+    });
+
+    await this.ws.connect();
+    this.reconnectAttempts = 0;
+    this.logger.info('Connected to MoltChats WebSocket');
+  }
+
+  async resolveAndSubscribe(): Promise<void> {
+    const channels: string[] = [...this.config.channels.serverChannels];
+
+    // Auto-subscribe to DM channels
+    if (this.config.channels.autoSubscribeDMs) {
+      try {
+        const friends = await this.client.getFriends();
+        for (const friend of friends) {
+          if (friend.dmChannelId) {
+            channels.push(friend.dmChannelId);
+            this.channelMeta.set(friend.dmChannelId, {
+              channelId: friend.dmChannelId,
+              type: 'dm',
+              friendUsername: friend.username,
+            });
+          }
+        }
+        this.logger.info(`Found ${friends.length} friends with DM channels`);
+      } catch (err) {
+        this.logger.error('Failed to fetch friends list:', (err as Error).message);
+      }
+    }
+
+    // Subscribe to server channels
+    for (const serverId of this.config.channels.serverIds) {
+      try {
+        const serverChannels = await this.client.getServerChannels(serverId);
+        const server = await this.client.getServer(serverId);
+        for (const ch of serverChannels) {
+          channels.push(ch.id);
+          this.channelMeta.set(ch.id, {
+            channelId: ch.id,
+            type: ch.type ?? 'text',
+            serverName: server.name,
+            channelName: ch.name,
+          });
+        }
+        this.logger.info(`Subscribed to ${serverChannels.length} channels in server "${server.name}"`);
+      } catch (err) {
+        this.logger.error(`Failed to fetch channels for server ${serverId}:`, (err as Error).message);
+      }
+    }
+
+    if (channels.length > 0) {
+      this.ws!.subscribe(channels);
+      for (const ch of channels) this.subscribedChannels.add(ch);
+      this.logger.info(`Subscribed to ${channels.length} channels total`);
+    } else {
+      this.logger.warn('No channels to subscribe to');
+    }
+  }
+
+  subscribeChannel(channelId: string, meta?: ChannelMeta): void {
+    if (this.subscribedChannels.has(channelId)) return;
+    this.subscribedChannels.add(channelId);
+    if (meta) this.channelMeta.set(channelId, meta);
+    this.ws?.subscribe([channelId]);
+    this.logger.debug(`Subscribed to channel ${channelId}`);
+  }
+
+  sendMessage(channelId: string, content: string): void {
+    this.ws?.sendMessage(channelId, content);
+  }
+
+  sendTyping(channelId: string): void {
+    this.ws?.sendTyping(channelId);
+  }
+
+  on(event: string, handler: MessageHandler): () => void {
+    if (!this.handlers.has(event)) {
+      this.handlers.set(event, new Set());
+    }
+    this.handlers.get(event)!.add(handler);
+    return () => this.handlers.get(event)?.delete(handler);
+  }
+
+  disconnect(): void {
+    this.closed = true;
+    if (this.refreshTimer) {
+      clearTimeout(this.refreshTimer);
+      this.refreshTimer = null;
+    }
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    this.ws?.disconnect();
+    this.ws = null;
+  }
+
+  private emit(event: string, data: WsServerOp): void {
+    this.handlers.get(event)?.forEach(h => h(data));
+    this.handlers.get('*')?.forEach(h => h(data));
+  }
+
+  private async handleDisconnect(): Promise<void> {
+    if (this.closed) return;
+
+    if (this.reconnectAttempts >= MAX_RECONNECT_ATTEMPTS) {
+      this.logger.error('Max MoltChats reconnect attempts reached');
+      return;
+    }
+
+    const delay = Math.min(
+      RECONNECT_BASE_MS * Math.pow(2, this.reconnectAttempts),
+      RECONNECT_CAP_MS,
+    );
+    this.reconnectAttempts++;
+    this.logger.info(`Reconnecting to MoltChats in ${delay}ms (attempt ${this.reconnectAttempts})`);
+
+    this.reconnectTimer = setTimeout(async () => {
+      try {
+        // Refresh auth before reconnecting
+        await this.authenticate();
+        await this.connectWs();
+        // Re-subscribe to all channels
+        if (this.subscribedChannels.size > 0) {
+          this.ws!.subscribe([...this.subscribedChannels]);
+        }
+      } catch (err) {
+        this.logger.error('MoltChats reconnect failed:', (err as Error).message);
+        this.handleDisconnect();
+      }
+    }, delay);
+  }
+
+  private scheduleTokenRefresh(token: string): void {
+    if (this.refreshTimer) clearTimeout(this.refreshTimer);
+
+    try {
+      // Parse JWT exp claim
+      const payload = JSON.parse(
+        Buffer.from(token.split('.')[1], 'base64').toString(),
+      );
+      const expiresAt = payload.exp * 1000;
+      const refreshAt = expiresAt - TOKEN_REFRESH_BUFFER_MS;
+      const delay = Math.max(refreshAt - Date.now(), 0);
+
+      this.logger.debug(`Token refresh scheduled in ${Math.round(delay / 1000)}s`);
+
+      this.refreshTimer = setTimeout(async () => {
+        try {
+          const auth = await this.client.refreshToken(this.credentials.refreshToken);
+          this.updateCredentials(auth.token, auth.refreshToken);
+          this.logger.info('Token refreshed proactively');
+          this.scheduleTokenRefresh(auth.token);
+
+          // Reconnect WS with new token
+          this.ws?.disconnect();
+          await this.connectWs();
+          if (this.subscribedChannels.size > 0) {
+            this.ws!.subscribe([...this.subscribedChannels]);
+          }
+        } catch (err) {
+          this.logger.error('Proactive token refresh failed:', (err as Error).message);
+          // Will be caught on next WS reconnect
+        }
+      }, delay);
+    } catch {
+      this.logger.warn('Could not parse JWT for refresh scheduling');
+    }
+  }
+
+  private updateCredentials(token: string, refreshToken: string): void {
+    this.credentials.token = token;
+    this.credentials.refreshToken = refreshToken;
+
+    // Persist updated credentials
+    try {
+      writeFileSync(
+        this.config.moltchats.credentialsPath,
+        JSON.stringify(this.credentials, null, 2),
+        { mode: 0o600 },
+      );
+    } catch (err) {
+      this.logger.warn('Failed to persist credentials:', (err as Error).message);
+    }
+  }
+}

package/src/openclaw-client.ts

@@ -0,0 +1,308 @@
+import { randomUUID } from 'node:crypto';
+import WebSocket from 'ws';
+import type { Logger } from './logger.js';
+
+export interface OpenClawConfig {
+  gatewayUrl: string;
+  authToken: string;
+  sessionKey: string;
+}
+
+export type ChatEventState = 'delta' | 'final' | 'aborted' | 'error';
+
+export interface ChatEvent {
+  runId: string;
+  sessionKey: string;
+  state: ChatEventState;
+  message?: unknown;
+  errorMessage?: string;
+}
+
+interface PendingRequest {
+  resolve: (payload: unknown) => void;
+  reject: (err: Error) => void;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+type ChatEventHandler = (event: ChatEvent) => void;
+
+const MAX_RECONNECT_ATTEMPTS = 20;
+const RECONNECT_BASE_MS = 2000;
+const RECONNECT_CAP_MS = 30000;
+const REQUEST_TIMEOUT_MS = 30000;
+const RUN_TIMEOUT_MS = 300000; // 5 minutes
+
+export class OpenClawClient {
+  private ws: WebSocket | null = null;
+  private config: OpenClawConfig;
+  private logger: Logger;
+  private pending = new Map<string, PendingRequest>();
+  private chatHandlers = new Set<ChatEventHandler>();
+  private reconnectAttempts = 0;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private closed = false;
+  private _connected = false;
+
+  constructor(config: OpenClawConfig, logger: Logger) {
+    this.config = config;
+    this.logger = logger;
+  }
+
+  get connected(): boolean {
+    return this._connected;
+  }
+
+  onChat(handler: ChatEventHandler): () => void {
+    this.chatHandlers.add(handler);
+    return () => this.chatHandlers.delete(handler);
+  }
+
+  async connect(): Promise<void> {
+    this.closed = false;
+    return new Promise((resolve, reject) => {
+      this.ws = new WebSocket(this.config.gatewayUrl);
+
+      let handshakeComplete = false;
+
+      this.ws.on('open', () => {
+        this.logger.debug('OpenClaw Gateway WS connected, waiting for challenge...');
+      });
+
+      this.ws.on('message', (raw: WebSocket.RawData) => {
+        let frame: Record<string, unknown>;
+        try {
+          frame = JSON.parse(raw.toString());
+        } catch {
+          return;
+        }
+
+        // Handle connect.challenge during handshake
+        if (!handshakeComplete && frame.type === 'event' && frame.event === 'connect.challenge') {
+          const payload = frame.payload as Record<string, unknown>;
+          this.sendRaw({
+            type: 'req',
+            id: randomUUID(),
+            method: 'connect',
+            params: {
+              minProtocol: 3,
+              maxProtocol: 3,
+              client: {
+                id: 'moltchats-connector',
+                version: '0.3.0',
+                platform: 'node',
+                mode: 'api',
+              },
+              auth: { token: this.config.authToken },
+              role: 'operator',
+              scopes: ['operator.read', 'operator.write'],
+              nonce: payload.nonce,
+            },
+          });
+          return;
+        }
+
+        // Handle connect response
+        if (!handshakeComplete && frame.type === 'res') {
+          const resFrame = frame as { ok?: boolean; error?: { message?: string } };
+          if (resFrame.ok === false) {
+            const errMsg = resFrame.error?.message ?? 'Gateway handshake failed';
+            reject(new Error(errMsg));
+            return;
+          }
+          handshakeComplete = true;
+          this._connected = true;
+          this.reconnectAttempts = 0;
+          this.logger.info('Connected to OpenClaw Gateway');
+          resolve();
+          return;
+        }
+
+        // Dispatch normal frames
+        this.handleFrame(frame);
+      });
+
+      this.ws.on('close', () => {
+        this._connected = false;
+        if (!this.closed) {
+          this.logger.warn('OpenClaw Gateway connection lost');
+          this.scheduleReconnect();
+        }
+      });
+
+      this.ws.on('error', (err: Error) => {
+        if (!handshakeComplete) {
+          reject(err);
+        } else {
+          this.logger.error('OpenClaw Gateway WS error:', err.message);
+        }
+      });
+    });
+  }
+
+  async chatSend(message: string): Promise<{ runId: string }> {
+    const id = randomUUID();
+    const idempotencyKey = randomUUID();
+
+    const payload = await this.request(id, 'chat.send', {
+      sessionKey: this.config.sessionKey,
+      message,
+      idempotencyKey,
+    }) as Record<string, unknown>;
+
+    return { runId: (payload.runId as string) ?? idempotencyKey };
+  }
+
+  /**
+   * Send chat.send and wait for the full streamed response.
+   * Returns the final response text.
+   */
+  async chatSendAndWait(message: string): Promise<string> {
+    const { runId } = await this.chatSend(message);
+    return this.waitForRunCompletion(runId);
+  }
+
+  async chatInject(message: string, label?: string): Promise<void> {
+    const id = randomUUID();
+    await this.request(id, 'chat.inject', {
+      sessionKey: this.config.sessionKey,
+      message,
+      ...(label ? { label } : {}),
+    });
+  }
+
+  async chatAbort(runId: string): Promise<void> {
+    const id = randomUUID();
+    await this.request(id, 'chat.abort', {
+      sessionKey: this.config.sessionKey,
+      runId,
+    });
+  }
+
+  disconnect(): void {
+    this.closed = true;
+    this._connected = false;
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    // Reject all pending requests
+    for (const [, req] of this.pending) {
+      clearTimeout(req.timer);
+      req.reject(new Error('Client disconnected'));
+    }
+    this.pending.clear();
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+    }
+  }
+
+  private waitForRunCompletion(runId: string): Promise<string> {
+    return new Promise((resolve, reject) => {
+      let accumulated = '';
+      const timeout = setTimeout(() => {
+        off();
+        this.chatAbort(runId).catch(() => {});
+        reject(new Error(`Run ${runId} timed out after ${RUN_TIMEOUT_MS / 1000}s`));
+      }, RUN_TIMEOUT_MS);
+
+      const off = this.onChat((event) => {
+        if (event.runId !== runId) return;
+
+        switch (event.state) {
+          case 'delta':
+            if (typeof event.message === 'string') {
+              accumulated = event.message;
+            }
+            break;
+          case 'final':
+            clearTimeout(timeout);
+            off();
+            if (typeof event.message === 'string') {
+              resolve(event.message);
+            } else if (typeof event.message === 'object' && event.message !== null) {
+              const msg = event.message as Record<string, unknown>;
+              resolve((msg.content as string) ?? accumulated);
+            } else {
+              resolve(accumulated);
+            }
+            break;
+          case 'aborted':
+            clearTimeout(timeout);
+            off();
+            reject(new Error('Run was aborted'));
+            break;
+          case 'error':
+            clearTimeout(timeout);
+            off();
+            reject(new Error(event.errorMessage ?? 'Run failed'));
+            break;
+        }
+      });
+    });
+  }
+
+  private async request(id: string, method: string, params: Record<string, unknown>): Promise<unknown> {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`Request ${method} timed out`));
+      }, REQUEST_TIMEOUT_MS);
+
+      this.pending.set(id, { resolve, reject, timer });
+      this.sendRaw({ type: 'req', id, method, params });
+    });
+  }
+
+  private handleFrame(frame: Record<string, unknown>): void {
+    if (frame.type === 'res') {
+      const id = frame.id as string;
+      const pending = this.pending.get(id);
+      if (pending) {
+        this.pending.delete(id);
+        clearTimeout(pending.timer);
+        if (frame.ok === false) {
+          const err = frame.error as Record<string, unknown> | undefined;
+          pending.reject(new Error((err?.message as string) ?? 'Request failed'));
+        } else {
+          pending.resolve(frame.payload ?? frame.result ?? {});
+        }
+      }
+      return;
+    }
+
+    if (frame.type === 'event' && frame.event === 'chat') {
+      const event = frame.payload as ChatEvent;
+      for (const handler of this.chatHandlers) {
+        handler(event);
+      }
+      return;
+    }
+  }
+
+  private sendRaw(data: Record<string, unknown>): void {
+    if (this.ws?.readyState === WebSocket.OPEN) {
+      this.ws.send(JSON.stringify(data));
+    }
+  }
+
+  private scheduleReconnect(): void {
+    if (this.reconnectAttempts >= MAX_RECONNECT_ATTEMPTS) {
+      this.logger.error('Max OpenClaw Gateway reconnect attempts reached');
+      return;
+    }
+
+    const delay = Math.min(
+      RECONNECT_BASE_MS * Math.pow(2, this.reconnectAttempts),
+      RECONNECT_CAP_MS,
+    );
+    this.reconnectAttempts++;
+    this.logger.info(`Reconnecting to OpenClaw Gateway in ${delay}ms (attempt ${this.reconnectAttempts})`);
+
+    this.reconnectTimer = setTimeout(() => {
+      this.connect().catch((err) => {
+        this.logger.error('OpenClaw Gateway reconnect failed:', err.message);
+      });
+    }, delay);
+  }
+}

package/src/rate-limiter.ts

@@ -0,0 +1,60 @@
+import { RATE_LIMITS } from '@moltchats/shared';
+
+interface Bucket {
+  tokens: number;
+  lastRefill: number;
+}
+
+export class ChannelRateLimiter {
+  private buckets = new Map<string, Bucket>();
+  private maxTokens: number;
+  private refillIntervalMs: number;
+
+  constructor(
+    maxTokens: number = RATE_LIMITS.WS_MESSAGES_PER_MIN_PER_CHANNEL,
+    refillIntervalMs: number = 60_000 / RATE_LIMITS.WS_MESSAGES_PER_MIN_PER_CHANNEL,
+  ) {
+    this.maxTokens = maxTokens;
+    this.refillIntervalMs = refillIntervalMs;
+  }
+
+  private getBucket(channelId: string): Bucket {
+    let bucket = this.buckets.get(channelId);
+    if (!bucket) {
+      bucket = { tokens: this.maxTokens, lastRefill: Date.now() };
+      this.buckets.set(channelId, bucket);
+    }
+    return bucket;
+  }
+
+  private refill(bucket: Bucket): void {
+    const now = Date.now();
+    const elapsed = now - bucket.lastRefill;
+    const tokensToAdd = Math.floor(elapsed / this.refillIntervalMs);
+    if (tokensToAdd > 0) {
+      bucket.tokens = Math.min(this.maxTokens, bucket.tokens + tokensToAdd);
+      bucket.lastRefill = now;
+    }
+  }
+
+  canSend(channelId: string): boolean {
+    const bucket = this.getBucket(channelId);
+    this.refill(bucket);
+    return bucket.tokens > 0;
+  }
+
+  async acquire(channelId: string): Promise<void> {
+    const bucket = this.getBucket(channelId);
+    this.refill(bucket);
+
+    if (bucket.tokens > 0) {
+      bucket.tokens--;
+      return;
+    }
+
+    // Wait until a token is available
+    const waitMs = this.refillIntervalMs - (Date.now() - bucket.lastRefill);
+    await new Promise(resolve => setTimeout(resolve, Math.max(waitMs, 100)));
+    return this.acquire(channelId);
+  }
+}

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}