@green-api/greenapi-integration 0.1.0 → 0.3.0

package/README.md

@@ -37,15 +37,6 @@ npm install @green-api/greenapi-integration
 ### 1. BaseAdapter
 
 The foundation of your integration. Handles message & instance management, and platform-specific logic.
-The `BaseAdapter` internally uses `GreenApiClient` for all common operations, so in most cases, you don't need to use
-GreenApiClient methods directly.
-
-**When to use `BaseAdapter` vs `GreenApiClient`**:
-
-✅ Use `BaseAdapter` methods for all standard operations (sending messages, handling webhooks, managing instances)
-
-⚠️ Use `GreenApiClient` directly only for specialized operations not covered by BaseAdapter (like setProfilePicture,
-getAuthorizationCode)
 
 ```typescript
 abstract class BaseAdapter<TPlatformWebhook, TPlatformMessage> {
@@ -60,19 +51,76 @@ abstract class BaseAdapter<TPlatformWebhook, TPlatformMessage> {
 }
 ```
 
-**Example of proper usage:**
+#### Methods
+
+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.
 
 ```typescript
-// ✅ CORRECT: Using BaseAdapter for standard operations
-const adapter = new YourAdapter(transformer, storage);
-await adapter.handlePlatformWebhook(webhook, instanceId);
-await adapter.createInstance(instance, settings, userCred);
-await adapter.sendMessage(transformedWebhook);
+// Handle webhooks from your platform
+await adapter.handlePlatformWebhook(webhookData, instanceId);
 
-// ⚠️ ONLY IF NEEDED: Direct GreenApiClient usage for specialized operations
-const client = new GreenApiClient(instance);
-await client.setProfilePicture(fileBlob);
-await client.getAuthorizationCode(phoneNumber);
+// Handle webhooks from GREEN-API. The second parameter is telling the function to handle only specific webhooks.
+// The second parameter must be specified, otherwise webhooks will not be processed.
+await adapter.handleGreenApiWebhook(webhook, ['incomingMessageReceived']);
+```
+
+##### Instance Management
+
+```typescript
+// Create new instance
+const instance = await adapter.createInstance(instanceData, settings, userEmail);
+
+// Get instance details
+const details = await adapter.getInstance(instanceId);
+
+// Remove instance
+await adapter.removeInstance(instanceId);
+```
+
+##### User Management
+
+```typescript
+// Create new user
+const user = await adapter.createUser(userEmail, userData);
+
+// Update user
+await adapter.updateUser(userEmail, updateData);
+```
+
+#### Webhook Implementation Example
+
+```typescript
+// Platform webhook endpoint
+app.post('/webhook/platform', async (req, res) => {
+	try {
+		await adapter.handlePlatformWebhook(req.body, instanceId);
+		res.status(200).send();
+	} catch (error) {
+		console.error('Failed to handle platform webhook:', error);
+		res.status(500).send();
+	}
+});
+
+// GREEN-API webhook endpoint
+app.post('/webhook/green-api', async (req, res) => {
+	try {
+		// Process specific webhook types
+		await adapter.handleGreenApiWebhook(req.body, [
+			'incomingMessageReceived',
+			'outgoingMessageStatus'
+		]);
+		res.status(200).send();
+	} catch (error) {
+		console.error('Failed to handle GREEN-API webhook:', error);
+		res.status(500).send();
+	}
+});
 ```
 
 ### 2. MessageTransformer
