sendly 4.0.0 → 4.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 40344d4fa41e8c72544b0b5327b7bc4d717285c38d244397bf0f93ad21ce5b1a
-  data.tar.gz: d0bf2bd2c6256ccdbdea1f8c9319c5891b5a030b798a091e7afc59d33752b543
+  metadata.gz: 6e04f0698b7520abcb9cd17816198b7e728ab2ce6d2ed1d564195887334dca82
+  data.tar.gz: 9f26320067a3fe83a7035364cdf6682e03f9b93bf26996faf728cbfb9899065c
 SHA512:
-  metadata.gz: 20aa959ad9bd7f630c1e26b0a511648aecbfb02d095a789d2d17500e2e035eb02b79fad1c9ae6dc9e0959c41dda68d73c97b1a3d1a795f2dedacd41f8ef03262
-  data.tar.gz: 70f56c72f0b628b86e5ea964de3653b7e16d00fa9c4a5214ef14038dbf3da30feedf84b3b489bbfdfd316c42d70f4116ff6b914fe358d7204498d41601a8213a
+  metadata.gz: 2b3ec03a21b0eae75affd32ee962e3e33a4481f1b5b23e656d5633ebeef18f0302168343943a5b74f45176609566229dcccead196d939f73e43a7c19aa676c77
+  data.tar.gz: f7d9d7f44fd1fe7aa99d53dcfbfdba8be8fb25e15d0ccdefda67488d7ea5552c04199f5a91287bab73b703192b1ae5860bb6c80fe23085bc2d4bb98d28f5ba2a

data/CHANGELOG.md

@@ -1,5 +1,39 @@
 # sendly (Ruby)
 
+## 4.2.0
+
+### Minor Changes
+
+- **Voice configuration: `client.voice`.** Everything a phone call depends on is now configurable from code over the new `/api/v1/voice` routes. `client.voice.numbers` has `list`, `get(number)`, `update(number, voice_enabled:, voice_mode:, agent_id:)` and `register_emergency_address(number, street:, city:, state:, zip:, unit: nil, country: nil)`: switch voice on for a number, choose how it answers (`Sendly::VoiceNumber::VOICE_MODES`), and register the emergency address a US or Canadian number needs before it can place calls ($1.50 a month; registering again replaces the address without a second charge). `number` is the number's id or its E.164 phone number, and `agent_id: nil` clears the stored agent. `client.voice.agents` has `list`, `create(name:, ...)`, `get(id)`, `update(id, ...)` and `delete(id)` for the AI agents that answer and place calls (up to 20 per workspace, each holding its own scoped sending key); `tools:` takes `send_sms` and `transfer_to` in snake_case or camelCase. `client.voice.voices.list` lists the voices agents can speak with. Lists are Enumerable (`Sendly::VoiceNumberList`, `Sendly::VoiceAgentList`, `Sendly::VoiceList`); the models are `Sendly::VoiceNumber` (with `Sendly::VoiceNumberEmergencyAddress`, `Sendly::EmergencyAddress` and `Sendly::VoiceNumberRates`), `Sendly::VoiceAgent` (with `Sendly::VoiceAgentTools`), `Sendly::Voice` and `Sendly::DeletedVoiceAgent`. POSTs send the client's usual `Idempotency-Key`, and every write accepts `idempotency_key:`. Reads need the `calls:read` scope, writes `calls:write` and a live key; in a team workspace, number changes also need a role that can change settings and agent changes a role that can manage API keys. Deleting an agent that still answers a number raises `Sendly::APIError` (409 `agent_in_use`). `Sendly::Call::ERROR_CODES` gains `agent_in_use`, `agent_limit`, `invalid_voice_mode`, `invalid_address`, `e911_not_applicable`, `voice_attach_failed`, `carrier_refused`, `invalid_request` and `insufficient_permissions`.
+
+  ```ruby
+  agent = client.voice.agents.create(name: "Front desk", tools: { send_sms: true })
+  client.voice.numbers.update("+15555550188", voice_enabled: true, voice_mode: "agent", agent_id: agent.id)
+  ```
+
+- **`Sendly::Error#response_body`** is the parsed JSON body of the API error response, for refusals that carry more than a message: a 409 `agent_in_use` lists the numbers the agent still answers under `"numbers"`, and a 422 `invalid_address` carries a corrected address (or `nil`) under `"suggested"`. It is `nil` for errors raised before a request is sent.
+- **`Sendly::Client#delete` accepts `idempotency_key:`**, like `patch` and `put`.
+
+### Patch Changes
+
+- **The `Sendly::CallRecording` docstring had the channels the wrong way round.** Agent-handled calls are recorded with the agent on the left channel and the other party on the right.
+
+## 4.1.0
+
+### Minor Changes
+
+- **Voice calls: `client.calls`.** Place phone calls handled by your AI agents, list and inspect them, end one early and fetch recordings, over the new `/api/v1/calls` routes. `create(to:, agent_id:, from: nil, context: nil, metadata: nil)` returns a `Sendly::Call` that is `ringing`; `list` takes `limit:`, `offset:`, `status:`, `direction:`, `kind:`, `agent_id:`, `to:` and `from:` and returns an Enumerable `Sendly::CallList` with `total`, `limit`, `offset` and `has_more?`; `get(id)` adds the `transcript` (an array of `Sendly::CallTranscriptLine`) on agent-handled calls and leaves it `nil` otherwise; `hangup(id)` cancels a ringing call or completes an active one and returns an already-ended call unchanged; `recording(id)` returns a `Sendly::CallRecording` whose signed `url` is set only while `ready?` and expires after five minutes. `create` and `hangup` send the client's usual `Idempotency-Key` and accept `idempotency_key:`. `Sendly::Call` also reads the snake_case object carried by the `call.started`, `call.completed` and `call.recording.ready` webhooks, including the new `billing` and `metadata` keys. Vocabularies are published as `Sendly::Call::STATUSES`, `::HANGUP_CLASSES` and `::ERROR_CODES`. `Sendly::PhoneNumber` gains `voice_enabled` (with `voice_enabled?`), `voice_mode` (`Sendly::PhoneNumber::VOICE_MODES`) and `raw`, so `client.numbers.list` can pick the `from` number for a call. Reads need the `calls:read` scope; writes need `calls:write` and a live key. Voice is enabled workspace by workspace: until it is on for yours the routes answer 404 `voice_not_enabled`, which raises `Sendly::NotFoundError`.
+
+  ```ruby
+  call = client.calls.create(
+    to: "+15555550123",
+    agent_id: "3c4d5e6f-7081-4293-a4b5-c6d7e8f90a1b",
+    context: "Confirm the 3pm appointment on Tuesday."
+  )
+  call = client.calls.get(call.id)
+  call.transcript&.each { |line| puts "#{line.speaker}: #{line.text}" }
+  ```
+
 ## 4.0.0
 
 **Upgrading from 3.40.0:** that release already contained the breaking changes below, published by mistake as a minor version. 4.0.0 carries them under the correct major. Relative to 3.40.0, the only new changes are under **Security**.

