@henry-dev/botkit 1.0.0 → 1.0.1

package/README.md

@@ -0,0 +1,77 @@
+# @henry-dev/botkit
+
+A deterministic, type-safe conversational state machine framework for chatbots.
+
+[![npm version](https://img.shields.io/npm/v/@henry-dev/botkit.svg)](https://www.npmjs.com/package/@henry-dev/botkit)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## 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
+
+```bash
+npm install @henry-dev/botkit
+```
+
+Or using `pnpm` or `yarn`:
+
+```bash
+pnpm add @henry-dev/botkit
+# or
+yarn add @henry-dev/botkit
+```
+
+---
+
+## Quick Example
+
+```typescript
+import { Bot, FSMEngine, matchesAny } from "@henry-dev/botkit";
+
+// 1. Define the conversation flow
+const bot = new Bot("onboarding-flow", 1);
+
+bot.ask("What is your name?")
+  .expect(matchesAny(["jina", "naitwa", "*"]))
+  .response((answer, ctx) => {
+    ctx.set("name", answer.raw);
+  })
+  .fallback("Sorry, I didn't catch that — what should I call you?")
+  .retries(3);
+
+const flow = bot.compile();
+
+// 2. Instantiate and process transitions
+const fsm = new FSMEngine(flow);
+const state = fsm.loadState("user-123");
+const result = await fsm.transition(state, "My name is Alex");
+```
+
+---
+
+## 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](LICENSE).
+
+
+