@owlmeans/bot 0.1.18-rc.2 → 0.1.18

package/src/helpers/text.ts

@@ -0,0 +1,91 @@
+import { BotTextMatch } from '../consts.js'
+import { BOT_PHRASE_SEPARATOR_PATTERN, BOT_SPACE_PATTERN, BOT_TOKEN_PATTERN } from '../consts.local.js'
+import type { BotTextHelper } from './text/types.js'
+
+export const createBotTextHelper = (): BotTextHelper => {
+  /**
+   * NFKC, then a case fold: upper-casing first maps what lower-casing alone keeps apart (`ß` → `SS`
+   * → `ss`, final `ς` → `Σ` → `σ`), and NFKC again recomposes what the case mapping decomposed.
+   */
+  const fold = (text: string): string =>
+    typeof text === 'string' ? text.normalize('NFKC').toUpperCase().toLowerCase().normalize('NFKC') : ''
+
+  const tokensOf = (text: string): string[] => fold(text).match(BOT_TOKEN_PATTERN) ?? []
+
+  /** The folded text with whitespace runs collapsed — the `contains` form and the dedupe key. */
+  const spacedOf = (text: string): string => fold(text).replace(BOT_SPACE_PATTERN, ' ').trim()
+
+  const hasPhrase = (tokens: readonly string[], phrase: readonly string[]): boolean => {
+    for (let at = 0; at + phrase.length <= tokens.length; at++) {
+      if (phrase.every((token, offset) => tokens[at + offset] === token)) {
+        return true
+      }
+    }
+    return false
+  }
+
+  const matched = (text: string, phrases: readonly string[], mode: BotTextMatch = BotTextMatch.Word): string[] => {
+    if (typeof text !== 'string' || text.trim() === '' || !Array.isArray(phrases)) {
+      return []
+    }
+    // Folded once per text, never per phrase.
+    let tokens: string[] | undefined
+    let spaced: string | undefined
+
+    const found = (phrase: string): boolean => {
+      if (mode === BotTextMatch.Contains) {
+        const needle = spacedOf(phrase)
+        spaced ??= spacedOf(text)
+        return needle !== '' && spaced.includes(needle)
+      }
+      const words = tokensOf(phrase)
+      tokens ??= tokensOf(text)
+      return words.length > 0 && hasPhrase(tokens, words)
+    }
+
+    const seen = new Set<string>()
+    const result: string[] = []
+    for (const phrase of phrases) {
+      if (typeof phrase !== 'string') {
+        continue
+      }
+      const key = spacedOf(phrase)
+      if (key === '' || seen.has(key)) {
+        continue
+      }
+      seen.add(key)
+      if (found(phrase)) {
+        result.push(phrase)
+      }
+    }
+
+    return result
+  }
+
+  const phrasesOf = (input: string | readonly string[]): string[] => {
+    const items: readonly unknown[] = typeof input === 'string' ? [input] : Array.isArray(input) ? input : []
+    const seen = new Set<string>()
+    const result: string[] = []
+
+    for (const item of items) {
+      if (typeof item !== 'string') {
+        continue
+      }
+      for (const part of item.split(BOT_PHRASE_SEPARATOR_PATTERN)) {
+        const phrase = part.replace(BOT_SPACE_PATTERN, ' ').trim()
+        const key = spacedOf(phrase)
+        if (key === '' || seen.has(key)) {
+          continue
+        }
+        seen.add(key)
+        result.push(phrase)
+      }
+    }
+
+    return result
+  }
+
+  return { fold, tokensOf, matched, phrasesOf }
+}
+
+export const botTextHelper = createBotTextHelper()

package/src/protocols/types.ts

