ami-bridge

Asterisk Manager Interface (AMI) client for Node.js, written in TypeScript and distributed as CommonJS.

Features

• AMI client for Node.js (CommonJS + TypeScript, Node >= 18).
• High-level API for common AMI actions (Ping, CoreStatus, QueueStatus, SIPPeers, etc.).
• Built-in CLI (ami-bridge) for quick inspection and event dumps.
• Test suite with Vitest and V8-based coverage (ready for Codecov).

Installation

npm install ami-bridge

Requires Node.js >= 18.

Usage (TypeScript / ESM consumers)

import { createClient, Actions } from 'ami-bridge';

const client = createClient({
  host: '127.0.0.1',
  port: 5038,
  login: 'admin',
  password: 'admin',
});

client.connect();

client.send(new Actions.Ping(), (err, data) => {
  if (err) {
    console.error('PING error:', err);
  } else {
    console.log('PING response:', data);
  }
});

More complete example handling connection lifecycle and multiple actions:

import { createClient, Actions } from 'ami-bridge';

const amibridge = createClient({
  host: '127.0.0.1',
  port: 5038,
  login: 'admin',
  password: 'admin',
});

amibridge.on('incorrectServer', () => {
  amibridge.logger.error('Invalid AMI welcome message. Are you sure if this is AMI?');
  process.exit(1);
});

amibridge.on('connectionRefused', () => {
  amibridge.logger.error('Connection refused.');
  process.exit(1);
});

amibridge.on('incorrectLogin', () => {
  amibridge.logger.error('Incorrect login or password.');
  process.exit(1);
});

amibridge.on('event', (event) => {
  amibridge.logger.info('event:', event);
});

amibridge.on('connected', () => {
  setTimeout(() => {
    amibridge.on('disconnected', () => {
      process.exit(0);
    });

        // Promise-based API is also available via sendAsync:
    amibridge.sendAsync(new Actions.QueueStatus())
      .then((res) => amibridge.logger.info('QueueStatus:', res))
      .catch((err) => amibridge.logger.error('QueueStatus error:', err));

    amibridge.send(new Actions.Ping(), (errPing, resPing) => {
      if (errPing) {
        amibridge.logger.error('Ping error:', errPing);
      } else {
        amibridge.logger.info('Ping response:', resPing);
      }
      amibridge.disconnect();
    });
  }, 10000);
});

amibridge.connect();

Public API from the ami-bridge package (entrypoint dist/index.js): Client, createClient, Actions, Action, Event, Response, Logger, SilentLogger.

Usage (CJS)

const { createClient, Actions } = require('ami-bridge');

const client = createClient({
  host: '127.0.0.1',
  port: 5038,
  login: 'admin',
  password: 'admin',
});

client.connect();

client.send(new Actions.Ping(), (err, data) => {
  if (err) {
    console.error('PING error:', err);
  } else {
    console.log('PING response:', data);
  }
});

CLI

A CLI bin ami-bridge is included:

npx ami-bridge <user> <password> [host[:port]] [-h host] [-p port] [-f eventsFile]

Example:

npx ami-bridge admin admin 127.0.0.1:5038

Options:

• -h: AMI host (default 127.0.0.1)
• -p: AMI port (default 5038)
• -f: saves received events to a JSON file

Examples

The example/ folder has runnable scripts against a real Asterisk instance (CJS, requires ami-bridge installed locally via file:..):

• basic-usage.js — connect, send several actions (Ping, CoreStatus, Status, Hangup, QueueStatus, Command) with callbacks, auto-disconnect after 10s.
• async-await.js — same idea using sendAsync() / await instead of callbacks.
• events.js — listen for event, rawEvent, and rawEvent.<Name> (Hangup, Newchannel, VarSet), periodic Ping keepalive, clean shutdown on SIGINT.

Run:

cd example
npm install
node basic-usage.js    # or async-await.js / events.js

Edit the host/login/password fields in each script to match your Asterisk Manager config (manager.conf).

Development

npm run build
npm run lint
npm test

Generate lcov coverage:

npm run coverage:lcov

License

MIT