Package Exports

@catalisa/wpp-sdk
@catalisa/wpp-sdk/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@catalisa/wpp-sdk) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@wpp/sdk

TypeScript SDK for WhatsApp Multi-tenant API - Clean, type-safe, and easy to use.

Installation

npm install @wpp/sdk
# or
yarn add @wpp/sdk

Quick Start

Admin Client (JWT Authentication)

import { WhatsAppAPIClient } from '@wpp/sdk';

const admin = new WhatsAppAPIClient({
  baseURL: 'https://api.example.com'
});

// Login
const { access_token, user } = await admin.login('admin@example.com', 'password');
console.log('Logged in as:', user.email);

// Create tenant
const tenant = await admin.tenants.create({ name: 'Acme Corp' });

// Create API token for tenant
const token = await admin.apiTokens.create(tenant.id, {
  name: 'Production Token',
  isTest: false
});
console.log('API Key:', token.key); // Store this securely!

// Connect device for tenant
await admin.whatsappAdmin.connect(tenant.id);

// Get QR code
const { qr } = await admin.whatsappAdmin.getQR(tenant.id);
console.log('Scan this QR:', qr);

User Client (API Token Authentication)

import { WhatsAppAPIClient } from '@wpp/sdk';

const client = new WhatsAppAPIClient({
  baseURL: 'https://api.example.com',
  auth: {
    type: 'apiToken',
    token: 'wpp_live_abc123_xyz789'
  }
});

// Connect session
const { correlationId } = await client.whatsapp.connect({
  callbackUrl: 'https://myapp.com/webhook'
});

// Send message
await client.whatsapp.sendMessage({
  jid: '5511999999999@s.whatsapp.net',
  text: 'Hello from SDK!'
});

// Send media
await client.whatsapp.sendMedia({
  jid: '5511999999999@s.whatsapp.net',
  type: 'image',
  url: 'https://example.com/photo.jpg',
  caption: 'Check this out!'
});

// List groups
const groups = await client.whatsapp.listGroups('tenant-id');
console.log('Groups:', groups);

Features

✨ Resource-Based API

Clean, intuitive API organized by domain:

client.auth          // Authentication
client.users         // User management (admin)
client.tenants       // Tenant management (admin)
client.apiTokens     // API token management (admin)
client.whatsapp      // WhatsApp operations (API token auth)
client.whatsappAdmin // WhatsApp admin operations (JWT auth)
client.webhooks      // Webhook management
client.branding      // Branding customization
client.health        // Health check

🔒 Dual Authentication Support

JWT (Admin endpoints)

const client = new WhatsAppAPIClient({
  baseURL: 'https://api.example.com',
  auth: { type: 'jwt', token: 'your-jwt-token' }
});

// Or login to get token automatically
await client.login('admin@example.com', 'password');

API Token (WhatsApp endpoints)

const client = new WhatsAppAPIClient({
  baseURL: 'https://api.example.com',
  auth: { type: 'apiToken', token: 'wpp_live_xxx' }
});

📝 Full TypeScript Support

100% typed with IntelliSense support:

import { SendMessageRequest, Group, AdvancedWebhook } from '@wpp/sdk';

const message: SendMessageRequest = {
  jid: '5511999999999@s.whatsapp.net',
  text: 'Hello!',
  callbackUrl: 'https://myapp.com/callback'
};

⚠️ Comprehensive Error Handling

import { APIError, AuthError, ValidationError, NotFoundError } from '@wpp/sdk';

try {
  await client.whatsapp.send({ jid: 'invalid', text: 'test' });
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Validation failed:', error.errors);
  } else if (error instanceof AuthError) {
    console.error('Auth failed, status:', error.statusCode);
  } else if (error instanceof APIError) {
    console.error('API error:', error.message);
  }
}

Testing

The SDK includes comprehensive test suites demonstrating all features:

# Run all tests
npm run test:real          # Complete integration tests
npm run test:messaging     # Messaging operations only
npm run test:groups        # Group operations only
npm run test:tenant        # Specific tenant tests
npm run test:admin-crud    # Admin CRUD (users, tenants)
npm run test:branding      # Branding configuration
npm run test:webhooks      # Basic webhooks

# Or run directly
npx ts-node -r tsconfig-paths/register examples/test-real.ts
npx ts-node -r tsconfig-paths/register examples/test-messaging.ts
npx ts-node -r tsconfig-paths/register examples/test-groups.ts
npx ts-node -r tsconfig-paths/register examples/test-admin-crud.ts
npx ts-node -r tsconfig-paths/register examples/test-branding.ts
npx ts-node -r tsconfig-paths/register examples/test-basic-webhooks.ts