@@ -2,7 +2,7 @@ import type { EntrypointProtocol, OpenRequest, OpenValue } from '@owlmeans/entry
 import type { RouteParent } from '@owlmeans/route'
 import type { BotPlatform } from '../consts.js'
 import type {
-  BotActivity, BotConnection, BotConnectionInput, BotRule, BotRuleInput, BotSimulateInput, BotSimulateResult,
+  BotActivity, BotConnection, BotConnectionInput, BotSimulateInput, BotSimulateResult,
 } from '../types.js'
 
 /** Where a bot tree mounts. Every leaf alias derives from `alias` (`<alias>:connection:list` …). */
@@ -32,7 +32,7 @@ export interface BotHookProtocolOptions {
   base: BotBaseOptions
 }
 
-/** `:id` of a connection or a rule. */
+/** `:id` of a connection. */
 export interface BotIdParams {
   id: string
 }
@@ -41,11 +41,6 @@ export interface BotRemoveResult {
   id: string
 }
 
-export interface BotRuleListQuery {
-  /** Rules of this connection plus the scope-wide ones; every rule of the scope when absent. */
-  connection?: string
-}
-
 export interface BotActivityQuery {
   connection?: string
   /** 1 … `BOT_ACTIVITY_LIMIT_MAX`; `BOT_ACTIVITY_LIMIT_DEFAULT` when absent. */
@@ -88,11 +83,6 @@ export interface BotProtocols {
     /** Mock transport only — a live connection answers `BotTransportMismatch` (409). */
     simulate: EntrypointProtocol<{ params: BotIdParams, body: BotSimulateInput }, BotSimulateResult>
   }
-  rule: {
-    list: EntrypointProtocol<{ query: BotRuleListQuery }, BotRule[]>
-    save: EntrypointProtocol<{ body: BotRuleInput }, BotRule>
-    remove: EntrypointProtocol<{ params: BotIdParams }, BotRemoveResult>
-  }
   activity: {
     /** Newest first. */
     list: EntrypointProtocol<{ query: BotActivityQuery }, BotActivity[]>

package/src/protocols.ts

@@ -2,16 +2,14 @@ import { contract, openProtocol, protocol, typed } from '@owlmeans/entrypoint'
 import { backend, route, RouteMethod, type RouteOptions } from '@owlmeans/route'
 import {
   BotActivityQuerySchema, BotChallengeQuerySchema, BotConnectionInputSchema, BotHookParamsSchema, BotIdParamsSchema,
-  BotRuleInputSchema, BotRuleListQuerySchema, BotSimulateInputSchema,
+  BotSimulateInputSchema,
 } from './schemas.js'
 import { botAliasUtils } from './utils/aliases.js'
 import type {
   BotActivityQuery, BotBaseOptions, BotChallengeQuery, BotHookParams, BotHookPayload, BotHookProtocolOptions,
-  BotHookProtocols, BotHookReply, BotIdParams, BotProtocolOptions, BotProtocols, BotRemoveResult, BotRuleListQuery,
+  BotHookProtocols, BotHookReply, BotIdParams, BotProtocolOptions, BotProtocols, BotRemoveResult,
 } from './protocols/types.js'
-import type {
-  BotActivity, BotConnection, BotConnectionInput, BotRule, BotRuleInput, BotSimulateInput, BotSimulateResult,
-} from './types.js'
+import type { BotActivity, BotConnection, BotConnectionInput, BotSimulateInput, BotSimulateResult } from './types.js'
 
 const mountOf = (base: BotBaseOptions): Partial<RouteOptions> => ({
   ...(base.parent != null ? { parent: base.parent } : {}),
@@ -19,7 +17,7 @@ const mountOf = (base: BotBaseOptions): Partial<RouteOptions> => ({
 })
 
 /**
- * Declare one managing surface of the bot — connections, rules, activity — as an immutable tree a
+ * Declare one managing surface of the bot — connections and activity — as an immutable tree a
  * server binds and a client calls.
  *
  * Every leaf hangs under ONE base that carries the guards and the gate, so they cannot drift apart;
@@ -64,21 +62,6 @@ export const makeBotProtocols = (opts: BotProtocolOptions): BotProtocols => {
       ),
     }),
 
-    rule: Object.freeze({
-      list: protocol(
-        leaf(aliases.rule.list, '/rules', RouteMethod.GET),
-        contract.request({ query: typed<BotRuleListQuery>(BotRuleListQuerySchema) }, typed<BotRule[]>())
-      ),
-      save: protocol(
-        leaf(aliases.rule.save, '/rules', RouteMethod.POST),
-        contract.request({ body: typed<BotRuleInput>(BotRuleInputSchema) }, typed<BotRule>())
-      ),
-      remove: protocol(
-        leaf(aliases.rule.remove, '/rules/:id', RouteMethod.DELETE),
-        contract.request({ params: typed<BotIdParams>(BotIdParamsSchema) }, typed<BotRemoveResult>())
-      ),
-    }),
-
     activity: Object.freeze({
       list: protocol(
         leaf(aliases.activity.list, '/activity', RouteMethod.GET),

package/src/schemas.ts

@@ -1,19 +1,15 @@
 import type { JSONSchemaType } from 'ajv'
 import {
   BOT_ACTIVITY_LIMIT_MAX, BOT_CREDENTIAL_KEY_PATTERN, BOT_CREDENTIAL_MAX, BOT_CREDENTIALS_MAX, BOT_ID_MAX,
-  BOT_ID_PATTERN, BOT_INSTRUCTION_MAX, BOT_KEYWORD_MAX, BOT_KEYWORDS_MAX, BOT_LABEL_MAX, BOT_NAME_MAX,
-  BOT_REPLY_MAX, BOT_RULE_NAME_MAX, BOT_TEXT_MAX, BotChatKind, BotMatchMode, BotPlatform, BotRuleAction,
-  BotTransport,
+  BOT_ID_PATTERN, BOT_LABEL_MAX, BOT_NAME_MAX, BOT_TEXT_MAX, BotChatKind, BotPlatform, BotTransport,
 } from './consts.js'
-import type {
-  BotActivityQuery, BotChallengeQuery, BotHookParams, BotIdParams, BotRuleListQuery,
-} from './protocols/types.js'
-import type { BotConnectionInput, BotRuleInput, BotSimulateInput } from './types.js'
+import type { BotActivityQuery, BotChallengeQuery, BotHookParams, BotIdParams } from './protocols/types.js'
+import type { BotConnectionInput, BotSimulateInput } from './types.js'
 
 /**
  * Hand-written request schemas, cast: an optional key is OPTIONAL, never `null` — the wire matches the
- * TypeScript type exactly. The only nullable is a rule's `connection`, whose `null` means "every
- * connection of the scope". `additionalProperties: false` everywhere a client writes.
+ * TypeScript type exactly, and nothing is nullable. `additionalProperties: false` everywhere a client
+ * writes.
  */
 const cast = <T>(schema: object): JSONSchemaType<T> => schema as unknown as JSONSchemaType<T>
 
@@ -51,29 +47,6 @@ export const BotConnectionInputSchema = cast<BotConnectionInput>({
   additionalProperties: false,
 })
 
-export const BotRuleInputSchema = cast<BotRuleInput>({
-  type: 'object',
-  properties: {
-    id: Id,
-    connection: { ...Id, nullable: true },
-    name: { type: 'string', minLength: 1, maxLength: BOT_RULE_NAME_MAX },
-    keywords: {
-      type: 'array',
-      items: { type: 'string', minLength: 1, maxLength: BOT_KEYWORD_MAX },
-      minItems: 1,
-      maxItems: BOT_KEYWORDS_MAX,
-    },
-    mode: { type: 'string', enum: Object.values(BotMatchMode) },
-    action: { type: 'string', enum: Object.values(BotRuleAction) },
-    reply: { type: 'string', maxLength: BOT_REPLY_MAX },
-    instruction: { type: 'string', maxLength: BOT_INSTRUCTION_MAX },
-    enabled: { type: 'boolean' },
-    order: { type: 'number' },
-  },
-  required: ['name', 'keywords', 'action'],
-  additionalProperties: false,
-})
-
 export const BotSimulateInputSchema = cast<BotSimulateInput>({
   type: 'object',
   properties: {
@@ -115,13 +88,6 @@ export const BotSimulateInputSchema = cast<BotSimulateInput>({
   additionalProperties: false,
 })
 
-export const BotRuleListQuerySchema = cast<BotRuleListQuery>({
-  type: 'object',
-  properties: { connection: Id },
-  required: [],
-  additionalProperties: false,
-})
-
 /** A query string arrives as text: the server coerces `limit` before this checks it. */
 export const BotActivityQuerySchema = cast<BotActivityQuery>({
   type: 'object',

package/src/types.ts

@@ -1,6 +1,5 @@
 import type {
-  BotActionKind, BotChatKind, BotConnectionStatus, BotMatchMode, BotPlatform, BotReceiveMode, BotRuleAction,
-  BotTransport, BotUpdateKind,
+  BotActionKind, BotChatKind, BotConnectionStatus, BotPlatform, BotReceiveMode, BotTransport, BotUpdateKind,
 } from './consts.js'
 
 /** One credential a platform needs — what the panel draws an input for. */
@@ -119,45 +118,6 @@ export interface BotCommand {
   args: string
 }
 
-/** A keyword group: the keywords and what the bot does with a message that matches them. */
-export interface BotRule {
-  id: string
-  scope: string
-  /** One connection only; `null` or absent applies to every connection of the scope. */
-  connection?: string | null
-  name: string
-  keywords: string[]
-  mode: BotMatchMode
-  action: BotRuleAction
-  /** The fixed text of `reply` / `warn` (and the confirmation of `record`). */
-  reply?: string
-  /** What the product's agent is told for this group. */
-  instruction?: string
-  enabled: boolean
-  order: number
-  createdAt: string
-  updatedAt: string
-}
-
-export interface BotRuleInput {
-  id?: string
-  connection?: string | null
-  name: string
-  keywords: string[]
-  mode?: BotMatchMode
-  action: BotRuleAction
-  reply?: string
-  instruction?: string
-  enabled?: boolean
-  order?: number
-}
-
-/** A rule a message matched, with the rule's keywords (as stored) that matched it. */
-export interface BotMatch {
-  rule: BotRule
-  keywords: string[]
-}
-
 /** A normalized inbound update, as a handler receives it. */
 export interface BotUpdate {
   id: string
@@ -171,8 +131,6 @@ export interface BotUpdate {
   command?: BotCommand
   /** A direct message, a mention of the bot, or a reply to it. */
   addressed: boolean
-  /** Enabled rules of the scope (and connection) the text matches, by order. */
-  matches: BotMatch[]
   receivedAt: string
   raw?: unknown
 }
@@ -195,8 +153,12 @@ export interface BotActivity {
   action: BotActionKind
   target?: BotActivityTarget
   text?: string
-  /** The rule it followed. */
-  rule?: string
+  /**
+   * An opaque reference the acting handler passed (`{ ref }` on the action) — e.g. the id of the
+   * application's own record it followed, such as the keyword group a message matched. The bot
+   * packages never read it.
+   */
+  ref?: string
   ok: boolean
   /** Why it failed, as a short sentence a person reads. */
   error?: string

package/src/utils/aliases/types.ts

@@ -8,7 +8,6 @@ export interface BotAliases {
     readonly remove: string
     readonly simulate: string
   }
-  readonly rule: { readonly list: string, readonly save: string, readonly remove: string }
   readonly activity: { readonly list: string }
 }
 

package/src/utils/aliases.ts

@@ -10,11 +10,6 @@ export const createBotAliasUtils = (): BotAliasUtils => {
       remove: `${base}:connection:remove`,
       simulate: `${base}:connection:simulate`,
     }),
-    rule: Object.freeze({
-      list: `${base}:rule:list`,
-      save: `${base}:rule:save`,
-      remove: `${base}:rule:remove`,
-    }),
     activity: Object.freeze({ list: `${base}:activity:list` }),
   })
 

package/tests/protocols.spec.ts

@@ -16,7 +16,6 @@ describe('makeBotProtocols', () => {
       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())
   })
@@ -28,9 +27,6 @@ describe('makeBotProtocols', () => {
       [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
 
@@ -47,9 +43,9 @@ describe('makeBotProtocols', () => {
     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)
+    expect(tree.activity.list.guards).toEqual([])
+    expect(tree.activity.list.gate).toBeUndefined()
+    expect(Object.isFrozen(tree) && Object.isFrozen(tree.connection) && Object.isFrozen(tree.connection.save)).toBe(true)
   })
 
   test('two mounts are two alias families, and parent and service reach the base', () => {

package/tests/schemas.spec.ts

@@ -1,7 +1,7 @@
 import { describe, expect, test } from 'bun:test'
 import {
-  BOT_ACTIVITY_LIMIT_MAX, BOT_KEYWORDS_MAX, BotActivityQuerySchema, BotChallengeQuerySchema, BotConnectionInputSchema,
-  BotHookParamsSchema, BotIdParamsSchema, BotRuleInputSchema, BotRuleListQuerySchema, BotSimulateInputSchema,
+  BOT_ACTIVITY_LIMIT_MAX, BotActivityQuerySchema, BotChallengeQuerySchema, BotConnectionInputSchema,
+  BotHookParamsSchema, BotIdParamsSchema, BotSimulateInputSchema,
 } from '../src/index.js'
 import { validatorOf } from './context.js'
 
@@ -25,27 +25,6 @@ describe('connection input', () => {
   })
 })
 
-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)
 
@@ -84,13 +63,6 @@ describe('params and queries', () => {
     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)

package/tests/text.spec.ts

@@ -0,0 +1,101 @@
+import { describe, expect, test } from 'bun:test'
+import { BotTextMatch, botTextHelper } from '../src/index.js'
+
+const { matched, phrasesOf, fold, tokensOf } = botTextHelper
+
+describe('botTextHelper.fold and tokensOf', () => {
+  test('fold applies NFKC, a case fold and NFKC again', () => {
+    expect(fold('STRASSE')).toBe(fold('straße'))
+    expect(fold('ＣＡＳＩＮＯ')).toBe('casino')
+    expect(fold('finance')).toBe('finance')
+    expect(fold('ЁЛКА')).toBe('ёлка')
+  })
+
+  test('tokens are runs of letters, marks, digits and _ — punctuation splits', () => {
+    expect(tokensOf('Free—MONEY, now_2!')).toEqual(['free', 'money', 'now_2'])
+    expect(tokensOf('!!! ...')).toEqual([])
+  })
+})
+
+describe('botTextHelper.matched — word mode (the default)', () => {
+  test('matches whole words only, case-insensitively and across punctuation', () => {
+    expect(matched('Visit the CASINO!', ['casino'])).toEqual(['casino'])
+    expect(matched('casino, now', ['casino'])).toEqual(['casino'])
+    expect(matched('casinos are fun', ['casino'])).toEqual([])
+    expect(matched('megacasino', ['casino'])).toEqual([])
+  })
+
+  test('a multi-word phrase must appear as consecutive words', () => {
+    expect(matched('Get FREE   money now', ['free money'])).toEqual(['free money'])
+    expect(matched('free—money', ['free money'])).toEqual(['free money'])
+    expect(matched('money for free', ['free money'])).toEqual([])
+    expect(matched('free real money', ['free money'])).toEqual([])
+  })
+
+  test('is Unicode-aware: Cyrillic, accents, compatibility forms and the German sharp s', () => {
+    expect(matched('Купите СПАМ сейчас', ['спам'])).toEqual(['спам'])
+    expect(matched('ёлка', ['ЁЛКА'])).toEqual(['ЁЛКА'])
+    expect(matched('Un café, por favor', ['CAFÉ'])).toEqual(['CAFÉ'])
+    // Accents are kept: "cafe" is not "café".
+    expect(matched('Un café', ['cafe'])).toEqual([])
+    // NFKC: the full-width form and the ligature fold onto plain letters; NFD text onto NFC.
+    expect(matched('ＣＡＳＩＮＯ night', ['casino'])).toEqual(['casino'])
+    expect(matched('finance tips', ['finance'])).toEqual(['finance'])
+    expect(matched('café au lait', ['café'])).toEqual(['café'])
+    expect(matched('STRASSE gesperrt', ['straße'])).toEqual(['straße'])
+  })
+
+  test('a phrase with no letters or digits never matches a word', () => {
+    expect(matched('!!! now', ['!!!'])).toEqual([])
+    expect(matched('!!! now', ['!!!'], BotTextMatch.Word)).toEqual([])
+  })
+})
+
+describe('botTextHelper.matched — contains mode', () => {
+  test('matches a folded substring, inside words too, with whitespace runs collapsed', () => {
+    const contains = BotTextMatch.Contains
+
+    expect(matched('MEGACASINO.com', ['casino'], contains)).toEqual(['casino'])
+    expect(matched('wow!!! ok', ['!!!'], contains)).toEqual(['!!!'])
+    expect(matched('get free\n money', ['free  money'], contains)).toEqual(['free  money'])
+    expect(matched('no match here', ['casino', '!!!', 'free money'], contains)).toEqual([])
+  })
+
+  test('finds a phrase in a script written without spaces', () => {
+    expect(matched('今日は営業時間を教えて', ['営業時間'], BotTextMatch.Contains)).toEqual(['営業時間'])
+  })
+})
+
+describe('botTextHelper.matched — the answer', () => {
+  test('lists every phrase found, in the given order, as given', () => {
+    expect(matched('You idiot, what are the OPENING hours? stupid!', ['moron', 'stupid', 'Idiot', 'opening hours']))
+      .toEqual(['stupid', 'Idiot', 'opening hours'])
+  })
+
+  test('answers each phrase once: a folded repeat is skipped, the first spelling kept', () => {
+    expect(matched('spam spam SPAM', ['Spam', 'spam', 'SPAM'])).toEqual(['Spam'])
+  })
+
+  test('empty text, blank phrases and non-strings never match', () => {
+    expect(matched('   ', ['spam'])).toEqual([])
+    expect(matched('spam', ['', '   '])).toEqual([])
+    expect(matched('spam', [42 as unknown as string, 'spam'])).toEqual(['spam'])
+    expect(matched(undefined as unknown as string, ['spam'])).toEqual([])
+  })
+})
+
+describe('botTextHelper.phrasesOf', () => {
+  test('splits on commas and line breaks, trims, collapses inner whitespace and drops empties', () => {
+    expect(phrasesOf('  Free   money , casino,\n\nopening hours\r\n,  '))
+      .toEqual(['Free money', 'casino', 'opening hours'])
+  })
+
+  test('drops folded duplicates keeping the first spelling — across the items of a list too', () => {
+    expect(phrasesOf(['  Free   money ', '', '   ', 'free MONEY', 'Спам', 'СПАМ, café'])).toEqual(['Free money', 'Спам', 'café'])
+  })
+
+  test('splits each item of a list and ignores what is not a string', () => {
+    expect(phrasesOf(['spam, scam', 7 as unknown as string, 'casino'])).toEqual(['spam', 'scam', 'casino'])
+    expect(phrasesOf('')).toEqual([])
+  })
+})

package/tests/update.spec.ts

@@ -1,18 +1,12 @@
 import { describe, expect, test } from 'bun:test'
 import {
-  BotChatKind, BotMatchMode, BotPlatform, BotRuleAction, BotUpdateKind, botCommandHelper, botRuleHelper,
-  type BotMessageRef, type BotRule, type BotUpdate,
+  BotChatKind, BotPlatform, BotUpdateKind, botCommandHelper, botTextHelper, type BotMessageRef, 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', () => {
+  test('carries its command and a message ref that alone addresses the message; a handler matches the text itself', () => {
     const ref: BotMessageRef = { chat: 'ch-1', id: 'm-1', thread: 't-1', space: 'guild-9' }
     const text = '/report@ModBot RAID incoming'
     const update: BotUpdate = {
@@ -26,12 +20,12 @@ describe('a normalized update, assembled the way a runtime does', () => {
       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']]])
+    expect(Object.keys(update)).not.toContain('matches')
+    expect(botTextHelper.matched(update.message?.text ?? '', ['raid', 'spam'])).toEqual(['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/build/helpers/rule/types.d.ts

@@ -1,26 +0,0 @@
-import type { BotMatch, BotRule } from '../../types.js';
-/**
- * How a message is matched against keyword groups — the ONE implementation the server's dispatch,
- * the panels and the tests share, so a rule means the same thing everywhere.
- */
-export interface BotRuleHelper {
-    /**
-     * The enabled rules whose keywords the text matches, ordered by `order` (ties keep the given
-     * order), each with the keywords (as stored) that matched.
-     *
-     * Both sides are folded the same way: NFKC, then case-folded (`ß` ≡ `ss`, `Ё` ≡ `ё`), accents
-     * kept. `word` compares whole tokens — runs of letters, combining marks, digits and `_` — and a
-     * multi-word keyword is a PHRASE that must appear as consecutive tokens; `contains` is a substring
-     * of the folded text with whitespace runs collapsed. Disabled rules never match.
-     */
-    match: (text: string, rules: readonly BotRule[]) => BotMatch[];
-    /**
-     * A keyword list as it is stored: each trimmed with inner whitespace collapsed, cut to
-     * `BOT_KEYWORD_MAX` code points, empties dropped, duplicates (by their folded form) dropped keeping
-     * the first spelling, at most `BOT_KEYWORDS_MAX` kept.
-     */
-    normalizeKeywords: (list: readonly string[]) => string[];
-    /** Whether a rule applies to a connection: its own, or a scope-wide one (`connection` null/absent). */
-    appliesTo: (rule: Pick<BotRule, 'connection'>, connection: string) => boolean;
-}
-//# sourceMappingURL=types.d.ts.map

package/build/helpers/rule/types.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/helpers/rule/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAA;AAEvD;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;;;OAQG;IACH,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,OAAO,EAAE,KAAK,QAAQ,EAAE,CAAA;IAC9D;;;;OAIG;IACH,iBAAiB,EAAE,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,KAAK,MAAM,EAAE,CAAA;IACxD,uGAAuG;IACvG,SAAS,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,EAAE,UAAU,EAAE,MAAM,KAAK,OAAO,CAAA;CAC9E"}

package/build/helpers/rule.d.ts

@@ -1,4 +0,0 @@
-import type { BotRuleHelper } from './rule/types.js';
-export declare const createBotRuleHelper: () => BotRuleHelper;
-export declare const botRuleHelper: BotRuleHelper;
-//# sourceMappingURL=rule.d.ts.map

package/build/helpers/rule.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"rule.d.ts","sourceRoot":"","sources":["../../src/helpers/rule.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAEpD,eAAO,MAAM,mBAAmB,QAAO,aAiFtC,CAAA;AAED,eAAO,MAAM,aAAa,eAAwB,CAAA"}