ruby-asterisk 0.2.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 95239d89540f2e3507f0b72b8f7e42af3c76f781
-  data.tar.gz: b3d95a77ba65f358d3504d008e5b41d3035399e5
+SHA256:
+  metadata.gz: c95a048e0d2735b23389820940e402ff7a48a3f50e4ec2a6f02d4bdd7b4fc202
+  data.tar.gz: cd6aa33ec274995602082c1c78a352c6ce32e979b402c35e62efcf728425fb2d
 SHA512:
-  metadata.gz: 4fdcf0145516e61659670bce72dd974925b076321180c115fa2d65fd55033faf08d9656d667c6934afbf51238ba42ac535a26a5208c20c79a2a3f17476e74ebf
-  data.tar.gz: 424f729d2eea0516b353f412d7fc4ee6830caf2b847d2931dd4bf78388ea52c4fb38f63ad28b7c73a91fec5975ca04917f3dbe31d1782a40f4ca0e0fe3389e10
+  metadata.gz: 4d6f5a3be79a8dcc25109ca1baf8d2844a72086a16eae470c136c3d36e6b5e9cba658b4d877a8e5f7693b8b8d7cc75e71ad0552ddb8d53ef6239ee25d07115c8
+  data.tar.gz: 0c97e244ad05079470ce0067d58fcc557dfaff420343ad79b6db853a2a865d233dff09e98df2c12631ce6d9dd0b3f7885cad6eb630f182d83902a0840091d273

data/.claude/skills/ruby-asterisk-agi/SKILL.md

