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

package/src/consts.ts

@@ -0,0 +1,214 @@
+import type { BotPlatformDescriptor } from './types.js'
+
+/** The messaging platforms a bot connection can live on. */
+export enum BotPlatform {
+  Telegram = 'telegram',
+  WhatsApp = 'whatsapp',
+  Discord = 'discord',
+  Slack = 'slack',
+}
+
+/** How a connection's updates reach the application. */
+export enum BotReceiveMode {
+  /** The platform POSTs every update to the connection's hook URL. */
+  Webhook = 'webhook',
+  /** The worker asks the platform for updates (Telegram long polling). */
+  Poll = 'poll',
+  /** The worker holds a socket the platform pushes over (the Discord gateway). */
+  Gateway = 'gateway',
+}
+
+/**
+ * Who answers a connection's platform calls.
+ *
+ * `mock` is the platform's API faithfully faked — no network, every call recorded as activity — so a
+ * preview, a test or an end-to-end run exercises the exact live path without a real bot.
+ */
+export enum BotTransport {
+  Live = 'live',
+  Mock = 'mock',
+}
+
+export enum BotConnectionStatus {
+  /** Saved, not verified yet. */
+  Pending = 'pending',
+  /** The platform accepted the credentials and the receiver is (or can be) running. */
+  Connected = 'connected',
+  /** The last verification or receive failed — `lastError` says why. */
+  Failed = 'failed',
+  /** Switched off by its owner; nothing is received or sent. */
+  Disabled = 'disabled',
+}
+
+/**
+ * What a bot can DO — the platform calls a handler makes, each recorded as one activity.
+ *
+ * `note` is the exception: it records an activity and makes no platform call, so every connection
+ * supports it and no platform descriptor lists it.
+ */
+export enum BotActionKind {
+  Reply = 'reply',
+  Send = 'send',
+  Delete = 'delete',
+  Mute = 'mute',
+  Ban = 'ban',
+  React = 'react',
+  Note = 'note',
+}
+
+/**
+ * What a keyword group (a rule) tells the bot to do with a message it matches.
+ *
+ * A product vocabulary, not a platform one: `warn` is a reply, `record` is a request record of the
+ * product, `agent` hands the message to the product's own agent.
+ */
+export enum BotRuleAction {
+  Delete = 'delete',
+  Warn = 'warn',
+  Mute = 'mute',
+  Ban = 'ban',
+  Reply = 'reply',
+  Record = 'record',
+  Agent = 'agent',
+}
+
+/** How a rule's keywords are compared with a message. */
+export enum BotMatchMode {
+  /** Whole words and whole phrases (consecutive words), Unicode-aware and case-insensitive. */
+  Word = 'word',
+  /** A case-insensitive substring — also the mode for scripts written without spaces. */
+  Contains = 'contains',
+}
+
+export enum BotUpdateKind {
+  Message = 'message',
+  Edited = 'edited',
+  Command = 'command',
+  Member = 'member',
+}
+
+export enum BotChatKind {
+  Private = 'private',
+  Group = 'group',
+  Channel = 'channel',
+}
+
+/** The longest identifier (connection, rule, activity, update) the wire accepts. */
+export const BOT_ID_MAX = 128
+
+/** What an identifier on the wire may look like — it is also a path segment of the hook URL. */
+export const BOT_ID_PATTERN = '^[A-Za-z0-9][A-Za-z0-9_.:-]*$'
+
+/** The longest connection label. */
+export const BOT_LABEL_MAX = 120
+
+/** The longest rule (keyword group) name. */
+export const BOT_RULE_NAME_MAX = 120
+
+/** How many keywords one rule keeps. */
+export const BOT_KEYWORDS_MAX = 200
+
+/** The longest keyword or phrase, in code points. */
+export const BOT_KEYWORD_MAX = 100
+
+/** The longest fixed reply text of a rule. */
+export const BOT_REPLY_MAX = 4096
+
+/** The longest instruction a rule hands to the product's agent. */
+export const BOT_INSTRUCTION_MAX = 4000
+
+/** The longest message text the simulator accepts. */
+export const BOT_TEXT_MAX = 4096
+
+/** The longest single credential value. */
+export const BOT_CREDENTIAL_MAX = 4096
+
+/** How many credential keys one connection input may carry. */
+export const BOT_CREDENTIALS_MAX = 16
+
+/** What a credential key may look like. */
+export const BOT_CREDENTIAL_KEY_PATTERN = '^[A-Za-z][A-Za-z0-9]{0,63}$'
+
+/** The longest free-text field of a simulated chat or sender (title, name, username). */
+export const BOT_NAME_MAX = 256
+
+/** The most activity rows one read returns. */
+export const BOT_ACTIVITY_LIMIT_MAX = 200
+
+/** The activity rows a read returns when it names no limit. */
+export const BOT_ACTIVITY_LIMIT_DEFAULT = 50
+
+/**
+ * The permission the MEMBER mount's gate requires (`gates: { alias: OIDC_GATE, params:
+ * [BOT_MANAGE_PERMISSION] }`) — who may connect an organization's bots, edit its keyword groups and
+ * read its bot activity. In a product whose users work in organizations, an organization's owners hold
+ * it by default; otherwise it is only ever granted explicitly.
+ */
+export const BOT_MANAGE_PERMISSION = 'bot--manage'
+
+/**
+ * What each platform needs and can do — the one table every layer reads: the panel draws the
+ * credential inputs from it, the server verifies and acts by it, generation picks actions from it.
+ *
+ * `actions` lists the platform CALLS a connection can make with its required credentials; an
+ * optional credential's `enables` adds more (Slack's admin `userToken` adds `delete`). `note` is never
+ * listed — it makes no platform call (`botPlatformHelper.actionsOf` answers the full set).
+ */
+export const BOT_PLATFORMS: Record<BotPlatform, BotPlatformDescriptor> = Object.freeze({
+  [BotPlatform.Telegram]: Object.freeze({
+    platform: BotPlatform.Telegram,
+    title: 'Telegram',
+    credentials: Object.freeze([
+      Object.freeze({ key: 'token', secret: true, required: true }),
+    ]),
+    receive: Object.freeze([BotReceiveMode.Webhook, BotReceiveMode.Poll]),
+    actions: Object.freeze([
+      BotActionKind.Reply, BotActionKind.Send, BotActionKind.Delete, BotActionKind.Mute, BotActionKind.Ban,
+      BotActionKind.React,
+    ]),
+    setup: 'auto',
+    docs: 'https://core.telegram.org/bots/tutorial#obtain-your-bot-token',
+  }),
+  [BotPlatform.WhatsApp]: Object.freeze({
+    platform: BotPlatform.WhatsApp,
+    title: 'WhatsApp',
+    credentials: Object.freeze([
+      Object.freeze({ key: 'accessToken', secret: true, required: true }),
+      Object.freeze({ key: 'phoneNumberId', secret: false, required: true }),
+      Object.freeze({ key: 'appSecret', secret: true, required: true }),
+      Object.freeze({ key: 'verifyToken', secret: true, required: true, generated: true }),
+    ]),
+    receive: Object.freeze([BotReceiveMode.Webhook]),
+    actions: Object.freeze([BotActionKind.Reply, BotActionKind.Send, BotActionKind.React]),
+    setup: 'manual',
+    docs: 'https://developers.facebook.com/docs/whatsapp/cloud-api/get-started',
+  }),
+  [BotPlatform.Discord]: Object.freeze({
+    platform: BotPlatform.Discord,
+    title: 'Discord',
+    credentials: Object.freeze([
+      Object.freeze({ key: 'token', secret: true, required: true }),
+      Object.freeze({ key: 'applicationId', secret: false, required: true }),
+    ]),
+    receive: Object.freeze([BotReceiveMode.Gateway]),
+    actions: Object.freeze([
+      BotActionKind.Reply, BotActionKind.Send, BotActionKind.Delete, BotActionKind.Mute, BotActionKind.Ban,
+      BotActionKind.React,
+    ]),
+    setup: 'auto',
+    docs: 'https://discord.com/developers/docs/quick-start/getting-started',
+  }),
+  [BotPlatform.Slack]: Object.freeze({
+    platform: BotPlatform.Slack,
+    title: 'Slack',
+    credentials: Object.freeze([
+      Object.freeze({ key: 'botToken', secret: true, required: true }),
+      Object.freeze({ key: 'signingSecret', secret: true, required: true }),
+      Object.freeze({ key: 'userToken', secret: true, required: false, enables: Object.freeze([BotActionKind.Delete]) }),
+    ]),
+    receive: Object.freeze([BotReceiveMode.Webhook]),
+    actions: Object.freeze([BotActionKind.Reply, BotActionKind.Send, BotActionKind.React]),
+    setup: 'manual',
+    docs: 'https://api.slack.com/apis/events-api',
+  }),
+}) as Record<BotPlatform, BotPlatformDescriptor>

