@wabot-dev/framework 0.5.2 → 0.5.4

package/README.md

@@ -6,10 +6,9 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
 [![Documentation](https://img.shields.io/badge/docs-wabot.dev-blue.svg?style=flat-square)](https://docs.wabot.dev)
 
-
 **Un framework moderno y flexible para crear bots con TypeScript e Inteligencia Artificial**
 
-[Documentación](https://docs.wabot.dev) • [Inicio Rápido](https://docs.wabot.dev/guides/start-new-project/) 
+[Documentación](https://docs.wabot.dev) • [Inicio Rápido](https://docs.wabot.dev/guides/start-new-project/)
 
 </div>
 
@@ -43,11 +42,11 @@ visita nuestra documentación 📘 **[Ver guía completa de inicio →](https://
 
 Wabot se integra nativamente con las principales plataformas de mensajería:
 
-| Plataforma | Estado |
-|------------|--------|
+| Plataforma      | Estado       |
+| --------------- | ------------ |
 | 📱 **WhatsApp** | ✅ Soportado |
 | ✈️ **Telegram** | ✅ Soportado |
-| 🔌 **Socket** | ✅ Soportado |
+| 🔌 **Socket**   | ✅ Soportado |
 
 ---
 
@@ -55,11 +54,12 @@ Wabot se integra nativamente con las principales plataformas de mensajería:
 
 Potencia tu bot con los principales proveedores de inteligencia artificial:
 
-| Proveedor | Soporte en Wabot |
-|-----------|------------------|
-| 🟢 **OpenAI** | ✅ Integración completa |
-| 🔵 **Google** | ✅ Integración completa |
+| Proveedor        | Soporte en Wabot        |
+| ---------------- | ----------------------- |
+| 🟢 **OpenAI**    | ✅ Integración completa |
+| 🔵 **Google**    | ✅ Integración completa |
 | 🟣 **Anthropic** | ✅ Integración completa |
+
 ---
 
 ## 📚 Documentación

package/dist/src/addon/auth/jwt/JwtGuardMiddleware.js

@@ -20,7 +20,10 @@ let JwtGuardMiddleware = class JwtGuardMiddleware {
         }
         const parts = authorization.split(' ');
         if (parts.length !== 2) {
-            throw new CustomError({ httpCode: 401, message: 'Authorization header must be: Bearer <token>' });
+            throw new CustomError({
+                httpCode: 401,
+                message: 'Authorization header must be: Bearer <token>',
+            });
         }
         const [bearer, token] = parts;
         if (bearer.toLowerCase() !== 'bearer') {

package/dist/src/addon/chat-bot/google/GoogleChatAdapter.js

@@ -124,7 +124,11 @@ let GoogleChatAdapter = class GoogleChatAdapter {
                 }
                 nextItems.push({
                     type: 'functionCall',
-                    functionCall: { id: id ?? Random.alphaNumericLowerCase(10), name, arguments: args && JSON.stringify(args) },
+                    functionCall: {
+                        id: id ?? Random.alphaNumericLowerCase(10),
+                        name,
+                        arguments: args && JSON.stringify(args),
+                    },
                 });
             }
         }

package/dist/src/addon/chat-controller/whatsapp/WhatsAppChannel.js

@@ -33,7 +33,7 @@ let WhatsAppChannel = class WhatsAppChannel {
                     });
                 }
                 catch (err) {
-                    this.logger.error(err);
+                    this.logger.error('Failed to handle WhatsApp message', err);
                 }
             },
         });

package/dist/src/addon/chat-controller/whatsapp/cloud-api/WhatsAppReceiverByCloudApi.js

@@ -33,7 +33,7 @@ class WhatsAppReceiverByCloudApi extends WhatsAppReceiver {
                 res.status(200).send(challenge);
             }
             catch (e) {
-                this.logger.error(e);
+                this.logger.error('WhatsApp webhook verification failed', e);
                 res.sendStatus(500);
                 return;
             }
