@gymspace/evolution 1.0.0

package/src/api/service.ts

@@ -0,0 +1,141 @@
+import type { ClientOptions } from "@/schemas/client";
+import type { APIRequestInit } from "@/types/api";
+
+import { EvolutionApiError, extractErrorMessage } from "./errors";
+
+export class ApiService {
+  constructor(private options: ClientOptions) {}
+
+  setInstance(instance: string) {
+    this.options.instance = instance;
+  }
+
+  async request<T = unknown>(
+    path: string,
+    options: APIRequestInit = {}
+  ): Promise<T> {
+    const { isInstanceUrl = true } = options;
+    let instance = this.options.instance;
+
+    // Priority: options.instance > this.options.instance
+    if (options.instance) {
+      instance = options.instance;
+      delete options.instance;
+    }
+
+    if (isInstanceUrl && !instance) {
+      throw new EvolutionApiError("Instance not set", {
+        message:
+          "Please set the instance before making a request or pass instance in the method options.",
+      });
+    }
+
+    const { init, params } = this.makeInit(options);
+
+    const urlPath = isInstanceUrl ? `/${path}/${instance}/` : `/${path}/`;
+    const url = new URL(urlPath, this.options.serverUrl);
+
+    // Add query parameters if any
+    if (params.toString()) {
+      url.search = params.toString();
+    }
+
+    let response: Response;
+    let data: any;
+
+    try {
+      response = await fetch(url, init);
+      data = await response.json();
+    } catch (error) {
+      // Handle network errors or JSON parsing errors
+      throw new EvolutionApiError("Network or parsing error", error);
+    }
+
+    if (!response.ok) {
+      // Extract meaningful error message from the response
+      const errorMessage =
+        extractErrorMessage(data) ||
+        `Request failed with status ${response.status}: ${response.statusText}`;
+
+      throw new EvolutionApiError(
+        errorMessage,
+        {
+          message: errorMessage,
+          response: JSON.stringify(data),
+          url: url.toString(),
+          params: params.toString(),
+          body: JSON.stringify(options.body),
+        } as unknown as Record<string, any>,
+        response.status
+      );
+    }
+
+    return data;
+  }
+
+  private makeInit(options: APIRequestInit): {
+    init: RequestInit;
+    params: URLSearchParams;
+  } {
+    const init: RequestInit = {
+      method: options.method || "GET",
+      headers: {
+        "Content-Type": "application/json",
+        apikey: this.options.token, // Evolution API uses apikey header
+        ...this.options.headers,
+        ...options.headers,
+      },
+    };
+
+    if (options.body) {
+      init.body = JSON.stringify(options.body);
+    }
+
+    const params = new URLSearchParams();
+    if (options.params) {
+      // Convert any object to URLSearchParams
+      Object.entries(options.params).forEach(([key, value]) => {
+        if (value !== undefined && value !== null) {
+          params.append(key, String(value));
+        }
+      });
+    }
+
+    return { init, params };
+  }
+
+  async get<T = unknown>(
+    path: string,
+    options: Omit<APIRequestInit, "method"> = {}
+  ): Promise<T> {
+    return this.request<T>(path, { ...options, method: "GET" });
+  }
+
+  async post<T = unknown>(
+    path: string,
+    options: Omit<APIRequestInit, "method"> = {}
+  ): Promise<T> {
+    return this.request<T>(path, { ...options, method: "POST" });
+  }
+
+  async put<T = unknown>(
+    path: string,
+    options: Omit<APIRequestInit, "method"> = {}
+  ): Promise<T> {
+    return this.request<T>(path, { ...options, method: "PUT" });
+  }
+
+  async patch<T = unknown>(
+    path: string,
+    options: Omit<APIRequestInit, "method"> = {}
+  ): Promise<T> {
+    return this.request<T>(path, { ...options, method: "PATCH" });
+  }
+
+  async delete<T = unknown>(
+    path: string,
+    options: Omit<APIRequestInit, "method"> = {}
+  ): Promise<T> {
+    return this.request<T>(path, { ...options, method: "DELETE" });
+  }
+}

package/src/index.ts

