@green-api/greenapi-integration 0.1.0 → 0.3.0

package/dist/core/base-adapter.js

@@ -3,17 +3,72 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.BaseAdapter = void 0;
 const green_api_client_1 = require("./green-api.client");
 const errors_1 = require("./errors");
+/**
+ * Base adapter for platform integrations with GREEN-API.
+ * This class handles the core integration logic between your platform and GREEN-API's WhatsApp gateway.
+ *
+ * @category Core
+ * @typeParam TPlatformWebhook - The webhook type specific to your platform
+ * @typeParam TPlatformMessage - The message type specific to your platform
+ * @typeParam TUser - User type extending BaseUser (default: BaseUser)
+ * @typeParam TInstance - Instance type extending Instance (default: Instance)
+ *
+ * @example
+ * ```typescript
+ * class YourAdapter extends BaseAdapter<YourWebhook, YourMessage> {
+ *   async createPlatformClient(config: YourConfig) {
+ *     return new YourPlatformClient(config);
+ *   }
+ *
+ *   async sendToPlatform(message: YourMessage, instance: Instance) {
+ *     const client = await this.createPlatformClient(instance.config);
+ *     await client.sendMessage(message);
+ *   }
+ * }
+ * ```
+ */
 class BaseAdapter {
+    /**
+     * 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, storage) {
         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.
+     *
+     * @param instance - The instance configuration containing ID and token
+     * @returns GREEN-API client
+     */
     createGreenApiClient(instance) {
         return new green_api_client_1.GreenApiClient({
             idInstance: instance.idInstance,
             apiTokenInstance: instance.apiTokenInstance,
         });
     }
+    /**
+     * Handles and wraps errors in IntegrationError.
+     *
+     * @param context - Error context description
+     * @param error - Original error
+     * @throws {IntegrationError} Always throws wrapped error
+     * @internal This method is used internally by the adapter
+     */
     handleError(context, error) {
         if (error instanceof errors_1.IntegrationError) {
             throw error;
@@ -21,6 +76,14 @@ class BaseAdapter {
         const errorMessage = error instanceof Error ? error.message : String(error);
         throw new errors_1.IntegrationError(`${context}: ${errorMessage}`, "UNEXPECTED_ERROR", 500, { originalError: error });
     }
+    /**
+     * Handles incoming webhooks from your platform and sends them to GREEN-API.
+     *
+     * @param message - The webhook message from your platform
+     * @param idInstance - The GREEN-API instance ID
+     * @returns Promise resolving to the send response
+     * @throws {IntegrationError} If instance is not found or message handling fails
+     */
     async handlePlatformWebhook(message, idInstance) {
         try {
             const instance = await this.storage.getInstance(idInstance);
@@ -52,24 +115,45 @@ class BaseAdapter {
             this.handleError("Failed to handle incoming message", error);
         }
     }
+    /**
+     * Handles incoming GREEN-API webhooks and forwards them to your platform.
+     *
+     * @param webhook - The webhook from GREEN-API
+     * @param allowedTypes - Array of webhook types to process, otherwise skipped
+     * @throws {NotFoundError} If instance is not found
+     * @throws {IntegrationError} If webhook handling fails
+     */
     async handleGreenApiWebhook(webhook, allowedTypes) {
         if (!allowedTypes.includes(webhook.typeWebhook)) {
             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);
         }
     }
-    async createInstance(instance, settings, userCred) {
-        console.log(instance, settings, userCred);
+    /**
+     * 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) {
         try {
             const user = await this.storage.findUser(userCred);
             if (!user) {
@@ -82,14 +166,23 @@ 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) {
             this.handleError("Failed to add instance", error);
         }
     }
+    /**
+     * Removes an instance by ID.
+     *
+     * @param idInstance - The instance ID to remove
+     * @returns Promise resolving to the removed instance
+     * @throws {NotFoundError} If instance is not found
+     */
     async removeInstance(idInstance) {
         try {
             const instance = await this.storage.getInstance(idInstance);
@@ -102,6 +195,13 @@ class BaseAdapter {
             this.handleError("Failed to remove instance", error);
         }
     }
+    /**
+     * Retrieves an instance by ID.
+     *
+     * @param idInstance - The instance ID to retrieve
+     * @returns Promise resolving to the instance or null if not found
+     * @throws {IntegrationError} If retrieval fails
+     */
     async getInstance(idInstance) {
         try {
             return this.storage.getInstance(idInstance);
@@ -110,15 +210,31 @@ class BaseAdapter {
             this.handleError("Failed to remove instance", error);
         }
     }
+    /**
+     * Updates user information.
+     *
+     * @param userCred - User credentials
+     * @param userUpdateData - New user data
+     * @returns Promise resolving to success status
+     * @throws {IntegrationError} If update fails
+     */
     async updateUser(userCred, userUpdateData) {
         try {
-            await this.storage.updateUser(userCred, userUpdateData);
-            return { status: "ok", message: "Token updated successfully" };
+            return this.storage.updateUser(userCred, userUpdateData);
         }
         catch (error) {
             this.handleError(`Failed to update user ${userCred}`, error);
         }
     }
+    /**
+     * Creates a new user in the storage.
+     * This method is implemented in the base adapter but can be overridden if needed.
+     *
+     * @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) {

package/dist/core/errors.d.ts

@@ -1,15 +1,90 @@
+/**
+ * Base error class for all integration-related errors.
+ *
+ * @category Errors
+ *
+ * @example
+ * ```typescript
+ * throw new IntegrationError(
+ *   "Failed to process webhook",
+ *   "PROCESSING_ERROR",
+ *   500,
+ *   { webhookId: "123" }
+ * );
+ * ```
+ */
 export declare class IntegrationError extends Error {
     readonly code: string;
     readonly statusCode: number;
     readonly details?: unknown | undefined;
+    /**
+     * Creates an integration error.
+     *
+     * @param message - Human-readable error message
+     * @param code - Error code for programmatic handling
+     * @param statusCode - HTTP status code (default: 500)
+     * @param details - Additional error details or context
+     */
     constructor(message: string, code: string, statusCode?: number, details?: unknown | undefined);
 }
+/**
+ * Error thrown when request validation fails or request data is invalid.
+ *
+ * @category Errors
+ *
+ * @example
+ * ```typescript
+ * if (!instanceId) {
+ *   throw new BadRequestError("Instance ID is required");
+ * }
+ * ```
+ */
 export declare class BadRequestError extends IntegrationError {
+    /**
+     * Creates a bad request error.
+     *
+     * @param message - Human-readable error message
+     * @param details - Additional error details or context
+     */
     constructor(message: string, details?: unknown);
 }
+/**
+ * Error thrown when authentication fails or credentials are invalid.
+ *
+ * @category Errors
+ *
+ * @example
+ * ```typescript
+ * if (!token) {
+ *   throw new AuthenticationError("Authentication token is missing");
+ * }
+ * ```
+ */
 export declare class AuthenticationError extends IntegrationError {
+    /**
+     * Creates an authentication error.
+     *
+     * @param message - Human-readable error message
+     */
     constructor(message: string);
 }
+/**
+ * Error thrown when a requested resource is not found.
+ *
+ * @category Errors
+ *
+ * @example
+ * ```typescript
+ * if (!instance) {
+ *   throw new NotFoundError("No instance with such ID");
+ * }
+ * ```
+ */
 export declare class NotFoundError extends IntegrationError {
+    /**
+     * Creates a not found error.
+     *
+     * @param message - Human-readable error message
+     */
     constructor(message: string);
 }

package/dist/core/errors.js

@@ -1,7 +1,30 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NotFoundError = exports.AuthenticationError = exports.BadRequestError = exports.IntegrationError = void 0;
+/**
+ * Base error class for all integration-related errors.
+ *
+ * @category Errors
+ *
+ * @example
+ * ```typescript
+ * throw new IntegrationError(
+ *   "Failed to process webhook",
+ *   "PROCESSING_ERROR",
+ *   500,
+ *   { webhookId: "123" }
+ * );
+ * ```
+ */
 class IntegrationError extends Error {
+    /**
+     * Creates an integration error.
+     *
+     * @param message - Human-readable error message
+     * @param code - Error code for programmatic handling
+     * @param statusCode - HTTP status code (default: 500)
+     * @param details - Additional error details or context
+     */
     constructor(message, code, statusCode = 500, details) {
         super(message);
         this.code = code;
@@ -11,19 +34,71 @@ class IntegrationError extends Error {
     }
 }
 exports.IntegrationError = IntegrationError;
+/**
+ * Error thrown when request validation fails or request data is invalid.
+ *
+ * @category Errors
+ *
+ * @example
+ * ```typescript
+ * if (!instanceId) {
+ *   throw new BadRequestError("Instance ID is required");
+ * }
+ * ```
+ */
 class BadRequestError extends IntegrationError {
+    /**
+     * Creates a bad request error.
+     *
+     * @param message - Human-readable error message
+     * @param details - Additional error details or context
+     */
     constructor(message, details) {
         super(message, "VALIDATION_ERROR", 400, details);
     }
 }
 exports.BadRequestError = BadRequestError;
+/**
+ * Error thrown when authentication fails or credentials are invalid.
+ *
+ * @category Errors
+ *
+ * @example
+ * ```typescript
+ * if (!token) {
+ *   throw new AuthenticationError("Authentication token is missing");
+ * }
+ * ```
+ */
 class AuthenticationError extends IntegrationError {
+    /**
+     * Creates an authentication error.
+     *
+     * @param message - Human-readable error message
+     */
     constructor(message) {
         super(message, "AUTHENTICATION_ERROR", 401);
     }
 }
 exports.AuthenticationError = AuthenticationError;
+/**
+ * Error thrown when a requested resource is not found.
+ *
+ * @category Errors
+ *
+ * @example
+ * ```typescript
+ * if (!instance) {
+ *   throw new NotFoundError("No instance with such ID");
+ * }
+ * ```
+ */
 class NotFoundError extends IntegrationError {
+    /**
+     * Creates a not found error.
+     *
+     * @param message - Human-readable error message
+     */
     constructor(message) {
         super(message, "NOT_FOUND_ERROR", 404);
     }

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

@@ -1,28 +1,216 @@
 import { Instance, Settings, SendMessage, SendFileByUrl, SendFileByUpload, SendPoll, StateInstance, Reboot, Logout, QR, SendResponse, SendFileByUploadResponse, SetSettingsResponse, GetAuthorizationCode, SetProfilePicture, WaSettings, UploadFile, SendLocation, SendContact, ForwardMessages, ForwardMessagesResponse } from "../types/types";
+/**
+ * Client for direct interaction with GREEN-API's WhatsApp gateway.
+ * Provides methods for sending messages, managing instances, and handling files.
+ *
+ * @category Client
+ *
+ * @example
+ * ```typescript
+ * const client = new GreenApiClient({
+ *   idInstance: 12345,
+ *   apiTokenInstance: "your-token"
+ * });
+ *
+ * await client.sendMessage({
+ *   chatId: "1234567890@c.us",
+ *   message: "Hello from GREEN-API!"
+ * });
+ * ```
+ */
 export declare class GreenApiClient {
     private instance;
     private client;
     private readonly baseUrl;
+    /**
+     * Creates a GREEN-API client instance.
+     *
+     * @param instance - Configuration containing idInstance and apiTokenInstance
+     */
     constructor(instance: Instance);
     private buildUrl;
     private buildEndpoint;
     private makeRequest;
     private makeFileUploadRequest;
+    /**
+     * Sends a text message to a WhatsApp chat.
+     *
+     * @param message - Message data containing chat ID and text
+     * @returns Promise resolving to send response with message ID
+     *
+     * @example
+     * ```typescript
+     * await client.sendMessage({
+     *   chatId: "1234567890@c.us",
+     *   message: "Hello!",
+     *   quotedMessageId: "12345" // Optional: reply to a message
+     * });
+     * ```
+     */
     sendMessage(message: SendMessage): Promise<SendResponse>;
+    /**
+     * Sends a file from a URL to a WhatsApp chat.
+     *
+     * @param message - Message data containing chat ID and file URL
+     * @returns Promise resolving to send response
+     *
+     * @example
+     * ```typescript
+     * await client.sendFileByUrl({
+     *   chatId: "1234567890@c.us",
+     *   file: {
+     *     url: "https://example.com/file.pdf",
+     *     fileName: "document.pdf"
+     *   },
+     *   caption: "Check this file" // Optional
+     * });
+     * ```
+     */
     sendFileByUrl(message: SendFileByUrl): Promise<SendResponse>;
+    /**
+     * Sends a file from local data to a WhatsApp chat.
+     *
+     * @param message - Message data containing chat ID and file data
+     * @returns Promise resolving to send response with file URL
+     *
+     * @example
+     * ```typescript
+     * await client.sendFileByUpload({
+     *   chatId: "1234567890@c.us",
+     *   file: {
+     *     data: fileBlob,
+     *     fileName: "image.jpg"
+     *   },
+     *   caption: "Check this image"
+     * });
+     * ```
+     */
     sendFileByUpload(message: SendFileByUpload): Promise<SendFileByUploadResponse>;
+    /**
+     * Creates a poll in a WhatsApp chat.
+     *
+     * @param message - Poll data with question and options
+     * @returns Promise resolving to send response
+     *
+     * @example
+     * ```typescript
+     * await client.sendPoll({
+     *   chatId: "1234567890@c.us",
+     *   message: "What's your favorite color?",
+     *   options: ["Red", "Blue", "Green"],
+     *   multipleAnswers: false
+     * });
+     * ```
+     */
     sendPoll(message: SendPoll): Promise<SendResponse>;
+    /**
+     * Forwards messages from one chat to another.
+     *
+     * @param request - Forward request with source and target chat IDs
+     * @returns Promise resolving to forward response
+     */
     forwardMessages(request: ForwardMessages): Promise<ForwardMessagesResponse>;
+    /**
+     * Sends a location to a WhatsApp chat.
+     *
+     * @param message - Location data with coordinates
+     * @returns Promise resolving to send response
+     *
+     * @example
+     * ```typescript
+     * await client.sendLocation({
+     *   chatId: "1234567890@c.us",
+     *   latitude: 51.5074,
+     *   longitude: -0.1278,
+     *   nameLocation: "London",
+     *   address: "London, UK"
+     * });
+     * ```
+     */
     sendLocation(message: SendLocation): Promise<SendResponse>;
+    /**
+     * Sends a contact card to a WhatsApp chat.
+     *
+     * @param message - Contact data
+     * @returns Promise resolving to send response
+     *
+     * @example
+     * ```typescript
+     * await client.sendContact({
+     *   chatId: "1234567890@c.us",
+     *   contact: {
+     *     phoneContact: 1234567890,
+     *     firstName: "John",
+     *     lastName: "Doe"
+     *   }
+     * });
+     * ```
+     */
     sendContact(message: SendContact): Promise<SendResponse>;
+    /**
+     * Reboots the GREEN-API instance.
+     *
+     * @returns Promise resolving to reboot status
+     */
     reboot(): Promise<Reboot>;
+    /**
+     * Logs out from the GREEN-API instance.
+     *
+     * @returns Promise resolving to logout status
+     */
     logout(): Promise<Logout>;
+    /**
+     * Gets the current state of the GREEN-API instance.
+     *
+     * @returns Promise resolving to instance state
+     */
     getStateInstance(): Promise<StateInstance>;
+    /**
+     * Gets the QR code for GREEN-API instance authentication.
+     *
+     * @returns Promise resolving to QR code data
+     */
     getQR(): Promise<QR>;
+    /**
+     * Gets current instance settings.
+     *
+     * @returns Promise resolving to settings object
+     */
     getSettings(): Promise<Settings>;
+    /**
+     * Updates instance settings.
+     *
+     * @param settings - New settings to apply
+     * @returns Promise resolving to settings update response
+     */
     setSettings(settings: Settings): Promise<SetSettingsResponse>;
+    /**
+     * Gets WhatsApp-specific settings.
+     *
+     * @returns Promise resolving to WhatsApp settings
+     */
     getWaSettings(): Promise<WaSettings>;
+    /**
+     * Sets the profile picture for the WhatsApp account.
+     *
+     * @param file - Image file to use as profile picture
+     * @returns Promise resolving to profile picture update response
+     */
     setProfilePicture(file: Blob | File): Promise<SetProfilePicture>;
+    /**
+     * Uploads a file to GREEN-API servers.
+     *
+     * @param file - File to upload
+     * @param customFileName - Optional custom name for the file
+     * @returns Promise resolving to upload response with file URL
+     */
     uploadFile(file: Blob | File, customFileName?: string): Promise<UploadFile>;
+    /**
+     * Gets authorization code for a phone number.
+     *
+     * @param phoneNumber - Phone number to get code for
+     * @returns Promise resolving to authorization code response
+     * @throws {Error} If phone number is not an integer
+     */
     getAuthorizationCode(phoneNumber: number): Promise<GetAuthorizationCode>;
 }