package/src/errors.ts

@@ -0,0 +1,78 @@
+import { ResilientError } from '@owlmeans/error'
+
+/**
+ * The bot refusal family.
+ *
+ * Every message starts with `bot:` and the class's own marker (`connection-not-found:` …) — the
+ * marker survives a hop where the class is not registered, so it is part of the contract. The family
+ * base declares no status: a fault of the platform or the store answers 500.
+ */
+export class BotError extends ResilientError {
+  public static override typeName: string = 'BotError'
+
+  constructor(message: string = 'error') {
+    super(BotError.typeName, `bot:${message}`)
+  }
+}
+
+/** The connection does not exist — or is another scope's, which is deliberately the same answer. */
+export class BotConnectionNotFound extends BotError {
+  public static override typeName: string = `${BotError.typeName}ConnectionNotFound`
+  public static httpStatus = 404
+
+  constructor(message: string = 'error') {
+    super(`connection-not-found:${message}`)
+    this.type = BotConnectionNotFound.typeName
+  }
+}
+
+/** The platform refused the credentials (or a required one is missing) at verification. */
+export class BotCredentialsRejected extends BotError {
+  public static override typeName: string = `${BotError.typeName}CredentialsRejected`
+  public static httpStatus = 422
+
+  constructor(message: string = 'error') {
+    super(`credentials-rejected:${message}`)
+    this.type = BotCredentialsRejected.typeName
+  }
+}
+
+/** An inbound hook whose signature (or verify token) does not prove it came from the platform. */
+export class BotSignatureRejected extends BotError {
+  public static override typeName: string = `${BotError.typeName}SignatureRejected`
+  public static httpStatus = 401
+
+  constructor(message: string = 'error') {
+    super(`signature-rejected:${message}`)
+    this.type = BotSignatureRejected.typeName
+  }
+}
+
+/** The request needs the other transport — `simulate` on a live connection. */
+export class BotTransportMismatch extends BotError {
+  public static override typeName: string = `${BotError.typeName}TransportMismatch`
+  public static httpStatus = 409
+
+  constructor(message: string = 'error') {
+    super(`transport-mismatch:${message}`)
+    this.type = BotTransportMismatch.typeName
+  }
+}
+
+/** The platform (or the connection's credentials) cannot perform the requested action. */
+export class BotUnsupportedAction extends BotError {
+  public static override typeName: string = `${BotError.typeName}UnsupportedAction`
+  public static httpStatus = 422
+
+  constructor(message: string = 'error') {
+    super(`unsupported-action:${message}`)
+    this.type = BotUnsupportedAction.typeName
+  }
+}
+
+ResilientError.registerErrorClass(BotError)
+ResilientError.registerErrorClass(BotConnectionNotFound)
+ResilientError.registerErrorClass(BotCredentialsRejected)
+ResilientError.registerErrorClass(BotSignatureRejected)
+ResilientError.registerErrorClass(BotTransportMismatch)
+ResilientError.registerErrorClass(BotUnsupportedAction)

