sendly 3.40.0 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 91dd6ee6db6b506dea8d70b085fc6a069330e9ddca10b1de8e097b3db07889cd
-  data.tar.gz: 3114725bc7d45361b625ba7c7cfc88b6a6eee0672154b3b3daf46237cb475b53
+  metadata.gz: 84b10285655be846bb857f5e11388a893d916838d480accfc46a646c16dd68a3
+  data.tar.gz: cfe12c76eeea0a6db834c09d97c7546260c4a313f5f6d9c64a549d467884ae3b
 SHA512:
-  metadata.gz: a8728f247769f3bbd8ad1713a86814eb419c944d64f06797ed94f858b543185d4c1baced35ba9aa910871b04a15e0348aece222a4e88de691e717df9b5542c01
-  data.tar.gz: ba2ad16077e383a0e37b7dee97ebada69cd3c1e815f6775afb677ab331a031da2f643666da3e95cc2b90e0dbff3478a6d35bc9a0364efd9b865c1ff5302f25fd
+  metadata.gz: 5c528f37943ed1c30eb8b6929097cb167ba9be070e0a8b3ec6d69949e9710a38ccbf1bdb04ce57d92a569fabdb68e56df3e50104e3ffffb620d9c6962d3e4e73
+  data.tar.gz: 73c7ba0af6ac53f75b33759b2566292f64ee5199c13f088da4ebb3b8bf68afea4b00fdddb76a0e7f3a7a1fa1547162ab94fa81a119d0b18004bce650ca6ed434

data/CHANGELOG.md

@@ -1,6 +1,24 @@
 # sendly (Ruby)
 
-## Unreleased
+## 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**.
 
 ### Breaking Changes
 
@@ -22,6 +40,120 @@
 
 - **`id` is no longer filled from an unrelated `id` key.** `contact.auto_flagged` carries the contact under `id` and the message that failed under `message_id`, so `event.data.message_id` returned the *contact* id — a handler that marked that message failed acted on the wrong row. Contact events have no message view at all now; read the message with `event.data[:message_id]`.
 
