@green-api/greenapi-integration 0.5.0 → 0.6.1

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.

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);
             }

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

@@ -6,6 +6,7 @@ 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.
@@ -35,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(),
         });
@@ -47,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)

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/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

@@ -109,7 +109,7 @@ export interface QueueMessage {
 export interface ClearMessagesQueue {
     isCleared: boolean;
 }
-export type MessageType = "textMessage" | "extendedTextMessage" | "imageMessage" | "videoMessage" | "documentMessage" | "audioMessage" | "contactMessage" | "locationMessage" | "pollMessage" | "reactionMessage" | "pollUpdateMessage" | "quotedMessage" | "stickerMessage";
+export type MessageType = "textMessage" | "extendedTextMessage" | "imageMessage" | "videoMessage" | "documentMessage" | "audioMessage" | "contactMessage" | "locationMessage" | "contactsArrayMessage" | "pollMessage" | "reactionMessage" | "pollUpdateMessage" | "quotedMessage" | "stickerMessage";
 export interface GetMessage {
     chatId: string;
     idMessage: string;
@@ -191,13 +191,22 @@ export interface PollMessageData {
     options: PollOption[];
     multipleAnswers: boolean;
 }
-type QuotedMessage = {
+export type QuotedMessage = {
     stanzaId: string;
     participant: string;
     typeMessage: MessageType;
 } & ({
     typeMessage: "textMessage";
     textMessage: string;
+} | {
+    typeMessage: "extendedTextMessage";
+    textMessage: string;
+    extendedTextMessage: {
+        description?: string;
+        title?: string;
+        previewType?: string;
+        jpegThumbnail?: string | null;
+    };
 } | {
     typeMessage: "contactMessage";
     contact: {
@@ -274,6 +283,10 @@ export type WebhookMessageData = {
 } | {
     typeMessage: "imageMessage" | "videoMessage" | "documentMessage" | "audioMessage";
     fileMessageData: FileMessageData;
+} | {
+    typeMessage: "quotedMessage";
+    extendedTextMessageData: ExtendedTextMessageData;
+    quotedMessage: QuotedMessage;
 } | {
     typeMessage: "locationMessage";
     locationMessageData: LocationMessageData;
@@ -542,4 +555,3 @@ export interface BaseUser {
     id: number | bigint;
     [key: string]: any;
 }
-export {};

package/package.json

@@ -1,41 +1,42 @@
-{
-  "name": "@green-api/greenapi-integration",
-  "version": "0.5.0",
-  "description": "GREEN-API Integration library",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "build": "tsc",
-    "clean": "rimraf dist",
-    "prebuild": "npm run clean",
-    "prepare": "npm run build",
-    "docs": "typedoc",
-    "docs:watch": "typedoc --watch"
-  },
-  "keywords": [
-    "green-api",
-    "whatsapp",
-    "integration"
-  ],
-  "author": "GREEN-API team",
-  "license": "MIT",
-  "devDependencies": {
-    "@types/express": "^5.0.0",
-    "@types/jest": "^29.5.14",
-    "@types/node": "^22.10.2",
-    "express": "^4.21.2",
-    "jest": "^29.7.0",
-    "rimraf": "^6.0.1",
-    "ts-jest": "^29.2.5",
-    "ts-node": "^10.9.2",
-    "typedoc": "^0.27.6",
-    "typedoc-plugin-markdown": "^4.4.1",
-    "typescript": "^5.7.2"
-  },
-  "dependencies": {
-    "axios": "^1.7.9"
-  }
-}
+{
+  "name": "@green-api/greenapi-integration",
+  "version": "0.6.1",
+  "description": "GREEN-API Integration library",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clean": "rimraf dist",
+    "prebuild": "npm run clean",
+    "prepare": "npm run build",
+    "docs": "typedoc",
+    "docs:watch": "typedoc --watch"
+  },
+  "keywords": [
+    "green-api",
+    "whatsapp",
+    "integration"
+  ],
+  "author": "GREEN-API team",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^22.10.2",
+    "express": "^4.21.2",
+    "jest": "^29.7.0",
+    "rimraf": "^6.0.1",
+    "ts-jest": "^29.2.5",
+    "ts-node": "^10.9.2",
+    "typedoc": "^0.27.6",
+    "typedoc-plugin-markdown": "^4.4.1",
+    "typescript": "^5.7.2"
+  },
+  "dependencies": {
+    "axios": "^1.7.9"
+  }
+}