@@ -0,0 +1,317 @@
+---
+name: ruby-asterisk-agi
+description: Build AGI/FastAGI dialplan logic in Ruby with ruby-asterisk: Server (Async+Fiber), Session command verbs, Protocol parsing, IVR patterns, 520 multi-line error handling.
+---
+
+# ruby-asterisk AGI / FastAGI
+
+## When to use this skill
+
+Use this skill when writing Ruby code that Asterisk calls via `AGI(agi://host:port)`. ruby-asterisk provides a FastAGI TCP server (`AGI::Server`) backed by the `async` gem's Fiber scheduler, plus a `Session` class with the full set of AGI command verbs.
+
+## Core concepts
+
+### Architecture
+
+```
+Asterisk          ruby-asterisk FastAGI server
+   |                      |
+   |--- TCP connect -----> AGI::Server (TCPServer + Async Sync)
+   |                             |
+   |                     spawns Fiber per connection
+   |                             |
+   |--- ENV block -------> Session#read_env  (parse agi_* vars)
+   |--- CMD response <---- Session#<verb>    (write command, read result)
+   |--- CMD response <---- ...
+   |--- EOF / hangup ----> Fiber exits, socket closed
+```
+
+Each connection runs in its own **Fiber** sharing one OS thread. Socket reads/writes yield the Fiber rather than blocking, so thousands of simultaneous calls can be handled efficiently.
+
+### Session execute model
+
+Every command method writes a line to the socket and reads back a response:
+
+```ruby
+# Low-level (rarely called directly):
+response = session.execute('ANSWER')
+# => { code: 200, result: "0", data: nil }
+
+# High-level convenience methods:
+session.answer     # => { code: 200, result: "0", data: nil }
+```
+
+`execute` raises `RubyAsterisk::Error` on:
+- EOF from Asterisk (`"Connection closed by Asterisk"`)
+- Any 5xx response, after collecting the full `520-…/520 End of proper usage.` multi-line error body
+
+### Protocol module
+
+`RubyAsterisk::AGI::Protocol` is a stateless utility module (all class methods):
+
+| Method | Purpose |
+|---|---|
+| `format_command(cmd, *args)` | Build a `"CMD arg1 arg2\n"` string with argument escaping |
+| `escape_argument(arg)` | Pass through bare words; double-quote strings with spaces/special chars |
+| `quote(arg)` | **Always** double-quote (use for filenames, variable values, messages) |
+| `parse_response(line)` | Parse `"200 result=0 (data)"` → `{code:, result:, data:}` frozen Hash |
+| `parse_env_line(line)` | Parse one `"agi_key: value"` line → `[key, value]` or `nil` |
+| `parse_env_block(io, &block)` | Read env lines until blank, return `Hash{String=>String}` |
+| `collect_multiline_error(first_line, first_resp, io)` | Drain 520 continuation lines |
+| `error?(response)` | `response[:code] >= 500` |
+
+**`quote` vs `escape_argument`**: use `quote` for filenames, variable values, and text that Asterisk requires always quoted; use `escape_argument` for digit-escape lists and simple identifiers that only need quoting when they contain spaces or special characters.
+
+## FastAGI server
+
+### Minimal setup
+
+```ruby
+require 'ruby-asterisk'
+
+server = RubyAsterisk::AGI::Server.new('0.0.0.0', 4573)
+server.handle do |session|
+  session.answer
+  session.stream_file('hello-world')
+  session.hangup
+end
+server.run   # blocks until server.stop is called
+```
+
+In Asterisk `extensions.conf`:
+
+```
+exten => 100,1,AGI(agi://192.168.1.100:4573)
+```
+
+### Server API
+
+| Method | Signature | Notes |
+|---|---|---|
+| `new` | `(host, port, logger: Logger.new($stdout))` | `port: 0` → ephemeral |
+| `handle` | `(&block)` | Must be called before `run`; returns `self` |
+| `run` | — | Blocks; raises `Error` if no handler |
+| `stop` | — | Closes listener; active sessions finish naturally |
+| `running?` | — | Boolean |
+| `port` | — | Actual bound port (useful when `port: 0`) |
+
+## Session command verbs
+
+All methods return `{ code: Integer, result: String|nil, data: String|nil }`.
+
+### Lifecycle and environment
+
+```ruby
+session.read_env     # parse initial agi_* block; fills session.env
+session.env          # => { "agi_channel" => "SIP/alice-001", "agi_callerid" => "...", ... }
+session.execute(cmd) # low-level: write cmd, read one response line
+```
+
+### Call control
+
+```ruby
+session.answer
+session.hangup
+session.hangup('SIP/alice-001')   # explicit channel
+session.channel_status            # status of current channel (returns numeric code in result)
+session.channel_status('SIP/b')   # explicit channel
+```
+
+### Audio playback
+
+```ruby
+session.stream_file('hello-world')           # play sound; no interrupt
+session.stream_file('hello-world', '1234')   # play; stop on digit 1/2/3/4
+session.stream_file('hello-world', '#*')     # stop on # or *
+
+session.say_digits('12345')
+session.say_digits('12345', '#')             # stop on #
+
+session.say_number(42)
+session.say_number(42, '#')
+```
+
+### DTMF / input collection
+
+```ruby
+result = session.get_data('enter-pin', timeout: 5000, max_digits: 4)
+puts result[:data]   # => "1234" (digits entered) or "" on timeout
+
+digit_ascii = session.wait_for_digit(5000)  # returns ASCII int, -1 on timeout
+char = digit_ascii.chr if digit_ascii > 0
+```
+
+### Variables
+
+```ruby
+session.set_variable('MY_VAR', 'hello world')
+response = session.get_variable('MY_VAR')
+puts response[:data]   # => "hello world"
+```
+
+### Recording
+
+```ruby
+session.record_file(
+  '/tmp/voicemail',      # filename (no extension)
+  format: 'wav',         # default: 'wav'
+  escape_digits: '#',    # stop on # (default)
+  timeout_ms: 30_000,    # -1 = no timeout (default)
+  offset: 0,
+  beep: true,            # play beep before recording (default)
+  silence: 3             # stop after 3 s of silence (optional)
+)
+```
+
+### Dialplan application execution
+
+```ruby
+session.exec('Playback', 'hello-world')
+session.exec('AGI', 'script.agi')
+session.dial('PJSIP/bob', timeout: 30, options: 'r')   # wraps Exec Dial
+```
+
+### AstDB operations
+
+```ruby
+session.database_put('myapp', 'last_caller', '0391234567')
+response = session.database_get('myapp', 'last_caller')
+puts response[:data]                              # => "0391234567"
+session.database_del('myapp', 'last_caller')
+session.database_deltree('myapp')                 # delete whole family
+session.database_deltree('myapp', 'sub/tree')     # delete sub-tree
+```
+
+### Utilities
+
+```ruby
+session.verbose('Starting IVR', level: 2)         # log to Asterisk CLI
+session.send_text('Hello from FastAGI')
+session.send_image('logo.png')
+```
+
+## Patterns
+
+### Pattern 1: Minimal FastAGI (answer → play → hangup)
+
+```ruby
+server = RubyAsterisk::AGI::Server.new('0.0.0.0', 4573)
+server.handle { |s| s.answer; s.stream_file('hello-world'); s.hangup }
+server.run
+```
+
+### Pattern 2: IVR with DTMF branching
+
+```ruby
+server = RubyAsterisk::AGI::Server.new('0.0.0.0', 4573)
+server.handle do |session|
+  session.answer
+
+  result = session.get_data('ivr-welcome', timeout: 5000, max_digits: 1)
+  choice = result[:data].to_s.strip
+
+  case choice
+  when '1'
+    session.dial('PJSIP/sales', timeout: 30)
+  when '2'
+    session.dial('PJSIP/support', timeout: 30)
+  when '0'
+    session.exec('VoiceMail', '1000@default')
+  else
+    session.stream_file('invalid-option')
+    session.hangup
+  end
+end
+server.run
+```
+
+### Pattern 3: Recording with error handling
+
+```ruby
+server = RubyAsterisk::AGI::Server.new('0.0.0.0', 4573)
+server.handle do |session|
+  session.answer
+  session.stream_file('record-after-beep')
+
+  begin
+    session.record_file('/tmp/greeting',
+                        format: 'wav',
+                        escape_digits: '#',
+                        timeout_ms: 30_000,
+                        beep: true,
+                        silence: 3)
+
+    session.database_put('greetings', 'latest', '/tmp/greeting.wav')
+    session.stream_file('your-recording-has-been-saved')
+  rescue RubyAsterisk::Error => e
+    # e.message contains the full 520 multi-line error body if applicable
+    session.verbose("Recording failed: #{e.message}", level: 1)
+    session.stream_file('an-error-occurred')
+  ensure
+    session.hangup
+  end
+end
+server.run
+```
+
+### Pattern 4: All verbs — quick reference snippets
+
+```ruby
+# ---- Call control ----
+session.answer                                    # ANSWER
+session.hangup                                    # HANGUP
+session.hangup('SIP/channel-001')                 # HANGUP <channel>
+session.channel_status                            # CHANNEL STATUS
+session.channel_status('SIP/channel-001')         # CHANNEL STATUS <channel>
+
+# ---- Playback ----
+session.stream_file('hello-world', '')            # STREAM FILE "hello-world" ""
+session.say_digits('123', '#')                    # SAY DIGITS 123 "#"
+session.say_number(42, '')                        # SAY NUMBER 42 ""
+
+# ---- Input ----
+session.get_data('enter-pin', timeout: 5000, max_digits: 4)  # GET DATA "enter-pin" 5000 4
+session.wait_for_digit(5000)                      # WAIT FOR DIGIT 5000
+
+# ---- Variables ----
+session.set_variable('FOO', 'bar baz')            # SET VARIABLE FOO "bar baz"
+session.get_variable('FOO')                       # GET VARIABLE FOO
+
+# ---- Recording ----
+session.record_file('/tmp/rec', format: 'wav', beep: true, silence: 3)
+
+# ---- Execution ----
+session.exec('Playback', 'hello-world')           # EXEC Playback "hello-world"
+session.dial('PJSIP/alice', timeout: 30)          # EXEC Dial "PJSIP/alice,30"
+session.verbose('log me', level: 1)               # VERBOSE "log me" 1
+
+# ---- Text / image ----
+session.send_text('Hello')                        # SEND TEXT "Hello"
+session.send_image('logo.png')                    # SEND IMAGE logo.png
+
+# ---- AstDB ----
+session.database_put('family', 'key', 'value')    # DATABASE PUT family key "value"
+session.database_get('family', 'key')             # DATABASE GET family key
+session.database_del('family', 'key')             # DATABASE DEL family key
+session.database_deltree('family')                # DATABASE DELTREE family
+session.database_deltree('family', 'sub')         # DATABASE DELTREE family sub
+```
+
+## Gotchas
+
+- **`handle` is mandatory** before `run`; calling `run` without it raises `RubyAsterisk::Error`.
+- **`execute` raises on EOF** (`"Connection closed by Asterisk"`) and on any 5xx, including `520-…` multi-line errors. All command methods propagate this.
+- **`Protocol.quote` vs `escape_argument`**: always use `quote` for filenames, variable values, and text content. Use `escape_argument` for digit-escape strings or other tokens that only need quoting conditionally.
+- **Ruby 3.1**: an `IO#timeout` / `IO#timeout=` shim is applied at load time in `agi/server.rb`. Required because the `async` gem calls `io.timeout` inside its scheduler on Ruby 3.2+ — the shim returns `nil` on 3.1 to disable that path. Never remove it while Ruby 3.1 is in the support matrix.
+- **CPU-bound work in handlers** will block the shared Fiber scheduler. Offload to a Thread or separate process if you need heavy computation per call.
+- **`session.env` is populated by `read_env`** which is called automatically by `Server#serve`. In tests, call `session.read_env` manually after writing the env block to the socket.
+- The `logger` on `Server` is passed down to each `Session`; unknown AGI env lines (not matching `agi_*:`) are logged at `debug` level.
+
+## Source files
+
+- `lib/ruby-asterisk/agi/server.rb` — `Server` class + `IO#timeout` shim
+- `lib/ruby-asterisk/agi/session.rb` — `Session` class
+- `lib/ruby-asterisk/agi/protocol.rb` — `Protocol` module
+- `spec/ruby-asterisk/agi/server_spec.rb` — server lifecycle + Fiber concurrency proof
+- `spec/ruby-asterisk/agi/session_spec.rb` — all command verbs, error handling
+- `spec/ruby-asterisk/agi/protocol_spec.rb` — parsing and formatting helpers

