@ihazz/bitrix24 1.0.3 → 1.1.0

package/tests/history-cache.test.ts

@@ -0,0 +1,117 @@
+import { describe, it, expect } from 'vitest';
+import { HistoryCache } from '../src/history-cache.js';
+
+describe('HistoryCache', () => {
+  it('keeps only the newest entries up to the per-key limit', () => {
+    const cache = new HistoryCache();
+
+    cache.append({
+      key: 'chat:1',
+      limit: 2,
+      entry: { messageId: '1', sender: 'A', body: 'first' },
+    });
+    cache.append({
+      key: 'chat:1',
+      limit: 2,
+      entry: { messageId: '2', sender: 'A', body: 'second' },
+    });
+    cache.append({
+      key: 'chat:1',
+      limit: 2,
+      entry: { messageId: '3', sender: 'A', body: 'third' },
+    });
+
+    expect(cache.get('chat:1')).toEqual([
+      { messageId: '2', sender: 'A', body: 'second' },
+      { messageId: '3', sender: 'A', body: 'third' },
+    ]);
+  });
+
+  it('finds entries by message id', () => {
+    const cache = new HistoryCache();
+    cache.append({
+      key: 'chat:1',
+      limit: 10,
+      entry: { messageId: '55', sender: 'A', body: 'hello' },
+    });
+
+    expect(cache.findByMessageId('chat:1', '55')).toMatchObject({
+      messageId: '55',
+      body: 'hello',
+    });
+    expect(cache.findByMessageId('chat:1', '99')).toBeUndefined();
+  });
+
+  it('evicts oldest keys when cache exceeds maxKeys', () => {
+    const cache = new HistoryCache({ maxKeys: 2 });
+    cache.append({
+      key: 'chat:1',
+      limit: 10,
+      entry: { messageId: '1', sender: 'A', body: 'one' },
+    });
+    cache.append({
+      key: 'chat:2',
+      limit: 10,
+      entry: { messageId: '2', sender: 'B', body: 'two' },
+    });
+    cache.append({
+      key: 'chat:3',
+      limit: 10,
+      entry: { messageId: '3', sender: 'C', body: 'three' },
+    });
+
+    expect(cache.size()).toBe(2);
+    expect(cache.get('chat:1')).toEqual([]);
+    expect(cache.get('chat:2')).toHaveLength(1);
+    expect(cache.get('chat:3')).toHaveLength(1);
+  });
+
+  it('stores and lists conversation metadata for history keys', () => {
+    const cache = new HistoryCache();
+
+    cache.append({
+      key: 'default:chat520',
+      limit: 10,
+      entry: { messageId: '1', sender: 'Alice', body: 'hello' },
+      meta: {
+        dialogId: 'chat520',
+        chatId: '520',
+        chatName: 'Чат зеленый 17',
+        chatType: 'chat',
+        isGroup: true,
+        lastActivityAt: 1,
+      },
+    });
+
+    expect(cache.listConversations()).toEqual([
+      {
+        key: 'default:chat520',
+        dialogId: 'chat520',
+        chatId: '520',
+        chatName: 'Чат зеленый 17',
+        chatType: 'chat',
+        isGroup: true,
+        lastActivityAt: 1,
+      },
+    ]);
+  });
+
+  it('does not append duplicate entries with the same message id to one history key', () => {
+    const cache = new HistoryCache();
+
+    cache.append({
+      key: 'chat:1',
+      limit: 10,
+      entry: { messageId: '55', sender: 'A', body: 'hello', eventScope: 'bot' },
+    });
+    cache.append({
+      key: 'chat:1',
+      limit: 10,
+      entry: { messageId: '55', sender: 'A', body: 'hello', eventScope: 'user' },
+    });
+
+    expect(cache.get('chat:1')).toEqual([
+      { messageId: '55', sender: 'A', body: 'hello', eventScope: 'bot' },
+    ]);
+  });
+});

package/tests/i18n.test.ts

