@owlmeans/bot 0.0.0-stage → 0.1.18-rc.2

package/tests/platforms.spec.ts

@@ -0,0 +1,60 @@
+import { describe, expect, test } from 'bun:test'
+import { BOT_PLATFORMS, BotActionKind, BotPlatform, BotReceiveMode, botPlatformHelper } from '../src/index.js'
+
+const ACTIONS = new Set<string>(Object.values(BotActionKind))
+const keysOf = (platform: BotPlatform, pick: (field: { required: boolean, generated?: boolean }) => boolean) =>
+  BOT_PLATFORMS[platform].credentials.filter(pick).map(field => field.key)
+
+describe('BOT_PLATFORMS', () => {
+  test('describes every platform once, its actions all BotActionKinds and never note', () => {
+    expect(Object.keys(BOT_PLATFORMS).sort()).toEqual(Object.values(BotPlatform).sort())
+    for (const platform of Object.values(BotPlatform)) {
+      const descriptor = BOT_PLATFORMS[platform]
+      expect(descriptor.platform).toBe(platform)
+      expect(descriptor.actions.every(action => ACTIONS.has(action))).toBe(true)
+      expect(descriptor.actions).not.toContain(BotActionKind.Note)
+      expect(descriptor.credentials.flatMap(field => field.enables ?? []).every(action => ACTIONS.has(action))).toBe(true)
+      expect(descriptor.receive.length).toBeGreaterThan(0)
+      expect(descriptor.docs.startsWith('https://')).toBe(true)
+    }
+  })
+
+  test('names the credentials each platform requires', () => {
+    expect(keysOf(BotPlatform.Telegram, field => field.required)).toEqual(['token'])
+    expect(keysOf(BotPlatform.WhatsApp, field => field.required)).toEqual(['accessToken', 'phoneNumberId', 'appSecret', 'verifyToken'])
+    expect(keysOf(BotPlatform.WhatsApp, field => field.generated === true)).toEqual(['verifyToken'])
+    expect(keysOf(BotPlatform.Discord, field => field.required)).toEqual(['token', 'applicationId'])
+    expect(keysOf(BotPlatform.Slack, field => field.required)).toEqual(['botToken', 'signingSecret'])
+    expect(keysOf(BotPlatform.Slack, field => !field.required)).toEqual(['userToken'])
+  })
+
+  test('receives as the contract says and is frozen', () => {
+    expect(BOT_PLATFORMS[BotPlatform.Telegram].receive).toEqual([BotReceiveMode.Webhook, BotReceiveMode.Poll])
+    expect(BOT_PLATFORMS[BotPlatform.WhatsApp].receive).toEqual([BotReceiveMode.Webhook])
+    expect(BOT_PLATFORMS[BotPlatform.Discord].receive).toEqual([BotReceiveMode.Gateway])
+    expect(BOT_PLATFORMS[BotPlatform.Slack].receive).toEqual([BotReceiveMode.Webhook])
+    expect(Object.isFrozen(BOT_PLATFORMS) && Object.isFrozen(BOT_PLATFORMS[BotPlatform.Slack].credentials)).toBe(true)
+  })
+})
+
+describe('botPlatformHelper', () => {
+  test('WhatsApp cannot delete, mute or ban; Telegram and Discord moderate fully; note is always supported', () => {
+    for (const kind of [BotActionKind.Delete, BotActionKind.Mute, BotActionKind.Ban]) {
+      expect(botPlatformHelper.supports(BotPlatform.WhatsApp, kind)).toBe(false)
+      expect(botPlatformHelper.supports(BotPlatform.Telegram, kind)).toBe(true)
+      expect(botPlatformHelper.supports(BotPlatform.Discord, kind)).toBe(true)
+    }
+    for (const platform of Object.values(BotPlatform)) {
+      expect(botPlatformHelper.supports(platform, BotActionKind.Note)).toBe(true)
+      expect(botPlatformHelper.supports(platform, BotActionKind.Reply)).toBe(true)
+    }
+  })
+
+  test('Slack deletes only with the admin userToken set', () => {
+    expect(botPlatformHelper.supports(BotPlatform.Slack, BotActionKind.Delete, ['botToken', 'signingSecret'])).toBe(false)
+    expect(botPlatformHelper.supports(BotPlatform.Slack, BotActionKind.Delete, ['botToken', 'signingSecret', 'userToken'])).toBe(true)
+    expect(botPlatformHelper.actionsOf(BotPlatform.Slack, ['userToken']).sort())
+      .toEqual([BotActionKind.Reply, BotActionKind.Send, BotActionKind.React, BotActionKind.Delete, BotActionKind.Note].sort())
+    expect(botPlatformHelper.supports(BotPlatform.Slack, BotActionKind.Mute, ['userToken'])).toBe(false)
+  })
+})

