@natyapp/meta 1.6.6 → 1.6.7

package/README.md

@@ -1,68 +1,420 @@
-# SDK MICROSSERVIÇO SECRETARIA NATY / META
+# @natyapp/meta
 
-## `_UNDER DEVELOPMENT_`
+A TypeScript SDK for integrating with Meta's WhatsApp Business API, providing a simple and elegant way to send messages, handle webhooks, and manage WhatsApp business communications.
 
-<!-- `(Will not work until March, please wait the Release)` -->
+## Features
 
-<!-- ## HOW WILL WORK -->
+- 🚀 **Easy Integration** - Simple setup with your Meta app token
+- 📱 **Rich Messaging** - Send text, images, documents, buttons, lists, and more
+- 🎯 **Interactive Elements** - Support for buttons, menus, and quick replies
+- 📍 **Location & Contacts** - Send location and contact information
+- 🔔 **Webhook Support** - Handle incoming messages and events
+- 📊 **Logging & Monitoring** - Built-in logging capabilities
+- 🛡️ **Type Safety** - Full TypeScript support with type definitions
+- ⚡ **Modern Architecture** - Built with async/await and promises
 
-### First we will import and Initialize the sdk package
+## Installation
 
-#### 1. importing the package
+```bash
+npm install @natyapp/meta
+```
+
+```bash
+yarn add @natyapp/meta
+```
+
+```bash
+pnpm add @natyapp/meta
+```
+
+## Quick Start
+
+### 1. Import the SDK
+
+```typescript
+import NatyMeta, { WhatsappResponse } from '@natyapp/meta';
+```
+
+### 2. Environment Configuration
+
+Set the API URL in your environment variables:
+
+```bash
+API_META=https://api.meta.naty.app
+```
+
+### 3. Initialize the SDK
+
+```typescript
+// Initialize without token
+const sdk = new NatyMeta();
+
+// Or initialize with token directly
+const sdk = new NatyMeta('YOUR_APP_TOKEN');
+```
+
+### 4. Connect to the API
+
+```typescript
+const connectResult = await sdk.connect({
+  appToken: 'YOUR_APP_TOKEN'
+});
+
+if (connectResult.isError) {
+  throw new Error(connectResult.isError.message);
+}
+
+console.log('Connected successfully:', connectResult.isSuccess);
+```
+
+## Usage Examples
+
+### Sending Messages
+
+#### Text Message
+
+```typescript
+import { Message } from '@natyapp/meta';
+
+const message = new Message('PHONE_NUMBER', 'MESSAGE_ID', 'ACCESS_TOKEN');
+
+// Send a simple text message
+const response = await message.send_text_message('Hello, World!');
+```
+
+#### Button Message
+
+```typescript
+import { Button } from '@natyapp/meta';
+
+const button = new Button({
+  type: 'button',
+  body: 'Choose an option:',
+  buttons: [
+    {
+      id: 'option1',
+      title: 'Option 1'
+    },
+    {
+      id: 'option2', 
+      title: 'Option 2'
+    }
+  ]
+});
+
+const response = await message.send_button(button);
+```
+
+#### List Message
+
+```typescript
+import { List } from '@natyapp/meta';
+
+const list = new List({
+  header: 'Our Services',
+  body: 'Please select a service:',
+  footer: 'Thank you for choosing us!',
+  button: 'View Services',
+  sections: [
+    {
+      title: 'Main Services',
+      rows: [
+        {
+          id: 'service1',
+          title: 'Web Development',
+          description: 'Custom web applications'
+        },
+        {
+          id: 'service2',
+          title: 'Mobile Apps',
+          description: 'iOS and Android applications'
+        }
+      ]
+    }
+  ]
+});
+
+const response = await message.send_list(list);
+```
+
+#### Document Message
+
+```typescript
+// Send document from URL
+const response = await message.send_document(
+  'https://example.com/document.pdf',
+  'application/pdf',
+  {
+    fileName: 'report.pdf',
+    description: 'Monthly report'
+  }
+);
+
+// Send document from base64
+const response = await message.send_document(
+  'base64EncodedString',
+  'application/pdf',
+  {
+    fileName: 'document.pdf',
+    description: 'Important document'
+  }
+);
+```
+
+#### Image Message
+
+```typescript
+// Send image from URL
+const response = await message.send_image('https://example.com/image.jpg');
+
+// Send image from base64
+const response = await message.send_image('base64EncodedString');
+```
+
+#### Location Message
+
+```typescript
+const response = await message.send_location({
+  lat: -23.5505,
+  long: -46.6333,
+  name: 'São Paulo',
+  address: 'São Paulo, Brazil'
+});
+```
+
+#### Contact Message
 
