ruby-whatsapp 0.4.2 → 0.6.2

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

@@ -2,9 +2,10 @@
 
 module Whatsapp
   module Webhook
-    # The `messages` webhook field's `value` payload — the only field with a
-    # confirmed, JSON-example-backed schema in Meta's docs. Carries inbound
-    # messages and/or delivery status updates for one of your business phone numbers.
+    # The `messages` webhook field's `value` payload — one of five fields with a
+    # confirmed, JSON-example-backed schema in Meta's docs, alongside {UserIdUpdate}
+    # and {BusinessUsernameUpdates}. Carries inbound messages and/or delivery status
+    # updates for one of your business phone numbers.
     # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview
     class Messages
       # @!attribute [rw] messaging_product

data/lib/ruby/whatsapp/webhook/smb_app_state_sync/contact.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    class SmbAppStateSync
+      # A synced address-book entry from the WhatsApp Business app.
+      #
+      # The gem's third `Contact`, and none of them are interchangeable:
+      # {Whatsapp::Webhook::Contact} is a notification's sender identity (`profile.name`,
+      # `wa_id`), {Whatsapp::Webhook::Message::Contacts::Contact} is a shared contact
+      # *card* of vCard-shaped arrays, and this is a device address-book row
+      # (`full_name`, `first_name`, `phone_number`). Forcing any two together would mean
+      # dual-key reads on both sides for no gain.
+      #
+      # A sibling of {StateSync} rather than nested inside it, following
+      # {UserIdUpdate::IdChange}.
+      class Contact
+        # @!attribute [rw] full_name
+        #   @return [String, nil]
+        attr_accessor :full_name
+
+        # @!attribute [rw] first_name
+        #   @return [String, nil]
+        attr_accessor :first_name
+
+        # @!attribute [rw] phone_number
+        #   @return [String, nil] Omitted once the contact adopts a username and their
+        #     number is no longer shareable. Fall back to {#user_id}.
+        attr_accessor :phone_number
+
+        # @!attribute [rw] user_id
+        #   @return [String, nil] The contact's business-scoped user ID (BSUID).
+        attr_accessor :user_id
+
+        # @!attribute [rw] parent_user_id
+        #   @return [String, nil] The contact's parent BSUID, present only when enrolled.
+        attr_accessor :parent_user_id
+
+        # @!attribute [rw] username
+        #   @return [String, nil] Set only if the contact has adopted a username. Read
+        #     flat, unlike {Whatsapp::Webhook::Contact#username}, which Meta nests under
+        #     `profile` — do not copy that dual read here.
+        attr_accessor :username
+
+        def initialize(
+          full_name: nil, first_name: nil, phone_number: nil,
+          user_id: nil, parent_user_id: nil, username: nil
+        )
+          @full_name = full_name
+          @first_name = first_name
+          @phone_number = phone_number
+          @user_id = user_id
+          @parent_user_id = parent_user_id
+          @username = username
+        end
+
+        class << self
+          # @param data [Hash, nil] A raw `contact` hash.
+          # @return [Contact]
+          def deserialize(data)
+            data ||= {}
+
+            new(
+              full_name: data["full_name"],
+              first_name: data["first_name"],
+              phone_number: data["phone_number"],
+              user_id: data["user_id"],
+              parent_user_id: data["parent_user_id"],
+              username: data["username"]
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/webhook/smb_app_state_sync/state_sync.rb

@@ -6,7 +6,7 @@ module Whatsapp
       # A single contact-sync entry within an `smb_app_state_sync` notification.
       class StateSync
         # @!attribute [rw] type
-        #   @return [String, nil]
+        #   @return [String, nil] `"contact"` is the only kind Meta documents.
         attr_accessor :type
 
         # @!attribute [rw] action
@@ -14,13 +14,22 @@ module Whatsapp
         attr_accessor :action
 
         # @!attribute [rw] contact
-        #   @return [Hash] Left untyped — Meta's docs don't publish this entry's schema.
+        #   @return [Contact, nil] The synced address-book entry.
         attr_accessor :contact
 
-        def initialize(type:, action:, contact:)
+        # @!attribute [rw] timestamp
+        #   @return [String, nil] Flattened up from this entry's own `metadata.timestamp`.
+        #     That nested object is *not* {Whatsapp::Webhook::Metadata} — it carries only a
+        #     timestamp, so the wrapper is dropped rather than typed, the same habit as
+        #     {Contact#profile_name}. Should Meta add a sibling key there, this becomes a
+        #     class instead.
+        attr_accessor :timestamp
+
+        def initialize(type:, action:, contact: nil, timestamp: nil)
           @type = type
           @action = action
           @contact = contact
+          @timestamp = timestamp
         end
 
         class << self
@@ -29,7 +38,12 @@ module Whatsapp
           def deserialize(data)
             data ||= {}
 
-            new(type: data["type"], action: data["action"], contact: data["contact"] || {})
+            new(
+              type: data["type"],
+              action: data["action"],
+              contact: data["contact"] ? Contact.deserialize(data["contact"]) : nil,
+              timestamp: data.dig("metadata", "timestamp")
+            )
           end
         end
       end

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

@@ -2,21 +2,40 @@
 
 module Whatsapp
   module Webhook
-    # Contact synchronization for onboarded WhatsApp Business app users.
+    # Contact synchronization for onboarded WhatsApp Business app users: the address book
+    # on the device, mirrored to your integration as entries are added, changed, or removed.
     #
-    # Best-effort schema: Meta's public docs describe this field in one line with
-    # no published JSON example; each entry's `contact` shape isn't confidently
-    # typeable from that description alone, so it's kept as a raw hash rather
-    # than guessing further. Validate against a real payload before relying on
-    # this in production.
-    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/overview
+    # Meta's BSUID documentation publishes the synced contact's shape, so
+    # {StateSync#contact} is a typed {Contact} rather than a raw hash. The array key
+    # itself (`state_sync`) is still inferred from the field name — hence {#raw}.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids
     class SmbAppStateSync
+      # @!attribute [rw] messaging_product
+      #   @return [String, nil]
+      attr_accessor :messaging_product
+
+      # @!attribute [rw] metadata
+      #   @return [Metadata, nil] The business phone number whose address book this is —
+      #     not the per-entry metadata, whose timestamp is flattened onto {StateSync}.
+      attr_accessor :metadata
+
       # @!attribute [rw] state_sync
       #   @return [Array<StateSync>]
       attr_accessor :state_sync
 
-      def initialize(state_sync:)
+      # @!attribute [r] raw
+      #   @return [Hash] The untouched `value` hash. A diagnostic escape hatch, not part of
+      #     the supported API: {#state_sync} reads `value["state_sync"]`, 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(state_sync:, messaging_product: nil, metadata: nil, raw: {})
+        @messaging_product = messaging_product
+        @metadata = metadata
         @state_sync = state_sync
+        @raw = raw
       end
 
       class << self
@@ -25,7 +44,12 @@ module Whatsapp
         def deserialize(data)
           data ||= {}
 
-          new(state_sync: Array(data["state_sync"]).map { |entry| StateSync.deserialize(entry) })
+          new(
+            messaging_product: data["messaging_product"],
+            metadata: data["metadata"] ? Metadata.deserialize(data["metadata"]) : nil,
+            state_sync: Array(data["state_sync"]).map { |entry| StateSync.deserialize(entry) },
+            raw: data
+          )
         end
       end
     end

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