@zapyapi/sdk 1.0.0-beta.5 → 1.0.0-beta.7

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
@@ -251,35 +284,70 @@ extractPhone('5511999999999@c.us'); // '5511999999999'
 
 ## Webhook Event Types
 
-The SDK provides types for webhook events:
+The SDK provides fully typed webhook events with discriminated unions for each message type:
 
 ```typescript
-import type {
-  WebhookEvent,
-  MessageWebhookEvent,
-  MessageAckWebhookEvent,
-  ConnectionWebhookEvent,
-  QRCodeWebhookEvent,
+import {
+  ZapyWebhookPayload,
+  ZapyEventTypes,
+  isTextMessage,
+  isImageMessage,
+  isVideoMessage,
+  isAudioMessage,
 } from '@zapyapi/sdk';
 
-function handleWebhook(event: WebhookEvent) {
-  switch (event.event) {
-    case 'message':
-      // event is MessageWebhookEvent
-      console.log(`New message from ${event.data.from}`);
+function handleWebhook(payload: ZapyWebhookPayload) {
+  console.log(`Event from instance: ${payload.instanceId}`);
+
+  switch (payload.event) {
+    case ZapyEventTypes.MESSAGE:
+      // payload.data is ZapyMessage (discriminated union)
+      const message = payload.data;
+
+      if (isTextMessage(message)) {
+        console.log(`Text: ${message.text}`);
+      } else if (isImageMessage(message)) {
+        console.log(`Image: ${message.url}, caption: ${message.caption}`);
+      } else if (isVideoMessage(message)) {
+        console.log(`Video: ${message.url}`);
+      } else if (isAudioMessage(message)) {
+        console.log(`Audio: ${message.url}, duration: ${message.duration}s`);
+      }
       break;
-    case 'message.ack':
-      // event is MessageAckWebhookEvent
-      console.log(`Message ${event.data.messageId} status: ${event.data.ack}`);
+
+    case ZapyEventTypes.MESSAGE_STATUS:
+      console.log(`Message ${payload.data.messageId} status: ${payload.data.status}`);
       break;
-    case 'connection.update':
-      // event is ConnectionWebhookEvent
-      console.log(`Connection status: ${event.data.status}`);
+
+    case ZapyEventTypes.QR_CODE:
+      console.log(`QR Code received, attempt: ${payload.data.attempt}`);
+      break;
+
+    case ZapyEventTypes.INSTANCE_STATUS:
+      console.log(`Instance status: ${payload.data.status}`);
       break;
   }
 }
 ```
 
+### Available Message Type Guards
+
+```typescript
+import {
+  isTextMessage,
+  isImageMessage,
+  isVideoMessage,
+  isAudioMessage,
+  isDocumentMessage,
+  isStickerMessage,
+  isLocationMessage,
+  isContactMessage,
+  isReactionMessage,
+  isPollMessage,
+  isMediaMessage, // matches any media type
+} from '@zapyapi/sdk';
+```
+
 ## Requirements
 
 - Node.js 18 or higher
@@ -295,6 +363,33 @@ const { ZapyClient } = require('@zapyapi/sdk');
 const client = new ZapyClient({ apiKey: 'your-api-key' });
 ```
 
+## Low-Level REST API Client
+
+For advanced use cases, the SDK also exports an auto-generated REST client with full type definitions from the OpenAPI spec:
+
+```typescript
+import { ZapyRestApi } from '@zapyapi/sdk';
+
+const api = new ZapyRestApi({
+  baseURL: 'https://api.zapyapi.com',
+  headers: {
+    'x-api-key': 'your-api-key',
+  },
+});
+
+// Direct REST calls with full type safety
+const response = await api.instances.managerInstancesControllerListInstances({
+  page: 1,
+  limit: 10,
+});
+
+// Send a message
+await api.sendMessage.sendMessageControllerSendTextMessage(
+  'my-instance',
+  { to: '5511999999999', text: 'Hello!' }
+);
+```
+
 ## License
 
 MIT