@zapyapi/sdk 1.0.0-beta.4 → 1.0.0-beta.6

package/README.md

@@ -202,12 +202,16 @@ await client.webhooks.deleteConfig();
 
 ## Error Handling
 
+The SDK provides detailed error classes for different failure scenarios:
+
 ```typescript
 import {
   ZapyClient,
   ZapyApiError,
   AuthenticationError,
   RateLimitError,
+  NetworkError,
+  TimeoutError,
   ValidationError,
 } from '@zapyapi/sdk';
 
@@ -217,17 +221,46 @@ try {
     text: 'Hello!',
   });
 } catch (error) {
-  if (error instanceof AuthenticationError) {
+  if (error instanceof TimeoutError) {
+    // Request timed out
+    console.error(`Request timed out after ${error.timeout}ms`);
+    console.error(`Request: ${error.method} ${error.url}`);
+  } else if (error instanceof NetworkError) {
+    // Network failure (no response received)
+    console.error(`Network error: ${error.message}`);
+    console.error(`Error code: ${error.code}`); // e.g., ECONNREFUSED
+  } else if (error instanceof AuthenticationError) {
     console.error('Invalid API key');
   } else if (error instanceof RateLimitError) {
     console.error(`Rate limited. Retry after: ${error.retryAfter}ms`);
+    console.error(`Retry at: ${error.getRetryAfterDate()}`);
   } else if (error instanceof ZapyApiError) {
     console.error(`API Error [${error.code}]: ${error.message}`);
+    console.error(`Status: ${error.statusCode}`);
     console.error(`Request ID: ${error.requestId}`);
+    console.error(`Request: ${error.method} ${error.url}`);
+
+    // For debugging/logging
+    console.error(error.toDetailedString());
+    // Or serialize to JSON
+    console.error(JSON.stringify(error.toJSON(), null, 2));
   }
 }
 ```
 
