ippanel-node-sdk/README.md

Node.js SDK for ippanel API

# ippanel Node.js SDK

A Node.js SDK for interacting with the ippanel API to send various types of SMS messages.

## Installation

Install the SDK using npm:

```bash
npm install ippanel-node-sdk
```

Or using yarn:

```bash
yarn add ippanel-node-sdk
```

## Usage

### Creating a Client

First, import and instantiate the client with your API key:

```javascript
// Using CommonJS
const { createClient } = require('ippanel-node-sdk');
const client = createClient('YOUR_API_KEY');

// Or using ES Modules
import { createClient } from 'ippanel-node-sdk';
const client = createClient('YOUR_API_KEY');

// Alternatively, you can use the Client class directly
const { Client } = require('ippanel-node-sdk');
const client = new Client('YOUR_API_KEY');
```

### Sending a Web Service Message

Send a simple message to one or more recipients:

```javascript
client.sendWebservice(
  'Hello from ippanel!', 
  '+983000505', // sender number
  ['+989123456789', '+989356789012'] // recipient numbers
)
  .then(response => console.log('Message sent:', response))
  .catch(error => console.error('Error sending message:', error));
```

### Sending a Pattern Message

Send a message using a predefined pattern:

```javascript
client.sendPattern(
  'YOUR_PATTERN_CODE',
  '+983000505', // sender number
  '+989123456789', // recipient number
  { 
    param1: 'value1',
    param2: 'value2'
  } // pattern parameters
)
  .then(response => console.log('Pattern message sent:', response))
  .catch(error => console.error('Error sending pattern message:', error));
```

### Sending a VOTP (Verification OTP) Message

Send a verification OTP message:

```javascript
client.sendVOTP(
  123456, // OTP code
  '+989123456789' // recipient number
)
  .then(response => console.log('VOTP message sent:', response))
  .catch(error => console.error('Error sending VOTP message:', error));
```

### Using async/await

All methods return promises and can be used with async/await:

```javascript
async function sendMessages() {
  try {
    // Send a web service message
    const webResult = await client.sendWebservice(
      'Hello from ippanel!', 
      '+983000505', 
      ['+989123456789']
    );
    console.log('Web service result:', webResult);
    
    // Send a pattern message
    const patternResult = await client.sendPattern(
      'PATTERN_CODE', 
      '+983000505', 
      '+989123456789', 
      { name: 'John', code: '12345' }
    );
    console.log('Pattern result:', patternResult);
    
    // Send a VOTP message
    const votpResult = await client.sendVOTP(123456, '+989123456789');
    console.log('VOTP result:', votpResult);
  } catch (error) {
    console.error('Error sending messages:', error);
  }
}
```

## Configuration & Customization

### Custom Base URL

You can specify a custom base URL when creating the client:

```javascript
const client = createClient('YOUR_API_KEY', 'https://custom-api.example.com/v1/api');
```

### Custom HTTP Client

You can customize the HTTP client settings:

```javascript
const axios = require('axios');
const { createClient } = require('ippanel-node-sdk');

const client = createClient('YOUR_API_KEY');

// Create custom axios instance
const customAxios = axios.create({
  timeout: 30000, // 30 seconds timeout
  headers: {
    'Authorization': client.apiKey,
    'Content-Type': 'application/json',
    'User-Agent': 'My Custom App'
  }
});

// Set the custom HTTP client
client.setHttpClient(customAxios);
```

## Error Handling

The SDK throws meaningful errors that you can catch and handle:

```javascript
client.sendWebservice('Test message', '+983000505', ['+989123456789'])
  .then(response => {
    console.log('Success:', response);
  })
  .catch(error => {
    if (error.message.includes('API Error:')) {
      console.error('API returned an error:', error.message);
    } else if (error.message === 'No response received from the API') {
      console.error('Network or timeout issue');
    } else {
      console.error('Unexpected error:', error.message);
    }
  });
```

## Response Structure

Successful responses have the following structure:

```javascript
{
  data: {
    // Response data specific to the API endpoint
  },
  meta: {
    status: true,
    message: "Operation successful",
    message_parameters: [],
    message_code: "success"
  }
}
```

## TypeScript Support

The SDK includes TypeScript definitions for improved development experience with TypeScript.

```typescript
import { createClient, SendResponse } from 'ippanel-node-sdk';

const client = createClient('YOUR_API_KEY');

async function sendSMS(): Promise<SendResponse> {
  return client.sendWebservice('Hello', '+983000505', ['+989123456789']);
}
```

## License

MIT