n8n-nodes-viber-bot 1.0.0

package/README.md

@@ -0,0 +1,165 @@
+# n8n-nodes-viber-bot
+
+This is an n8n community node that allows you to seamlessly integrate the **Viber Bot REST API** with your workflows. It provides native support for messaging, broadcasting, registration of webhooks, and retrieval of account and subscriber details.
+
+---
+
+## Features
+
+### 1. Message Management
+*   **Send Message:** Dispatch individual messages to subscribed Viber users.
+*   **Broadcast Message:** Send the same message to up to 300 subscriber IDs simultaneously in a single request.
+*   **Message Types Supported:**
+    *   **Text:** Simple text messages up to 7,000 characters.
+    *   **Picture:** High-quality image URL (HTTPS only), optional text caption, and custom thumbnail override.
+    *   **Video:** Video URL (HTTPS), file size in bytes, and optional duration constraint.
+    *   **File:** Any document or media file URL (HTTPS), file size in bytes, and explicit file name.
+    *   **Location:** Geographical coordinates (latitude and longitude).
+    *   **Contact:** Direct contact details (name and phone number).
+    *   **Sticker:** Native Viber sticker ID.
+    *   **URL:** Clickable link URL.
+*   **Advanced Message Parameters:** Include custom tracking data (`trackingData`) and display profile overrides (`senderName` and `senderAvatar`).
+
+### 2. Webhook Settings
+*   **Set Webhook:** Register an HTTPS callback URL to receive real-time Viber events.
+*   **Granular Events:** Subscribe to any combination of `conversation_started`, `delivered`, `seen`, `failed`, `subscribed`, and `unsubscribed`.
+*   **Privacy Parameters:** Toggle whether the sender's name (`sendName`) and photo (`sendPhoto`) are delivered in callback payloads.
+
+### 3. Account Profile
+*   **Get Account Info:** Instantly fetch details of your Viber Bot account, including subscriber count, active webhook status, and bot name/uri.
+
+### 4. Subscriber Management
+*   **Get User Details:** Retrieve private profile metadata for a specific user (name, primary device OS, device type, language, and country code).
+
+---
+
+## Directory Layout
+
+```text
+n8n-nodes-viber-bot/
+├── credentials/
+│   ├── ViberBotApi.credentials.ts        # Viber API Authentication definition
+│   └── viber.svg                         # Polished logo for credentials modal
+├── nodes/
+│   └── ViberBot/
+│       ├── ViberBot.node.ts              # Custom Node definition & parameter mapping
+│       └── viber.svg                     # Polished logo for n8n workspace canvas
+├── tests/
+│   ├── mocks/
+│   │   └── mockExecuteFunctions.ts       # n8n runtime execution mock helper
+│   └── ViberBot.node.test.ts             # Extensive Jest unit tests
+├── package.json                          # Package scripts & n8n entry configurations
+├── tsconfig.json                         # TypeScript compilation settings
+├── eslint.config.mjs                     # ESLint configuration file
+├── jest.config.js                        # Jest environment configurations
+└── README.md                             # Documentation index
+```
+
+---
+
+## Local Installation (For Testing)
+
+To load and test this node in a local n8n instance before releasing it:
+
+1.  **Build the Package:**
+    Compile the TypeScript source files and copy visual assets to the `dist/` build directory:
+    ```bash
+    npm run build
+    ```
+
+2.  **Link Your Local Package:**
+    Create a global symlink for your workspace folder:
+    ```bash
+    npm link
+    ```
+
+3.  **Link into Your n8n Folder:**
+    Navigate to your local n8n configurations directory (typically `~/.n8n/`) and link the package:
+    ```bash
+    cd ~/.n8n
+    npm link n8n-nodes-viber-bot
+    ```
+
+4.  **Restart n8n:**
+    Launch your local n8n process. The workspace canvas will load the custom "Viber Bot" node automatically.
+
+---
+
+## Credentials Configuration
+
+1.  Create a **Viber Bot** account through the [Viber Admin Panel](https://partners.viber.com/).
+2.  Retrieve your unique **App Key (Auth Token)**.
+3.  In n8n, add a new **Viber Bot API** credential and paste your App Key into the **Auth Token** field.
+4.  Click **Test connection** to verify the credential validity (calls Viber's account endpoint in the background).
+
+---
+
+## Operations Guide
+
+### **Resource: Message**
+
+#### **Operation: Send**
+*   **Receiver:** The unique Viber subscriber ID (string, required).
+*   **Message Type:** Select between `Contact`, `File`, `Location`, `Picture`, `Sticker`, `Text`, `URL`, and `Video`.
+*   **Additional Fields:**
+    *   *Sender Name:* Custom profile name shown in chat (max 28 characters).
+    *   *Sender Avatar:* Custom profile photo URL (must be HTTPS, JPEG/PNG).
+    *   *Tracking Data:* Custom metadata returned inside user callback reactions (max 4,096 characters).
+
+#### **Operation: Broadcast**
+*   **Broadcast List:** A comma-separated list of user IDs or a raw JSON array of user ID strings (e.g., `["user1", "user2"]`). Maximum of 300 IDs per request.
+
+---
+
+### **Resource: Webhook**
+
+#### **Operation: Set**
+*   **URL:** The webhook endpoint to receive notifications (must be HTTPS, required).
+*   **Event Types:** Select which events trigger callbacks. Defaults to all standard viber events.
+
+---
+
+### **Resource: Account**
+
+#### **Operation: Get**
+*   Fetches public information about the bot account. No parameters are required.
+
+---
+
+### **Resource: User**
+
+#### **Operation: Get**
+*   **User ID:** The unique Viber subscriber ID to fetch metadata for (string, required).
+
+---
+
+## Development & Maintenance Scripts
+
+Inside your workspace root, you can invoke the following CLI commands:
+
+*   **Build Compilation:**
+    ```bash
+    npm run build
+    ```
+*   **TypeScript Watcher:**
+    ```bash
+    npm run build:watch
+    ```
+*   **Style & Best Practices Linter:**
+    ```bash
+    npm run lint
+    ```
+*   **Code Formatter (Lint Fix):**
+    ```bash
+    npm run lint:fix
+    ```
+*   **Execute Test Suite:**
+    ```bash
+    npm run test
+    ```
+
+---
+
+## License
+
+This project is licensed under the [MIT License](LICENSE).

package/dist/credentials/ViberBotApi.credentials.d.ts

@@ -0,0 +1,10 @@
+import type { IAuthenticateGeneric, ICredentialTestRequest, ICredentialType, Icon, INodeProperties } from 'n8n-workflow';
+export declare class ViberBotApi implements ICredentialType {
+    name: string;
+    displayName: string;
+    icon: Icon;
+    documentationUrl: string;
+    properties: INodeProperties[];
+    authenticate: IAuthenticateGeneric;
+    test: ICredentialTestRequest;
+}

package/dist/credentials/ViberBotApi.credentials.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ViberBotApi = void 0;
+class ViberBotApi {
+    constructor() {
+        this.name = 'viberBotApi';
+        this.displayName = 'Viber Bot API';
+        this.icon = 'file:viber.svg';
+        this.documentationUrl = 'https://developers.viber.com/docs/api/rest-bot-api/#authentication';
+        this.properties = [
+            {
+                displayName: 'Auth Token',
+                name: 'authToken',
+                type: 'string',
+                typeOptions: {
+                    password: true,
+                },
+                default: '',
+                required: true,
+                description: 'The authentication token for your Viber Bot',
+            },
+        ];
+        this.authenticate = {
+            type: 'generic',
+            properties: {
+                headers: {
+                    'X-Viber-Auth-Token': '={{$credentials.authToken}}',
+                },
+            },
+        };
+        this.test = {
+            request: {
+                baseURL: 'https://chatapi.viber.com/pa',
+                url: '/get_account_info',
+                method: 'POST',
+                body: {},
+            },
+        };
+    }
+}
+exports.ViberBotApi = ViberBotApi;
+//# sourceMappingURL=ViberBotApi.credentials.js.map

package/dist/credentials/ViberBotApi.credentials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ViberBotApi.credentials.js","sourceRoot":"","sources":["../../credentials/ViberBotApi.credentials.ts"],"names":[],"mappings":";;;AAQA,MAAa,WAAW;IAAxB;QACC,SAAI,GAAG,aAAa,CAAC;QACrB,gBAAW,GAAG,eAAe,CAAC;QAC9B,SAAI,GAAS,gBAAgB,CAAC;QAC9B,qBAAgB,GAAG,oEAAoE,CAAC;QAExF,eAAU,GAAsB;YAC/B;gBACC,WAAW,EAAE,YAAY;gBACzB,IAAI,EAAE,WAAW;gBACjB,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE;oBACZ,QAAQ,EAAE,IAAI;iBACd;gBACD,OAAO,EAAE,EAAE;gBACX,QAAQ,EAAE,IAAI;gBACd,WAAW,EAAE,6CAA6C;aAC1D;SACD,CAAC;QAEF,iBAAY,GAAyB;YACpC,IAAI,EAAE,SAAS;YACf,UAAU,EAAE;gBACX,OAAO,EAAE;oBACR,oBAAoB,EAAE,6BAA6B;iBACnD;aACD;SACD,CAAC;QAEF,SAAI,GAA2B;YAC9B,OAAO,EAAE;gBACR,OAAO,EAAE,8BAA8B;gBACvC,GAAG,EAAE,mBAAmB;gBACxB,MAAM,EAAE,MAAM;gBACd,IAAI,EAAE,EAAE;aACR;SACD,CAAC;IACH,CAAC;CAAA;AArCD,kCAqCC"}

package/dist/credentials/viber.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="24" height="24">
+  <rect width="512" height="512" rx="120" fill="#7360F2"/>
+  <path d="M374.2 301.9c-11.8-4-34.9-16-40.8-18.1-5.9-2.1-10.2-3.2-14.5 3.2-4.3 6.4-16.6 20.8-20.4 25.1-3.7 4.3-7.5 4.8-19.3.8-11.8-4-49.8-18.4-94.9-58.6-35.1-31.3-58.8-70-65.7-81.8-6.9-11.8-.7-18.1 5.2-24 5.4-5.3 11.8-13.8 17.7-20.8 5.9-6.9 7.9-11.8 11.8-19.7 4-7.9 2-14.9-1-21.3-3-6.4-26.2-63.2-35.9-86.6-9.5-22.7-19.1-19.6-26.2-19.6-6.7 0-14.4-.8-22 1-7.7 1.8-20.2 6.6-28.7 15.9s-32.5 31.8-32.5 77.6c0 45.8 33.3 90 38 96.4 4.6 6.4 65.5 100.1 158.7 140.4 22.1 9.6 39.4 15.3 52.8 19.6 22.3 7.1 42.6 6.1 58.6 3.7 17.9-2.7 36.8-15 42-29.4 5.2-14.4 5.2-26.8 3.7-29.4-1.5-2.6-5.4-4.2-17.2-10.2z" fill="#FFF" transform="translate(48, 48) scale(0.8)"/>
+</svg>

package/dist/nodes/ViberBot/ViberBot.node.d.ts

@@ -0,0 +1,5 @@
+import { IExecuteFunctions, INodeExecutionData, INodeType, INodeTypeDescription } from 'n8n-workflow';
+export declare class ViberBot implements INodeType {
+    description: INodeTypeDescription;
+    execute(this: IExecuteFunctions): Promise<INodeExecutionData[][]>;
+}