package/tests/protocols.spec.ts

@@ -0,0 +1,80 @@
+import { describe, expect, test } from 'bun:test'
+import { protocols } from '@owlmeans/entrypoint'
+import { RouteMethod } from '@owlmeans/route'
+import { makeBotHookProtocols, makeBotProtocols } from '../src/index.js'
+
+const BASE = 'api:bot:operator'
+const gate = { alias: 'gate:oidc', params: ['operator'] }
+
+describe('makeBotProtocols', () => {
+  const tree = makeBotProtocols({ base: { alias: BASE, path: '/bot/operator' }, guards: 'guard:default', gates: gate })
+
+  test('declares exactly the leaves of the contract, each alias derived from the base alias', () => {
+    const declared = protocols(tree as never).map(protocol => protocol.alias)
+
+    expect(declared.sort()).toEqual([
+      BASE,
+      `${BASE}:connection:list`, `${BASE}:connection:save`, `${BASE}:connection:verify`,
+      `${BASE}:connection:remove`, `${BASE}:connection:simulate`,
+      `${BASE}:rule:list`, `${BASE}:rule:save`, `${BASE}:rule:remove`,
+      `${BASE}:activity:list`,
+    ].sort())
+  })
+
+  test('every leaf has its method and path, hanging under the base', () => {
+    const routes = [
+      [tree.connection.list, RouteMethod.GET, '/connections'],
+      [tree.connection.save, RouteMethod.POST, '/connections'],
+      [tree.connection.verify, RouteMethod.POST, '/connections/:id/verify'],
+      [tree.connection.remove, RouteMethod.DELETE, '/connections/:id'],
+      [tree.connection.simulate, RouteMethod.POST, '/connections/:id/simulate'],
+      [tree.rule.list, RouteMethod.GET, '/rules'],
+      [tree.rule.save, RouteMethod.POST, '/rules'],
+      [tree.rule.remove, RouteMethod.DELETE, '/rules/:id'],
+      [tree.activity.list, RouteMethod.GET, '/activity'],
+    ] as const
+
+    for (const [leaf, method, path] of routes) {
+      expect([leaf.alias, leaf.route.route.method, leaf.route.route.path, leaf.route.route.parent])
+        .toEqual([leaf.alias, method, path, BASE])
+    }
+    expect(tree.connection.save.contract?.requestSchemas.body).toBeDefined()
+    expect(tree.connection.simulate.contract?.requestSchemas.params).toBeDefined()
+    expect(tree.activity.list.contract?.requestSchemas.query).toBeDefined()
+  })
+
+  test('the guards and the gate sit on the base alone; the tree is frozen', () => {
+    expect(tree.base.guards).toEqual(['guard:default'])
+    expect(tree.base.gate).toEqual(gate)
+    expect(tree.base.route.route.path).toBe('/bot/operator')
+    expect(tree.rule.list.guards).toEqual([])
+    expect(tree.rule.list.gate).toBeUndefined()
+    expect(Object.isFrozen(tree) && Object.isFrozen(tree.connection) && Object.isFrozen(tree.rule.save)).toBe(true)
+  })
+
+  test('two mounts are two alias families, and parent and service reach the base', () => {
+    const member = makeBotProtocols({ base: { alias: 'api:bot:member', path: '/bot/member', parent: 'api', service: 'api' } })
+
+    expect(member.connection.list.alias).toBe('api:bot:member:connection:list')
+    expect(member.base.route.route).toMatchObject({ parent: 'api', service: 'api' })
+    expect(member.base.guards).toEqual([])
+  })
+})
+
+describe('makeBotHookProtocols', () => {
+  const hook = makeBotHookProtocols({ base: { alias: 'api:bot:hook', path: '/bot/hook' } })
+
+  test('receive is POST and challenge GET, both at /:platform/:connection', () => {
+    expect(protocols(hook as never).map(protocol => protocol.alias).sort())
+      .toEqual(['api:bot:hook', 'api:bot:hook:challenge', 'api:bot:hook:receive'])
+    expect(hook.receive.route.route).toMatchObject({ method: RouteMethod.POST, path: '/:platform/:connection', parent: 'api:bot:hook' })
+    expect(hook.challenge.route.route).toMatchObject({ method: RouteMethod.GET, path: '/:platform/:connection', parent: 'api:bot:hook' })
+  })
+
+  test('carries no guard and no gate anywhere — the platform signs', () => {
+    for (const protocol of protocols(hook as never)) {
+      expect([protocol.alias, protocol.guards, protocol.gate]).toEqual([protocol.alias, [], undefined])
+    }
+    expect(hook.receive.contract?.requestSchemas.body).toBeUndefined()
+  })
+})

