@green-api/greenapi-integration 0.4.0 → 0.6.0

package/README.md

@@ -39,10 +39,12 @@ npm install @green-api/greenapi-integration
 The foundation of your integration. Handles message & instance management, and platform-specific logic.
 
 ```typescript
-abstract class BaseAdapter<TPlatformWebhook, TPlatformMessage> {
+abstract class BaseAdapter<TPlatformWebhook, TPlatformMessage, TUser extends BaseUser = BaseUser, TInstance extends Instance = Instance> {
+	private readonly gaLogger = GreenApiLogger.getInstance(this.constructor.name);
+
 	public constructor(
 		transformer: MessageTransformer<TPlatformWebhook, TPlatformMessage>,
-		storage: StorageProvider
+		storage: StorageProvider<TUser, TInstance>,
 	);
 
 	public abstract createPlatformClient(params: any): Promise<any>;
@@ -58,8 +60,7 @@ When extending BaseAdapter, your implementation has access to several methods:
 ##### Webhook Handling
 
 These webhook handling methods call your message transformation methods automatically, without the need to use them
-directly in
-your code.
+directly in your code.
 
 ```typescript
 // Handle webhooks from your platform
@@ -140,18 +141,23 @@ abstract class MessageTransformer<TPlatformWebhook, TPlatformMessage> {
 Interface for data persistence operations.
 
 ```typescript
-abstract class StorageProvider<TUser extends BaseUser = BaseUser, TInstance extends BaseInstance = Instance> {
-	abstract createInstance(instance: BaseInstance, userId: bigint | number): Promise<TInstance>;
+abstract class StorageProvider<
+	TUser extends BaseUser = BaseUser,
+	TInstance extends Instance = Instance,
+	TUserCreate extends Record<string, any> = any,
+	TUserUpdate extends Record<string, any> = any
+> {
+	abstract createInstance(instance: Instance): Promise<TInstance>;
 
 	abstract getInstance(idInstance: number | bigint): Promise<TInstance | null>;
 
 	abstract removeInstance(instanceId: number | bigint): Promise<TInstance>;
 
-	abstract createUser(data: any): Promise<TUser>;
+	abstract createUser(data: TUserCreate): Promise<TUser>;
 
 	abstract findUser(identifier: string): Promise<TUser | null>;
 
-	abstract updateUser(identifier: string, data: any): Promise<TUser>;
+	abstract updateUser(identifier: string, data: Partial<TUserUpdate>): Promise<TUser>;
 }
 ```
 
@@ -161,6 +167,8 @@ Handles webhook authentication for incoming GREEN-API requests.
 
 ```typescript
 abstract class BaseGreenApiAuthGuard<T extends BaseRequest = BaseRequest> {
+	private readonly gaLogger = GreenApiLogger.getInstance(this.constructor.name);
+
 	constructor(protected storage: StorageProvider);
 
 	// Validates incoming webhook requests
@@ -193,7 +201,196 @@ app.post('/webhook', async (req, res) => {
 });
 ```
 
-### 5. GreenApiClient
+### 5. GreenApiLogger
+
+A structured JSON logger with colored output. Provides consistent logging format across your application with
+proper error handling and serialization support.
+
+```typescript
+const logger = GreenApiLogger.getInstance("YourComponent");
+
+// Basic logging
+logger.debug("Debug message", {someContext: "value"});
+logger.info("Info message", {userId: 123});
+logger.warn("Warning message", {alert: true});
+logger.error("Error occurred", {errorCode: 500});
+logger.fatal("Fatal error", {critical: true});
+
+// Error logging with full context
+try {
+	await someOperation();
+} catch (error) {
+	logger.logErrorResponse(error, "Operation failed", {
+		operationId: "123",
+		additionalInfo: "some context"
+	});
+}
+```
+
+#### Features
+
+- Structured JSON logging with consistent format
+- Colored output based on log level (debug=cyan, info=green, warn=yellow, error=red, fatal=magenta)
+- Built-in error handling with stack trace formatting
+- Automatic serialization
+- Framework agnostic - works with any Node.js application
+- Special handling for Axios errors with detailed request/response info
+
+#### Log Levels
+
+- `debug` - Detailed information for debugging
+- `info` - General information about system operation
+- `warn` - Warning messages for potentially harmful situations
+- `error` - Error messages for serious problems
+- `fatal` - Critical errors that require immediate attention
+- `log` - Alternative to info (for compatibility)
+
+#### Output Format
+
+```json
+{
+  "timestamp": "30/01/2025, 04:34:49",
+  "level": "error",
+  "context": "CoreService",
+  "message": "Operation failed",
+  "error": "Failed to process request",
+  "stack": [
+    "Error: Failed to process request",
+    "    at CoreService.process (/app/service.js:123:45)",
+    "    at async Router.handle (/app/router.js:67:89)"
+  ],
+  "additionalContext": {
+    "requestId": "abc-123",
+    "userId": "user_456"
+  }
+}
+```
+
+#### Error Handling
+
+```typescript
+// Axios error handling
+try {
+	await apiRequest();
+} catch (error) {
+	logger.logErrorResponse(error, "API Request failed", {
+		endpoint: "/users",
+		method: "POST"
+	});
+}
+```
+
+// Will output detailed API error info:
+
+```
+{
+    "timestamp": "30/01/2025, 04:34:49",
+    "level": "error",
+    "context": "ApiService",
+    "message": "API Request failed - API Error:",
+    "status": 400,
+    "statusText": "Bad Request",
+    "data": { "error": "Invalid input" },
+    "url": "https://api.example.com/users",
+    "method": "POST",
+    "endpoint": "/users"
+}
+```
+
+#### Using with Frameworks
+
+The logger is framework-agnostic but can be easily integrated with any framework:
+
+```typescript
+// NestJS example
+const app = await NestFactory.create(AppModule, {
+	logger: GreenApiLogger.getInstance("NestJS")
+});
+
+// Express example
+app.use((err, req, res, next) => {
+	const logger = GreenApiLogger.getInstance("Express");
+	logger.error("Request failed", {
+		path: req.path,
+		method: req.method,
+		error: err.message
+	});
+	next(err);
+});
+```
+
+#### Methods
+
+##### Basic Logging Methods
+
+- `debug(message: string, context?: Record<string, any>)`: Log debug level message
+- `info(message: string, context?: Record<string, any>)`: Log info level message
+- `warn(message: string, context?: Record<string, any>)`: Log warning level message
+- `error(message: string, context?: Record<string, any>)`: Log error level message
+- `fatal(message: string, context?: Record<string, any>)`: Log fatal level message
+- `log(message: string, context?: string)`: Alternative to info method
+
+##### Special Methods
+
+- `logErrorResponse(error: any, context: string, additionalContext?: Record<string, any>)`:
+  Enhanced error logging with special handling for Axios errors and stack traces
+
+##### Utility Methods
+
+- `getInstance(context: string = "Global"): GreenApiLogger`: Get or create logger instance for specified context
+
+#### Best Practices
+
+1. **Use Consistent Context Names**
+
+```typescript
+// In your component/service
+private readonly logger = GreenApiLogger.getInstance(YourService.name);
+```
+
+2. **Include Relevant Context**
+
+```typescript
+logger.info("User action completed", {
+	userId: user.id,
+	action: "profile_update",
+	duration: timeTaken
+});
+```
+
+3. **Proper Error Handling**
+
+```typescript
+try {
+	await complexOperation();
+} catch (error) {
+	logger.logErrorResponse(error, "Complex operation failed", {
+		operationId: id,
+		parameters: params
+	});
+}
+```
+
+4. **Use Appropriate Log Levels**
+
+```typescript
+// Debug for detailed information
+logger.debug("Processing chunk", {chunkId: 123, size: 1024});
+
+// Info for general operation
+logger.info("User logged in", {userId: 456});
+
+// Warn for potential issues
+logger.warn("High memory usage", {memoryUsage: "85%"});
+
+// Error for actual problems
+logger.error("Database connection failed", {dbHost: "primary"});
+
+// Fatal for critical issues
+logger.fatal("System shutdown required", {reason: "data corruption"});
+```
+
+### 6. GreenApiClient
 
 Direct interface to GREEN-API methods.
 
@@ -324,12 +521,16 @@ export class YourStorage extends StorageProvider {
 		this.db = new PrismaClient();
 	}
 
-	async createInstance(instance: Instance, userId: bigint) {
+	async findUserByEmail(email: string) {
+		return this.db.user.findUnique({where: {email}});
+	}
+
+	async createInstance(instance: Instance) {
 		return this.db.instance.create({
 			data: {
 				idInstance: instance.idInstance,
 				apiTokenInstance: instance.apiTokenInstance,
-				userId,
+				userId: instance.userId,
 				settings: instance.settings || {},
 			},
 		});
@@ -427,6 +628,7 @@ router.post('/instance', async (req, res) => {
 			throw new BadRequestError('Required fields missing');
 		}
 
+		const user = await storage.findUserByEmail(userEmail);
 		const instance = await adapter.createInstance({
 			idInstance: Number(idInstance),
 			apiTokenInstance,
@@ -434,8 +636,9 @@ router.post('/instance', async (req, res) => {
 				webhookUrl: `${process.env.APP_URL}/webhook/green-api`,
 				webhookUrlToken: `token_${Date.now()}`,
 				incomingWebhook: 'yes'
-			}
-		}, userEmail);
+			},
+			userId: user.id
+		});
 
 		res.status(200).json({
 			status: 'ok',
@@ -845,10 +1048,10 @@ isValidSettingValue('webhookUrl', 'https://example.com') // Returns true
 
 // Clean settings
 const input = {
- webhookUrl: 'https://example.com',
- outgoingWebhook: 'yes', 
- invalidKey: 'value',
- delaySendMessagesMilliseconds: 'invalid'
+	webhookUrl: 'https://example.com',
+	outgoingWebhook: 'yes',
+	invalidKey: 'value',
+	delaySendMessagesMilliseconds: 'invalid'
 }
 validateAndCleanSettings(input) // Returns { webhookUrl: 'https://example.com', outgoingWebhook: 'yes' }
 ```

package/README.ru.md

@@ -192,10 +192,202 @@ app.post('/webhook', async (req, res) => {
 });
 ```
 
-### 5. GreenApiClient
+### 5. GreenApiLogger
 
-Прямой интерфейс к эндпоинтам GREEN-API. Хотя большинство операций должны выполняться через BaseAdapter, GreenApiClient
-может использоваться напрямую для операций, непокрытых в `BaseAdapter`.
+Структурированный JSON-логгер с цветным выводом. Обеспечивает единый формат логирования в вашем приложении с корректной
+обработкой ошибок и сериализацией.
+
+```typescript
+const logger = GreenApiLogger.getInstance("YourComponent");
+
+// Базовое логирование
+logger.debug("Debug message", {someContext: "value"});
+logger.info("Info message", {userId: 123});
+logger.warn("Warning message", {alert: true});
+logger.error("Error occurred", {errorCode: 500});
+logger.fatal("Fatal error", {critical: true});
+
+// Логирование ошибок с контекстом
+try {
+	await someOperation();
+} catch (error) {
+	logger.logErrorResponse(error, "Operation failed", {
+		operationId: "123",
+		additionalInfo: "some context"
+	});
+}
+```
+
+#### Возможности
+
+- Структурированное JSON-логирование в едином формате
+- Цветной вывод в зависимости от уровня лога (debug=голубой, info=зеленый, warn=желтый, error=красный, fatal=пурпурный)
+- Встроенная обработка ошибок с форматированием стека вызовов
+- Автоматическая сериализация
+- Независимость от фреймворка - работает с любым Node.js приложением
+- Специальная обработка ошибок Axios с подробной информацией о запросе/ответе
+
+#### Уровни логирования
+
+- `debug` - Подробная информация для отладки
+- `info` - Общая информация о работе системы
+- `warn` - Предупреждения о потенциально опасных ситуациях
+- `error` - Сообщения об ошибках
+- `fatal` - Критические ошибки, требующие немедленного внимания
+- `log` - Альтернатива info (для совместимости)
+
+#### Формат вывода
+
+```json
+{
+  "timestamp": "30/01/2025, 04:34:49",
+  "level": "error",
+  "context": "CoreService",
+  "message": "Operation failed",
+  "error": "Failed to process request",
+  "stack": [
+    "Error: Failed to process request",
+    "    at CoreService.process (/app/service.js:123:45)",
+    "    at async Router.handle (/app/router.js:67:89)"
+  ],
+  "additionalContext": {
+    "requestId": "abc-123",
+    "userId": "user_456"
+  }
+}
+```
+
+#### Обработка ошибок
+
+```typescript
+// Обработка ошибок Axios
+try {
+	await apiRequest();
+} catch (error) {
+	logger.logErrorResponse(error, "API Request failed", {
+		endpoint: "/users",
+		method: "POST"
+	});
+}
+```
+
+// Получим подробную информацию об ошибке API:
+
+```json
+{
+  "timestamp": "30/01/2025, 04:34:49",
+  "level": "error",
+  "context": "ApiService",
+  "message": "API Request failed - API Error:",
+  "status": 400,
+  "statusText": "Bad Request",
+  "data": {
+    "error": "Invalid input"
+  },
+  "url": "https://api.example.com/users",
+  "method": "POST",
+  "endpoint": "/users"
+}
+```
+
+#### Использование с фреймворками
+
+Логгер независим от фреймворков, но легко интегрируется с любым из них:
+
+```typescript
+// Пример с NestJS
+const app = await NestFactory.create(AppModule, {
+	logger: GreenApiLogger.getInstance("NestJS")
+});
+
+// Пример с Express
+app.use((err, req, res, next) => {
+	const logger = GreenApiLogger.getInstance("Express");
+	logger.error("Request failed", {
+		path: req.path,
+		method: req.method,
+		error: err.message
+	});
+	next(err);
+});
+```
+
+#### Методы
+
+##### Основные методы логирования
+
+- `debug(message: string, context?: Record<string, any>)`: Логирование отладочной информации
+- `info(message: string, context?: Record<string, any>)`: Логирование информационных сообщений
+- `warn(message: string, context?: Record<string, any>)`: Логирование предупреждений
+- `error(message: string, context?: Record<string, any>)`: Логирование ошибок
+- `fatal(message: string, context?: Record<string, any>)`: Логирование критических ошибок
+- `log(message: string, context?: string)`: Альтернатива методу info
+
+##### Специальные методы
+
+- `logErrorResponse(error: any, context: string, additionalContext?: Record<string, any>)`:
+  Расширенное логирование ошибок со специальной обработкой ошибок Axios и стека вызовов
+
+##### Вспомогательные методы
+
+- `getInstance(context: string = "Global"): GreenApiLogger`: Получение или создание экземпляра логгера для указанного
+  контекста
+
+#### Лучшие практики
+
+1. **Используйте последовательные имена контекста**
+
+```typescript
+// В вашем компоненте/сервисе
+private readonly
+logger = GreenApiLogger.getInstance(YourService.name);
+```
+
+2. **Включайте релевантный контекст**
+
+```typescript
+logger.info("User action completed", {
+	userId: user.id,
+	action: "profile_update",
+	duration: timeTaken
+});
+```
+
+3. **Правильная обработка ошибок**
+
+```typescript
+try {
+	await complexOperation();
+} catch (error) {
+	logger.logErrorResponse(error, "Complex operation failed", {
+		operationId: id,
+		parameters: params
+	});
+}
+```
+
+4. **Используйте соответствующие уровни логирования**
+
+```typescript
+// Debug для детальной информации
+logger.debug("Processing chunk", {chunkId: 123, size: 1024});
+
+// Info для общей информации о работе
+logger.info("User logged in", {userId: 456});
+
+// Warn для потенциальных проблем
+logger.warn("High memory usage", {memoryUsage: "85%"});
+
+// Error для реальных проблем
+logger.error("Database connection failed", {dbHost: "primary"});
+
+// Fatal для критических проблем
+logger.fatal("System shutdown required", {reason: "data corruption"});
+```
+
+### 6. GreenApiClient
+
+Прямой интерфейс к методам GREEN-API.
 
 ```typescript
 const client = new GreenApiClient({
@@ -209,7 +401,7 @@ await client.getAuthorizationCode(phoneNumber);
 await client.getQR();
 ```
 
-## Руководство разработчика
+## Руководство для разработчика
 
 Это руководство проведет вас через процесс создания вашей первой интеграции с WhatsApp шлюзом GREEN-API.
 
@@ -615,7 +807,13 @@ interface SimplePlatformMessage {
 ### simple-transformer.ts
 
 ```typescript
-import { MessageTransformer, Message, GreenApiWebhook, formatPhoneNumber, IntegrationError } from '@green-api/greenapi-integration';
+import {
+	MessageTransformer,
+	Message,
+	GreenApiWebhook,
+	formatPhoneNumber,
+	IntegrationError
+} from '@green-api/greenapi-integration';
 
 export class SimpleTransformer extends MessageTransformer<SimplePlatformWebhook, SimplePlatformMessage> {
 	toPlatformMessage(webhook: GreenApiWebhook): SimplePlatformMessage {

package/dist/core/base-adapter.d.ts

@@ -2,6 +2,7 @@ import { GreenApiClient } from "./green-api.client";
 import { MessageTransformer } from "./message-transformer";
 import { BaseUser, ForwardMessagesResponse, GreenApiWebhook, Instance, SendResponse, StateInstanceWebhook, WebhookType } from "../types/types";
 import { StorageProvider } from "./storage-provider";
+import { GreenApiLogger } from "./logger";
 /**
  * Base adapter for platform integrations with GREEN-API.
  * This class handles the core integration logic between your platform and GREEN-API's WhatsApp gateway.
@@ -29,13 +30,14 @@ import { StorageProvider } from "./storage-provider";
 export declare abstract class BaseAdapter<TPlatformWebhook, TPlatformMessage, TUser extends BaseUser = BaseUser, TInstance extends Instance = Instance> {
     protected transformer: MessageTransformer<TPlatformWebhook, TPlatformMessage>;
     protected storage: StorageProvider<TUser, TInstance>;
+    protected readonly gaLogger: GreenApiLogger;
     /**
      * Creates an instance of BaseAdapter.
      *
      * @param transformer - Message transformer for converting between platform and GREEN-API formats
      * @param storage - Storage provider for user and instance data
      */
-    constructor(transformer: MessageTransformer<TPlatformWebhook, TPlatformMessage>, storage: StorageProvider<TUser, TInstance>);
+    protected constructor(transformer: MessageTransformer<TPlatformWebhook, TPlatformMessage>, storage: StorageProvider<TUser, TInstance>);
     /**
      * Sends a message to your platform. This method must be implemented to define how
      * messages are sent to your specific platform.
@@ -120,12 +122,11 @@ export declare abstract class BaseAdapter<TPlatformWebhook, TPlatformMessage, TU
      * Creates a new instance with specified settings.
      *
      * @param instance - The instance configuration
-     * @param userCred - User credentials
      * @returns Promise resolving to the created instance
      * @throws {NotFoundError} If user is not found
      * @throws {IntegrationError} If instance creation fails
      */
-    createInstance(instance: Instance, userCred: any): Promise<TInstance>;
+    createInstance(instance: Instance): Promise<TInstance>;
     /**
      * Removes an instance by ID.
      *
@@ -157,8 +158,6 @@ export declare abstract class BaseAdapter<TPlatformWebhook, TPlatformMessage, TU
      *
      * @param userCred - User credentials
      * @param data - User data
-     * @throws {BadRequestError} If user already exists
-     * @throws {IntegrationError} If creation fails
      */
     createUser(userCred: any, data: any): Promise<TUser>;
 }

package/dist/core/base-adapter.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.BaseAdapter = void 0;
 const green_api_client_1 = require("./green-api.client");
 const errors_1 = require("./errors");
+const logger_1 = require("./logger");
 /**
  * Base adapter for platform integrations with GREEN-API.
  * This class handles the core integration logic between your platform and GREEN-API's WhatsApp gateway.
@@ -37,6 +38,7 @@ class BaseAdapter {
     constructor(transformer, storage) {
         this.transformer = transformer;
         this.storage = storage;
+        this.gaLogger = logger_1.GreenApiLogger.getInstance(this.constructor.name);
     }
     /**
      * Handles instance state change webhooks from GREEN-API.
@@ -86,6 +88,7 @@ class BaseAdapter {
      */
     async handlePlatformWebhook(message, idInstance) {
         try {
+            this.gaLogger.info("Handling platform webhook", { platformWebhook: message, idInstance });
             const instance = await this.storage.getInstance(idInstance);
             if (!instance) {
                 throw new errors_1.IntegrationError("Instance not found", "INSTANCE_NOT_FOUND", 404);
@@ -124,10 +127,15 @@ class BaseAdapter {
      * @throws {IntegrationError} If webhook handling fails
      */
     async handleGreenApiWebhook(webhook, allowedTypes) {
-        if (!allowedTypes.includes(webhook.typeWebhook)) {
-            return;
-        }
         try {
+            this.gaLogger.info("Handling GREEN-API webhook", { webhook, allowedTypes });
+            if (!allowedTypes.includes(webhook.typeWebhook)) {
+                this.gaLogger.warn(`Skipping GREEN-API webhook because the ${webhook.typeWebhook} is not allowed`, {
+                    webhook,
+                    allowedTypes,
+                });
+                return;
+            }
             if (webhook.typeWebhook === "stateInstanceChanged") {
                 await this.handleStateInstanceWebhook(webhook);
             }
@@ -148,17 +156,12 @@ class BaseAdapter {
      * Creates a new instance with specified settings.
      *
      * @param instance - The instance configuration
-     * @param userCred - User credentials
      * @returns Promise resolving to the created instance
      * @throws {NotFoundError} If user is not found
      * @throws {IntegrationError} If instance creation fails
      */
-    async createInstance(instance, userCred) {
+    async createInstance(instance) {
         try {
-            const user = await this.storage.findUser(userCred);
-            if (!user) {
-                throw new errors_1.NotFoundError("No user with such credentials");
-            }
             const client = this.createGreenApiClient(instance);
             try {
                 await client.getSettings();
@@ -166,7 +169,7 @@ class BaseAdapter {
             catch (error) {
                 throw new errors_1.IntegrationError(`Failed to get settings for instance ${instance.idInstance}: ${error.message}`, "INTEGRATION_ERROR");
             }
-            const createdInstance = await this.storage.createInstance(instance, user.id);
+            const createdInstance = await this.storage.createInstance(instance);
             if (instance.settings) {
                 await client.setSettings(instance.settings);
             }
@@ -185,10 +188,6 @@ class BaseAdapter {
      */
     async removeInstance(idInstance) {
         try {
-            const instance = await this.storage.getInstance(idInstance);
-            if (!instance) {
-                throw new errors_1.NotFoundError("No instance with such ID");
-            }
             return this.storage.removeInstance(idInstance);
         }
         catch (error) {
@@ -232,14 +231,8 @@ class BaseAdapter {
      *
      * @param userCred - User credentials
      * @param data - User data
-     * @throws {BadRequestError} If user already exists
-     * @throws {IntegrationError} If creation fails
      */
     async createUser(userCred, data) {
-        const existingUser = await this.storage.findUser(userCred);
-        if (existingUser) {
-            throw new errors_1.BadRequestError("User already created");
-        }
         try {
             return this.storage.createUser(data);
         }

package/dist/core/green-api.client.d.ts

@@ -23,6 +23,7 @@ export declare class GreenApiClient {
     private instance;
     private client;
     private readonly baseUrl;
+    private readonly gaLogger;
     /**
      * Creates a GREEN-API client instance.
      *

package/dist/core/green-api.client.js

@@ -5,6 +5,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GreenApiClient = void 0;
 const axios_1 = __importDefault(require("axios"));
+const errors_1 = require("./errors");
+const logger_1 = require("./logger");
 /**
  * Client for direct interaction with GREEN-API's WhatsApp gateway.
  * Provides methods for sending messages, managing instances, and handling files.
@@ -34,6 +36,7 @@ class GreenApiClient {
     constructor(instance) {
         this.instance = instance;
         this.baseUrl = "https://api.green-api.com";
+        this.gaLogger = logger_1.GreenApiLogger.getInstance(GreenApiClient.name);
         this.client = axios_1.default.create({
             baseURL: this.buildUrl(),
         });
@@ -46,6 +49,14 @@ class GreenApiClient {
     }
     async makeRequest(method, endpoint, data, queryParams, config) {
         try {
+            this.gaLogger.info("Making a request", {
+                idInstance: this.instance.idInstance,
+                endpoint,
+                method,
+                data,
+                queryParams,
+                config,
+            });
             const url = this.buildEndpoint(endpoint) + (queryParams ? "?" + new URLSearchParams(Object.entries(queryParams).map(([key, value]) => [key, value.toString()])).toString() : "");
             const response = await (method === "get"
                 ? this.client.get(url, config)
@@ -53,7 +64,7 @@ class GreenApiClient {
             return response.data;
         }
         catch (error) {
-            throw new Error(`Failed to ${endpoint.replace(/([A-Z])/g, " $1").toLowerCase()}: ${error.message}. ${JSON.stringify(error.response?.data)}`);
+            throw new errors_1.IntegrationError(`Failed to ${endpoint.replace(/([A-Z])/g, " $1").toLowerCase()}: ${error.message}. ${JSON.stringify(error.response?.data)}`, "INTEGRATION_ERROR");
         }
     }
     async makeFileUploadRequest(endpoint, formData, headers) {

package/dist/core/guard.d.ts

@@ -31,12 +31,13 @@ import { StorageProvider } from "./storage-provider";
  */
 export declare abstract class BaseGreenApiAuthGuard<T extends BaseRequest = BaseRequest> {
     protected storage: StorageProvider;
+    private readonly gaLogger;
     /**
      * Creates an instance of BaseGreenApiAuthGuard.
      *
      * @param storage - Storage provider for accessing instance data
      */
-    constructor(storage: StorageProvider);
+    protected constructor(storage: StorageProvider);
     /**
      * Validates an incoming webhook request.
      * Checks for presence of authorization token and validates it against instance settings.

package/dist/core/guard.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BaseGreenApiAuthGuard = void 0;
 const errors_1 = require("./errors");
+const logger_1 = require("./logger");
 /**
  * Base authentication guard for validating incoming GREEN-API webhooks.
  * Ensures that webhooks are authenticated and come from valid instances.
@@ -39,6 +40,7 @@ class BaseGreenApiAuthGuard {
      */
     constructor(storage) {
         this.storage = storage;
+        this.gaLogger = logger_1.GreenApiLogger.getInstance(this.constructor.name);
     }
     /**
      * Validates an incoming webhook request.
@@ -56,13 +58,14 @@ class BaseGreenApiAuthGuard {
         if (!token) {
             throw new errors_1.AuthenticationError("Authentication header is missing");
         }
+        this.gaLogger.info("Request from GREEN-API", { body: request.body });
         const idInstance = request.body?.instanceData?.idInstance;
         if (!idInstance) {
             throw new errors_1.AuthenticationError("Invalid webhook format");
         }
         const instance = await this.storage.getInstance(idInstance);
         if (!instance) {
-            throw new errors_1.AuthenticationError("No instance with such ID");
+            throw new errors_1.AuthenticationError(`No instance with such ID ${idInstance}`);
         }
         if (instance.settings?.webhookUrlToken !== token.split(" ")[1]) {
             throw new errors_1.AuthenticationError("Invalid token");

package/dist/core/logger.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Logger for GREEN-API integration library.
+ * Provides structured JSON logging with colored output and error handling.
+ * Uses singleton pattern to maintain consistent logging instances across the application.
+ *
+ * @category Core
+ *
+ * @example
+ * ```typescript
+ * const logger = GreenApiLogger.getInstance("MyComponent");
+ *
+ * // Basic logging
+ * logger.info("Operation successful", { userId: 123 });
+ *
+ * // Error logging
+ * try {
+ *   // ... some code
+ * } catch (error) {
+ *   logger.logErrorResponse(error, "Failed to process request");
+ * }
+ * ```
+ */
+export declare class GreenApiLogger {
+    private readonly context;
+    private static instances;
+    private readonly colors;
+    /**
+     * Private constructor to enforce singleton pattern
+     * @param context - The context (usually component name) for this logger instance
+     */
+    private constructor();
+    /**
+     * Gets a logger instance for the specified context.
+     * Creates a new instance if one doesn't exist, otherwise returns existing instance.
+     *
+     * @param context - The context for the logger (default: "Global")
+     * @returns Logger instance for the specified context
+     *
+     * @example
+     * ```typescript
+     * const logger = GreenApiLogger.getInstance("MyService");
+     * ```
+     */
+    static getInstance(context?: string): GreenApiLogger;
+    /**
+     * Formats timestamp in locale-specific format
+     * @returns Formatted timestamp string
+     * @private
+     */
+    private formatTimestamp;
+    /**
+     * Sanitizes values for JSON serialization.
+     * Handles special cases like Error objects and BigInt values.
+     *
+     * @param value - Value to sanitize
+     * @returns Sanitized value safe for JSON serialization
+     * @private
+     */
+    private sanitizeValue;
+    /**
+     * Creates and outputs a log entry
+     * @param level - Log level
+     * @param message - Log message
+     * @param additionalContext - Additional context data
+     * @private
+     */
+    private logEntry;
+    /**
+     * Logs a debug message
+     * @param message - Debug message
+     * @param context - Additional context data
+     */
+    debug(message: string, context?: Record<string, any>): void;
+    /**
+     * Logs an info message
+     * @param message - Info message
+     * @param context - Additional context data
+     */
+    info(message: string, context?: Record<string, any>): void;
+    /**
+     * Logs a warning message
+     * @param message - Warning message
+     * @param context - Additional context data
+     */
+    warn(message: string, context?: Record<string, any>): void;
+    /**
+     * Logs an error message
+     * @param message - Error message
+     * @param context - Additional context data
+     */
+    error(message: string, context?: Record<string, any>): void;
+    /**
+     * Alternative method for logging info messages
+     * @param message - Log message
+     * @param context - Context string
+     */
+    log(message: string, context?: string): void;
+    /**
+     * Logs a verbose debug message
+     * @param message - Debug message
+     * @param context - Context string
+     */
+    verbose(message: string, context?: string): void;
+    /**
+     * Logs a fatal error message
+     * @param message - Fatal error message
+     * @param context - Additional context data
+     */
+    fatal(message: string, context?: Record<string, any>): void;
+    /**
+     * Logs detailed error information, handling both Axios errors and regular errors.
+     * Particularly useful for API errors and exceptions.
+     *
+     * @param error - Error object (Axios error or regular error)
+     * @param context - Error context description
+     * @param additionalContext - Additional context data
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   await api.request();
+     * } catch (error) {
+     *   logger.logErrorResponse(error, "API Request failed", { requestId: "123" });
+     * }
+     * ```
+     */
+    logErrorResponse(error: any, context: string, additionalContext?: Record<string, any>): void;
+}

package/dist/core/logger.js

@@ -0,0 +1,217 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GreenApiLogger = void 0;
+const axios_1 = __importDefault(require("axios"));
+/**
+ * Logger for GREEN-API integration library.
+ * Provides structured JSON logging with colored output and error handling.
+ * Uses singleton pattern to maintain consistent logging instances across the application.
+ *
+ * @category Core
+ *
+ * @example
+ * ```typescript
+ * const logger = GreenApiLogger.getInstance("MyComponent");
+ *
+ * // Basic logging
+ * logger.info("Operation successful", { userId: 123 });
+ *
+ * // Error logging
+ * try {
+ *   // ... some code
+ * } catch (error) {
+ *   logger.logErrorResponse(error, "Failed to process request");
+ * }
+ * ```
+ */
+class GreenApiLogger {
+    /**
+     * Private constructor to enforce singleton pattern
+     * @param context - The context (usually component name) for this logger instance
+     */
+    constructor(context) {
+        this.context = context;
+        this.colors = {
+            log: "\x1b[32m", // Same as info (green)
+            debug: "\x1b[36m", // Cyan
+            info: "\x1b[32m", // Green
+            warn: "\x1b[33m", // Yellow
+            error: "\x1b[31m", // Red
+            fatal: "\x1b[35m", // Magenta/Purple for fatal
+            reset: "\x1b[0m", // Reset
+        };
+    }
+    /**
+     * Gets a logger instance for the specified context.
+     * Creates a new instance if one doesn't exist, otherwise returns existing instance.
+     *
+     * @param context - The context for the logger (default: "Global")
+     * @returns Logger instance for the specified context
+     *
+     * @example
+     * ```typescript
+     * const logger = GreenApiLogger.getInstance("MyService");
+     * ```
+     */
+    static getInstance(context = "Global") {
+        if (!GreenApiLogger.instances.has(context)) {
+            GreenApiLogger.instances.set(context, new GreenApiLogger(context));
+        }
+        return GreenApiLogger.instances.get(context);
+    }
+    /**
+     * Formats timestamp in locale-specific format
+     * @returns Formatted timestamp string
+     * @private
+     */
+    formatTimestamp() {
+        return new Date().toLocaleString("en-GB");
+    }
+    /**
+     * Sanitizes values for JSON serialization.
+     * Handles special cases like Error objects and BigInt values.
+     *
+     * @param value - Value to sanitize
+     * @returns Sanitized value safe for JSON serialization
+     * @private
+     */
+    sanitizeValue(value) {
+        if (value instanceof Error) {
+            return {
+                message: value.message,
+                stack: value.stack?.split("\n").map(line => line.trim()),
+            };
+        }
+        if (typeof value === "bigint") {
+            return value.toString();
+        }
+        if (Array.isArray(value)) {
+            return value.map(item => this.sanitizeValue(item));
+        }
+        if (value && typeof value === "object") {
+            return Object.fromEntries(Object.entries(value).map(([key, val]) => [key, this.sanitizeValue(val)]));
+        }
+        return value;
+    }
+    /**
+     * Creates and outputs a log entry
+     * @param level - Log level
+     * @param message - Log message
+     * @param additionalContext - Additional context data
+     * @private
+     */
+    logEntry(level, message, additionalContext = {}) {
+        const entry = {
+            timestamp: this.formatTimestamp(),
+            level,
+            context: this.context,
+            message,
+            ...this.sanitizeValue(additionalContext),
+        };
+        const color = this.colors[level];
+        const jsonString = JSON.stringify(entry);
+        console.log(`${color}${jsonString}${this.colors.reset}`);
+    }
+    /**
+     * Logs a debug message
+     * @param message - Debug message
+     * @param context - Additional context data
+     */
+    debug(message, context = {}) {
+        this.logEntry("debug", message, context);
+    }
+    /**
+     * Logs an info message
+     * @param message - Info message
+     * @param context - Additional context data
+     */
+    info(message, context = {}) {
+        this.logEntry("info", message, context);
+    }
+    /**
+     * Logs a warning message
+     * @param message - Warning message
+     * @param context - Additional context data
+     */
+    warn(message, context = {}) {
+        this.logEntry("warn", message, context);
+    }
+    /**
+     * Logs an error message
+     * @param message - Error message
+     * @param context - Additional context data
+     */
+    error(message, context = {}) {
+        this.logEntry("error", message, context);
+    }
+    /**
+     * Alternative method for logging info messages
+     * @param message - Log message
+     * @param context - Context string
+     */
+    log(message, context) {
+        this.logEntry("info", message, { context });
+    }
+    /**
+     * Logs a verbose debug message
+     * @param message - Debug message
+     * @param context - Context string
+     */
+    verbose(message, context) {
+        this.logEntry("debug", message, { context, level: "verbose" });
+    }
+    /**
+     * Logs a fatal error message
+     * @param message - Fatal error message
+     * @param context - Additional context data
+     */
+    fatal(message, context = {}) {
+        this.logEntry("error", message, context);
+    }
+    /**
+     * Logs detailed error information, handling both Axios errors and regular errors.
+     * Particularly useful for API errors and exceptions.
+     *
+     * @param error - Error object (Axios error or regular error)
+     * @param context - Error context description
+     * @param additionalContext - Additional context data
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   await api.request();
+     * } catch (error) {
+     *   logger.logErrorResponse(error, "API Request failed", { requestId: "123" });
+     * }
+     * ```
+     */
+    logErrorResponse(error, context, additionalContext = {}) {
+        if (axios_1.default.isAxiosError(error)) {
+            const axiosError = error;
+            this.error(`${context} - API Error:`, {
+                status: axiosError.response?.status,
+                statusText: axiosError.response?.statusText,
+                data: axiosError.response?.data,
+                url: axiosError.config?.url,
+                method: axiosError.config?.method,
+                headers: axiosError.response?.headers,
+                timestamp: new Date().toISOString(),
+                ...additionalContext,
+            });
+        }
+        else {
+            const errorObject = {
+                message: error instanceof Error ? error.message : String(error),
+                stack: error instanceof Error ? error.stack?.split("\n").map(line => line.trim()) : undefined,
+                timestamp: new Date().toISOString(),
+                ...additionalContext,
+            };
+            this.error(`${context} - Non-API Error:`, errorObject);
+        }
+    }
+}
+exports.GreenApiLogger = GreenApiLogger;
+GreenApiLogger.instances = new Map();

package/dist/core/storage-provider.d.ts

@@ -25,10 +25,9 @@ export declare abstract class StorageProvider<TUser extends BaseUser = BaseUser,
      * Creates a new instance in storage.
      *
      * @param instance - The instance data to store
-     * @param userId - ID of the user who owns this instance
      * @returns Promise resolving to the created instance
      */
-    abstract createInstance(instance: Instance, userId: bigint | number): Promise<TInstance>;
+    abstract createInstance(instance: Instance): Promise<TInstance>;
     /**
      * Retrieves an instance by its ID.
      *

package/dist/index.d.ts

@@ -4,5 +4,6 @@ export { GreenApiClient } from "./core/green-api.client";
 export { MessageTransformer } from "./core/message-transformer";
 export { BaseGreenApiAuthGuard } from "./core/guard";
 export { StorageProvider } from "./core/storage-provider";
+export { GreenApiLogger } from "./core/logger";
 export * from "./utils/helpers";
 export * from "./core/errors";

package/dist/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.StorageProvider = exports.BaseGreenApiAuthGuard = exports.MessageTransformer = exports.GreenApiClient = exports.BaseAdapter = void 0;
+exports.GreenApiLogger = exports.StorageProvider = exports.BaseGreenApiAuthGuard = exports.MessageTransformer = exports.GreenApiClient = exports.BaseAdapter = void 0;
 __exportStar(require("./types/types"), exports);
 var base_adapter_1 = require("./core/base-adapter");
 Object.defineProperty(exports, "BaseAdapter", { enumerable: true, get: function () { return base_adapter_1.BaseAdapter; } });
@@ -26,5 +26,7 @@ var guard_1 = require("./core/guard");
 Object.defineProperty(exports, "BaseGreenApiAuthGuard", { enumerable: true, get: function () { return guard_1.BaseGreenApiAuthGuard; } });
 var storage_provider_1 = require("./core/storage-provider");
 Object.defineProperty(exports, "StorageProvider", { enumerable: true, get: function () { return storage_provider_1.StorageProvider; } });
+var logger_1 = require("./core/logger");
+Object.defineProperty(exports, "GreenApiLogger", { enumerable: true, get: function () { return logger_1.GreenApiLogger; } });
 __exportStar(require("./utils/helpers"), exports);
 __exportStar(require("./core/errors"), exports);

package/dist/types/types.d.ts

@@ -180,12 +180,18 @@ export interface ContactMessageData extends ForwardableMessage {
     displayName: string;
     vcard: string;
 }
+export interface ContactsArrayMessageData extends ForwardableMessage {
+    contacts: Array<{
+        displayName: string;
+        vcard: string;
+    }>;
+}
 export interface PollMessageData {
     name: string;
     options: PollOption[];
     multipleAnswers: boolean;
 }
-type QuotedMessage = {
+export type QuotedMessage = {
     stanzaId: string;
     participant: string;
     typeMessage: MessageType;
@@ -198,6 +204,12 @@ type QuotedMessage = {
         displayName: string;
         vcard: string;
     };
+} | {
+    typeMessage: "contactsArrayMessage";
+    contacts: Array<{
+        displayName: string;
+        vcard: string;
+    }>;
 } | {
     typeMessage: "locationMessage";
     location: {
@@ -274,6 +286,9 @@ export type WebhookMessageData = {
 } | {
     typeMessage: "pollUpdateMessage";
     pollMessageData: PollUpdateMessageData;
+} | {
+    typeMessage: "contactsArrayMessage";
+    messageData: ContactsArrayMessageData;
 };
 export interface MessageWebhook {
     typeWebhook: "incomingMessageReceived" | "outgoingMessageReceived" | "outgoingAPIMessageReceived";
@@ -527,4 +542,3 @@ export interface BaseUser {
     id: number | bigint;
     [key: string]: any;
 }
-export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@green-api/greenapi-integration",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "GREEN-API Integration library",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",