@zapyapi/sdk 1.0.0-beta.1

package/index.js

@@ -0,0 +1,1149 @@
+import axios from 'axios';
+
+/** SDK version - auto-generated from package.json */
+const SDK_VERSION = '1.0.0-beta.1';
+
+/**
+ * Custom error classes for @zapyapi/sdk
+ */
+/**
+ * Base error class for all ZapyAPI errors
+ */
+class ZapyError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'ZapyError';
+    Object.setPrototypeOf(this, ZapyError.prototype);
+  }
+}
+/**
+ * Error thrown when the API returns an error response
+ */
+class ZapyApiError extends ZapyError {
+  /**
+   * HTTP status code
+   */
+  statusCode;
+  /**
+   * Error code from the API
+   */
+  code;
+  /**
+   * Request ID for debugging (if available)
+   */
+  requestId;
+  /**
+   * Additional error details
+   */
+  details;
+  constructor(message, statusCode, code, requestId, details) {
+    super(message);
+    this.name = 'ZapyApiError';
+    this.statusCode = statusCode;
+    this.code = code;
+    this.requestId = requestId;
+    this.details = details;
+    Object.setPrototypeOf(this, ZapyApiError.prototype);
+  }
+  /**
+   * Create a ZapyApiError from an Axios error
+   */
+  static fromAxiosError(error) {
+    const statusCode = error.response?.status ?? 500;
+    const data = error.response?.data;
+    const requestId = error.response?.headers?.['x-request-id'];
+    if (data && typeof data === 'object' && 'code' in data) {
+      return new ZapyApiError(data.message || error.message, statusCode, data.code, requestId || data.requestId, data.details);
+    }
+    return new ZapyApiError(error.message || 'An unexpected error occurred', statusCode, 'UNKNOWN_ERROR', requestId);
+  }
+}
+/**
+ * Error thrown when input validation fails
+ */
+class ValidationError extends ZapyError {
+  /**
+   * Validation error details by field
+   */
+  details;
+  constructor(message, details) {
+    super(message);
+    this.name = 'ValidationError';
+    this.details = details;
+    Object.setPrototypeOf(this, ValidationError.prototype);
+  }
+}
+/**
+ * Error thrown when an instance is not found
+ */
+class InstanceNotFoundError extends ZapyApiError {
+  constructor(instanceId, requestId) {
+    super(`Instance '${instanceId}' not found`, 404, 'INSTANCE_NOT_FOUND', requestId, {
+      instanceId
+    });
+    this.name = 'InstanceNotFoundError';
+    Object.setPrototypeOf(this, InstanceNotFoundError.prototype);
+  }
+}
+/**
+ * Error thrown when authentication fails
+ */
+class AuthenticationError extends ZapyApiError {
+  constructor(message = 'Invalid or missing API key', requestId) {
+    super(message, 401, 'UNAUTHORIZED', requestId);
+    this.name = 'AuthenticationError';
+    Object.setPrototypeOf(this, AuthenticationError.prototype);
+  }
+}
+/**
+ * Error thrown when rate limit is exceeded
+ */
+class RateLimitError extends ZapyApiError {
+  /**
+   * Timestamp when the rate limit resets (Unix ms)
+   */
+  retryAfter;
+  constructor(message = 'Rate limit exceeded', retryAfter, requestId) {
+    super(message, 429, 'RATE_LIMIT_EXCEEDED', requestId, {
+      retryAfter
+    });
+    this.name = 'RateLimitError';
+    this.retryAfter = retryAfter;
+    Object.setPrototypeOf(this, RateLimitError.prototype);
+  }
+}
+
+/**
+ * Base resource class with common HTTP functionality
+ */
+class BaseResource {
+  http;
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Handle API errors and convert to appropriate error types
+   */
+  handleError(error) {
+    if (this.isAxiosError(error)) {
+      const statusCode = error.response?.status;
+      const retryAfter = error.response?.headers?.['retry-after'];
+      if (statusCode === 401) {
+        throw new AuthenticationError(error.response?.data?.message || 'Invalid or missing API key', error.response?.headers?.['x-request-id']);
+      }
+      if (statusCode === 429) {
+        throw new RateLimitError(error.response?.data?.message || 'Rate limit exceeded', retryAfter ? parseInt(retryAfter, 10) * 1000 : undefined, error.response?.headers?.['x-request-id']);
+      }
+      throw ZapyApiError.fromAxiosError(error);
+    }
+    if (error instanceof Error) {
+      throw new ZapyApiError(error.message, 500, 'UNKNOWN_ERROR');
+    }
+    throw new ZapyApiError('An unexpected error occurred', 500, 'UNKNOWN_ERROR');
+  }
+  /**
+   * Type guard for Axios errors
+   */
+  isAxiosError(error) {
+    return typeof error === 'object' && error !== null && 'isAxiosError' in error && error.isAxiosError === true;
+  }
+}
+
+/**
+ * Messages resource for sending and managing messages
+ */
+class MessagesResource extends BaseResource {
+  constructor(http) {
+    super(http);
+  }
+  /**
+   * Send a text message
+   *
+   * @param instanceId - Instance ID
+   * @param options - Message options
+   * @returns Message response with ID and status
+   *
+   * @example
+   * const response = await client.messages.sendText('my-instance', {
+   *   to: '5511999999999',
+   *   text: 'Hello from ZapyAPI!'
+   * });
+   */
+  async sendText(instanceId, options) {
+    try {
+      const response = await this.http.post(`/message/${instanceId}/text`, {
+        to: options.to,
+        message: options.text,
+        quoteMessageId: options.quotedMessageId
+      });
+      return response.data;
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+  /**
+   * Send an image message
+   *
+   * @param instanceId - Instance ID
+   * @param options - Image message options
+   * @returns Message response with ID and status
+   *
+   * @example
+   * await client.messages.sendImage('my-instance', {
+   *   to: '5511999999999',
+   *   url: 'https://example.com/image.jpg',
+   *   caption: 'Check this out!'
+   * });
+   */
+  async sendImage(instanceId, options) {
+    try {
+      const response = await this.http.post(`/message/${instanceId}/image`, {
+        to: options.to,
+        url: options.url,
+        base64: options.base64,
+        caption: options.caption,
+        quoteMessageId: options.quotedMessageId
+      });
+      return response.data;
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+  /**
+   * Send a video message
+   *
+   * @param instanceId - Instance ID
+   * @param options - Video message options
+   * @returns Message response with ID and status
+   *
+   * @example
+   * await client.messages.sendVideo('my-instance', {
+   *   to: '5511999999999',
+   *   url: 'https://example.com/video.mp4',
+   *   caption: 'Watch this!'
+   * });
+   */
+  async sendVideo(instanceId, options) {
+    try {
+      const response = await this.http.post(`/message/${instanceId}/video`, {
+        to: options.to,
+        url: options.url,
+        base64: options.base64,
+        caption: options.caption,
+        quoteMessageId: options.quotedMessageId
+      });
+      return response.data;
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+  /**
+   * Send an audio note (voice message)
+   *
+   * @param instanceId - Instance ID
+   * @param options - Audio note options
+   * @returns Message response with ID and status
+   *
+   * @example
+   * await client.messages.sendAudioNote('my-instance', {
+   *   to: '5511999999999',
+   *   url: 'https://example.com/audio.ogg'
+   * });
+   */
+  async sendAudioNote(instanceId, options) {
+    try {
+      const response = await this.http.post(`/message/${instanceId}/audio-note`, {
+        to: options.to,
+        url: options.url,
+        base64: options.base64,
+        quoteMessageId: options.quotedMessageId
+      });
+      return response.data;
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+  /**
+   * Send an audio file
+   *
+   * @param instanceId - Instance ID
+   * @param options - Audio file options
+   * @returns Message response with ID and status
+   *
+   * @example
+   * await client.messages.sendAudioFile('my-instance', {
+   *   to: '5511999999999',
+   *   url: 'https://example.com/song.mp3'
+   * });
+   */
+  async sendAudioFile(instanceId, options) {
+    try {
+      const response = await this.http.post(`/message/${instanceId}/audio-file`, {
+        to: options.to,
+        url: options.url,
+        base64: options.base64,
+        quoteMessageId: options.quotedMessageId
+      });
+      return response.data;
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+  /**
+   * Send a document
+   *
+   * @param instanceId - Instance ID
+   * @param options - Document options
+   * @returns Message response with ID and status
+   *
+   * @example
+   * await client.messages.sendDocument('my-instance', {
+   *   to: '5511999999999',
+   *   url: 'https://example.com/document.pdf',
+   *   filename: 'report.pdf',
+   *   caption: 'Here is the report'
+   * });
+   */
+  async sendDocument(instanceId, options) {
+    try {
+      const response = await this.http.post(`/message/${instanceId}/document`, {
+        to: options.to,
+        url: options.url,
+        base64: options.base64,
+        filename: options.filename,
+        caption: options.caption,
+        quoteMessageId: options.quotedMessageId
+      });
+      return response.data;
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+  /**
+   * Forward a message to another contact/group
+   *
+   * @param instanceId - Instance ID
+   * @param options - Forward options
+   * @returns Message response with ID and status
+   *
+   * @example
+   * await client.messages.forward('my-instance', {
+   *   to: '5511888888888',
+   *   messageId: 'ABC123...'
+   * });
+   */
+  async forward(instanceId, options) {
+    try {
+      const response = await this.http.post(`/message/${instanceId}/forward`, {
+        to: options.to,
+        messageId: options.messageId
+      });
+      return response.data;
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+  /**
+   * Edit a previously sent text message
+   *
+   * @param instanceId - Instance ID
+   * @param options - Edit options
+   * @returns Message response
+   *
+   * @example
+   * await client.messages.edit('my-instance', {
+   *   messageId: 'ABC123...',
+   *   text: 'Updated message text'
+   * });
+   */
+  async edit(instanceId, options) {
+    try {
+      const response = await this.http.post(`/message/${instanceId}/edit`, {
+        messageId: options.messageId,
+        message: options.text
+      });
+      return response.data;
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+  /**
+   * Mark a message as read
+   *
+   * @param instanceId - Instance ID
+   * @param messageId - Message ID to mark as read
+   * @returns Read confirmation
+   *
+   * @example
+   * await client.messages.markAsRead('my-instance', 'ABC123...');
+   */
+  async markAsRead(instanceId, messageId) {
+    try {
+      const response = await this.http.post(`/message/${instanceId}/read`, {
+        messageId
+      });
+      return response.data;
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+  /**
+   * Delete a message for everyone
+   *
+   * @param instanceId - Instance ID
+   * @param messageId - Message ID to delete
+   *
+   * @example
+   * await client.messages.delete('my-instance', 'ABC123...');
+   */
+  async delete(instanceId, messageId) {
+    try {
+      await this.http.delete(`/message/${instanceId}/delete`, {
+        data: {
+          messageId
+        }
+      });
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+  /**
+   * Get a download link for message media
+   *
+   * @param instanceId - Instance ID
+   * @param messageId - Message ID containing media
+   * @returns Media download link
+   *
+   * @example
+   * const media = await client.messages.getMediaDownloadLink('my-instance', 'ABC123...');
+   * console.log(media.url);
+   */
+  async getMediaDownloadLink(instanceId, messageId) {
+    try {
+      const response = await this.http.get(`/message/${instanceId}/media-download-link/${messageId}`);
+      return response.data;
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+}
+
+/**
+ * Webhooks resource
+ *
+ * Webhooks are configured at the USER level, not per-instance.
+ * One webhook URL receives events from ALL your instances.
+ *
+ * Benefits of user-level webhooks:
+ * - One webhook URL receives events from ALL your instances
+ * - Simplified configuration and management
+ * - Built-in retry queue with pause/resume functionality
+ * - HMAC-SHA256 signature verification
+ *
+ * Each webhook payload includes `instanceId` to identify the source instance.
+ *
+ * @see https://docs.zapyapi.com/webhooks for documentation
+ */
+/**
+ * Webhooks resource for managing user-level webhook configuration
+ *
+ * @example
+ * ```typescript
+ * import { ZapyClient } from '@zapyapi/sdk';
+ *
+ * const client = new ZapyClient({ apiKey: 'your-api-key' });
+ *
+ * // Configure webhook
+ * await client.webhooks.configure({
+ *   url: 'https://your-server.com/webhook',
+ *   secret: 'your-webhook-secret',
+ *   isActive: true,
+ * });
+ *
+ * // Get current configuration
+ * const config = await client.webhooks.getConfig();
+ *
+ * // Check queue status
+ * const status = await client.webhooks.getQueueStatus();
+ * ```
+ */
+class WebhooksResource extends BaseResource {
+  constructor(http) {
+    super(http);
+  }
+  /**
+   * Get the current webhook configuration
+   *
+   * @returns The webhook configuration or null if not configured
+   *
+   * @example
+   * ```typescript
+   * const config = await client.webhooks.getConfig();
+   * if (config) {
+   *   console.log('Webhook URL:', config.url);
+   *   console.log('Is active:', config.isActive);
+   * }
+   * ```
+   */
+  async getConfig() {
+    try {
+      const response = await this.http.get('/webhooks/config');
+      return response.data;
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+  /**
+   * Configure or update the webhook
+   *
+   * @param config - Webhook configuration
+   * @returns The saved webhook configuration
+   *
+   * @example
+   * ```typescript
+   * const config = await client.webhooks.configure({
+   *   url: 'https://your-server.com/webhook',
+   *   secret: 'your-webhook-secret-min-16-chars',
+   *   isActive: true,
+   * });
+   * ```
+   */
+  async configure(config) {
+    try {
+      const response = await this.http.put('/webhooks/config', config);
+      return response.data;
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+  /**
+   * Delete the webhook configuration
+   *
+   * This will also delete all queued webhooks.
+   *
+   * @example
+   * ```typescript
+   * await client.webhooks.deleteConfig();
+   * ```
+   */
+  async deleteConfig() {
+    try {
+      await this.http.delete('/webhooks/config');
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+  /**
+   * Get the webhook queue status
+   *
+   * @returns Queue status with counts of pending, failed, paused, and delivered webhooks
+   *
+   * @example
+   * ```typescript
+   * const status = await client.webhooks.getQueueStatus();
+   * console.log('Pending:', status.pendingCount);
+   * console.log('Failed:', status.failedCount);
+   * ```
+   */
+  async getQueueStatus() {
+    try {
+      const response = await this.http.get('/webhooks/queue/status');
+      return response.data;
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+  /**
+   * Resume all paused and failed webhooks
+   *
+   * This will unpause the webhook configuration and reset all paused/failed items to pending.
+   *
+   * @returns The number of webhooks resumed
+   *
+   * @example
+   * ```typescript
+   * const result = await client.webhooks.resume();
+   * console.log('Resumed:', result.resumedCount, 'webhooks');
+   * ```
+   */
+  async resume() {
+    try {
+      const response = await this.http.post('/webhooks/queue/resume');
+      return response.data;
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+}
+
+/**
+ * Instances resource for managing WhatsApp instances
+ */
+class InstancesResource extends BaseResource {
+  constructor(http) {
+    super(http);
+  }
+  /**
+   * List all instances with pagination
+   *
+   * @param query - Pagination options
+   * @returns Paginated list of instances
+   *
+   * @example
+   * const instances = await client.instances.list({ page: 1, limit: 10 });
+   * console.log(`Found ${instances.total} instances`);
+   */
+  async list(query) {
+    try {
+      const response = await this.http.get('/instances', {
+        params: query
+      });
+      return response.data;
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+  /**
+   * Create a new WhatsApp instance (Partner only)
+   *
+   * @param options - Instance creation options
+   * @returns The created instance
+   *
+   * @example
+   * const instance = await client.instances.create({
+   *   name: 'My Instance',
+   *   metadata: { department: 'sales' }
+   * });
+   */
+  async create(options) {
+    try {
+      const response = await this.http.post('/instances', options ?? {});
+      return response.data;
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+  /**
+   * Get QR code for connecting an instance
+   *
+   * @param instanceId - Instance ID
+   * @returns QR code response with base64 image
+   *
+   * @example
+   * const qr = await client.instances.getQRCode('my-instance');
+   * // Display qr.qrCode as an image (it's base64 encoded)
+   */
+  async getQRCode(instanceId) {
+    try {
+      const response = await this.http.get(`/instances/${instanceId}/qr`);
+      return response.data;
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+  /**
+   * Restart an instance connection
+   *
+   * @param instanceId - Instance ID
+   *
+   * @example
+   * await client.instances.restart('my-instance');
+   */
+  async restart(instanceId) {
+    try {
+      await this.http.post(`/instances/${instanceId}/restart`);
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+  /**
+   * Logout from WhatsApp (disconnect the instance)
+   *
+   * @param instanceId - Instance ID
+   *
+   * @example
+   * await client.instances.logout('my-instance');
+   */
+  async logout(instanceId) {
+    try {
+      await this.http.post(`/instances/${instanceId}/logout`);
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+  /**
+   * Delete an instance (Partner only)
+   *
+   * This permanently deletes the instance and all associated data.
+   * This action is irreversible.
+   *
+   * @param instanceId - Instance ID
+   *
+   * @example
+   * await client.instances.delete('my-instance');
+   */
+  async delete(instanceId) {
+    try {
+      await this.http.delete(`/instances/${instanceId}`);
+    } catch (error) {
+      this.handleError(error);
+    }
+  }
+}
+
+/**
+ * ZapyClient - Main entry point for the ZapyAPI SDK
+ */
+/**
+ * ZapyClient - Official TypeScript SDK for ZapyAPI
+ *
+ * @example
+ * ```typescript
+ * import { ZapyClient, WebhookEventType, isMessageEvent } from '@zapyapi/sdk';
+ *
+ * const client = new ZapyClient({
+ *   apiKey: 'your-api-key',
+ * });
+ *
+ * // Send a text message
+ * await client.messages.sendText('my-instance', {
+ *   to: '5511999999999',
+ *   text: 'Hello from ZapyAPI SDK!'
+ * });
+ *
+ * // List instances
+ * const instances = await client.instances.list();
+ *
+ * // Get QR code for an instance
+ * const qr = await client.instances.getQRCode('my-instance');
+ *
+ * // Configure webhooks programmatically
+ * await client.webhooks.configure({
+ *   url: 'https://your-server.com/webhook',
+ *   secret: 'your-secret-key-min-16-chars',
+ *   isActive: true,
+ * });
+ * ```
+ */
+class ZapyClient {
+  /**
+   * Internal Axios HTTP client
+   */
+  http;
+  /**
+   * Instance management operations
+   */
+  instances;
+  /**
+   * Message sending and management operations
+   */
+  messages;
+  /**
+   * Webhook configuration and management operations
+   *
+   * Webhooks are configured at the user level - one webhook URL receives
+   * events from ALL your instances. Each payload includes `instanceId`.
+   */
+  webhooks;
+  /**
+   * Create a new ZapyClient instance
+   *
+   * @param options - Client configuration options
+   *
+   * @example
+   * const client = new ZapyClient({
+   *   apiKey: 'your-api-key',
+   *   baseUrl: 'https://api.zapyapi.com/api', // optional
+   *   timeout: 30000, // optional, in milliseconds
+   * });
+   */
+  constructor(options) {
+    if (!options.apiKey) {
+      throw new Error('API key is required. Get yours at https://app.zapyapi.com/');
+    }
+    this.http = axios.create({
+      baseURL: options.baseUrl ?? 'https://api.zapyapi.com/api',
+      timeout: options.timeout ?? 30000,
+      headers: {
+        'x-api-key': options.apiKey,
+        'Content-Type': 'application/json',
+        'User-Agent': `@zapyapi/sdk/${SDK_VERSION}`,
+        ...options.headers
+      }
+    });
+    // Initialize resources
+    this.instances = new InstancesResource(this.http);
+    this.messages = new MessagesResource(this.http);
+    this.webhooks = new WebhooksResource(this.http);
+  }
+  /**
+   * Get the underlying Axios instance for advanced usage
+   *
+   * @returns The configured Axios instance
+   *
+   * @example
+   * const httpClient = client.getHttpClient();
+   * httpClient.interceptors.response.use(/* ... *\/);
+   */
+  getHttpClient() {
+    return this.http;
+  }
+}
+/**
+ * Create a new ZapyClient instance
+ *
+ * @param options - Client configuration options
+ * @returns A configured ZapyClient instance
+ *
+ * @example
+ * import { createClient } from '@zapyapi/sdk';
+ *
+ * const client = createClient({
+ *   apiKey: 'your-api-key',
+ * });
+ */
+function createClient(options) {
+  return new ZapyClient(options);
+}
+
+/**
+ * SDK Enums - Type-safe enums for ZapyAPI SDK
+ *
+ * These enums can be imported and used for type-safe comparisons and
+ * webhook event handling.
+ *
+ * @example
+ * ```typescript
+ * import { WebhookEventType, InstanceStatus, MessageAckStatus } from '@zapyapi/sdk';
+ *
+ * // Type-safe event handling
+ * if (event.event === WebhookEventType.MESSAGE) {
+ *   // Handle message event
+ * }
+ *
+ * // Check instance status
+ * if (instance.status === InstanceStatus.CONNECTED) {
+ *   // Instance is ready
+ * }
+ * ```
+ */
+/**
+ * Webhook event types sent by ZapyAPI
+ * These are the event types you'll receive in webhook payloads
+ */
+const WebhookEventType = {
+  /** New message received */
+  MESSAGE: 'message',
+  /** Message delivery status update */
+  MESSAGE_STATUS: 'message-status',
+  /** QR code generated for authentication */
+  QR_CODE: 'qr-code',
+  /** New contact discovered */
+  CONTACT_CREATED: 'contact-created',
+  /** Contact information updated */
+  CONTACT_UPDATED: 'contact-updated',
+  /** Duplicate contacts merged */
+  CONTACT_DEDUPLICATED: 'contact-deduplicated'
+};
+/**
+ * Instance status values
+ * Represents the current state of a WhatsApp instance
+ */
+const InstanceStatus = {
+  /** Instance is stopped */
+  STOPPED: 'stopped',
+  /** Instance was manually stopped by user */
+  MANUALLY_STOPPED: 'manually_stopped',
+  /** Instance is connecting to WhatsApp */
+  CONNECTING: 'connecting',
+  /** Waiting for QR code to be scanned */
+  PENDING_QR_CODE_SCAN: 'pending_qr_code_scan',
+  /** Instance is connected and ready */
+  CONNECTED: 'connected',
+  /** Instance encountered an error */
+  ERROR: 'error',
+  /** Instance was just created */
+  CREATED: 'created',
+  /** QR code scanning timed out */
+  QR_TIMEOUT: 'qr_timeout',
+  /** Payment pending for this instance */
+  PAYMENT_PENDING: 'payment_pending'
+};
+/**
+ * Message acknowledgment status
+ * Represents the delivery status of a sent message
+ */
+const MessageAckStatus = {
+  /** Message is pending to be sent */
+  PENDING: 'pending',
+  /** Message was sent to server */
+  SENT: 'sent',
+  /** Message was delivered to recipient */
+  DELIVERED: 'delivered',
+  /** Message was read by recipient */
+  READ: 'read',
+  /** Audio/video message was played */
+  PLAYED: 'played'
+};
+/**
+ * Message types for incoming messages
+ * Identifies the type of content in a received message
+ */
+const MessageType = {
+  /** Text message */
+  TEXT: 'text',
+  /** Image message */
+  IMAGE: 'image',
+  /** Video message */
+  VIDEO: 'video',
+  /** Audio message (voice note or file) */
+  AUDIO: 'audio',
+  /** Document/file message */
+  DOCUMENT: 'document',
+  /** Sticker message */
+  STICKER: 'sticker',
+  /** Location message */
+  LOCATION: 'location',
+  /** Contact card message */
+  CONTACT: 'contact',
+  /** Poll message */
+  POLL: 'poll',
+  /** Reaction message */
+  REACTION: 'reaction'
+};
+/**
+ * Webhook queue item status
+ * Used for monitoring webhook delivery status
+ */
+const WebhookQueueStatus = {
+  /** Webhook is queued for delivery */
+  PENDING: 'pending',
+  /** Webhook is being processed */
+  PROCESSING: 'processing',
+  /** Webhook was successfully delivered */
+  DELIVERED: 'delivered',
+  /** Webhook delivery failed after retries */
+  FAILED: 'failed',
+  /** Webhook delivery is paused due to repeated failures */
+  PAUSED: 'paused'
+};
+/**
+ * Connection status for webhook events
+ * Sent in connection.update webhook events
+ */
+const ConnectionStatus = {
+  /** Instance is connecting */
+  CONNECTING: 'connecting',
+  /** Instance is connected */
+  CONNECTED: 'connected',
+  /** Instance disconnected */
+  DISCONNECTED: 'disconnected',
+  /** Connection error occurred */
+  ERROR: 'error'
+};
+
+/**
+ * Webhook event type definitions
+ * Types for webhook payloads sent by ZapyAPI
+ */
+/** Type guard for message events */
+function isMessageEvent(event) {
+  return event.event === 'message';
+}
+/** Type guard for message status events */
+function isMessageStatusEvent(event) {
+  return event.event === 'message-status';
+}
+/** Type guard for QR code events */
+function isQRCodeEvent(event) {
+  return event.event === 'qr-code';
+}
+/** Type guard for contact created events */
+function isContactCreatedEvent(event) {
+  return event.event === 'contact-created';
+}
+/** Type guard for contact updated events */
+function isContactUpdatedEvent(event) {
+  return event.event === 'contact-updated';
+}
+/** Type guard for contact deduplicated events */
+function isContactDeduplicatedEvent(event) {
+  return event.event === 'contact-deduplicated';
+}
+
+/**
+ * Phone number utilities for @zapyapi/sdk
+ */
+/**
+ * Normalize a phone number to the format expected by the API
+ *
+ * @param phone - Phone number in various formats
+ * @returns Normalized phone number
+ *
+ * @example
+ * normalizePhone('11999999999')     // '5511999999999'
+ * normalizePhone('5511999999999')   // '5511999999999'
+ * normalizePhone('+5511999999999')  // '5511999999999'
+ * normalizePhone('5511999999999@c.us') // '5511999999999@c.us'
+ */
+function normalizePhone(phone) {
+  // If it's already a WhatsApp ID, return as-is
+  if (phone.includes('@')) {
+    return phone;
+  }
+  // Remove all non-numeric characters except +
+  let cleaned = phone.replace(/[^\d+]/g, '');
+  // Remove leading +
+  if (cleaned.startsWith('+')) {
+    cleaned = cleaned.slice(1);
+  }
+  // If it doesn't start with 55 (Brazil), add it
+  // This assumes Brazilian numbers as default - can be made configurable
+  if (!cleaned.startsWith('55') && cleaned.length <= 11) {
+    cleaned = '55' + cleaned;
+  }
+  return cleaned;
+}
+/**
+ * Validate if a string is a valid phone number format
+ *
+ * @param phone - Phone number to validate
+ * @returns Whether the phone number is valid
+ */
+function isValidPhone(phone) {
+  // WhatsApp IDs are valid
+  if (phone.includes('@')) {
+    return phone.endsWith('@c.us') || phone.endsWith('@g.us') || phone.endsWith('@lid');
+  }
+  // Clean and check if it's a valid number
+  const cleaned = phone.replace(/[^\d]/g, '');
+  // Brazilian number: 12-13 digits with country code
+  // International: 10-15 digits
+  return cleaned.length >= 10 && cleaned.length <= 15;
+}
+/**
+ * Check if a WhatsApp ID is a group
+ *
+ * @param jid - WhatsApp ID (JID)
+ * @returns Whether the JID is a group
+ */
+function isGroup(jid) {
+  return jid.endsWith('@g.us');
+}
+/**
+ * Extract the phone number from a WhatsApp ID
+ *
+ * @param jid - WhatsApp ID (JID)
+ * @returns Phone number without the @suffix
+ */
+function extractPhone(jid) {
+  const parts = jid.split('@');
+  return parts[0] ?? jid;
+}
+
+/**
+ * Webhook signature verification utilities
+ * HMAC-SHA256 signature verification for webhook payloads
+ */
+/**
+ * Verify webhook signature (synchronous)
+ *
+ * For best results, pass the raw request body as a string.
+ *
+ * @param payload - The webhook payload (raw body string recommended)
+ * @param signature - The X-Webhook-Signature header value
+ * @param secret - Your webhook secret
+ * @returns true if the signature is valid
+ *
+ * @example
+ * ```typescript
+ * import { verifyWebhookSignature } from '@zapyapi/sdk';
+ *
+ * app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
+ *   const signature = req.headers['x-webhook-signature'] as string;
+ *   const isValid = verifyWebhookSignature(
+ *     req.body.toString('utf8'),
+ *     signature,
+ *     process.env.WEBHOOK_SECRET!
+ *   );
+ *
+ *   if (!isValid) {
+ *     return res.status(401).send('Invalid signature');
+ *   }
+ *
+ *   const event = JSON.parse(req.body.toString('utf8'));
+ *   res.status(200).send('OK');
+ * });
+ * ```
+ */
+function verifyWebhookSignature(payload, signature, secret) {
+  if (!signature || !secret) return false;
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const crypto = require('crypto');
+    return verifySignatureWithCrypto(crypto, payload, signature, secret);
+  } catch {
+    if (typeof console !== 'undefined' && console.warn) {
+      console.warn('@zapyapi/sdk: crypto module not available. ' + 'Use verifyWebhookSignatureAsync() or verify on your server.');
+    }
+    return false;
+  }
+}
+/**
+ * Verify webhook signature (async - recommended for ESM)
+ *
+ * Uses dynamic import() for ESM compatibility.
+ *
+ * @param payload - The webhook payload (raw body string recommended)
+ * @param signature - The X-Webhook-Signature header value
+ * @param secret - Your webhook secret
+ * @returns Promise resolving to true if valid
+ *
+ * @example
+ * ```typescript
+ * import { verifyWebhookSignatureAsync } from '@zapyapi/sdk';
+ *
+ * app.post('/webhook', express.raw({ type: 'application/json' }), async (req, res) => {
+ *   const signature = req.headers['x-webhook-signature'] as string;
+ *   const isValid = await verifyWebhookSignatureAsync(
+ *     req.body.toString('utf8'),
+ *     signature,
+ *     process.env.WEBHOOK_SECRET!
+ *   );
+ *
+ *   if (!isValid) {
+ *     return res.status(401).send('Invalid signature');
+ *   }
+ *
+ *   const event = JSON.parse(req.body.toString('utf8'));
+ *   res.status(200).send('OK');
+ * });
+ * ```
+ */
+async function verifyWebhookSignatureAsync(payload, signature, secret) {
+  if (!signature || !secret) return false;
+  try {
+    const crypto = await import('crypto');
+    return verifySignatureWithCrypto(crypto, payload, signature, secret);
+  } catch {
+    if (typeof console !== 'undefined' && console.warn) {
+      console.warn('@zapyapi/sdk: crypto module not available. ' + 'Verify signatures on your server instead.');
+    }
+    return false;
+  }
+}
+/**
+ * Internal helper to verify signature with crypto module
+ */
+function verifySignatureWithCrypto(crypto, payload, signature, secret) {
+  const body = typeof payload === 'string' ? payload : JSON.stringify(payload);
+  const expectedSignature = `sha256=${crypto.createHmac('sha256', secret).update(body, 'utf8').digest('hex')}`;
+  // Fast fail for wrong length
+  if (signature.length !== expectedSignature.length) {
+    return false;
+  }
+  // Timing-safe comparison to prevent timing attacks
+  return crypto.timingSafeEqual(Buffer.from(signature, 'utf8'), Buffer.from(expectedSignature, 'utf8'));
+}
+
+export { AuthenticationError, ConnectionStatus, InstanceNotFoundError, InstanceStatus, MessageAckStatus, MessageType, RateLimitError, ValidationError, WebhookEventType, WebhookQueueStatus, ZapyApiError, ZapyClient, ZapyError, createClient, extractPhone, isContactCreatedEvent, isContactDeduplicatedEvent, isContactUpdatedEvent, isGroup, isMessageEvent, isMessageStatusEvent, isQRCodeEvent, isValidPhone, normalizePhone, verifyWebhookSignature, verifyWebhookSignatureAsync };