-```ts
-  import SDKMeta from "NatyMeta"
+```typescript
+const contacts = [
+  {
+    name: {
+      first_name: 'John',
+      last_name: 'Doe'
+    },
+    phones: [
+      {
+        phone: '+1234567890',
+        type: 'WORK'
+      }
+    ],
+    emails: [
+      {
+        email: 'john.doe@example.com',
+        type: 'WORK'
+      }
+    ]
+  }
+];
+
+const response = await message.send_contacts(contacts);
+```
+
+### Message Reactions and Status
+
+#### React to Message
+
+```typescript
+// Send thumbs up reaction
+const response = await message.send_reaction('👍');
+
+// Send custom emoji
+const response = await message.send_reaction('😊');
+```
+
+#### Mark as Read
+
+```typescript
+const success = await message.mark_as_read();
+```
+
+#### Reply to Message
+
+```typescript
+// Reply with text
+const response = await message.reply({
+  type: 'text',
+  toReply: 'This is a reply message',
+  messageToReply: 'ORIGINAL_MESSAGE_ID'
+});
+
+// Reply with interactive element
+const response = await message.reply({
+  type: 'interactive',
+  toReply: buttonObject,
+  messageToReply: 'ORIGINAL_MESSAGE_ID'
+});
 ```
 
-#### 2. set environment variable  
+### Webhook Handling
+
+```typescript
+import { Webhook } from '@natyapp/meta';
 
-  The API URL for the integration with the Meta API. The default value is `https://api.meta.naty.app`  
+// Initialize webhook handler
+const webhook = new Webhook();
+
+// Listen for incoming messages
+sdk.on('message', (response: WhatsappResponse) => {
+  console.log('Received message:', response);
+  
+  // Send automatic reply
+  response.send_text_message('Thank you for your message!');
+});
+
+// Setup webhook endpoint (if using Express)
+import express from 'express';
+const app = express();
+
+app.use('/webhook', webhook.getRouter());
+```
 
-  ```text
-    API_META=https://api.meta.naty.app
-  ```
+### Media Handling
 
-#### 3. initialize the class
+```typescript
+// Get media URL from media ID
+const mediaData = await message.get_media_url('MEDIA_ID');
+console.log('Media URL:', mediaData.url);
 
-```ts
-  const SDK = new NatyMeta()
-  // you can use new sdk(`YOUR-APP-TOKEN`) to connect right on the class creation
+// Create media from file
+const mediaId = await message.createMedia(
+  'base64EncodedContent',
+  'image/jpeg'
+);
 ```
 
-#### 4. connect your app token (if you dont use your token on class creation)
+### Connection Management
 
-```ts
-  const connectSDK = await SDK.connect( {apptoken: { `YOUR-APP-TOKEN` } } )
+```typescript
+import { Connection } from '@natyapp/meta';
 
-  if(connectSDK.isError) throw new Error(connectSDK.isError.message)
+// Create new connection
+const connection = new Connection();
 
-  console.log(connectSDK.isSuccess)
-        // Do what you need with the data... (connectSDK.isSuccess)
+// Check connection status
+const status = await connection.getStatus();
+
+// Update connection settings
+const updated = await connection.updateSettings({
+  webhookUrl: 'https://your-domain.com/webhook',
+  verifyToken: 'your-verify-token'
+});
 ```
 
-#### 5. connect your app token (if you dont use your token on class creation)
+### Logging
+
+```typescript
+import { Log } from '@natyapp/meta';
+
+const logger = new Log();
 
-```ts
- SDK.on('message', (res) => {
-  res.sendTextMessage("teste");
+// Log message activity
+await logger.logMessage({
+  messageId: 'MESSAGE_ID',
+  phoneNumber: 'PHONE_NUMBER',
+  content: 'Message content',
+  type: 'outbound'
+});
+
+// Get message logs
+const logs = await logger.getMessageLogs({
+  phoneNumber: 'PHONE_NUMBER',
+  startDate: new Date('2024-01-01'),
+  endDate: new Date('2024-12-31')
 });
 ```
 