@@ -147,8 +195,7 @@ app.post('/webhook', async (req, res) => {
 
 ### 5. GreenApiClient
 
-Direct interface to GREEN-API endpoints. While most operations should be handled through BaseAdapter, GreenApiClient can
-be used directly for specialized operations.
+Direct interface to GREEN-API methods.
 
 ```typescript
 const client = new GreenApiClient({
@@ -156,7 +203,7 @@ const client = new GreenApiClient({
 	apiTokenInstance: 'your_token'
 });
 
-// Examples of specialized operations:
+// Examples:
 await client.setProfilePicture(fileBlob);
 await client.getAuthorizationCode(phoneNumber);
 await client.getQR();
@@ -164,6 +211,8 @@ await client.getQR();
 
 ## Developer Guide
 
+This guide will walk you through creating your first integration with GREEN-API's WhatsApp gateway.
+
 ### Project Structure
 
 ```
@@ -181,9 +230,37 @@ your-integration/
 └── tsconfig.json
 ```
 
+```mermaid
+graph TB
+    subgraph "WhatsApp to Platform"
+        WA[WhatsApp] -->|Send message| GA1[GREEN-API]
+        GA1 -->|Webhook| INT1[Your Integration]
+        INT1 -->|1 . Validate webhook| GD1[BaseGreenApiAuthGuard]
+        INT1 -->|2 . Transform message| TR1[MessageTransformer]
+        INT1 -->|3 . Send to platform| PL1[Your Platform]
+    end
+
+    subgraph "Platform to WhatsApp"
+        PL2[Your Platform] -->|Webhook| INT2[Your Integration]
+        INT2 -->|1 . Transform message| TR2[MessageTransformer]
+        INT2 -->|2 . Send via API| GA2[GREEN-API]
+        GA2 -->|Send message| WA2[WhatsApp]
+    end
+
+    subgraph "Components"
+        style Components fill: #f9f9f9, stroke: #333, stroke-width: 2px
+        TR[MessageTransformer]
+        ST[StorageProvider]
+        AD[BaseAdapter]
+        GD[WebhookGuard]
+    end
+```
+
 ### Implementation Steps
 
-1. **Define Platform Types**
+#### Step 1: Define Platform Types
+
+First, define the message types for your platform:
 
 ```typescript
 // types/types.ts
@@ -202,7 +279,9 @@ export interface YourPlatformMessage {
 }
 ```
 
-2. **Create Message Transformer**
+#### Step 2: Create Message Transformer
+
+Create a transformer that converts messages between your platform's format and GREEN-API's format:
 
 ```typescript
 // core/transformer.ts
@@ -229,7 +308,9 @@ export class YourTransformer extends MessageTransformer<YourPlatformWebhook, You
 }
 ```
 
-3. **Implement Storage**
+#### Step 3: Implement Storage Provider
+
+Create a storage provider to manage users and instances. You can use any database or ORM:
 
 ```typescript
 // core/storage.ts
@@ -258,7 +339,9 @@ export class YourStorage extends StorageProvider {
 }
 ```
 
-4. **Create Platform Adapter**
+#### Step 4: Create Your Platform Adapter
+
+The adapter handles the actual communication between platforms:
 
 ```typescript
 // core/adapter.ts
@@ -281,7 +364,9 @@ export class YourAdapter extends BaseAdapter<YourPlatformWebhook, YourPlatformMe
 }
 ```
 
-5. **Implement Webhook Controller**
+#### Step 5: Implement Webhook Controller
+
+Define webhook endpoints that your application will listen to:
 
 ```typescript
 // core/webhook.ts
