@green-api/greenapi-integration 0.1.0 → 0.3.0

package/dist/types/types.d.ts

@@ -1,77 +1,231 @@
-export interface BaseInstance {
+/**
+ * Base interface for GREEN-API WhatsApp instances.
+ * Contains the essential credentials needed to interact with the API.
+ */
+interface BaseInstance {
     idInstance: number | bigint;
     apiTokenInstance: string;
-    settings?: any;
+    stateInstance?: InstanceState;
+    settings?: Settings | Record<string, any>;
 }
+/**
+ * Extended instance interface that allows for additional platform-specific properties.
+ * Use this when you need to store extra data with your instance.
+ */
 export interface Instance extends BaseInstance {
     [key: string]: any;
 }
-export type Message = SendMessage | SendFileByUpload | SendFileByUrl | SendPoll | SendLocation | SendContact | ForwardMessages;
-export interface BaseMessage {
-    type: SendMessageType;
-    chatId: string;
-    quotedMessageId?: string;
-}
-export type SendMessageType = "text" | "upload-file" | "url-file" | "poll" | "location" | "contact" | "forward";
-export interface SendMessage extends BaseMessage {
+/**
+ * Union type representing all possible message formats that can be sent through GREEN-API.
+ * Each message type has its own specific structure and required fields.
+ */
+export type Message = ({
     type: "text";
     message: string;
-}
-export interface ForwardMessages {
-    type: "forward";
-    chatId: string;
-    chatIdFrom: string;
-    messages: string[];
-}
-export interface ForwardMessagesResponse {
-    messages: string[];
-}
-export interface Contact {
-    phoneContact: number;
-    firstName?: string;
-    middleName?: string;
-    lastName?: string;
-    company?: string;
-}
-export interface SendContact extends BaseMessage {
-    type: "contact";
-    contact: Contact;
-}
-export interface SendFileByUpload extends BaseMessage {
+} & BaseMessage) | ({
     type: "upload-file";
     caption?: string;
     file: {
         data: Blob | File;
         fileName: string;
     };
-}
-export interface SendFileByUrl extends BaseMessage {
+} & BaseMessage) | ({
     type: "url-file";
     caption?: string;
     file: {
         url: string;
         fileName: string;
     };
-}
-export interface SendLocation extends BaseMessage {
+} & BaseMessage) | ({
+    type: "poll";
+    message: string;
+    options: PollOption[];
+    multipleAnswers?: boolean;
+} & BaseMessage) | ({
     type: "location";
     nameLocation?: string;
     address?: string;
     latitude: number;
     longitude: number;
+} & BaseMessage) | ({
+    type: "contact";
+    contact: {
+        phoneContact: number;
+        firstName?: string;
+        middleName?: string;
+        lastName?: string;
+        company?: string;
+    };
+} & BaseMessage) | {
+    type: "forward";
+    chatId: string;
+    chatIdFrom: string;
+    messages: string[];
+};
+/**
+ * Common properties shared by all message types.
+ */
+export interface BaseMessage {
+    chatId: string;
+    quotedMessageId?: string;
+}
+export type SendMessageType = "text" | "upload-file" | "url-file" | "poll" | "location" | "contact" | "forward";
+export interface ForwardMessagesResponse {
+    messages: string[];
 }
 export interface PollOption {
     optionName: string;
 }
-export interface SendPoll extends BaseMessage {
+export type SendMessage = Extract<Message, {
+    type: "text";
+}>;
+export type SendFileByUpload = Extract<Message, {
+    type: "upload-file";
+}>;
+export type SendFileByUrl = Extract<Message, {
+    type: "url-file";
+}>;
+export type SendLocation = Extract<Message, {
+    type: "location";
+}>;
+export type SendContact = Extract<Message, {
+    type: "contact";
+}>;
+export type SendPoll = Extract<Message, {
     type: "poll";
-    message: string;
+}>;
+export type ForwardMessages = Extract<Message, {
+    type: "forward";
+}>;
+export type MessageType = "textMessage" | "extendedTextMessage" | "imageMessage" | "videoMessage" | "documentMessage" | "audioMessage" | "contactMessage" | "locationMessage" | "pollMessage";
+export interface ForwardableMessage {
+    forwardingScore: number;
+    isForwarded: boolean;
+}
+export interface MediaMessage extends ForwardableMessage {
+    jpegThumbnail: string;
+}
+export interface TextMessageData {
+    textMessage: string;
+}
+export interface ExtendedTextMessageData extends MediaMessage {
+    text: string;
+    description: string;
+    title: string;
+}
+export interface FileMessageData extends MediaMessage {
+    downloadUrl: string;
+    caption: string;
+    mimeType: string;
+    fileName: string;
+}
+export interface LocationMessageData extends MediaMessage {
+    nameLocation: string;
+    address: string;
+    latitude: number;
+    longitude: number;
+}
+export interface ContactMessageData extends ForwardableMessage {
+    displayName: string;
+    vcard: string;
+}
+export interface PollMessageData {
+    name: string;
     options: PollOption[];
-    multipleAnswers?: boolean;
+    multipleAnswers: boolean;
+}
+type QuotedMessage = {
+    stanzaId: string;
+    participant: string;
+    typeMessage: MessageType;
+} & ({
+    typeMessage: "textMessage";
+    textMessage: string;
+} | {
+    typeMessage: "contactMessage";
+    contact: {
+        displayName: string;
+        vcard: string;
+    };
+} | {
+    typeMessage: "locationMessage";
+    location: {
+        nameLocation: string;
+        address: string;
+        jpegThumbnail: string;
+        latitude: number;
+        longitude: number;
+    };
+} | {
+    typeMessage: "imageMessage" | "videoMessage" | "documentMessage" | "audioMessage";
+    downloadUrl: string;
+    caption: string;
+    jpegThumbnail: string;
+});
+export interface PollVote {
+    optionName: string;
+    optionVoters: string[];
+}
+export interface PollUpdateMessageData {
+    stanzaId: string;
+    name: string;
+    votes: PollVote[];
+    multipleAnswers: boolean;
+}
+export type OutgoingMessageStatus = "sent" | "delivered" | "read" | "failed" | "noAccount" | "notInGroup" | "yellowCard";
+export type WebhookType = "stateInstanceChanged" | "outgoingMessageStatus" | "outgoingAPIMessageReceived" | "outgoingMessageReceived" | "incomingMessageReceived";
+/**
+ * Webhook payload received when a message status changes.
+ * Used to track delivery and read receipts.
+ */
+export interface OutgoingMessageStatusWebhook {
+    typeWebhook: "outgoingMessageStatus";
+    chatId: string;
+    instanceData: {
+        idInstance: number;
+        wid: string;
+        typeInstance: string;
+    };
+    timestamp: number;
+    idMessage: string;
+    status: OutgoingMessageStatus;
+    description?: string;
+    sendByApi: boolean;
+}
+export interface StateInstanceWebhook {
+    typeWebhook: "stateInstanceChanged";
+    instanceData: {
+        idInstance: number;
+        wid: string;
+        typeInstance: string;
+    };
+    timestamp: number;
+    stateInstance: InstanceState;
 }
-export type MessageType = "textMessage" | "extendedTextMessage" | "imageMessage" | "videoMessage" | "documentMessage" | "audioMessage";
-export interface IncomingGreenApiWebhook {
-    typeWebhook: string;
+export type WebhookMessageData = {
+    typeMessage: "textMessage";
+    textMessageData: TextMessageData;
+} | {
+    typeMessage: "extendedTextMessage";
+    extendedTextMessageData: ExtendedTextMessageData;
+} | {
+    typeMessage: "imageMessage" | "videoMessage" | "documentMessage" | "audioMessage";
+    fileMessageData: FileMessageData;
+} | {
+    typeMessage: "locationMessage";
+    locationMessageData: LocationMessageData;
+} | {
+    typeMessage: "contactMessage";
+    contactMessageData: ContactMessageData;
+} | {
+    typeMessage: "pollMessage";
+    pollMessageData: PollMessageData;
+} | {
+    typeMessage: "pollUpdateMessage";
+    pollMessageData: PollUpdateMessageData;
+};
+export interface MessageWebhook {
+    typeWebhook: "incomingMessageReceived" | "outgoingMessageReceived" | "outgoingAPIMessageReceived";
     instanceData: {
         idInstance: number;
         wid: string;
@@ -82,34 +236,22 @@ export interface IncomingGreenApiWebhook {
     senderData: {
         chatId: string;
         sender: string;
-        chatName?: string;
-        senderName?: string;
+        chatName: string;
+        senderName: string;
         senderContactName?: string;
     };
-    messageData: {
-        typeMessage: MessageType;
-        textMessageData?: {
-            textMessage: string;
-        };
-        extendedTextMessageData?: {
-            text: string;
-            description?: string;
-            title?: string;
-            jpegThumbnail?: string;
-            forwardingScore?: number;
-            isForwarded?: boolean;
-        };
-        fileMessageData?: {
-            downloadUrl: string;
-            caption?: string;
-            jpegThumbnail?: string;
-            mimeType: string;
-            forwardingScore?: number;
-            isForwarded?: boolean;
-            fileName: string;
-        };
+    messageData: WebhookMessageData & {
+        quotedMessage?: QuotedMessage;
     };
 }
+/**
+ * Primary webhook types received from GREEN-API.
+ */
+export type GreenApiWebhook = MessageWebhook | OutgoingMessageStatusWebhook | StateInstanceWebhook;
+/**
+ * Configuration settings for a GREEN-API instance.
+ * Controls webhook behavior, message handling, and other instance features.
+ */
 export interface Settings {
     wid?: string;
     webhookUrl?: string;
@@ -132,6 +274,9 @@ export interface Reboot {
 export interface Logout {
     isLogout: boolean;
 }
+/**
+ * Represents an instance state in the GREEN-API system.
+ */
 export type InstanceState = "notAuthorized" | "authorized" | "blocked" | "starting" | "yellowCard";
 export interface StateInstance {
     stateInstance: InstanceState;
@@ -176,3 +321,4 @@ export interface BaseUser {
     id: number | bigint;
     [key: string]: any;
 }
+export {};

package/dist/utils/helpers.d.ts

@@ -1,2 +1,73 @@
-export declare function formatPhoneNumber(phone: string): string;
+import { Settings } from "../types/types";
+/**
+ * Utility functions for working with phone numbers, tokens, and vCards.
+ *
+ * @category Utilities
+ */
+/**
+ * Formats a phone number into GREEN-API's expected format.
+ * Removes all non-digit characters and adds @c.us or @g.us suffix.
+ *
+ * @param phone - The phone number to format
+ * @param chatType - The type of a chat, can be either "group" or "private"
+ * @returns Formatted phone number with @c.us suffix
+ *
+ * @example
+ * formatPhoneNumber('+1 (234) 567-8900')  // Returns '12345678900@c.us'
+ * formatPhoneNumber('1234567890')          // Returns '1234567890@c.us'
+ */
+export declare function formatPhoneNumber(phone: string, chatType?: "group" | "private"): string;
+/**
+ * Generates a cryptographically secure random token.
+ *
+ * @param length - Length of the token in bytes (default: 32)
+ * @returns Hexadecimal string of the specified length
+ *
+ * @example
+ * generateRandomToken()     // Returns a 64-character hex string (32 bytes)
+ * generateRandomToken(16)   // Returns a 32-character hex string (16 bytes)
+ */
 export declare function generateRandomToken(length?: number): string;
+/**
+ * Extracts a phone number from a vCard string format.
+ * Supports various vCard formats and phone number notations.
+ *
+ * @param vcard - The vCard string containing contact information
+ * @returns The extracted phone number or null if not found
+ *
+ * @example
+ * const vcard = `BEGIN:VCARD\nTEL:+1234567890\nEND:VCARD`;
+ * extractPhoneNumberFromVCard(vcard)  // Returns '+1234567890'
+ */
+export declare function extractPhoneNumberFromVCard(vcard: string): string | null;
+/**
+ * Validates if a value is appropriate for a specific Settings interface key.
+ * Checks type compatibility for numbers, strings, and yes/no enums.
+ *
+ * @param key - The settings key to validate
+ * @param value - The value to check against the key's expected type
+ * @returns Boolean indicating if the value is valid for the given key
+ *
+ * @example
+ * isValidSettingValue('delaySendMessagesMilliseconds', 1000)     // Returns true
+ * isValidSettingValue('outgoingWebhook', 'maybe')                // Returns false
+ * isValidSettingValue('webhookUrl', 'https://example.com')       // Returns true
+ */
+export declare function isValidSettingValue(key: keyof Settings, value: any): boolean;
+/**
+ * Validates and cleans a settings object against the Settings interface.
+ * Removes any properties that don't match the interface or have invalid values.
+ *
+ * @param settings - The settings object to validate and clean
+ * @returns A new Settings object containing only valid properties and values
+ *
+ * @example
+ * const input = {
+ *   webhookUrl: 'https://example.com',
+ *   outgoingWebhook: 'yes',
+ *   invalidKey: 'value',
+ *   delaySendMessagesMilliseconds: 'invalid'
+ * };
+ * validateAndCleanSettings(input)  // Returns { webhookUrl: 'https://example.com', outgoingWebhook: 'yes' }
+ */
+export declare function validateAndCleanSettings(settings: any): Settings;

package/dist/utils/helpers.js

@@ -35,11 +35,118 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.formatPhoneNumber = formatPhoneNumber;
 exports.generateRandomToken = generateRandomToken;
+exports.extractPhoneNumberFromVCard = extractPhoneNumberFromVCard;
+exports.isValidSettingValue = isValidSettingValue;
+exports.validateAndCleanSettings = validateAndCleanSettings;
 const crypto = __importStar(require("crypto"));
-function formatPhoneNumber(phone) {
+/**
+ * Utility functions for working with phone numbers, tokens, and vCards.
+ *
+ * @category Utilities
+ */
+/**
+ * Formats a phone number into GREEN-API's expected format.
+ * Removes all non-digit characters and adds @c.us or @g.us suffix.
+ *
+ * @param phone - The phone number to format
+ * @param chatType - The type of a chat, can be either "group" or "private"
+ * @returns Formatted phone number with @c.us suffix
+ *
+ * @example
+ * formatPhoneNumber('+1 (234) 567-8900')  // Returns '12345678900@c.us'
+ * formatPhoneNumber('1234567890')          // Returns '1234567890@c.us'
+ */
+function formatPhoneNumber(phone, chatType = "private") {
     const cleaned = phone.replace(/\D/g, "");
-    return `${cleaned}@c.us`;
+    return chatType === "private" ? `${cleaned}@c.us` : `${cleaned}@g.us`;
 }
+/**
+ * Generates a cryptographically secure random token.
+ *
+ * @param length - Length of the token in bytes (default: 32)
+ * @returns Hexadecimal string of the specified length
+ *
+ * @example
+ * generateRandomToken()     // Returns a 64-character hex string (32 bytes)
+ * generateRandomToken(16)   // Returns a 32-character hex string (16 bytes)
+ */
 function generateRandomToken(length = 32) {
     return crypto.randomBytes(length).toString("hex");
 }
+/**
+ * Extracts a phone number from a vCard string format.
+ * Supports various vCard formats and phone number notations.
+ *
+ * @param vcard - The vCard string containing contact information
+ * @returns The extracted phone number or null if not found
+ *
+ * @example
+ * const vcard = `BEGIN:VCARD\nTEL:+1234567890\nEND:VCARD`;
+ * extractPhoneNumberFromVCard(vcard)  // Returns '+1234567890'
+ */
+function extractPhoneNumberFromVCard(vcard) {
+    const phoneMatch = vcard.match(/TEL(?:;[^:]+)?:([+\d\s-]+)/);
+    return phoneMatch ? phoneMatch[1] : null;
+}
+/**
+ * Validates if a value is appropriate for a specific Settings interface key.
+ * Checks type compatibility for numbers, strings, and yes/no enums.
+ *
+ * @param key - The settings key to validate
+ * @param value - The value to check against the key's expected type
+ * @returns Boolean indicating if the value is valid for the given key
+ *
+ * @example
+ * isValidSettingValue('delaySendMessagesMilliseconds', 1000)     // Returns true
+ * isValidSettingValue('outgoingWebhook', 'maybe')                // Returns false
+ * isValidSettingValue('webhookUrl', 'https://example.com')       // Returns true
+ */
+function isValidSettingValue(key, value) {
+    switch (key) {
+        case "delaySendMessagesMilliseconds":
+            return typeof value === "number";
+        case "wid":
+        case "webhookUrl":
+        case "webhookUrlToken":
+            return typeof value === "string";
+        case "markIncomingMessagesReaded":
+        case "markIncomingMessagesReadedOnReply":
+        case "outgoingWebhook":
+        case "outgoingMessageWebhook":
+        case "outgoingAPIMessageWebhook":
+        case "stateWebhook":
+        case "incomingWebhook":
+        case "keepOnlineStatus":
+        case "pollMessageWebhook":
+        case "incomingCallWebhook":
+            return value === "yes" || value === "no";
+        default:
+            return false;
+    }
+}
+/**
+ * Validates and cleans a settings object against the Settings interface.
+ * Removes any properties that don't match the interface or have invalid values.
+ *
+ * @param settings - The settings object to validate and clean
+ * @returns A new Settings object containing only valid properties and values
+ *
+ * @example
+ * const input = {
+ *   webhookUrl: 'https://example.com',
+ *   outgoingWebhook: 'yes',
+ *   invalidKey: 'value',
+ *   delaySendMessagesMilliseconds: 'invalid'
+ * };
+ * validateAndCleanSettings(input)  // Returns { webhookUrl: 'https://example.com', outgoingWebhook: 'yes' }
+ */
+function validateAndCleanSettings(settings) {
+    const validSettings = {};
+    const settingsKeys = Object.keys(settings);
+    for (const key of settingsKeys) {
+        if (key in validSettings && isValidSettingValue(key, settings[key])) {
+            validSettings[key] = settings[key];
+        }
+    }
+    return validSettings;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@green-api/greenapi-integration",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "GREEN-API Integration library",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -11,7 +11,9 @@
     "build": "tsc",
     "clean": "rimraf dist",
     "prebuild": "npm run clean",
-    "prepare": "npm run build"
+    "prepare": "npm run build",
+    "docs": "typedoc",
+    "docs:watch": "typedoc --watch"
   },
   "keywords": [
     "green-api",
@@ -29,6 +31,8 @@
     "rimraf": "^6.0.1",
     "ts-jest": "^29.2.5",
     "ts-node": "^10.9.2",
+    "typedoc": "^0.27.6",
+    "typedoc-plugin-markdown": "^4.4.1",
     "typescript": "^5.7.2"
   },
   "dependencies": {