@green-api/greenapi-integration 0.2.0 → 0.3.0

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

@@ -1,6 +1,6 @@
 import { GreenApiClient } from "./green-api.client";
 import { MessageTransformer } from "./message-transformer";
-import { BaseUser, ForwardMessagesResponse, GreenApiWebhook, Instance, SendResponse, Settings } from "../types/types";
+import { BaseUser, ForwardMessagesResponse, GreenApiWebhook, Instance, SendResponse, StateInstanceWebhook, WebhookType } from "../types/types";
 import { StorageProvider } from "./storage-provider";
 /**
  * Base adapter for platform integrations with GREEN-API.
@@ -74,6 +74,14 @@ export declare abstract class BaseAdapter<TPlatformWebhook, TPlatformMessage, TU
      * ```
      */
     abstract createPlatformClient(params: any): Promise<any>;
+    /**
+     * Handles instance state change webhooks from GREEN-API.
+     * Adapters MUST override this method if they need to handle instance state changes
+     *
+     * @param webhook - The state change webhook from GREEN-API
+     * @returns Promise resolving when the webhook is handled
+     */
+    handleStateInstanceWebhook(webhook: StateInstanceWebhook): Promise<void>;
     /**
      * Creates a GREEN-API client instance.
      *
@@ -107,18 +115,17 @@ export declare abstract class BaseAdapter<TPlatformWebhook, TPlatformMessage, TU
      * @throws {NotFoundError} If instance is not found
      * @throws {IntegrationError} If webhook handling fails
      */
-    handleGreenApiWebhook(webhook: GreenApiWebhook, allowedTypes: string[]): Promise<void>;
+    handleGreenApiWebhook(webhook: GreenApiWebhook, allowedTypes: WebhookType[]): Promise<void>;
     /**
      * Creates a new instance with specified settings.
      *
      * @param instance - The instance configuration
-     * @param settings - GREEN-API settings for the instance
      * @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, settings: Settings, userCred: any): Promise<TInstance>;
+    createInstance(instance: Instance, userCred: any): Promise<TInstance>;
     /**
      * Removes an instance by ID.
      *

package/dist/core/base-adapter.js

@@ -38,6 +38,17 @@ class BaseAdapter {
         this.transformer = transformer;
         this.storage = storage;
     }
+    /**
+     * Handles instance state change webhooks from GREEN-API.
+     * Adapters MUST override this method if they need to handle instance state changes
+     *
+     * @param webhook - The state change webhook from GREEN-API
+     * @returns Promise resolving when the webhook is handled
+     */
+    async handleStateInstanceWebhook(webhook) {
+        // Default empty implementation
+        return;
+    }
     /**
      * Creates a GREEN-API client instance.
      *
@@ -117,12 +128,17 @@ class BaseAdapter {
             return;
         }
         try {
-            const transformedMessage = await this.transformer.toPlatformMessage(webhook);
-            const instance = await this.storage.getInstance(webhook.instanceData.idInstance);
-            if (!instance) {
-                throw new errors_1.NotFoundError("Instance not found");
+            if (webhook.typeWebhook === "stateInstanceChanged") {
+                await this.handleStateInstanceWebhook(webhook);
+            }
+            else {
+                const transformedMessage = await this.transformer.toPlatformMessage(webhook);
+                const instance = await this.storage.getInstance(webhook.instanceData.idInstance);
+                if (!instance) {
+                    throw new errors_1.NotFoundError("Instance not found");
+                }
+                await this.sendToPlatform(transformedMessage, instance);
             }
-            await this.sendToPlatform(transformedMessage, instance);
         }
         catch (error) {
             this.handleError("Failed to handle GREEN-API webhook", error);
@@ -132,13 +148,12 @@ class BaseAdapter {
      * Creates a new instance with specified settings.
      *
      * @param instance - The instance configuration
-     * @param settings - GREEN-API settings for the instance
      * @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, settings, userCred) {
+    async createInstance(instance, userCred) {
         try {
             const user = await this.storage.findUser(userCred);
             if (!user) {
@@ -151,8 +166,10 @@ 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, settings);
-            await client.setSettings(settings);
+            const createdInstance = await this.storage.createInstance(instance, user.id);
+            if (instance.settings) {
+                await client.setSettings(instance.settings);
+            }
             return createdInstance;
         }
         catch (error) {

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

@@ -51,7 +51,7 @@ class GreenApiClient {
             return response.data;
         }
         catch (error) {
-            throw new Error(`Failed to ${endpoint.replace(/([A-Z])/g, " $1").toLowerCase()}: ${error.message}`);
+            throw new Error(`Failed to ${endpoint.replace(/([A-Z])/g, " $1").toLowerCase()}: ${error.message}. ${JSON.stringify(error.response?.data)}`);
         }
     }
     async makeFileUploadRequest(endpoint, formData, headers) {

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

@@ -1,4 +1,4 @@
-import { BaseUser, Instance, Settings } from "../types/types";
+import { BaseUser, Instance } from "../types/types";
 /**
  * Abstract class for managing instance and user data storage.
  * Implement this class to define how your integration stores and retrieves data.
@@ -26,10 +26,9 @@ export declare abstract class StorageProvider<TUser extends BaseUser = BaseUser,
      *
      * @param instance - The instance data to store
      * @param userId - ID of the user who owns this instance
-     * @param settings - Optional GREEN-API settings for the instance
      * @returns Promise resolving to the created instance
      */