@@ -0,0 +1,89 @@
+export * from "./types/webhooks";
+
+import { ApiService } from "./api/service";
+import {
+  ChatsModule,
+  GroupsModule,
+  InstanceModule,
+  MessagesModule,
+  ProfileModule,
+  SettingsModule,
+  WebhookModule,
+} from "./modules";
+import { type ClientOptions } from "./schemas/client";
+
+export class EvolutionClient {
+  /**
+   * API service for directly interacting with the Evolution API (no specific typings)
+   */
+  public readonly api: ApiService;
+
+  /**
+   * Find and manage chats, send presences and check numbers
+   */
+  public readonly chats: ChatsModule;
+  /**
+   * Find and manage groups
+   */
+  public readonly groups: GroupsModule;
+  /**
+   * Send messages
+   */
+  public readonly messages: MessagesModule;
+  /**
+   * Create and manage instances
+   */
+  public readonly instances: InstanceModule;
+  /**
+   * Manage profile settings
+   */
+  public readonly profile: ProfileModule;
+  /**
+   * Manage webhooks
+   */
+  public readonly webhook: WebhookModule;
+  /**
+   * Manage settings
+   */
+  public readonly settings: SettingsModule;
+
+  /**
+   * Evolution Client - API client for interacting with the Evolution API
+   * @param options - Client options
+   */
+  constructor(public options: ClientOptions) {
+    this.api = new ApiService(options);
+    this.chats = new ChatsModule(this.api);
+    this.groups = new GroupsModule(this.api);
+    this.messages = new MessagesModule(this.api);
+    this.instances = new InstanceModule(this.api);
+    this.profile = new ProfileModule(this.api);
+    this.webhook = new WebhookModule(this.api);
+    this.settings = new SettingsModule(this.api);
+  }
+
+  setInstance(instance: string) {
+    this.options.instance = instance;
+    this.api.setInstance(instance);
+  }
+}
+
+export { EvolutionApiError } from "./api/errors";
+export { phoneNumberFromJid } from "./utils/phone-numer-from-jid";
+export { validatePhoneNumber } from "./schemas/common";
+
+export type * from "./modules/chats/schemas";
+export type * from "./modules/groups/schemas";
+export type * from "./modules/messages/schemas";
+export type * from "./modules/instance/schemas";
+export type * from "./modules/profile/schemas";
+export type * from "./modules/webhook/schemas";
+export type * from "./modules/settings/schemas";
+export type { ClientOptions };
+
+// API types
+export { APIRequestInit, MethodOptions } from "./types/api";
+export { MessageUpdateStatus } from "./types/messages";
+export { ChatId, GroupJid, Jid, MessageId } from "./types/tags";
+export * from "./types/webhooks";
+export { WebhookEvent, WebhookEventSetup } from "./types/events";

package/src/modules/chats/index.ts