+### Error Classes
+
+| Error Class | Description |
+|-------------|-------------|
+| `ZapyError` | Base error class for all SDK errors |
+| `ZapyApiError` | API returned an error response (4xx, 5xx) |
+| `AuthenticationError` | Invalid or missing API key (401) |
+| `RateLimitError` | Rate limit exceeded (429) |
+| `NetworkError` | Network failure, no response received |
+| `TimeoutError` | Request timed out |
+| `ValidationError` | Input validation failed |
+| `InstanceNotFoundError` | Instance not found (404) |
+
 ## Utilities
 
 ```typescript

package/index.cjs

@@ -3,7 +3,7 @@
 var axios = require('axios');
 
 /** SDK version - auto-generated from package.json */
-const SDK_VERSION = '1.0.0-beta.4';
+const SDK_VERSION = '1.0.0-beta.6';
 
 /**
  * Custom error classes for @zapyapi/sdk
@@ -12,11 +12,30 @@ const SDK_VERSION = '1.0.0-beta.4';
  * Base error class for all ZapyAPI errors
  */
 class ZapyError extends Error {
-  constructor(message) {
-    super(message);
+  /**
+   * Original error that caused this error (if any)
+   */
+  cause;
+  constructor(message, cause) {
+    super(message, {
+      cause
+    });
     this.name = 'ZapyError';
     Object.setPrototypeOf(this, ZapyError.prototype);
   }
+  /**
+   * Get a detailed string representation of the error
+   */
+  toDetailedString() {
+    let result = `${this.name}: ${this.message}`;
+    if (this.cause) {
+      result += `\nCaused by: ${this.cause.message}`;
+      if (this.cause.stack) {
+        result += `\n${this.cause.stack}`;
+      }
+    }
+    return result;
+  }
 }
 /**
  * Error thrown when the API returns an error response
@@ -38,13 +57,28 @@ class ZapyApiError extends ZapyError {
    * Additional error details
    */
   details;
-  constructor(message, statusCode, code, requestId, details) {
-    super(message);
+  /**
+   * HTTP method used in the request
+   */
+  method;
+  /**
+   * URL that was requested
+   */
+  url;
+  /**
+   * Raw response body (for debugging)
+   */
+  responseBody;
+  constructor(message, statusCode, code, options) {
+    super(message, options?.cause);
     this.name = 'ZapyApiError';
     this.statusCode = statusCode;
     this.code = code;
-    this.requestId = requestId;
-    this.details = details;
+    this.requestId = options?.requestId;
+    this.details = options?.details;
+    this.method = options?.method;
+    this.url = options?.url;
+    this.responseBody = options?.responseBody;
     Object.setPrototypeOf(this, ZapyApiError.prototype);
   }
   /**
@@ -54,10 +88,81 @@ class ZapyApiError extends ZapyError {
     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);
+    const method = error.config?.method?.toUpperCase();
+    const url = error.config?.url;
+    // Build a descriptive message
+    let message;
+    if (data && typeof data === 'object' && 'message' in data && data.message) {
+      message = data.message;
+    } else if (error.message) {
+      message = error.message;
+    } else {
+      message = `Request failed with status ${statusCode}`;
+    }
+    // Add context to the message
+    const context = [];
+    if (method && url) {
+      context.push(`${method} ${url}`);
+    }
+    if (statusCode) {
+      context.push(`Status: ${statusCode}`);
     }
-    return new ZapyApiError(error.message || 'An unexpected error occurred', statusCode, 'UNKNOWN_ERROR', requestId);
+    if (requestId) {
+      context.push(`Request ID: ${requestId}`);
+    }
+    const fullMessage = context.length > 0 ? `${message} [${context.join(' | ')}]` : message;
+    const code = data && typeof data === 'object' && 'code' in data && data.code ? data.code : 'UNKNOWN_ERROR';
+    const details = data && typeof data === 'object' && 'details' in data ? data.details : undefined;
+    return new ZapyApiError(fullMessage, statusCode, code, {
+      requestId: requestId || (data && typeof data === 'object' && 'requestId' in data ? data.requestId : undefined),
+      details,
+      method,
+      url,
+      responseBody: data,
+      cause: error
+    });
+  }
+  /**
+   * Get a detailed string representation for logging
+   */
+  toDetailedString() {
+    const lines = [`${this.name}: ${this.message}`, `  Status Code: ${this.statusCode}`, `  Error Code: ${this.code}`];
+    if (this.method && this.url) {
+      lines.push(`  Request: ${this.method} ${this.url}`);
+    }
+    if (this.requestId) {
+      lines.push(`  Request ID: ${this.requestId}`);
+    }
+    if (this.details && Object.keys(this.details).length > 0) {
+      lines.push(`  Details: ${JSON.stringify(this.details, null, 2)}`);
+    }
+    if (this.responseBody && typeof this.responseBody === 'object') {
+      lines.push(`  Response Body: ${JSON.stringify(this.responseBody, null, 2)}`);
+    }
+    if (this.cause) {
+      lines.push(`  Caused by: ${this.cause.message}`);
+      if (this.cause.stack) {
+        lines.push(`  Stack: ${this.cause.stack.split('\n').slice(1, 4).join('\n    ')}`);
+      }
+    }
+    return lines.join('\n');
+  }
+  /**
+   * Convert to a plain object for logging/serialization
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      statusCode: this.statusCode,
+      code: this.code,
+      requestId: this.requestId,
+      method: this.method,
+      url: this.url,
+      details: this.details,
+      responseBody: this.responseBody,
+      cause: this.cause?.message
+    };
   }
 }
 /**
@@ -74,16 +179,32 @@ class ValidationError extends ZapyError {
     this.details = details;
     Object.setPrototypeOf(this, ValidationError.prototype);
   }
+  toDetailedString() {
+    const fieldErrors = Object.entries(this.details).map(([field, errors]) => `  ${field}: ${errors.join(', ')}`).join('\n');
+    return `${this.name}: ${this.message}\n${fieldErrors}`;
+  }
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      details: this.details
+    };
+  }
 }
 /**
  * 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
+  instanceId;
+  constructor(instanceId, options) {
+    super(`Instance '${instanceId}' not found`, 404, 'INSTANCE_NOT_FOUND', {
+      ...options,
+      details: {
+        instanceId
+      }
     });
     this.name = 'InstanceNotFoundError';
+    this.instanceId = instanceId;
     Object.setPrototypeOf(this, InstanceNotFoundError.prototype);
   }
 }
@@ -91,8 +212,8 @@ class InstanceNotFoundError extends ZapyApiError {
  * Error thrown when authentication fails
  */
 class AuthenticationError extends ZapyApiError {
-  constructor(message = 'Invalid or missing API key', requestId) {
-    super(message, 401, 'UNAUTHORIZED', requestId);
+  constructor(message = 'Invalid or missing API key', options) {
+    super(message, 401, 'UNAUTHORIZED', options);
     this.name = 'AuthenticationError';
     Object.setPrototypeOf(this, AuthenticationError.prototype);
   }
@@ -105,14 +226,89 @@ 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
+  constructor(message = 'Rate limit exceeded', retryAfter, options) {
+    super(message, 429, 'RATE_LIMIT_EXCEEDED', {
+      ...options,
+      details: retryAfter ? {
+        retryAfter
+      } : undefined
     });
     this.name = 'RateLimitError';
     this.retryAfter = retryAfter;
     Object.setPrototypeOf(this, RateLimitError.prototype);
   }
+  /**
+   * Get the Date when the rate limit resets
+   */
+  getRetryAfterDate() {
+    return this.retryAfter ? new Date(this.retryAfter) : undefined;
+  }
+}
+/**
+ * Error thrown when a network error occurs (no response received)
+ */
+class NetworkError extends ZapyError {
+  /**
+   * HTTP method used in the request
+   */
+  method;
+  /**
+   * URL that was requested
+   */
+  url;
+  /**
+   * Error code (e.g., ECONNREFUSED, ETIMEDOUT)
+   */
+  code;
+  constructor(message, options) {
+    super(message, options?.cause);
+    this.name = 'NetworkError';
+    this.method = options?.method;
+    this.url = options?.url;
+    this.code = options?.code;
+    Object.setPrototypeOf(this, NetworkError.prototype);
+  }
+  toDetailedString() {
+    const lines = [`${this.name}: ${this.message}`];
+    if (this.code) {
+      lines.push(`  Error Code: ${this.code}`);
+    }
+    if (this.method && this.url) {
+      lines.push(`  Request: ${this.method} ${this.url}`);
+    }
+    if (this.cause) {
+      lines.push(`  Caused by: ${this.cause.message}`);
+    }
+    return lines.join('\n');
+  }
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code,
+      method: this.method,
+      url: this.url,
+      cause: this.cause?.message
+    };
+  }
+}
+/**
+ * Error thrown when request times out
+ */
+class TimeoutError extends NetworkError {
+  /**
+   * Timeout duration in milliseconds
+   */
+  timeout;
+  constructor(message = 'Request timed out', options) {
+    super(message, {
+      ...options,
+      code: 'ETIMEDOUT'
+    });
+    this.name = 'TimeoutError';
+    this.timeout = options?.timeout;
+    Object.setPrototypeOf(this, TimeoutError.prototype);
+  }
 }
 
 /**
@@ -128,18 +324,58 @@ class BaseResource {
    */
   handleError(error) {
     if (this.isAxiosError(error)) {
-      const statusCode = error.response?.status;
-      const retryAfter = error.response?.headers?.['retry-after'];
+      const method = error.config?.method?.toUpperCase();
+      const url = error.config?.url;
+      const requestId = error.response?.headers?.['x-request-id'];
+      // Network errors (no response received)
+      if (!error.response) {
+        const code = error.code;
+        // Timeout errors
+        if (code === 'ECONNABORTED' || code === 'ETIMEDOUT' || error.message?.includes('timeout')) {
+          const timeout = error.config?.timeout;
+          throw new TimeoutError(`Request timed out${timeout ? ` after ${timeout}ms` : ''}`, {
+            method,
+            url,
+            timeout,
+            cause: error
+          });
+        }
+        // Other network errors (connection refused, DNS failure, etc.)
+        throw new NetworkError(error.message || 'Network error occurred', {
+          method,
+          url,
+          code,
+          cause: 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']);
+        throw new AuthenticationError(error.response.data?.message || 'Invalid or missing API key', {
+          requestId,
+          method,
+          url,
+          cause: error
+        });
       }
       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']);
+        const retryAfterMs = retryAfter ? parseInt(retryAfter, 10) * 1000 : undefined;
+        throw new RateLimitError(error.response.data?.message || 'Rate limit exceeded', retryAfterMs, {
+          requestId,
+          method,
+          url,
+          cause: error
+        });
       }
       throw ZapyApiError.fromAxiosError(error);
     }
+    if (error instanceof ZapyError) {
+      throw error;
+    }
     if (error instanceof Error) {
-      throw new ZapyApiError(error.message, 500, 'UNKNOWN_ERROR');
+      throw new ZapyApiError(error.message, 500, 'UNKNOWN_ERROR', {
+        cause: error
+      });
     }
     throw new ZapyApiError('An unexpected error occurred', 500, 'UNKNOWN_ERROR');
   }
@@ -1239,6 +1475,126 @@ function isContactDeduplicatedEvent(event) {
   return event.event === 'contact-deduplicated';
 }
 
+/**
+ * WhatsApp Message Event Types
+ * Comprehensive type definitions for all WhatsApp message types
+ */
+// ============================================================================
+// Message Status
+// ============================================================================
+exports.ZapyMessageStatusEnum = void 0;
+(function (ZapyMessageStatusEnum) {
+  ZapyMessageStatusEnum["UNKNOWN"] = "UNKNOWN";
+  ZapyMessageStatusEnum["ERROR"] = "ERROR";
+  ZapyMessageStatusEnum["PENDING"] = "PENDING";
+  ZapyMessageStatusEnum["SENT"] = "SENT";
+  ZapyMessageStatusEnum["RECEIVED"] = "RECEIVED";
+  ZapyMessageStatusEnum["READ"] = "READ";
+  ZapyMessageStatusEnum["PLAYED"] = "PLAYED";
+})(exports.ZapyMessageStatusEnum || (exports.ZapyMessageStatusEnum = {}));
+exports.ZapyMessageType = void 0;
+(function (ZapyMessageType) {
+  ZapyMessageType["TEXT"] = "text";
+  ZapyMessageType["IMAGE"] = "image";
+  ZapyMessageType["VIDEO"] = "video";
+  ZapyMessageType["AUDIO"] = "audio";
+  ZapyMessageType["DOCUMENT"] = "document";
+  ZapyMessageType["STICKER"] = "sticker";
+  ZapyMessageType["LOCATION"] = "location";
+  ZapyMessageType["LIVE_LOCATION"] = "live_location";
+  ZapyMessageType["CONTACT"] = "contact";
+  ZapyMessageType["REACTION"] = "reaction";
+  ZapyMessageType["EDITED"] = "edited";
+  ZapyMessageType["DELETED"] = "deleted";
+  ZapyMessageType["POLL"] = "poll";
+  ZapyMessageType["POLL_VOTE"] = "poll_vote";
+  ZapyMessageType["CALL"] = "call";
+  ZapyMessageType["UNSUPPORTED"] = "unsupported";
+})(exports.ZapyMessageType || (exports.ZapyMessageType = {}));
+// ============================================================================
+// Type Guards
+// ============================================================================
+function isTextMessage(message) {
+  return message.messageType === exports.ZapyMessageType.TEXT;
+}
+function isImageMessage(message) {
+  return message.messageType === exports.ZapyMessageType.IMAGE;
+}
+function isVideoMessage(message) {
+  return message.messageType === exports.ZapyMessageType.VIDEO;
+}
+function isAudioMessage(message) {
+  return message.messageType === exports.ZapyMessageType.AUDIO;
+}
+function isDocumentMessage(message) {
+  return message.messageType === exports.ZapyMessageType.DOCUMENT;
+}
+function isStickerMessage(message) {
+  return message.messageType === exports.ZapyMessageType.STICKER;
+}
+function isLocationMessage(message) {
+  return message.messageType === exports.ZapyMessageType.LOCATION;
+}
+function isLiveLocationMessage(message) {
+  return message.messageType === exports.ZapyMessageType.LIVE_LOCATION;
+}
+function isContactMessage(message) {
+  return message.messageType === exports.ZapyMessageType.CONTACT;
+}
+function isReactionMessage(message) {
+  return message.messageType === exports.ZapyMessageType.REACTION;
+}
+function isEditedMessage(message) {
+  return message.messageType === exports.ZapyMessageType.EDITED;
+}
+function isDeletedMessage(message) {
+  return message.messageType === exports.ZapyMessageType.DELETED;
+}
+function isPollMessage(message) {
+  return message.messageType === exports.ZapyMessageType.POLL;
+}
+function isPollVoteMessage(message) {
+  return message.messageType === exports.ZapyMessageType.POLL_VOTE;
+}
+function isCallMessage(message) {
+  return message.messageType === exports.ZapyMessageType.CALL;
+}
+function isUnsupportedMessage(message) {
+  return message.messageType === exports.ZapyMessageType.UNSUPPORTED;
+}
+function isMediaMessage(message) {
+  return [exports.ZapyMessageType.IMAGE, exports.ZapyMessageType.VIDEO, exports.ZapyMessageType.AUDIO, exports.ZapyMessageType.DOCUMENT, exports.ZapyMessageType.STICKER].includes(message.messageType);
+}
+
+exports.WhatsappInstanceStatus = void 0;
+(function (WhatsappInstanceStatus) {
+  WhatsappInstanceStatus["STOPPED"] = "stopped";
+  WhatsappInstanceStatus["MANUALLY_STOPPED"] = "manually_stopped";
+  WhatsappInstanceStatus["CONNECTING"] = "connecting";
+  WhatsappInstanceStatus["PENDING_QR_CODE_SCAN"] = "pending_qr_code_scan";
+  WhatsappInstanceStatus["CONNECTED"] = "connected";
+  WhatsappInstanceStatus["ERROR"] = "error";
+  WhatsappInstanceStatus["CREATED"] = "created";
+  WhatsappInstanceStatus["QR_TIMEOUT"] = "qr_timeout";
+  WhatsappInstanceStatus["PAYMENT_PENDING"] = "payment_pending";
+})(exports.WhatsappInstanceStatus || (exports.WhatsappInstanceStatus = {}));
+
+// Re-export all event types
+/**
+ * Event type constants for type-safe event handling
+ */
+const ZapyEventTypes = {
+  MESSAGE: 'message',
+  MESSAGE_STATUS: 'message-status',
+  REACTION: 'reaction',
+  PRESENCE: 'presence',
+  QR_CODE: 'qr-code',
+  CONTACT_CREATED: 'contact-created',
+  CONTACT_UPDATED: 'contact-updated',
+  CONTACT_DEDUPLICATED: 'contact-deduplicated',
+  INSTANCE_STATUS: 'instance-status'
+};
+
 /**
  * Phone number utilities for @zapyapi/sdk
  */
@@ -1420,23 +1776,43 @@ exports.InstanceNotFoundError = InstanceNotFoundError;
 exports.InstanceStatus = InstanceStatus;
 exports.MessageAckStatus = MessageAckStatus;
 exports.MessageType = MessageType;
+exports.NetworkError = NetworkError;
 exports.RateLimitError = RateLimitError;
+exports.TimeoutError = TimeoutError;
 exports.ValidationError = ValidationError;
 exports.WebhookEventType = WebhookEventType;
 exports.WebhookQueueStatus = WebhookQueueStatus;
 exports.ZapyApiError = ZapyApiError;
 exports.ZapyClient = ZapyClient;
 exports.ZapyError = ZapyError;
+exports.ZapyEventTypes = ZapyEventTypes;
 exports.createClient = createClient;
 exports.extractPhone = extractPhone;
+exports.isAudioMessage = isAudioMessage;
+exports.isCallMessage = isCallMessage;
 exports.isContactCreatedEvent = isContactCreatedEvent;
 exports.isContactDeduplicatedEvent = isContactDeduplicatedEvent;
+exports.isContactMessage = isContactMessage;
 exports.isContactUpdatedEvent = isContactUpdatedEvent;
+exports.isDeletedMessage = isDeletedMessage;
+exports.isDocumentMessage = isDocumentMessage;
+exports.isEditedMessage = isEditedMessage;
 exports.isGroup = isGroup;
+exports.isImageMessage = isImageMessage;
+exports.isLiveLocationMessage = isLiveLocationMessage;
+exports.isLocationMessage = isLocationMessage;
+exports.isMediaMessage = isMediaMessage;
 exports.isMessageEvent = isMessageEvent;
 exports.isMessageStatusEvent = isMessageStatusEvent;
+exports.isPollMessage = isPollMessage;
+exports.isPollVoteMessage = isPollVoteMessage;
 exports.isQRCodeEvent = isQRCodeEvent;
+exports.isReactionMessage = isReactionMessage;
+exports.isStickerMessage = isStickerMessage;
+exports.isTextMessage = isTextMessage;
+exports.isUnsupportedMessage = isUnsupportedMessage;
 exports.isValidPhone = isValidPhone;
+exports.isVideoMessage = isVideoMessage;
 exports.normalizePhone = normalizePhone;
 exports.verifyWebhookSignature = verifyWebhookSignature;
 exports.verifyWebhookSignatureAsync = verifyWebhookSignatureAsync;