-    abstract createInstance(instance: Instance, userId: bigint | number, settings?: Settings): Promise<TInstance>;
+    abstract createInstance(instance: Instance, userId: bigint | number): Promise<TInstance>;
     /**
      * Retrieves an instance by its ID.
      *

package/dist/types/types.d.ts

@@ -5,7 +5,8 @@
 interface BaseInstance {
     idInstance: number | bigint;
     apiTokenInstance: string;
-    settings?: Settings;
+    stateInstance?: InstanceState;
+    settings?: Settings | Record<string, any>;
 }
 /**
  * Extended instance interface that allows for additional platform-specific properties.
@@ -172,6 +173,7 @@ export interface PollUpdateMessageData {
     multipleAnswers: boolean;
 }
 export type OutgoingMessageStatus = "sent" | "delivered" | "read" | "failed" | "noAccount" | "notInGroup" | "yellowCard";
+export type WebhookType = "stateInstanceChanged" | "outgoingMessageStatus" | "outgoingAPIMessageReceived" | "outgoingMessageReceived" | "incomingMessageReceived";
 /**
  * Webhook payload received when a message status changes.
  * Used to track delivery and read receipts.
@@ -190,6 +192,16 @@ export interface OutgoingMessageStatusWebhook {
     description?: string;
     sendByApi: boolean;
 }
+export interface StateInstanceWebhook {
+    typeWebhook: "stateInstanceChanged";
+    instanceData: {
+        idInstance: number;
+        wid: string;
+        typeInstance: string;
+    };
+    timestamp: number;
+    stateInstance: InstanceState;
+}
 export type WebhookMessageData = {
     typeMessage: "textMessage";
     textMessageData: TextMessageData;
@@ -235,7 +247,7 @@ export interface MessageWebhook {
 /**
  * Primary webhook types received from GREEN-API.
  */
-export type GreenApiWebhook = MessageWebhook | OutgoingMessageStatusWebhook;
+export type GreenApiWebhook = MessageWebhook | OutgoingMessageStatusWebhook | StateInstanceWebhook;
 /**
  * Configuration settings for a GREEN-API instance.
  * Controls webhook behavior, message handling, and other instance features.

package/dist/utils/helpers.d.ts

@@ -1,3 +1,4 @@
+import { Settings } from "../types/types";
 /**
  * Utility functions for working with phone numbers, tokens, and vCards.
  *
@@ -39,3 +40,34 @@ export declare function generateRandomToken(length?: number): string;
  * extractPhoneNumberFromVCard(vcard)  // Returns '+1234567890'
  */
 export declare function extractPhoneNumberFromVCard(vcard: string): string | null;