@@ -66,7 +66,7 @@ class WhatsAppReceiverByCloudApi extends WhatsAppReceiver {
             }
         }
         catch (err) {
-            this.logger.error(err);
+            this.logger.error('Failed to handle WhatsApp webhook payload', err);
         }
     }
     async emmitMessage(metadata, message, contact) {
@@ -75,7 +75,7 @@ class WhatsAppReceiverByCloudApi extends WhatsAppReceiver {
             return;
         }
         if (message.type !== 'text') {
-            this.logger.error(`message type ${message.type} is not supported yet`);
+            this.logger.warn(`Message type '${message.type}' is not supported yet`);
             return;
         }
         const channelName = 'WhatsAppChannel';

package/dist/src/addon/chat-controller/whatsapp/cloud-api/WhatsAppSenderByCloudApi.js

@@ -114,7 +114,7 @@ let WhatsAppSenderByCloudApi = class WhatsAppSenderByCloudApi extends WhatsAppSe
             return template;
         }
         catch (error) {
-            this.logger.error(error);
+            this.logger.error('Failed to fetch WhatsApp template', error);
             throw error;
         }
     }

package/dist/src/addon/chat-controller/whatsapp/proxy/WhatsAppSenderByWabotProxy.js

@@ -43,7 +43,7 @@ let WhatsAppSenderByWabotProxy = class WhatsAppSenderByWabotProxy extends WhatsA
             }
         }
         catch (err) {
-            this.logger.error(err);
+            this.logger.error(`Failed to send WhatsApp from '${request.from}' to '${request.to}'`, err);
             throw new Error(undefined, { cause: err });
         }
     }

package/dist/src/core/description/metadata/@description.js

@@ -13,7 +13,7 @@ function description(description) {
             propertyType,
             functionArgsTypes,
             functionReturnType: undefined,
-            description
+            description,
         });
     };
 }

package/dist/src/core/env/Env.js

@@ -17,7 +17,7 @@ let Env = class Env {
     }
     requireString(varName, options) {
         const value = process.env[varName] ?? options?.default;
-        if (!value)
+        if (value == null)
             throw new Error(`Env Variable ${varName} is required`);
         return value;
     }

package/dist/src/core/logger/Logger.js

@@ -13,6 +13,30 @@ const levelToSeverity = {
     error: 'error',
     fatal: 'fatal',
 };
+/**
+ * Logger with 6 severity levels. Uses the `debug` library for output.
+ *
+ * ## Level verbosity contract
+ *
+ * - **fatal** — The process cannot continue. Something is critically broken
+ *   (uncaught exceptions, unhandled rejections). Investigate immediately.
+ *
+ * - **error** — An operation failed unexpectedly. Always include: what failed,
+ *   why (the Error), and enough context to locate the problem (IDs, names).
+ *
+ * - **warn** — Something unusual happened but the system handled it gracefully.
+ *   Known limitations, safety guards triggered, recoverable issues.
+ *
+ * - **info** — Key lifecycle events the user cares about: systems starting or
+ *   stopping, configuration applied, significant state changes. Should read
+ *   like a high-level audit log.
+ *
+ * - **debug** — Internal operational details for developers troubleshooting.
+ *   Step-by-step flow, lock acquisition, query execution, reconciliation steps.
+ *
+ * - **trace** — Very fine-grained: every HTTP request, every socket event,
+ *   every message sent or received.
+ */
 class Logger {
     static monitor = null;
     debuggers;
@@ -32,21 +56,27 @@ class Logger {
     static getMonitor() {
         return Logger.monitor;
     }
+    /** Very fine-grained: every HTTP request, socket event, message sent/received. */
     trace(...args) {
         this.log('trace', args);
     }
+    /** Internal operational details for developers: step-by-step flow, lock acquisition, queries. */
     debug(...args) {
         this.log('debug', args);
     }
+    /** Key lifecycle events: systems start/stop, configuration applied, significant state changes. */
     info(...args) {
         this.log('info', args);
     }
+    /** Something unusual happened but the system recovered. Known limitations, safety guards. */
     warn(...args) {
         this.log('warn', args);
     }
+    /** Operation failed unexpectedly. Always include: what failed + why (Error) + identifiers. */
     error(...args) {
         this.log('error', args);
     }
+    /** Process cannot continue. Uncaught exceptions, unhandled rejections. Investigate immediately. */
     fatal(...args) {
         this.log('fatal', args);
     }

package/dist/src/core/validation/metadata/@isArray.js

@@ -11,7 +11,7 @@ function isArray(options) {
             propertyName,
             validator: validateArray,
             validatorOptions: options,
-            typeDescriptor: 'array'
+            typeDescriptor: 'array',
         });
     };
 }

