# Workspace

## Overview

pnpm workspace monorepo using TypeScript. Each package manages its own dependencies.

## Stack

- **Monorepo tool**: pnpm workspaces
- **Node.js version**: 24
- **Package manager**: pnpm
- **TypeScript version**: 5.9
- **API framework**: Express 5
- **Database**: PostgreSQL + Drizzle ORM
- **Validation**: Zod (`zod/v4`), `drizzle-zod`
- **API codegen**: Orval (from OpenAPI spec)
- **Build**: esbuild (CJS bundle)

## Key Commands

- `pnpm run typecheck` — full typecheck across all packages
- `pnpm run build` — typecheck + build all packages
- `pnpm --filter @workspace/api-spec run codegen` — regenerate API hooks and Zod schemas from OpenAPI spec
- `pnpm --filter @workspace/db run push` — push DB schema changes (dev only)
- `pnpm --filter @workspace/api-server run dev` — run API server locally

## Telegram Bot (Submitaibot)

Persian-language bot-builder running in `artifacts/api-server` against `TELEGRAM_BOT_TOKEN`. Owner is `545441870`.

### Parent bot AI tools (in `telegramBot.ts`)
- `create_child_bot` — provision a new child bot from a BotFather token
- `list_my_bots` — show the caller's child bots with stats
- `get_child_bot_details` — fetch a child bot's current name + full system prompt (use before append-edit)
- `edit_child_bot` — rename and/or update a child's system prompt; **defaults to `mode="append"`** so tweaks don't wipe the old prompt. Pass `mode="replace"` only when the user asks to rewrite from scratch. Auto-restarts polling.
- `restart_child_bot` — restart a single child bot's polling
- `generate_image` — text-to-image with `gpt-image-1`

### Child bot AI tools (in `botRegistry.ts`)
- `send_message` — text + optional inline buttons (شیشه‌ای), reply keyboard (کیبوردی), parse_mode, remove_keyboard
- `edit_message` / `delete_message` — in-place updates of bot messages
- `set_state` / `list_state` / `clear_state` — per-chat persistent state, debounced save to `data/child-states/{token}.json`
- `generate_image`, `forward_to_owner`, `broadcast_message` (owner-only), `get_user_info`
- `set_bot_commands` (owner-only) — replaces the child bot's Telegram command menu via `setMyCommands` so users see entries like `/menu` next to the input field.

### Persistence
- `data/child-bots.json` — registered child configs
- `data/child-states/{tokenSafe}.json` — per-chat state, survives restart
- `data/child-users/{tokenSafe}.json` — known users per child bot (used for broadcast)

### Admin panel (`/adminPannel`)
Common buttons: stats, list bots, restart-all bots, VIP grant/revoke, ban/unban, add/remove admin, broadcast, lists, set log channel, toggle main bot.

Owner-only section (visible only to `OWNER_USER_ID`):
- **🤖 AI admin** — toggles a per-user mode where the parent bot adds an admin-focused system prompt and uses tools (list/edit/restart child bots, broadcasts, etc.) to act on plain-Persian commands. Exit via the same button or `/exitai`.
- **🧬 Copy bot** — accepts a new BotFather token and spins up another fully-featured parent-bot instance on it via `startTelegramBot(token, isClone=true)`. All file-backed state is shared. Tracked in `parentBotInstances` map.
- **➕ plusAi** — two-step flow: pick a source child bot by name/username, then provide a new BotFather token. Clones the source's `name` + `systemPrompt` to a new child via `createChildBot`.
- **💾 Database** — zips `artifacts/api-server/{src,data,package.json,tsconfig.json}` plus `replit.md` via `adm-zip` (`buildSourceArchive`) and DMs the file to the owner.
- **♻️ Bot reset** — stops every child bot, clears in-memory `histories`/`pendingActions`/`aiAdminMode`, and reboots all children from disk via `startAllChildBots`.

### Error reporting
Quota exhaustion (HTTP 403 `FREE_TIER_BUDGET_EXCEEDED`) and other OpenAI errors surface as Persian-language messages via `formatAiError` in `runChatTurn` instead of a generic "مشکلی پیش اومد".

See the `pnpm-workspace` skill for workspace structure, TypeScript setup, and package details.