@@ -0,0 +1,253 @@
+import { Routes } from "@/api/routes";
+import type { ApiService } from "@/api/service";
+import { validateGroupJid, validateJid } from "@/schemas/common";
+import type { MethodOptions } from "@/types/api";
+
+import type * as Archive from "./schemas/archive";
+import type * as Check from "./schemas/check";
+import type * as DeleteMessage from "./schemas/delete-message";
+import type * as FetchProfilePicture from "./schemas/fetch-profile-picture";
+import type * as FindAll from "./schemas/find-all";
+import type * as FindContacts from "./schemas/find-contacts";
+import type * as FindMessages from "./schemas/find-messages";
+import type * as FindStatusMessage from "./schemas/find-status-message";
+import type * as GetBase64FromMediaMessage from "./schemas/get-base64-from-media-message";
+import type * as MarkAsRead from "./schemas/mark-as-read";
+import type * as MarkAsUnread from "./schemas/mark-as-unread";
+import type * as Presence from "./schemas/presence";
+import type * as UpdateMessage from "./schemas/update-message";
+
+export class ChatsModule {
+  constructor(private readonly api: ApiService) {}
+
+  /**
+   * Checks if phone numbers are registered on WhatsApp
+   * @param numbers - Array of phone numbers to check
+   * @param methodOptions - Method-specific options (instance override)
+   */
+  async check(
+    numbers: Check.CheckOptions,
+    methodOptions?: MethodOptions
+  ): Promise<Check.CheckResponse> {
+    const body = {
+      numbers: Array.isArray(numbers) ? numbers : [numbers],
+    };
+    const response = await this.api.post(Routes.Chats.Check, {
+      body,
+      ...methodOptions,
+    });
+
+    return response as Check.CheckResponse;
+  }
+
+  /**
+   * Gets all chats
+   * @param methodOptions - Method-specific options (instance override)
+   */
+  async findAll(
+    methodOptions?: MethodOptions
+  ): Promise<FindAll.FindAllChatsResponse> {
+    const response = await this.api.post(Routes.Chats.FindAll, {
+      body: {},
+      ...methodOptions,
+    });
+
+    return response as FindAll.FindAllChatsResponse;
+  }
+
+  /**
+   * Updates presence status
+   * @param params - Presence parameters
+   * @param methodOptions - Method-specific options (instance override)
+   */
+  async updatePresence(
+    options: Presence.PresenceOptions,
+    methodOptions?: MethodOptions
+  ): Promise<void> {
+    if (!options.number) {
+      throw new Error("Number is required");
+    }
+
+    if (!validateJid(options.number) && !validateGroupJid(options.number)) {
+      options.number = `${options.number}@s.whatsapp.net`;
+    }
+
+    await this.api.post(Routes.Chats.SendPresence, {
+      body: options,
+      ...methodOptions,
+    });
+  }
+
+  /**
+   * Marks messages as read
+   * @param options - Mark as read options
+   * @param methodOptions - Method-specific options (instance override)
+   */
+  async markAsRead(
+    options: MarkAsRead.MarkAsReadRequest,
+    methodOptions?: MethodOptions
+  ): Promise<MarkAsRead.MarkAsReadResponse> {
+    const response = await this.api.post(Routes.Chats.MarkAsRead, {
+      body: options,
+      ...methodOptions,
+    });
+
+    return response as MarkAsRead.MarkAsReadResponse;
+  }
+
+  /**
+   * Marks messages as unread
+   * @param options - Mark as unread options
+   * @param methodOptions - Method-specific options (instance override)
+   */
+  async markAsUnread(
+    options: MarkAsUnread.MarkAsUnreadRequest,
+    methodOptions?: MethodOptions
+  ): Promise<MarkAsUnread.MarkAsUnreadResponse> {
+    const response = await this.api.post(Routes.Chats.MarkAsUnread, {
+      body: options,
+      ...methodOptions,
+    });
+
+    return response as MarkAsUnread.MarkAsUnreadResponse;
+  }
+
+  /**
+   * Archives a chat
+   * @param options - Archive options
+   * @param methodOptions - Method-specific options (instance override)
+   */
+  async archive(
+    options: Archive.ArchiveRequest,
+    methodOptions?: MethodOptions
+  ): Promise<Archive.ArchiveResponse> {
+    const response = await this.api.post(Routes.Chats.Archive, {
+      body: options,
+      ...methodOptions,
+    });
+
+    return response as Archive.ArchiveResponse;
+  }
+
+  /**
+   * Deletes a message
+   * @param options - Delete message options
+   * @param methodOptions - Method-specific options (instance override)
+   */
+  async deleteMessage(
+    options: DeleteMessage.DeleteMessageRequest,
+    methodOptions?: MethodOptions
+  ): Promise<DeleteMessage.DeleteMessageResponse> {
+    const response = await this.api.delete(Routes.Chats.DeleteMessage, {
+      body: options,
+      ...methodOptions,
+    });
+
+    return response as DeleteMessage.DeleteMessageResponse;
+  }
+
+  /**
+   * Fetches profile picture
+   * @param options - Fetch profile picture options
+   * @param methodOptions - Method-specific options (instance override)
+   */
+  async fetchProfilePicture(
+    options: FetchProfilePicture.FetchProfilePictureRequest,
+    methodOptions?: MethodOptions
+  ): Promise<FetchProfilePicture.FetchProfilePictureResponse> {
+    const response = await this.api.post(Routes.Chats.FetchProfilePicture, {
+      body: options,
+      ...methodOptions,
+    });
+
+    return response as FetchProfilePicture.FetchProfilePictureResponse;
+  }
+
+  /**
+   * Finds contacts
+   * @param options - Find contacts options
+   * @param methodOptions - Method-specific options (instance override)
+   */
+  async findContacts(
+    options: FindContacts.FindContactsRequest,
+    methodOptions?: MethodOptions
+  ): Promise<FindContacts.FindContactsResponse> {
+    const response = await this.api.post(Routes.Chats.FindContacts, {
+      body: options,
+      ...methodOptions,
+    });
+
+    return response as FindContacts.FindContactsResponse;
+  }
+
+  /**
+   * Finds messages
+   * @param options - Find messages options
+   * @param methodOptions - Method-specific options (instance override)
+   */
+  async findMessages(
+    options: FindMessages.FindMessagesRequest,
+    methodOptions?: MethodOptions
+  ): Promise<FindMessages.FindMessagesResponse> {
+    const response = await this.api.post(Routes.Chats.FindMessages, {
+      body: options,
+      ...methodOptions,
+    });
+
+    return response as FindMessages.FindMessagesResponse;
+  }
+
+  /**
+   * Finds status messages
+   * @param options - Find status message options
+   * @param methodOptions - Method-specific options (instance override)
+   */
+  async findStatusMessage(
+    options: FindStatusMessage.FindStatusMessageRequest,
+    methodOptions?: MethodOptions
+  ): Promise<FindStatusMessage.FindStatusMessageResponse> {
+    const response = await this.api.post(Routes.Chats.FindStatusMessage, {
+      body: options,
+      ...methodOptions,
+    });
+
+    return response as FindStatusMessage.FindStatusMessageResponse;
+  }
+
+  /**
+   * Updates a message
+   * @param options - Update message options
+   * @param methodOptions - Method-specific options (instance override)
+   */
+  async updateMessage(
+    options: UpdateMessage.UpdateMessageRequest,
+    methodOptions?: MethodOptions
+  ): Promise<UpdateMessage.UpdateMessageResponse> {
+    const response = await this.api.put(Routes.Chats.UpdateMessage, {
+      body: options,
+      ...methodOptions,
+    });
+
+    return response as UpdateMessage.UpdateMessageResponse;
+  }
+
+  /**
+   * Gets base64 representation of media from a message
+   * @param options - Get base64 from media message options
+   * @param methodOptions - Method-specific options (instance override)
+   */
+  async getBase64FromMediaMessage(
+    options: GetBase64FromMediaMessage.GetBase64FromMediaMessageRequest,
+    methodOptions?: MethodOptions
+  ): Promise<GetBase64FromMediaMessage.GetBase64FromMediaMessageResponse> {
+    const response = await this.api.post(
+      Routes.Chats.GetBase64FromMediaMessage,
+      {
+        body: options,
+        ...methodOptions,
+      }
+    );
+
+    return response as GetBase64FromMediaMessage.GetBase64FromMediaMessageResponse;
+  }
+}

