whatshub-sdk

TypeScript/JavaScript SDK for integrating with the WhatsHub WhatsApp API. Send messages, manage instances, and interact with WhatsApp programmatically.

Installation

npm install whatshub-sdk
# or
yarn add whatshub-sdk

Quick Start

import { WhatsHubClient } from 'whatshub-sdk';

const client = new WhatsHubClient({
  baseUrl: 'http://localhost:9697',
  apiToken: 'your-api-token-here'
});

// Check server health
const health = await client.getStatus();
console.log('Server status:', health);

// Send a text message
const message = await client.messages.sendText({
  from: '971582354842',
  to: '971521128878',
  text: 'Hello from WhatsHub SDK!'
});

Features

• Instance Management: Create, monitor, and manage WhatsApp instances
• Message Sending: Send text, images, documents, and videos
• Type-Safe: Full TypeScript support with comprehensive type definitions
• Error Handling: Custom error classes for better error management
• Utilities: Phone number validation and normalization

Usage

Initialize Client

import { WhatsHubClient } from 'whatshub-sdk';

const client = new WhatsHubClient({
  baseUrl: 'http://localhost:9697',
  apiToken: 'your-api-token-here',
  timeout: 30000 // optional, default is 30000ms
});

Instance Management

Create Instance

const instance = await client.instances.create({
  phoneNumber: '971582354842'
});

console.log('QR Code:', instance.qrCodeUrl);

Get Instance Status

const status = await client.instances.getStatus('971582354842');
console.log('Instance status:', status.state);

List All Instances

const instances = await client.instances.list();
console.log('Total instances:', instances.instances.length);

Reconnect Instance

const result = await client.instances.reconnect('971582354842');
console.log('Reconnected:', result.success);

Delete Instance

await client.instances.delete('971582354842', {
  logout: true // optional: logout before deleting
});

Sending Messages

Text Message

await client.messages.sendText({
  from: '971582354842',
  to: '971521128878',
  text: 'Hello from WhatsHub!'
});

Image Message

await client.messages.sendImage({
  from: '971582354842',
  to: '971521128878',
  imageUrl: 'https://example.com/image.jpg',
  caption: 'Check out this image!' // optional
});

Document Message

await client.messages.sendDocument({
  from: '971582354842',
  to: '971521128878',
  documentUrl: 'https://example.com/document.pdf',
  filename: 'report.pdf', // optional
  caption: 'Monthly report' // optional
});

Video Message

await client.messages.sendVideo({
  from: '971582354842',
  to: '971521128878',
  videoUrl: 'https://example.com/video.mp4',
  caption: 'Watch this!' // optional
});

Utilities

Phone Number Validation

import { validatePhoneNumber, normalizePhoneNumber } from 'whatshub-sdk';

// Validate phone number
if (validatePhoneNumber('971582354842')) {
  console.log('Valid phone number');
}

// Normalize phone number (removes spaces, dashes, etc.)
const normalized = normalizePhoneNumber('+971 58 235 4842');
console.log(normalized); // '971582354842'

Error Handling

import { WhatsHubClient, ApiError } from 'whatshub-sdk';

try {
  await client.messages.sendText({
    from: '971582354842',
    to: '971521128878',
    text: 'Hello!'
  });
} catch (error) {
  if (error instanceof ApiError) {
    console.error('API Error:', error.message);
    console.error('Status Code:', error.statusCode);
    console.error('Response:', error.response);
  }
}

API Reference

Client Configuration

| Option | Type | Required | Default | Description | |--------|------|----------|---------|-------------| | baseUrl | string | Yes | - | Base URL of the WhatsHub API server | | apiToken | string | Yes | - | API authentication token | | timeout | number | No | 30000 | Request timeout in milliseconds |

Instance Methods

• client.instances.create(request) - Create a new WhatsApp instance
• client.instances.getStatus(phoneNumber) - Get instance status
• client.instances.list() - List all instances
• client.instances.reconnect(phoneNumber) - Reconnect an instance
• client.instances.delete(phoneNumber, options?) - Delete an instance

Message Methods

• client.messages.sendText(request) - Send text message
• client.messages.sendImage(request) - Send image message
• client.messages.sendDocument(request) - Send document message
• client.messages.sendVideo(request) - Send video message

Health Check

• client.getStatus() - Get server health status

Development

Setup

yarn install

Build

yarn build

Test

yarn test

Development Mode

yarn dev

Type Checking

yarn typecheck

Requirements

• Node.js 18.x or higher
• WhatsHub API server running

License

MIT