Test Coverage:

✅ Authentication (JWT + API Token)
✅ Admin CRUD Operations (users, tenants) - NEW!
✅ Admin Operations (API tokens)
✅ Messaging (text messages)
✅ Group Operations (create, update, lifecycle testing with polling)
✅ Advanced Webhooks (admin CRUD, filtering, logs, stats)
✅ Basic Webhooks (CRUD) - NEW!
✅ Device Management (connect, disconnect, reset)
✅ Branding Configuration (CRUD) - NEW!
⏭️ Media Operations (deferred to next phase)

Test Results:

Test File	Results	Coverage
`test-real.ts`	19/20 passing (95%)	Admin ops, webhooks, device mgmt
`test-messaging.ts`	7/10 passing (70%, 3 skipped)	Text messages, callbacks
`test-groups.ts`	21/22 passing (95.5%)	Complete group lifecycle
`test-specific-tenant.ts`	7/7 passing (100%)	Device operations
`test-admin-crud.ts`	17/17 passing (100%) 🆕	User & Tenant CRUD
`test-branding.ts`	6/6 passing (100%) 🆕	Branding config
`test-basic-webhooks.ts`	8/8 passing (100%) 🆕	Basic webhook CRUD

Total Coverage:

Endpoints Tested: 70/108 (64.8%) ⬆️ from 53.7%
Phase 1 Complete: +12 endpoints tested
All new tests: 100% passing 🎉

Test Highlights:

✅ Complete lifecycle testing with proper async operation polling
✅ Automatic cleanup with try/finally blocks
✅ Comprehensive CRUD coverage for admin resources
✅ Multi-webhook testing
✅ User-tenant integration testing

Improvements in test-groups.ts:

Added waitForOperation() helper to poll async operations until completion
Added checkDeviceReady() helper to verify device status before tests
Refactored both user and admin tests with proper polling and group ID extraction
Added try/finally cleanup blocks to ensure test groups are deleted
Complete lifecycle testing: create → update → verify → cleanup

Examples

Send Message with Callback

const { correlationId } = await client.whatsapp.sendMessage({
  jid: '5511999999999@s.whatsapp.net',
  text: 'Hello!',
  callbackUrl: 'https://myapp.com/callback',
  correlationId: 'my-custom-id-123'
});

// Later, check operation status
const operation = await client.whatsapp.getOperation(correlationId);
console.log('Status:', operation.status); // 'pending', 'completed', or 'failed'
console.log('Result:', operation.result);

Group Management

// Create group
const { correlationId } = await client.whatsapp.createGroup({
  subject: 'My Group',
  participants: ['5511111111111@s.whatsapp.net', '5522222222222@s.whatsapp.net']
});

const operation = await client.whatsapp.getOperation(correlationId);
const groupId = operation.result.gid;

// Update group subject
await client.whatsapp.updateGroupSubject({
  gid: groupId,
  subject: 'New Group Name'
});

// Add participants
await client.whatsapp.addGroupParticipants({
  gid: groupId,
  participants: ['5533333333333@s.whatsapp.net']
});

// Promote to admin
await client.whatsapp.promoteGroupParticipants({
  gid: groupId,
  participants: ['5533333333333@s.whatsapp.net']
});

Advanced Webhooks

// Create advanced webhook with filtering
const webhook = await client.webhooks.create({
  name: 'Group Messages Only',
  urls: ['https://api.example.com/webhook'],
  eventTypes: ['messages.upsert'],
  filters: {
    remoteJid: '120363XXX@g.us', // Specific group
    fromMe: false,                // Only incoming messages
    textContains: 'urgent'        // Only messages containing 'urgent'
  },
  secret: 'my-webhook-secret',
  retryCount: 3,
  timeoutMs: 10000
});

// Get webhook statistics
const stats = await client.webhooks.getStats(webhook.id);
console.log('Trigger count:', stats.triggerCount);
console.log('Success rate:', stats.successRate);
console.log('Avg response time:', stats.avgResponseTimeMs);

// Get delivery logs
const logs = await client.webhooks.getLogs(webhook.id, {
  success: false, // Only failed deliveries
  limit: 50
});

Admin Operations

// List all devices
const devices = await admin.whatsappAdmin.listDevices();