+/**
+ * Validates if a value is appropriate for a specific Settings interface key.
+ * Checks type compatibility for numbers, strings, and yes/no enums.
+ *
+ * @param key - The settings key to validate
+ * @param value - The value to check against the key's expected type
+ * @returns Boolean indicating if the value is valid for the given key
+ *
+ * @example
+ * isValidSettingValue('delaySendMessagesMilliseconds', 1000)     // Returns true
+ * isValidSettingValue('outgoingWebhook', 'maybe')                // Returns false
+ * isValidSettingValue('webhookUrl', 'https://example.com')       // Returns true
+ */
+export declare function isValidSettingValue(key: keyof Settings, value: any): boolean;
+/**
+ * Validates and cleans a settings object against the Settings interface.
+ * Removes any properties that don't match the interface or have invalid values.
+ *
+ * @param settings - The settings object to validate and clean
+ * @returns A new Settings object containing only valid properties and values
+ *
+ * @example
+ * const input = {
+ *   webhookUrl: 'https://example.com',
+ *   outgoingWebhook: 'yes',
+ *   invalidKey: 'value',
+ *   delaySendMessagesMilliseconds: 'invalid'
+ * };
+ * validateAndCleanSettings(input)  // Returns { webhookUrl: 'https://example.com', outgoingWebhook: 'yes' }
+ */
+export declare function validateAndCleanSettings(settings: any): Settings;

package/dist/utils/helpers.js

@@ -36,6 +36,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.formatPhoneNumber = formatPhoneNumber;
 exports.generateRandomToken = generateRandomToken;
 exports.extractPhoneNumberFromVCard = extractPhoneNumberFromVCard;
+exports.isValidSettingValue = isValidSettingValue;
+exports.validateAndCleanSettings = validateAndCleanSettings;
 const crypto = __importStar(require("crypto"));
 /**
  * Utility functions for working with phone numbers, tokens, and vCards.
@@ -86,3 +88,65 @@ function extractPhoneNumberFromVCard(vcard) {
     const phoneMatch = vcard.match(/TEL(?:;[^:]+)?:([+\d\s-]+)/);
     return phoneMatch ? phoneMatch[1] : null;
 }
+/**
+ * Validates if a value is appropriate for a specific Settings interface key.
+ * Checks type compatibility for numbers, strings, and yes/no enums.
+ *
+ * @param key - The settings key to validate
+ * @param value - The value to check against the key's expected type
+ * @returns Boolean indicating if the value is valid for the given key
+ *
+ * @example
+ * isValidSettingValue('delaySendMessagesMilliseconds', 1000)     // Returns true
+ * isValidSettingValue('outgoingWebhook', 'maybe')                // Returns false
+ * isValidSettingValue('webhookUrl', 'https://example.com')       // Returns true
+ */
+function isValidSettingValue(key, value) {
+    switch (key) {
+        case "delaySendMessagesMilliseconds":
+            return typeof value === "number";
+        case "wid":
+        case "webhookUrl":
+        case "webhookUrlToken":
+            return typeof value === "string";
+        case "markIncomingMessagesReaded":
+        case "markIncomingMessagesReadedOnReply":
+        case "outgoingWebhook":
+        case "outgoingMessageWebhook":
+        case "outgoingAPIMessageWebhook":
+        case "stateWebhook":
+        case "incomingWebhook":
+        case "keepOnlineStatus":
+        case "pollMessageWebhook":
+        case "incomingCallWebhook":
+            return value === "yes" || value === "no";
+        default:
+            return false;
+    }
+}
+/**
+ * Validates and cleans a settings object against the Settings interface.
+ * Removes any properties that don't match the interface or have invalid values.
+ *
+ * @param settings - The settings object to validate and clean
+ * @returns A new Settings object containing only valid properties and values
+ *
+ * @example
+ * const input = {
+ *   webhookUrl: 'https://example.com',
+ *   outgoingWebhook: 'yes',
+ *   invalidKey: 'value',
+ *   delaySendMessagesMilliseconds: 'invalid'
+ * };
+ * validateAndCleanSettings(input)  // Returns { webhookUrl: 'https://example.com', outgoingWebhook: 'yes' }
+ */
+function validateAndCleanSettings(settings) {
+    const validSettings = {};
+    const settingsKeys = Object.keys(settings);
+    for (const key of settingsKeys) {
+        if (key in validSettings && isValidSettingValue(key, settings[key])) {
+            validSettings[key] = settings[key];
+        }
+    }
+    return validSettings;
+}

package/package.json

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