sendly 3.39.0 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c474ade97511ceecadbff15268b602edb67953395417996e9c1ac8b7626e68ff
-  data.tar.gz: b034a8b316eab9f85e98de49e31db3045326662beeefbafb306844302a147037
+  metadata.gz: 40344d4fa41e8c72544b0b5327b7bc4d717285c38d244397bf0f93ad21ce5b1a
+  data.tar.gz: d0bf2bd2c6256ccdbdea1f8c9319c5891b5a030b798a091e7afc59d33752b543
 SHA512:
-  metadata.gz: 10f0a1eecb587b5c0b801c1abb5366d41caaa4fecf7e274ac3a37860d82bbdf92ca644280a419626391d0fce53679c35172a66aca3f26893d780bb499321c15c
-  data.tar.gz: 0221a6cfd5de361ff4648b4b4e0256ceccf4bab50e3b44b2616cd2200c136c2acd27409c3b20a99f2f81176663e0e272664a07d07f113d29d2b2064a0546bd33
+  metadata.gz: 20aa959ad9bd7f630c1e26b0a511648aecbfb02d095a789d2d17500e2e035eb02b79fad1c9ae6dc9e0959c41dda68d73c97b1a3d1a795f2dedacd41f8ef03262
+  data.tar.gz: 70f56c72f0b628b86e5ea964de3653b7e16d00fa9c4a5214ef14038dbf3da30feedf84b3b489bbfdfd316c42d70f4116ff6b914fe358d7204498d41601a8213a

data/CHANGELOG.md

@@ -1,9 +1,151 @@
 # sendly (Ruby)
 
-## Unreleased
+## 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
+
+- **A webhook that is not a message is no longer presented as one.** `parse_event` built a `Sendly::WebhookMessageData` out of every `data.object`, whatever the event was. For an `rcs_*`, `whatsapp_*`, `call.*`, `brand.*`, `campaign.*`, `assignment.*`, `number.*`, `port*`, `contact*`, `conversation.*` or `draft.*` payload that dropped every field the event actually carried — `agent_id`, `stage`, `port_request_id`, `duration_secs` and the rest were unreachable — and filled the gaps with message fields that were never sent. `event.data` is now a `Sendly::WebhookObject`, a hash-like view of `data.object`: read a key with `[]` (String or Symbol), a reader method of the same name, or `to_h`. `event.message` is the message view and is `nil` for all of the above; `message.*` events are unchanged, and `event.data` is still the `WebhookMessageData` there.
+
+  ```ruby
+  # before — "" for every RCS event, and the agent was unreachable
+  event.data.from
+  # after
+  event.data[:agent_id]   # => "bb22cc33-..."
+  event.message           # => nil
+  ```
+
+- **Absent fields are `nil` instead of a plausible-looking default.** `WebhookMessageData` defaulted `segments` to `1`, `credits_used` to `0`, `direction` to `"outbound"`, `from` to `""` and `id` to `""`, none of which a handler could tell from a real value. They are now `nil` when the payload did not carry them, and `data.key?(:segments)` says which case you are in. `WebhookVerificationData` loses the same kind of defaults (`delivery_status` `"queued"`, `attempts` `0`, `max_attempts` `3`), though nothing could reach that class before this release.
+
+- **JSON `null` survives as `nil`.** `from` and `to` on a `call.*` event are `null` for every in-app call; `from` used to arrive as `""`. Code branching on `from.empty?` should branch on `nil` now.
+
+- **`event.data.to_h` returns `data.object` as it arrived.** It used to return a compacted subset of the typed message fields, which dropped `text`, `metadata`, `media_urls`, `message_format` and `organization_id`, renamed `message_id` to `id`, and emitted the invented `segments`/`credits_used` defaults. `event.to_h[:data]` is the same hash. For a current-shape payload the familiar keys are all still there.
+
+- **`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`.
+
+- **`Sendly::WebhookVerificationData` is reachable.** Nothing ever constructed it, and it read String keys while `parse_event` symbolizes names, so it could not have worked if anything had. `verification.*` events now build one, as `event.verification` and `event.data`, and every reader takes String or Symbol keys.
+
+- **`Sendly::WebhookEvent` gains `#message?` and `#verification?`** for the two cases that have a typed view.
+
 - **`Sendly::ValidationError#field_errors` is now populated.** It was always `nil` before, because the API path never passed it. It now carries the response body's `errors` array on any 400 or 422, on every resource rather than just RCS: `client.contacts.import` already returns one, for example. Each entry is a Hash. Code that treats a truthy `field_errors` as "this only happens for X" should be rechecked.
 
 