// Connect device for specific tenant
await admin.whatsappAdmin.connect('tenant-123');

// Send message as tenant
await admin.whatsappAdmin.sendMessage('tenant-123', {
  jid: '5511999999999@s.whatsapp.net',
  text: 'Admin sending message as tenant'
});

// Generate QR link for support
const qrLink = await admin.whatsappAdmin.generateQRLink('tenant-123', {
  expirationHours: 24
});
console.log('Share this link:', qrLink.url);

// Send QR link to user via WhatsApp
await admin.whatsappAdmin.sendQRLink('tenant-123', {
  recipientTenantId: 'tenant-456',
  recipientJid: '5511999999999@s.whatsapp.net'
});

Branding Customization

// Update branding for tenant
await admin.branding.update({
  tenantId: 'tenant-123',
  companyName: 'Acme Corp',
  primaryColor: '#FF5722',
  logoUrl: 'https://example.com/logo.png',
  headerMessage: 'Welcome to Acme Support',
  footerMessage: 'Powered by Acme Corp'
});

// Get public branding (no auth required)
const branding = await client.branding.get('tenant-123');

User Management

// Create user
const user = await admin.users.create({
  email: 'user@example.com',
  password: 'securepassword',
  role: 'user',
  tenantId: 'tenant-123'
});

// List all users
const users = await admin.users.list();

// Update user role
await admin.users.update(user.id, {
  role: 'admin'
});

// Delete user
await admin.users.delete(user.id);

Health Check

const health = await client.health.check();
console.log('API Status:', health.status); // 'ok'

Configuration

Advanced Configuration

const client = new WhatsAppAPIClient({
  baseURL: 'https://api.example.com',
  timeout: 60000, // 60 seconds (default: 30000)

  // Interceptors
  onRequest: async (config) => {
    console.log('Request:', config.method, config.url);
    return config;
  },

  onResponse: async (response) => {
    console.log('Response:', response.status);
    return response;
  },

  onError: (error) => {
    console.error('API Error:', error.message);
  }
});

Dynamic Auth Updates

const client = new WhatsAppAPIClient({
  baseURL: 'https://api.example.com'
});

// Login and set JWT
await client.login('admin@example.com', 'password');

// Switch to API token
client.setAuth('wpp_live_abc123', 'apiToken');

// Clear auth
client.clearAuth();

API Reference

Authentication

auth.login(email, password) - Login with credentials
auth.forgotPassword(email) - Request password reset
auth.resetPassword(token, newPassword) - Reset password
auth.me() - Get current user

Users (Admin)

users.list() - List all users
users.get(id) - Get user by ID
users.create(data) - Create user
users.update(id, data) - Update user
users.delete(id) - Delete user

Tenants (Admin)

tenants.list() - List all tenants
tenants.get(id) - Get tenant by ID
tenants.create(data) - Create tenant
tenants.update(id, data) - Update tenant
tenants.delete(id) - Delete tenant

API Tokens (Admin)

apiTokens.list(tenantId) - List tokens
apiTokens.create(tenantId, data) - Create token
apiTokens.delete(tenantId, tokenId) - Delete token

WhatsApp (User)

Session: connect(), reconnect(), reset(), logout(), ping()
Messaging: sendMessage(), sendReaction(), sendMedia()
Groups: createGroup(), updateGroupSubject(), addGroupParticipants(), etc.
Queries: listGroups(), listChats(), listContacts(), getOperation()

WhatsApp Admin

Device: listDevices(), getDevice(), getQR()
Session: connect(), reconnect(), disconnect(), reset(), ping()
Operations: sendMessage(), getOperation()
Groups: listGroups(), createGroup(), manageGroupParticipants(), etc.

Webhooks

Basic: createBasic(), listBasic(), deleteBasic()
Advanced (Admin): createAdvanced(), listAdvanced(), updateAdvanced(), deleteAdvanced()
Advanced (User): create(), list(), update(), delete()
Logs & Stats: getLogs(), getStats()

Branding

get(tenantId) - Get branding (public)
update(data) - Update branding (admin)
delete(tenantId) - Delete branding (admin)

Health

check() - Health check

Error Types

APIError - Base API error
AuthError - Authentication/authorization errors (401, 403)
ValidationError - Validation errors (400, 422)
NotFoundError - Not found errors (404)
RateLimitError - Rate limit errors (429)
NetworkError - Network/connection errors

License

MIT

Support

For issues and questions, visit the GitHub repository.