package/src/helpers/command/types.ts

@@ -0,0 +1,14 @@
+import type { BotCommand } from '../../types.js'
+
+export interface BotCommandHelper {
+  /**
+   * Read a `/command` off the start of a message: `/report@MyBot some args` →
+   * `{ name: 'report', args: 'some args' }`.
+   *
+   * The name is lower-cased and must end at whitespace or at the end of the text (`/usr/bin` is not a
+   * command); `args` is the trimmed rest, `''` when none. A command addressed to ANOTHER bot
+   * (`@OtherBot`, compared case-insensitively, a leading `@` of `botUsername` ignored) answers `null`
+   * — when `botUsername` is not given, any address is accepted. Not a command answers `null`.
+   */
+  parse: (text: string, botUsername?: string) => BotCommand | null
+}

package/src/helpers/command.ts

@@ -0,0 +1,26 @@
+import { BOT_COMMAND_PATTERN } from '../consts.local.js'
+import type { BotCommand } from '../types.js'
+import type { BotCommandHelper } from './command/types.js'
+
+export const createBotCommandHelper = (): BotCommandHelper => {
+  const parse = (text: string, botUsername?: string): BotCommand | null => {
+    if (typeof text !== 'string') {
+      return null
+    }
+    const found = BOT_COMMAND_PATTERN.exec(text.trimStart())
+    if (found == null) {
+      return null
+    }
+    const [, name, addressee, args] = found
+    const own = botUsername?.replace(/^@/, '').trim().toLowerCase()
+    if (addressee != null && own != null && own !== '' && addressee.toLowerCase() !== own) {
+      return null
+    }
+
+    return { name: name.toLowerCase(), args: (args ?? '').trim() }
+  }
+
+  return { parse }
+}
+
+export const botCommandHelper = createBotCommandHelper()

