sendly 3.39.0 → 3.40.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c474ade97511ceecadbff15268b602edb67953395417996e9c1ac8b7626e68ff
-  data.tar.gz: b034a8b316eab9f85e98de49e31db3045326662beeefbafb306844302a147037
+  metadata.gz: 91dd6ee6db6b506dea8d70b085fc6a069330e9ddca10b1de8e097b3db07889cd
+  data.tar.gz: 3114725bc7d45361b625ba7c7cfc88b6a6eee0672154b3b3daf46237cb475b53
 SHA512:
-  metadata.gz: 10f0a1eecb587b5c0b801c1abb5366d41caaa4fecf7e274ac3a37860d82bbdf92ca644280a419626391d0fce53679c35172a66aca3f26893d780bb499321c15c
-  data.tar.gz: 0221a6cfd5de361ff4648b4b4e0256ceccf4bab50e3b44b2616cd2200c136c2acd27409c3b20a99f2f81176663e0e272664a07d07f113d29d2b2064a0546bd33
+  metadata.gz: a8728f247769f3bbd8ad1713a86814eb419c944d64f06797ed94f858b543185d4c1baced35ba9aa910871b04a15e0348aece222a4e88de691e717df9b5542c01
+  data.tar.gz: ba2ad16077e383a0e37b7dee97ebada69cd3c1e815f6775afb677ab331a031da2f643666da3e95cc2b90e0dbff3478a6d35bc9a0364efd9b865c1ff5302f25fd

data/CHANGELOG.md

@@ -2,8 +2,34 @@
 
 ## Unreleased
 