package/tests/rule.spec.ts

@@ -0,0 +1,129 @@
+import { describe, expect, test } from 'bun:test'
+import { BOT_KEYWORD_MAX, BOT_KEYWORDS_MAX, BotMatchMode, BotRuleAction, botRuleHelper, type BotRule } from '../src/index.js'
+
+const at = '2026-10-26T10:00:00.000Z'
+
+const rule = (id: string, keywords: string[], extra: Partial<BotRule> = {}): BotRule => ({
+  id,
+  scope: 'org-1',
+  connection: null,
+  name: id,
+  keywords,
+  mode: BotMatchMode.Word,
+  action: BotRuleAction.Delete,
+  enabled: true,
+  order: 0,
+  createdAt: at,
+  updatedAt: at,
+  ...extra,
+})
+
+const ids = (text: string, rules: BotRule[]): string[] => botRuleHelper.match(text, rules).map(found => found.rule.id)
+
+describe('botRuleHelper.match — word mode', () => {
+  test('matches whole words only, case-insensitively and across punctuation', () => {
+    const spam = rule('spam', ['casino'])
+
+    expect(ids('Visit the CASINO!', [spam])).toEqual(['spam'])
+    expect(ids('casino, now', [spam])).toEqual(['spam'])
+    expect(ids('casinos are fun', [spam])).toEqual([])
+    expect(ids('megacasino', [spam])).toEqual([])
+  })
+
+  test('a multi-word keyword is a phrase of consecutive words', () => {
+    const offer = rule('offer', ['free money'])
+
+    expect(ids('Get FREE   money now', [offer])).toEqual(['offer'])
+    expect(ids('free—money', [offer])).toEqual(['offer'])
+    expect(ids('money for free', [offer])).toEqual([])
+    expect(ids('free real money', [offer])).toEqual([])
+  })
+
+  test('is Unicode-aware: Cyrillic, accents, compatibility forms and the German sharp s', () => {
+    expect(ids('Купите СПАМ сейчас', [rule('ru', ['спам'])])).toEqual(['ru'])
+    expect(ids('ёлка', [rule('yo', ['ЁЛКА'])])).toEqual(['yo'])
+    expect(ids('Un café, por favor', [rule('es', ['CAFÉ'])])).toEqual(['es'])
+    // Accents are kept: "cafe" is not "café".
+    expect(ids('Un café', [rule('plain', ['cafe'])])).toEqual([])
+    // NFKC: the full-width form and the ligature fold onto plain letters; NFD text onto NFC.
+    expect(ids('ＣＡＳＩＮＯ night', [rule('wide', ['casino'])])).toEqual(['wide'])
+    expect(ids('finance tips', [rule('lig', ['finance'])])).toEqual(['lig'])
+    expect(ids('café au lait', [rule('nfd', ['café'])])).toEqual(['nfd'])
+    expect(ids('STRASSE gesperrt', [rule('de', ['straße'])])).toEqual(['de'])
+  })
+
+  test('a keyword with no letters or digits never matches a word', () => {
+    expect(ids('!!! now', [rule('bang', ['!!!'])])).toEqual([])
+  })
+})
+
+describe('botRuleHelper.match — contains mode', () => {
+  test('matches a folded substring, inside words too, with whitespace runs collapsed', () => {
+    const inside = rule('inside', ['casino'], { mode: BotMatchMode.Contains })
+    const punct = rule('punct', ['!!!'], { mode: BotMatchMode.Contains })
+    const spaced = rule('spaced', ['free  money'], { mode: BotMatchMode.Contains })
+
+    expect(ids('MEGACASINO.com', [inside])).toEqual(['inside'])
+    expect(ids('wow!!! ok', [punct])).toEqual(['punct'])
+    expect(ids('get free\n money', [spaced])).toEqual(['spaced'])
+    expect(ids('no match here', [inside, punct, spaced])).toEqual([])
+  })
+})
+
+describe('botRuleHelper.match — groups', () => {
+  test('skips disabled rules and answers [] for empty text', () => {
+    const off = rule('off', ['spam'], { enabled: false })
+
+    expect(ids('spam', [off])).toEqual([])
+    expect(ids('   ', [rule('on', ['spam'])])).toEqual([])
+  })
+
+  test('orders matches by rule order, ties keeping the given order', () => {
+    const rules = [
+      rule('third', ['spam'], { order: 3 }),
+      rule('first', ['spam'], { order: 1 }),
+      rule('tie-a', ['spam'], { order: 2 }),
+      rule('tie-b', ['spam'], { order: 2 }),
+    ]
+
+    expect(ids('spam', rules)).toEqual(['first', 'tie-a', 'tie-b', 'third'])
+  })
+
+  test('reports every group a message matches, each with its own matched keywords as stored', () => {
+    const abuse = rule('abuse', ['Idiot', 'stupid', 'moron'], { order: 1, action: BotRuleAction.Warn })
+    const hours = rule('hours', ['opening hours', 'open'], { order: 2, action: BotRuleAction.Reply })
+    const quiet = rule('quiet', ['delivery'], { order: 0 })
+    const found = botRuleHelper.match('You idiot, what are the OPENING hours? stupid!', [hours, quiet, abuse])
+
+    expect(found.map(match => [match.rule.id, match.keywords])).toEqual([
+      ['abuse', ['Idiot', 'stupid']],
+      ['hours', ['opening hours']],
+    ])
+  })
+})
+
+describe('botRuleHelper.normalizeKeywords', () => {
+  test('trims, collapses inner whitespace, drops empties and folded duplicates keeping the first spelling', () => {
+    expect(botRuleHelper.normalizeKeywords(['  Free   money ', '', '   ', 'free MONEY', 'Спам', 'СПАМ', 'café']))
+      .toEqual(['Free money', 'Спам', 'café'])
+  })
+
+  test('caps the keyword length (in code points) and the list size', () => {
+    const long = '😀'.repeat(BOT_KEYWORD_MAX + 10)
+    const [capped] = botRuleHelper.normalizeKeywords([long])
+    const many = botRuleHelper.normalizeKeywords(Array.from({ length: BOT_KEYWORDS_MAX + 5 }, (_, n) => `kw${n}`))
+
+    expect(Array.from(capped)).toHaveLength(BOT_KEYWORD_MAX)
+    expect(many).toHaveLength(BOT_KEYWORDS_MAX)
+    expect(many[0]).toBe('kw0')
+  })
+})
+
+describe('botRuleHelper.appliesTo', () => {
+  test('a scope-wide rule applies to every connection, an own one to its connection only', () => {
+    expect(botRuleHelper.appliesTo({ connection: null }, 'c1')).toBe(true)
+    expect(botRuleHelper.appliesTo({}, 'c1')).toBe(true)
+    expect(botRuleHelper.appliesTo({ connection: 'c1' }, 'c1')).toBe(true)
+    expect(botRuleHelper.appliesTo({ connection: 'c2' }, 'c1')).toBe(false)
+  })
+})