@@ -366,7 +451,9 @@ router.post('/instance', async (req, res) => {
 export default router;
 ```
 
-6. **Create Application Entry Point**
+#### Step 6: Create Application Entry Point
+
+Put it all together in your entrypoint:
 
 ```typescript
 // main.ts
@@ -407,24 +494,6 @@ async function bootstrap() {
 bootstrap();
 ```
 
-Or with NestJS:
-
-```typescript
-// main.ts
-import { NestFactory } from '@nestjs/core';
-import { AppModule } from './app.module';
-import helmet from 'helmet';
-
-async function bootstrap() {
-	const app = await NestFactory.create(AppModule);
-	app.setGlobalPrefix('api');
-	app.use(helmet());
-	await app.listen(process.env.PORT ?? 3000);
-}
-
-bootstrap();
-```
-
 ### Publishing Your Integration
 
 1. **Prepare package.json**
@@ -441,7 +510,6 @@ bootstrap();
   },
   "dependencies": {
     "@green-api/greenapi-integration": "^1.0.0",
-    "@prisma/client": "^5.0.0",
     "express": "^4.18.2"
     // other dependencies
   }
@@ -741,18 +809,7 @@ PORT=3000
 
 For complete real-world integration examples, check out:
 
-- [Rocket.Chat Integration](link-to-rocket-chat-repo)
-
-## Best Practices
-
-1. **Message Transformation**:
-    - Handle only relevant message types
-
-2. **Security**:
-    - Validate all incoming webhooks
-    - Use secure tokens
-    - Implement rate limiting
-    - Use HTTPS for all endpoints
+- [Rocket.Chat Integration](https://github.com/green-api/greenapi-integration-rocketchat)
 
 ## Utilities
 
@@ -764,6 +821,10 @@ formatPhoneNumber('1234567890') // Returns '1234567890@c.us'
 
 // Generate secure random tokens
 generateRandomToken(32) // Returns a 32-character random token
+
+// Extract phone number from vcard
+const vcard = 'BEGIN:VCARD\nTEL:+1234567890\nEND:VCARD'
+extractPhoneNumberFromVCard(vcard) // Returns '+1234567890'
 ```
 
 ## License

package/README.ru.md

@@ -37,17 +37,6 @@ npm install @green-api/greenapi-integration
 ### 1. BaseAdapter
 
 Основа вашей интеграции. Управляет сообщениями и инстансами, а также логикой взаимодействия с платформой.
-BaseAdapter внутренне использует GreenApiClient для всех общих операций, поэтому в большинстве случаев вам не нужно
-использовать
-методы GreenApiClient напрямую.
-
-**Когда использовать BaseAdapter, а когда GreenApiClient**:
-
-✅ Используйте методы BaseAdapter для всех стандартных операций (отправка сообщений, обработка вебхуков, управление
-инстансами)
-
-⚠️ Используйте GreenApiClient напрямую только для специальных операций, не покрытых BaseAdapter (например,
-setProfilePicture, getAuthorizationCode)
 
 ```typescript
 abstract class BaseAdapter<TPlatformWebhook, TPlatformMessage> {
@@ -62,19 +51,75 @@ abstract class BaseAdapter<TPlatformWebhook, TPlatformMessage> {
 }
 ```
 
-**Пример правильного использования:**
+#### Методы
+
+При расширении BaseAdapter, ваша реализация получает доступ к следующим методам:
+
+##### Обработка вебхуков
+
+Эти методы обработки вебхуков автоматически вызывают ваши методы преобразования (маппинга) сообщений, без необходимости
+использовать их напрямую.
 
 ```typescript
-// ✅ ПРАВИЛЬНО: Использование BaseAdapter для стандартных операций
-const adapter = new YourAdapter(transformer, storage);
-await adapter.handlePlatformWebhook(webhook, instanceId);
-await adapter.createInstance(instance, settings, userCred);
-await adapter.sendMessage(transformedWebhook);
+// Обработка вебхуков от вашей платформы
+await adapter.handlePlatformWebhook(webhookData, instanceId);
 
-// ⚠️ ТОЛЬКО ПРИ НЕОБХОДИМОСТИ: Прямое использование GreenApiClient для специальных операций
-const client = new GreenApiClient(instance);
-await client.setProfilePicture(fileBlob);
-await client.getAuthorizationCode(phoneNumber);
+// Обработка вебхуков от GREEN-API. Второй параметр указывает функции, какие конкретные вебхуки обрабатывать.
+// Второй параметр должен быть указан, иначе вебхуки не будут обработаны.
+await adapter.handleGreenApiWebhook(webhook, ['incomingMessageReceived']);
+```
+
+##### Управление инстансами
+
+```typescript
+// Создание нового инстанса
+const instance = await adapter.createInstance(instanceData, settings, userEmail);
+
+// Получение данных инстанса
+const details = await adapter.getInstance(instanceId);
+
+// Удаление инстанса
+await adapter.removeInstance(instanceId);
+```
+
+##### Управление пользователями
+
+```typescript
+// Создание нового пользователя
+const user = await adapter.createUser(userEmail, userData);
+
+// Обновление пользователя
+await adapter.updateUser(userEmail, updateData);
+```
+
+#### Пример реализации вебхуков
+
+```typescript
+// Конечная точка для вебхуков платформы
+app.post('/webhook/platform', async (req, res) => {
+	try {
+		await adapter.handlePlatformWebhook(req.body, instanceId);
+		res.status(200).send();
+	} catch (error) {
+		console.error('Не удалось обработать вебхук платформы:', error);
+		res.status(500).send();
+	}
+});
+
+// Конечная точка для вебхуков GREEN-API
+app.post('/webhook/green-api', async (req, res) => {
+	try {
+		// Обработка определенных типов вебхуков
+		await adapter.handleGreenApiWebhook(req.body, [
+			'incomingMessageReceived',
+			'outgoingMessageStatus'
+		]);
+		res.status(200).send();
+	} catch (error) {
+		console.error('Не удалось обработать вебхук GREEN-API:', error);
+		res.status(500).send();
+	}
+});
 ```
 
 ### 2. MessageTransformer
@@ -166,6 +211,8 @@ await client.getQR();
 
 ## Руководство разработчика
 
+Это руководство проведет вас через процесс создания вашей первой интеграции с WhatsApp шлюзом GREEN-API.
+
 ### Структура проекта
 
 ```
@@ -183,9 +230,37 @@ your-integration/
 └── tsconfig.json
 ```
 
+```mermaid
+graph TB
+    subgraph "WhatsApp в Платформу"
+        WA[WhatsApp] -->|Отправка сообщения| GA1[GREEN-API]
+        GA1 -->|Вебхук| INT1[Ваша Интеграция]
+        INT1 -->|1 . Валидация вебхука| GD1[BaseGreenApiAuthGuard]
+        INT1 -->|2 . Преобразование сообщения| TR1[MessageTransformer]
+        INT1 -->|3 . Отправка в платформу| PL1[Ваша Платформа]
+    end
+
+    subgraph "Платформа в WhatsApp"
+        PL2[Ваша Платформа] -->|Вебхук| INT2[Ваша Интеграция]
+        INT2 -->|1 . Преобразование сообщения| TR2[MessageTransformer]
+        INT2 -->|2 . Отправка через API| GA2[GREEN-API]
+        GA2 -->|Отправка сообщения| WA2[WhatsApp]
+    end
+
+    subgraph "Компоненты"
+        style Компоненты fill: #f9f9f9, stroke: #333, stroke-width: 2px
+        TR[MessageTransformer]
+        ST[StorageProvider]
+        AD[BaseAdapter]
+        GD[WebhookGuard]
+    end
+```
+
 ### Этапы реализации
 
-1. **Определение типов платформы**
+#### Этап 1: Определение типов платформы
+
+Сначала определите типы сообщений для вашей платформы:
 
 ```typescript
 // types/types.ts
@@ -204,7 +279,9 @@ export interface YourPlatformMessage {
 }
 ```
 
-2. **Создание преобразователя сообщений**
+#### Этап 2. Создание преобразователя сообщений
+
+Создайте преобразователь, который конвертирует сообщения между форматом вашей платформы и форматом GREEN-API:
 
 ```typescript
 // core/transformer.ts
@@ -231,7 +308,10 @@ export class YourTransformer extends MessageTransformer<YourPlatformWebhook, You
 }
 ```
 
-3. **Реализация хранилища**
+#### Этап 3: Реализация хранилища
+
+Создайте провайдер хранилища для управления пользователями и инстансами. Вы можете использовать любую базу данных или
+ORM:
 
 ```typescript
 // core/storage.ts
@@ -260,7 +340,9 @@ export class YourStorage extends StorageProvider {
 }
 ```
 
-4. **Создание адаптера платформы**
+#### Этап 4: Создание адаптера платформы
+
+Адаптер обрабатывает фактическое взаимодействие между платформами:
 
 ```typescript
 // core/adapter.ts
@@ -283,7 +365,9 @@ export class YourAdapter extends BaseAdapter<YourPlatformWebhook, YourPlatformMe
 }
 ```
 
-5. **Реализация контроллера вебхуков**
+#### Этап 5: Реализация контроллера вебхуков
+
+Определите эндпоинты вебхуков, которые будет слушать ваше приложение:
 
 ```typescript
 // core/webhook.ts
@@ -368,7 +452,9 @@ router.post('/instance', async (req, res) => {
 export default router;
 ```
 
-6. **Создание точки входа приложения**
+#### Этап 6: Создание точки входа приложения
+
+Соберите все компоненты вместе в точке входа:
 
 ```typescript
 // main.ts
@@ -744,18 +830,7 @@ PORT=3000
 
 Для полных примеров реальных интеграций, смотрите:
 
-- [Интеграция с Rocket.Chat](link-to-rocket-chat-repo)
-
-## Лучшие практики
-
-1. **Преобразование сообщений**:
-    - Обрабатывайте только релевантные типы сообщений
-
-2. **Безопасность**:
-    - Проверяйте все входящие вебхуки
-    - Используйте безопасные вебхук-токены
-    - Реализуйте ограничение частоты запросов
-    - Используйте HTTPS для всех эндпоинтов
+- [Интеграция с Rocket.Chat](https://github.com/green-api/greenapi-integration-rocketchat)
 
 ## Утилиты
 
@@ -767,6 +842,10 @@ formatPhoneNumber('1234567890') // Возвращает '1234567890@c.us'
 
 // Генерация безопасных случайных токенов
 generateRandomToken(32) // Возвращает 32-символьный случайный токен
+
+// Извлечение номера телефона из vcard
+const vcard = 'BEGIN:VCARD\nTEL:+1234567890\nEND:VCARD'
+extractPhoneNumberFromVCard(vcard) // Возвращает '+1234567890'
 ```
 
 ## Лицензия

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

@@ -1,23 +1,164 @@
 import { GreenApiClient } from "./green-api.client";
 import { MessageTransformer } from "./message-transformer";
-import { BaseInstance, BaseUser, ForwardMessagesResponse, IncomingGreenApiWebhook, Instance, SendResponse, Settings } from "../types/types";
+import { BaseUser, ForwardMessagesResponse, GreenApiWebhook, Instance, SendResponse, StateInstanceWebhook, WebhookType } from "../types/types";
 import { StorageProvider } from "./storage-provider";
-export declare abstract class BaseAdapter<TPlatformWebhook, TPlatformMessage, TUser extends BaseUser = BaseUser, TInstance extends BaseInstance = Instance> {
+/**
+ * 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);
+ *   }
+ * }
+ * ```
+ */
+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>;
+    /**
+     * 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>);
+    /**
+     * Sends a message to your platform. This method must be implemented to define how
+     * messages are sent to your specific platform.
+     *
+     * @param message - The platform-specific message to send
+     * @param instance - The instance configuration for the current integration
+     * @returns Promise that resolves when the message is sent
+     *
+     * @example
+     * ```typescript
+     * async sendToPlatform(message: YourMessage, instance: Instance) {
+     *   const client = await this.createPlatformClient(instance.config);
+     *   await client.sendMessage({
+     *     recipient: message.to,
+     *     content: message.text
+     *   });
+     * }
+     * ```
+     */
     abstract sendToPlatform(message: TPlatformMessage, instance: TInstance): Promise<void>;
-    createGreenApiClient(instance: BaseInstance): GreenApiClient;
-    private handleError;
+    /**
+     * Creates a platform-specific client. This method must be implemented to define how
+     * to create a client for your platform's API.
+     *
+     * @param params - Configuration parameters for your platform's client
+     * @returns Promise resolving to your platform's client instance
+     *
+     * @example
+     * ```typescript
+     * async createPlatformClient(config: YourConfig) {
+     *   return new YourPlatformSDK({
+     *     apiKey: config.apiKey,
+     *     apiUrl: config.apiUrl
+     *   });
+     * }
+     * ```
+     */
     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.
+     *
+     * @param instance - The instance configuration containing ID and token
+     * @returns GREEN-API client
+     */
+    createGreenApiClient(instance: Instance): GreenApiClient;
+    /**
+     * 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
+     */
+    private handleError;
+    /**
+     * 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
+     */
     handlePlatformWebhook(message: TPlatformWebhook, idInstance: number | bigint): Promise<SendResponse | ForwardMessagesResponse>;
-    handleGreenApiWebhook(webhook: IncomingGreenApiWebhook, allowedTypes: string[]): Promise<void>;
-    createInstance(instance: Instance, settings: Settings, userCred: any): Promise<TInstance>;
+    /**
+     * 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
+     */
+    handleGreenApiWebhook(webhook: GreenApiWebhook, allowedTypes: WebhookType[]): Promise<void>;
+    /**
+     * 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>;
+    /**
+     * 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
+     */
     removeInstance(idInstance: number | bigint): Promise<TInstance>;
+    /**
+     * 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
+     */
     getInstance(idInstance: number | bigint): Promise<TInstance | null>;
-    updateUser(userCred: any, userUpdateData: any): Promise<{
-        status: string;
-        message: string;
-    }>;
+    /**
+     * Updates user information.
+     *
+     * @param userCred - User credentials
+     * @param userUpdateData - New user data
+     * @returns Promise resolving to success status
+     * @throws {IntegrationError} If update fails
+     */
+    updateUser(userCred: any, userUpdateData: any): Promise<TUser>;
+    /**
+     * 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
+     */
     createUser(userCred: any, data: any): Promise<TUser>;
 }