data/Gemfile.lock

@@ -1,14 +1,14 @@
 PATH
   remote: .
   specs:
-    sendly (4.0.0)
+    sendly (4.2.0)
       faraday (~> 2.0)
       faraday-retry (~> 2.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    addressable (2.8.8)
+    addressable (2.9.0)
       public_suffix (>= 2.0.2, < 8.0)
     ast (2.4.3)
     bigdecimal (3.3.1)
@@ -74,7 +74,7 @@ GEM
       unicode-emoji (~> 4.1)
     unicode-emoji (4.1.0)
     uri (1.1.1)
-    webmock (3.26.1)
+    webmock (3.26.4)
       addressable (>= 2.8.0)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)

data/README.md

@@ -802,6 +802,7 @@ end
 # Get one number you own (includes is_default, which the list omits)
 number = client.numbers.get('num_abc123')
 puts "#{number.phone_number} — default sender: #{number.is_default}"
+puts "voice: #{number.voice_enabled?} (#{number.voice_mode})"
 
 # Update a number — make it the default sender (must be active),
 # and/or cancel a scheduled release ("keep this number")
@@ -1171,6 +1172,173 @@ client.messages.send(
 )
 ```
 
+## Voice Calls
+
+Place phone calls that one of your AI agents handles, list and inspect
+calls, end a call early, and download recordings. Agents are created with
+`client.voice.agents` or in the dashboard under Calls, then Agents; the
+number you call from must have voice switched on and an emergency address
+registered before it can place outbound calls (see
+[Configure voice](#configure-voice), or Calls, then Settings in the
+dashboard). Each `Sendly::PhoneNumber`
+from `client.numbers.list` carries `voice_enabled?` and `voice_mode`
+(`"none"`, `"ring_dashboard"` or `"agent"`) so you can pick a `from`:
+
+```ruby
+from = client.numbers.list[:numbers].find(&:voice_enabled?)&.phone_number
+```
+
+Calls are prepaid from your credit balance per started minute: 2 credits a
+minute outbound, plus 8 a minute while an AI agent is on the call (10 in
+total for an API-placed call). Unanswered calls cost nothing. Destinations
+are US and Canadian numbers. Reads need the `calls:read` scope; `create`
+and `hangup` need `calls:write` and a live key.
+
+> **Rolling out.** Voice is enabled workspace by workspace. Until it is on
+> for yours, every `client.calls` and `client.voice` method raises
+> `Sendly::NotFoundError` (`voice_not_enabled`).
+
+```ruby
+# Place a call. Returns at once with the call ringing; the agent greets the
+# callee when they answer and uses `context` for this call only.
+call = client.calls.create(
+  to: "+15555550123",
+  agent_id: "3c4d5e6f-7081-4293-a4b5-c6d7e8f90a1b",
+  from: "+15555550188",                # optional when you have one voice number
+  context: "Confirm the 3pm appointment on Tuesday.",
+  metadata: { "crmId" => "lead_8812" } # up to 20 string pairs, echoed everywhere
+)
+puts call.id
+puts call.status        # "ringing"
+puts call.handled_by    # "agent"
+
+# Follow it. Agent-handled calls include a transcript once fetched by id.
+call = client.calls.get(call.id)
+puts call.status        # "ringing" -> "active" -> "completed" (or no_answer, busy, ...)
+puts call.hangup_class  # why it ended, e.g. "agent_agent_hangup"
+puts call.credits_charged
+call.transcript&.each { |line| puts "#{line.speaker}: #{line.text}" }
+
+# List (newest first; limit 1-100, default 50)
+page = client.calls.list(status: "completed", direction: "outbound", agent_id: call.agent_id, limit: 20)
+page.each { |c| puts "#{c.to} #{c.duration_secs}s #{c.credits_charged} credits" }
+puts page.total
+puts page.has_more?
+
+# End a call. Ringing -> "cancelled", active -> "completed"; a call that
+# has already ended comes back unchanged.
+client.calls.hangup(call.id)
+
+# Recording. The URL is signed and valid for five minutes; it is nil until
+# the recording is ready. Ogg/Opus; agent calls are dual channel, with the
+# agent on the left channel and the other party on the right.
+rec = client.calls.recording(call.id)
+if rec.ready?
+  File.binwrite("#{call.id}.ogg", Net::HTTP.get(URI(rec.url)))
+end
+```
+
+Call errors map onto the usual classes: `Sendly::InsufficientCreditsError`
+when the balance cannot cover one minute at the agent rate;
+`Sendly::NotFoundError` for `voice_not_enabled`, `outbound_calls_not_enabled`,
+`agent_not_found`, `number_not_found` and `call_not_found`;
+`Sendly::ValidationError` for `invalid_number`, `destination_not_supported`,
+`agent_required`, `invalid_metadata` and `from_number_required`;
+`Sendly::RateLimitError` for `daily_call_limit`; `Sendly::APIError` with
+`status_code` 428 for `e911_required` (register an emergency address for the
+number), 409 for `agent_disabled`, `no_voice_number` and `lines_busy` (retry
+shortly), or 403 for `live_key_required` and a key missing the scope; and
+`Sendly::ServerError` (a sibling of `APIError`, not a subclass) for 503
+`voice_unavailable` / `agents_unavailable` and 500 `voice_internal_error`.
+The full list is `Sendly::Call::ERROR_CODES`; the hangup vocabulary is
+`Sendly::Call::HANGUP_CLASSES`.
+
+`call.started`, `call.completed` and `call.recording.ready` webhooks carry
+the same object in snake_case (`handled_by`, `hangup_class`, `billing`,
+`metadata`, ...); `Sendly::Call.new(event.raw_object)` reads it.
+
+### Configure voice
+
+Everything a call depends on is configurable from code with `client.voice`:
+switch voice on for a number and choose how it answers, register the
+number's emergency address, and create the AI agents that talk. Reads need
+the `calls:read` scope; writes need `calls:write` and a live key. In a team
+workspace, changing a number or its emergency address also needs a role that
+can change settings, and managing agents a role that can manage API keys
+(each agent holds its own scoped sending key).
+
+```ruby
+# Numbers. Pass the number's id or its E.164 phone number.
+client.voice.numbers.list.each do |n|
+  puts "#{n.phone_number} #{n.voice_mode} #{n.emergency_address&.status || 'no emergency address'}"
+end
+number = client.voice.numbers.get("+15555550188")
+puts number.rate_per_minute.agent   # credits a minute when an agent answers
+
+# A US or Canadian number needs an emergency address before it can place
+# calls. The first registration adds $1.50 a month to the number;
+# registering again replaces the address without a second charge.
+number = client.voice.numbers.register_emergency_address(
+  "+15555550188",
+  street: "500 Example Ave",
+  unit: "Suite 2",
+  city: "Austin",
+  state: "TX",
+  zip: "78701"                      # country: defaults to "US"
+)
+puts number.emergency_address.status
+
+# Voices and agents. An agent answers real callers on any number pointed at it.
+client.voice.voices.list.each { |v| puts "#{v.id}: #{v.label}" }
+
+agent = client.voice.agents.create(
+  name: "Front desk",
+  voice: "ashley",
+  greeting: "Thanks for calling Acme, how can I help?",
+  instructions: "Answer questions about opening hours and take a message for anything else.",
+  tools: { send_sms: true }         # snake_case or camelCase keys
+)
+puts agent.can_send_sms?            # true once it holds its scoped sending key
+client.voice.agents.update(agent.id, greeting: "Thanks for calling Acme. How can I help today?")
+client.voice.agents.list.each { |a| puts "#{a.name}: #{a.calls_handled} calls" }
+
+# Switching voice on changes how real calls to the number are answered.
+client.voice.numbers.update("+15555550188", voice_enabled: true, voice_mode: "agent", agent_id: agent.id)
+client.voice.numbers.update("+15555550188", voice_mode: "ring_dashboard") # ring the team instead
+client.voice.numbers.update("+15555550188", voice_enabled: false)         # switch voice off
+
+# An agent that answers a number can't be deleted until the number is moved.
+begin
+  client.voice.agents.delete(agent.id)
+rescue Sendly::APIError => e
+  raise unless e.response_body&.dig("error") == "agent_in_use"
+
+  puts "Still answers #{e.response_body['numbers'].join(', ')}"
+end
+```
+
+A mode alone is enough: `voice_mode: "agent"` or `"ring_dashboard"` switches
+voice on, so it can fail the way switching on does, and `voice_mode: "none"`
+switches it off. `voice_enabled: false` wins over any mode, and
+`voice_enabled: true` with `"none"` answers in `"ring_dashboard"` mode.
+
+Configuration errors map the same way: `Sendly::NotFoundError` for
+`number_not_found` and `agent_not_found`; `Sendly::ValidationError` for
+`invalid_request` (for example an emergency address field that is not a
+string), `invalid_voice_mode`, `agent_required`,
+`e911_not_applicable` and `invalid_address` (a 422 `invalid_address` means
+the address could not be validated, and `e.response_body["suggested"]` holds
+a corrected address when one was found); `Sendly::APIError` with
+`status_code` 409 for `agent_disabled`, `agent_limit` (20 agents per
+workspace) and `agent_in_use`; and `Sendly::ServerError` for 502
+`voice_attach_failed` and `carrier_refused` and 503 `voice_unavailable`,
+raised after the client has already retried the 5xx on its own. Not every
+`carrier_refused` is worth retrying: when the message says the number
+couldn't be found for emergency registration, retrying won't help, so
+contact support. When it says the address couldn't be registered or
+emergency calling couldn't be switched on, try again later. Every API error
+keeps the parsed body on `e.response_body`.
+
 ## Error Handling
 
 ```ruby