package/dist/src/core/validation/metadata/@isModel.js

@@ -11,7 +11,7 @@ function isModel(model) {
             propertyName,
             validator: validateModel,
             validatorOptions: store.getModelValidatorsInfo(model),
-            typeDescriptor: 'object'
+            typeDescriptor: 'object',
         });
     };
 }

package/dist/src/core/validation/validators/is-date/@isDate.js

@@ -10,7 +10,7 @@ function isDate() {
             modelConstructor: target.constructor,
             propertyName,
             validator: validateIsDate,
-            typeDescriptor: 'date'
+            typeDescriptor: 'date',
         });
     };
 }

package/dist/src/core/validation/validators/is-number/@isNumber.js

@@ -10,7 +10,7 @@ function isNumber() {
             modelConstructor: target.constructor,
             propertyName,
             validator: validateIsNumber,
-            typeDescriptor: 'number'
+            typeDescriptor: 'number',
         });
     };
 }

package/dist/src/core/validation/validators/is-string/@isString.js

@@ -10,7 +10,7 @@ function isString() {
             modelConstructor: target.constructor,
             propertyName,
             validator: validateIsString,
-            typeDescriptor: 'string'
+            typeDescriptor: 'string',
         });
     };
 }

package/dist/src/feature/async/CronScheduler.js

