npm package: @fastmsg/sdk
Description: JavaScript/TypeScript SDK for FastMsg.io WhatsApp API
Author: FastMsg.io
Latest version: 1.0.0

# FastMsg JavaScript/TypeScript SDK

JavaScript/TypeScript SDK for interacting with FastMsg.io WhatsApp API. This SDK allows you to control a single WhatsApp instance programmatically.

## Installation

```bash
npm install @fastmsg/sdk
```

Or using yarn:

```bash
yarn add @fastmsg/sdk
```

## Quick Start

```typescript
import { FastMsgClient } from '@fastmsg/sdk';

// Initialize client with your instance credentials
const client = new FastMsgClient({
  baseUrl: 'https://api.fastmsg.io',
  instanceId: 'your-instance-id',
  instanceToken: 'your-instance-token'
});

// Send a text message
const response = await client.messages.sendText({
  number: '963930928165',
  text: 'Hello from JavaScript!'
});

console.log(response);
```

## Configuration

### Environment Variables

You can set the API base URL using an environment variable:

```bash
export FASTMSG_API_URL="https://api.fastmsg.io"
```

Then initialize the client without `baseUrl`:

```typescript
const client = new FastMsgClient({
  instanceId: 'your-instance-id',
  instanceToken: 'your-instance-token'
});
```

## Usage Examples

### Instance Management

```typescript
// Get QR code for connection
const qrCode = await client.getQRCode();
console.log(`QR Code: ${qrCode}`);

// Check connection state
const state = await client.getConnectionState();
console.log(`Connection state:`, state);

// Restart instance
await client.restart();

// Set presence
await client.setPresence('available'); // or 'unavailable'

// Logout instance
await client.logout();
```

### Sending Messages

```typescript
// Send text message
await client.messages.sendText({
  number: '963930928165',
  text: 'Hello World!'
});

// Send image
await client.messages.sendMedia({
  number: '963930928165',
  mediaUrl: 'https://example.com/image.jpg',
  caption: 'Check out this image!'
});

// Send location
await client.messages.sendLocation({
  number: '963930928165',
  latitude: 33.5138,
  longitude: 36.2765,
  name: 'Damascus'
});

// Send contact
await client.messages.sendContact({
  number: '963930928165',
  contactData: {
    name: 'John Doe',
    number: '963930928165'
  }
});

// Send buttons
await client.messages.sendButtons({
  number: '963930928165',
  text: 'Choose an option:',
  buttons: [
    { id: '1', text: 'Option 1' },
    { id: '2', text: 'Option 2' }
  ]
});
```

### Settings Management

```typescript
// Get current settings
const settings = await client.settings.getSettings();
console.log(settings);

// Update settings
await client.settings.updateSettings({
  readMessages: true,
  readStatus: true,
  alwaysOnline: true
});

// Set webhook
await client.settings.setWebhook({
  url: 'https://your-server.com/webhook',
  enabled: true,
  events: ['messages.upsert', 'messages.update']
});
```

## Error Handling

```typescript
import { FastMsgClient } from '@fastmsg/sdk';

try {
  const client = new FastMsgClient({
    instanceId: 'invalid-id',
    instanceToken: 'invalid-token'
  });
  await client.messages.sendText({ number: '123', text: 'Hello' });
} catch (error: any) {
  if (error.message.includes('Authentication failed')) {
    console.error('Authentication failed');
  } else {
    console.error('API error:', error.message);
  }
}
```

## TypeScript Support

This SDK is written in TypeScript and includes full type definitions. All types are exported for your convenience:

```typescript
import {
  FastMsgClient,
  FastMsgClientConfig,
  SendTextParams,
  Settings,
  WebhookConfig
} from '@fastmsg/sdk';
```

## API Reference

### FastMsgClient

Main client class for interacting with the API.

#### Constructor

```typescript
new FastMsgClient(config: FastMsgClientConfig)
```

#### Instance Methods

- `getQRCode(): Promise<string>` - Get QR code for connection
- `getConnectionState(): Promise<ConnectionState>` - Get connection state
- `connect(): Promise<string>` - Connect instance (alias for getQRCode)
- `restart(): Promise<FastMsgResponse>` - Restart the instance
- `logout(): Promise<FastMsgResponse>` - Logout and disconnect
- `setPresence(presence: 'available' | 'unavailable'): Promise<FastMsgResponse>` - Set presence status

### Messages

Message sending methods (accessed via `client.messages`).

- `sendText(params: SendTextParams): Promise<FastMsgResponse>`
- `sendMedia(params: SendMediaParams): Promise<FastMsgResponse>`
- `sendSticker(number: string, stickerUrl: string): Promise<FastMsgResponse>`
- `sendLocation(params: SendLocationParams): Promise<FastMsgResponse>`
- `sendContact(params: SendContactParams): Promise<FastMsgResponse>`
- `sendButtons(params: SendButtonsParams): Promise<FastMsgResponse>`
- `sendList(params: SendListParams): Promise<FastMsgResponse>`

### Settings

Settings management methods (accessed via `client.settings`).

- `getSettings(): Promise<Settings>` - Get current settings
- `updateSettings(settings: Partial<Settings>): Promise<FastMsgResponse>` - Update settings
- `setWebhook(config: WebhookConfig): Promise<FastMsgResponse>` - Set webhook
- `getWebhook(): Promise<WebhookConfig>` - Get webhook configuration

## Building from Source

```bash
git clone https://github.com/fastmsg/fastmsg-js-sdk.git
cd fastmsg-js-sdk
npm install
npm run build
```

## License

MIT License

## Support

For issues and questions, please visit [https://docs.fastmsg.io](https://docs.fastmsg.io) or open an issue on GitHub.