Skip to content

Commit f3ffd00

Browse files
committed
refactor: improve type safety and error handling
- Add proper TypeScript generics for HTTP methods - Improve error handling with custom HTTPError class - Add comprehensive JSDoc documentation - Translate all messages to English - Add better logging for debugging - Implement robust WebSocket reconnection - Add new utility methods for better API handling - Update README with detailed usage examples Breaking Changes: - BaseClient HTTP methods now use generic types for request data - Error messages are now consistently in English
1 parent 066f457 commit f3ffd00

27 files changed

+4152
-1093
lines changed

README.md

Lines changed: 254 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,254 @@
1+
# @ipcom/asterisk-ari
2+
3+
A modern JavaScript/TypeScript library for interacting with the Asterisk REST Interface (ARI).
4+
5+
## Features
6+
7+
- Complete Asterisk ARI support
8+
- Written in TypeScript with full type support
9+
- WebSocket support for real-time events
10+
- Automatic reconnection management
11+
- Simplified channel and playback handling
12+
- ESM and CommonJS support
13+
- Complete type documentation
14+
15+
## Installation
16+
17+
```bash
18+
npm install @ipcom/asterisk-ari
19+
```
20+
21+
## Basic Usage
22+
23+
### Initial Setup
24+
25+
```typescript
26+
import { AriClient } from '@ipcom/asterisk-ari';
27+
28+
const client = new AriClient({
29+
host: 'localhost', // Asterisk host
30+
port: 8088, // ARI port
31+
username: 'username', // ARI username
32+
password: 'password', // ARI password
33+
secure: false // Use true for HTTPS/WSS
34+
});
35+
```
36+
37+
### WebSocket Connection
38+
39+
```typescript
40+
// Connect to WebSocket to receive events
41+
await client.connectWebSocket(['myApp']); // 'myApp' is your application name
42+
43+
// Listen for specific events
44+
client.on('StasisStart', event => {
45+
console.log('New channel started:', event.channel.id);
46+
});
47+
48+
client.on('StasisEnd', event => {
49+
console.log('Channel ended:', event.channel.id);
50+
});
51+
52+
// Listen for DTMF events
53+
client.on('ChannelDtmfReceived', event => {
54+
console.log('DTMF received:', event.digit);
55+
});
56+
57+
// Close WebSocket connection
58+
client.closeWebSocket();
59+
```
60+
61+
### Channel Handling
62+
63+
```typescript
64+
// Create a channel instance
65+
const channel = client.Channel();
66+
67+
// Originate a call
68+
await channel.originate({
69+
endpoint: 'PJSIP/1000',
70+
extension: '1001',
71+
context: 'default',
72+
priority: 1
73+
});
74+
75+
// Answer a call
76+
await channel.answer();
77+
78+
// Play audio
79+
const playback = await channel.play({
80+
media: 'sound:welcome'
81+
});
82+
83+
// Hangup the channel
84+
await channel.hangup();
85+
```
86+
87+
### Playback Handling
88+
89+
```typescript
90+
// Create a playback instance
91+
const playback = client.Playback();
92+
93+
// Monitor playback events
94+
playback.on('PlaybackStarted', event => {
95+
console.log('Playback started:', event.playback.id);
96+
});
97+
98+
playback.on('PlaybackFinished', event => {
99+
console.log('Playback finished:', event.playback.id);
100+
});
101+
102+
// Control playback
103+
await playback.control('pause'); // Pause
104+
await playback.control('unpause'); // Resume
105+
await playback.control('restart'); // Restart
106+
await playback.stop(); // Stop
107+
```
108+
109+
### Specific Channel Monitoring
110+
111+
```typescript
112+
// Create an instance for a specific channel
113+
const channel = client.Channel('channel-id');
114+
115+
// Monitor specific channel events
116+
channel.on('ChannelStateChange', event => {
117+
console.log('Channel state changed:', event.channel.state);
118+
});
119+
120+
channel.on('ChannelDtmfReceived', event => {
121+
console.log('DTMF received on channel:', event.digit);
122+
});
123+
124+
// Get channel details
125+
const details = await channel.getDetails();
126+
console.log('Channel details:', details);
127+
128+
// Handle channel variables
129+
await channel.getVariable('CALLERID');
130+
await channel.setVariable('CUSTOM_VAR', 'value');
131+
```
132+
133+
### Channel Playback Handling
134+
135+
```typescript
136+
// Play audio on a specific channel
137+
const channel = client.Channel('channel-id');
138+
const playback = await channel.play({
139+
media: 'sound:welcome',
140+
lang: 'en'
141+
});
142+
143+
// Monitor specific playback
144+
playback.on('PlaybackStarted', event => {
145+
console.log('Playback started on channel');
146+
});
147+
148+
// Control playback
149+
await channel.stopPlayback(playback.id);
150+
await channel.pausePlayback(playback.id);
151+
await channel.resumePlayback(playback.id);
152+
```
153+
154+
## Error Handling
155+
156+
```typescript
157+
try {
158+
await client.connectWebSocket(['myApp']);
159+
} catch (error) {
160+
console.error('Error connecting to WebSocket:', error);
161+
}
162+
163+
// Using with async/await
164+
try {
165+
const channel = client.Channel();
166+
await channel.originate({
167+
endpoint: 'PJSIP/1000'
168+
});
169+
} catch (error) {
170+
console.error('Error originating call:', error);
171+
}
172+
```
173+
174+
## TypeScript Support
175+
176+
The library provides complete type definitions for all operations:
177+
178+
```typescript
179+
import type {
180+
Channel,
181+
ChannelEvent,
182+
WebSocketEvent
183+
} from '@ipcom/asterisk-ari';
184+
185+
// Types will be available for use
186+
const handleChannelEvent = (event: ChannelEvent) => {
187+
const channelId: string = event.channel.id;
188+
};
189+
```
190+
191+
## Additional Features
192+
193+
The library provides access to many other ARI features:
194+
195+
- Bridge management
196+
- Endpoint handling
197+
- Sound manipulation
198+
- Application control
199+
- Asterisk system information
200+
- And much more...
201+
202+
## Advanced Examples
203+
204+
### Bridge Creation and Channel Management
205+
206+
```typescript
207+
// Create and manage a bridge
208+
const bridge = await client.bridges.createBridge({
209+
type: 'mixing',
210+
name: 'myBridge'
211+
});
212+
213+
// Add channels to bridge
214+
await client.bridges.addChannels(bridge.id, {
215+
channel: ['channel-id-1', 'channel-id-2']
216+
});
217+
```
218+
219+
### Recording Management
220+
221+
```typescript
222+
// Start recording on a channel
223+
const channel = client.Channel('channel-id');
224+
await channel.record({
225+
name: 'recording-name',
226+
format: 'wav',
227+
maxDurationSeconds: 60,
228+
beep: true
229+
});
230+
```
231+
232+
### External Media
233+
234+
```typescript
235+
// Create external media channel
236+
const channel = await client.channels.createExternalMedia({
237+
app: 'myApp',
238+
external_host: 'media-server:8088',
239+
format: 'slin16'
240+
});
241+
```
242+
243+
## API Reference
244+
245+
For complete API documentation, please refer to the TypeScript types and interfaces exported by the package.
246+
247+
## Contributing
248+
249+
Contributions are welcome! Please feel free to submit a Pull Request.
250+
251+
## License
252+
253+
Apache-2.0
254+

0 commit comments

Comments
 (0)