package/src/modules/chats/schemas/archive.ts

@@ -0,0 +1,15 @@
+// Pure TypeScript interfaces for better IDE support and performance
+import type { ChatId } from "@/types/tags";
+
+export interface ArchiveRequest {
+  number: ChatId;
+  archive: boolean;
+}
+
+export interface ArchiveResponse {
+  status: string;
+  message: string;
+}
+
+// Backward compatibility aliases
+export type ArchiveOptions = ArchiveRequest; 

package/src/modules/chats/schemas/check.ts

@@ -0,0 +1,20 @@
+// Pure TypeScript interfaces for better IDE support and performance
+import { parsePhoneNumber } from "libphonenumber-js";
+import { Jid } from "@/types/tags";
+
+// Raw response interface from API
+export interface CheckResponseRaw {
+  exists: boolean;
+  jid: string;
+  number: string;
+}
+
+// Transformed response interface
+export interface CheckResponseItem {
+  exists: boolean;
+  jid: Jid;
+  number: string;
+}
+
+export type CheckOptions = string | string[];
+export type CheckResponse = CheckResponseItem[];

package/src/modules/chats/schemas/delete-message.ts

@@ -0,0 +1,16 @@
+// Pure TypeScript interfaces for better IDE support and performance
+import type { ChatId, MessageId } from "@/types/tags";
+
+export interface DeleteMessageRequest {
+  number: ChatId;
+  messageId: MessageId;
+  owner: boolean;
+}
+
+export interface DeleteMessageResponse {
+  status: string;
+  message: string;
+}
+
+// Backward compatibility aliases
+export type DeleteMessageOptions = DeleteMessageRequest; 

package/src/modules/chats/schemas/fetch-profile-picture.ts

@@ -0,0 +1,13 @@
+// Pure TypeScript interfaces for better IDE support and performance
+import type { ChatId } from "@/types/tags";
+
+export interface FetchProfilePictureRequest {
+  number: ChatId;
+}
+
+export interface FetchProfilePictureResponse {
+  profilePictureUrl: string;
+}
+
+// Backward compatibility aliases
+export type FetchProfilePictureOptions = FetchProfilePictureRequest; 