package/tests/schemas.spec.ts

@@ -0,0 +1,102 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  BOT_ACTIVITY_LIMIT_MAX, BOT_KEYWORDS_MAX, BotActivityQuerySchema, BotChallengeQuerySchema, BotConnectionInputSchema,
+  BotHookParamsSchema, BotIdParamsSchema, BotRuleInputSchema, BotRuleListQuerySchema, BotSimulateInputSchema,
+} from '../src/index.js'
+import { validatorOf } from './context.js'
+
+describe('connection input', () => {
+  const valid = validatorOf(BotConnectionInputSchema)
+
+  test('accepts a minimal and a full input, credentials write-only and clearable', () => {
+    expect(valid({ platform: 'telegram', label: 'Community' })).toBe(true)
+    expect(valid({
+      id: 'conn_1', platform: 'slack', label: 'Office', transport: 'mock', enabled: true,
+      credentials: { botToken: 'xoxb-1', signingSecret: 's', userToken: '' },
+    })).toBe(true)
+  })
+
+  test('refuses an unknown platform, an empty label, a stray key and a malformed credential key', () => {
+    expect(valid({ platform: 'viber', label: 'x' })).toBe(false)
+    expect(valid({ platform: 'telegram', label: '' })).toBe(false)
+    expect(valid({ platform: 'telegram', label: 'x', scope: 'org-1' })).toBe(false)
+    expect(valid({ platform: 'telegram', label: 'x', credentials: { 'bad key': 'v' } })).toBe(false)
+    expect(valid({ platform: 'telegram', label: 'x', credentials: { token: { value: 'v' } } })).toBe(false)
+  })
+})
+
+describe('rule input', () => {
+  const valid = validatorOf(BotRuleInputSchema)
+
+  test('accepts a rule with keywords and an action, scope-wide (null) or bound to a connection', () => {
+    expect(valid({ name: 'Spam', keywords: ['casino'], action: 'delete' })).toBe(true)
+    expect(valid({
+      id: 'r1', connection: null, name: 'Hours', keywords: ['open', 'hours'], mode: 'contains',
+      action: 'reply', reply: 'We open at 9.', instruction: 'Be brief.', enabled: false, order: 2.5,
+    })).toBe(true)
+    expect(valid({ connection: 'conn_1', name: 'x', keywords: ['k'], action: 'agent' })).toBe(true)
+  })
+
+  test('refuses no keywords, too many, an unknown action or mode, and a missing name', () => {
+    expect(valid({ name: 'x', keywords: [], action: 'delete' })).toBe(false)
+    expect(valid({ name: 'x', keywords: Array.from({ length: BOT_KEYWORDS_MAX + 1 }, (_, n) => `k${n}`), action: 'delete' })).toBe(false)
+    expect(valid({ name: 'x', keywords: ['k'], action: 'kick' })).toBe(false)
+    expect(valid({ name: 'x', keywords: ['k'], action: 'delete', mode: 'regex' })).toBe(false)
+    expect(valid({ keywords: ['k'], action: 'delete' })).toBe(false)
+  })
+})
+
+describe('simulate input', () => {
+  const valid = validatorOf(BotSimulateInputSchema)
+
+  test('accepts text with optional partial chat, sender and reply target — platform ids unconstrained', () => {
+    expect(valid({ text: 'hello' })).toBe(true)
+    expect(valid({
+      text: 'buy now', chat: { id: '-1001234', kind: 'group', space: 'T123' },
+      sender: { id: '42', username: 'member' }, replyTo: { id: '17', text: 'earlier' },
+    })).toBe(true)
+  })
+
+  test('refuses empty text, an unknown chat kind and a reply target without id', () => {
+    expect(valid({ text: '' })).toBe(false)
+    expect(valid({ text: 'x', chat: { kind: 'forum' } })).toBe(false)
+    expect(valid({ text: 'x', replyTo: { text: 'earlier' } })).toBe(false)
+  })
+})
+
+describe('params and queries', () => {
+  test('ids are path-safe', () => {
+    const valid = validatorOf(BotIdParamsSchema)
+
+    expect(valid({ id: 'conn_1' })).toBe(true)
+    expect(valid({ id: '../etc' })).toBe(false)
+    expect(valid({ id: '' })).toBe(false)
+  })
+
+  test('the activity limit is a whole number from 1 to the cap, coerced from a query string', () => {
+    const valid = validatorOf(BotActivityQuerySchema)
+
+    expect(valid({})).toBe(true)
+    expect(valid({ connection: 'conn_1', limit: '50' })).toBe(true)
+    expect(valid({ limit: BOT_ACTIVITY_LIMIT_MAX })).toBe(true)
+    expect(valid({ limit: BOT_ACTIVITY_LIMIT_MAX + 1 })).toBe(false)
+    expect(valid({ limit: 0 })).toBe(false)
+    expect(valid({ limit: 1.5 })).toBe(false)
+  })
+
+  test('the rule list filters by connection only', () => {
+    const valid = validatorOf(BotRuleListQuerySchema)
+
+    expect(valid({ connection: 'conn_1' })).toBe(true)
+    expect(valid({ scope: 'org-1' })).toBe(false)
+  })
+
+  test('the hook names a known platform and a path-safe connection; its handshake query stays open', () => {
+    const params = validatorOf(BotHookParamsSchema)
+    const query = validatorOf(BotChallengeQuerySchema)
+
+    expect(params({ platform: 'whatsapp', connection: 'conn_1' })).toBe(true)
+    expect(params({ platform: 'viber', connection: 'conn_1' })).toBe(false)
+    expect(query({ 'hub.mode': 'subscribe', 'hub.verify_token': 't', 'hub.challenge': '123', other: 'x' })).toBe(true)
+  })
+})