data/.claude/skills/ruby-asterisk-ami/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: ruby-asterisk-ami
+description: Build an async Asterisk AMI client with ruby-asterisk: connect, login, Promise-based commands (channel, queue, conference, SIP, mailbox, monitor, extension state).
+---
+
+# ruby-asterisk AMI Client
+
+## When to use this skill
+
+Use this skill when writing code that connects to the Asterisk Manager Interface via TCP — for example: originating calls, checking extension state, managing queues, monitoring channels, or handling SIP peers.
+
+## Core concepts
+
+### Every command returns a Promise
+
+```ruby
+promise  = ami.ping          # returns RubyAsterisk::AMI::Promise immediately
+response = promise.value     # blocks up to 5 s (default timeout)
+response = promise.value(10) # custom timeout in seconds
+```
+
+`#value` raises `Timeout::Error` if no response arrives within the timeout.
+`disconnect` rejects all pending promises with `RuntimeError`.
+
+### The Response object
+
+| Attribute | Type | Notes |
+|---|---|---|
+| `success` | Boolean | `true` when raw contains `Response: Success` |
+| `action_id` | String | echoed ActionID |
+| `message` | String | `Message:` field |
+| `data` | Hash / Array | structured, present when action is in `PARSE_DATA` |
+| `raw_response` | String/Array | unprocessed AMI text |
+| `type` | String | AMI action name |
+
+### Connection lifecycle
+
+```ruby
+ami = RubyAsterisk::AMI::Client.new(host: '192.168.1.1', port: 5038)
+ami.connect                                        # starts the reader + writer threads
+ami.login(username: 'admin', secret: 'secret').value
+# ... use commands ...
+ami.logoff.value
+ami.disconnect                                     # stops both threads, rejects pending promises
+```
+
+`login` auto-calls `connect` if not already connected.
+
+## API reference
+
+### System
+
+| Method | AMI Action | Notes |
+|---|---|---|
+| `ping` | `Ping` | Returns `Pong` response |
+| `command(cmd)` | `Command` | CLI passthrough, e.g. `'core show channels'` |
+| `wait_event(timeout: -1)` | `WaitEvent` | negative = wait forever, so `#value` has no deadline; a positive value bounds it (floor: the client default) |
+| `event_mask(mask = 'off')` | `Events` | `'on'` / `'off'` / `'system,call'` |
+| `parked_calls` | `ParkedCalls` | |
+| `device_state_list` | `DeviceStateList` | |
+| `skinny_devices` | `SKINNYdevices` | |
+| `skinny_lines` | `SKINNYlines` | |
+
+### Channel
+
+| Method | Signature | AMI Action |
+|---|---|---|
+| `core_show_channels` | — | `CoreShowChannels` |
+| `status` | `(channel: nil, action_id: nil)` | `Status` |
+| `originate` | `(channel, context, callee, priority, variable: nil, caller_id: nil, timeout: 30_000, async: nil)` | `Originate` |
+| `originate_app` | `(channel:, application:, data:, async:)` | `Originate` (Application/Data form) |
+| `redirect` | `(channel, context, callee, priority, variable: nil, caller_id: nil, timeout: 30_000)` | `Redirect` |
+| `hangup` | `(channel)` | `Hangup` |
+| `atxfer` | `(channel:, exten:, context:, priority: '1')` | `Atxfer` |
+
+### Queue
+
+| Method | Signature |
+|---|---|
+| `queues` | — |
+| `queue_status` | — |
+| `queue_summary` | `(queue)` |
+| `queue_add` | `(queue, interface, penalty: 2, paused: false, member_name: '')` |
+| `queue_remove` | `(queue:, interface:)` |
+| `queue_pause` | `(interface:, paused:, queue:, reason: 'none')` |
+
+### Conference
+
+| Method | Signature |
+|---|---|
+| `meet_me_list` | — |
+| `confbridges` | — |
+| `confbridge` | `(conference)` |
+| `confbridge_mute` | `(conference:, channel:)` |
+| `confbridge_unmute` | `(conference:, channel:)` |
+| `confbridge_kick` | `(conference:, channel:)` |
+
+### Mailbox
+
+| Method | Signature |
+|---|---|
+| `mailbox_status` | `(mailbox:, context: 'default')` |
+| `mailbox_count` | `(mailbox:, context: 'default')` |
+
+### SIP
+
+| Method | Signature |
+|---|---|
+| `sip_peers` | — |
+| `sip_show_peer` | `(peer)` |
+| `sip_show_registry` | — |
+
+### Extension
+
+| Method | Signature | Notes |
+|---|---|---|
+| `extension_state` | `(exten:, context:, action_id: nil)` | `data[:hints]` decorated with `DescriptiveStatus` |
+
+### Monitor
+
+| Method | Signature |
+|---|---|
+| `monitor` | `(channel, mix: false, file: nil, format: 'wav')` |
+| `stop_monitor` | `(channel)` |
+| `pause_monitor` | `(channel)` |
+| `unpause_monitor` | `(channel)` |
+| `change_monitor` | `(channel:, file:)` |
+
+## Usage patterns
+
+### Minimal connect + command
+
+```ruby
+ami = RubyAsterisk::AMI::Client.new(host: '127.0.0.1', port: 5038)
+ami.login(username: 'admin', secret: 'secret').value
+response = ami.ping.value
+puts response.success   # => true
+ami.disconnect
+```
+
+### Originate and wait for result
+
+```ruby
+promise  = ami.originate('PJSIP/alice', 'outbound', '0391234567', '1', async: true)
+response = promise.value(30)
+puts response.success
+```
+
+### Poll queue status
+
+```ruby
+loop do
+  members = ami.queue_status.value.data
+  members&.each { |m| puts m.inspect }
+  sleep 5
+end
+```
+
+### Handle Timeout::Error
+
+```ruby
+begin
+  response = ami.originate('SIP/slow', 'default', '100', '1').value(2)
+rescue Timeout::Error
+  puts 'AMI did not respond in time'
+end
+```
+
+## Gotchas
+
+- **ActionID is auto-generated** (monotonic nanosecond clock in base36 plus an atomic counter). A caller-supplied `action_id:` replaces it — including in the `Promise` used for correlation — so it must be unique among in-flight commands.
+- **Call `event_mask('on')`** on the connection if you need Asterisk to push async events (e.g. `StasisStart`). Off by default. Note that `AMI::Client` currently discards received events: there is no public subscription API yet.
+- **`timeout:` is per command** and never mutates the client-wide default; `wait_event(timeout: -1)` builds a promise with no deadline, so bound it with `value(seconds)` if you must not block forever.
+- **`disconnect` rejects all pending promises** — check for `RuntimeError` if you disconnect mid-flight.
+- **`PARSE_DATA`** (`lib/ruby-asterisk/parsing_constants.rb`) controls which responses get structured `data`; unlisted actions return the raw string.
+- The version constant is now `RubyAsterisk::VERSION` (was `Rami::VERSION` before 1.0.0).
+
+## Source files
+
+- `lib/ruby-asterisk/ami/client.rb` — `Client` class
+- `lib/ruby-asterisk/ami/reactor.rb` — reader/writer threads owning the socket
+- `lib/ruby-asterisk/ami/parser.rb` — stateless AMI frame parser
+- `lib/ruby-asterisk/ami/promise.rb` — `Promise` class
+- `lib/ruby-asterisk/ami/commands/*.rb` — command modules
+- `lib/ruby-asterisk/response.rb` — `Response` class
+- `lib/ruby-asterisk/parsing_constants.rb` — `PARSE_DATA`, `DESCRIPTIVE_STATUS`
+- `spec/ruby-asterisk/ami/async_client_spec.rb` — integration tests