@@ -22,6 +164,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.39.0)
+    sendly (4.0.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

@@ -308,6 +308,8 @@ Full details: https://sendly.live/docs/idempotency
 
 ## Webhooks
 
+### Managing endpoints
+
 ```ruby
 # Create a webhook endpoint
 webhook = client.webhooks.create(
@@ -340,6 +342,137 @@ 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
+`Sendly::WebhookEvent`. Pass the raw request body — not a re-serialized hash,
+which would no longer match the signature.
+
+```ruby
+event = Sendly::Webhooks.parse_event(
+  request.raw_post,
+  request.headers["X-Sendly-Signature"],
+  ENV.fetch("SENDLY_WEBHOOK_SECRET"),
+  timestamp: request.headers["X-Sendly-Timestamp"]
+)
+```
+
+`event.raw_object` is `data.object` exactly as it arrived, for every event
+type. `event.data` is a hash-like view of the same object: read a key with
+`[]` (String or Symbol), a reader method of the same name, or `to_h`.
+
+```ruby
+case event.type
+when Sendly::Webhooks::EVENT_MESSAGE_DELIVERED
+  # message.* events also get a typed message view
+  puts "#{event.message.id} -> #{event.message.to}"
+when Sendly::Webhooks::EVENT_RCS_AGENT_LIVE
+  puts event.data[:agent_id]
+  puts event.data.stage
+when Sendly::Webhooks::EVENT_CALL_COMPLETED
+  puts event.data[:duration_secs]
+end
+
+# Or read data.object as a type of your own. A Struct or Data class is filled
+# from the members it declares and ignores the rest of the payload, so a field
+# added to the event later cannot break the call.
+AgentLive = Struct.new(:agent_id, :name, :stage)
+agent = event.object_as(AgentLive)
+```
+
+Two things the SDK will not do, because both make a handler act on data that
+was never sent:
+
+- **Nothing is invented.** A field the payload did not carry is `nil`, and
+  `event.data.key?(:segments)` is `false`. `segments`, `credits_used`,
+  `direction`, `to` and `from` are no longer defaulted to `1`, `0`,
+  `"outbound"` and `""`.
+- **`nil` stays `nil`.** An in-app `call.*` event carries `from` and `to` as
+  JSON `null`; they come back as `nil`, not `""`.
+
+`event.message` is the message view and is `nil` for every event that is not a
+message — `rcs_*`, `whatsapp_*`, `call.*`, `brand.*`, `campaign.*`,
+`assignment.*`, `number.*`, `port*`, `contact*`, `conversation.*` and
+`draft.*`, whose payloads are not message-shaped. `verification.*` events get
+`event.verification`, a `Sendly::WebhookVerificationData`. `event.data` is the
+typed view where one exists and a plain `Sendly::WebhookObject` otherwise, so
+reading `data.object` works the same way for all of them, including an event
+type this SDK predates.
+
+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

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:)

data/lib/sendly/campaigns_resource.rb

@@ -131,7 +131,7 @@ module Sendly
     end
 
     def get(id)
-      response = @client.get("/campaigns/#{id}")
+      response = @client.get("/campaigns/#{URI.encode_www_form_component(id)}")
       Campaign.new(response)
     end
 
@@ -142,21 +142,21 @@ module Sendly
       body[:templateId] = template_id unless template_id.nil?
       body[:contactListIds] = contact_list_ids if contact_list_ids
 
-      response = @client.patch("/campaigns/#{id}", body)
+      response = @client.patch("/campaigns/#{URI.encode_www_form_component(id)}", body)
       Campaign.new(response)
     end
 
     def delete(id)
-      @client.delete("/campaigns/#{id}")
+      @client.delete("/campaigns/#{URI.encode_www_form_component(id)}")
     end
 
     def preview(id)
-      response = @client.get("/campaigns/#{id}/preview")
+      response = @client.get("/campaigns/#{URI.encode_www_form_component(id)}/preview")
       CampaignPreview.new(response)
     end
 
     def send_campaign(id)
-      response = @client.post("/campaigns/#{id}/send")
+      response = @client.post("/campaigns/#{URI.encode_www_form_component(id)}/send")
       Campaign.new(response)
     end
 
@@ -164,17 +164,17 @@ module Sendly
       body = { scheduledAt: scheduled_at }
       body[:timezone] = timezone if timezone
 
-      response = @client.post("/campaigns/#{id}/schedule", body)
+      response = @client.post("/campaigns/#{URI.encode_www_form_component(id)}/schedule", body)
       Campaign.new(response)
     end
 
     def cancel(id)
-      response = @client.post("/campaigns/#{id}/cancel")
+      response = @client.post("/campaigns/#{URI.encode_www_form_component(id)}/cancel")
       Campaign.new(response)
     end
 
     def clone(id)
-      response = @client.post("/campaigns/#{id}/clone")
+      response = @client.post("/campaigns/#{URI.encode_www_form_component(id)}/clone")
       Campaign.new(response)
     end
   end

data/lib/sendly/contacts_resource.rb

@@ -114,7 +114,7 @@ module Sendly
       params[:limit] = limit if limit
       params[:offset] = offset if offset
 
-      response = @client.get("/contact-lists/#{id}", params)
+      response = @client.get("/contact-lists/#{URI.encode_www_form_component(id)}", params)
       ContactList.new(response)
     end
 
@@ -131,21 +131,21 @@ module Sendly
       body[:name] = name if name
       body[:description] = description unless description.nil?
 
-      response = @client.patch("/contact-lists/#{id}", body)
+      response = @client.patch("/contact-lists/#{URI.encode_www_form_component(id)}", body)
       ContactList.new(response)
     end
 
     def delete(id)
-      @client.delete("/contact-lists/#{id}")
+      @client.delete("/contact-lists/#{URI.encode_www_form_component(id)}")
     end
 
     def add_contacts(list_id, contact_ids)
-      response = @client.post("/contact-lists/#{list_id}/contacts", { contact_ids: contact_ids })
+      response = @client.post("/contact-lists/#{URI.encode_www_form_component(list_id)}/contacts", { contact_ids: contact_ids })
       { added_count: response["added_count"] || response["addedCount"] }
     end
 
     def remove_contact(list_id, contact_id)
-      @client.delete("/contact-lists/#{list_id}/contacts/#{contact_id}")
+      @client.delete("/contact-lists/#{URI.encode_www_form_component(list_id)}/contacts/#{URI.encode_www_form_component(contact_id)}")
     end
   end
 
@@ -175,7 +175,7 @@ module Sendly
     end
 
     def get(id)
-      response = @client.get("/contacts/#{id}")
+      response = @client.get("/contacts/#{URI.encode_www_form_component(id)}")
       Contact.new(response)
     end
 
@@ -195,12 +195,12 @@ module Sendly
       body[:email] = email unless email.nil?
       body[:metadata] = metadata unless metadata.nil?
 
-      response = @client.patch("/contacts/#{id}", body)
+      response = @client.patch("/contacts/#{URI.encode_www_form_component(id)}", body)
       Contact.new(response)
     end
 
     def delete(id)
-      @client.delete("/contacts/#{id}")
+      @client.delete("/contacts/#{URI.encode_www_form_component(id)}")
     end
 
     # Clear the invalid flag on a contact so future campaigns include it again.
@@ -208,7 +208,7 @@ module Sendly
     # error (landline, invalid number) or when a carrier lookup reports they
     # can't receive SMS.
     def mark_valid(id)
-      response = @client.post("/contacts/#{id}/mark-valid", {})
+      response = @client.post("/contacts/#{URI.encode_www_form_component(id)}/mark-valid", {})
       Contact.new(response)
     end