package/src/modules/chats/schemas/find-all.ts

@@ -0,0 +1,49 @@
+// Pure TypeScript interfaces for better IDE support and performance
+import { ChatId, GroupJid, Jid } from "@/types/tags";
+import { phoneNumberFromJid } from "@/utils/phone-numer-from-jid";
+
+// Raw response interface from API
+export interface FindAllChatsResponseRaw {
+	id: string;
+	remoteJid: string;
+	name?: string | null;
+	labels?: string[] | null;
+	createdAt: string | Date;
+	updatedAt: string | Date;
+	pushName?: string | null;
+	profilePicUrl?: string | null;
+}
+
+// Transformed response interface
+export interface FindAllChatsResponseItem {
+	id: ChatId;
+	jid: GroupJid | Jid;
+	phoneNumber: string;
+	name?: string;
+	labels?: string[];
+	createdAt: Date;
+	updatedAt: Date;
+	pushName?: string;
+	pictureUrl?: string;
+}
+
+export type FindAllChatsResponse = FindAllChatsResponseItem[];
+
+// Transform function
+export const FindAllChatsResponseTransform = (chats: FindAllChatsResponseRaw[]): FindAllChatsResponse =>
+	chats.map((chat) => ({
+		id: ChatId(chat.id),
+		jid: chat.remoteJid.endsWith("@g.us")
+			? GroupJid(chat.remoteJid)
+			: Jid(chat.remoteJid),
+		phoneNumber: phoneNumberFromJid(chat.remoteJid),
+		name: chat.name || undefined,
+		labels: chat.labels || undefined,
+		createdAt: new Date(chat.createdAt),
+		updatedAt: new Date(chat.updatedAt),
+		pushName: chat.pushName || undefined,
+		pictureUrl: chat.profilePicUrl || undefined,
+	}));
+
+// Backward compatibility alias
+export const ResponseSchema = { parse: FindAllChatsResponseTransform };

package/src/modules/chats/schemas/find-contacts.ts

@@ -0,0 +1,17 @@
+// Pure TypeScript interfaces for better IDE support and performance
+import type { ChatId } from "@/types/tags";
+
+export interface FindContactsRequest {
+  number: ChatId;
+}
+
+export interface Contact {
+  id: ChatId;
+  name: string;
+  pushname: string;
+}
+
+export type FindContactsResponse = Contact[];
+
+// Backward compatibility aliases
+export type FindContactsOptions = FindContactsRequest; 

package/src/modules/chats/schemas/find-messages.ts

@@ -0,0 +1,55 @@
+// Pure TypeScript interfaces for better IDE support and performance
+import type { Jid } from "@/types/tags";
+import type {
+  ContextInfo,
+  MessageContent,
+  MessageUpdate,
+} from "@/types/webhooks";
+
+export interface FindMessagesRequest {
+  where: {
+    key: {
+      id?: string;
+      fromMe?: boolean;
+      remoteJid?: string;
+      participants?: string;
+      messageTimestamp?: {
+        lte: string;
+        gte: string;
+      };
+    };
+  };
+  page?: number;
+  offset?: number;
+}
+
+export interface ResponseMessage {
+  id: string;
+  key: {
+    id: string;
+    fromMe: boolean;
+    remoteJid: Jid;
+    senderLid?: string;
+  };
+  pushName?: string;
+  messageType: string;
+  message: MessageContent;
+  messageTimestamp: number;
+  instanceId: string;
+  source: string;
+  contextInfo?: ContextInfo | null;
+  MessageUpdate: MessageUpdate[];
+}
+
+export interface FindMessagesResponse {
+  messages: {
+    total: number;
+    pages: number;
+    currentPage: number;
+    records: ResponseMessage[];
+  };
+}
+
+// Backward compatibility aliases
+export type FindMessagesOptions = FindMessagesRequest;
+export type Message = ResponseMessage;

package/src/modules/chats/schemas/find-status-message.ts

@@ -0,0 +1,11 @@
+// Pure TypeScript interfaces for better IDE support and performance
+import type { ChatId } from "@/types/tags";
+
+export interface FindStatusMessageRequest {
+  number: ChatId;
+}
+
+export type FindStatusMessageResponse = any[];
+
+// Backward compatibility aliases
+export type FindStatusMessageOptions = FindStatusMessageRequest;