@wabot-dev/framework 0.9.26 → 0.9.80

package/README.md

@@ -28,6 +28,7 @@
 - 🤖 **Soporte para bots con IA** - Inteligencia artificial lista para usar
 - 🧠 **Múltiples proveedores de IA** - OpenAI, Google Gemini, Anthropic Claude
 - 💬 **Múltiples canales de chat** - Telegram, WhatsApp, Socket y más
+- 🧪 **Sistema de testing integrado** - Prueba tus chatbots sin API keys ni base de datos
 - 📖 **Documentación clara y en español** - Aprende sin barreras de idioma
 
 ---
@@ -103,6 +104,32 @@ Los addons opcionales (`pg`, SDKs de IA) se mantienen como `peerDependencies` y
 
 ---
 
+## 🧪 Testing
+
+El framework incluye un sistema de testing en `@wabot-dev/framework/testing`, agnóstico al runner (node:test, vitest, bun test). Permite probar chatbots de forma determinista —sin API keys ni base de datos— y también evaluar el comportamiento real con un juez LLM.
+
+```ts
+import { createChatBotHarness, LlmJudge } from '@wabot-dev/framework/testing'
+
+// Determinista: el LLM se simula, tus tools se ejecutan de verdad
+const harness = createChatBotHarness({ mindset: EliaMindset })
+harness.adapter.callTool('saveEvent', { title: 'Demo', ... }).reply('¡Agendado!')
+
+const turn = await harness.send('agenda una demo mañana')
+// turn.replies, turn.toolCalls (con resultados reales), harness.history()
+
+// Evals: juzga conversaciones reales con un LLM
+const judge = new LlmJudge({ adapter, models: [{ model: 'claude-haiku-4-5' }] })
+await judge.assert({
+  transcript: harness.history(),
+  criteria: 'Responde en español y confirma la fecha del evento',
+})
+```
+
+También incluye harnesses para controllers de chat (`createChatControllerHarness`), endpoints REST con guards JWT/API-Key reales (`createRestHarness`), commands y crons (`createAsyncHarness`), repositorios en memoria (`useMemoryRepositories`), aserciones de validación y una suite de conformance para adapters LLM propios (`chatAdapterConformanceCases`).
+
+---
+
 ## 💬 Plataformas Soportadas
 
 Wabot se integra nativamente con las principales plataformas de mensajería:

package/dist/src/feature/chat-bot/stripAnsweredMedia.js

@@ -10,8 +10,27 @@ function stripAnsweredMedia(items) {
         const humanMessage = { ...item.humanMessage };
         delete humanMessage.images;
         delete humanMessage.documents;
+        // A media-only message becomes empty once its binaries are stripped, which
+        // makes the provider adapters reject it as empty content. Leave a short
+        // placeholder so the answered turn stays in the history coherently.
+        if (isStrippedMessageEmpty(humanMessage)) {
+            humanMessage.text = describeStrippedMedia(item.humanMessage);
+        }
         return { type: 'humanMessage', humanMessage };
     });
 }
+function isStrippedMessageEmpty(message) {
+    return !message.text && !message.object;
+}
+function describeStrippedMedia(message) {
+    const parts = [];
+    const images = message.images?.length ?? 0;
+    const documents = message.documents?.length ?? 0;
+    if (images > 0)
+        parts.push(`${images} image${images > 1 ? 's' : ''}`);
+    if (documents > 0)
+        parts.push(`${documents} document${documents > 1 ? 's' : ''}`);
+    return `[sent ${parts.join(' and ')}]`;
+}
 
 export { stripAnsweredMedia };

package/dist/src/feature/chat-controller/runChatControllers.js

@@ -43,6 +43,9 @@ async function prepareChatContainer(container, messageContext, mindsetCtor) {
             chatContainer.register(chatBotMetadata.injectionToken, { useValue: chatBot });
         });
     }
+    if (mindsetCtor) {
+        chatContainer.register(Mindset, { useClass: mindsetCtor });
+    }
     return chatContainer;
 }
 const logger = new Logger('wabot:chat-controller');
@@ -91,4 +94,4 @@ function runChatControllers(controllers) {
     }
 }
 
-export { runChatControllers };
+export { prepareChatContainer, runChatControllers };

package/dist/src/feature/rest-controller/runRestControllers.js

@@ -16,11 +16,12 @@ import { Container } from '../../core/injection/Container.js';
 function buildRequest(req) {
     return Object.assign({}, req.body, req.query, req.params);
 }
