feat: implement Asterisk Manager Interface (AMI) client with core functionality including actions, events, and responses

Author: civilcoder55

package.json

@@ -9,7 +9,8 @@
     "dist"
   ],
   "scripts": {
-    "build": "tsup"
+    "build": "tsup",
+    "watch": "tsup --watch"
   },
   "keywords": [
     "asterisk",

src/action.ts

@@ -0,0 +1,43 @@
+import { Message } from "./message";
+
+/**
+ * Action ID generator function.
+ * Implements a closure to maintain a sequential counter for generating unique Action IDs.
+ * Ensures each action sent to Asterisk AMI has a unique identifier.
+ */
+const ActionUniqueId = (function () {
+  let nextId = 0;
+  return function () {
+    return nextId++;
+  };
+})();
+
+/**
+ * Base action class for all AMI actions.
+ * Represents a command to be sent to the Asterisk Manager Interface.
+ * Every action sent to AMI extends this class to implement specific AMI operations.
+ * Automatically assigns a unique ActionID to each instance for tracking responses.
+ *
+ * @extends Message
+ */
+export class Action extends Message {
+  /** ActionID field for AMI - string representation of the ID */
+  ActionID!: string;
+  /** Internal unique identifier for tracking */
+  protected id: number;
+  /** The name of the action to be performed by AMI */
+  protected Action!: string;
+
+  /**
+   * Creates a new Action with the specified name.
+   * Automatically assigns a unique Action ID.
+   *
+   * @param {String} name - The action name (e.g., "Login", "Status", "Ping")
+   */
+  constructor(name: string) {
+    super();
+    this.id = ActionUniqueId();
+    this.ActionID = String(this.id);
+    this.Action = name;
+  }
+}

src/actions/CoreShowChannels.ts

@@ -0,0 +1,16 @@
+import { Action } from "../action";
+
+/**
+ * CoreShowChannels Action for listing all active channels.
+ * Provides detailed information about all currently active channels in the system.
+ *
+ * @extends Action
+ */
+export class CoreShowChannels extends Action {
+  /**
+   * Creates a new CoreShowChannels action.
+   */
+  constructor() {
+    super("CoreShowChannels");
+  }
+}

src/actions/CustomAction.ts

@@ -0,0 +1,29 @@
+import { Action } from "../action";
+
+/**
+ * CustomAction for executing arbitrary AMI actions.
+ * Allows dynamic creation of any AMI action not explicitly defined as a class.
+ *
+ * @extends Action
+ */
+export class CustomAction extends Action {
+  /**
+   * Creates a new custom AMI action with the specified name and parameters.
+   *
+   * @param {Object} options - Action configuration
+   * @param {string} options.name - The name of the AMI action
+   * @param {Record<string, string | number | boolean>} [options.params] - Optional parameters for the action
+   */
+  constructor({
+    name,
+    params,
+  }: {
+    name: string;
+    params?: Record<string, any>;
+  }) {
+    super(name);
+    if (params) {
+      Object.assign(this, params);
+    }
+  }
+}

src/actions/Hangup.ts

@@ -0,0 +1,26 @@
+import { Action } from "../action";
+
+/**
+ * Hangup Action for terminating an active channel.
+ * Allows administrative termination of calls in progress.
+ *
+ * @extends Action
+ */
+export class Hangup extends Action {
+  /** The name of the channel to hang up */
+  protected Channel: string;
+  /** The numeric hangup cause. */
+  protected Cause?: string;
+
+  /**
+   * Creates a new Hangup action.
+   *
+   * @param {string} channel - The name of the channel to hang up
+   * @param {string} cause - The numeric hangup cause (e.g., "16" for Normal Clearing, "17" for User Busy)
+   */
+  constructor(channel: string, cause?: string) {
+    super("Hangup");
+    this.Channel = channel;
+    this.Cause = cause;
+  }
+}

src/actions/Login.ts

@@ -0,0 +1,26 @@
+import { Action } from "../action";
+
+/**
+ * Login Action for authenticating with the Asterisk Manager Interface.
+ * Required as the first action when establishing a new AMI session.
+ *
+ * @extends Action
+ */
+export class Login extends Action {
+  /** Username for authentication with AMI */
+  protected readonly Username: string;
+  /** Password for authentication with AMI */
+  protected readonly Secret: string;
+
+  /**
+   * Creates a new Login action with the specified credentials.
+   *
+   * @param {string} username - AMI username
+   * @param {string} secret - AMI password or secret
+   */
+  constructor(username: string, secret: string) {
+    super("Login");
+    this.Username = username;
+    this.Secret = secret;
+  }
+}

src/actions/Logoff.ts

@@ -0,0 +1,16 @@
+import { Action } from "../action";
+
+/**
+ * Logoff Action for terminating an AMI session.
+ * Closes the manager connection and stops event generation.
+ *
+ * @extends Action
+ */
+export class Logoff extends Action {
+  /**
+   * Creates a new Logoff action.
+   */
+  constructor() {
+    super("Logoff");
+  }
+}

src/actions/Ping.ts

@@ -0,0 +1,16 @@
+import { Action } from "../action";
+
+/**
+ * Ping Action for testing connectivity with the Asterisk server.
+ * Useful for keeping the connection alive and verifying server responsiveness.
+ *
+ * @extends Action
+ */
+export class Ping extends Action {
+  /**
+   * Creates a new Ping action.
+   */
+  constructor() {
+    super("Ping");
+  }
+}

src/actions/Status.ts

@@ -0,0 +1,33 @@
+import { Action } from "../action";
+
+/**
+ * Status Action for obtaining detailed information about channels.
+ * When used without a channel parameter, returns information on all active channels.
+ * When specified with a channel, returns detailed status for only that channel.
+ *
+ * @extends Action
+ */
+export class Status extends Action {
+  /** Optional channel name to get status for (omit for all channels) */
+  protected readonly Channel?: string;
+  /** Optional variables to include in the response */
+  protected readonly Variables?: string;
+  /** Optional flag to include all variables */
+  protected readonly AllVariables?: boolean;
+
+  /**
+   * Creates a new Status action.
+   *
+   * @param {string} channel - The name of the channel to get status for
+   * @param {string[]} variables - The variables to include in the response
+   * @param {boolean} allVariables - Whether to include all variables
+   */
+  constructor(channel?: string, variables?: string[], allVariables?: boolean) {
+    super("Status");
+
+    if (channel) this.Channel = channel;
+    if (variables) this.Variables = variables.join(",");
+
+    if (allVariables !== undefined) this.AllVariables = !!allVariables;
+  }
+}

src/actions/index.ts

@@ -0,0 +1,7 @@
+export { Logoff } from "./Logoff";
+export { Login } from "./Login";
+export { Ping } from "./Ping";
+export { CoreShowChannels } from "./CoreShowChannels";
+export { Status } from "./Status";
+export { Hangup } from "./Hangup";
+export { CustomAction } from "./CustomAction";