@@ -1,11 +1,14 @@
 import { describe, it, expect } from 'vitest';
 import {
+  accessApproved,
+  accessDenied,
+  groupPairingPending,
   resolveLocale,
   welcomeMessage,
   onboardingMessage,
+  ownerAndAllowedUsersOnly,
   personalBotOwnerOnly,
-  forwardedMessageUnsupported,
-  replyMessageUnsupported,
+  watchOwnerDmNotice,
 } from '../src/i18n.js';
 
 describe('i18n welcome messages', () => {
@@ -16,12 +19,12 @@ describe('i18n welcome messages', () => {
   });
 
   it('returns localized Russian welcome message', () => {
-    expect(welcomeMessage('ru', 'OpenClaw')).toContain('OpenClaw готов');
+    expect(welcomeMessage('ru', 'OpenClaw')).toContain('OpenClaw готов к работе');
   });
 
   it('falls back to English welcome message for unknown locale', () => {
     expect(welcomeMessage('zz', 'OpenClaw')).toBe(
-      'OpenClaw ready. Send me a message or pick a command below.',
+      'OpenClaw is ready. Send a message or choose a command below.',
     );
   });
 
@@ -31,17 +34,57 @@ describe('i18n welcome messages', () => {
   });
 
   it('returns localized personal bot access denied message', () => {
-    expect(personalBotOwnerOnly('ru')).toContain('персональный');
-    expect(personalBotOwnerOnly('en')).toContain('personal');
+    expect(personalBotOwnerOnly('ru')).toContain('Писать ему может только владелец');
+    expect(personalBotOwnerOnly('en')).toContain('Only the bot owner can message it');
   });
 
-  it('returns localized reply unsupported message', () => {
-    expect(replyMessageUnsupported('ru')).toContain('пока не поддерживаются');
-    expect(replyMessageUnsupported('en')).toContain('not supported');
+  it('returns localized access approved message', () => {
+    expect(accessApproved('ru')).toBe('Доступ к боту подтвержден.');
+    expect(accessApproved('en')).toBe('Access to the bot has been approved.');
   });
 
-  it('returns localized forwarded message unsupported message', () => {
-    expect(forwardedMessageUnsupported('ru')).toContain('Пересланные сообщения');
-    expect(forwardedMessageUnsupported('en')).toContain('Forwarded messages');
+  it('returns localized owner and allowlist access denied message', () => {
+    expect(ownerAndAllowedUsersOnly('ru')).toContain('пользователям с подтвержденным доступом');
+    expect(ownerAndAllowedUsersOnly('en')).toContain('approved access');
+  });
+
+  it('returns localized generic access denied message', () => {
+    expect(accessDenied('ru')).toContain('нет доступа');
+    expect(accessDenied('en')).toContain('do not have access');
+  });
+
+  it('returns localized group pairing pending message', () => {
+    expect(groupPairingPending('ru')).toContain('сначала нужно подтвердить доступ');
+    expect(groupPairingPending('en')).toContain('access must be approved first');
+  });
+
+  it('returns localized owner watch DM notification message', () => {
+    expect(watchOwnerDmNotice('ru', {
+      chatRef: '[URL=/online/?IM_DIALOG=chat520&IM_MESSAGE=710]Green Chat 15[/URL]',
+      topicsRef: '[b]секрет[/b]',
+    })).toBe('Сработало правило отслеживания в чате [URL=/online/?IM_DIALOG=chat520&IM_MESSAGE=710]Green Chat 15[/URL]. Совпавшие темы: [b]секрет[/b]');
+    expect(watchOwnerDmNotice('en', {
+      chatRef: '[URL=/online/?IM_DIALOG=chat520&IM_MESSAGE=710]Green Chat 15[/URL]',
+      topicsRef: '[b]secret[/b]',
+    })).toBe('A watch rule was triggered in chat [URL=/online/?IM_DIALOG=chat520&IM_MESSAGE=710]Green Chat 15[/URL]. Matched topics: [b]secret[/b]');
+    expect(watchOwnerDmNotice('de', {
+      chatRef: '[URL=/online/?IM_DIALOG=chat520&IM_MESSAGE=710]Green Chat 15[/URL]',
+      topicsRef: '[b]geheim[/b]',
+    })).toBe('Eine Beobachtungsregel wurde im Chat [URL=/online/?IM_DIALOG=chat520&IM_MESSAGE=710]Green Chat 15[/URL] ausgeloest. Zugeordnete Themen: [b]geheim[/b]');
+    expect(watchOwnerDmNotice('zz', {
+      chatRef: '[URL=/online/?IM_DIALOG=chat520&IM_MESSAGE=710]Green Chat 15[/URL]',
+      topicsRef: '[b]secret[/b]',
+    })).toBe('A watch rule was triggered in chat [URL=/online/?IM_DIALOG=chat520&IM_MESSAGE=710]Green Chat 15[/URL]. Matched topics: [b]secret[/b]');
+
+    expect(watchOwnerDmNotice('ru', {
+      chatRef: '[URL=/online/?IM_DIALOG=10&IM_MESSAGE=31671]Сергей Рыжиков[/URL]',
+      topicsRef: '[b]авария[/b]',
+      sourceKind: 'dm',
+    })).toBe('Сработало правило отслеживания в личном чате с [URL=/online/?IM_DIALOG=10&IM_MESSAGE=31671]Сергей Рыжиков[/URL]. Совпавшие темы: [b]авария[/b]');
+  expect(watchOwnerDmNotice('en', {
+      chatRef: '[URL=/online/?IM_DIALOG=10&IM_MESSAGE=31671]Sergey Ryzhikov[/URL]',
+      topicsRef: '[b]incident[/b]',
+      sourceKind: 'dm',
+    })).toBe('A watch rule was triggered in a direct chat with [URL=/online/?IM_DIALOG=10&IM_MESSAGE=31671]Sergey Ryzhikov[/URL]. Matched topics: [b]incident[/b]');
   });
 });

package/tests/inbound-handler.test.ts

@@ -116,12 +116,14 @@ describe('InboundHandler', () => {
 
     const ctx = onMessage.mock.calls[0][0] as B24MsgContext;
     expect(ctx.channel).toBe('bitrix24');
+    expect(ctx.eventScope).toBe('bot');
     expect(ctx.text).toBe('Hello, how are you?');
     expect(ctx.senderId).toBe('1');
     expect(ctx.senderName).toBe('Test User');
     expect(ctx.senderFirstName).toBe('Test');
     expect(ctx.chatId).toBe('1');
     expect(ctx.chatInternalId).toBe('40985');
+    expect(ctx.chatName).toBe('Test User');
     expect(ctx.messageId).toBe('490659');
     expect(ctx.replyToMessageId).toBeUndefined();
     expect(ctx.isForwarded).toBe(false);
@@ -129,9 +131,147 @@ describe('InboundHandler', () => {
     expect(ctx.isGroup).toBe(false);
     expect(ctx.media).toEqual([]);
     expect(ctx.language).toBe('ru');
+    expect(ctx.timestamp).toBe(Date.parse('2026-03-18T08:00:00+02:00'));
     expect(ctx.botId).toBe(2081);
   });
 
+  it('dispatches user message events from combined fetch in agent mode', async () => {
+    const onMessage = vi.fn();
+    handler = new InboundHandler({
+      config: { dmPolicy: 'pairing', agentMode: true },
+      logger: silentLogger,
+      onMessage,
+    });
+
+    const event = {
+      eventId: 1007,
+      type: 'ONIMV2MESSAGEADD',
+      date: '2026-03-19T14:36:03+02:00',
+      data: {
+        message: {
+          id: 490660,
+          chatId: 520,
+          authorId: 77,
+          date: '2026-03-19T14:36:03+02:00',
+          text: 'Авария в личке',
+          isSystem: false,
+          uuid: '',
+          forward: null,
+          params: {},
+          viewedByOthers: false,
+        },
+        chat: {
+          id: 520,
+          dialogId: '77',
+          type: 'private',
+          name: 'Sergey',
+          entityType: '',
+          owner: 1,
+          avatar: '',
+          color: '#ab7761',
+        },
+        user: {
+          ...baseUser,
+          id: 77,
+          name: 'Sergey',
+          firstName: 'Sergey',
+        },
+        language: 'ru',
+      },
+    };
+
+    const result = await handler.handleFetchEvent(event as never, fetchCtx);
+    expect(result).toBe(true);
+    expect(onMessage).toHaveBeenCalledOnce();
+    expect(onMessage.mock.calls[0][0]).toMatchObject({
+      eventScope: 'user',
+      chatId: '77',
+      senderId: '77',
+      text: 'Авария в личке',
+      wasMentioned: false,
+    });
+  });
+
+  it('deduplicates bot and user message events that share one message id', async () => {
+    const onMessage = vi.fn();
+    handler = new InboundHandler({
+      config: { dmPolicy: 'pairing', agentMode: true },
+      logger: silentLogger,
+      onMessage,
+    });
+
+    const botEvent = createFetchMessageEvent({
+      message: {
+        id: 555001,
+        chatId: 520,
+        authorId: 77,
+        date: '2026-03-19T14:36:03+02:00',
+        text: 'shared message',
+        isSystem: false,
+        uuid: '',
+        forward: null,
+        params: {},
+        viewedByOthers: false,
+      },
+      chat: {
+        id: 520,
+        dialogId: 'chat520',
+        type: 'chat',
+        name: 'Group Chat',
+        entityType: '',
+        owner: 1,
+        avatar: '',
+        color: '#ab7761',
+      },
+      user: {
+        ...baseUser,
+        id: 77,
+        name: 'Sergey',
+      },
+    });
+
+    const userEvent = {
+      eventId: 1008,
+      type: 'ONIMV2MESSAGEADD',
+      date: '2026-03-19T14:36:04+02:00',
+      data: {
+        message: {
+          id: 555001,
+          chatId: 520,
+          authorId: 77,
+          date: '2026-03-19T14:36:03+02:00',
+          text: 'shared message',
+          isSystem: false,
+          uuid: '',
+          forward: null,
+          params: {},
+          viewedByOthers: false,
+        },
+        chat: {
+          id: 520,
+          dialogId: 'chat520',
+          type: 'chat',
+          name: 'Group Chat',
+          entityType: '',
+          owner: 1,
+          avatar: '',
+          color: '#ab7761',
+        },
+        user: {
+          ...baseUser,
+          id: 77,
+          name: 'Sergey',
+        },
+        language: 'ru',
+      },
+    };
+
+    await handler.handleFetchEvent(botEvent as never, fetchCtx);
+    await handler.handleFetchEvent(userEvent as never, fetchCtx);
+
+    expect(onMessage).toHaveBeenCalledTimes(1);
+  });
+
   it('keeps incoming dialogId for direct chats without replacing it by user id', async () => {
     const onMessage = vi.fn();
     handler = new InboundHandler({
@@ -157,7 +297,7 @@ describe('InboundHandler', () => {
       },
     });
 
-    await handler.handleFetchEvent(event, fetchCtx);
+    await handler.handleFetchEvent(event, { ...fetchCtx, botId: 6809 });
 
     const ctx = onMessage.mock.calls[0][0] as B24MsgContext;
     expect(ctx.chatId).toBe('123');
@@ -173,8 +313,8 @@ describe('InboundHandler', () => {
     });
 
     const event = createFetchMessageEvent();
-    await handler.handleFetchEvent(event, fetchCtx);
-    await handler.handleFetchEvent(event, fetchCtx);
+    await handler.handleFetchEvent(event, { ...fetchCtx, botId: 6809 });
+    await handler.handleFetchEvent(event, { ...fetchCtx, botId: 6809 });
 
     expect(onMessage).toHaveBeenCalledOnce();
   });
@@ -281,6 +421,91 @@ describe('InboundHandler', () => {
     expect(ctx.isForwarded).toBe(true);
   });
 
+  it('detects bot mention in a group message from real Bitrix payload format', async () => {
+    const onMessage = vi.fn();
+    handler = new InboundHandler({
+      config: { dmPolicy: 'pairing', botName: 'OpenClaw' },
+      logger: silentLogger,
+      onMessage,
+    });
+
+    const event = createFetchMessageEvent({
+      eventId: 9745,
+      message: {
+        id: 30857,
+        chatId: 520,
+        authorId: 1,
+        date: '2026-03-19T14:36:03+02:00',
+        text: '[USER=6809]OpenClaw[/USER] привет',
+        isSystem: false,
+        uuid: '',
+        forward: null,
+        params: [],
+        viewedByOthers: false,
+      },
+      chat: {
+        id: 520,
+        dialogId: 'chat520',
+        type: 'chat',
+        name: 'Group Chat',
+        entityType: '',
+        owner: 1,
+        avatar: '',
+        color: '#ab7761',
+      },
+    });
+
+    await handler.handleFetchEvent(event, { ...fetchCtx, botId: 6809 });
+
+    const ctx = onMessage.mock.calls[0][0] as B24MsgContext;
+    expect(ctx.chatId).toBe('chat520');
+    expect(ctx.chatInternalId).toBe('520');
+    expect(ctx.chatName).toBe('Group Chat');
+    expect(ctx.chatType).toBe('chat');
+    expect(ctx.isDm).toBe(false);
+    expect(ctx.isGroup).toBe(true);
+    expect(ctx.wasMentioned).toBe(true);
+  });
+
+  it('does not mark plain group messages as mentions', async () => {
+    const onMessage = vi.fn();
+    handler = new InboundHandler({
+      config: { dmPolicy: 'pairing', botName: 'OpenClaw' },
+      logger: silentLogger,
+      onMessage,
+    });
+
+    const event = createFetchMessageEvent({
+      message: {
+        id: 30858,
+        chatId: 520,
+        authorId: 1,
+        date: '2026-03-19T14:36:10+02:00',
+        text: 'привет',
+        isSystem: false,
+        uuid: '',
+        forward: null,
+        params: [],
+        viewedByOthers: false,
+      },
+      chat: {
+        id: 520,
+        dialogId: 'chat520',
+        type: 'chat',
+        name: 'Group Chat',
+        entityType: '',
+        owner: 1,
+        avatar: '',
+        color: '#ab7761',
+      },
+    });
+
+    await handler.handleFetchEvent(event, fetchCtx);
+
+    const ctx = onMessage.mock.calls[0][0] as B24MsgContext;
+    expect(ctx.wasMentioned).toBe(false);
+  });
+
   it('dispatches webhook message events from JSON body', async () => {
     const onMessage = vi.fn();
     handler = new InboundHandler({
@@ -440,13 +665,58 @@ describe('InboundHandler', () => {
     expect(result).toBe(true);
     expect(onJoinChat).toHaveBeenCalledOnce();
     expect(onJoinChat).toHaveBeenCalledWith({
+      senderId: '1',
       dialogId: '1',
+      chatId: '40985',
       chatType: 'private',
       language: 'ru',
       fetchCtx,
     });
   });
 
+  it('dispatches group join chat events with numeric chat id', async () => {
+    const onJoinChat = vi.fn();
+    handler = new InboundHandler({
+      config: { dmPolicy: 'pairing' },
+      logger: silentLogger,
+      onJoinChat,
+    });
+
+    const event = {
+      eventId: 1006,
+      type: 'ONIMBOTV2JOINCHAT',
+      date: '2026-03-19T14:36:03+02:00',
+      data: {
+        bot: baseBot,
+        dialogId: 'chat520',
+        chat: {
+          id: 520,
+          dialogId: 'chat520',
+          type: 'chat',
+          name: 'Group Chat',
+          entityType: '',
+          owner: 1,
+          avatar: '',
+          color: '#ab7761',
+        },
+        user: baseUser,
+        language: 'ru',
+      },
+    };
+
+    const result = await handler.handleFetchEvent(event as never, fetchCtx);
+    expect(result).toBe(true);
+    expect(onJoinChat).toHaveBeenCalledOnce();
+    expect(onJoinChat).toHaveBeenCalledWith({
+      senderId: '1',
+      dialogId: 'chat520',
+      chatId: '520',
+      chatType: 'chat',
+      language: 'ru',
+      fetchCtx,
+    });
+  });
+
   it('dispatches command events', async () => {
     const onCommand = vi.fn();
     handler = new InboundHandler({
@@ -504,6 +774,7 @@ describe('InboundHandler', () => {
       commandText: '/help topic',
       senderId: '1',
       dialogId: '1',
+      chatId: '40985',
       chatType: 'P',
       messageId: '490667',
       language: 'ru',
@@ -555,6 +826,7 @@ describe('InboundHandler', () => {
       commandText: '/status',
       senderId: '1',
       dialogId: '1',
+      chatId: '40985',
       chatType: 'P',
       messageId: '1004',
       language: 'ru',
@@ -562,6 +834,71 @@ describe('InboundHandler', () => {
     });
   });
 
+  it('dispatches group command events with numeric chat id', async () => {
+    const onCommand = vi.fn();
+    handler = new InboundHandler({
+      config: { dmPolicy: 'pairing' },
+      logger: silentLogger,
+      onCommand,
+    });
+
+    const event = {
+      eventId: 1007,
+      type: 'ONIMBOTV2COMMANDADD',
+      date: '2026-03-19T14:36:03+02:00',
+      data: {
+        bot: baseBot,
+        command: {
+          id: 56,
+          command: '/help',
+          params: '',
+          context: 'textarea',
+        },
+        message: {
+          id: 30857,
+          chatId: 520,
+          authorId: 1,
+          date: '2026-03-19T14:36:03+02:00',
+          text: '/help',
+          isSystem: false,
+          uuid: '',
+          forward: null,
+          params: [],
+          viewedByOthers: false,
+        },
+        chat: {
+          id: 520,
+          dialogId: 'chat520',
+          type: 'chat',
+          name: 'Group Chat',
+          entityType: '',
+          owner: 1,
+          avatar: '',
+          color: '#ab7761',
+        },
+        user: baseUser,
+        language: 'ru',
+      },
+    };
+
+    const result = await handler.handleFetchEvent(event as never, fetchCtx);
+    expect(result).toBe(true);
+    expect(onCommand).toHaveBeenCalledOnce();
+    expect(onCommand).toHaveBeenCalledWith({
+      commandId: 56,
+      commandName: 'help',
+      commandParams: '',
+      commandText: '/help',
+      senderId: '1',
+      dialogId: 'chat520',
+      chatId: '520',
+      chatType: 'chat',
+      messageId: '30857',
+      language: 'ru',
+      fetchCtx,
+    });
+  });
+
   it('builds command text from command payload instead of message text', async () => {
     const onCommand = vi.fn();
     handler = new InboundHandler({
@@ -619,6 +956,7 @@ describe('InboundHandler', () => {
       commandText: '/status',
       senderId: '1',
       dialogId: '1',
+      chatId: '40985',
       chatType: 'P',
       messageId: '490668',
       language: 'ru',

package/tests/polling-service.test.ts

@@ -74,4 +74,42 @@ describe('PollingService', () => {
     expect(onEvent).toHaveBeenCalledTimes(2);
     expect(state.offset).toBe(11);
   });
+
+  it('passes withUserEvents through to fetch polling', async () => {
+    tempHome = mkdtempSync(join(tmpdir(), 'b24-polling-agent-'));
+    process.env.HOME = tempHome;
+
+    const abortController = new AbortController();
+    const fetchEvents = vi.fn().mockImplementation(async () => {
+      abortController.abort();
+      return {
+        events: [],
+        lastEventId: 0,
+        hasMore: false,
+      };
+    });
+
+    const api = { fetchEvents } as unknown as Bitrix24Api;
+    const service = new PollingService({
+      api,
+      webhookUrl: 'https://test.bitrix24.com/rest/1/token/',
+      bot: { botId: 7, botToken: 'bot_token' },
+      accountId: 'default',
+      pollingIntervalMs: 1,
+      pollingFastIntervalMs: 1,
+      withUserEvents: true,
+      onEvent: vi.fn(),
+      abortSignal: abortController.signal,
+      logger: silentLogger,
+    });
+
+    await service.start();
+
+    expect(fetchEvents).toHaveBeenCalledOnce();
+    expect(fetchEvents).toHaveBeenCalledWith(
+      'https://test.bitrix24.com/rest/1/token/',
+      { botId: 7, botToken: 'bot_token' },
+      { offset: 0, limit: 100, withUserEvents: true },
+    );
+  });
 });