@zapyapi/sdk 1.0.0-beta.1

package/README.md

@@ -0,0 +1,308 @@
+# @zapyapi/sdk
+
+[![npm version](https://img.shields.io/npm/v/@zapyapi/sdk.svg)](https://www.npmjs.com/package/@zapyapi/sdk)
+[![npm downloads](https://img.shields.io/npm/dm/@zapyapi/sdk.svg)](https://www.npmjs.com/package/@zapyapi/sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0%2B-blue.svg)](https://www.typescriptlang.org/)
+
+Official TypeScript SDK for [ZapyAPI](https://zapyapi.com) - REST API for WhatsApp integration.
+
+Send messages, manage instances, and receive webhooks with a simple API. No infrastructure to manage.
+
+## Installation
+
+```bash
+npm install @zapyapi/sdk
+# or
+yarn add @zapyapi/sdk
+# or
+pnpm add @zapyapi/sdk
+```
+
+## Quick Start
+
+```typescript
+import { ZapyClient } from '@zapyapi/sdk';
+
+// Initialize the client
+const client = new ZapyClient({
+  apiKey: 'your-api-key', // Get yours at https://app.zapyapi.com/
+});
+
+// Send a text message
+const response = await client.messages.sendText('my-instance', {
+  to: '5511999999999',
+  text: 'Hello from ZapyAPI SDK!',
+});
+
+console.log(`Message sent with ID: ${response.messageId}`);
+```
+
+## Features
+
+- **Type-safe** - Full TypeScript support with comprehensive types
+- **Dual Format** - ESM and CommonJS support out of the box
+- **Modern** - Works with Node.js 18+
+- **Simple** - Intuitive API design for great developer experience
+- **Complete** - Covers all ZapyAPI endpoints (instances, messages, webhooks)
+
+## API Reference
+
+### Client Initialization
+
+```typescript
+import { ZapyClient, createClient } from '@zapyapi/sdk';
+
+// Using constructor
+const client = new ZapyClient({
+  apiKey: 'your-api-key',
+  baseUrl: 'https://api.zapyapi.com/api', // optional
+  timeout: 30000, // optional, in milliseconds
+});
+
+// Using factory function
+const client = createClient({ apiKey: 'your-api-key' });
+```
+
+### Instances
+
+```typescript
+// List all instances
+const instances = await client.instances.list({ page: 1, limit: 10 });
+console.log(`Total: ${instances.total} instances`);
+
+// Create a new instance (Partner only)
+const instance = await client.instances.create({
+  name: 'My Instance',
+  metadata: { department: 'sales' },
+});
+
+// Get QR code for connection
+const qr = await client.instances.getQRCode('my-instance');
+// qr.qrCode is a base64 encoded image
+
+// Restart an instance
+await client.instances.restart('my-instance');
+
+// Logout from WhatsApp
+await client.instances.logout('my-instance');
+```
+
+### Messages
+
+#### Send Text Message
+
+```typescript
+const response = await client.messages.sendText('my-instance', {
+  to: '5511999999999',
+  text: 'Hello, World!',
+  quotedMessageId: 'ABC123...', // optional, for replies
+});
+```
+
+#### Send Image
+
+```typescript
+// Using URL
+await client.messages.sendImage('my-instance', {
+  to: '5511999999999',
+  url: 'https://example.com/image.jpg',
+  caption: 'Check this out!', // optional
+});
+
+// Using Base64
+await client.messages.sendImage('my-instance', {
+  to: '5511999999999',
+  base64: 'data:image/jpeg;base64,...',
+  caption: 'Check this out!',
+});
+```
+
+#### Send Video
+
+```typescript
+await client.messages.sendVideo('my-instance', {
+  to: '5511999999999',
+  url: 'https://example.com/video.mp4',
+  caption: 'Watch this!',
+});
+```
+
+#### Send Audio Note (Voice Message)
+
+```typescript
+await client.messages.sendAudioNote('my-instance', {
+  to: '5511999999999',
+  url: 'https://example.com/audio.ogg',
+});
+```
+
+#### Send Document
+
+```typescript
+await client.messages.sendDocument('my-instance', {
+  to: '5511999999999',
+  url: 'https://example.com/document.pdf',
+  filename: 'report.pdf',
+  caption: 'Here is the report',
+});
+```
+
+#### Other Message Operations
+
+```typescript
+// Forward a message
+await client.messages.forward('my-instance', {
+  to: '5511888888888',
+  messageId: 'ABC123...',
+});
+
+// Edit a message
+await client.messages.edit('my-instance', {
+  messageId: 'ABC123...',
+  text: 'Updated message text',
+});
+
+// Mark as read
+await client.messages.markAsRead('my-instance', 'ABC123...');
+
+// Delete a message
+await client.messages.delete('my-instance', 'ABC123...');
+
+// Get media download link
+const media = await client.messages.getMediaDownloadLink('my-instance', 'ABC123...');
+console.log(media.url);
+```
+
+### Webhooks
+
+```typescript
+// Configure webhooks
+await client.webhooks.configure('my-instance', {
+  url: 'https://your-server.com/webhook',
+  events: ['message', 'message.ack', 'connection.update'],
+  headers: {
+    'X-Custom-Header': 'your-value',
+  },
+});
+
+// Get current configuration
+const config = await client.webhooks.get('my-instance');
+
+// Delete webhook configuration
+await client.webhooks.delete('my-instance');
+```
+
+## Error Handling
+
+```typescript
+import {
+  ZapyClient,
+  ZapyApiError,
+  AuthenticationError,
+  RateLimitError,
+  ValidationError,
+} from '@zapyapi/sdk';
+
+try {
+  await client.messages.sendText('my-instance', {
+    to: '5511999999999',
+    text: 'Hello!',
+  });
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    console.error('Invalid API key');
+  } else if (error instanceof RateLimitError) {
+    console.error(`Rate limited. Retry after: ${error.retryAfter}ms`);
+  } else if (error instanceof ZapyApiError) {
+    console.error(`API Error [${error.code}]: ${error.message}`);
+    console.error(`Request ID: ${error.requestId}`);
+  }
+}
+```
+
+## Utilities
+
+```typescript
+import { normalizePhone, isValidPhone, isGroup, extractPhone } from '@zapyapi/sdk';
+
+// Normalize phone numbers
+normalizePhone('11999999999'); // '5511999999999'
+normalizePhone('+5511999999999'); // '5511999999999'
+
+// Validate phone numbers
+isValidPhone('5511999999999'); // true
+isValidPhone('5511999999999@c.us'); // true
+
+// Check if JID is a group
+isGroup('123456789@g.us'); // true
+isGroup('5511999999999@c.us'); // false
+
+// Extract phone from JID
+extractPhone('5511999999999@c.us'); // '5511999999999'
+```
+
+## Webhook Event Types
+
+The SDK provides types for webhook events:
+
+```typescript
+import type {
+  WebhookEvent,
+  MessageWebhookEvent,
+  MessageAckWebhookEvent,
+  ConnectionWebhookEvent,
+  QRCodeWebhookEvent,
+} from '@zapyapi/sdk';
+
+function handleWebhook(event: WebhookEvent) {
+  switch (event.event) {
+    case 'message':
+      // event is MessageWebhookEvent
+      console.log(`New message from ${event.data.from}`);
+      break;
+    case 'message.ack':
+      // event is MessageAckWebhookEvent
+      console.log(`Message ${event.data.messageId} status: ${event.data.ack}`);
+      break;
+    case 'connection.update':
+      // event is ConnectionWebhookEvent
+      console.log(`Connection status: ${event.data.status}`);
+      break;
+  }
+}
+```
+
+## Requirements
+
+- Node.js 18 or higher
+- TypeScript 5.0+ (for TypeScript users)
+
+## CommonJS Usage
+
+The SDK also works with CommonJS:
+
+```javascript
+const { ZapyClient } = require('@zapyapi/sdk');
+
+const client = new ZapyClient({ apiKey: 'your-api-key' });
+```
+
+## License
+
+MIT
+
+## Links
+
+- [Documentation](https://docs.zapyapi.com)
+- [Dashboard](https://app.zapyapi.com)
+- [API Reference](https://docs.zapyapi.com/api)
+
+## Support
+
+- Email: contato@zapyapi.com
+
+---
+
+Made with :heart: by [ZapyAPI](https://zapyapi.com)