data/lib/sendly/calls_resource.rb

@@ -0,0 +1,413 @@
+# frozen_string_literal: true
+
+module Sendly
+  # One line of what was said on an agent-handled call. +speaker+ is
+  # "caller" or "agent"; +at_ms+ is the offset from the start of the call.
+  class CallTranscriptLine
+    SPEAKERS = %w[caller agent].freeze
+
+    attr_reader :speaker, :text, :at_ms
+
+    def initialize(data)
+      data ||= {}
+      @speaker = data["speaker"]
+      @text = data["text"]
+      @at_ms = data["atMs"] || data["at_ms"]
+    end
+
+    def to_h
+      { speaker: speaker, text: text, at_ms: at_ms }.compact
+    end
+  end
+
+  # A phone call placed or received by one of your workspace's numbers.
+  #
+  # +kind+ is "pstn" for a phone call and "internal" for a browser-to-browser
+  # call between teammates. +status+ is "ringing" or "active" while the call
+  # is live and one of the terminal values ("completed", "no_answer", "busy",
+  # "cancelled", "declined", "failed") once it has ended; "suspended" can
+  # appear on an internal call whose media dropped and may recover.
+  # +handled_by+ says whether an AI agent ("agent") or the team in the
+  # dashboard ("dashboard") took the call. +billing+ is "metered" while a
+  # phone call is charged per started minute, "settled" once it has ended,
+  # and "unbilled" for calls that are never charged. +hangup_class+ says why
+  # the call ended (see {HANGUP_CLASSES}); anything unrecognised arrives as
+  # "ended". +metadata+ is the string map attached on create (+{}+ when
+  # none). +transcript+ is only present on {CallsResource#get} for
+  # agent-handled calls and is +nil+ otherwise.
+  class Call
+    STATUSES = %w[ringing active completed no_answer busy cancelled declined failed suspended].freeze
+    LIVE_STATUSES = %w[ringing active].freeze
+    DIRECTIONS = %w[inbound outbound].freeze
+    KINDS = %w[pstn internal].freeze
+    HANDLED_BY = %w[agent dashboard].freeze
+    BILLING_STATES = %w[metered settled unbilled].freeze
+    RECORDING_STATUSES = %w[recording ready failed].freeze
+    HANGUP_CLASSES = %w[
+      normal caller_hung_up callee_hung_up caller_left peer_left agent_ended
+      agent_agent_hangup agent_caller_left
+      ring_timeout callee_declined callee_busy caller_cancelled room_closed_unanswered
+      agent_left_unanswered agent_caller_never_joined invalid_number destination_rejected
+      max_duration credits_exhausted media_aborted peer_connection_lost room_closed agent_left
+      setup_failed agent_dispatch_failed agent_api_unreachable agent_already_ended
+      ended
+    ].freeze
+    ERROR_CODES = %w[
+      voice_unavailable agents_unavailable voice_not_enabled outbound_calls_not_enabled
+      agent_required agent_not_found agent_disabled invalid_metadata from_number_required
+      no_voice_number number_not_found destination_not_supported e911_required lines_busy
+      daily_call_limit call_not_found live_key_required voice_internal_error
+      insufficient_credits invalid_number rate_limit_exceeded forbidden
+      invalid_request insufficient_permissions agent_in_use agent_limit invalid_voice_mode
+      invalid_address e911_not_applicable voice_attach_failed carrier_refused
+    ].freeze
+
+    attr_reader :id, :object, :kind, :direction, :status, :handled_by, :agent_id,
+                :from, :to, :caller_name, :callee_name, :started_at, :answered_at,
+                :ended_at, :duration_secs, :credits_charged, :billing, :hangup_class,
+                :recording_status, :metadata, :transcript
+
+    # @return [Hash] The raw parsed response
+    attr_reader :raw
+
+    def initialize(data)
+      data ||= {}
+      @raw = data
+      @id = data["id"]
+      @object = data["object"] || "call"
+      @kind = data["kind"]
+      @direction = data["direction"]
+      @status = data["status"]
+      @handled_by = data["handledBy"] || data["handled_by"]
+      @agent_id = data["agentId"] || data["agent_id"]
+      @from = data["from"]
+      @to = data["to"]
+      @caller_name = data["callerName"] || data["caller_name"]
+      @callee_name = data["calleeName"] || data["callee_name"]
+      @started_at = data["startedAt"] || data["started_at"]
+      @answered_at = data["answeredAt"] || data["answered_at"]
+      @ended_at = data["endedAt"] || data["ended_at"]
+      @duration_secs = data["durationSecs"] || data["duration_secs"] || 0
+      @credits_charged = data["creditsCharged"] || data["credits_charged"] || 0
+      @billing = data["billing"]
+      @hangup_class = data["hangupClass"] || data["hangup_class"]
+      @recording_status = data["recordingStatus"] || data["recording_status"]
+      @metadata = data["metadata"] || {}
+      lines = data["transcript"]
+      @transcript = lines.is_a?(Array) ? lines.map { |l| CallTranscriptLine.new(l) } : nil
+    end
+
+    # @return [Boolean] Whether the call is still ringing or in progress
+    def live?
+      LIVE_STATUSES.include?(status)
+    end
+
+    # @return [Boolean] Whether the call has reached a terminal status
+    def ended?
+      !status.nil? && !live? && status != "suspended"
+    end
+
+    def answered?
+      !answered_at.nil?
+    end
+
+    def agent_handled?
+      handled_by == "agent"
+    end
+
+    def inbound?
+      direction == "inbound"
+    end
+
+    def outbound?
+      direction == "outbound"
+    end
+
+    def to_h
+      {
+        id: id, object: object, kind: kind, direction: direction, status: status,
+        handled_by: handled_by, agent_id: agent_id, from: from, to: to,
+        caller_name: caller_name, callee_name: callee_name, started_at: started_at,
+        answered_at: answered_at, ended_at: ended_at, duration_secs: duration_secs,
+        credits_charged: credits_charged, billing: billing, hangup_class: hangup_class,
+        recording_status: recording_status, metadata: metadata,
+        transcript: transcript&.map(&:to_h)
+      }.compact
+    end
+  end
+
+  # A page of calls, newest first, with the pagination the API returned.
+  class CallList
+    include Enumerable
+
+    attr_reader :data, :total, :limit, :offset, :has_more
+
+    def initialize(response)
+      @data = (response["data"] || []).map { |c| Call.new(c) }
+      pagination = response["pagination"] || {}
+      @total = pagination["total"] || @data.length
+      @limit = pagination["limit"] || 50
+      @offset = pagination["offset"] || 0
+      @has_more = pagination["hasMore"] || pagination["has_more"] || false
+    end
+
+    def has_more?
+      has_more == true
+    end
+
+    def each(&block)
+      data.each(&block)
+    end
+
+    def count
+      data.length
+    end
+
+    alias size count
+    alias length count
+
+    def empty?
+      data.empty?
+    end
+
+    def first
+      data.first
+    end
+
+    def last
+      data.last
+    end
+  end
+
+  # The recording of a call. +status+ is "none" when there is no recording
+  # (recording off, or the call was never answered), "recording" while the
+  # call runs, "ready" once it can be fetched, or "failed". +url+ and
+  # +expires_at+ are set only when {#ready?}: the URL is signed and valid for
+  # five minutes. Recordings are Ogg/Opus (+content_type+ "audio/ogg");
+  # agent-handled calls are recorded dual-channel, with the agent on the
+  # left channel and the other party on the right.
+  class CallRecording
+    STATUSES = %w[none recording ready failed].freeze
+
+    attr_reader :call_id, :status, :url, :expires_at, :content_type
+
+    def initialize(data)
+      data ||= {}
+      @call_id = data["callId"] || data["call_id"]
+      @status = data["status"]
+      @url = data["url"]
+      @expires_at = data["expiresAt"] || data["expires_at"]
+      @content_type = data["contentType"] || data["content_type"]
+    end
+
+    def ready?
+      status == "ready"
+    end
+
+    def to_h
+      {
+        call_id: call_id, status: status, url: url, expires_at: expires_at,
+        content_type: content_type
+      }.compact
+    end
+  end
+
+  # Calls resource: place phone calls handled by your AI agents, list and
+  # inspect calls, end a call and fetch recordings.
+  #
+  # A call placed over the API is answered by one of your AI agents
+  # (create them with {VoiceAgentsResource#create} or in the dashboard
+  # under Calls, then Agents); the +from+ number must have voice switched
+  # on ({VoiceNumbersResource#update} or the dashboard). Calls are charged per
+  # started minute from your credit balance: 2 credits a minute outbound,
+  # plus 8 a minute while an agent is on the call. Destinations are US and
+  # Canadian numbers. Reads need the +calls:read+ scope, writes
+  # +calls:write+ and a live API key (+sk_live_v1_xxx+).
+  #
+  # Voice is enabled workspace by workspace. Until it is on for yours,
+  # every method here raises {Sendly::NotFoundError} (+voice_not_enabled+).
+  #
+  # Error codes map onto the usual classes: {Sendly::NotFoundError} for
+  # +voice_not_enabled+, +outbound_calls_not_enabled+, +agent_not_found+,
+  # +number_not_found+ and +call_not_found+; {Sendly::ValidationError} for
+  # +invalid_number+, +destination_not_supported+, +agent_required+,
+  # +invalid_metadata+ and +from_number_required+;
+  # {Sendly::InsufficientCreditsError} for +insufficient_credits+;
+  # {Sendly::RateLimitError} for +daily_call_limit+ and
+  # +rate_limit_exceeded+; {Sendly::APIError} with the HTTP status for
+  # +e911_required+ (428), +agent_disabled+ / +no_voice_number+ /
+  # +lines_busy+ (409) and +live_key_required+ / +forbidden+ (403); and
+  # {Sendly::ServerError} (not an +APIError+) for +voice_unavailable+ /
+  # +agents_unavailable+ (503) and +voice_internal_error+ (500). The full
+  # list is {Call::ERROR_CODES}.
+  #
+  # @example Place a call and wait for it to end
+  #   call = client.calls.create(
+  #     to: "+15555550123",
+  #     agent_id: "3c4d5e6f-7081-4293-a4b5-c6d7e8f90a1b",
+  #     context: "Confirm the 3pm appointment on Tuesday."
+  #   )
+  #   call = client.calls.get(call.id) while call.live? && sleep(2)
+  #   puts call.hangup_class
+  #   call.transcript.each { |line| puts "#{line.speaker}: #{line.text}" }
+  class CallsResource
+    def initialize(client)
+      @client = client
+    end
+
+    # Place a phone call that one of your AI agents handles. Returns at once
+    # with the call +ringing+; poll {#get} or subscribe to the +call.started+
+    # and +call.completed+ webhooks to follow it. Requires the +calls:write+
+    # scope and a live key.
+    #
+    # @param to [String] The number to call, in E.164 format (US or Canada)
+    # @param agent_id [String] The AI agent that talks on the call
+    # @param from [String, nil] A voice-enabled number in your workspace.
+    #   Optional when the workspace has exactly one; required (the API
+    #   responds 400 +from_number_required+) when it has more.
+    # @param context [String, nil] Up to 2000 characters appended to the
+    #   agent's instructions for this call only. Not echoed back.
+    # @param metadata [Hash{String => String}, nil] Up to 20 string pairs
+    #   (keys 1-40 characters of +A-Z a-z 0-9 _ . : -+, values up to 500
+    #   characters). Stored, echoed on every read and in every +call.*+
+    #   webhook.
+    # @param idempotency_key [String, nil] Idempotency key for this operation
+    # @return [Sendly::Call] The new call (+status+ "ringing", +handled_by+ "agent")
+    # @raise [Sendly::ValidationError] If +to+ or +agent_id+ is missing, or
+    #   HTTP 400 (+invalid_number+, +destination_not_supported+,
+    #   +agent_required+, +invalid_metadata+, +from_number_required+)
+    # @raise [Sendly::NotFoundError] HTTP 404 (+voice_not_enabled+,
+    #   +outbound_calls_not_enabled+, +agent_not_found+, +number_not_found+)
+    # @raise [Sendly::InsufficientCreditsError] HTTP 402 when the balance
+    #   cannot cover one minute at the agent rate
+    # @raise [Sendly::APIError] HTTP 428 +e911_required+ (register an
+    #   emergency address for the number first with
+    #   {VoiceNumbersResource#register_emergency_address}), 409 +agent_disabled+ /
+    #   +no_voice_number+ / +lines_busy+, 403 +live_key_required+
+    # @raise [Sendly::RateLimitError] HTTP 429 +daily_call_limit+ / +rate_limit_exceeded+
+    # @raise [Sendly::ServerError] HTTP 503 +voice_unavailable+ /
+    #   +agents_unavailable+ (calling is not switched on for this deployment),
+    #   HTTP 500 +voice_internal_error+
+    #
+    # @example
+    #   call = client.calls.create(
+    #     to: "+15555550123",
+    #     agent_id: "3c4d5e6f-7081-4293-a4b5-c6d7e8f90a1b",
+    #     from: "+15555550188",
+    #     metadata: { "crmId" => "lead_8812" }
+    #   )
+    #   puts call.id
+    def create(to:, agent_id:, from: nil, context: nil, metadata: nil, idempotency_key: nil)
+      raise ValidationError, "to is required" if to.nil? || to.to_s.empty?
+      raise ValidationError, "agent_id is required" if agent_id.nil? || agent_id.to_s.empty?
+
+      body = { to: to, agentId: agent_id }
+      body[:from] = from unless from.nil?
+      body[:context] = context unless context.nil?
+      body[:metadata] = metadata unless metadata.nil?
+
+      response = @client.post("/calls", body, idempotency_key: idempotency_key)
+      Call.new(response)
+    end
+
+    # List your workspace's calls, newest first. Live rows are reconciled
+    # before they are returned, so a ring past its deadline reads as
+    # +no_answer+. Requires the +calls:read+ scope.
+    #
+    # @param limit [Integer, nil] Calls per page (1-100, default 50)
+    # @param offset [Integer, nil] Calls to skip (default 0)
+    # @param status [String, nil] One of {Call::STATUSES}
+    # @param direction [String, nil] "inbound" or "outbound"
+    # @param kind [String, nil] "pstn" or "internal"
+    # @param agent_id [String, nil] Only calls handled by this agent
+    # @param to [String, nil] Exact E.164 match on the called number
+    # @param from [String, nil] Exact E.164 match on the calling number
+    # @return [Sendly::CallList] The page and its pagination
+    # @raise [Sendly::ValidationError] HTTP 400 +invalid_request+ for a value
+    #   outside the vocabularies above
+    #
+    # @example
+    #   page = client.calls.list(status: "completed", direction: "outbound", limit: 20)
+    #   page.each { |c| puts "#{c.to} #{c.duration_secs}s #{c.credits_charged} credits" }
+    #   puts page.has_more?
+    def list(limit: nil, offset: nil, status: nil, direction: nil, kind: nil,
+             agent_id: nil, to: nil, from: nil)
+      params = {}
+      params[:limit] = limit unless limit.nil?
+      params[:offset] = offset unless offset.nil?
+      params[:status] = status unless status.nil?
+      params[:direction] = direction unless direction.nil?
+      params[:kind] = kind unless kind.nil?
+      params[:agentId] = agent_id unless agent_id.nil?
+      params[:to] = to unless to.nil?
+      params[:from] = from unless from.nil?
+
+      response = @client.get("/calls", params)
+      CallList.new(response)
+    end
+
+    # Fetch one call. Agent-handled calls include their +transcript+; a live
+    # call is reconciled first. Requires the +calls:read+ scope.
+    #
+    # @param id [String] Call identifier
+    # @return [Sendly::Call]
+    # @raise [Sendly::NotFoundError] HTTP 404 +call_not_found+ when the call
+    #   is not in your workspace
+    #
+    # @example
+    #   call = client.calls.get("6f1c2d3e-4a5b-4c6d-8e9f-0a1b2c3d4e5f")
+    #   call.transcript&.each { |line| puts "#{line.speaker}: #{line.text}" }
+    def get(id)
+      encoded_id = encode_id!(id)
+      response = @client.get("/calls/#{encoded_id}")
+      Call.new(response)
+    end
+
+    # End a call. A ringing call becomes +cancelled+ (+hangup_class+
+    # "caller_cancelled") and the callee stops ringing; an active call
+    # becomes +completed+ ("normal"). Hanging up a call that has already
+    # ended returns it unchanged. Requires the +calls:write+ scope and a
+    # live key.
+    #
+    # @param id [String] Call identifier
+    # @param idempotency_key [String, nil] Idempotency key for this operation
+    # @return [Sendly::Call] The call after the hangup
+    # @raise [Sendly::NotFoundError] HTTP 404 +call_not_found+
+    #
+    # @example
+    #   call = client.calls.hangup(call.id)
+    #   puts call.status # "cancelled" or "completed"
+    def hangup(id, idempotency_key: nil)
+      encoded_id = encode_id!(id)
+      response = @client.post("/calls/#{encoded_id}/hangup", {}, idempotency_key: idempotency_key)
+      Call.new(response)
+    end
+
+    # Fetch the recording of a call. +url+ is a signed link valid for five
+    # minutes and is only set once the recording is +ready?+; fetch again
+    # for a fresh link. Requires the +calls:read+ scope.
+    #
+    # @param id [String] Call identifier
+    # @return [Sendly::CallRecording]
+    # @raise [Sendly::NotFoundError] HTTP 404 +call_not_found+
+    #
+    # @example
+    #   rec = client.calls.recording(call.id)
+    #   if rec.ready?
+    #     File.binwrite("#{call.id}.ogg", Net::HTTP.get(URI(rec.url)))
+    #   end
+    def recording(id)
+      encoded_id = encode_id!(id)
+      response = @client.get("/calls/#{encoded_id}/recording")
+      CallRecording.new(response)
+    end
+
+    private
+
+    def encode_id!(id)
+      raise ValidationError, "Call ID is required" if id.nil? || id.to_s.empty?
+
+      URI.encode_www_form_component(id)
+    end
+  end
+end