sendly 3.40.0 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 91dd6ee6db6b506dea8d70b085fc6a069330e9ddca10b1de8e097b3db07889cd
-  data.tar.gz: 3114725bc7d45361b625ba7c7cfc88b6a6eee0672154b3b3daf46237cb475b53
+  metadata.gz: 40344d4fa41e8c72544b0b5327b7bc4d717285c38d244397bf0f93ad21ce5b1a
+  data.tar.gz: d0bf2bd2c6256ccdbdea1f8c9319c5891b5a030b798a091e7afc59d33752b543
 SHA512:
-  metadata.gz: a8728f247769f3bbd8ad1713a86814eb419c944d64f06797ed94f858b543185d4c1baced35ba9aa910871b04a15e0348aece222a4e88de691e717df9b5542c01
-  data.tar.gz: ba2ad16077e383a0e37b7dee97ebada69cd3c1e815f6775afb677ab331a031da2f643666da3e95cc2b90e0dbff3478a6d35bc9a0364efd9b865c1ff5302f25fd
+  metadata.gz: 20aa959ad9bd7f630c1e26b0a511648aecbfb02d095a789d2d17500e2e035eb02b79fad1c9ae6dc9e0959c41dda68d73c97b1a3d1a795f2dedacd41f8ef03262
+  data.tar.gz: 70f56c72f0b628b86e5ea964de3653b7e16d00fa9c4a5214ef14038dbf3da30feedf84b3b489bbfdfd316c42d70f4116ff6b914fe358d7204498d41601a8213a

data/CHANGELOG.md

@@ -1,6 +1,8 @@
 # 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
 
@@ -22,6 +24,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 +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.40.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

@@ -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

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
 

data/lib/sendly/enterprise.rb

@@ -22,13 +22,13 @@ module Sendly
     def get(workspace_id)
       raise ArgumentError, "Workspace ID is required" if workspace_id.nil? || workspace_id.empty?
 
-      @client.get("/enterprise/workspaces/#{workspace_id}")
+      @client.get("/enterprise/workspaces/#{URI.encode_www_form_component(workspace_id)}")
     end
 
     def delete(workspace_id)
       raise ArgumentError, "Workspace ID is required" if workspace_id.nil? || workspace_id.empty?
 
-      @client.delete("/enterprise/workspaces/#{workspace_id}")
+      @client.delete("/enterprise/workspaces/#{URI.encode_www_form_component(workspace_id)}")
     end
 
     # Submit (or resubmit) a verification for an enterprise workspace.
@@ -89,7 +89,7 @@ module Sendly
       body[:privacyUrl] = privacy_url unless privacy_url.nil?
       body[:termsUrl] = terms_url unless terms_url.nil?
 
-      @client.post("/enterprise/workspaces/#{workspace_id}/verification/submit", body)
+      @client.post("/enterprise/workspaces/#{URI.encode_www_form_component(workspace_id)}/verification/submit", body)
     end
 
     # Convenience alias for resubmits. Identical to +submit_verification+
@@ -106,7 +106,7 @@ module Sendly
       raise ArgumentError, "Workspace ID is required" if workspace_id.nil? || workspace_id.empty?
       raise ArgumentError, "Source workspace ID is required" if source_workspace_id.nil? || source_workspace_id.empty?
 
