asterisk-ami-client
Version:
Asterisk AMI Client for NodeJS (ES2015)
284 lines (219 loc) • 8.92 kB
Markdown
# Asterisk AMI Client for NodeJS (ES2015)
[](https://travis-ci.org/BelirafoN/asterisk-ami-client)
[](https://coveralls.io/github/BelirafoN/asterisk-ami-client?branch=master)
[](https://codeclimate.com/github/BelirafoN/asterisk-ami-client)
[](https://badge.fury.io/js/asterisk-ami-client)
Full functionality client for Asterisk's AMI. Support any data packages (action/event/response/custom responses) from AMI;
With this client you can select you'r own case of programming interactions with Asterisk AMI.
If you like events & handlers - you can use it!
If you like promises - you can use it!
If you like `co` & sync-style of code - you can use it!
1. [Install](#install)
2. [Usage](#usage)
* [Example 1](#example-1)
* [Example 2](#example-2)
* [Example 3](#example-3)
* [Example 4](#example-4)
* [Example 5](#example-5)
3. [More examples](#more-examples)
4. [Docs & internal details](#docs--internal-details)
* [Events](#events)
* [Client's parameters](#clients-parameters)
* [Methods](#methods)
* [Properties](#properties)
5. [Tests](#tests)
6. [License](#license)
## Install
```bash
$ npm i asterisk-ami-client
```
## NodeJS versions
support `>=4.0.0`
## Usage
It is only some usage cases.
#### Example 1:
Listening all events on instance of client;
```javascript
const AmiClient = require('asterisk-ami-client');
let client = new AmiClient();
client.connect('user', 'secret', {host: 'localhost', port: 5038})
.then(amiConnection => {
client
.on('connect', () => console.log('connect'))
.on('event', event => console.log(event))
.on('data', chunk => console.log(chunk))
.on('response', response => console.log(response))
.on('disconnect', () => console.log('disconnect'))
.on('reconnection', () => console.log('reconnection'))
.on('internalError', error => console.log(error))
.action({
Action: 'Ping'
});
setTimeout(() => {
client.disconnect();
}, 5000);
})
.catch(error => console.log(error));
```
#### Example 2:
Receive Asterisk's AMI responses with promise-chunk.
```javascript
const AmiClient = require('asterisk-ami-client');
let client = new AmiClient({reconnect: true});
client.connect('username', 'secret', {host: '127.0.0.1', port: 5038})
.then(() => { // any action after connection
return client.action({Action: 'Ping'}, true);
})
.then(response1 => { // response of first action
console.log(response1);
})
.then(() => { // any second action
return client.action({Action: 'Ping'}, true);
})
.then(response2 => { // response of second action
console.log(response2)
})
.catch(error => error)
.then(error => {
client.disconnect(); // disconnect
if(error instanceof Error){ throw error; }
});
```
or with `co`-library for sync-style of code
#### Example 3:
Receive Asterisk's AMI responses with `co`.
```javascript
const AmiClient = require('asterisk-ami-client');
const co = require('co');
let client = new AmiClient({reconnect: true});
co(function* (){
yield client.connect('username', 'secret', {host: '127.0.0.1', port: 5038});
let response1 = yield client.action({Action: 'Ping'}, true);
console.log(response1);
let response2 = yield client.action({Action: 'Ping'}, true);
console.log(response2);
client.disconnect();
}).catch(error => console.log(error));
```
#### Example 4:
Listening `event` and `response` events on instance of client.
```javascript
const AmiClient = require('asterisk-ami-client');
let client = new AmiClient({
reconnect: true,
keepAlive: true
});
client.connect('user', 'secret', {host: 'localhost', port: 5038})
.then(() => {
client
.on('event', event => console.log(event))
.on('response', response => {
console.log(response);
client.disconnect();
})
.on('internalError', error => console.log(error));
client.action({Action: 'Ping'});
})
.catch(error => console.log(error));
```
### Example 5:
Emit events by names and emit of response by `resp_${ActionID}`
(if ActionID is set in action's data package).
```javascript
const AmiClient = require('asterisk-ami-client');
let client = new AmiClient({
reconnect: true,
keepAlive: true,
emitEventsByTypes: true,
emitResponsesById: true
});
client.connect('user', 'secret', {host: 'localhost', port: 5038})
.then(() => {
client
.on('Dial', event => console.log(event))
.on('Hangup', event => console.log(event))
.on('Hold', event => console.log(event))
.on('Bridge', event => console.log(event))
.on('resp_123', response => {
console.log(response);
client.disconnect();
})
.on('internalError', error => console.log(error));
client.action({
Action: 'Ping',
ActionID: 123
});
})
.catch(error => console.log(error));
```
## More examples
For more examples, please, see `./examples/*`.
## Docs & internal details
### Events
* `connect` - emits when client was connected;
* `event` - emits when was received a new event of Asterisk;
* `data` - emits when was received a new chunk of data form the Asterisk's socket;
* `response` - emits when was received a new response of Asterisk;
* `disconnect` - emits when client was disconnected;
* `reconnection` - emits when client tries reconnect to Asterisk;
* `internalError` - emit when happens something very bad. Like a disconnection from Asterisk and etc;
* `${eventName}` - emits when was received event with name `eventName` of Asterisk and parameter `emitEventsByTypes` was set to `true`. [See example 5](#example-5);
* `${resp_ActionID}` - emits when was received response with `ActionID` of Asterisk and parameter `emitResponsesById` was set to `true`. [See example 5](#example-5).
### Client's parameters
Default values:
```javascript
{
reconnect: false,
maxAttemptsCount: 30,
attemptsDelay: 1000,
keepAlive: false,
keepAliveDelay: 1000,
emitEventsByTypes: true,
eventTypeToLowerCase: false,
emitResponsesById: true,
dontDeleteSpecActionId: false,
addTime: false,
eventFilter: null // filter disabled
}
```
* `reconnect` - auto reconnection;
* `maxAttemptsCount` - max count of attempts when client tries to reconnect to Asterisk;
* `attemptsDelay` - delay (ms) between attempts of reconnection;
* `keepAlive` - when is `true`, client send `Action: Ping` to Asterisk automatic every minute;
* `keepAliveDelay` - delay (ms) between keep-alive actions, when parameter `keepAlive` was set to `true`;
* `emitEventsByTypes` - when is `true`, client will emit events by names. See [example 5](#example-5);
* `eventTypeToLowerCase` - when is `true`, client will emit events by names in lower case. Uses with `emitEventsByTypes`;
* `emitResponsesById` - when is `true` and data package of action has ActionID field, client will emit responses by `resp_ActionID`. See [example 5](#example-5);
* `dontDeleteSpecActionId` - when is `true`, client will not hide generated ActionID field in responses;
* `addTime` - when is `true`, client will be add into events and responses field `$time` with value equal to ms-timestamp;
* `eventFilter` - object, array or Set with names of events, which will be ignored by client.
### Methods
* `.connect(username, secret[, options])` - connect to Asterisk. See [examples](#usage);
* `.disconnect()` - disconnect from Asterisk;
* `.action(message)` - send new action to Asterisk;
* `.write(message)` - alias of `action` method;
* `.send(message)` - alias of `action` method;
* `.option(name[, value])` - get or set option of client;
* `.options([newOptions])` - get or set all options of client.
### Properties
Getters
* `lastEvent` - last event, which was receive from Asterisk;
* `lastResponse` - last response which was receive from Asterisk;
* `isConnected` - status of current connection to Asterisk;
* `lastAction` - last action data which was transmitted to Asterisk;
* `connection` - get current amiConnection.
## Tests
Tests require [Mocha](https://mochajs.org/).
```bash
mocha ./tests
```
or with `npm`
```bash
npm test
```
Test coverage with [Istanbul](https://gotwarlost.github.io/istanbul/)
```bash
npm run coverage
```
## License
Licensed under the MIT License