ruby-whatsapp 0.4.0 → 0.6.1

data/lib/ruby/whatsapp/webhook/smb_message_echoes/echo.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    class SmbMessageEchoes
+      # One echoed message: who the business sent it *to*, plus the message itself.
+      #
+      # A wrapper rather than three more accessors on {Message::Base}, deliberately.
+      # `Base` is the envelope shared by every inbound message type, and an inbound
+      # message can never carry a recipient — Meta's own convention is that a keyword
+      # defaults to `nil` when a field is *conditional*, not when it is impossible.
+      # Putting `to`/`to_user_id`/`to_parent_user_id` there to serve this one field would
+      # hand fifteen classes three permanently-`nil` readers, and would turn the
+      # `NoMethodError` that currently tells you `message.to` is meaningless into a silent
+      # `nil`. Composing instead keeps {Message.deserialize}'s dispatch untouched, so an
+      # echoed `revoke` or `edit` resolves exactly as an inbound one does.
+      class Echo
+        # @!attribute [rw] to
+        #   @return [String, nil] The customer's phone number. Omitted once they adopt a
+        #     username and it is no longer shareable — fall back to {#to_user_id}.
+        attr_accessor :to
+
+        # @!attribute [rw] to_user_id
+        #   @return [String, nil] The customer's business-scoped user ID (BSUID).
+        attr_accessor :to_user_id
+
+        # @!attribute [rw] to_parent_user_id
+        #   @return [String, nil] The customer's parent BSUID, present only when enrolled.
+        attr_accessor :to_parent_user_id
+
+        # @!attribute [rw] message
+        #   @return [Message::Base] The echoed message, dispatched by `type` like any
+        #     inbound one. Its `from` is the *business* number, not the customer's.
+        attr_accessor :message
+
+        def initialize(message:, to: nil, to_user_id: nil, to_parent_user_id: nil)
+          @to = to
+          @to_user_id = to_user_id
+          @to_parent_user_id = to_parent_user_id
+          @message = message
+        end
+
+        class << self
+          # @param data [Hash, nil] A raw `message_echoes[]` entry.
+          # @return [Echo]
+          def deserialize(data)
+            data ||= {}
+
+            new(
+              to: data["to"],
+              to_user_id: data["to_user_id"],
+              to_parent_user_id: data["to_parent_user_id"],
+              message: Message.deserialize(data)
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/webhook/smb_message_echoes.rb

@@ -2,15 +2,14 @@
 
 module Whatsapp
   module Webhook
-    # Messages sent via the WhatsApp Business App or a linked device, echoed back
-    # so a Cloud API integration stays in sync with what the business itself sent.
+    # Messages sent via the WhatsApp Business App or a linked device, echoed back so a
+    # Cloud API integration stays in sync with what the business itself sent — including
+    # messages the business revoked or edited from the app.
     #
-    # Best-effort schema: Meta's public docs describe this field in one line with
-    # no published JSON example, but do state these mirror the standard inbound
-    # `messages` shape — hence reusing {Message.deserialize} here. The exact key
-    # name (`message_echoes`) is a best-effort guess; validate against a real
-    # payload before relying on it in production.
-    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview
+    # Meta's BSUID documentation publishes the value-level `contacts` array and the
+    # per-echo recipient identifiers. The array key itself (`message_echoes`) remains
+    # inferred, hence {#raw}.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids
     class SmbMessageEchoes
       # @!attribute [rw] messaging_product
       #   @return [String, nil]
@@ -20,14 +19,28 @@ module Whatsapp
       #   @return [Metadata, nil]
       attr_accessor :metadata
 
+      # @!attribute [rw] contacts
+      #   @return [Array<Contact>] The customers these messages went to.
+      attr_accessor :contacts
+
       # @!attribute [rw] message_echoes
-      #   @return [Array<Message::Base>]
+      #   @return [Array<Echo>] Each pairs the echoed message with who it was sent to.
       attr_accessor :message_echoes
 
-      def initialize(messaging_product:, metadata:, message_echoes:)
+      # @!attribute [r] raw
+      #   @return [Hash] The untouched `value` hash. A diagnostic escape hatch, not part of
+      #     the supported API: {#message_echoes} reads `value["message_echoes"]`, a key
+      #     inferred from the field's own name rather than confirmed by a published
+      #     example, so a key that drifts would leave the array empty with no other trace.
+      #     Read-only — it is the object `JSON.parse` returned, not a copy.
+      attr_reader :raw
+
+      def initialize(messaging_product:, metadata:, message_echoes:, contacts: [], raw: {})
         @messaging_product = messaging_product
         @metadata = metadata
+        @contacts = contacts
         @message_echoes = message_echoes
+        @raw = raw
       end
 
       class << self
@@ -39,7 +52,9 @@ module Whatsapp
           new(
             messaging_product: data["messaging_product"],
             metadata: data["metadata"] ? Metadata.deserialize(data["metadata"]) : nil,
-            message_echoes: Array(data["message_echoes"]).map { |echo_data| Message.deserialize(echo_data) }
+            contacts: Array(data["contacts"]).map { |contact_data| Contact.deserialize(contact_data) },
+            message_echoes: Array(data["message_echoes"]).map { |echo_data| Echo.deserialize(echo_data) },
+            raw: data
           )
         end
       end

data/lib/ruby/whatsapp/webhook/status.rb

@@ -18,9 +18,22 @@ module Whatsapp
       attr_accessor :timestamp
 
       # @!attribute [rw] recipient_id
-      #   @return [String, nil]
+      #   @return [String, nil] Omitted when sent to the recipient's BSUID and their
+      #     phone number is unavailable.
       attr_accessor :recipient_id
 
+      # @!attribute [rw] recipient_user_id
+      #   @return [String, nil] The recipient's business-scoped user ID (BSUID). Meta sends
+      #     it on every status, however the message was addressed — a phone number in `to`
+      #     does not suppress it. The single exception is a `"failed"` status for a message
+      #     sent to a phone number, where it is omitted; a `"failed"` status for a
+      #     BSUID-addressed message still carries it.
+      attr_accessor :recipient_user_id
+
+      # @!attribute [rw] recipient_parent_user_id
+      #   @return [String, nil] The recipient's parent BSUID, present only when enrolled.
+      attr_accessor :recipient_parent_user_id
+
       # @!attribute [rw] conversation
       #   @return [Conversation, nil]
       attr_accessor :conversation
@@ -33,11 +46,17 @@ module Whatsapp
       #   @return [Array<Error>]
       attr_accessor :errors
 
-      def initialize(id:, status:, timestamp:, recipient_id:, conversation: nil, pricing: nil, errors: [])
+      def initialize(
+        id:, status:, timestamp:,
+        recipient_id: nil, recipient_user_id: nil, recipient_parent_user_id: nil,
+        conversation: nil, pricing: nil, errors: []
+      )
         @id = id
         @status = status
         @timestamp = timestamp
         @recipient_id = recipient_id
+        @recipient_user_id = recipient_user_id
+        @recipient_parent_user_id = recipient_parent_user_id
         @conversation = conversation
         @pricing = pricing
         @errors = errors
@@ -54,6 +73,8 @@ module Whatsapp
             status: data["status"],
             timestamp: data["timestamp"],
             recipient_id: data["recipient_id"],
+            recipient_user_id: data["recipient_user_id"],
+            recipient_parent_user_id: data["recipient_parent_user_id"],
             conversation: data["conversation"] ? Conversation.deserialize(data["conversation"]) : nil,
             pricing: data["pricing"] ? Pricing.deserialize(data["pricing"]) : nil,
             errors: Array(data["errors"]).map { |error_data| Error.deserialize(error_data) }

data/lib/ruby/whatsapp/webhook/user_id_update/entry.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    class UserIdUpdate
+      # A single `user_id_update[]` entry: one user's BSUID (and parent BSUID, if
+      # enrolled) changed.
+      class Entry
+        # @!attribute [rw] wa_id
+        #   @return [String, nil] The user's phone number, if available.
+        attr_accessor :wa_id
+
+        # @!attribute [rw] detail
+        #   @return [String, nil] Human-readable description of the change.
+        attr_accessor :detail
+
+        # @!attribute [rw] user_id
+        #   @return [IdChange, nil] The user's previous and current BSUID.
+        attr_accessor :user_id
+
+        # @!attribute [rw] parent_user_id
+        #   @return [IdChange, nil] The user's previous and current parent BSUID,
+        #     present only when enrolled.
+        attr_accessor :parent_user_id
+
+        # @!attribute [rw] timestamp
+        #   @return [String, nil]
+        attr_accessor :timestamp
+
+        def initialize(timestamp:, wa_id: nil, detail: nil, user_id: nil, parent_user_id: nil)
+          @wa_id = wa_id
+          @detail = detail
+          @user_id = user_id
+          @parent_user_id = parent_user_id
+          @timestamp = timestamp
+        end
+
+        class << self
+          # @param data [Hash] A raw `user_id_update[]` entry.
+          # @return [Entry]
+          def deserialize(data)
+            data ||= {}
+
+            new(
+              wa_id: data["wa_id"],
+              detail: data["detail"],
+              user_id: IdChange.deserialize(data["user_id"]),
+              parent_user_id: IdChange.deserialize(data["parent_user_id"]),
+              timestamp: data["timestamp"]
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/webhook/user_id_update/id_change.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    class UserIdUpdate
+      # The `{previous, current}` shape shared by `user_id` and `parent_user_id` on a
+      # `user_id_update[]` entry.
+      class IdChange
+        # @!attribute [rw] previous
+        #   @return [String, nil]
+        attr_accessor :previous
+
+        # @!attribute [rw] current
+        #   @return [String, nil]
+        attr_accessor :current
+
+        def initialize(previous:, current:)
+          @previous = previous
+          @current = current
+        end
+
+        class << self
+          # @param data [Hash, nil] The raw `user_id` or `parent_user_id` hash.
+          # @return [IdChange, nil] `nil` when the key is absent — an id change that did
+          #   not happen is not a change from nothing to nothing.
+          def deserialize(data)
+            return if data.nil?
+
+            new(previous: data["previous"], current: data["current"])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/webhook/user_id_update.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    # A WhatsApp user's business-scoped user ID (BSUID) changed — for example, after
+    # they changed their phone number (see the `system` message type's
+    # `user_changed_user_id` event) or were re-scoped by Meta.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids
+    class UserIdUpdate
+      # @!attribute [rw] messaging_product
+      #   @return [String, nil]
+      attr_accessor :messaging_product
+
+      # @!attribute [rw] metadata
+      #   @return [Metadata, nil]
+      attr_accessor :metadata
+
+      # @!attribute [rw] contacts
+      #   @return [Array<Contact>]
+      attr_accessor :contacts
+
+      # @!attribute [rw] updates
+      #   @return [Array<Entry>]
+      attr_accessor :updates
+
+      # @!attribute [r] raw
+      #   @return [Hash] The untouched `value` hash. A diagnostic escape hatch, not part
+      #     of the supported API: {#updates} reads `value["user_id_update"]` — entries
+      #     nested under a repeat of the field's own name, which is what Meta's published
+      #     example shows — so a key that drifts would otherwise leave `updates` empty
+      #     with no other trace. Reach for it when a typed accessor is unexpectedly
+      #     `nil`, log what you find, and treat it as read-only: it is the object
+      #     `JSON.parse` returned, not a copy.
+      attr_reader :raw
+
+      def initialize(messaging_product:, metadata:, contacts:, updates:, raw: {})
+        @messaging_product = messaging_product
+        @metadata = metadata
+        @contacts = contacts
+        @updates = updates
+        @raw = raw
+      end
+
+      class << self
+        # @param data [Hash] The raw `user_id_update` field's `value` hash.
+        # @return [UserIdUpdate]
+        def deserialize(data)
+          data ||= {}
+
+          new(
+            messaging_product: data["messaging_product"],
+            metadata: data["metadata"] ? Metadata.deserialize(data["metadata"]) : nil,
+            contacts: Array(data["contacts"]).map { |contact_data| Contact.deserialize(contact_data) },
+            updates: Array(data["user_id_update"]).map { |entry_data| Entry.deserialize(entry_data) },
+            raw: data
+          )
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/webhook/user_preferences/entry.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    class UserPreferences
+      # A single `user_preferences[]` entry: one user changed one preference.
+      class Entry
+        # @!attribute [rw] wa_id
+        #   @return [String, nil] The user's phone number, omitted once they adopt a
+        #     username and it is no longer shareable. Fall back to {#user_id}.
+        attr_accessor :wa_id
+
+        # @!attribute [rw] user_id
+        #   @return [String, nil] The user's business-scoped user ID (BSUID).
+        attr_accessor :user_id
+
+        # @!attribute [rw] parent_user_id
+        #   @return [String, nil] The user's parent BSUID, present only when enrolled.
+        attr_accessor :parent_user_id
+
+        # @!attribute [rw] detail
+        #   @return [String, nil] Human-readable description of the change.
+        attr_accessor :detail
+
+        # @!attribute [rw] category
+        #   @return [String, nil] The preference category. `"marketing_messages"` is the
+        #     only value Meta documents; kept a raw String, never validated on the way in,
+        #     so a category added later still round-trips.
+        attr_accessor :category
+
+        # @!attribute [rw] value
+        #   @return [String, nil] The preference itself, e.g. `"stop"` or `"resume"`. Note
+        #     the name: this sits *inside* the change's own `value` hash, so the full path
+        #     reads `change.value.preferences.first.value`. Meta's naming, not ours.
+        attr_accessor :value
+
+        # @!attribute [rw] timestamp
+        #   @return [Integer, String, nil] Unix seconds. Meta's example sends a number
+        #     here, unlike the string timestamps on `messages`, so it is passed through
+        #     as-is rather than coerced.
+        attr_accessor :timestamp
+
+        def initialize(
+          wa_id: nil, user_id: nil, parent_user_id: nil,
+          detail: nil, category: nil, value: nil, timestamp: nil
+        )
+          @wa_id = wa_id
+          @user_id = user_id
+          @parent_user_id = parent_user_id
+          @detail = detail
+          @category = category
+          @value = value
+          @timestamp = timestamp
+        end
+
+        class << self
+          # @param data [Hash, nil] A raw `user_preferences[]` entry.
+          # @return [Entry]
+          def deserialize(data)
+            data ||= {}
+
+            new(
+              wa_id: data["wa_id"],
+              user_id: data["user_id"],
+              parent_user_id: data["parent_user_id"],
+              detail: data["detail"],
+              category: data["category"],
+              value: data["value"],
+              timestamp: data["timestamp"]
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/webhook/user_preferences.rb

@@ -3,43 +3,64 @@
 module Whatsapp
   module Webhook
     # User marketing message preference changes (e.g. a customer opting out of
-    # marketing messages).
+    # marketing messages) — one of the fields with a confirmed, JSON-example-backed
+    # schema, alongside {Messages}, {UserIdUpdate}, and {BusinessUsernameUpdates}.
     #
-    # Best-effort schema: Meta's public docs describe this field in one line with
-    # no published JSON example. Validate against a real payload (App Dashboard
-    # "send test payload") before relying on these attribute names in production.
-    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview
+    # Structurally identical to {UserIdUpdate}: the value carries the notification's
+    # own identity (`messaging_product`, `metadata`, `contacts`) plus an array of
+    # entries nested under a repeat of the field's own name.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids
     class UserPreferences
-      # @!attribute [rw] wa_id
+      # @!attribute [rw] messaging_product
       #   @return [String, nil]
-      attr_accessor :wa_id
+      attr_accessor :messaging_product
 
-      # @!attribute [rw] detail
-      #   @return [String, nil]
-      attr_accessor :detail
+      # @!attribute [rw] metadata
+      #   @return [Metadata, nil]
+      attr_accessor :metadata
 
-      # @!attribute [rw] value
-      #   @return [String, nil] e.g. `"stop"`, `"resume"`.
-      attr_accessor :value
+      # @!attribute [rw] contacts
+      #   @return [Array<Contact>] The users whose preferences changed, carrying the same
+      #     BSUID identifiers as every other `contacts[]` entry — which is how a
+      #     username-adopted user is identifiable here at all once their phone number
+      #     stops being shared.
+      attr_accessor :contacts
 
-      # @!attribute [rw] timestamp
-      #   @return [String, nil]
-      attr_accessor :timestamp
+      # @!attribute [rw] preferences
+      #   @return [Array<Entry>]
+      attr_accessor :preferences
+
+      # @!attribute [r] raw
+      #   @return [Hash] The untouched `value` hash. A diagnostic escape hatch, not part
+      #     of the supported API: {#preferences} reads `value["user_preferences"]` —
+      #     entries nested under a repeat of the field's own name, which is what Meta's
+      #     published example shows — so a key that drifts would otherwise leave
+      #     `preferences` empty with no other trace. Reach for it when a typed accessor is
+      #     unexpectedly `nil`, log what you find, and treat it as read-only: it is the
+      #     object `JSON.parse` returned, not a copy.
+      attr_reader :raw
 
-      def initialize(wa_id:, detail:, value:, timestamp:)
-        @wa_id = wa_id
-        @detail = detail
-        @value = value
-        @timestamp = timestamp
+      def initialize(messaging_product:, metadata:, contacts:, preferences:, raw: {})
+        @messaging_product = messaging_product
+        @metadata = metadata
+        @contacts = contacts
+        @preferences = preferences
+        @raw = raw
       end
 
       class << self
-        # @param data [Hash] The raw `value` hash.
+        # @param data [Hash] The raw `user_preferences` field's `value` hash.
         # @return [UserPreferences]
         def deserialize(data)
           data ||= {}
 
-          new(wa_id: data["wa_id"], detail: data["detail"], value: data["value"], timestamp: data["timestamp"])
+          new(
+            messaging_product: data["messaging_product"],
+            metadata: data["metadata"] ? Metadata.deserialize(data["metadata"]) : nil,
+            contacts: Array(data["contacts"]).map { |contact_data| Contact.deserialize(contact_data) },
+            preferences: Array(data["user_preferences"]).map { |entry_data| Entry.deserialize(entry_data) },
+            raw: data
+          )
         end
       end
     end