-function runRestControllers(controllers) {
+function registerRestControllers(controllers, options = {}) {
     const logger = new Logger('wabot:rest');
-    const metadataStore = container.resolve(RestControllerMetadataStore);
-    const expressProvider = container.resolve(ExpressProvider);
-    const validationMetadataStore = container.resolve(ValidationMetadataStore);
+    const baseContainer = options.baseContainer ?? container;
+    const metadataStore = baseContainer.resolve(RestControllerMetadataStore);
+    const expressProvider = options.expressProvider ?? baseContainer.resolve(ExpressProvider);
+    const validationMetadataStore = baseContainer.resolve(ValidationMetadataStore);
     const expressApp = expressProvider.getExpress();
     controllers.forEach((controller) => {
         const endPoints = metadataStore.getControllerEndPointsInfo(controller);
@@ -38,7 +39,7 @@ function runRestControllers(controllers) {
                 rawMiddlewares.push(urlencoded({ extended: true }));
             }
             expressApp[method](route, ...rawMiddlewares, async (req, res) => {
-                const requestContainer = container.createChildContainer();
+                const requestContainer = baseContainer.createChildContainer();
                 requestContainer.register(Container, { useValue: requestContainer });
                 requestContainer.register(EXPRESS_REQ, { useValue: req });
                 requestContainer.register(EXPRESS_RES, { useValue: req });
@@ -93,6 +94,10 @@ function runRestControllers(controllers) {
             });
         });
     });
+    return expressProvider;
+}
+function runRestControllers(controllers) {
+    const expressProvider = registerRestControllers(controllers);
     expressProvider.listen();
 }
 function removeCircular(obj, seen = new WeakSet()) {
@@ -110,4 +115,4 @@ function removeCircular(obj, seen = new WeakSet()) {
     return obj;
 }
 
-export { runRestControllers };
+export { registerRestControllers, runRestControllers };

package/dist/src/index.d.ts

@@ -1295,6 +1295,7 @@ interface IMessageContext extends IReceivedMessage {
     authInfo?: object;
 }
 
+declare function prepareChatContainer(container: DependencyContainer$1, messageContext: IMessageContext, mindsetCtor?: IConstructor<IMindset>): Promise<DependencyContainer$1>;
 declare function runChatControllers(controllers: IConstructor<any>[]): void;
 
 declare class HttpServerProvider {
@@ -1623,6 +1624,13 @@ declare class RestControllerMetadataStore {
     }[];
 }
 
+interface IRegisterRestControllersOptions {
+    /** Container the per-request child containers derive from. */
+    baseContainer?: DependencyContainer$1;
+    /** Express provider to mount the routes on. */
+    expressProvider?: ExpressProvider;
+}
+declare function registerRestControllers(controllers: IConstructor<any>[], options?: IRegisterRestControllersOptions): ExpressProvider;
 declare function runRestControllers(controllers: IConstructor<any>[]): void;
 
 declare const EXPRESS_REQ = "EXPRESS_REQ";
@@ -2722,4 +2730,4 @@ declare function HtmlModule(options: IHtmlModuleOptions): {
     new (): {};
 };
 
-export { AnthropicChatAdapter, ApiKey, ApiKeyGuardMiddleware, ApiKeyHandshakeGuardMiddleware, ApiKeyRepository, Async, AsyncMetadataStore, Auth, Chat, ChatAdapter, ChatAdapterMetadataStore, ChatAdapterRegistry, ChatBot, ChatBotMetadataStore, ChatItem, ChatMemory, ChatOperator, ChatRepository, ChatResolver, type ClientMap, CmdChannel, CmdChannelConfig, CmdChannelServer, type CmdClientMessage, type CmdServerMessage, type ConfigReference, type ConfigReferenceType, ConfigResolver, Container, ControllerMetadataStore, CronJob, CronJobRepository, CrudRepository, CustomError, DeepSeekChatAdapter, DescriptionMetadataStore, EXPRESS_REQ, EXPRESS_RES, Entity, Env, type ErrorSeverity, ExpressProvider, GoogleChatAdapter, type GoogleChatAdapterV2Options, HtmlModule, HttpServerProvider, type IApiKeyData, type IApiKeyRepository, type IArrayValidationError, type IArrayValidationResult, type IBotMessageItem, type IBuiltQuery, type IChannelMessage, type IChannelMetadata, type IChatAdapter, type IChatAdapterDecoratorConfig, type IChatAdapterMetadata, type IChatAdapterNextItemsReq, type IChatAdapterNextItemsRes, type IChatAssociation, type IChatBot, type IChatBotMetadata, type IChatChannel, type IChatConnection, type IChatControllerMetadata, type IChatData, type IChatItem, type IChatItemData, type IChatItemType, type IChatMemory, type IChatMessage, type IChatMessageDocument, type IChatMessageFile, type IChatMessageImage, type IChatMessagesPrivateFile, type IChatMessagesPublicFile, type IChatRepository, type IChatType, type ICmdChannelEntry, type ICmdChannelHandlers, type ICmdChannelMessage, type ICmdImage, type ICmdIncomingMessage, type ICmdReceivedMessage, type ICommandConfig, type ICommandHandler, type ICommandHandlerConfig, type IConstructor, type ICronConfig, type ICronHandler, type ICronJobData, type ICronJobRepository, type ICrudRepository, type ICustomErrorData, type IDedupConfig, type IDescriptionMetadata, type IEndPointConfig, type IEndPointMetadata, type IEntityData, type IEnvType, type IErrorHandlersConfig, type IErrorMonitor, type IErrorMonitorContext, type IExtractChatMessageTextOptions, type IFunctionCall, type IFunctionCallItem, type IGenerateApiKeyReq, type IGenerateApiKeyRes, type IHandshakeMiddleware, type IHandshakeMiddlewareMetadata, type IHtmlModuleOptions, type IHumanMessageItem, type IJobData, type IJobOptions, type IJobRepository, type IJwtRefreshTokenData, type IJwtRefreshTokenRepository, type IKapsoChannelConfig, type IKapsoChannelMessage, type IKapsoChannelMessageListener, type IKapsoChatMessage, type IKapsoConversation, type IKapsoEvent, type IKapsoIncomingMessage, type IKapsoMessageReceivedEvent, type IKapsoReceivedMessage, type IKapsoUnknownEvent, type ILanguageModelUsage, type ILockKey, type ILocker, type ILockerKey, type IMemoryRepositoryAdapterOptions, type IMessageContext, type IMiddleware, type IMiddlewareMetadata, type IMindset, type IMindsetConfig, type IMindsetIdentity, type IMindsetLlm, type IMindsetMetadata, type IMindsetModelKind, type IMindsetModelRef, type IMindsetModels, type IMindsetModuleConfig, type IMindsetModuleMetadata, type IMindsetParameterSchema, type IMindsetTool, type IMindsetToolParameter, type IModelValidationError, type IModelValidationResult, type IModelValidatorsInfo, type IMoneyData, type IPersistentData, type IPgRepositoryConfig, type IProjectRunnerConfig, type IPropertyValidatorInfo, type IQueryAst, type IQueryCondition, type IQueryMethodMetadata, type IQueryOrderBy, type IReceivedMessage, type IRemoteApiKeyFetcher, type IRepositoryAdapter, type IRepositoryConfig, type IRepositoryRuntime, type IRestControllerConfig, type IRestControllerMetadata, type IScanProjectFilesOptions, type IScheduleAt, type IScheduleDelay, type ISendWhatsAppMessageReq, type ISendWhatsAppTemplateReq, type ISocketChannelConfig, type ISocketChannelMessage, type ISocketChannelReceivedMessage, type ISocketControllerConfig, type ISocketControllerMetadata, type ISocketEventConfig, type ISocketEventMetadata, type ISocketReceivedMessage, type IStorableData, type ITelegramChannelConfig, type ITelegramChannelMessage, type ITelegramReceivedMessage, type ITransactionAdapter, type IValidateArrayOptions, type IValidateArrayOptionsWithItemsValidators, type IValidateInputShape, type IValidateIsInOptions, type IValidateIsRecordOptions, type IValidateMaxOptions, type IValidateMinOptions, type IValidationError, type IValidationResult, type IValidator, type IValidatorMetadata, type IWasenderChannelConfig, type IWasenderChannelMessageListener, type IWasenderDeviceListMetadata, type IWasenderEvent, type IWasenderMessageContent, type IWasenderMessageContextInfo, type IWasenderMessageKey, type IWasenderMessageReceivedData, type IWasenderMessageReceivedEvent, type IWasenderQrUpdatedEvent, type IWasenderReceivedMessage, type IWhatsAppCloudContact, type IWhatsAppCloudMessage, type IWhatsAppCloudMessageMetadata, type IWhatsAppCloudTemplate, type IWhatsAppCloudTemplateComponent, type IWhatsAppCloudTemplateResponse, type IWhatsAppCloudWebhookPayload, type IWhatsAppSender, type IWhatsAppTemplateData, type IWhatsAppTemplateParameter, type IchatControllerConfig, InMemoryChatMemory, InMemoryChatRepository, InMemoryCronJobRepository, InMemoryJobRepository, InMemoryLockKey, InMemoryLocker, Job, JobRepository, JobRunner, Jwt, JwtAccessAndRefreshTokenDto, JwtConfig, JwtGuardMiddleware, JwtHandshakeGuardMiddleware, JwtRefreshToken, JwtRefreshTokenRepository, JwtSigner, JwtTokenDto, KapsoChannel, KapsoChannelConfig, KapsoReceiver, KapsoSender, KapsoWebhookController, Lifecycle, Locker, Logger, MEMORY_ADAPTER_ID, Mapper, MemoryRepositoryAdapter, MemoryRepositoryExtension, Mindset, MindsetMetadataStore, MindsetOperator, Money, MoneyDto, OpenRouterChatAdapter, OpenaiChatAdapter, PG_ADAPTER_ID, Password, type PasswordHashOptions, Persistent, PgApiKeyRepository, PgChatMemory, PgChatRepository, PgCronJobRepository, PgCrudRepository, PgJobRepository, PgJsonRepositoryAdapter, PgJwtRefreshTokenRepository, PgLockKey, PgLocker, PgRepositoryBase, PgRepositoryBase as PgRepositoryExtension, PgTransactionAdapter, ProjectRunner, type QueryConnector, type QueryOperator, type QueryPrefix, Random, RemoteApiKeyRepository, RepositoryAdapterRegistry, RepositoryMetadataStore, type ResolvedConfig, RestControllerMetadataStore, RestRequest, SocketChannel, SocketChannelConfig, SocketChannelMessageFile, SocketChannelReceivedMessage, SocketControllerMetadataStore, SocketServerConfig, SocketServerProvider, Storable, TelegramChannel, TelegramChannelConfig, TransactionMetadataStore, UnionChatAdapter, ValidationMetadataStore, WabotChatAdapter, WasenderChannel, WasenderChannelConfig, WasenderReceiver, WasenderSender, WasenderWebhookController, WhatsAppApiSender, WhatsAppReceiverByCloudApi, WhatsAppSender, apiKeyGuard, apiKeyHandshakeGuard, bool, boolArr, buildQuerySql, chatAdapter, chatBot, chatController, chatItemTypeOptions, cmd, cmdChannelName, cmdChannelSocketPath, command, commandHandler, computeDedupKey, container, cronHandler, description, errorToPlainObject, evaluateQueryAst, extractChatMessageText, extractNumberFromWasenderMessageKey, getClientMap, getPgClient, handshakeMiddlewares, inject, injectable, isArray, isBoolean, isChatMessageEmpty, isDate, isIn, isModel, isNotEmpty, isNumber, isOptional, isPresent, isRecord, isRetryableError, isString, jwtGuard, jwtHandshakeGuard, kapso, kapsoChannelName, markdownToTelegramHtml, max, memExtension, middleware, min, mindset, mindsetModule, modelInfo, num, numArr, obj, onDelete, onGet, onPost, onPut, onSocketEvent, parseQueryMethodName, pendingMediaStartIndex, pgExtension, pgStorage, query, queryExtension, readJsonFromFile, repository, resolveConfigReferences, restController, run, runChatAdapters, runChatControllers, runCmdClient, runCommandHandlers, runCronHandlers, runRestControllers, runSocketControllers, safeJsonParse, scanProjectFiles, scoped, setupErrorHandlers, singleton, socket, socketChannelName, socketController, stopCommandHandlers, stopCronHandlers, str, strArr, stripAnsweredMedia, telegram, telegramChannelName, transaction, validateAndTransform, validateArray, validateIsBoolean, validateIsDate, validateIsIn, validateIsNotEmpty, validateIsNumber, validateIsPresent, validateIsRecord, validateIsString, validateMax, validateMin, validateModel, wasender, wasenderChannelName, withPgClient, withPgTransaction, writeJsonToFile };
+export { AnthropicChatAdapter, ApiKey, ApiKeyGuardMiddleware, ApiKeyHandshakeGuardMiddleware, ApiKeyRepository, Async, AsyncMetadataStore, Auth, Chat, ChatAdapter, ChatAdapterMetadataStore, ChatAdapterRegistry, ChatBot, ChatBotMetadataStore, ChatItem, ChatMemory, ChatOperator, ChatRepository, ChatResolver, type ClientMap, CmdChannel, CmdChannelConfig, CmdChannelServer, type CmdClientMessage, type CmdServerMessage, type ConfigReference, type ConfigReferenceType, ConfigResolver, Container, ControllerMetadataStore, CronJob, CronJobRepository, CrudRepository, CustomError, DeepSeekChatAdapter, DescriptionMetadataStore, EXPRESS_REQ, EXPRESS_RES, Entity, Env, type ErrorSeverity, ExpressProvider, GoogleChatAdapter, type GoogleChatAdapterV2Options, HtmlModule, HttpServerProvider, type IApiKeyData, type IApiKeyRepository, type IArrayValidationError, type IArrayValidationResult, type IBotMessageItem, type IBuiltQuery, type IChannelMessage, type IChannelMetadata, type IChatAdapter, type IChatAdapterDecoratorConfig, type IChatAdapterMetadata, type IChatAdapterNextItemsReq, type IChatAdapterNextItemsRes, type IChatAssociation, type IChatBot, type IChatBotMetadata, type IChatChannel, type IChatConnection, type IChatControllerMetadata, type IChatData, type IChatItem, type IChatItemData, type IChatItemType, type IChatMemory, type IChatMessage, type IChatMessageDocument, type IChatMessageFile, type IChatMessageImage, type IChatMessagesPrivateFile, type IChatMessagesPublicFile, type IChatRepository, type IChatType, type ICmdChannelEntry, type ICmdChannelHandlers, type ICmdChannelMessage, type ICmdImage, type ICmdIncomingMessage, type ICmdReceivedMessage, type ICommandConfig, type ICommandHandler, type ICommandHandlerConfig, type IConstructor, type ICronConfig, type ICronHandler, type ICronJobData, type ICronJobRepository, type ICrudRepository, type ICustomErrorData, type IDedupConfig, type IDescriptionMetadata, type IEndPointConfig, type IEndPointMetadata, type IEntityData, type IEnvType, type IErrorHandlersConfig, type IErrorMonitor, type IErrorMonitorContext, type IExtractChatMessageTextOptions, type IFunctionCall, type IFunctionCallItem, type IGenerateApiKeyReq, type IGenerateApiKeyRes, type IHandshakeMiddleware, type IHandshakeMiddlewareMetadata, type IHtmlModuleOptions, type IHumanMessageItem, type IJobData, type IJobOptions, type IJobRepository, type IJwtRefreshTokenData, type IJwtRefreshTokenRepository, type IKapsoChannelConfig, type IKapsoChannelMessage, type IKapsoChannelMessageListener, type IKapsoChatMessage, type IKapsoConversation, type IKapsoEvent, type IKapsoIncomingMessage, type IKapsoMessageReceivedEvent, type IKapsoReceivedMessage, type IKapsoUnknownEvent, type ILanguageModelUsage, type ILockKey, type ILocker, type ILockerKey, type IMemoryRepositoryAdapterOptions, type IMessageContext, type IMiddleware, type IMiddlewareMetadata, type IMindset, type IMindsetConfig, type IMindsetIdentity, type IMindsetLlm, type IMindsetMetadata, type IMindsetModelKind, type IMindsetModelRef, type IMindsetModels, type IMindsetModuleConfig, type IMindsetModuleMetadata, type IMindsetParameterSchema, type IMindsetTool, type IMindsetToolParameter, type IModelValidationError, type IModelValidationResult, type IModelValidatorsInfo, type IMoneyData, type IPersistentData, type IPgRepositoryConfig, type IProjectRunnerConfig, type IPropertyValidatorInfo, type IQueryAst, type IQueryCondition, type IQueryMethodMetadata, type IQueryOrderBy, type IReceivedMessage, type IRegisterRestControllersOptions, type IRemoteApiKeyFetcher, type IRepositoryAdapter, type IRepositoryConfig, type IRepositoryRuntime, type IRestControllerConfig, type IRestControllerMetadata, type IScanProjectFilesOptions, type IScheduleAt, type IScheduleDelay, type ISendWhatsAppMessageReq, type ISendWhatsAppTemplateReq, type ISocketChannelConfig, type ISocketChannelMessage, type ISocketChannelReceivedMessage, type ISocketControllerConfig, type ISocketControllerMetadata, type ISocketEventConfig, type ISocketEventMetadata, type ISocketReceivedMessage, type IStorableData, type ITelegramChannelConfig, type ITelegramChannelMessage, type ITelegramReceivedMessage, type ITransactionAdapter, type IValidateArrayOptions, type IValidateArrayOptionsWithItemsValidators, type IValidateInputShape, type IValidateIsInOptions, type IValidateIsRecordOptions, type IValidateMaxOptions, type IValidateMinOptions, type IValidationError, type IValidationResult, type IValidator, type IValidatorMetadata, type IWasenderChannelConfig, type IWasenderChannelMessageListener, type IWasenderDeviceListMetadata, type IWasenderEvent, type IWasenderMessageContent, type IWasenderMessageContextInfo, type IWasenderMessageKey, type IWasenderMessageReceivedData, type IWasenderMessageReceivedEvent, type IWasenderQrUpdatedEvent, type IWasenderReceivedMessage, type IWhatsAppCloudContact, type IWhatsAppCloudMessage, type IWhatsAppCloudMessageMetadata, type IWhatsAppCloudTemplate, type IWhatsAppCloudTemplateComponent, type IWhatsAppCloudTemplateResponse, type IWhatsAppCloudWebhookPayload, type IWhatsAppSender, type IWhatsAppTemplateData, type IWhatsAppTemplateParameter, type IchatControllerConfig, InMemoryChatMemory, InMemoryChatRepository, InMemoryCronJobRepository, InMemoryJobRepository, InMemoryLockKey, InMemoryLocker, Job, JobRepository, JobRunner, Jwt, JwtAccessAndRefreshTokenDto, JwtConfig, JwtGuardMiddleware, JwtHandshakeGuardMiddleware, JwtRefreshToken, JwtRefreshTokenRepository, JwtSigner, JwtTokenDto, KapsoChannel, KapsoChannelConfig, KapsoReceiver, KapsoSender, KapsoWebhookController, Lifecycle, Locker, Logger, MEMORY_ADAPTER_ID, Mapper, MemoryRepositoryAdapter, MemoryRepositoryExtension, Mindset, MindsetMetadataStore, MindsetOperator, Money, MoneyDto, OpenRouterChatAdapter, OpenaiChatAdapter, PG_ADAPTER_ID, Password, type PasswordHashOptions, Persistent, PgApiKeyRepository, PgChatMemory, PgChatRepository, PgCronJobRepository, PgCrudRepository, PgJobRepository, PgJsonRepositoryAdapter, PgJwtRefreshTokenRepository, PgLockKey, PgLocker, PgRepositoryBase, PgRepositoryBase as PgRepositoryExtension, PgTransactionAdapter, ProjectRunner, type QueryConnector, type QueryOperator, type QueryPrefix, Random, RemoteApiKeyRepository, RepositoryAdapterRegistry, RepositoryMetadataStore, type ResolvedConfig, RestControllerMetadataStore, RestRequest, SocketChannel, SocketChannelConfig, SocketChannelMessageFile, SocketChannelReceivedMessage, SocketControllerMetadataStore, SocketServerConfig, SocketServerProvider, Storable, TelegramChannel, TelegramChannelConfig, TransactionMetadataStore, UnionChatAdapter, ValidationMetadataStore, WabotChatAdapter, WasenderChannel, WasenderChannelConfig, WasenderReceiver, WasenderSender, WasenderWebhookController, WhatsAppApiSender, WhatsAppReceiverByCloudApi, WhatsAppSender, apiKeyGuard, apiKeyHandshakeGuard, bool, boolArr, buildQuerySql, chatAdapter, chatBot, chatController, chatItemTypeOptions, cmd, cmdChannelName, cmdChannelSocketPath, command, commandHandler, computeDedupKey, container, cronHandler, description, errorToPlainObject, evaluateQueryAst, extractChatMessageText, extractNumberFromWasenderMessageKey, getClientMap, getPgClient, handshakeMiddlewares, inject, injectable, isArray, isBoolean, isChatMessageEmpty, isDate, isIn, isModel, isNotEmpty, isNumber, isOptional, isPresent, isRecord, isRetryableError, isString, jwtGuard, jwtHandshakeGuard, kapso, kapsoChannelName, markdownToTelegramHtml, max, memExtension, middleware, min, mindset, mindsetModule, modelInfo, num, numArr, obj, onDelete, onGet, onPost, onPut, onSocketEvent, parseQueryMethodName, pendingMediaStartIndex, pgExtension, pgStorage, prepareChatContainer, query, queryExtension, readJsonFromFile, registerRestControllers, repository, resolveConfigReferences, restController, run, runChatAdapters, runChatControllers, runCmdClient, runCommandHandlers, runCronHandlers, runRestControllers, runSocketControllers, safeJsonParse, scanProjectFiles, scoped, setupErrorHandlers, singleton, socket, socketChannelName, socketController, stopCommandHandlers, stopCronHandlers, str, strArr, stripAnsweredMedia, telegram, telegramChannelName, transaction, validateAndTransform, validateArray, validateIsBoolean, validateIsDate, validateIsIn, validateIsNotEmpty, validateIsNumber, validateIsPresent, validateIsRecord, validateIsString, validateMax, validateMin, validateModel, wasender, wasenderChannelName, withPgClient, withPgTransaction, writeJsonToFile };

package/dist/src/index.js

@@ -84,7 +84,7 @@ export { stripAnsweredMedia } from './feature/chat-bot/stripAnsweredMedia.js';
 export { chatController } from './feature/chat-controller/metadata/controller/@chatController.js';
 export { ControllerMetadataStore } from './feature/chat-controller/metadata/ControllerMetadataStore.js';
 export { ChatResolver } from './feature/chat-controller/ChatResolver.js';
-export { runChatControllers } from './feature/chat-controller/runChatControllers.js';
+export { prepareChatContainer, runChatControllers } from './feature/chat-controller/runChatControllers.js';
 export { ExpressProvider } from './feature/express/ExpressProvider.js';
 export { HttpServerProvider } from './feature/http/HttpServerProvider.js';
 export { mindset } from './feature/mindset/metadata/mindsets/@mindset.js';
@@ -120,7 +120,7 @@ export { onPut } from './feature/rest-controller/metadata/@onPut.js';
 export { onDelete } from './feature/rest-controller/metadata/@onDelete.js';
 export { restController } from './feature/rest-controller/metadata/@restController.js';
 export { RestControllerMetadataStore } from './feature/rest-controller/metadata/RestControllerMetadataStore.js';
-export { runRestControllers } from './feature/rest-controller/runRestControllers.js';
+export { registerRestControllers, runRestControllers } from './feature/rest-controller/runRestControllers.js';
 export { EXPRESS_REQ, EXPRESS_RES } from './feature/rest-controller/injection-tokens.js';
 export { RestRequest } from './feature/rest-controller/RestRequest.js';
 export { SocketServerConfig } from './feature/socket/SocketServerConfig.js';

package/dist/src/testing/LlmJudge.js

@@ -0,0 +1,93 @@
+const VERDICT_TOOL = {
+    language: 'english',
+    name: 'submitVerdict',
+    description: 'Submit your evaluation verdict. You MUST always call this tool exactly once; never answer with plain text.',
+    parameters: [
+        {
+            name: 'pass',
+            required: true,
+            schema: { type: 'boolean', description: 'true if the transcript satisfies the criteria' },
+        },
+        {
+            name: 'reasoning',
+            required: true,
+            schema: { type: 'string', description: 'short explanation of the verdict' },
+        },
+    ],
+};
+const JUDGE_SYSTEM_PROMPT = `
+You are a strict QA judge for chatbot conversations.
+You will receive a chat transcript and evaluation criteria.
+Evaluate whether the transcript satisfies ALL the criteria.
+You MUST report your verdict by calling the submitVerdict tool exactly once.
+Never reply with plain text.
+`;
+function renderTranscript(items) {
+    return items
+        .map((item) => {
+        if (item.type === 'humanMessage') {
+            const msg = item.humanMessage;
+            const parts = [
+                msg.text,
+                msg.images?.length ? `[${msg.images.length} image(s)]` : undefined,
+                msg.documents?.length ? `[${msg.documents.length} document(s)]` : undefined,
+                msg.object ? JSON.stringify(msg.object) : undefined,
+            ].filter(Boolean);
+            return `HUMAN: ${parts.join(' ')}`;
+        }
+        if (item.type === 'botMessage') {
+            return `BOT: ${item.botMessage.text ?? JSON.stringify(item.botMessage)}`;
+        }
+        const call = item.functionCall;
+        return `TOOL CALL: ${call.name}(${call.arguments ?? '{}'}) -> ${call.result ?? '(no result)'}`;
+    })
+        .join('\n');
+}
+/**
+ * Grades chatbot behavior with a real LLM. Provider-agnostic: the verdict is
+ * extracted through a forced tool call instead of parsing free-form text.
+ */
+class LlmJudge {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async evaluate(req) {
+        const transcript = typeof req.transcript === 'string' ? req.transcript : renderTranscript(req.transcript);
+        const { nextItems } = await this.options.adapter.nextItems({
+            models: this.options.models,
+            systemPrompt: JUDGE_SYSTEM_PROMPT,
+            tools: [VERDICT_TOOL],
+            prevItems: [
+                {
+                    type: 'humanMessage',
+                    humanMessage: {
+                        text: `## Criteria\n${req.criteria}\n\n## Transcript\n${transcript}\n\nEvaluate now and call submitVerdict.`,
+                    },
+                },
+            ],
+        });
+        const verdictCall = nextItems.find((item) => item.type === 'functionCall' && item.functionCall.name === VERDICT_TOOL.name);
+        if (!verdictCall || verdictCall.type !== 'functionCall') {
+            const texts = nextItems
+                .map((item) => (item.type === 'botMessage' ? item.botMessage.text : null))
+                .filter(Boolean);
+            throw new Error(`LlmJudge: the judge model did not call submitVerdict. Got: ${texts.join(' | ') || JSON.stringify(nextItems)}`);
+        }
+        const args = JSON.parse(verdictCall.functionCall.arguments ?? '{}');
+        if (typeof args.pass !== 'boolean') {
+            throw new Error(`LlmJudge: invalid verdict arguments: ${verdictCall.functionCall.arguments}`);
+        }
+        return { pass: args.pass, reasoning: String(args.reasoning ?? '') };
+    }
+    /** Like evaluate(), but throws (with the judge's reasoning) when it fails. */
+    async assert(req) {
+        const verdict = await this.evaluate(req);
+        if (!verdict.pass) {
+            throw new Error(`LlmJudge: criteria not satisfied: ${req.criteria}\n${verdict.reasoning}`);
+        }
+        return verdict;
+    }
+}
+
+export { LlmJudge, renderTranscript };

package/dist/src/testing/MockChatAdapter.js

@@ -0,0 +1,68 @@
+/**
+ * Deterministic IChatAdapter for tests: script the LLM turns with
+ * reply()/callTool()/enqueue() and assert on the recorded requests.
+ * Each queued response is consumed by one nextItems() call, so a tool
+ * call turn must be followed by another scripted turn (the ChatBot loop
+ * calls the adapter again after executing the tool).
+ */
+class MockChatAdapter {
+    options;
+    requests = [];
+    queue = [];
+    callIdCounter = 0;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    /** Queue a turn where the bot answers with a plain text message. */
+    reply(text) {
+        return this.enqueue([{ type: 'botMessage', botMessage: { text } }]);
+    }
+    /** Queue a turn where the bot requests a tool call (executed for real by the ChatBot). */
+    callTool(name, args) {
+        return this.enqueue([
+            {
+                type: 'functionCall',
+                functionCall: {
+                    id: `mock-call-${++this.callIdCounter}`,
+                    name,
+                    arguments: typeof args === 'string' ? args : JSON.stringify(args ?? {}),
+                },
+            },
+        ]);
+    }
+    /** Queue a raw turn: a list of chat items, or a function of the request. */
+    enqueue(response) {
+        this.queue.push(response);
+        return this;
+    }
+    get lastRequest() {
+        return this.requests[this.requests.length - 1];
+    }
+    pendingResponses() {
+        return this.queue.length;
+    }
+    async nextItems(req) {
+        this.requests.push(req);
+        let response = this.queue.shift();
+        if (!response) {
+            if (this.options.fallbackReply === undefined) {
+                throw new Error('MockChatAdapter: no scripted response left for this turn. ' +
+                    'Queue one with reply()/callTool()/enqueue(), or set the fallbackReply option. ' +
+                    'Remember that after a callTool() turn the ChatBot calls the adapter again.');
+            }
+            response = [{ type: 'botMessage', botMessage: { text: this.options.fallbackReply } }];
+        }
+        const nextItems = typeof response === 'function' ? await response(req) : response;
+        return {
+            nextItems,
+            usage: {
+                inputTokens: 1,
+                outputTokens: 1,
+                provider: 'mock',
+                model: req.models[0]?.model ?? 'mock-model',
+            },
+        };
+    }
+}
+
+export { MockChatAdapter };

package/dist/src/testing/TestChatMemory.js

@@ -0,0 +1,73 @@
+import { randomUUID } from 'node:crypto';
+import '../feature/chat-bot/ChatAdapterRegistry.js';
+import '../feature/chat-bot/ChatBot.js';
+import { ChatOperator } from '../feature/chat-bot/ChatOperator.js';
+import '../feature/chat-bot/UnionChatAdapter.js';
+import '../core/injection/index.js';
+import '../feature/chat-bot/metadata/ChatAdapterMetadataStore.js';
+import 'uuid';
+import '../feature/chat-bot/metadata/ChatBotMetadataStore.js';
+import '../core/error/setupErrorHandlers.js';
+
+/**
+ * Pure in-RAM chat memory for tests. Unlike the in-memory addon, it never
+ * touches the filesystem and exposes the full item list for assertions.
+ */
+class TestChatMemory {
+    items = [];
+    async findLastItems(count) {
+        return this.items.slice(-count);
+    }
+    async create(item) {
+        if (!item.wasCreated()) {
+            item['data'].id = randomUUID();
+            item['data'].createdAt = Date.now();
+        }
+        this.items.push(item);
+    }
+    all() {
+        return [...this.items];
+    }
+    allData() {
+        return this.items.map((item) => item.getData());
+    }
+    clear() {
+        this.items = [];
+    }
+}
+/** Pure in-RAM chat repository for tests (no `.wabot/` persistence). */
+class TestChatRepository {
+    chats = [];
+    memories = new Map();
+    async create(chat) {
+        if (chat.wasCreated()) {
+            throw new Error('Chat already created');
+        }
+        chat['data'].id = randomUUID();
+        chat['data'].createdAt = Date.now();
+        chat.validate();
+        this.chats.push(chat);
+        this.memories.set(chat.id, new TestChatMemory());
+    }
+    async update(chat) {
+        if (!chat.wasCreated()) {
+            throw new Error('Chat was not created');
+        }
+        chat.validate();
+    }
+    async findByConnection(query) {
+        return this.chats.find((chat) => chat.hasConnection(query)) ?? null;
+    }
+    async findMemory(chatId) {
+        return this.memories.get(chatId) ?? null;
+    }
+    async findOperator(chatId) {
+        const chat = this.chats.find((item) => item.id === chatId) ?? null;
+        const memory = this.memories.get(chatId);
+        if (!chat || !memory)
+            return null;
+        return new ChatOperator(chat, memory, this);
+    }
+}
+
+export { TestChatMemory, TestChatRepository };

package/dist/src/testing/asyncHarness.js

@@ -0,0 +1,66 @@
+import { Auth } from '../core/auth/Auth.js';
+import { container } from '../core/injection/index.js';
+import { AsyncMetadataStore } from '../feature/async/AsyncMetadataStore.js';
+import '../feature/async/TransactionMetadataStore.js';
+import '../feature/async/Async.js';
+import '../_virtual/index.js';
+import '../core/error/setupErrorHandlers.js';
+import 'node:crypto';
+import '../feature/async/JobRepository.js';
+import '../feature/async/JobRunner.js';
+import '../feature/async/JobScheduler.js';
+import '../feature/async/JobWatchdog.js';
+import '../feature/async/CronScheduler.js';
+import { assertValid } from './validation.js';
+import { Container } from '../core/injection/Container.js';
+
+/**
+ * Executes @command handlers and @cronHandler jobs inline — no PostgreSQL,
+ * no polling workers — with the same validation production applies.
+ */
+class AsyncHarness {
+    container;
+    constructor(options = {}) {
+        const child = container.createChildContainer();
+        child.register(Container, { useValue: child });
+        for (const [token, instance] of options.register ?? []) {
+            child.registerInstance(token, instance);
+        }
+        if (options.authInfo) {
+            const auth = child.resolve(Auth);
+            auth.assign(options.authInfo);
+        }
+        this.container = child;
+    }
+    /**
+     * Validate the command data and run its handler immediately, like the
+     * JobRunner does for a scheduled job. Returns the transformed command.
+     */
+    async execute(commandConstructor, data = {}) {
+        const store = container.resolve(AsyncMetadataStore);
+        const commandName = store.getCommandName(commandConstructor);
+        if (!commandName) {
+            throw new Error(`AsyncHarness: ${commandConstructor.name} is not registered with the @command decorator`);
+        }
+        const handlerConstructor = store.getHandlerForCommandName(commandName);
+        if (!handlerConstructor) {
+            throw new Error(`AsyncHarness: no @commandHandler registered for command '${commandName}'`);
+        }
+        const command = assertValid(commandConstructor, data);
+        const handler = this.container.resolve(handlerConstructor);
+        await handler.handle(command);
+        return command;
+    }
+    /** Run a @cronHandler's handle() once, immediately. */
+    async runCron(cronConstructor) {
+        const store = container.resolve(AsyncMetadataStore);
+        store.requireCronMetadata(cronConstructor);
+        const handler = this.container.resolve(cronConstructor);
+        await handler.handle();
+    }
+}
+function createAsyncHarness(options = {}) {
+    return new AsyncHarness(options);
+}
+
+export { AsyncHarness, createAsyncHarness };

package/dist/src/testing/auth.js

@@ -0,0 +1,114 @@
+import jwt from 'jsonwebtoken';
+import '../feature/socket-controller/metadata/SocketControllerMetadataStore.js';
+import '../core/injection/index.js';
+import { CustomError } from '../core/error/CustomError.js';
+import '../core/error/setupErrorHandlers.js';
+import 'debug';
+import '../core/validation/metadata/ValidationMetadataStore.js';
+import 'socket.io';
+import '../feature/socket/SocketServerConfig.js';
+import '../feature/socket/SocketServerProvider.js';
+import '../addon/auth/api-key/ApiKeyHandshakeGuardMiddleware.js';
+import '../feature/rest-controller/metadata/RestControllerMetadataStore.js';
+import '../feature/express/ExpressProvider.js';
+import 'express';
+import 'node:path';
+import 'node:http';
+import '../addon/auth/api-key/ApiKeyGuardMiddleware.js';
+import { ApiKey } from '../addon/auth/api-key/ApiKey.js';
+import { ApiKeyRepository } from '../addon/auth/api-key/ApiKeyRepository.js';
+import '../addon/auth/api-key/PgApiKeyRepository.js';
+import '../addon/auth/jwt/JwtHandshakeGuardMiddleware.js';
+import '../addon/auth/jwt/JwtGuardMiddleware.js';
+import '../addon/auth/jwt/Jwt.js';
+import '../addon/auth/jwt/JwtAccessAndRefreshTokenDto.js';
+import { JwtConfig } from '../addon/auth/jwt/JwtConfig.js';
+import 'node:crypto';
+import '../addon/auth/jwt/JwtSigner.js';
+import '../addon/auth/jwt/JwtTokenDto.js';
+import '../addon/auth/jwt/PgJwtRefreshTokenRepository.js';
+
+/**
+ * JWT setup for tests: a JwtConfig with a test secret (no JWT_SECRET env var
+ * needed) plus a signer, so the real JwtGuardMiddleware validates the tokens.
+ */
+class TestJwt {
+    config;
+    constructor(options = {}) {
+        const config = Object.create(JwtConfig.prototype);
+        config.algorithm = 'HS256';
+        config.secretOrPublicKey = options.secret ?? 'wabot-test-jwt-secret';
+        config.secretOrPrivateKey = options.secret ?? 'wabot-test-jwt-secret';
+        config.accessExpirationSeconds = options.accessExpirationSeconds ?? 10 * 60;
+        config.refreshExpirationSeconds = 365 * 24 * 3600;
+        this.config = config;
+    }
+    /** Sign a valid access token carrying the given authInfo. */
+    sign(authInfo) {
+        return jwt.sign(authInfo, this.config.secretOrPrivateKey, {
+            algorithm: this.config.algorithm,
+            expiresIn: this.config.accessExpirationSeconds,
+        });
+    }
+    /** A token signed with a different secret; useful for 401 tests. */
+    signInvalid(authInfo = {}) {
+        return jwt.sign(authInfo, `${this.config.secretOrPrivateKey}-corrupted`, {
+            algorithm: this.config.algorithm,
+            expiresIn: this.config.accessExpirationSeconds,
+        });
+    }
+}
+function setupTestJwt(options = {}) {
+    return new TestJwt(options);
+}
+/**
+ * In-RAM IApiKeyRepository so the real ApiKeyGuardMiddleware can run in
+ * tests. Register it with: register: [[ApiKeyRepository, testApiKeys]].
+ */
+class TestApiKeyRepository extends ApiKeyRepository {
+    items = [];
+    idCounter = 0;
+    /** Create a key for the given authInfo and return its secret. */
+    async addKey(authInfo, name = 'test-key') {
+        const { secret } = await this.generate({ name, authInfo });
+        return secret;
+    }
+    async find(id) {
+        return this.items.find((item) => item.id === id) ?? null;
+    }
+    async findOrThrow(id) {
+        const item = await this.find(id);
+        if (!item) {
+            throw new CustomError({ message: `Not found ApiKey with id = '${id}'`, httpCode: 404 });
+        }
+        return item;
+    }
+    async findByMetadata(metadata) {
+        return this.items.filter((item) => Object.entries(metadata).every(([key, value]) => item.metadata[key] === value));
+    }
+    async create(item) {
+        if (!item.wasCreated()) {
+            item['data'].id = `test-api-key-${++this.idCounter}`;
+            item['data'].createdAt = Date.now();
+        }
+        this.items.push(item);
+    }
+    async generate(req) {
+        const apiKey = new ApiKey({ name: req.name, metadata: req.metadata, authInfo: req.authInfo });
+        const secret = apiKey.generateSecret();
+        await this.create(apiKey);
+        return { apiKey, secret };
+    }
+    async findBySecret(secret) {
+        return this.items.find((item) => item.isValidSecret(secret)) ?? null;
+    }
+    async findAndValidate(secret) {
+        const apiKey = await this.findBySecret(secret);
+        if (!apiKey) {
+            throw new CustomError({ message: 'Invalid API key', httpCode: 401 });
+        }
+        return apiKey.authInfo;
+    }
+}
+
+export { TestApiKeyRepository, TestJwt, setupTestJwt };