@per_moeller/asterisk-ari 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Per Moeller
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,291 @@
+# @per_moeller/asterisk-ari
+
+Modern TypeScript client for Asterisk ARI (Asterisk REST Interface). A drop-in replacement for the outdated `ari-client` package with full TypeScript support, aggressive WebSocket reconnection, and support for Asterisk 16-23.
+
+## Features
+
+- **Modern TypeScript** - Full type definitions, async/await, Promises
+- **Asterisk 16-23 support** - Automatic version detection with compatibility layer
+- **Complete ARI API** - All 11 REST resources with 100+ endpoints
+- **Robust WebSocket** - Aggressive reconnection with exponential backoff
+- **Event system** - Listen to events on resource instances (like ari-client)
+- **Connection pooling** - Built-in pool for high-throughput scenarios
+- **Request queue** - Automatic retry with circuit breaker pattern
+- **Node.js 20+** - Uses native fetch, no external HTTP dependencies
+
+## Installation
+
+```bash
+npm install @per_moeller/asterisk-ari
+```
+
+## Quick Start
+
+```typescript
+import { connect } from '@per_moeller/asterisk-ari';
+
+const client = await connect({
+  url: 'http://localhost:8088',
+  username: 'asterisk',
+  password: 'asterisk',
+  app: 'my-app',
+});
+
+console.log('Connected to', client.version.toString());
+
+// Create a channel instance
+const channel = client.Channel();
+
+// Register events BEFORE originating
+channel.on('StasisStart', async (event, ch) => {
+  console.log('Channel started:', ch.name);
+  await ch.answer();
+  await ch.play({ media: 'sound:hello-world' });
+});
+
+channel.on('StasisEnd', () => {
+  console.log('Channel ended');
+  client.stop();
+});
+
+// Originate the call
+await channel.originate({
+  endpoint: 'PJSIP/1000',
+  app: 'my-app',
+});
+```
+
+## Connection Options
+
+```typescript
+const client = await connect({
+  // Required
+  url: 'http://localhost:8088',
+  username: 'asterisk',
+  password: 'asterisk',
+  app: 'my-app',
+
+  // Optional
+  subscribeAll: false,              // Subscribe to all Asterisk events
+  reconnect: true,                  // Enable auto-reconnect
+  reconnectInterval: 1000,          // Initial reconnect delay (ms)
+  maxReconnectInterval: 30000,      // Max reconnect delay (ms)
+  reconnectBackoffMultiplier: 1.5,  // Backoff multiplier
+  pingInterval: 30000,              // WebSocket ping interval (ms)
+  pingTimeout: 5000,                // Ping response timeout (ms)
+  requestTimeout: 30000,            // HTTP request timeout (ms)
+});
+```
+
+## API Resources
+
+All ARI resources are available on the client:
+
+```typescript
+// Channels
+const channels = await client.channels.list();
+const channel = await client.channels.get('channel-id');
+await client.channels.hangup('channel-id');
+
+// Bridges
+const bridges = await client.bridges.list();
+const bridge = await client.bridges.create({ type: 'mixing' });
+await client.bridges.addChannel(bridge.id, { channel: 'channel-id' });
+
+// Endpoints
+const endpoints = await client.endpoints.list();
+const endpoint = await client.endpoints.get('PJSIP', '1000');
+
+// Applications
+const apps = await client.applications.list();
+await client.applications.subscribe('my-app', 'channel:channel-id');
+
+// Playbacks
+const playback = await client.playbacks.get('playback-id');
+await client.playbacks.control('playback-id', 'pause');
+
+// Recordings
+const recordings = await client.recordings.stored.list();
+await client.recordings.live.stop('recording-name');
+
+// Sounds
+const sounds = await client.sounds.list({ lang: 'en' });
+
+// Mailboxes
+const mailboxes = await client.mailboxes.list();
+
+// Device States
+const states = await client.deviceStates.list();
+
+// Asterisk
+const info = await client.asterisk.getInfo();
+```
+
+## Resource Instances
+
+Create instances to receive events and call methods:
+
+### Channel
+
+```typescript
+const channel = client.Channel();
+
+channel.on('StasisStart', async (event, ch) => {
+  await ch.answer();
+  await ch.play({ media: 'sound:hello-world' });
+});
+
+channel.on('ChannelDtmfReceived', (event, ch) => {
+  console.log('DTMF:', event.digit);
+});
+
+channel.on('StasisEnd', (event, ch) => {
+  ch.removeAllListeners();
+});
+
+await channel.originate({
+  endpoint: 'PJSIP/1000',
+  app: 'my-app',
+});
+```
+
+### Bridge
+
+```typescript
+const bridge = client.Bridge();
+
+bridge.on('ChannelEnteredBridge', (event, br) => {
+  console.log('Channel entered:', event.channel.name);
+});
+
+bridge.on('ChannelLeftBridge', (event, br) => {
+  if (br.channels.length === 0) {
+    br.destroy();
+  }
+});
+
+await bridge.create({ type: 'mixing' });
+await bridge.addChannel({ channel: channel.id });
+```
+
+### Playback
+
+```typescript
+const playback = await channel.play({ media: 'sound:hello-world' });
+
+playback.on('PlaybackFinished', () => {
+  console.log('Playback done');
+});
+
+// Control playback
+await playback.pause();
+await playback.unpause();
+await playback.stop();
+```
+
+### Recording
+
+```typescript
+const recording = await channel.record({
+  name: 'my-recording',
+  format: 'wav',
+});
+
+recording.on('RecordingFinished', () => {
+  console.log('Recording saved');
+});
+
+await recording.pause();
+await recording.unpause();
+await recording.stop();
+```
+
+## Global Events
+
+Listen to all events on the client:
+
+```typescript
+// All events
+client.on('*', (event) => {
+  console.log('Event:', event.type);
+});
+
+// Specific events
+client.on('StasisStart', (event) => {
+  console.log('New channel:', event.channel.name);
+});
+
+client.on('ChannelDestroyed', (event) => {
+  console.log('Channel destroyed:', event.channel.id);
+});
+```
+
+## Connection Pool
+
+For high-throughput scenarios:
+
+```typescript
+import { createPool } from '@per_moeller/asterisk-ari';
+
+const pool = await createPool({
+  url: 'http://localhost:8088',
+  username: 'asterisk',
+  password: 'asterisk',
+  app: 'pool-app',
+  poolSize: 5,
+});
+
+// Get connection (round-robin)
+const client = pool.getConnection();
+
+// Use the client
+const channel = client.Channel();
+await channel.originate({ endpoint: 'PJSIP/1000', app: 'pool-app' });
+
+// Cleanup
+await pool.stop();
+```
+
+## Request Queue
+
+For automatic retry and circuit breaker:
+
+```typescript
+import { RequestQueue } from '@per_moeller/asterisk-ari';
+
+const queue = new RequestQueue({
+  maxConcurrent: 10,
+  maxRetries: 3,
+  retryDelay: 1000,
+  circuitBreakerThreshold: 5,
+  circuitBreakerTimeout: 30000,
+});
+
+// Enqueue requests
+const result = await queue.enqueue(() => client.channels.list());
+```
+
+## Version Compatibility
+
+The client automatically detects the Asterisk version and adjusts API calls:
+
+```typescript
+console.log(client.version.toString()); // "Asterisk 20 (ARI 8.0.0)"
+console.log(client.version.asteriskVersion); // 20
+console.log(client.version.hasExternalMedia); // true (Asterisk 18+)
+console.log(client.version.hasProtocolId); // true (Asterisk 20+)
+```
+
+## Event Types
+
+Full TypeScript types for all 30+ event types:
+
+- Channel: `StasisStart`, `StasisEnd`, `ChannelCreated`, `ChannelDestroyed`, `ChannelStateChange`, `ChannelDtmfReceived`, `ChannelHangupRequest`, `ChannelVarset`, `ChannelHold`, `ChannelUnhold`, `ChannelTalkingStarted`, `ChannelTalkingFinished`, `ChannelConnectedLine`, `ChannelDialplan`, `ChannelCallerId`, `ChannelToneDetected`
+- Bridge: `BridgeCreated`, `BridgeDestroyed`, `BridgeMerged`, `BridgeVideoSourceChanged`, `BridgeBlindTransfer`, `BridgeAttendedTransfer`, `ChannelEnteredBridge`, `ChannelLeftBridge`
+- Playback: `PlaybackStarted`, `PlaybackContinuing`, `PlaybackFinished`
+- Recording: `RecordingStarted`, `RecordingFinished`, `RecordingFailed`
+- Other: `EndpointStateChange`, `PeerStatusChange`, `ContactStatusChange`, `DeviceStateChanged`, `TextMessageReceived`, `Dial`, `ApplicationReplaced`, `ApplicationMoveFailed`
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,123 @@
+/**
+ * ARI Client - Main entry point for Asterisk REST Interface
+ */
+import { HttpConnection } from './connection.js';
+import { WebSocketManager } from './websocket.js';
+import { VersionCompat } from './version.js';
+import { AriEventEmitter } from './events/emitter.js';
+import type { ConnectOptions, ResolvedOptions } from './types/options.js';
+import { ChannelsResource } from './resources/channels.js';
+import { BridgesResource } from './resources/bridges.js';
+import { EndpointsResource } from './resources/endpoints.js';
+import { ApplicationsResource } from './resources/applications.js';
+import { AsteriskResource } from './resources/asterisk.js';
+import { PlaybacksResource } from './resources/playbacks.js';
+import { RecordingsResource } from './resources/recordings.js';
+import { SoundsResource } from './resources/sounds.js';
+import { MailboxesResource } from './resources/mailboxes.js';
+import { DeviceStatesResource } from './resources/devicestates.js';
+import { ChannelInstance } from './models/channel.js';
+import { BridgeInstance } from './models/bridge.js';
+import { PlaybackInstance } from './models/playback.js';
+import { LiveRecordingInstance, StoredRecordingInstance } from './models/recording.js';
+import type { Channel, Bridge, Playback, LiveRecording } from './types/api.js';
+/**
+ * ARI Client for interacting with Asterisk
+ */
+export declare class AriClient extends AriEventEmitter {
+    private readonly options;
+    private readonly http;
+    private readonly ws;
+    private readonly versionCompat;
+    private readonly channelInstances;
+    private readonly bridgeInstances;
+    private readonly playbackInstances;
+    private readonly recordingInstances;
+    readonly channels: ChannelsResource;
+    readonly bridges: BridgesResource;
+    readonly endpoints: EndpointsResource;
+    readonly applications: ApplicationsResource;
+    readonly asterisk: AsteriskResource;
+    readonly playbacks: PlaybacksResource;
+    readonly recordings: RecordingsResource;
+    readonly sounds: SoundsResource;
+    readonly mailboxes: MailboxesResource;
+    readonly deviceStates: DeviceStatesResource;
+    /**
+     * @internal - Use connect() function instead
+     */
+    constructor(options: ResolvedOptions, http: HttpConnection, ws: WebSocketManager, versionCompat: VersionCompat);
+    /**
+     * Set up WebSocket event handlers
+     */
+    private setupWebSocketEvents;
+    /**
+     * Handle an incoming ARI event
+     */
+    private handleEvent;
+    /**
+     * Route event to appropriate instance listeners
+     */
+    private routeEventToInstances;
+    /**
+     * Create a Channel instance
+     */
+    Channel(id?: string, data?: Partial<Channel>): ChannelInstance;
+    /**
+     * Create a Bridge instance
+     */
+    Bridge(id?: string, data?: Partial<Bridge>): BridgeInstance;
+    /**
+     * Create a Playback instance
+     */
+    Playback(id?: string, data?: Partial<Playback>): PlaybackInstance;
+    /**
+     * Create a LiveRecording instance
+     */
+    LiveRecording(name: string, data?: Partial<LiveRecording>): LiveRecordingInstance;
+    /**
+     * Create a StoredRecording instance (no events, just convenience methods)
+     */
+    StoredRecording(name: string): StoredRecordingInstance;
+    /** @internal */
+    _registerChannelInstance(id: string, instance: ChannelInstance): void;
+    /** @internal */
+    _unregisterChannelInstance(id: string): void;
+    /** @internal */
+    _registerBridgeInstance(id: string, instance: BridgeInstance): void;
+    /** @internal */
+    _unregisterBridgeInstance(id: string): void;
+    /** @internal */
+    _registerPlaybackInstance(id: string, instance: PlaybackInstance): void;
+    /** @internal */
+    _unregisterPlaybackInstance(id: string): void;
+    /** @internal */
+    _registerRecordingInstance(name: string, instance: LiveRecordingInstance): void;
+    /** @internal */
+    _unregisterRecordingInstance(name: string): void;
+    /**
+     * Get the detected ARI/Asterisk version
+     */
+    get version(): VersionCompat;
+    /**
+     * Check if WebSocket is connected
+     */
+    isConnected(): boolean;
+    /**
+     * Stop the client and disconnect
+     */
+    stop(): void;
+    /**
+     * Reconnect the WebSocket
+     */
+    reconnect(): Promise<void>;
+    /**
+     * Get the application name
+     */
+    get app(): string;
+}
+/**
+ * Connect to Asterisk ARI
+ */
+export declare function connect(options: ConnectOptions): Promise<AriClient>;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}