-      @client.post("/enterprise/workspaces/#{workspace_id}/verification/inherit", {
+      @client.post("/enterprise/workspaces/#{URI.encode_www_form_component(workspace_id)}/verification/inherit", {
         source_workspace_id: source_workspace_id
       })
     end
@@ -114,7 +114,7 @@ module Sendly
     def get_verification(workspace_id)
       raise ArgumentError, "Workspace ID is required" if workspace_id.nil? || workspace_id.empty?
 
-      @client.get("/enterprise/workspaces/#{workspace_id}/verification")
+      @client.get("/enterprise/workspaces/#{URI.encode_www_form_component(workspace_id)}/verification")
     end
 
     def transfer_credits(workspace_id, source_workspace_id:, amount:)
@@ -122,7 +122,7 @@ module Sendly
       raise ArgumentError, "Source workspace ID is required" if source_workspace_id.nil? || source_workspace_id.empty?
       raise ArgumentError, "Amount must be a positive number" if !amount.is_a?(Integer) || amount <= 0
 
-      @client.post("/enterprise/workspaces/#{workspace_id}/transfer-credits", {
+      @client.post("/enterprise/workspaces/#{URI.encode_www_form_component(workspace_id)}/transfer-credits", {
         source_workspace_id: source_workspace_id,
         amount: amount
       })
@@ -131,7 +131,7 @@ module Sendly
     def get_credits(workspace_id)
       raise ArgumentError, "Workspace ID is required" if workspace_id.nil? || workspace_id.empty?
 
-      @client.get("/enterprise/workspaces/#{workspace_id}/credits")
+      @client.get("/enterprise/workspaces/#{URI.encode_www_form_component(workspace_id)}/credits")
     end
 
     def create_key(workspace_id, name: nil, type: nil)
@@ -141,26 +141,26 @@ module Sendly
       body[:name] = name if name
       body[:type] = type if type
 
-      @client.post("/enterprise/workspaces/#{workspace_id}/keys", body)
+      @client.post("/enterprise/workspaces/#{URI.encode_www_form_component(workspace_id)}/keys", body)
     end
 
     def list_keys(workspace_id)
       raise ArgumentError, "Workspace ID is required" if workspace_id.nil? || workspace_id.empty?
 
-      @client.get("/enterprise/workspaces/#{workspace_id}/keys")
+      @client.get("/enterprise/workspaces/#{URI.encode_www_form_component(workspace_id)}/keys")
     end
 
     def revoke_key(workspace_id, key_id)
       raise ArgumentError, "Workspace ID is required" if workspace_id.nil? || workspace_id.empty?
       raise ArgumentError, "Key ID is required" if key_id.nil? || key_id.empty?
 
-      @client.delete("/enterprise/workspaces/#{workspace_id}/keys/#{key_id}")
+      @client.delete("/enterprise/workspaces/#{URI.encode_www_form_component(workspace_id)}/keys/#{URI.encode_www_form_component(key_id)}")
     end
 
     def list_opt_in_pages(workspace_id)
       raise ArgumentError, "Workspace ID is required" if workspace_id.nil? || workspace_id.empty?
 
-      @client.get("/enterprise/workspaces/#{workspace_id}/opt-in-pages")
+      @client.get("/enterprise/workspaces/#{URI.encode_www_form_component(workspace_id)}/opt-in-pages")
     end
 
     def create_opt_in_page(workspace_id, business_name:, use_case: nil, use_case_summary: nil, sample_messages: nil)
@@ -172,7 +172,7 @@ module Sendly
       body[:useCaseSummary] = use_case_summary if use_case_summary
       body[:sampleMessages] = sample_messages if sample_messages
 
-      @client.post("/enterprise/workspaces/#{workspace_id}/opt-in-pages", body)
+      @client.post("/enterprise/workspaces/#{URI.encode_www_form_component(workspace_id)}/opt-in-pages", body)
     end
 
     def update_opt_in_page(workspace_id, page_id, logo_url: nil, header_color: nil, button_color: nil, custom_headline: nil, custom_benefits: nil)
@@ -186,14 +186,14 @@ module Sendly
       body[:customHeadline] = custom_headline unless custom_headline.nil?
       body[:customBenefits] = custom_benefits unless custom_benefits.nil?
 
-      @client.patch("/enterprise/workspaces/#{workspace_id}/opt-in-pages/#{page_id}", body)
+      @client.patch("/enterprise/workspaces/#{URI.encode_www_form_component(workspace_id)}/opt-in-pages/#{URI.encode_www_form_component(page_id)}", body)
     end
 
     def delete_opt_in_page(workspace_id, page_id)
       raise ArgumentError, "Workspace ID is required" if workspace_id.nil? || workspace_id.empty?
       raise ArgumentError, "Page ID is required" if page_id.nil? || page_id.empty?
 
-      @client.delete("/enterprise/workspaces/#{workspace_id}/opt-in-pages/#{page_id}")
+      @client.delete("/enterprise/workspaces/#{URI.encode_www_form_component(workspace_id)}/opt-in-pages/#{URI.encode_www_form_component(page_id)}")
     end
 
     def set_webhook(workspace_id, url:, events: nil, description: nil)
@@ -204,19 +204,19 @@ module Sendly
       body[:events] = events if events
       body[:description] = description if description
 
-      @client.put("/enterprise/workspaces/#{workspace_id}/webhooks", body)
+      @client.put("/enterprise/workspaces/#{URI.encode_www_form_component(workspace_id)}/webhooks", body)
     end
 
     def list_webhooks(workspace_id)
       raise ArgumentError, "Workspace ID is required" if workspace_id.nil? || workspace_id.empty?
 
-      @client.get("/enterprise/workspaces/#{workspace_id}/webhooks")
+      @client.get("/enterprise/workspaces/#{URI.encode_www_form_component(workspace_id)}/webhooks")
     end
 
     def delete_webhooks(workspace_id, webhook_id: nil)
       raise ArgumentError, "Workspace ID is required" if workspace_id.nil? || workspace_id.empty?
 
-      path = "/enterprise/workspaces/#{workspace_id}/webhooks"
+      path = "/enterprise/workspaces/#{URI.encode_www_form_component(workspace_id)}/webhooks"
       path += "?webhookId=#{webhook_id}" if webhook_id
 
       @client.delete(path)
@@ -225,7 +225,7 @@ module Sendly
     def test_webhook(workspace_id)
       raise ArgumentError, "Workspace ID is required" if workspace_id.nil? || workspace_id.empty?
 
-      @client.post("/enterprise/workspaces/#{workspace_id}/webhooks/test")
+      @client.post("/enterprise/workspaces/#{URI.encode_www_form_component(workspace_id)}/webhooks/test")
     end
 
     def suspend(workspace_id, reason: nil)
@@ -234,13 +234,13 @@ module Sendly
       body = {}
       body[:reason] = reason if reason
 
-      @client.post("/enterprise/workspaces/#{workspace_id}/suspend", body)
+      @client.post("/enterprise/workspaces/#{URI.encode_www_form_component(workspace_id)}/suspend", body)
     end
 
     def resume(workspace_id)
       raise ArgumentError, "Workspace ID is required" if workspace_id.nil? || workspace_id.empty?
 
-      @client.post("/enterprise/workspaces/#{workspace_id}/resume")
+      @client.post("/enterprise/workspaces/#{URI.encode_www_form_component(workspace_id)}/resume")
     end
 
     def provision_bulk(workspaces)
@@ -255,7 +255,7 @@ module Sendly
       raise ArgumentError, "Page ID is required" if page_id.nil? || page_id.empty?
       raise ArgumentError, "Domain is required" if domain.nil? || domain.empty?
 
-      @client.put("/enterprise/workspaces/#{workspace_id}/pages/#{page_id}/domain", { domain: domain })
+      @client.put("/enterprise/workspaces/#{URI.encode_www_form_component(workspace_id)}/pages/#{URI.encode_www_form_component(page_id)}/domain", { domain: domain })
     end
 
     def send_invitation(workspace_id, email:, role:)
@@ -263,7 +263,7 @@ module Sendly
       raise ArgumentError, "Email is required" if email.nil? || email.empty?
       raise ArgumentError, "Role is required" if role.nil? || role.empty?
 
-      @client.post("/enterprise/workspaces/#{workspace_id}/invitations", {
+      @client.post("/enterprise/workspaces/#{URI.encode_www_form_component(workspace_id)}/invitations", {
         email: email,
         role: role
       })
@@ -272,26 +272,26 @@ module Sendly
     def list_invitations(workspace_id)
       raise ArgumentError, "Workspace ID is required" if workspace_id.nil? || workspace_id.empty?
 
-      @client.get("/enterprise/workspaces/#{workspace_id}/invitations")
+      @client.get("/enterprise/workspaces/#{URI.encode_www_form_component(workspace_id)}/invitations")
     end
 
     def cancel_invitation(workspace_id, invite_id)
       raise ArgumentError, "Workspace ID is required" if workspace_id.nil? || workspace_id.empty?
       raise ArgumentError, "Invite ID is required" if invite_id.nil? || invite_id.empty?
 
-      @client.delete("/enterprise/workspaces/#{workspace_id}/invitations/#{invite_id}")
+      @client.delete("/enterprise/workspaces/#{URI.encode_www_form_component(workspace_id)}/invitations/#{URI.encode_www_form_component(invite_id)}")
     end
 
     def get_quota(workspace_id)
       raise ArgumentError, "Workspace ID is required" if workspace_id.nil? || workspace_id.empty?
 
-      @client.get("/enterprise/workspaces/#{workspace_id}/quota")
+      @client.get("/enterprise/workspaces/#{URI.encode_www_form_component(workspace_id)}/quota")
     end
 
     def set_quota(workspace_id, monthly_message_quota:)
       raise ArgumentError, "Workspace ID is required" if workspace_id.nil? || workspace_id.empty?
 
-      @client.put("/enterprise/workspaces/#{workspace_id}/quota", {
+      @client.put("/enterprise/workspaces/#{URI.encode_www_form_component(workspace_id)}/quota", {
         monthlyMessageQuota: monthly_message_quota
       })
     end

data/lib/sendly/templates_resource.rb

@@ -129,7 +129,7 @@ module Sendly
     end
 
     def get(id)
-      response = @client.get("/templates/#{id}")
+      response = @client.get("/templates/#{URI.encode_www_form_component(id)}")
       Template.new(response)
     end
 
@@ -198,16 +198,16 @@ module Sendly
       request_body[:name] = name if name
       request_body[:text] = content if content
 
-      response = @client.patch("/templates/#{id}", request_body)
+      response = @client.patch("/templates/#{URI.encode_www_form_component(id)}", request_body)
       Template.new(response)
     end
 
     def delete(id)
-      @client.delete("/templates/#{id}")
+      @client.delete("/templates/#{URI.encode_www_form_component(id)}")
     end
 
     def publish(id)
-      response = @client.post("/templates/#{id}/publish")
+      response = @client.post("/templates/#{URI.encode_www_form_component(id)}/publish")
       Template.new(response)
     end
 
@@ -217,7 +217,7 @@ module Sendly
     #   this call fails with a 404. To retire a published template today,
     #   {#create} and {#publish} a replacement, then {#delete} this one.
     def unpublish(id)
-      response = @client.post("/templates/#{id}/unpublish")
+      response = @client.post("/templates/#{URI.encode_www_form_component(id)}/unpublish")
       Template.new(response)
     end
 
@@ -229,7 +229,7 @@ module Sendly
     def clone(id, name: nil)
       body = {}
       body[:name] = name if name
-      response = @client.post("/templates/#{id}/clone", body)
+      response = @client.post("/templates/#{URI.encode_www_form_component(id)}/clone", body)
       Template.new(response)
     end
 

data/lib/sendly/verify.rb

@@ -181,17 +181,17 @@ module Sendly
     end
 
     def resend(id)
-      response = @client.post("/verify/#{id}/resend")
+      response = @client.post("/verify/#{URI.encode_www_form_component(id)}/resend")
       SendVerificationResponse.new(response)
     end
 
     def check(id, code:)
-      response = @client.post("/verify/#{id}/check", { code: code })
+      response = @client.post("/verify/#{URI.encode_www_form_component(id)}/check", { code: code })
       CheckVerificationResponse.new(response)
     end
 
     def get(id)
-      response = @client.get("/verify/#{id}")
+      response = @client.get("/verify/#{URI.encode_www_form_component(id)}")
       Verification.new(response)
     end
 

data/lib/sendly/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Sendly
-  VERSION = "3.40.0"
+  VERSION = "4.0.0"
 end

data/lib/sendly/webhooks_resource.rb

@@ -51,7 +51,7 @@ module Sendly
     # @return [Sendly::Webhook]
     def get(webhook_id)
       validate_webhook_id!(webhook_id)
-      response = @client.get("/webhooks/#{webhook_id}")
+      response = @client.get("/webhooks/#{URI.encode_www_form_component(webhook_id)}")
       Webhook.new(response)
     end
 
@@ -77,7 +77,7 @@ module Sendly
       body[:mode] = mode unless mode.nil?
       body[:metadata] = metadata unless metadata.nil?
 
-      response = @client.patch("/webhooks/#{webhook_id}", body)
+      response = @client.patch("/webhooks/#{URI.encode_www_form_component(webhook_id)}", body)
       Webhook.new(response)
     end
 
@@ -87,7 +87,7 @@ module Sendly
     # @return [void]
     def delete(webhook_id)
       validate_webhook_id!(webhook_id)
-      @client.delete("/webhooks/#{webhook_id}")
+      @client.delete("/webhooks/#{URI.encode_www_form_component(webhook_id)}")
       nil
     end
 
@@ -97,7 +97,7 @@ module Sendly
     # @return [Sendly::WebhookTestResult]
     def test(webhook_id)
       validate_webhook_id!(webhook_id)
-      response = @client.post("/webhooks/#{webhook_id}/test")
+      response = @client.post("/webhooks/#{URI.encode_www_form_component(webhook_id)}/test")
       WebhookTestResult.new(response)
     end
 
@@ -107,7 +107,7 @@ module Sendly
     # @return [Hash] Reset confirmation with updated webhook
     def reset_circuit(webhook_id)
       validate_webhook_id!(webhook_id)
-      @client.post("/webhooks/#{webhook_id}/reset-circuit")
+      @client.post("/webhooks/#{URI.encode_www_form_component(webhook_id)}/reset-circuit")
     end
 
     # Replay failed or cancelled webhook deliveries from the audit log.
@@ -133,7 +133,7 @@ module Sendly
       body[:event_types] = event_types unless event_types.nil?
       body[:statuses] = statuses unless statuses.nil?
       body[:limit] = limit unless limit.nil?
-      @client.post("/webhooks/#{webhook_id}/redeliver", body)
+      @client.post("/webhooks/#{URI.encode_www_form_component(webhook_id)}/redeliver", body)
     end
 
     # Backfill missed webhook events from the underlying message log.
@@ -157,7 +157,7 @@ module Sendly
       body[:until] = until_ unless until_.nil?
       body[:event_types] = event_types unless event_types.nil?
       body[:limit] = limit unless limit.nil?
-      @client.post("/webhooks/#{webhook_id}/backfill", body)
+      @client.post("/webhooks/#{URI.encode_www_form_component(webhook_id)}/backfill", body)
     end
 
     # Rotate the webhook signing secret
@@ -166,7 +166,7 @@ module Sendly
     # @return [Sendly::WebhookSecretRotation]
     def rotate_secret(webhook_id)
       validate_webhook_id!(webhook_id)
-      response = @client.post("/webhooks/#{webhook_id}/rotate-secret")
+      response = @client.post("/webhooks/#{URI.encode_www_form_component(webhook_id)}/rotate-secret")
       WebhookSecretRotation.new(response)
     end
 
@@ -176,7 +176,7 @@ module Sendly
     # @return [Array<Sendly::WebhookDelivery>]
     def deliveries(webhook_id)
       validate_webhook_id!(webhook_id)
-      response = @client.get("/webhooks/#{webhook_id}/deliveries")
+      response = @client.get("/webhooks/#{URI.encode_www_form_component(webhook_id)}/deliveries")
       response.map { |data| WebhookDelivery.new(data) }
     end
 
@@ -188,7 +188,7 @@ module Sendly
     def retry_delivery(webhook_id, delivery_id)
       validate_webhook_id!(webhook_id)
       validate_delivery_id!(delivery_id)
-      @client.post("/webhooks/#{webhook_id}/deliveries/#{delivery_id}/retry")
+      @client.post("/webhooks/#{URI.encode_www_form_component(webhook_id)}/deliveries/#{URI.encode_www_form_component(delivery_id)}/retry")
       nil
     end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sendly
 version: !ruby/object:Gem::Version
-  version: 3.40.0
+  version: 4.0.0
 platform: ruby
 authors:
 - Sendly
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2026-09-09 00:00:00.000000000 Z
+date: 2026-09-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday