@zapyapi/sdk 1.0.0-beta.1 → 1.0.0-beta.10

package/README.md

@@ -178,30 +178,40 @@ console.log(media.url);
 ### Webhooks
 
 ```typescript
-// Configure webhooks
-await client.webhooks.configure('my-instance', {
+// Configure webhook
+await client.webhooks.configure({
   url: 'https://your-server.com/webhook',
-  events: ['message', 'message.ack', 'connection.update'],
-  headers: {
-    'X-Custom-Header': 'your-value',
-  },
+  secret: 'your-secret-min-16-chars', // for HMAC-SHA256 verification
+  isActive: true,
 });
 
 // Get current configuration
-const config = await client.webhooks.get('my-instance');
+const config = await client.webhooks.getConfig();
+
+// Check queue status
+const status = await client.webhooks.getQueueStatus();
+console.log(`Pending: ${status.pendingCount}, Failed: ${status.failedCount}`);
+
+// Resume paused/failed webhooks
+const result = await client.webhooks.resume();
+console.log(`Resumed ${result.resumedCount} webhooks`);
 
 // Delete webhook configuration
-await client.webhooks.delete('my-instance');
+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';
 
@@ -211,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
@@ -233,47 +272,82 @@ normalizePhone('+5511999999999'); // '5511999999999'
 
 // Validate phone numbers
 isValidPhone('5511999999999'); // true
-isValidPhone('5511999999999@c.us'); // true
+isValidPhone('5511999999999@s.whatsapp.net'); // true
 
 // Check if JID is a group
 isGroup('123456789@g.us'); // true
-isGroup('5511999999999@c.us'); // false
+isGroup('5511999999999@s.whatsapp.net'); // false
 
 // Extract phone from JID
-extractPhone('5511999999999@c.us'); // '5511999999999'
+extractPhone('5511999999999@s.whatsapp.net'); // '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 ZapyEventTypes.MESSAGE_STATUS:
+      console.log(`Message ${payload.data.messageId} status: ${payload.data.status}`);
       break;
-    case 'message.ack':
-      // event is MessageAckWebhookEvent
-      console.log(`Message ${event.data.messageId} status: ${event.data.ack}`);
+
+    case ZapyEventTypes.QR_CODE:
+      console.log(`QR Code received, attempt: ${payload.data.attempt}`);
       break;
-    case 'connection.update':
-      // event is ConnectionWebhookEvent
-      console.log(`Connection status: ${event.data.status}`);
+
+    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
@@ -289,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