wabot-ts

Use when building real-time phone-call bots for Wabot — receiving inbound calls and placing outbound calls over Twilio, bridged to an OpenAI Realtime model, with the same Mindset as the brain. Covers @voiceController, @voiceBot, @twilioVoice (webhook/media routes + X-Twilio-Signature verification), VoiceBot.answer, IVoiceCall, TwilioCalls.initiate (channel picked by `from`) + TwilioAccountRegistry (multiple numbers/accounts), InitiateCallTools, the @realtimeVoiceEngine provider model, and how run() auto-boots it. Also the speechToText/textToSpeech chat voice notes.

A ready-made design system for building good-looking web UIs in Wabot apps. Ships tokens (color, type, spacing, radii, motion), accessible components (buttons, badges, cards, forms, tables), and layout primitives so elements look polished by default. Use when generating UI, pages, forms, prototypes, slides, or any visual artifact for a Wabot project.

Use when defining a Wabot bot's personality, tool functions, language/model configuration, or chat-scope state. Covers @mindset, @tools (formerly @mindsetModule), the IMindset interface (describe() → IMindsetDescription with identity + context/skills/limits/workflow, and models()), caching describe()/models() via @mindset({ cache }) + MindsetCache, IMindsetModels and the model kinds (llm, visionLlm, audioLlm, speechToText, textToSpeech, imageGen, embedding), tool functions exposed via @description, agents the mindset can call autonomously via @mindset({ agents }) with per-agent allow/deny tool gating, request validation, and ChatOperator for per-chat associations. For dev-facing agents that reuse the same tools, see wabot-agents.

Use when building dev-facing agents, asking an LLM for a typed/deterministic answer or yes/no, giving orders, or letting a mindset delegate to an agent — either autonomously via @mindset({ agents }) or from a tool — with controlled context and tool access. Covers @agent (incl. description), IAgent, AgentFactory, AgentSession (ask / confirm / order), typed structured output, AgentReply (answer / question / stopped), context attachments (attachChat / attachMessage — e.g. "should the bot respond?"), the shared @tools decorator, tool gating (allowTools / denyTools / exposeToMindsets / budget), and testing agents with createAgentHarness.

Use when writing or debugging tests for a Wabot project — deterministic unit tests for chatbots (mindsets + tools), chat controllers, REST controllers, async commands/cron, validation models and repositories, plus real-LLM evals. Covers the '@wabot-dev/framework/testing' entrypoint, ChatBotHarness, ChatControllerHarness, AgentHarness, MockChatAdapter, RestHarness, AsyncHarness, UiHarness, SocketHarness, LlmJudge, useMemoryRepositories, TestJwt/TestApiKeyRepository, fixtures, and the .unit.test.ts / .eval.test.ts conventions.

Use when building server-rendered web pages, forms, or interactive UI from a Wabot app. Covers @uiController, @view, @action, @uiMiddleware, the one validated-DTO handler arg, redirect(), islands (island() in *.island.tsx, callAction/actionUrl), signals vs hooks, boosted navigation (app: true) with layout/<Outlet/> and swr, static generation (SSG) via @view({ static }) + StaticPageCache, head resource hints, CSS modules, the tsconfig JSX setup, and custom UiRenderer. Argument validation is shared with wabot-validation.

Use when wiring services, choosing service lifecycles, reading env vars, or expressing typed config references for Wabot apps. Covers @injectable / @singleton / @scoped / @inject, the container, the Env service, and the config tag functions (str, num, bool, obj, strArr, numArr, boolArr) that drive resolveConfigReferences in channel and adapter decorators.

Use when working with @wabot-dev/framework — building, reviewing, or debugging chat bots, REST APIs, sockets, async jobs, or any project scaffolded with @wabot-dev/create. Covers project boot, the IProjectRunnerConfig flow, file layout, the WABOT_BUNDLED dev/prod split, and where to dive for each subsystem.

Use when defining request DTOs, mindset module argument classes, or any class that must be validated and transformed by Wabot — including REST/socket inputs and tool function parameters. Covers the validator decorators (@isString, @isNumber, @isBoolean, @isDate, @isIn, @isNotEmpty, @isPresent, @isRecord, @isOptional, @isModel, @isArray, @min, @max), @description, validateAndTransform, and Mapper.

Use when running background work in Wabot — fire-and-forget commands, scheduled deferred commands, cron handlers, or wrapping side-effectful methods in a DB transaction. Covers @command, @commandHandler, @cronHandler, @transaction, the Async service (runCommand, scheduleCommand, IScheduleAt), ICommandHandler / ICronHandler, and how the in-memory vs PG job/cron stores are wired by the project runner.

Use when adding authentication to a Wabot REST endpoint or Socket.IO namespace, issuing JWT access/refresh tokens, or protecting endpoints with API keys. Covers the chat/request-scoped Auth<D> service, @jwtGuard / @jwtHandshakeGuard, JwtConfig and the JWT_* env vars, Jwt.createToken / findRefreshTokenAuthInfo, JwtRefreshToken, and @apiKeyGuard / @apiKeyHandshakeGuard with PgApiKeyRepository / RemoteApiKeyRepository.

Use when wiring chat input/output for a Wabot bot — receiving messages from one or more channels (cmd, socket, telegram, whatsapp, wasender), injecting a ChatBot bound to a mindset, and replying. Covers @chatController, @chatBot, @cmd / @socket / @telegram / @whatsApp / @wasender, IReceivedMessage, the ChatBot.sendMessage callback, and the @chatAdapter / runChatAdapters provider model.

Use when reaching for cross-cutting utilities in a Wabot app — structured logging, distributed/in-process locking, custom errors with HTTP codes, password hashing, secure random generators, or process-level error handlers. Covers Logger (6 levels via debug + optional IErrorMonitor), Locker / ILockKey / ILockerKey (in-memory + PG implementations selected by DATABASE_URL), CustomError, setupErrorHandlers, Password (scrypt-based), and Random.

Use when defining entities, repositories, queries, or per-adapter query extensions in Wabot. Covers Entity / IEntityData, @repository, the @query method-name DSL (find/findOne/count/exists/delete + And/Or + operators), @queryExtension, @memExtension / MemoryRepositoryExtension, @pgExtension / PgRepositoryExtension, and how the active adapter is chosen automatically by the project runner.

Use when exposing HTTP endpoints or Socket.IO namespaces from a Wabot app. Covers @restController, @onGet / @onPost / @onPut / @onDelete, @middleware and IMiddleware, the EXPRESS_REQ / EXPRESS_RES tokens, the RestRequest base for raw-request access, plus @socketController, @onSocketEvent, @handshakeMiddlewares and IHandshakeMiddleware. Argument validation is shared with wabot-validation.