@wabot-dev/framework 0.5.7 → 0.5.9

package/dist/src/node_modules/wasenderapi/dist/index.js

@@ -0,0 +1,553 @@
+// src/errors.ts
+var WasenderAPIError = class _WasenderAPIError extends Error {
+  constructor(apiMessage, statusCode, errorDetails, retryAfter, rateLimit) {
+    super(`Wasender API Error (Status ${statusCode || "N/A"}): ${apiMessage}`);
+    this.success = false;
+    this.name = "WasenderAPIError";
+    this.apiMessage = apiMessage;
+    this.statusCode = statusCode;
+    this.errorDetails = errorDetails;
+    this.retryAfter = retryAfter;
+    this.rateLimit = rateLimit;
+    Object.setPrototypeOf(this, _WasenderAPIError.prototype);
+  }
+};
+
+// src/webhook.ts
+var WEBHOOK_SIGNATURE_HEADER = "x-webhook-signature";
+function verifyWasenderWebhookSignature(requestSignature, configuredSecret) {
+  if (!requestSignature || !configuredSecret) {
+    return false;
+  }
+  return requestSignature === configuredSecret;
+}
+
+// src/main.ts
+var SDK_VERSION = "0.1.0";
+var Wasender = class {
+  constructor(apiKey, personalAccessToken, baseUrl = "https://www.wasenderapi.com/api", fetchImplementation, retryOptions, webhookSecret) {
+    if (apiKey === void 0 && personalAccessToken === void 0) {
+      throw new Error("Either an API Key (for session operations) or a Personal Access Token (for session management) must be provided to initialize the Wasender SDK.");
+    }
+    this.apiKey = apiKey;
+    this.personalAccessToken = personalAccessToken;
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+    this.fetchImpl = fetchImplementation || globalThis.fetch;
+    this.retryConfig = {
+      enabled: retryOptions?.enabled ?? false,
+      maxRetries: retryOptions?.maxRetries ?? 0
+    };
+    this.configuredWebhookSecret = webhookSecret;
+    if (!this.fetchImpl) {
+      throw new Error("Fetch implementation is not available. Please provide one (e.g., for Node.js < 18 by polyfilling globalThis.fetch or passing a custom fetch).");
+    }
+  }
+  parseRateLimitHeaders(headers) {
+    const limit = headers.get("X-RateLimit-Limit");
+    const remaining = headers.get("X-RateLimit-Remaining");
+    const reset = headers.get("X-RateLimit-Reset");
+    const resetTimestampNum = reset ? parseInt(reset, 10) : null;
+    return {
+      limit: limit ? parseInt(limit, 10) : null,
+      remaining: remaining ? parseInt(remaining, 10) : null,
+      resetTimestamp: resetTimestampNum,
+      getResetTimestampAsDate: () => resetTimestampNum ? new Date(resetTimestampNum * 1e3) : null
+    };
+  }
+  // General purpose request helper
+  async request(method, path, body) {
+    const url = `${this.baseUrl}${path}`;
+    const isSessionManagementPath = path.startsWith("/whatsapp-sessions") || path === "/status";
+    let tokenToUse;
+    if (isSessionManagementPath) {
+      if (!this.personalAccessToken) {
+        throw new WasenderAPIError("Personal Access Token is required for this operation but was not provided during SDK initialization.", 401);
+      }
+      tokenToUse = this.personalAccessToken;
+    } else {
+      if (!this.apiKey) {
+        throw new WasenderAPIError("Session API Key is required for this operation but was not provided or is not applicable.", 401);
+      }
+      tokenToUse = this.apiKey;
+    }
+    const requestHeaders = {
+      "Authorization": `Bearer ${tokenToUse}`,
+      "Accept": "application/json",
+      "User-Agent": `wasender-typescript-sdk/${SDK_VERSION}`
+    };
+    let processedBody = body ? { ...body } : null;
+    if (processedBody && typeof processedBody === "object" && "messageType" in processedBody && processedBody.messageType === "location") {
+      const locationPayload = processedBody.location;
+      if (locationPayload && typeof locationPayload.latitude === "string") {
+        locationPayload.latitude = parseFloat(locationPayload.latitude);
+      }
+      if (locationPayload && typeof locationPayload.longitude === "string") {
+        locationPayload.longitude = parseFloat(locationPayload.longitude);
+      }
+    }
+    const requestOptions = {
+      method,
+      headers: requestHeaders
+    };
+    if ((method === "POST" || method === "PUT") && processedBody) {
+      requestHeaders["Content-Type"] = "application/json";
+      requestOptions.body = JSON.stringify(processedBody);
+    } else if (method === "POST" || method === "PUT") {
+      requestHeaders["Content-Type"] = "application/json";
+      requestOptions.body = JSON.stringify({});
+    } else ;
+    let attempts = 0;
+    while (true) {
+      attempts++;
+      let httpResponse;
+      let rateLimitInfo;
+      try {
+        httpResponse = await this.fetchImpl(url, requestOptions);
+        rateLimitInfo = this.parseRateLimitHeaders(httpResponse.headers);
+      } catch (networkError) {
+        const errorToThrow = networkError instanceof Error ? new WasenderAPIError(
+          `Network error: ${networkError.message}`,
+          void 0,
+          void 0,
+          void 0,
+          rateLimitInfo
+        ) : new WasenderAPIError(
+          "An unknown network error occurred during the request.",
+          void 0,
+          void 0,
+          void 0,
+          rateLimitInfo
+        );
+        if (attempts > this.retryConfig.maxRetries || !this.retryConfig.enabled) {
+          throw errorToThrow;
+        }
+        if (attempts > 1 && method === "GET") throw errorToThrow;
+        console.warn(
+          `Wasender SDK: Network error on attempt ${attempts} for ${method} ${path}. Retrying if configured...`
+        );
+        await new Promise((resolve) => setTimeout(resolve, 1e3 * attempts));
+        continue;
+      }
+      let responseBody;
+      try {
+        if (httpResponse.status === 204) {
+          if (path.includes("/block") || path.includes("/unblock")) {
+            responseBody = { success: true, data: { message: path.includes("/block") ? "Contact blocked" : "Contact unblocked" } };
+          } else if (method === "DELETE" && path.startsWith("/whatsapp-sessions/")) {
+            responseBody = { success: true, data: null };
+          } else {
+            responseBody = { success: true };
+          }
+        } else {
+          if (path === "/status") {
+            responseBody = await httpResponse.json();
+          } else if (path.includes("/regenerate-key")) {
+            responseBody = await httpResponse.json();
+          } else {
+            responseBody = await httpResponse.json();
+          }
+        }
+      } catch (parseError) {
+        const errorText = await httpResponse.text().catch(() => "Could not retrieve error text.");
+        throw new WasenderAPIError(
+          `Failed to parse API response (Status ${httpResponse.status}): ${errorText}`,
+          httpResponse.status,
+          void 0,
+          void 0,
+          rateLimitInfo
+        );
+      }
+      if (path === "/status" && httpResponse.ok) {
+        return {
+          response: responseBody,
+          rateLimit: rateLimitInfo
+        };
+      }
+      if (path.includes("/regenerate-key") && "api_key" in responseBody && responseBody.success === true) {
+        return {
+          response: responseBody,
+          rateLimit: rateLimitInfo
+        };
+      }
+      if (!httpResponse.ok || responseBody && "success" in responseBody && typeof responseBody.success === "boolean" && !responseBody.success) {
+        const apiError = responseBody;
+        const errorToThrow = new WasenderAPIError(
+          apiError.message || "API request failed with an unspecified error.",
+          httpResponse.status,
+          apiError.errors,
+          apiError.retry_after,
+          rateLimitInfo
+        );
+        if (this.retryConfig.enabled && errorToThrow.statusCode === 429 && errorToThrow.retryAfter && errorToThrow.retryAfter > 0 && attempts <= this.retryConfig.maxRetries) {
+          console.warn(
+            `Wasender SDK: Rate limit (429) on attempt ${attempts} for ${method} ${path}. Retrying after ${errorToThrow.retryAfter}s...`
+          );
+          await new Promise((resolve) => setTimeout(resolve, errorToThrow.retryAfter * 1e3));
+          continue;
+        } else {
+          throw errorToThrow;
+        }
+      }
+      if ("success" in responseBody && responseBody.success === true) {
+        return {
+          response: responseBody,
+          rateLimit: rateLimitInfo
+        };
+      }
+      throw new WasenderAPIError(
+        `Unexpected API response structure from ${method} ${path}. Status: ${httpResponse.status}`,
+        httpResponse.status,
+        void 0,
+        void 0,
+        rateLimitInfo
+      );
+    }
+  }
+  // End of request method
+  // General purpose POST (adapted from original post for sending messages)
+  async postInternal(path, payload) {
+    const apiPayload = payload ? { ...payload } : null;
+    if (apiPayload && "messageType" in apiPayload) {
+      delete apiPayload.messageType;
+    }
+    return this.request("POST", path, apiPayload);
+  }
+  // General purpose GET
+  async getInternal(path) {
+    return this.request("GET", path);
+  }
+  // General purpose PUT
+  async putInternal(path, payload) {
+    return this.request("PUT", path, payload);
+  }
+  // General purpose DELETE
+  async deleteInternal(path) {
+    return this.request("DELETE", path);
+  }
+  // ---------- Generic Send Method (modified to use postInternal) ----------
+  /**
+   * Sends any valid Wasender message payload.
+   * @param payload A WasenderMessagePayload object (e.g., TextOnlyMessage, ImageUrlMessage).
+   * @returns A promise that resolves to the API response and rate limit information.
+   * @throws WasenderAPIError if the request fails.
+   */
+  async send(payload) {
+    const { messageType, ...apiPayload } = payload;
+    return this.postInternal("/send-message", apiPayload);
+  }
+  // ---------- Specific Endpoint Helpers (Wrappers for the generic send) ----------
+  // These now add the `messageType` discriminant before calling the generic send.
+  sendText(payload) {
+    return this.send({ ...payload, messageType: "text" });
+  }
+  sendImage(payload) {
+    return this.send({ ...payload, messageType: "image" });
+  }
+  sendVideo(payload) {
+    return this.send({ ...payload, messageType: "video" });
+  }
+  sendDocument(payload) {
+    return this.send({ ...payload, messageType: "document" });
+  }
+  sendAudio(payload) {
+    return this.send({ ...payload, messageType: "audio" });
+  }
+  sendSticker(payload) {
+    return this.send({ ...payload, messageType: "sticker" });
+  }
+  sendContact(payload) {
+    return this.send({ ...payload, messageType: "contact" });
+  }
+  sendLocation(payload) {
+    return this.send({ ...payload, messageType: "location" });
+  }
+  // ---------- Contact Management Methods ----------
+  /**
+   * Retrieves a list of all contacts synced with the WhatsApp session.
+   * @returns A promise that resolves to the list of contacts and rate limit information.
+   * @throws WasenderAPIError if the request fails.
+   */
+  async getContacts() {
+    return this.getInternal("/contacts");
+  }
+  /**
+   * Retrieves detailed information for a specific contact.
+   * @param contactPhoneNumber The JID (Jabber ID) of the contact in E.164 format (e.g., 1234567890).
+   * @returns A promise that resolves to the contact information and rate limit information.
+   * @throws WasenderAPIError if the request fails.
+   */
+  async getContactInfo(contactPhoneNumber) {
+    if (!contactPhoneNumber) {
+      throw new WasenderAPIError("Contact phone number (JID) is required.", 400);
+    }
+    return this.getInternal(`/contacts/${contactPhoneNumber}`);
+  }
+  /**
+   * Retrieves the URL of the profile picture for a specific contact.
+   * @param contactPhoneNumber The JID (Jabber ID) of the contact in E.164 format (e.g., 1234567890).
+   * @returns A promise that resolves to the profile picture URL and rate limit information.
+   * @throws WasenderAPIError if the request fails.
+   */
+  async getContactProfilePicture(contactPhoneNumber) {
+    if (!contactPhoneNumber) {
+      throw new WasenderAPIError("Contact phone number (JID) is required.", 400);
+    }
+    return this.getInternal(`/contacts/${contactPhoneNumber}/picture`);
+  }
+  /**
+   * Blocks a specific contact.
+   * @param contactPhoneNumber The JID (Jabber ID) of the contact in E.164 format (e.g., 1234567890).
+   * @returns A promise that resolves to the action status and rate limit information.
+   * @throws WasenderAPIError if the request fails.
+   */
+  async blockContact(contactPhoneNumber) {
+    if (!contactPhoneNumber) {
+      throw new WasenderAPIError("Contact phone number (JID) is required.", 400);
+    }
+    return this.postInternal(`/contacts/${contactPhoneNumber}/block`, null);
+  }
+  /**
+   * Unblocks a specific contact.
+   * @param contactPhoneNumber The JID (Jabber ID) of the contact in E.164 format (e.g., 1234567890).
+   * @returns A promise that resolves to the action status and rate limit information.
+   * @throws WasenderAPIError if the request fails.
+   */
+  async unblockContact(contactPhoneNumber) {
+    if (!contactPhoneNumber) {
+      throw new WasenderAPIError("Contact phone number (JID) is required.", 400);
+    }
+    return this.postInternal(`/contacts/${contactPhoneNumber}/unblock`, null);
+  }
+  // ---------- Group Management Methods ----------
+  /**
+   * Retrieves a list of all WhatsApp groups the connected account is a member of.
+   * @returns A promise that resolves to the list of groups and rate limit information.
+   * @throws WasenderAPIError if the request fails.
+   */
+  async getGroups() {
+    return this.getInternal("/groups");
+  }
+  /**
+   * Retrieves metadata for a specific group.
+   * @param groupJid The JID of the group (e.g., '123456789-987654321@g.us').
+   * @returns A promise that resolves to the group metadata and rate limit information.
+   * @throws WasenderAPIError if the request fails.
+   */
+  async getGroupMetadata(groupJid) {
+    if (!groupJid) {
+      throw new WasenderAPIError("Group JID is required.", 400);
+    }
+    return this.getInternal(`/groups/${groupJid}/metadata`);
+  }
+  /**
+   * Retrieves a list of participants for a specific group.
+   * @param groupJid The JID of the group.
+   * @returns A promise that resolves to the list of group participants and rate limit information.
+   * @throws WasenderAPIError if the request fails.
+   */
+  async getGroupParticipants(groupJid) {
+    if (!groupJid) {
+      throw new WasenderAPIError("Group JID is required.", 400);
+    }
+    return this.getInternal(`/groups/${groupJid}/participants`);
+  }
+  /**
+   * Adds participants to a specific group. Requires admin privileges in the group.
+   * @param groupJid The JID of the group.
+   * @param participants An array of participant JIDs (E.164 format phone numbers) to add.
+   * @returns A promise that resolves to the action status for each participant and rate limit information.
+   * @throws WasenderAPIError if the request fails.
+   */
+  async addGroupParticipants(groupJid, participants) {
+    if (!groupJid) {
+      throw new WasenderAPIError("Group JID is required.", 400);
+    }
+    if (!participants || participants.length === 0) {
+      throw new WasenderAPIError("Participants array cannot be null or empty.", 400);
+    }
+    const payload = { participants };
+    return this.postInternal(
+      `/groups/${groupJid}/participants/add`,
+      payload
+    );
+  }
+  /**
+   * Removes participants from a specific group. Requires admin privileges in the group.
+   * @param groupJid The JID of the group.
+   * @param participants An array of participant JIDs (E.164 format phone numbers) to remove.
+   * @returns A promise that resolves to the action status for each participant and rate limit information.
+   * @throws WasenderAPIError if the request fails.
+   */
+  async removeGroupParticipants(groupJid, participants) {
+    if (!groupJid) {
+      throw new WasenderAPIError("Group JID is required.", 400);
+    }
+    if (!participants || participants.length === 0) {
+      throw new WasenderAPIError("Participants array cannot be null or empty.", 400);
+    }
+    const payload = { participants };
+    return this.postInternal(
+      `/groups/${groupJid}/participants/remove`,
+      payload
+    );
+  }
+  /**
+   * Updates settings for a specific group.
+   * @param groupJid The JID of the group.
+   * @param settings An object containing the settings to update (e.g., subject, description, announce, restrict).
+   * @returns A promise that resolves to the updated group settings information and rate limit information.
+   * @throws WasenderAPIError if the request fails.
+   */
+  async updateGroupSettings(groupJid, settings) {
+    if (!groupJid) {
+      throw new WasenderAPIError("Group JID is required.", 400);
+    }
+    if (Object.keys(settings).length === 0) {
+      throw new WasenderAPIError("Settings object cannot be empty.", 400);
+    }
+    return this.putInternal(
+      `/groups/${groupJid}/settings`,
+      settings
+    );
+  }
+  // ---------- Session Management Methods ----------
+  /**
+   * Retrieves a list of all WhatsApp sessions available to the authenticated user.
+   * @returns A promise that resolves to the list of WhatsApp sessions and rate limit information.
+   * @throws WasenderAPIError if the request fails.
+   */
+  async getAllWhatsAppSessions() {
+    return this.getInternal("/whatsapp-sessions");
+  }
+  /**
+   * Creates a new WhatsApp session.
+   * @param payload Details for the new session.
+   * @returns A promise that resolves to the created session information and rate limit information.
+   * @throws WasenderAPIError if the request fails.
+   */
+  async createWhatsAppSession(payload) {
+    return this.postInternal("/whatsapp-sessions", payload);
+  }
+  /**
+   * Retrieves details for a specific WhatsApp session.
+   * @param sessionId ID of the WhatsApp session.
+   * @returns A promise that resolves to the session details and rate limit information.
+   * @throws WasenderAPIError if the request fails.
+   */
+  async getWhatsAppSessionDetails(sessionId) {
+    if (!sessionId) throw new WasenderAPIError("Session ID is required.", 400);
+    return this.getInternal(`/whatsapp-sessions/${sessionId}`);
+  }
+  /**
+   * Updates details for a specific WhatsApp session.
+   * @param sessionId ID of the WhatsApp session.
+   * @param payload Fields to update.
+   * @returns A promise that resolves to the updated session details and rate limit information.
+   * @throws WasenderAPIError if the request fails.
+   */
+  async updateWhatsAppSession(sessionId, payload) {
+    if (!sessionId) throw new WasenderAPIError("Session ID is required.", 400);
+    if (Object.keys(payload).length === 0) throw new WasenderAPIError("Update payload cannot be empty.", 400);
+    return this.putInternal(`/whatsapp-sessions/${sessionId}`, payload);
+  }
+  /**
+   * Deletes a specific WhatsApp session.
+   * @param sessionId ID of the WhatsApp session.
+   * @returns A promise that resolves to the deletion confirmation and rate limit information.
+   * @throws WasenderAPIError if the request fails.
+   */
+  async deleteWhatsAppSession(sessionId) {
+    if (!sessionId) throw new WasenderAPIError("Session ID is required.", 400);
+    return this.deleteInternal(`/whatsapp-sessions/${sessionId}`);
+  }
+  /**
+   * Initiates the connection process for a WhatsApp session.
+   * @param sessionId ID of the WhatsApp session.
+   * @param qrAsImage Optional. If true, requests the QR code as an image in the response.
+   * @returns A promise that resolves to the connection status (e.g., QR code) and rate limit information.
+   * @throws WasenderAPIError if the request fails.
+   */
+  async connectWhatsAppSession(sessionId, qrAsImage) {
+    if (!sessionId) throw new WasenderAPIError("Session ID is required.", 400);
+    const payload = qrAsImage !== void 0 ? { qr_as_image: qrAsImage } : null;
+    return this.postInternal(
+      `/whatsapp-sessions/${sessionId}/connect`,
+      payload
+    );
+  }
+  /**
+   * Retrieves the QR code for connecting a WhatsApp session.
+   * @param sessionId ID of the WhatsApp session.
+   * @returns A promise that resolves to the QR code data and rate limit information.
+   * @throws WasenderAPIError if the request fails.
+   */
+  async getWhatsAppSessionQRCode(sessionId) {
+    if (!sessionId) throw new WasenderAPIError("Session ID is required.", 400);
+    return this.getInternal(`/whatsapp-sessions/${sessionId}/qrcode`);
+  }
+  /**
+   * Disconnects an active WhatsApp session.
+   * @param sessionId ID of the WhatsApp session.
+   * @returns A promise that resolves to the disconnection status and rate limit information.
+   * @throws WasenderAPIError if the request fails.
+   */
+  async disconnectWhatsAppSession(sessionId) {
+    if (!sessionId) throw new WasenderAPIError("Session ID is required.", 400);
+    return this.postInternal(`/whatsapp-sessions/${sessionId}/disconnect`, null);
+  }
+  /**
+   * Regenerates the API key for a specific WhatsApp session.
+   * Note: The response structure for this endpoint is unique.
+   * @param sessionId ID of the WhatsApp session.
+   * @returns A promise that resolves to the new API key and rate limit information.
+   * @throws WasenderAPIError if the request fails.
+   */
+  async regenerateApiKey(sessionId) {
+    if (!sessionId) throw new WasenderAPIError("Session ID is required.", 400);
+    return this.request("POST", `/whatsapp-sessions/${sessionId}/regenerate-key`, {});
+  }
+  /**
+   * Retrieves the current status of the WhatsApp session associated with the API key.
+   * Note: The response structure for this endpoint is unique and does not include a session ID.
+   * @returns A promise that resolves to the session status. Rate limiting may or may not apply as per API docs.
+   * @throws WasenderAPIError if the request fails.
+   */
+  async getSessionStatus() {
+    const result = await this.request("GET", "/status");
+    return result;
+  }
+  // ---------- Webhook Handling ----------
+  /**
+   * Verifies and parses an incoming Wasender webhook event.
+   * @param request An object that adapts your HTTP framework's request, providing methods to get headers and the raw body.
+   * @returns A promise that resolves to the parsed WasenderWebhookEvent.
+   * @throws WasenderAPIError if the webhook secret is not configured in the SDK, if the signature is invalid, or if the body cannot be parsed.
+   */
+  async handleWebhookEvent(request) {
+    if (!this.configuredWebhookSecret) {
+      throw new WasenderAPIError("Webhook secret is not configured in the Wasender SDK instance. Cannot verify signature.");
+    }
+    const signature = request.getHeader(WEBHOOK_SIGNATURE_HEADER);
+    if (!verifyWasenderWebhookSignature(signature, this.configuredWebhookSecret)) {
+      throw new WasenderAPIError("Invalid webhook signature.", 401);
+    }
+    let rawBody;
+    try {
+      const bodyPromiseOrString = request.getRawBody();
+      rawBody = typeof bodyPromiseOrString === "string" ? bodyPromiseOrString : await bodyPromiseOrString;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Unknown error";
+      throw new WasenderAPIError(`Failed to get raw body for webhook: ${message}`);
+    }
+    try {
+      const parsedEvent = JSON.parse(rawBody);
+      return parsedEvent;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Unknown error";
+      throw new WasenderAPIError(`Failed to parse webhook JSON body: ${message}`);
+    }
+  }
+};
+var createWasender = (apiKey, personalAccessToken, baseUrl, fetchImplementation, retryOptions, webhookSecret) => new Wasender(apiKey, personalAccessToken, baseUrl, fetchImplementation, retryOptions, webhookSecret);
+
+export { WEBHOOK_SIGNATURE_HEADER, Wasender, WasenderAPIError, createWasender, verifyWasenderWebhookSignature };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wabot-dev/framework",
-  "version": "0.5.7",
+  "version": "0.5.9",
   "description": "Framework for IA Chat Bots",
   "type": "module",
   "main": "dist/src/index.js",
@@ -65,6 +65,7 @@
     "socket.io-client": "^4.8.1",
     "tslib": "^2.8.1",
     "tsyringe": "^4.9.1",
-    "uuid": "^11.1.0"
+    "uuid": "^11.1.0",
+    "wasenderapi": "^0.1.5"
   }
 }