package/src/helpers/index.ts

@@ -0,0 +1,6 @@
+export type * from './rule/types.js'
+export type * from './command/types.js'
+export type * from './platform/types.js'
+export * from './rule.js'
+export * from './command.js'
+export * from './platform.js'

package/src/helpers/platform/types.ts

@@ -0,0 +1,12 @@
+import type { BotActionKind, BotPlatform } from '../../consts.js'
+
+/** What a connection on a platform can do, given which of its credentials hold a value. */
+export interface BotPlatformHelper {
+  /**
+   * The descriptor's actions, plus those an optional credential `enables` when its key is in
+   * `credentialsSet` (Slack's `userToken` → `delete`), plus `note`, which every connection supports.
+   */
+  actionsOf: (platform: BotPlatform, credentialsSet?: readonly string[]) => BotActionKind[]
+  /** Whether {@link BotPlatformHelper.actionsOf} includes `kind`. */
+  supports: (platform: BotPlatform, kind: BotActionKind, credentialsSet?: readonly string[]) => boolean
+}

package/src/helpers/platform.ts

@@ -0,0 +1,23 @@
+import { BOT_PLATFORMS, BotActionKind, type BotPlatform } from '../consts.js'
+import type { BotPlatformHelper } from './platform/types.js'
+
+export const createBotPlatformHelper = (): BotPlatformHelper => {
+  const actionsOf = (platform: BotPlatform, credentialsSet: readonly string[] = []): BotActionKind[] => {
+    const descriptor = BOT_PLATFORMS[platform]
+    if (descriptor == null) {
+      return [BotActionKind.Note]
+    }
+    const enabled = descriptor.credentials
+      .filter(field => field.enables != null && credentialsSet.includes(field.key))
+      .flatMap(field => field.enables ?? [])
+
+    return [...new Set([...descriptor.actions, ...enabled, BotActionKind.Note])]
+  }
+
+  const supports = (platform: BotPlatform, kind: BotActionKind, credentialsSet?: readonly string[]): boolean =>
+    actionsOf(platform, credentialsSet).includes(kind)
+
+  return { actionsOf, supports }
+}
+
+export const botPlatformHelper = createBotPlatformHelper()

package/src/helpers/rule/types.ts

@@ -0,0 +1,26 @@
+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
+}

package/src/helpers/rule.ts