package/tests/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": [
+    "@owlmeans/dep-config/tsconfig.base.json",
+    "@owlmeans/dep-config/tsconfig.node.json"
+  ],
+  "compilerOptions": {
+    "types": ["bun"],
+    "rootDir": "../",
+    "noEmit": true
+  },
+  "include": ["./**/*", "../src/**/*"]
+}

package/tests/update.spec.ts

@@ -0,0 +1,38 @@
+import { describe, expect, test } from 'bun:test'
+import {
+  BotChatKind, BotMatchMode, BotPlatform, BotRuleAction, BotUpdateKind, botCommandHelper, botRuleHelper,
+  type BotMessageRef, type BotRule, type BotUpdate,
+} from '../src/index.js'
+
+const at = '2026-10-26T10:00:00.000Z'
+
+const rules: BotRule[] = [
+  { id: 'r-other', scope: 'org-1', connection: 'conn_2', name: 'Other', keywords: ['raid'], mode: BotMatchMode.Word, action: BotRuleAction.Ban, enabled: true, order: 0, createdAt: at, updatedAt: at },
+  { id: 'r-all', scope: 'org-1', connection: null, name: 'Raid', keywords: ['raid'], mode: BotMatchMode.Word, action: BotRuleAction.Mute, enabled: true, order: 1, createdAt: at, updatedAt: at },
+]
+
+describe('a normalized update, assembled the way a runtime does', () => {
+  test('its matches come from the rules that apply to its connection, and its message ref alone addresses the message', () => {
+    const ref: BotMessageRef = { chat: 'ch-1', id: 'm-1', thread: 't-1', space: 'guild-9' }
+    const text = '/report@ModBot RAID incoming'
+    const update: BotUpdate = {
+      id: 'u-1',
+      connection: 'conn_1',
+      scope: 'org-1',
+      platform: BotPlatform.Discord,
+      kind: BotUpdateKind.Command,
+      chat: { id: 'ch-1', kind: BotChatKind.Group, space: 'guild-9' },
+      sender: { id: 'user-5', username: 'member' },
+      message: { ref, text, date: at },
+      command: botCommandHelper.parse(text, 'ModBot') ?? undefined,
+      addressed: true,
+      matches: botRuleHelper.match(text, rules.filter(rule => botRuleHelper.appliesTo(rule, 'conn_1'))),
+      receivedAt: at,
+    }
+
+    expect(update.command).toEqual({ name: 'report', args: 'RAID incoming' })
+    expect(update.matches.map(found => [found.rule.id, found.keywords])).toEqual([['r-all', ['raid']]])
+    // A Discord timeout needs the guild: the reference carries it, so nothing else is consulted.
+    expect(update.message?.ref).toEqual({ chat: 'ch-1', id: 'm-1', thread: 't-1', space: 'guild-9' })
+  })
+})

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": ["@owlmeans/dep-config/tsconfig.base.json"],
+  "compilerOptions": {
+    "rootDir": "./src/",
+    "outDir": "./build/"
+  },
+  "exclude": ["./dist/**/*", "./build/**/*", "./tests/**/*", "./*.ts"]
+}