data/.claude/skills/ruby-asterisk-ari/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: ruby-asterisk-ari
+description: Use the Asterisk REST Interface with ruby-asterisk: channels, bridges, playbacks, endpoints via HTTP, and RubyAsterisk::Error for 4xx/5xx handling.
+---
+
+# ruby-asterisk ARI HTTP Client
+
+## When to use this skill
+
+Use this skill when writing code that controls Asterisk channels or bridges via the ARI REST API — for example: answering calls from a Stasis application, mixing channels into a bridge, controlling media playback, or inspecting endpoint registration state.
+
+## Core concepts
+
+- The client is **synchronous** (backed by Faraday). Every method blocks and returns the parsed JSON body (Hash or Array) or raises `RubyAsterisk::Error`.
+- Resources are accessed via `Collection` objects (`client.channels`, `client.bridges`, etc.); each collection supports `list` and `get(id)`.
+- Individual resource objects have a `data` Hash with the full JSON representation, plus convenience methods for actions.
+- **`app_name`** must match the Stasis application declared in Asterisk's `ari.conf`; mismatches cause channels to be rejected or events to be silently dropped.
+
+## Initialize
+
+```ruby
+require 'ruby-asterisk'
+
+client = RubyAsterisk::ARI::Client.new(
+  'http://192.168.1.1:8088',   # ARI base URL (no trailing slash)
+  'my_api_key',                # API key used as HTTP Basic auth username
+  'my_stasis_app'              # Stasis application name
+)
+```
+
+## API reference
+
+### Asterisk info
+
+```ruby
+info = client.asterisk_info
+# => Hash with keys "build", "system", "config", "status"
+puts info['system']['version']
+```
+
+### Channels — `client.channels`
+
+| Method | Signature | Returns |
+|---|---|---|
+| `list` | — | Array of `Channel` |
+| `get` | `(id)` | `Channel` |
+
+**Channel actions:**
+
+| Method | Notes |
+|---|---|
+| `channel.id` | Channel identifier string |
+| `channel.data` | Full JSON Hash from ARI |
+| `channel.ring` | Send ringing indication |
+| `channel.answer` | Answer the channel |
+| `channel.play(media, **opts)` | Play audio; `media` = `'sound:hello-world'` |
+| `channel.hangup` | Hang up and destroy |
+
+### Bridges — `client.bridges`
+
+| Method | Signature | Returns |
+|---|---|---|
+| `list` | — | Array of `Bridge` |
+| `get` | `(id)` | `Bridge` |
+
+**Bridge actions:**
+
+| Method | Notes |
+|---|---|
+| `bridge.id` | Bridge identifier |
+| `bridge.data` | Full JSON Hash |
+| `bridge.add_channel(channel_id)` | Mix a channel into the bridge |
+| `bridge.remove_channel(channel_id)` | Remove a channel |
+| `bridge.destroy` | Destroy the bridge |
+
+### Playbacks — `client.playbacks`
+
+| Method | Signature | Returns |
+|---|---|---|
+| `get` | `(id)` | `Playback` |
+
+**Playback actions:**
+
+| Method | Notes |
+|---|---|
+| `playback.control('pause')` | Pause playback |
+| `playback.control('unpause')` | Resume |
+| `playback.control('restart')` | Restart from beginning |
+| `playback.stop` | Stop and destroy |
+
+### Endpoints — `client.endpoints`
+
+| Method | Signature | Returns |
+|---|---|---|
+| `list` | — | Array of `Endpoint` |
+
+**Endpoint attributes:**
+
+| Method | Notes |
+|---|---|
+| `ep.technology` | e.g. `'PJSIP'`, `'SIP'` |
+| `ep.resource` | e.g. `'alice'` |
+| `ep.state` | `'online'` / `'offline'` |
+| `ep.data` | Full JSON Hash |
+
+## Error handling
+
+All methods raise `RubyAsterisk::Error` for HTTP 4xx/5xx responses:
+
+```ruby
+begin
+  channel = client.channels.get('nonexistent')
+rescue RubyAsterisk::Error => e
+  puts e.message  # => "Channel not found"
+end
+```
+
+The error message comes from the JSON `message` field if present, otherwise from the HTTP reason phrase.
+
+## Usage patterns
+
+### Answer a Stasis channel and bridge two callers
+
+```ruby
+channel_a = client.channels.get(event_channel_a_id)
+channel_b = client.channels.get(event_channel_b_id)
+
+bridge = client.bridges.list.first || begin
+  # bridges.list returns all existing bridges; create via ARI REST directly if none
+end
+
+channel_a.answer
+channel_b.answer
+
+bridge.add_channel(channel_a.id)
+bridge.add_channel(channel_b.id)
+```
+
+### Play audio and track playback
+
+```ruby
+channel.play('sound:tt-monkeys', playbackId: 'pb-greeting')
+pb = client.playbacks.get('pb-greeting')
+pb.control('pause')
+sleep 2
+pb.control('unpause')
+pb.stop
+```
+
+### List all online PJSIP endpoints
+
+```ruby
+online = client.endpoints.list.select { |ep| ep.technology == 'PJSIP' && ep.state == 'online' }
+online.each { |ep| puts ep.resource }
+```
+
+## Gotchas
+
+- **Basic auth**: `api_key` is the **username**; the password is always empty (`''`). Check `ari.conf` if you get 401 errors.
+- **`app_name` must match** the Stasis application configured in Asterisk; channels not subscribed to your app will not deliver events to the WebSocket client.
+- **JSON parse fallback**: if the response body is not valid JSON, the raw string is returned instead of a Hash. This can happen with some error responses.
+- **`client.channels.list`** returns an empty array (not nil) when no channels are active.
+
+## Source files
+
+- `lib/ruby-asterisk/ari/client.rb` — `Client` class
+- `lib/ruby-asterisk/ari/resources/channel.rb` — `Channel` resource
+- `lib/ruby-asterisk/ari/resources/bridge.rb` — `Bridge` resource
+- `lib/ruby-asterisk/ari/resources/playback.rb` — `Playback` resource
+- `lib/ruby-asterisk/ari/resources/endpoint.rb` — `Endpoint` resource
+- `lib/ruby-asterisk/ari/resources/collection.rb` — `Collection` (list/get)
+- `lib/ruby-asterisk/ari/resources/base.rb` — `Base` resource (id, data)
+- `spec/ruby-asterisk/ari/client_spec.rb`
+- `spec/ruby-asterisk/ari/resources/`