@green-api/greenapi-integration 0.1.0 → 0.3.0

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

@@ -5,7 +5,31 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GreenApiClient = void 0;
 const axios_1 = __importDefault(require("axios"));
+/**
+ * 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!"
+ * });
+ * ```
+ */
 class GreenApiClient {
+    /**
+     * Creates a GREEN-API client instance.
+     *
+     * @param instance - Configuration containing idInstance and apiTokenInstance
+     */
     constructor(instance) {
         this.instance = instance;
         this.baseUrl = "https://api.green-api.com";
@@ -27,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) {
@@ -36,6 +60,21 @@ class GreenApiClient {
             ...headers,
         });
     }
+    /**
+     * 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
+     * });
+     * ```
+     */
     async sendMessage(message) {
         return this.makeRequest("post", "sendMessage", {
             chatId: message.chatId,
@@ -43,6 +82,24 @@ class GreenApiClient {
             quotedMessageId: message.quotedMessageId,
         });
     }
+    /**
+     * 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
+     * });
+     * ```
+     */
     async sendFileByUrl(message) {
         return this.makeRequest("post", "sendFileByUrl", {
             chatId: message.chatId,
@@ -52,6 +109,24 @@ class GreenApiClient {
             quotedMessageId: message.quotedMessageId,
         });
     }
+    /**
+     * 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"
+     * });
+     * ```
+     */
     async sendFileByUpload(message) {
         const formData = new FormData();
         formData.append("file", message.file.data);
@@ -63,6 +138,22 @@ class GreenApiClient {
             formData.append("quotedMessageId", message.quotedMessageId);
         return this.makeFileUploadRequest("sendFileByUpload", formData);
     }
+    /**
+     * 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
+     * });
+     * ```
+     */
     async sendPoll(message) {
         return this.makeRequest("post", "sendPoll", {
             chatId: message.chatId,
@@ -72,6 +163,12 @@ class GreenApiClient {
             quotedMessageId: message.quotedMessageId,
         });
     }
+    /**
+     * Forwards messages from one chat to another.
+     *
+     * @param request - Forward request with source and target chat IDs
+     * @returns Promise resolving to forward response
+     */
     async forwardMessages(request) {
         return this.makeRequest("post", "forwardMessages", {
             chatId: request.chatId,
@@ -79,6 +176,23 @@ class GreenApiClient {
             messages: request.messages,
         });
     }
+    /**
+     * 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"
+     * });
+     * ```
+     */
     async sendLocation(message) {
         return this.makeRequest("post", "sendLocation", {
             chatId: message.chatId,
@@ -89,6 +203,24 @@ class GreenApiClient {
             quotedMessageId: message.quotedMessageId,
         });
     }
+    /**
+     * 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"
+     *   }
+     * });
+     * ```
+     */
     async sendContact(message) {
         return this.makeRequest("post", "sendContact", {
             chatId: message.chatId,
@@ -96,32 +228,81 @@ class GreenApiClient {
             quotedMessageId: message.quotedMessageId,
         });
     }
+    /**
+     * Reboots the GREEN-API instance.
+     *
+     * @returns Promise resolving to reboot status
+     */
     async reboot() {
         return this.makeRequest("get", "reboot");
     }
+    /**
+     * Logs out from the GREEN-API instance.
+     *
+     * @returns Promise resolving to logout status
+     */
     async logout() {
         return this.makeRequest("get", "logout");
     }
+    /**
+     * Gets the current state of the GREEN-API instance.
+     *
+     * @returns Promise resolving to instance state
+     */
     async getStateInstance() {
         return this.makeRequest("get", "getStateInstance");
     }
+    /**
+     * Gets the QR code for GREEN-API instance authentication.
+     *
+     * @returns Promise resolving to QR code data
+     */
     async getQR() {
         return this.makeRequest("get", "qr");
     }
+    /**
+     * Gets current instance settings.
+     *
+     * @returns Promise resolving to settings object
+     */
     async getSettings() {
         return this.makeRequest("get", "getSettings");
     }
+    /**
+     * Updates instance settings.
+     *
+     * @param settings - New settings to apply
+     * @returns Promise resolving to settings update response
+     */
     async setSettings(settings) {
         return this.makeRequest("post", "setSettings", settings);
     }
+    /**
+     * Gets WhatsApp-specific settings.
+     *
+     * @returns Promise resolving to WhatsApp settings
+     */
     async getWaSettings() {
         return this.makeRequest("get", "getWaSettings");
     }
+    /**
+     * 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
+     */
     async setProfilePicture(file) {
         const formData = new FormData();
         formData.append("file", file);
         return this.makeFileUploadRequest("setProfilePicture", formData);
     }
+    /**
+     * 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
+     */
     async uploadFile(file, customFileName) {
         const formData = new FormData();
         formData.append("file", file);
@@ -140,6 +321,13 @@ class GreenApiClient {
         }
         return this.makeFileUploadRequest("uploadFile", formData, headers);
     }
+    /**
+     * 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
+     */
     async getAuthorizationCode(phoneNumber) {
         if (!Number.isInteger(phoneNumber)) {
             throw new Error("Phone number must contain only digits");

package/dist/core/guard.d.ts

@@ -1,7 +1,52 @@
 import { BaseRequest } from "../types/types";
 import { StorageProvider } from "./storage-provider";
+/**
+ * Base authentication guard for validating incoming GREEN-API webhooks.
+ * Ensures that webhooks are authenticated and come from valid instances.
+ *
+ * @category Authentication
+ * @typeParam T - Request type extending BaseRequest, contains headers and body
+ *
+ * @example
+ * ```typescript
+ * class WebhookGuard extends BaseGreenApiAuthGuard<ExpressRequest> {
+ *   constructor(storage: StorageProvider) {
+ *     super(storage);
+ *   }
+ * }
+ *
+ * // Usage in Express
+ * app.post('/webhook', async (req, res) => {
+ *   const guard = new WebhookGuard(storage);
+ *   try {
+ *     await guard.validateRequest(req);
+ *     // Process webhook
+ *   } catch (error) {
+ *     if (error instanceof AuthenticationError) {
+ *       res.status(401).json({ error: error.message });
+ *     }
+ *   }
+ * });
+ * ```
+ */
 export declare abstract class BaseGreenApiAuthGuard<T extends BaseRequest = BaseRequest> {
     protected storage: StorageProvider;
+    /**
+     * Creates an instance of BaseGreenApiAuthGuard.
+     *
+     * @param storage - Storage provider for accessing instance data
+     */
     constructor(storage: StorageProvider);
+    /**
+     * Validates an incoming webhook request.
+     * Checks for presence of authorization token and validates it against instance settings.
+     *
+     * @param request - The incoming request with headers and body
+     * @returns Promise resolving to true if validation succeeds
+     * @throws {AuthenticationError} If authorization header is missing
+     * @throws {AuthenticationError} If webhook format is invalid
+     * @throws {AuthenticationError} If instance is not found
+     * @throws {AuthenticationError} If token is invalid
+     */
     validateRequest(request: T): Promise<boolean>;
 }

package/dist/core/guard.js

@@ -2,10 +2,55 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BaseGreenApiAuthGuard = void 0;
 const errors_1 = require("./errors");
+/**
+ * Base authentication guard for validating incoming GREEN-API webhooks.
+ * Ensures that webhooks are authenticated and come from valid instances.
+ *
+ * @category Authentication
+ * @typeParam T - Request type extending BaseRequest, contains headers and body
+ *
+ * @example
+ * ```typescript
+ * class WebhookGuard extends BaseGreenApiAuthGuard<ExpressRequest> {
+ *   constructor(storage: StorageProvider) {
+ *     super(storage);
+ *   }
+ * }
+ *
+ * // Usage in Express
+ * app.post('/webhook', async (req, res) => {
+ *   const guard = new WebhookGuard(storage);
+ *   try {
+ *     await guard.validateRequest(req);
+ *     // Process webhook
+ *   } catch (error) {
+ *     if (error instanceof AuthenticationError) {
+ *       res.status(401).json({ error: error.message });
+ *     }
+ *   }
+ * });
+ * ```
+ */
 class BaseGreenApiAuthGuard {
+    /**
+     * Creates an instance of BaseGreenApiAuthGuard.
+     *
+     * @param storage - Storage provider for accessing instance data
+     */
     constructor(storage) {
         this.storage = storage;
     }
+    /**
+     * Validates an incoming webhook request.
+     * Checks for presence of authorization token and validates it against instance settings.
+     *
+     * @param request - The incoming request with headers and body
+     * @returns Promise resolving to true if validation succeeds
+     * @throws {AuthenticationError} If authorization header is missing
+     * @throws {AuthenticationError} If webhook format is invalid
+     * @throws {AuthenticationError} If instance is not found
+     * @throws {AuthenticationError} If token is invalid
+     */
     async validateRequest(request) {
         const token = request.headers["authorization"];
         if (!token) {

package/dist/core/message-transformer.d.ts

@@ -1,5 +1,49 @@
-import { IncomingGreenApiWebhook, Message } from "../types/types";
+import { GreenApiWebhook, Message } from "../types/types";
+/**
+ * Abstract class for transforming messages between your platform's format and GREEN-API's format.
+ * Implement this class to define how messages are converted between the two systems.
+ *
+ * @category Transformer
+ * @typeParam TPlatformWebhook - Your platform's webhook message type
+ * @typeParam TPlatformMessage - Your platform's outgoing message type
+ *
+ * @example
+ * ```typescript
+ * class YourTransformer extends MessageTransformer<YourWebhook, YourMessage> {
+ *   toPlatformMessage(webhook: GreenApiWebhook): YourMessage {
+ *     return {
+ *       recipient: webhook.senderData.sender,
+ *       content: webhook.messageData.textMessageData?.textMessage || "",
+ *     };
+ *   }
+ *
+ *   toGreenApiMessage(message: YourWebhook): Message {
+ *     return {
+ *       type: "text",
+ *       chatId: formatPhoneNumber(message.from),
+ *       message: message.content,
+ *     };
+ *   }
+ * }
+ * ```
+ */
 export declare abstract class MessageTransformer<TPlatformWebhook, TPlatformMessage> {
-    abstract toPlatformMessage(webhook: IncomingGreenApiWebhook): TPlatformMessage;
+    /**
+     * Transforms a GREEN-API webhook into your platform's message format.
+     * Implement this method to convert incoming WhatsApp messages to your platform's format.
+     *
+     * @param webhook - The incoming webhook from GREEN-API
+     * @returns Your platform's message format
+     * @throws {Error} If the webhook format is invalid or unsupported
+     */
+    abstract toPlatformMessage(webhook: GreenApiWebhook): TPlatformMessage;
+    /**
+     * Transforms your platform's message format into GREEN-API's message format.
+     * Implement this method to convert your platform's messages to WhatsApp format.
+     *
+     * @param message - The message in your platform's format
+     * @returns Message formatted for GREEN-API
+     * @throws {Error} If the message format is invalid or unsupported
+     */
     abstract toGreenApiMessage(message: TPlatformWebhook): Message;
 }

package/dist/core/message-transformer.js

@@ -1,6 +1,34 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MessageTransformer = void 0;
+/**
+ * Abstract class for transforming messages between your platform's format and GREEN-API's format.
+ * Implement this class to define how messages are converted between the two systems.
+ *
+ * @category Transformer
+ * @typeParam TPlatformWebhook - Your platform's webhook message type
+ * @typeParam TPlatformMessage - Your platform's outgoing message type
+ *
+ * @example
+ * ```typescript
+ * class YourTransformer extends MessageTransformer<YourWebhook, YourMessage> {
+ *   toPlatformMessage(webhook: GreenApiWebhook): YourMessage {
+ *     return {
+ *       recipient: webhook.senderData.sender,
+ *       content: webhook.messageData.textMessageData?.textMessage || "",
+ *     };
+ *   }
+ *
+ *   toGreenApiMessage(message: YourWebhook): Message {
+ *     return {
+ *       type: "text",
+ *       chatId: formatPhoneNumber(message.from),
+ *       message: message.content,
+ *     };
+ *   }
+ * }
+ * ```
+ */
 class MessageTransformer {
 }
 exports.MessageTransformer = MessageTransformer;

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

@@ -1,9 +1,68 @@
-import { BaseInstance, BaseUser, Instance, Settings } from "../types/types";
-export declare abstract class StorageProvider<TUser extends BaseUser = BaseUser, TInstance extends BaseInstance = Instance, TUserCreate extends Record<string, any> = any, TUserUpdate extends Record<string, any> = any> {
-    abstract createInstance(instance: BaseInstance, userId: bigint | number, settings?: Settings): Promise<TInstance>;
+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.
+ *
+ * @category Storage
+ * @typeParam TUser - User entity type, extends BaseUser
+ * @typeParam TInstance - Instance entity type, extends Instance
+ * @typeParam TUserCreate - Shape of data required to create a user
+ * @typeParam TUserUpdate - Shape of data allowed for user updates
+ *
+ * @example
+ * ```typescript
+ * class PostgresStorage extends StorageProvider<User, Instance> {
+ *   async createInstance(instance: Instance, userId: bigint, settings?: Settings) {
+ *     return prisma.instance.create({
+ *       data: { ...instance, userId, settings }
+ *     });
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class StorageProvider<TUser extends BaseUser = BaseUser, TInstance extends Instance = Instance, TUserCreate extends Record<string, any> = any, TUserUpdate extends Record<string, any> = any> {
+    /**
+     * 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>;
+    /**
+     * Retrieves an instance by its ID.
+     *
+     * @param idInstance - The instance ID to look up
+     * @returns Promise resolving to the instance or null if not found
+     */
     abstract getInstance(idInstance: number | bigint): Promise<TInstance | null>;
+    /**
+     * Removes an instance from storage.
+     *
+     * @param instanceId - ID of the instance to remove
+     * @returns Promise resolving to the removed instance
+     */
     abstract removeInstance(instanceId: number | bigint): Promise<TInstance>;
+    /**
+     * Creates a new user in storage.
+     *
+     * @param data - User data matching TUserCreate type
+     * @returns Promise resolving to the created user
+     */
     abstract createUser(data: TUserCreate): Promise<TUser>;
+    /**
+     * Finds a user by identifier (usually email or username).
+     *
+     * @param identifier - The identifier to look up
+     * @returns Promise resolving to the user or null if not found
+     */
     abstract findUser(identifier: string): Promise<TUser | null>;
+    /**
+     * Updates an existing user's data.
+     *
+     * @param identifier - The identifier of the user to update
+     * @param data - Partial update data matching TUserUpdate type
+     * @returns Promise resolving to the updated user
+     */
     abstract updateUser(identifier: string, data: Partial<TUserUpdate>): Promise<TUser>;
 }

package/dist/core/storage-provider.js

@@ -1,6 +1,27 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.StorageProvider = void 0;
+/**
+ * Abstract class for managing instance and user data storage.
+ * Implement this class to define how your integration stores and retrieves data.
+ *
+ * @category Storage
+ * @typeParam TUser - User entity type, extends BaseUser
+ * @typeParam TInstance - Instance entity type, extends Instance
+ * @typeParam TUserCreate - Shape of data required to create a user
+ * @typeParam TUserUpdate - Shape of data allowed for user updates
+ *
+ * @example
+ * ```typescript
+ * class PostgresStorage extends StorageProvider<User, Instance> {
+ *   async createInstance(instance: Instance, userId: bigint, settings?: Settings) {
+ *     return prisma.instance.create({
+ *       data: { ...instance, userId, settings }
+ *     });
+ *   }
+ * }
+ * ```
+ */
 class StorageProvider {
 }
 exports.StorageProvider = StorageProvider;

package/dist/index.d.ts

@@ -5,3 +5,4 @@ export { MessageTransformer } from "./core/message-transformer";
 export { BaseGreenApiAuthGuard } from "./core/guard";
 export { StorageProvider } from "./core/storage-provider";
 export * from "./utils/helpers";
+export * from "./core/errors";

package/dist/index.js

@@ -27,3 +27,4 @@ Object.defineProperty(exports, "BaseGreenApiAuthGuard", { enumerable: true, get:
 var storage_provider_1 = require("./core/storage-provider");
 Object.defineProperty(exports, "StorageProvider", { enumerable: true, get: function () { return storage_provider_1.StorageProvider; } });
 __exportStar(require("./utils/helpers"), exports);
+__exportStar(require("./core/errors"), exports);