telemeister 0.1.0

package/README.md

@@ -0,0 +1,460 @@
+# Telemeister
+
+A TypeScript Telegram Bot Framework with [Grammy](https://grammy.dev), XState-powered Finite State Machines (FSM), Prisma ORM for persistence, and a type-safe builder pattern for defining conversation flows.
+
+**Goal**: Build bot infrastructure with explicit structure that allows an LLM to build and verify bots from text descriptions, and detect inconsistencies in those descriptions.
+
+## Features
+
+- **NPM Package**: Install as a dependency to any bot project
+- **Project Scaffolding**: `npx telemeister create-bot` creates new projects
+- **Grammy Bot Framework**: Modern, TypeScript-first Telegram Bot API library
+- **XState FSM**: Compact, maintainable state machines using XState's "states as data" pattern
+- **Type-Safe State Transitions**: Full TypeScript support with strict transition types
+- **State Machine Configuration**: JSON-based state machine definition (`bot.json`)
+- **Auto-Generated Types**: TypeScript types generated from state machine config
+- **State Diagram Visualization**: Mermaid diagrams (MD + PNG) auto-generated
+- **Prisma ORM 7.x**: Modern database toolkit with driver adapters for SQLite and MySQL
+- **Single Schema**: One Prisma schema works for both SQLite (dev) and MySQL (production)
+- **Builder Pattern**: Fluent API for defining state handlers
+- **Dual Mode**: Supports both Polling and Webhook modes
+- **CLI Tools**: Built-in commands for managing states, transitions, and webhooks
+
+## Quick Start
+
+### Create a New Bot
+
+```bash
+npx telemeister create-bot my-bot
+cd my-bot
+npm install
+```
+
+### Environment Setup
+
+```bash
+cp .env.example .env
+# Edit .env with your credentials
+```
+
+Required environment variables:
+```env
+BOT_TOKEN=your_bot_token    # From @BotFather (https://t.me/BotFather)
+
+# Database Configuration
+# For SQLite (development):
+DATABASE_URL="file:./dev.db"
+
+# For MySQL (production):
+# DATABASE_URL="mysql://user:password@localhost:3306/dbname"
+```
+
+### Database Setup
+
+**Generate Prisma Client:**
+```bash
+npm run db:generate
+```
+
+**Run Migrations:**
+```bash
+# Development (SQLite)
+npm run db:migrate
+
+# Production (MySQL) - after updating DATABASE_URL
+npm run db:deploy
+```
+
+### Run the Bot
+
+**Polling mode (development):**
+```bash
+npm run dev
+```
+
+**Webhook mode (production):**
+```bash
+# Set webhook URL first
+npm run webhook:set -- https://your-domain.com/webhook
+
+# Start in webhook mode
+BOT_MODE=webhook npm run dev
+```
+
+## Project Structure
+
+```
+my-bot/
+├── bot.json                 # State machine configuration (source of truth, gitignored)
+├── src/
+│   ├── bot-state-types.ts   # Auto-generated types (DO NOT EDIT)
+│   ├── bot-diagram.md       # Auto-generated Mermaid diagram
+│   ├── bot-diagram.png      # Auto-generated diagram image
+│   ├── handlers/            # Your state handlers
+│   │   ├── index.ts        # Handler imports
+│   │   ├── idle/           # Idle state handler
+│   │   ├── welcome/        # Welcome state handler
+│   │   └── menu/           # Menu state handler
+│   └── index.ts            # Bot entry point
+├── prisma/
+│   └── schema.prisma       # Database schema
+├── .env                    # Environment variables (gitignored)
+└── package.json
+```
+
+## State Management
+
+### State Machine Configuration
+
+The `bot.json` file is the source of truth for your state machine:
+
+```json
+{
+  "idle": ["welcome"],
+  "welcome": ["menu"],
+  "menu": ["welcome", "idle"]
+}
+```
+
+Each key is a state, and the array contains valid transition targets.
+
+### CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `telemeister state:add <name>` | Add a new state + create handler |
+| `telemeister state:delete <name>` | Delete a state (with safety checks) |
+| `telemeister state:sync` | Sync types + create missing handlers |
+| `telemeister state:transition:add <from> <to>` | Add a transition |
+| `telemeister state:transition:delete <from> <to>` | Delete a transition |
+
+Or use npm scripts:
+```bash
+npm run state:add -- settings
+npm run state:sync
+```
+
+### Adding a New State
+
+```bash
+telemeister state:add collectEmail
+```
+
+This command:
+- Adds `"collectEmail": []` to `bot.json`
+- Creates `src/handlers/collectEmail/index.ts` with a template
+- Updates `src/handlers/index.ts` with the import
+- Regenerates `src/bot-state-types.ts`
+- Regenerates `src/bot-diagram.md` and `src/bot-diagram.png`
+
+### Adding Transitions
+
+```bash
+telemeister state:transition:add collectEmail completed
+```
+
+This updates `bot.json`, regenerates types and diagrams.
+
+### Deleting States
+
+Safety checks prevent accidental deletion:
+- Cannot delete if handler folder is non-empty
+- Cannot delete if state has outgoing transitions
+- Cannot delete if state has incoming transitions
+
+```bash
+# Remove transitions first
+telemeister state:transition:delete collectEmail completed
+
+# Then empty the handler folder or move files
+rm -rf src/handlers/collectEmail
+
+# Now delete the state
+telemeister state:delete collectEmail
+```
+
+### Syncing
+
+```bash
+telemeister state:sync
+```
+
+This regenerates:
+- `src/bot-state-types.ts` - TypeScript types from `bot.json`
+- `src/bot-diagram.md` - Mermaid diagram
+- `src/bot-diagram.png` - PNG image (requires mermaid-cli)
+- Creates missing handler folders (never overwrites existing)
+
+## Auto-Generated Types
+
+The `src/bot-state-types.ts` file is auto-generated:
+
+```typescript
+// Auto-generated by state:sync - DO NOT EDIT
+
+export type AppStates = 'idle' | 'menu' | 'welcome';
+
+export type StateTransitions = {
+  idle: 'welcome' | void;
+  menu: 'idle' | 'welcome' | void;
+  welcome: 'menu' | void;
+};
+
+export type IdleTransitions = Promise<StateTransitions['idle']>;
+export type MenuTransitions = Promise<StateTransitions['menu']>;
+export type WelcomeTransitions = Promise<StateTransitions['welcome']>;
+```
+
+## Handler API
+
+### Strict Transition Types
+
+Handlers use generated types for strict return type checking:
+
+```typescript
+import { appBuilder, type AppContext } from 'telemeister/core';
+import type { MenuTransitions } from './bot-state-types.js';
+
+appBuilder
+  .forState('menu')
+  .onEnter(async (context: AppContext): MenuTransitions => {
+    await context.send('Welcome to menu!');
+    // Can only return 'idle', 'welcome', or void
+  })
+  .onResponse(async (context: AppContext, response): MenuTransitions => {
+    if (response === 'back') return 'welcome'; // ✅ Valid
+    if (response === 'exit') return 'idle';    // ✅ Valid
+    return 'invalid';  // ❌ Type error - not in transitions
+  });
+```
+
+### Context Methods
+
+```typescript
+interface BotHandlerContext<TState> {
+  // User info
+  userId: number;
+  telegramId: number;
+  chatId: number;
+  currentState: TState;
+
+  // Messaging
+  send: (text: string) => Promise<unknown>;
+
+  // Data persistence (per-user)
+  setData: <T>(key: string, value: T) => void;
+  getData: <T>(key: string) => T | undefined;
+
+  // State transition
+  transition: (toState: TState) => Promise<void>;
+}
+```
+
+### Handler Types
+
+```typescript
+// Called when entering a state
+.onEnter(async (context) => {
+  await context.send("Welcome!");
+  // Optionally return a state for immediate transition
+  return "anotherState";
+})
+
+// Called when user sends a message
+.onResponse(async (context, response) => {
+  // Return state name to transition, or void/undefined to stay
+  if (response === "yes") return "confirmed";
+  return "cancelled";
+})
+```
+
+## State Diagram
+
+Auto-generated visualizations are updated on every state/transition change:
+
+**`src/bot-diagram.md`:**
+```markdown
+# Bot State Diagram
+
+```mermaid
+stateDiagram-v2
+    idle --> welcome
+    welcome --> menu
+    menu --> welcome
+    menu --> idle
+```
+```
+
+**`src/bot-diagram.png`:** PNG image rendered by mermaid-cli.
+
+## Database Configuration
+
+### Switching Between SQLite and MySQL
+
+**1. Update `prisma/schema.prisma`:**
+```prisma
+datasource db {
+  provider = "sqlite"  // Change to "mysql" for production
+}
+```
+
+**2. Update `.env`:**
+```bash
+# SQLite (development)
+DATABASE_URL="file:./dev.db"
+
+# MySQL (production)
+DATABASE_URL="mysql://user:password@localhost:3306/dbname"
+```
+
+**3. Regenerate and migrate:**
+```bash
+npm run db:generate
+npm run db:migrate
+```
+
+### Database Commands
+
+```bash
+npm run db:generate    # Generate Prisma Client after schema changes
+npm run db:migrate     # Create and apply migrations (development)
+npm run db:deploy      # Apply migrations in production
+npm run db:push        # Push schema changes without migration files
+npm run db:studio      # Open Prisma Studio (database GUI)
+```
+
+## Webhook Commands
+
+```bash
+# Set webhook URL
+npm run webhook:set -- https://your-domain.com/webhook
+
+# Check webhook info
+npm run webhook:info
+
+# Delete webhook (switch back to polling)
+npm run webhook:delete
+```
+
+## Database Schema
+
+Users are persisted with:
+- `telegramId` - Telegram user ID
+- `chatId` - Telegram chat ID
+- `currentState` - Current FSM state
+- `stateData` - JSON data storage for user context (in separate `userInfo` relation)
+
+### Prisma Schema
+
+```prisma
+model User {
+  id           Int       @id @default(autoincrement())
+  telegramId   Int       @unique
+  chatId       Int
+  currentState String    @default("idle")
+  updatedAt    DateTime  @updatedAt
+  info         UserInfo?
+
+  @@index([currentState])
+}
+
+model UserInfo {
+  id        Int    @id @default(autoincrement())
+  userId    Int    @unique
+  user      User   @relation(fields: [userId], references: [id], onDelete: Cascade)
+  stateData String @default("{}")
+}
+```
+
+## Architecture
+
+### State Persistence Flow
+
+```
+User sends message
+       ↓
+Load user from DB (by telegramId)
+       ↓
+Execute onResponse for current state
+       ↓
+Handler returns nextState (or void)
+       ↓
+Update DB with new state
+       ↓
+Execute onEnter for new state
+       ↓
+Send prompt to user
+```
+
+### Compact FSM Pattern
+
+Instead of defining every state in XState:
+
+```typescript
+// Traditional - verbose
+states: {
+  idle: { on: { START: 'welcome' } },
+  welcome: { on: { NEXT: 'menu' } },
+  // ... every state
+}
+
+// Telemeister - compact
+states: {
+  active: {
+    on: {
+      TRANSITION: {
+        actions: assign({ currentState: ({ event }) => event.toState }),
+        target: 'active',
+        reenter: true, // Triggers onEnter
+      }
+    }
+  }
+}
+```
+
+The actual state value is stored in `context.currentState`. The `bot.json` file is the source of truth for valid states and transitions.
+
+## Development
+
+### Developing the Telemeister Framework
+
+This repository contains the Telemeister framework source code.
+
+```bash
+# Clone and install
+git clone <repo>
+cd telemeister
+npm install
+
+# Build
+npm run build
+
+# Run CLI locally
+npm run telemeister:state:add -- settings
+
+# Or use tsx directly
+npx tsx src/cli/cli.ts state:add settings
+```
+
+### Publishing
+
+```bash
+npm run build
+npm version patch
+npm publish
+```
+
+## Technology Stack
+
+- **[Grammy](https://grammy.dev)**: Modern Telegram Bot API framework with excellent TypeScript support
+- **[XState](https://stately.ai/docs/xstate)**: State machines for complex conversation flows
+- **[Prisma ORM 7.x](https://prisma.io)**: Database toolkit with driver adapters
+  - **Driver Adapters**: Required adapters for database connections (`@prisma/adapter-better-sqlite3`, `@prisma/adapter-mariadb`)
+  - **ESM-Only**: Native ES module support
+  - **Generated Client in Source**: Better IDE support and file watching
+- **[EJS](https://ejs.co)**: Template engine for handler generation
+- **[Mermaid CLI](https://github.com/mermaid-js/mermaid-cli)**: Diagram generation
+
+## License
+
+MIT

package/bin/telemeister.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+
+/**
+ * Telemeister CLI Entry Point
+ */
+
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const cliPath = join(__dirname, '..', 'dist', 'cli', 'index.js');
+
+import(cliPath).catch((err) => {
+  console.error('Failed to load CLI:', err.message);
+  process.exit(1);
+});

package/dist/bot/polling.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Grammy-based Polling Mode Implementation
+ *
+ * Uses Grammy Bot API library with database-backed sessions.
+ */
+import { Bot, type Context } from 'grammy';
+import { type SessionData } from './session.js';
+interface BotContext extends Context {
+    session: SessionData;
+}
+/**
+ * Create and configure the Grammy bot
+ */
+export declare function createBot(botToken: string): Bot<BotContext>;
+/**
+ * Start the bot in polling mode
+ */
+export declare function startPollingMode(botToken: string): Promise<void>;
+export {};
+//# sourceMappingURL=polling.d.ts.map

package/dist/bot/polling.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"polling.d.ts","sourceRoot":"","sources":["../../src/bot/polling.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,GAAG,EAAW,KAAK,OAAO,EAAE,MAAM,QAAQ,CAAC;AAGpD,OAAO,EAA4C,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAI1F,UAAU,UAAW,SAAQ,OAAO;IAClC,OAAO,EAAE,WAAW,CAAC;CACtB;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,GAAG,CAAC,UAAU,CAAC,CAyD3D;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAWtE"}

package/dist/bot/polling.js

@@ -0,0 +1,115 @@
+/**
+ * Grammy-based Polling Mode Implementation
+ *
+ * Uses Grammy Bot API library with database-backed sessions.
+ */
+import { Bot, session } from 'grammy';
+import { appBuilder } from '../core/index.js';
+import { PrismaSessionAdapter, getOrCreateSession } from './session.js';
+/**
+ * Create and configure the Grammy bot
+ */
+export function createBot(botToken) {
+    const bot = new Bot(botToken);
+    // Install session middleware with Prisma adapter
+    bot.use(session({
+        initial: () => ({
+            currentState: 'idle',
+            stateData: {},
+        }),
+        storage: new PrismaSessionAdapter(),
+        getSessionKey: (ctx) => ctx.from?.id.toString(),
+    }));
+    // Ensure user exists in database on each update
+    bot.use(async (ctx, next) => {
+        if (!ctx.from || !ctx.chat) {
+            return next();
+        }
+        const telegramId = ctx.from.id;
+        const chatId = ctx.chat.id;
+        // Get or create user session
+        const userSession = await getOrCreateSession(telegramId, chatId);
+        ctx.session = userSession;
+        return next();
+    });
+    // Handle text messages
+    bot.on('message:text', async (ctx) => {
+        const text = ctx.message.text;
+        const session = ctx.session;
+        // Create handler context compatible with existing handlers
+        const handlerContext = createHandlerContext(ctx, session);
+        // Execute onResponse handler for current state
+        const nextState = await appBuilder.executeOnResponse(session.currentState, handlerContext, text);
+        // Handle state transition
+        if (nextState && nextState !== session.currentState) {
+            await transitionToState(ctx, session, nextState, handlerContext);
+        }
+        else {
+            // Save any state data changes
+            session.stateData =
+                handlerContext.getData('__all') || session.stateData;
+        }
+    });
+    return bot;
+}
+/**
+ * Start the bot in polling mode
+ */
+export async function startPollingMode(botToken) {
+    const bot = createBot(botToken);
+    console.log('🤖 Bot started in polling mode');
+    // Start polling
+    await bot.start({
+        onStart: () => {
+            console.log('✅ Bot is running and polling for updates...');
+        },
+    });
+}
+/**
+ * Create a handler context compatible with existing handlers
+ */
+function createHandlerContext(ctx, session) {
+    // Local state data copy for modifications
+    const localStateData = { ...session.stateData };
+    return {
+        userId: session.userId || 0,
+        telegramId: ctx.from?.id || 0,
+        chatId: ctx.chat?.id || 0,
+        currentState: session.currentState,
+        send: async (text) => {
+            await ctx.reply(text, { parse_mode: 'Markdown' });
+        },
+        setData: (key, value) => {
+            localStateData[key] = value;
+        },
+        getData: (key) => {
+            if (key === '__all') {
+                return localStateData;
+            }
+            return localStateData[key];
+        },
+        transition: async (toState) => {
+            await transitionToState(ctx, session, toState, createHandlerContext(ctx, session));
+        },
+    };
+}
+/**
+ * Transition to a new state and execute onEnter handler
+ */
+async function transitionToState(ctx, session, toState, handlerContext) {
+    // Update session state
+    session.currentState = toState;
+    // Execute onEnter handler for new state
+    const enterNextState = await appBuilder.executeOnEnter(toState, handlerContext);
+    // Save state data changes
+    session.stateData = handlerContext.getData('__all') || session.stateData;
+    // Handle chained transition from onEnter
+    if (enterNextState && enterNextState !== toState) {
+        // Create fresh context for the next state
+        const nextContext = createHandlerContext(ctx, session);
+        const nextState = enterNextState;
+        nextContext.currentState = nextState;
+        await transitionToState(ctx, session, nextState, nextContext);
+    }
+}
+//# sourceMappingURL=polling.js.map

package/dist/bot/polling.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"polling.js","sourceRoot":"","sources":["../../src/bot/polling.ts"],"names":[],"mappings":"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"}

package/dist/bot/session.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Grammy Session Adapter for Prisma Database
+ *
+ * This adapter integrates Grammy's session system with the Prisma database,
+ * allowing user state to persist across restarts.
+ */
+import type { StorageAdapter } from 'grammy';
+/**
+ * Session data stored per user
+ */
+export interface SessionData {
+    /** Current FSM state */
+    currentState: string;
+    /** User-specific data storage */
+    stateData: Record<string, unknown>;
+    /** Internal user ID from database */
+    userId?: number;
+    /** Telegram chat ID */
+    chatId?: number;
+}
+/**
+ * Prisma-backed session storage adapter for Grammy
+ *
+ * This adapter loads/saves session data from/to the database,
+ * keyed by Telegram user ID.
+ */
+export declare class PrismaSessionAdapter implements StorageAdapter<SessionData> {
+    /**
+     * Read session data from database
+     * @param key - Telegram user ID (as string)
+     */
+    read(key: string): Promise<SessionData | undefined>;
+    /**
+     * Write session data to database
+     * @param key - Telegram user ID (as string)
+     * @param value - Session data to save
+     */
+    write(key: string, value: SessionData): Promise<void>;
+    /**
+     * Delete session data (not typically used in bots)
+     * @param key - Telegram user ID (as string)
+     */
+    delete(key: string): Promise<void>;
+}
+/**
+ * Get or create user session
+ * This helper ensures a user exists in the database before processing
+ */
+export declare function getOrCreateSession(telegramId: number, chatId: number): Promise<SessionData>;
+//# sourceMappingURL=session.d.ts.map

package/dist/bot/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/bot/session.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC;AAG7C;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,wBAAwB;IACxB,YAAY,EAAE,MAAM,CAAC;IACrB,iCAAiC;IACjC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,qCAAqC;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uBAAuB;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,qBAAa,oBAAqB,YAAW,cAAc,CAAC,WAAW,CAAC;IACtE;;;OAGG;IACG,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC;IAmBzD;;;;OAIG;IACG,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAO3D;;;OAGG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CASzC;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CA8BjG"}