@@ -60,12 +60,12 @@ let CronScheduler = class CronScheduler {
         this.logger.debug(`start reconciliation of crons ${configToReconciliate.map((x) => x.name).join(', ')}`);
         try {
             const cronJobs = await Promise.all(configToReconciliate.map((x) => this.reconciliateConfig(x)));
-            this.logger.info(`success reconciliation of reconciliation of crons ${configToReconciliate.map((x) => x.name).join(', ')}`);
+            this.logger.info(`Cron reconciliation succeeded for ${configToReconciliate.map((x) => x.name).join(', ')}`);
             this.jobScheduler.start(cronJobs.map((x) => x.commandName));
             this.jobWatchdog.start(cronJobs.map((x) => x.commandName));
         }
         catch (e) {
-            this.logger.error(e);
+            this.logger.error('Cron reconciliation failed', e);
             this.stop(configToReconciliate);
             this.logger.error(`reconciliation fail - stopped crons ${configToReconciliate.map((x) => x.name).join(', ')}`);
             throw e;
@@ -88,7 +88,7 @@ let CronScheduler = class CronScheduler {
             });
         }
         catch (e) {
-            this.logger.error(e);
+            this.logger.error('Cron tick failed', e);
         }
         finally {
             this.timeout = setTimeout(() => this.tick(), interval * 1000);

package/dist/src/feature/async/JobRunner.js

@@ -45,7 +45,7 @@ let JobRunner = class JobRunner {
             job.setAsSuccess();
         }
         catch (e) {
-            this.logger.error(e);
+            this.logger.error(`Failed to run command '${job.commandName}'`, e);
             job.setAsFailed(e instanceof Error ? e : new Error('Invalid Job error'));
         }
         finally {

package/dist/src/feature/async/JobScheduler.js

@@ -22,16 +22,15 @@ let JobScheduler = class JobScheduler {
         this.env = env;
     }
     start(commands) {
-        this.logger.info(`starting handlers for commands ${commands}`);
         commands.forEach((x) => this.commands.add(x));
-        this.logger.info(`starting job handlers for commands ${commands.join(', ')}`);
+        this.logger.info(`Starting job handlers for commands ${commands.join(', ')}`);
         if (this.commands.size > 0 && !this.running) {
             this.running = true;
             this.tick();
         }
     }
     stop(commands) {
-        this.logger.info(`stoping handlers for commands ${commands}`);
+        this.logger.info(`Stopping job handlers for commands ${commands.join(', ')}`);
         commands.forEach((x) => this.commands.delete(x));
         if (this.commands.size === 0) {
             this.running = false;
@@ -42,7 +41,9 @@ let JobScheduler = class JobScheduler {
     }
     tryExecuteNow(job) {
         if (this.commands.has(job.commandName))
-            this.executor.execute(job).catch((e) => this.logger.error(e));
+            this.executor
+                .execute(job)
+                .catch((e) => this.logger.error(`Failed to execute job ${job.id}`, e));
     }
     async tick() {
         if (!this.running)
@@ -57,12 +58,14 @@ let JobScheduler = class JobScheduler {
             await this.locker.withKey('wabot-job-scheduler-loop').run(async () => {
                 const jobs = await this.repo.findPendingForRunFrom(new Date(), this.executor.remainingSlots());
                 const readyToRunJobs = jobs.filter((job) => this.commands.has(job.commandName) && job.isScheduleReady());
-                readyToRunJobs.forEach((j) => this.executor.execute(j).catch((e) => this.logger.error(e)));
+                readyToRunJobs.forEach((j) => this.executor
+                    .execute(j)
+                    .catch((e) => this.logger.error(`Failed to execute job ${j.id}`, e)));
                 await new Promise((r) => setTimeout(r, 10));
             });
         }
         catch (e) {
-            this.logger.error(e);
+            this.logger.error('Job scheduler tick failed', e);
         }
         finally {
             this.timeout = setTimeout(() => this.tick(), interval * 1000);

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

@@ -1,9 +1,9 @@
 class ChatMemory {
     findLastItems(count) {
-        throw new Error("Method not implemented.");
+        throw new Error('Method not implemented.');
     }
     create(item) {
-        throw new Error("Method not implemented.");
+        throw new Error('Method not implemented.');
     }
 }
 

package/dist/src/feature/http/HttpServerProvider.js

@@ -20,7 +20,7 @@ let HttpServerProvider = class HttpServerProvider {
         this.listening = true;
         const PORT = process.env.PORT || 3000;
         this.server.listen(PORT, () => {
-            this.logger.info(`server listenig on port ${PORT}`);
+            this.logger.info(`Server listening on port ${PORT}`);
         });
     }
 };

package/dist/src/feature/pg/PgLockKey.js

@@ -16,9 +16,9 @@ class PgLockKey {
         return withPgClient(this.pool, async (client) => {
             let locked = false;
             try {
-                this.logger.debug(`try to adquire ${this.key}`);
+                this.logger.debug(`try to acquire ${this.key}`);
                 await client.query('SELECT pg_advisory_lock($1)', [this.value]);
-                this.logger.debug(`adquired ${this.key}`);
+                this.logger.debug(`acquired ${this.key}`);
                 locked = true;
                 return await fn();
             }
@@ -27,7 +27,7 @@ class PgLockKey {
                     this.logger.debug(`try to release ${this.key}`);
                     const res = await client.query('SELECT pg_advisory_unlock($1) AS unlocked', [this.value]);
                     if (!res.rows[0]?.unlocked) {
-                        this.logger.error('error - no unlock');
+                        this.logger.error(`Failed to release lock '${this.key}'`);
                     }
                     else {
                         this.logger.debug(`released ${this.key}`);
@@ -50,7 +50,7 @@ class PgLockKey {
                 if (locked) {
                     const res = await client.query('SELECT pg_advisory_unlock($1) AS unlocked', [this.value]);
                     if (!res.rows[0]?.unlocked) {
-                        this.logger.error('error - no unlock');
+                        this.logger.error(`Failed to release lock '${this.key}'`);
                     }
                 }
             }

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

@@ -68,7 +68,7 @@ function runRestControllers(controllers) {
                     res.status(200).json(response ?? null);
                 }
                 catch (err) {
-                    logger.error(err);
+                    logger.error(`${method.toUpperCase()} ${route} failed`, err);
                     if (err instanceof Error) {
                         const keys = Object.keys(err).filter((key) => !['message', 'stack'].includes(key));
                         const { httpCode, ...info } = keys.reduce((acc, key) => {

package/dist/src/feature/socket-controller/runSocketControllers.js

@@ -70,7 +70,7 @@ function runSocketControllers(controllers) {
                 }
             }
             catch (err) {
-                logger.error(err);
+                logger.error(`Event '${event.config.event}' on '${namespace}' failed`, err);
                 if (err instanceof Error) {
                     const keys = Object.keys(err).filter((key) => !['message', 'stack'].includes(key));
                     const { httpCode, ...info } = keys.reduce((acc, key) => {
@@ -108,7 +108,7 @@ function runSocketControllers(controllers) {
                 }
             }
             catch (err) {
-                logger.error(err);
+                logger.error(`Connection setup on '${namespace}' failed`, err);
                 socket.disconnect();
                 connectionContainer.dispose();
             }

package/dist/src/index.d.ts

@@ -129,6 +129,30 @@ interface IErrorMonitor {
     captureMessage(message: string, context: IErrorMonitorContext): void;
 }
 
+/**
+ * Logger with 6 severity levels. Uses the `debug` library for output.
+ *
+ * ## Level verbosity contract
+ *
+ * - **fatal** — The process cannot continue. Something is critically broken
+ *   (uncaught exceptions, unhandled rejections). Investigate immediately.
+ *
+ * - **error** — An operation failed unexpectedly. Always include: what failed,
+ *   why (the Error), and enough context to locate the problem (IDs, names).
+ *
+ * - **warn** — Something unusual happened but the system handled it gracefully.
+ *   Known limitations, safety guards triggered, recoverable issues.
+ *
+ * - **info** — Key lifecycle events the user cares about: systems starting or
+ *   stopping, configuration applied, significant state changes. Should read
+ *   like a high-level audit log.
+ *
+ * - **debug** — Internal operational details for developers troubleshooting.
+ *   Step-by-step flow, lock acquisition, query execution, reconciliation steps.
+ *
+ * - **trace** — Very fine-grained: every HTTP request, every socket event,
+ *   every message sent or received.
+ */
 declare class Logger {
     private static monitor;
     private debuggers;
@@ -136,11 +160,17 @@ declare class Logger {
     constructor(name: string);
     static setMonitor(monitor: IErrorMonitor): void;
     static getMonitor(): IErrorMonitor | null;
+    /** Very fine-grained: every HTTP request, socket event, message sent/received. */
     trace(...args: any[]): void;
+    /** Internal operational details for developers: step-by-step flow, lock acquisition, queries. */
     debug(...args: any[]): void;
+    /** Key lifecycle events: systems start/stop, configuration applied, significant state changes. */
     info(...args: any[]): void;
+    /** Something unusual happened but the system recovered. Known limitations, safety guards. */
     warn(...args: any[]): void;
+    /** Operation failed unexpectedly. Always include: what failed + why (Error) + identifiers. */
     error(...args: any[]): void;
+    /** Process cannot continue. Uncaught exceptions, unhandled rejections. Investigate immediately. */
     fatal(...args: any[]): void;
     private log;
     private sendToMonitor;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wabot-dev/framework",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "description": "Framework for IA Chat Bots",
   "type": "module",
   "main": "dist/src/index.js",