+### Migrating from 3.x
+
+Nothing outside webhook handling changed. The client, every resource and every
+`message.*` handler you already have keep working as written; the list below is
+the whole edit.
+
+**1. Reading a message field off a lifecycle event now raises.** 3.x decoded
+every `data.object` into a `Sendly::WebhookMessageData`, so an `rcs_agent.live`
+handler that asked for `event.data.from` was handed `""`, `event.data.segments`
+`1` and `event.data.credits_used` `0` — values the event never carried, not
+distinguishable from real ones, and no error was raised. The same calls raise
+`NoMethodError` in 4.0, naming the keys that did arrive. That failure is the
+point of this release rather than an accident of it: the value it replaces was
+wrong, and silently so.
+
+```ruby
+# 3.x — silently wrong, on every RCS event
+event.data.from       # => ""
+event.data.segments   # => 1
+
+# 4.0 — the same call
+event.data.from
+# => NoMethodError: undefined method 'from' for Sendly::WebhookObject:
+#    this event's data.object carries agent_id, name, stage, organization_id
+
+# 4.0 — the edit: read the object the event actually carries
+event.data[:agent_id]   # => "bb22cc33-dd44-4e55-9f66-001122334455"
+event.data.stage        # => "live"
+event.raw_object        # => the whole data.object Hash, untouched
+```
+
+**2. `event.data` is a message view only on `message.*` events.** In 3.x it was
+a `WebhookMessageData` whatever the event was, so `event.data.id` and
+`event.data.status` answered for anything — with the payload's value when the
+key happened to exist, and with `''` or `nil` when it did not. In 4.0 a
+lifecycle event's `event.data` is a `Sendly::WebhookObject`: the keys the
+payload carried are readable and nothing else is. `event.message` is new in 4.0
+and is the message view; it is `nil` outside `message.*`, so guard it with
+`event.message?` rather than calling into it unconditionally.
+
+```ruby
+# 3.x — answered for every event type; "" when the payload had no id
+mark_delivered(event.data.id)
+
+# 4.0 — split the branches
+case event.type
+when Sendly::Webhooks::EVENT_MESSAGE_DELIVERED
+  mark_delivered(event.message.id)         # same value as 3.x
+when Sendly::Webhooks::EVENT_NUMBER_ACTIVATED
+  number_active(event.data[:id])           # the number's id, as it always was
+when Sendly::Webhooks::EVENT_RCS_AGENT_LIVE
+  agent_went_live(event.data[:agent_id])   # unreachable in 3.x
+end
+```
+
+**3. `contact.auto_flagged` no longer reports the contact as the message.** The
+payload carries the contact under `id` and the message that failed under
+`message_id`; 3.x filled the message view's `id` from the contact, so a handler
+that marked "the message" failed acted on the wrong record.
+
+```ruby
+# 3.x — the CONTACT id, presented as a message id
+event.data.message_id    # => "ct_9"
+
+# 4.0
+event.data[:id]          # => "ct_9"    the contact
+event.data[:message_id]  # => "msg_77"  the message that failed
+event.message            # => nil
+```
+
+**4. Message fields the payload omitted are `nil`, not a default.** On a
+`message.*` event the readers still exist, so this raises nothing — it changes
+what you get. `key?` separates "absent" from "arrived as null".
+
+```ruby
+# message.delivered, on a payload that carried no segments
+event.data.segments          # 3.x => 1           4.0 => nil
+event.data.credits_used      # 3.x => 0           4.0 => nil
+event.data.direction         # 3.x => "outbound"  4.0 => nil
+event.data.key?(:segments)   # => false when absent, true when it arrived as null
+```
+
+**5. `event.data.to_h` is now `data.object` as it arrived.** It used to be a
+compacted subset of the typed message fields, dropping `text`, `metadata`,
+`media_urls`, `message_format` and `organization_id` and renaming `message_id`
+to `id`. Code that persisted `to_h` will start seeing the full object.
+
+```ruby
+event.data.to_h == event.raw_object   # => true, for every event type
+```
+
+**6. If you want a typed object for a lifecycle event, ask for one.**
+`#object_as` fills a Struct or Data class from the members it declares and
+ignores the rest of the payload, so a field added to the event later cannot
+break the call.
+
+```ruby
+AgentLive = Struct.new(:agent_id, :name, :stage)
+agent = event.object_as(AgentLive)
+agent.stage   # => "live"
+```
+
+### Deprecations
+
+- **`Sendly::Webhooks::EVENT_MESSAGE_QUEUED` is deprecated.** The API has never
+  emitted `message.queued`, and subscribing to it fails: `client.webhooks.create`
+  and `client.webhooks.update` reject any event outside the API's list with a
+  400, raised here as `Sendly::ValidationError`. The constant stays exported in
+  4.0 so existing code still loads, and will be removed in the next major.
+  `message.undelivered` is rejected on subscribe the same way and has never had
+  a constant in this SDK. Subscribe to `message.sent`, `message.failed` and
+  `message.bounced` instead. Every other `EVENT_*` constant matches the API's
+  list exactly.
+
 ### Minor Changes
 
 - **`Sendly::WebhookEvent#raw_object`** carries `data.object` exactly as it arrived, for every event type, and **`#object_as(klass)`** reads it as a type of your choosing (`event.object_as(AgentLive)`). `#object` is an alias for `raw_object`.
@@ -48,6 +180,11 @@
 
 - **`Sendly::ValidationError#field_errors` carries the API's `errors` list** (`[{ "path", "message" }, ...]`) when a 400 or 422 response includes one, instead of always being `nil`. RCS registration uses it to say which brand, agent, campaign or device field needs attention.
 
+
+### Security
+
+- **Path parameters are percent-encoded.** Every id you pass is now encoded (`URI.encode_www_form_component`) before it goes into the request path. An id containing `/`, `?` or `#` used to change which endpoint the request reached: an id of `../../account/keys` left its collection and hit another endpoint carrying your API key. Ordinary ids are sent byte-for-byte as before.
+
 ## 3.38.0
 
 ### Minor Changes

data/Gemfile.lock

@@ -1,14 +1,14 @@
 PATH
   remote: .
   specs:
-    sendly (3.40.0)
+    sendly (4.1.0)
       faraday (~> 2.0)
       faraday-retry (~> 2.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    addressable (2.9.0)
+    addressable (2.8.8)
       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.4)
+    webmock (3.26.1)
       addressable (>= 2.8.0)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)

data/README.md