+### 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]`.
+
 ### 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.
 
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    sendly (3.39.0)
+    sendly (3.40.0)
       faraday (~> 2.0)
       faraday-retry (~> 2.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,67 @@ rotation = client.webhooks.rotate_secret("whk_xxx")
 client.webhooks.delete("whk_xxx")
 ```
 
+### 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]`.
+
 ## Account & Credits
 
 ```ruby

data/lib/sendly/version.rb

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

data/lib/sendly/webhooks.rb

@@ -20,9 +20,13 @@ module Sendly
   #
   #         case event.type
   #         when 'message.delivered'
-  #           puts "Message delivered: #{event.data.id}"
+  #           puts "Message delivered: #{event.message.id}"
   #         when 'message.failed'
-  #           puts "Message failed: #{event.data.error}"
+  #           puts "Message failed: #{event.message.error}"
+  #         when 'rcs_agent.live'
+  #           # A lifecycle payload is not message-shaped. event.message is nil
+  #           # for it; read data.object through event.data or event.raw_object.
+  #           puts "RCS agent live: #{event.data[:agent_id]}"
   #         end
   #
   #         head :ok
@@ -36,9 +40,13 @@ module Sendly
 
     # Webhook event type string constants. Use these when subscribing
     # instead of string literals so you catch typos at load time.
+    # Deprecated: the API has never emitted this and rejects it when you
+    # subscribe. It will be removed in the next major version.
     EVENT_MESSAGE_QUEUED                = "message.queued"
+
     EVENT_MESSAGE_SENT                  = "message.sent"
     EVENT_MESSAGE_DELIVERED             = "message.delivered"
+    EVENT_MESSAGE_READ                  = "message.read"
     EVENT_MESSAGE_FAILED                = "message.failed"
     EVENT_MESSAGE_BOUNCED               = "message.bounced"
     EVENT_MESSAGE_RETRYING              = "message.retrying"
@@ -52,6 +60,11 @@ module Sendly
     EVENT_VERIFICATION_FAILED           = "verification.failed"
     EVENT_VERIFICATION_RESENT           = "verification.resent"
     EVENT_VERIFICATION_DELIVERY_FAILED  = "verification.delivery_failed"
+    EVENT_CONVERSATION_CREATED          = "conversation.created"
+    EVENT_CONVERSATION_UPDATED          = "conversation.updated"
+    EVENT_DRAFT_CREATED                 = "draft.created"
+    EVENT_DRAFT_APPROVED                = "draft.approved"
+    EVENT_DRAFT_REJECTED                = "draft.rejected"
     EVENT_CONTACT_AUTO_FLAGGED          = "contact.auto_flagged"
     EVENT_CONTACT_MARKED_VALID          = "contact.marked_valid"
     EVENT_CONTACTS_LOOKUP_COMPLETED     = "contacts.lookup_completed"
@@ -63,6 +76,12 @@ module Sendly
     EVENT_CAMPAIGN_SUSPENDED            = "campaign.suspended"
     EVENT_ASSIGNMENT_CONFIRMED          = "assignment.confirmed"
     EVENT_ASSIGNMENT_FAILED             = "assignment.failed"
+    EVENT_RCS_BRAND_VERIFIED            = "rcs_brand.verified"
+    EVENT_RCS_BRAND_FAILED              = "rcs_brand.failed"
+    EVENT_RCS_AGENT_TESTING             = "rcs_agent.testing"
+    EVENT_RCS_AGENT_LIVE                = "rcs_agent.live"
+    EVENT_RCS_AGENT_REJECTED            = "rcs_agent.rejected"
+    EVENT_RCS_AGENT_ACTION_REQUIRED     = "rcs_agent.action_required"
     EVENT_PORT_COMPLETED                = "port.completed"
     EVENT_PORT_OUT_REQUESTED            = "port_out.requested"
     EVENT_PORT_OUT_COMPLETED            = "port_out.completed"
@@ -72,6 +91,14 @@ module Sendly
     EVENT_NUMBER_FAILED                 = "number.failed"
     EVENT_NUMBER_REQUIREMENTS_REQUIRED  = "number.requirements_required"
     EVENT_NUMBER_RELEASED               = "number.released"
+    EVENT_WHATSAPP_ACCOUNT_CONNECTED    = "whatsapp_account.connected"
+    EVENT_WHATSAPP_ACCOUNT_FAILED       = "whatsapp_account.failed"
+    EVENT_WHATSAPP_TEMPLATE_APPROVED    = "whatsapp_template.approved"
+    EVENT_WHATSAPP_TEMPLATE_REJECTED    = "whatsapp_template.rejected"
+    EVENT_WHATSAPP_TEMPLATE_PAUSED      = "whatsapp_template.paused"
+    EVENT_CALL_STARTED                  = "call.started"
+    EVENT_CALL_COMPLETED                = "call.completed"
+    EVENT_CALL_RECORDING_READY          = "call.recording.ready"
 
     # Source of a list-health event. Frozen enum — new values will be
     # added in minor SDK versions, never removed.
@@ -163,105 +190,369 @@ module Sendly
     end
   end
 
-  class WebhookEvent
-    attr_reader :id, :type, :data, :created, :api_version, :livemode
+  # A hash-like view of a webhook event's +data.object+.
+  #
+  # Every key the payload carried is reachable — by +[]+ with a String or a
+  # Symbol, by {#to_h}, or as a reader method of the same name — and nothing
+  # else is. A key the payload did not carry is absent rather than filled in
+  # with a plausible-looking default, and a key that arrived as JSON +null+
+  # stays +nil+.
+  #
+  # @example An rcs_agent.live payload
+  #   event.data[:agent_id]    # => "bb22cc33-dd44-4e55-9f66-001122334455"
+  #   event.data.stage         # => "live"
+  #   event.data.key?(:from)   # => false — an RCS agent event has no from
+  class WebhookObject
+    include Enumerable
 
-    def initialize(data)
-      @id = data[:id]
-      @type = data[:type]
-      obj = data[:data][:object] || data[:data]
-      @data = WebhookMessageData.new(obj)
-      @created = data[:created] || data[:created_at] || 0
-      @api_version = data[:api_version] || '2024-01'
-      @livemode = data[:livemode] || false
+    # Names that must keep Ruby's meaning even if a payload carries them as a
+    # key. Overriding these on an instance breaks object identity, equality or
+    # dispatch, so a reader is never defined for them — reach those keys with
+    # +[]+, +fetch+ or +to_h+, which always read the payload.
+    RESERVED = %i[
+      __send__ __id__ object_id class singleton_class method methods
+      instance_variable_get instance_variable_set instance_variables
+      respond_to? equal? is_a? kind_of? instance_of? nil? tap raw
+    ].freeze
+
+    # @return [Hash] +data.object+ exactly as it arrived
+    attr_reader :raw
+
+    # @param raw [Hash] the parsed +data.object+
+    def initialize(raw = {})
+      @raw = raw.is_a?(Hash) ? raw : {}
+      define_payload_readers
     end
 
-    def created_at
-      @created
+    # @param key [String, Symbol]
+    # @return [Object, nil] nil when the payload did not carry the key
+    def [](key)
+      resolved = resolve_key(key)
+      resolved.nil? ? nil : @raw[resolved]
+    end
+
+    # @param key [String, Symbol]
+    # @return [Object] the value, the default, or the block's result
+    # @raise [KeyError] if the key is absent and no default was given
+    def fetch(key, *default, &block)
+      resolved = resolve_key(key)
+      return @raw[resolved] unless resolved.nil?
+      return default.first unless default.empty?
+      return block.call(key) if block
+
+      raise KeyError, "key not found: #{key.inspect}"
+    end
+
+    def dig(key, *rest)
+      value = self[key]
+      return value if rest.empty? || value.nil?
+
+      value.dig(*rest)
     end
 
+    # @return [Boolean] whether the payload carried this key at all. Use it to
+    #   tell "absent" from "arrived as null".
+    def key?(key)
+      !resolve_key(key).nil?
+    end
+    alias has_key? key?
+
+    def keys
+      @raw.keys
+    end
+
+    def values
+      @raw.values
+    end
+
+    def each(&block)
+      @raw.each(&block)
+    end
+
+    def empty?
+      @raw.empty?
+    end
+
+    def size
+      @raw.size
+    end
+    alias length size
+
+    # @return [Hash] a copy of +data.object+. Absent keys stay absent and
+    #   nulls stay nil; nothing is added.
     def to_h
-      {
-        id: @id,
-        type: @type,
-        data: @data.to_h,
-        created: @created,
-        api_version: @api_version,
-        livemode: @livemode
-      }
+      @raw.dup
+    end
+
+    def ==(other)
+      case other
+      when WebhookObject then @raw == other.raw
+      when Hash then @raw == other
+      else false
+      end
+    end
+
+    def inspect
+      "#<#{self.class.name} #{@raw.inspect}>"
+    end
+
+    # @return [Array<Symbol>] payload keys that cannot be read as a method
+    #   because doing so would override Ruby's own semantics. Read them with
+    #   +[]+ instead.
+    def reserved_keys
+      @raw.keys.map { |k| k.to_sym rescue nil }.compact & RESERVED
+    end
+
+    private
+
+    # Payload keys win over inherited methods.
+    #
+    # Reader access used to go through method_missing, which only fires when
+    # nothing else answers — so any key colliding with an Object or Enumerable
+    # method was silently shadowed. `contacts.bulk_marked_valid` really carries
+    # `count`, so `event.data.count` returned the NUMBER OF KEYS instead of the
+    # value, and respond_to?(:count) was true, giving the caller no signal.
+    # Defining a singleton reader per key makes the payload authoritative.
+    def define_payload_readers
+      singleton = singleton_class
+      @raw.each_key do |key|
+        name = begin
+          key.to_sym
+        rescue StandardError
+          next
+        end
+        next if RESERVED.include?(name)
+        next unless name.to_s.match?(/\A[A-Za-z_][A-Za-z0-9_]*[?!]?\z/)
+
+        singleton.define_method(name) { @raw[key] }
+      end
+    end
+
+    def resolve_key(key)
+      return key if @raw.key?(key)
+
+      case key
+      when Symbol then @raw.key?(key.to_s) ? key.to_s : nil
+      when String then @raw.key?(key.to_sym) ? key.to_sym : nil
+      end
+    end
+
+    def method_missing(name, *args, &block)
+      key = args.empty? && block.nil? ? resolve_key(name) : nil
+      return @raw[key] unless key.nil?
+
+      carries = @raw.empty? ? 'no fields' : @raw.keys.map(&:to_s).join(', ')
+      raise NoMethodError.new(
+        "undefined method '#{name}' for #{self.class.name}: " \
+        "this event's data.object carries #{carries}",
+        name
+      )
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      !resolve_key(name).nil? || super
     end
   end
 
-  class WebhookMessageData
+  # The message view of +data.object+, built only for +message.*+ events.
+  #
+  # Readers return exactly what the payload carried. An absent field is +nil+:
+  # this class does not invent +segments+, +credits_used+, +direction+, +to+
+  # or +from+.
+  class WebhookMessageData < WebhookObject
     attr_reader :id, :status, :to, :from, :direction, :organization_id,
                 :text, :error, :error_code, :delivered_at, :failed_at,
-                :created_at, :segments, :credits_used, :message_format, :media_urls,
-                :retry_count, :metadata, :batch_id
-
-    def initialize(data)
-      @id = data[:id] || data[:message_id] || ''
-      @status = data[:status]
-      @to = data[:to]
-      @from = data[:from] || ''
-      @direction = data[:direction] || 'outbound'
-      @organization_id = data[:organization_id]
-      @text = data[:text]
-      @error = data[:error]
-      @error_code = data[:error_code]
-      @delivered_at = data[:delivered_at]
-      @failed_at = data[:failed_at]
-      @created_at = data[:created_at]
-      @segments = data[:segments] || 1
-      @credits_used = data[:credits_used] || 0
-      @message_format = data[:message_format]
-      @media_urls = data[:media_urls]
-      @retry_count = data[:retry_count]
-      @metadata = data[:metadata]
-      @batch_id = data[:batch_id]
+                :created_at, :segments, :credits_used, :message_format,
+                :media_urls, :retry_count, :metadata, :batch_id
+
+    def initialize(data = {})
+      super
+      # Both spellings name the same message: the current payload shape uses
+      # `id`, the pre-`data.object` shape used `message_id`.
+      @id = self[:id] || self[:message_id]
+      @status = self[:status]
+      @to = self[:to]
+      @from = self[:from]
+      @direction = self[:direction]
+      @organization_id = self[:organization_id]
+      @text = self[:text]
+      @error = self[:error]
+      @error_code = self[:error_code]
+      @delivered_at = self[:delivered_at]
+      @failed_at = self[:failed_at]
+      @created_at = self[:created_at]
+      @segments = self[:segments]
+      @credits_used = self[:credits_used]
+      @message_format = self[:message_format]
+      @media_urls = self[:media_urls]
+      @retry_count = self[:retry_count]
+      @metadata = self[:metadata]
+      @batch_id = self[:batch_id]
     end
 
+    # Backwards-compatible alias for {#id}.
     def message_id
       @id
     end
-
-    def to_h
-      {
-        id: @id,
-        status: @status,
-        to: @to,
-        from: @from,
-        direction: @direction,
-        error: @error,
-        error_code: @error_code,
-        delivered_at: @delivered_at,
-        failed_at: @failed_at,
-        segments: @segments,
-        credits_used: @credits_used,
-        batch_id: @batch_id
-      }.compact
-    end
   end
 
-  class WebhookVerificationData
+  # The verification view of +data.object+, built only for +verification.*+
+  # events. Readers carry what the payload held and nothing more.
+  class WebhookVerificationData < WebhookObject
     attr_reader :id, :organization_id, :phone, :status, :delivery_status,
                 :attempts, :max_attempts, :expires_at, :verified_at,
                 :created_at, :app_name, :template_id, :profile_id, :metadata
 
     def initialize(data = {})
-      @id = data["id"]
-      @organization_id = data["organization_id"]
-      @phone = data["phone"]
-      @status = data["status"]
-      @delivery_status = data["delivery_status"] || "queued"
-      @attempts = data["attempts"] || 0
-      @max_attempts = data["max_attempts"] || 3
-      @expires_at = data["expires_at"]
-      @verified_at = data["verified_at"]
-      @created_at = data["created_at"]
-      @app_name = data["app_name"]
-      @template_id = data["template_id"]
-      @profile_id = data["profile_id"]
-      @metadata = data["metadata"]
+      super
+      @id = self[:id]
+      @organization_id = self[:organization_id]
+      @phone = self[:phone]
+      @status = self[:status]
+      @delivery_status = self[:delivery_status]
+      @attempts = self[:attempts]
+      @max_attempts = self[:max_attempts]
+      @expires_at = self[:expires_at]
+      @verified_at = self[:verified_at]
+      @created_at = self[:created_at]
+      @app_name = self[:app_name]
+      @template_id = self[:template_id]
+      @profile_id = self[:profile_id]
+      @metadata = self[:metadata]
+    end
+  end
+
+  # A parsed webhook event.
+  #
+  # {#raw_object} is +data.object+ exactly as it arrived, for every event type.
+  # {#data} adds a typed view on top of it where one applies: a
+  # {WebhookMessageData} for +message.*+, a {WebhookVerificationData} for
+  # +verification.*+, and a plain {WebhookObject} for everything else —
+  # +rcs_*+, +whatsapp_*+, +call.*+, +brand.*+, +campaign.*+, +assignment.*+,
+  # +number.*+, +port*+, +contact*+, +conversation.*+ and +draft.*+, whose
+  # payloads are not message-shaped.
+  #
+  # @example Handling a lifecycle event
+  #   case event.type
+  #   when Sendly::Webhooks::EVENT_MESSAGE_DELIVERED
+  #     puts event.message.id
+  #   when Sendly::Webhooks::EVENT_RCS_AGENT_LIVE
+  #     puts event.data[:agent_id]
+  #   end
+  class WebhookEvent
+    MESSAGE_EVENT_PREFIX = 'message.'
+
+    # message.opt_in and message.opt_out share the message.* prefix but carry
+    # an opt-out record ({phone_number, keyword, from_number, timestamp}), not
+    # a message. Treating them as messages produced a message view with every
+    # field nil, which is the invented-value problem this class removes.
+    NON_MESSAGE_MESSAGE_EVENTS = ['message.opt_in', 'message.opt_out'].freeze
+    VERIFICATION_EVENT_PREFIX = 'verification.'
+
+    # @return [String] event id, for idempotency
+    attr_reader :id
+
+    # @return [String] event type, verbatim — including one this SDK predates
+    attr_reader :type
+
+    # @return [Hash] +data.object+ exactly as it arrived, for every event type
+    attr_reader :raw_object
+
+    # @return [WebhookObject] hash-like view of +data.object+. A
+    #   {WebhookMessageData} for +message.*+ events and a
+    #   {WebhookVerificationData} for +verification.*+ events; a plain
+    #   {WebhookObject} otherwise.
+    attr_reader :data
+
+    # @return [WebhookMessageData, nil] the message view, or nil when this
+    #   event is not a message. Lifecycle events return nil rather than a
+    #   message struct full of invented values.
+    attr_reader :message
+
+    # @return [WebhookVerificationData, nil] the verification view, or nil
+    #   when this event is not a +verification.*+ event
+    attr_reader :verification
+
+    attr_reader :created, :api_version, :livemode
+
+    def initialize(payload)
+      env = payload.is_a?(WebhookObject) ? payload : WebhookObject.new(payload)
+
+      @id = env[:id]
+      @type = env[:type]
+      @raw_object = extract_object(env[:data])
+      @created = env[:created] || env[:created_at] || 0
+      @api_version = env[:api_version] || '2024-01'
+      @livemode = env[:livemode] || false
+
+      @message = message? ? WebhookMessageData.new(@raw_object) : nil
+      @verification = verification? ? WebhookVerificationData.new(@raw_object) : nil
+      @data = @message || @verification || WebhookObject.new(@raw_object)
+    end
+
+    # @return [Hash] alias for {#raw_object}
+    def object
+      @raw_object
+    end
+
+    # Read +data.object+ as a type of your choosing — the supported way to
+    # handle a lifecycle payload with a typed object.
+    #
+    # A Struct or Data class is filled from the members it declares, and the
+    # rest of the payload is ignored, so a field added to the event later
+    # cannot break the call. Any other class is handed +raw_object+ itself.
+    #
+    # @example
+    #   AgentLive = Struct.new(:agent_id, :name, :stage)
+    #   agent = event.object_as(AgentLive)   # => #<struct AgentLive ...>
+    #
+    # @param klass [Class] a Struct or Data class, or anything whose
+    #   initializer takes a Hash
+    # @return [Object]
+    def object_as(klass)
+      return klass.new(@raw_object) unless klass.respond_to?(:members)
+
+      values = klass.members.map { |member| @data[member] }
+      begin
+        klass.new(*values)
+      rescue ArgumentError
+        klass.new(**klass.members.zip(values).to_h)
+      end
+    end
+
+    # @return [Boolean] whether this event carries a message
+    def message?
+      @type.to_s.start_with?(MESSAGE_EVENT_PREFIX) &&
+        !NON_MESSAGE_MESSAGE_EVENTS.include?(@type.to_s)
+    end
+
+    # @return [Boolean] whether this event carries a verification
+    def verification?
+      @type.to_s.start_with?(VERIFICATION_EVENT_PREFIX)
+    end
+
+    def created_at
+      @created
+    end
+
+    def to_h
+      {
+        id: @id,
+        type: @type,
+        data: @data.to_h,
+        created: @created,
+        api_version: @api_version,
+        livemode: @livemode
+      }
+    end
+
+    private
+
+    def extract_object(data)
+      return {} unless data.is_a?(Hash)
+
+      object = data.key?(:object) ? data[:object] : data['object']
+      object.is_a?(Hash) ? object : data
     end
   end
 end

metadata

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