-#### 6. than set your application context to use all the individual classes
+## Error Handling
+
+The SDK uses a consistent error handling pattern:
+
+```typescript
+const result = await sdk.someMethod();
+
+if (result.isError) {
+  console.error('Error occurred:', result.isError.message);
+  // Handle error appropriately
+  return;
+}
+
+// Success case
+console.log('Success:', result.isSuccess);
+```
+
+## TypeScript Support
+
+The SDK is written in TypeScript and provides full type definitions:
+
+```typescript
+import { 
+  WhatsappResponse,
+  ISendMessageReturn,
+  ConnectProps,
+  Button,
+  List
+} from '@natyapp/meta';
+
+// All types are available for import
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `API_META` | Meta API base URL | `https://api.meta.naty.app` |
+
+### Initialization Options
+
+```typescript
+interface ConnectProps {
+  appToken: string;
+  pathname?: string;  // Custom webhook path
+  app?: Express;      // Express app instance
+}
+```
+
+## API Reference
+
+### Classes
+
+- **NatyMeta** - Main SDK class
+- **Message** - Handle message operations
+- **Webhook** - Webhook management
+- **Connection** - Connection management
+- **Log** - Logging functionality
+- **WhatsappResponse** - Response handler
+
+### Elements
+
+- **Button** - Interactive buttons
+- **List** - List messages
+- **Text** - Text messages
+- **Image** - Image messages
+
+## Requirements
+
+- Node.js >= 14
+- TypeScript >= 4.9 (for development)
+
+## Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+## License
+
+ISC License - see [LICENSE](LICENSE) file for details.
+
+## Support
 