@@ -342,6 +342,16 @@ rotation = client.webhooks.rotate_secret("whk_xxx")
 client.webhooks.delete("whk_xxx")
 ```
 
+Subscribe with the `Sendly::Webhooks::EVENT_*` constants rather than string
+literals — a typo then fails at load time instead of in a 400. Every constant
+but one names an event the API accepts on subscribe. The exception is
+`EVENT_MESSAGE_QUEUED`: `message.queued` has never been emitted and is
+rejected on subscribe with a 400 (`Sendly::ValidationError`). It is
+deprecated, kept only so existing code still loads, and will be removed in the
+next major. `message.undelivered` is rejected in the same way and has never had
+a constant here. Subscribe to `message.sent`, `message.failed` and
+`message.bounced` instead.
+
 ### Receiving events
 
 `Sendly::Webhooks.parse_event` verifies the signature and returns a
@@ -403,6 +413,66 @@ Note that `contact.auto_flagged` carries the contact under `id` and the message
 that failed under `message_id`; read the message with
 `event.data[:message_id]`.
 
+### Handling a lifecycle event
+
+Only `message.*` events carry a message. A lifecycle event — `rcs_*`,
+`whatsapp_*`, `call.*`, `brand.*`, `campaign.*`, `assignment.*`, `number.*`,
+`port*`, `contact*`, `conversation.*`, `draft.*` — carries a different object,
+so `event.message` is `nil` and you read `data.object` off `event.data` or
+`event.raw_object`.
+
+```ruby
+require "sendly"
+
+# Framework-neutral: hand it the raw request body and a headers Hash.
+def handle_sendly_webhook(raw_body, headers)
+  event = Sendly::Webhooks.parse_event(
+    raw_body,
+    headers["X-Sendly-Signature"],
+    ENV.fetch("SENDLY_WEBHOOK_SECRET"),
+    timestamp: headers["X-Sendly-Timestamp"]
+  )
+
+  case event.type
+  when Sendly::Webhooks::EVENT_RCS_AGENT_LIVE
+    # data.object is the agent: agent_id, name, stage
+    puts "RCS agent #{event.data[:name]} is #{event.data.stage}"
+    puts event.data[:agent_id]
+  when Sendly::Webhooks::EVENT_NUMBER_ACTIVATED
+    # data.object is the number: id, phone, status, country_code, source
+    puts "#{event.data[:phone]} active in #{event.data[:country_code]}"
+  when Sendly::Webhooks::EVENT_CONTACT_AUTO_FLAGGED
+    # the contact is `id`; the message that failed is `message_id`
+    puts "flagged #{event.data[:id]} (#{event.data[:invalid_reason]})"
+    puts "from message #{event.data[:message_id]}"
+  when Sendly::Webhooks::EVENT_MESSAGE_DELIVERED
+    # message.* events, and only these, also get the typed message view
+    puts "#{event.message.id} delivered to #{event.message.to}"
+  else
+    # An event type this SDK predates still parses; raw_object holds all of it.
+    puts "unhandled #{event.type}: #{event.raw_object.inspect}"
+  end
+
+  :ok
+rescue Sendly::WebhookSignatureError
+  :unauthorized
+end
+```
+
+Reading a message field off a lifecycle event fails loudly rather than
+answering with a value the event never carried:
+
+```ruby
+event.data.from
+# => NoMethodError: undefined method 'from' for Sendly::WebhookObject:
+#    this event's data.object carries agent_id, name, stage, organization_id
+event.message      # => nil
+event.message.id   # => NoMethodError — nil has no #id
+```
+
+Branch on `event.type`, or on `event.message?` / `event.verification?`, before
+reaching for a typed view.
+
 ## Account & Credits
 
 ```ruby
@@ -732,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")
@@ -1101,6 +1172,88 @@ 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 configured in
+the dashboard under Calls, then Agents; the number you call from must have
+voice switched on there (Calls, then Settings) and an emergency address
+registered before it can place outbound calls. 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 call 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, dual channel on agent calls.
+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.
+
 ## Error Handling
 
 ```ruby

data/lib/sendly/account_resource.rb

@@ -55,7 +55,7 @@ module Sendly
     # @param key_id [String] API key ID
     # @return [Sendly::ApiKey]
     def api_key(key_id)
-      response = @client.get("/account/keys/#{key_id}")
+      response = @client.get("/account/keys/#{URI.encode_www_form_component(key_id)}")
       ApiKey.new(response)
     end
 
@@ -64,7 +64,7 @@ module Sendly
     # @param key_id [String] API key ID
     # @return [Hash] Usage statistics
     def api_key_usage(key_id)
-      @client.get("/account/keys/#{key_id}/usage")
+      @client.get("/account/keys/#{URI.encode_www_form_component(key_id)}/usage")
     end
 
     # Create a new API key
@@ -96,7 +96,7 @@ module Sendly
       body = {}
       body[:reason] = reason if reason
 
-      @client.patch("/account/keys/#{key_id}/revoke", body)
+      @client.patch("/account/keys/#{URI.encode_www_form_component(key_id)}/revoke", body)
     end
 
     # Rotate an API key.
@@ -127,7 +127,7 @@ module Sendly
       body = {}
       body[:gracePeriodHours] = grace_period_hours unless grace_period_hours.nil?
 
-      @client.post("/account/keys/#{key_id}/rotate", body)
+      @client.post("/account/keys/#{URI.encode_www_form_component(key_id)}/rotate", body)
     end
 
     def transfer_credits(target_organization_id:, amount:)