A deterministic, type-safe conversational state machine framework for chatbots.

Key Features

• Deterministic FSM Engine: Pure, 100% testable state transitions with automatic timeout guards and fallback recovery.
• Compiled Pattern Matching: Regex-compiled keyword normalization, word-boundary safety, and negation guards (excludeIf).
• Durable State Persistence: MongoDB / Mongoose adapter with Optimistic Concurrency Control (OCC) to prevent race conditions.
• High-Speed Idempotency: Redis-backed webhook deduplication and BullMQ asynchronous worker queue processing.
• Analytics & Evals: Built-in conversation trace collectors, automated evaluation suite, and node-level drop-off metrics.

Installation

pnpm add @henry-dev/botkit
# or
npm install @henry-dev/botkit
# or
yarn add @henry-dev/botkit

Quick Example

import { Bot, FSMEngine } from "@henry-dev/botkit";

// 1. Setup the Bot DSL and define flows
const bot = new Bot("support_flow", 1);

bot.ask("Hello! How can we help you today? Please reply with 'help', 'delivery', or 'refund':")
  .expect(["msaada", "help", "delivery", "refund"])
  .response((answer, ctx) => {
    ctx.set("customerQuery", answer.raw);
  })
  .fallback("I missed that. Please reply with 'help', 'delivery', or 'refund':")
  .retries(3);

const flow = bot.compile();

// 2. Instantiate and feed the FSM Engine
const fsm = new FSMEngine(flow);
const state = fsm.createInitialState("whatsapp-user-id");

// 3. Drive transition deterministically
const result = await fsm.transition(state, "help");
console.log(result.nextState.context.customerQuery); // "help"

Documentation & Interactive Playground

For full guides, API references, architecture deep-dives and an interactive simulator:

• Interactive Simulator: Test conversational state flows live in browser
• Analytics & Evals: Track drop-offs and evaluate scenario completion rates
• Full Documentation: Explore detailed guides on matchers, persistence, webhooks and workers

License

Released under the MIT License.