-#### In this example  
+- 📧 **Email**: <support@naty.app>
+- 🐛 **Issues**: [GitHub Issues](https://github.com/your-org/sdk-meta/issues)
+- 📚 **Documentation**: [Full Documentation](https://docs.naty.app)
 
-- Retun of any Promise is {isSuccess:AuthReturnType, isError:ErrorHandlingType}  
-- If successed method (like the SDK.connect example too),  
-  the sdk will abstract and will handle properly with the token for you,  
-the token will be automatic joined into axios instance header  
-- ErrorHandling type { code: number, message: string | Object }  
-- On the exemple, we are using "throw new Error" on every ErrorHandling to  
-stop and handle it on a simple way, but u can work at your way like  
-returning an alert using some alert lib like toastfy for the user.  
+## Authors
 
-<!-- ## Click on [NatyMeta](https://whatsapp.secretarianaty.com) for more information. -->
+- **IkiraDev** - *Initial work*
 
-##### (The link will be avalible soon)
+---
 
-###### All Rights Reserved for Ikiradev
+Made with ❤️ by the Naty team

package/dist/elements/index.d.ts

@@ -2,3 +2,4 @@ export * from "./button";
 export * from "./list";
 export * from "./text";
 export * from "./textTemplate";
+export * from "./mediaTemplate";

package/dist/elements/index.js

@@ -18,3 +18,4 @@ __exportStar(require("./button"), exports);
 __exportStar(require("./list"), exports);
 __exportStar(require("./text"), exports);
 __exportStar(require("./textTemplate"), exports);
+__exportStar(require("./mediaTemplate"), exports);

package/dist/elements/mediaTemplate.d.ts

@@ -0,0 +1,45 @@
+export declare class MediaTemplate {
+    messaging_product: string;
+    recipient_type: string;
+    to: string;
+    type: string;
+    template: {
+        name: string;
+        language: {
+            code: string;
+        };
+        components: Array<{
+            type: string;
+            parameters: Array<{
+                type: string;
+                image?: {
+                    link: string;
+                };
+                video?: {
+                    link: string;
+                };
+                document?: {
+                    link: string;
+                    filename?: string;
+                };
+                text: string;
+            }>;
+        }>;
+    };
+    constructor({ template, language, to, header, bodyParameters }: {
+        template: string;
+        to: string;
+        language: string;
+        header?: {
+            type: "image" | "video" | "document";
+            media: {
+                link: string;
+                filename?: string;
+            };
+        };
+        bodyParameters?: Array<{
+            type: string;
+            text: string;
+        }>;
+    });
+}

package/dist/elements/mediaTemplate.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MediaTemplate = void 0;
+class MediaTemplate {
+    constructor({ template, language, to, header, bodyParameters }) {
+        this.messaging_product = "whatsapp";
+        this.recipient_type = "individual";
+        this.to = to;
+        this.type = "template";
+        const components = [];
+        if (header) {
+            const headerParam = {
+                type: header.type
+            };
+            if (header.type === "image") {
+                headerParam.image = { link: header.media.link };
+            }
+            else if (header.type === "video") {
+                headerParam.video = { link: header.media.link };
+            }
+            else if (header.type === "document") {
+                headerParam.document = Object.assign({ link: header.media.link }, (header.media.filename && { filename: header.media.filename }));
+            }
+            components.push({
+                type: "header",
+                parameters: [headerParam]
+            });
+        }
+        if (bodyParameters && bodyParameters.length > 0) {
+            components.push({
+                type: "body",
+                parameters: bodyParameters.map(param => ({
+                    type: param.type,
+                    text: param.text
+                }))
+            });
+        }
+        this.template = {
+            name: template,
+            language: {
+                code: language,
+            },
+            components
+        };
+    }
+}
+exports.MediaTemplate = MediaTemplate;

package/dist/elements/textTemplate.d.ts

@@ -8,10 +8,21 @@ export declare class TextTemplate {
         language: {
             code: string;
         };
+        components?: Array<{
+            type: string;
+            parameters: Array<{
+                type: string;
+                text: string;
+            }>;
+        }>;
     };
-    constructor({ template, language, to }: {
+    constructor({ template, language, to, bodyParameters }: {
         template: string;
         to: string;
         language: string;
+        bodyParameters?: Array<{
+            type: string;
+            text: string;
+        }>;
     });
 }

package/dist/elements/textTemplate.js

@@ -2,17 +2,24 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TextTemplate = void 0;
 class TextTemplate {
-    constructor({ template, language, to }) {
+    constructor({ template, language, to, bodyParameters }) {
         this.messaging_product = "whatsapp";
         this.recipient_type = "individual";
         this.to = to;
         this.type = "template";
-        this.template = {
-            name: template,
-            language: {
+        const components = [];
+        if (bodyParameters && bodyParameters.length > 0) {
+            components.push({
+                type: "body",
+                parameters: bodyParameters.map(param => ({
+                    type: param.type,
+                    text: param.text
+                }))
+            });
+        }
+        this.template = Object.assign({ name: template, language: {
                 code: language,
-            },
-        };
+            } }, (components.length > 0 && { components }));
     }
 }
 exports.TextTemplate = TextTemplate;

package/dist/useCases/message/whatsappResponse.d.ts

@@ -60,5 +60,21 @@ export declare class WhatsappResponse {
     download_media(url: string, mimetype: string): Promise<any>;
     get_media_url(media_id: string): Promise<any>;
     update_long_lived_token(client_id: string, client_secret: string, fb_exchange_token: string): Promise<string | undefined>;
-    send_template_text_message(template: string, language: string): Promise<ISendMessageReturn | null>;
+    send_template_text_message(template: string, language: string, bodyParameters?: Array<{
+        type: string;
+        text: string;
+    }>): Promise<ISendMessageReturn | null>;
+    send_template_media_message(template: string, language: string, options: {
+        header?: {
+            type: "image" | "video" | "document";
+            media: {
+                link: string;
+                filename?: string;
+            };
+        };
+        bodyParameters?: Array<{
+            type: string;
+            text: string;
+        }>;
+    }): Promise<ISendMessageReturn | null>;
 }

package/dist/useCases/message/whatsappResponse.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.WhatsappResponse = void 0;
 const axios_1 = __importDefault(require("axios"));
 const elements_1 = require("../../elements");
+const mediaTemplate_1 = require("../../elements/mediaTemplate");
 const text_1 = require("../../elements/text");
 const services_1 = require("../../services");
 const parseError_1 = require("../../utils/parseError");
@@ -400,7 +401,7 @@ class WhatsappResponse {
             return undefined;
         }
     }
-    async send_template_text_message(template, language) {
+    async send_template_text_message(template, language, bodyParameters) {
         try {
             if (!this.apiCall)
                 await this.getApiInstanceToken();
@@ -408,11 +409,31 @@ class WhatsappResponse {
                 to: this.clientNumber,
                 template: template,
                 language: language,
+                bodyParameters: bodyParameters,
             }));
         }
         catch (err) {
             return (0, parseError_1.throwParsedError)(err, "Não foi possível criar mensagem de texto");
         }
     }
+    async send_template_media_message(template, language, options) {
+        try {
+            if (!this.apiCall)
+                await this.getApiInstanceToken();
+            if (options.header && !options.header.media.link) {
+                throw new Error("É necessário fornecer 'link' para a mídia do template");
+            }
+            return await this.apiCall.post("/messages", new mediaTemplate_1.MediaTemplate({
+                to: this.clientNumber,
+                template: template,
+                language: language,
+                header: options.header,
+                bodyParameters: options.bodyParameters,
+            }));
+        }
+        catch (err) {
+            return (0, parseError_1.throwParsedError)(err, "Não foi possível criar template com mídia");
+        }
+    }
 }
 exports.WhatsappResponse = WhatsappResponse;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@natyapp/meta",
-  "version": "1.6.6",
+  "version": "1.6.7",
   "description": "",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",