@@ -0,0 +1,89 @@
+import { BOT_KEYWORD_MAX, BOT_KEYWORDS_MAX, BotMatchMode } from '../consts.js'
+import { BOT_SPACE_PATTERN, BOT_TOKEN_PATTERN } from '../consts.local.js'
+import type { BotMatch, BotRule } from '../types.js'
+import type { BotRuleHelper } from './rule/types.js'
+
+export const createBotRuleHelper = (): BotRuleHelper => {
+  /**
+   * 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 =>
+    text.normalize('NFKC').toUpperCase().toLowerCase().normalize('NFKC')
+
+  const tokensOf = (text: string): string[] => fold(text).match(BOT_TOKEN_PATTERN) ?? []
+
+  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 match = (text: string, rules: readonly BotRule[]): BotMatch[] => {
+    if (typeof text !== 'string' || text.trim() === '') {
+      return []
+    }
+    // Folded once per message, never per rule.
+    let tokens: string[] | undefined
+    let spaced: string | undefined
+
+    const matchesKeyword = (mode: BotMatchMode, keyword: string): boolean => {
+      if (mode === BotMatchMode.Contains) {
+        const needle = spacedOf(keyword)
+        spaced ??= spacedOf(text)
+        return needle !== '' && spaced.includes(needle)
+      }
+      const phrase = tokensOf(keyword)
+      tokens ??= tokensOf(text)
+      return phrase.length > 0 && hasPhrase(tokens, phrase)
+    }
+
+    return rules
+      .filter(rule => rule.enabled)
+      .map((rule): BotMatch => ({
+        rule,
+        keywords: [...new Set(rule.keywords.filter(
+          keyword => typeof keyword === 'string' && matchesKeyword(rule.mode ?? BotMatchMode.Word, keyword)
+        ))],
+      }))
+      .filter(found => found.keywords.length > 0)
+      // Array#sort is stable: rules of equal order keep the order they were given in.
+      .sort((left, right) => (left.rule.order ?? 0) - (right.rule.order ?? 0))
+  }
+
+  const normalizeKeywords = (list: readonly string[]): string[] => {
+    const seen = new Set<string>()
+    const result: string[] = []
+
+    for (const raw of list ?? []) {
+      if (typeof raw !== 'string') {
+        continue
+      }
+      const keyword = Array.from(raw.replace(BOT_SPACE_PATTERN, ' ').trim())
+        .slice(0, BOT_KEYWORD_MAX).join('').trim()
+      const key = spacedOf(keyword)
+      if (keyword === '' || seen.has(key)) {
+        continue
+      }
+      seen.add(key)
+      result.push(keyword)
+      if (result.length >= BOT_KEYWORDS_MAX) {
+        break
+      }
+    }
+
+    return result
+  }
+
+  const appliesTo = (rule: Pick<BotRule, 'connection'>, connection: string): boolean =>
+    rule.connection == null || rule.connection === connection
+
+  return { match, normalizeKeywords, appliesTo }
+}
+
+export const botRuleHelper = createBotRuleHelper()

package/src/index.ts

@@ -0,0 +1,7 @@
+export type * from './types.js'
+export type * from './protocols/types.js'
+export * from './consts.js'
+export * from './schemas.js'
+export * from './errors.js'
+export * from './protocols.js'
+export * from './helpers/index.js'

package/src/protocols/types.ts

@@ -0,0 +1,107 @@
+import type { EntrypointProtocol, OpenRequest, OpenValue } from '@owlmeans/entrypoint'
+import type { RouteParent } from '@owlmeans/route'
+import type { BotPlatform } from '../consts.js'
+import type {
+  BotActivity, BotConnection, BotConnectionInput, BotRule, BotRuleInput, BotSimulateInput, BotSimulateResult,
+} from '../types.js'
+
+/** Where a bot tree mounts. Every leaf alias derives from `alias` (`<alias>:connection:list` …). */
+export interface BotBaseOptions {
+  alias: string
+  /** The base path — `/bot/operator`, `/bot/member`, `/bot/hook`. */
+  path: string
+  parent?: RouteParent
+  service?: string
+}
+
+/** The access gate the managing base carries — `EntrypointOptions['gate']`. */
+export interface BotGateOptions {
+  alias: string
+  params?: string | readonly string[]
+}
+
+export interface BotProtocolOptions {
+  base: BotBaseOptions
+  /** The guard(s) the base carries; every leaf inherits them. */
+  guards?: string | readonly string[]
+  /** The ONE gate the base carries (a protocol has one gate); every leaf inherits it. */
+  gates?: BotGateOptions
+}
+
+export interface BotHookProtocolOptions {
+  base: BotBaseOptions
+}
+
+/** `:id` of a connection or a rule. */
+export interface BotIdParams {
+  id: string
+}
+
+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. */
+  limit?: number
+}
+
+/** The hook address: `/:platform/:connection`. */
+export interface BotHookParams {
+  platform: BotPlatform
+  connection: string
+}
+
+/** The platform's NATIVE payload — authenticated and normalized by the server, never by a schema. */
+export interface BotHookPayload {
+  [key: string]: unknown
+}
+
+/** What the receive hook answers: 200 at once, or a handshake's challenge (Slack `url_verification`). */
+export interface BotHookReply {
+  ok?: boolean
+  challenge?: string
+}
+
+/** The subscription handshake WhatsApp sends as a GET (`hub.*`); answered with `hub.challenge`. */
+export interface BotChallengeQuery {
+  'hub.mode'?: string
+  'hub.verify_token'?: string
+  'hub.challenge'?: string
+}
+
+/** The managing surface of one mount (operator or member). */
+export interface BotProtocols {
+  /** Carries the guards and the gate; every leaf hangs under it. */
+  base: EntrypointProtocol<OpenRequest, OpenValue>
+  connection: {
+    list: EntrypointProtocol<{}, BotConnection[]>
+    save: EntrypointProtocol<{ body: BotConnectionInput }, BotConnection>
+    verify: EntrypointProtocol<{ params: BotIdParams }, BotConnection>
+    remove: EntrypointProtocol<{ params: BotIdParams }, BotRemoveResult>
+    /** 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[]>
+  }
+}
+
+/** The platforms' inbound surface — no guard: the platform signs. */
+export interface BotHookProtocols {
+  base: EntrypointProtocol<OpenRequest, OpenValue>
+  receive: EntrypointProtocol<{ params: BotHookParams, body: BotHookPayload }, BotHookReply>
+  challenge: EntrypointProtocol<{ params: BotHookParams, query: BotChallengeQuery }, string>
+}