ruby-whatsapp 0.4.0 → 0.6.1

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

@@ -2,50 +2,89 @@
 
 module Whatsapp
   module Webhook
-    # Chat history synchronization for onboarded business customers.
+    # Chat history synchronization for onboarded business customers — one of the fields
+    # with a confirmed, JSON-example-backed schema, alongside {Messages},
+    # {UserIdUpdate}, {BusinessUsernameUpdates}, and {UserPreferences}.
     #
-    # Best-effort schema: Meta's public docs describe this field in one line with
-    # no published JSON example; `threads`' entry shape isn't confidently
-    # typeable from that description alone, so it's kept as a raw array 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
+    # History arrives in chunks. Each `history[]` entry is one {Chunk}, carrying its own
+    # sync `metadata` (`phase`/`chunk_order`/`progress`) and the {Thread}s in it — note
+    # that the value-level `metadata` is the ordinary business-phone-number
+    # {Whatsapp::Webhook::Metadata}, a different object entirely.
+    #
+    # Meta sends a second variant of this field for a synced media asset, which carries
+    # `contacts` and `messages` at the value level instead of inside a thread; both are
+    # mapped here, and are empty for a thread-carrying payload.
+    # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/business-scoped-user-ids
     class History
-      # @!attribute [rw] phase
-      #   @return [Integer, nil]
-      attr_accessor :phase
-
-      # @!attribute [rw] chunk_order
-      #   @return [Integer, nil]
-      attr_accessor :chunk_order
-
-      # @!attribute [rw] progress
-      #   @return [Integer, nil]
-      attr_accessor :progress
-
-      # @!attribute [rw] threads
-      #   @return [Array<Hash>]
-      attr_accessor :threads
-
-      def initialize(phase:, chunk_order:, progress:, threads:)
-        @phase = phase
-        @chunk_order = chunk_order
-        @progress = progress
-        @threads = threads
+      # @!attribute [rw] messaging_product
+      #   @return [String, nil]
+      attr_accessor :messaging_product
+
+      # @!attribute [rw] metadata
+      #   @return [Metadata, nil] The business phone number this history belongs to — not
+      #     the per-chunk sync metadata, which lives on {Chunk}.
+      attr_accessor :metadata
+
+      # @!attribute [rw] chunks
+      #   @return [Array<Chunk>]
+      attr_accessor :chunks
+
+      # @!attribute [rw] contacts
+      #   @return [Array<Contact>] Populated only by the media-asset variant.
+      attr_accessor :contacts
+
+      # @!attribute [rw] messages
+      #   @return [Array<Message::Base>] Populated only by the media-asset variant; a
+      #     thread-carrying payload puts its messages on {Thread#messages} instead.
+      attr_accessor :messages
+
+      # @!attribute [r] raw
+      #   @return [Hash] The untouched `value` hash. A diagnostic escape hatch, not part of
+      #     the supported API: this field has two payload variants and the deeper one nests
+      #     three levels, so a key that drifts would leave a typed accessor empty with no
+      #     other trace. Treat it as read-only — it is the object `JSON.parse` returned.
+      attr_reader :raw
+
+      def initialize(messaging_product:, metadata:, chunks:, contacts:, messages:, raw: {})
+        @messaging_product = messaging_product
+        @metadata = metadata
+        @chunks = chunks
+        @contacts = contacts
+        @messages = messages
+        @raw = raw
+      end
+
+      # A delivery normally carries exactly one chunk, so these three read through to it
+      # rather than making every caller reach for `chunks.first`. Check {#chunks} directly
+      # if you need to handle a multi-chunk delivery.
+      # @return [Integer, nil]
+      def phase
+        chunks.first&.phase
+      end
+
+      # @return [Integer, nil]
+      def chunk_order
+        chunks.first&.chunk_order
+      end
+
+      # @return [Integer, nil] Percent complete, 0-100.
+      def progress
+        chunks.first&.progress
       end
 
       class << self
-        # @param data [Hash] The raw `value` hash.
+        # @param data [Hash] The raw `history` field's `value` hash.
         # @return [History]
         def deserialize(data)
           data ||= {}
-          metadata = data["metadata"] || {}
 
           new(
-            phase: metadata["phase"],
-            chunk_order: metadata["chunk_order"],
-            progress: metadata["progress"],
-            threads: Array(data["threads"])
+            messaging_product: data["messaging_product"],
+            metadata: data["metadata"] ? Metadata.deserialize(data["metadata"]) : nil,
+            chunks: Array(data["history"]).map { |chunk_data| Chunk.deserialize(chunk_data) },
+            contacts: Array(data["contacts"]).map { |contact_data| Contact.deserialize(contact_data) },
+            messages: Array(data["messages"]).map { |message_data| Message.deserialize(message_data) },
+            raw: data
           )
         end
       end

data/lib/ruby/whatsapp/webhook/message/base.rb

@@ -7,9 +7,24 @@ module Whatsapp
       # wamid, when it arrived, and (optionally) what it's replying to.
       class Base
         # @!attribute [rw] from
-        #   @return [String, nil]
+        #   @return [String, nil] Omitted once the sender adopts a username, unless a
+        #     recent interaction or the contact book still allows sharing the phone number.
         attr_accessor :from
 
+        # @!attribute [rw] from_user_id
+        #   @return [String, nil] The sender's business-scoped user ID (BSUID).
+        attr_accessor :from_user_id
+
+        # @!attribute [rw] from_parent_user_id
+        #   @return [String, nil] The sender's parent BSUID, present only when enrolled.
+        attr_accessor :from_parent_user_id
+
+        # @!attribute [rw] group_id
+        #   @return [String, nil] Set only when the message was sent in a group chat.
+        #     Reading groups works; this gem wraps no Groups API, so there is no way to
+        #     reply into one — the id is for correlation and for filtering group traffic out.
+        attr_accessor :group_id
+
         # @!attribute [rw] id
         #   @return [String, nil] The message's wamid.
         attr_accessor :id
@@ -30,8 +45,15 @@ module Whatsapp
         #   @return [Referral, nil]
         attr_accessor :referral
 
-        def initialize(from:, id:, timestamp:, type:, context: nil, referral: nil)
+        def initialize(
+          id:, timestamp:, type:,
+          from: nil, from_user_id: nil, from_parent_user_id: nil, group_id: nil,
+          context: nil, referral: nil
+        )
           @from = from
+          @from_user_id = from_user_id
+          @from_parent_user_id = from_parent_user_id
+          @group_id = group_id
           @id = id
           @timestamp = timestamp
           @type = type
@@ -47,6 +69,9 @@ module Whatsapp
           def common_attributes(data)
             {
               from: data["from"],
+              from_user_id: data["from_user_id"],
+              from_parent_user_id: data["from_parent_user_id"],
+              group_id: data["group_id"],
               id: data["id"],
               timestamp: data["timestamp"],
               type: data["type"],

data/lib/ruby/whatsapp/webhook/message/contacts/contact.rb

@@ -34,7 +34,16 @@ module Whatsapp
           #   @return [String, nil] Date in YYYY-MM-DD format.
           attr_accessor :birthday
 
-          def initialize(name:, phones:, emails:, addresses:, urls:, org: nil, birthday: nil)
+          # @!attribute [rw] vcard
+          #   @return [String, nil] The card's raw vCard, set only when `origin` is `"other"`.
+          attr_accessor :vcard
+
+          # @!attribute [rw] origin
+          #   @return [String, nil] `"contact_request"` (a `REQUEST_CONTACT_INFO` button tap)
+          #     or `"other"` (shared directly from the chat).
+          attr_accessor :origin
+
+          def initialize(name:, phones:, emails:, addresses:, urls:, org: nil, birthday: nil, vcard: nil, origin: nil)
             @name = name
             @phones = phones
             @emails = emails
@@ -42,6 +51,8 @@ module Whatsapp
             @org = org
             @urls = urls
             @birthday = birthday
+            @vcard = vcard
+            @origin = origin
           end
 
           class << self
@@ -57,7 +68,9 @@ module Whatsapp
                 addresses: Array(data["addresses"]).map { |address_data| Address.deserialize(address_data) },
                 org: data["org"] ? Org.deserialize(data["org"]) : nil,
                 urls: Array(data["urls"]).map { |url_data| Url.deserialize(url_data) },
-                birthday: data["birthday"]
+                birthday: data["birthday"],
+                vcard: data["vcard"],
+                origin: data["origin"]
               )
             end
           end

data/lib/ruby/whatsapp/webhook/message/context.rb

@@ -7,9 +7,22 @@ module Whatsapp
       # swipe, or a tap on an interactive button/list from an earlier message).
       class Context
         # @!attribute [rw] from
-        #   @return [String, nil]
+        #   @return [String, nil] The WhatsApp ID of the quoted message's sender, absent
+        #     once they adopt a username and their phone number is no longer shareable.
         attr_accessor :from
 
+        # @!attribute [rw] from_user_id
+        #   @return [String, nil] The quoted sender's BSUID, the fallback identifier once
+        #     {#from} is gone. **The key name is inferred** by symmetry with
+        #     {Base#from_user_id} — Meta has not published a `context` example carrying
+        #     it. Validate against a real payload before depending on it.
+        attr_accessor :from_user_id
+
+        # @!attribute [rw] from_parent_user_id
+        #   @return [String, nil] The quoted sender's parent BSUID, present only for
+        #     businesses enrolled in parent BSUIDs. Key name inferred, as above.
+        attr_accessor :from_parent_user_id
+
         # @!attribute [rw] id
         #   @return [String, nil] The wamid of the message being replied to.
         attr_accessor :id
@@ -22,8 +35,14 @@ module Whatsapp
         #   @return [Boolean, nil]
         attr_accessor :frequently_forwarded
 
-        def initialize(from:, id:, forwarded: nil, frequently_forwarded: nil)
+        def initialize(
+          id:,
+          from: nil, from_user_id: nil, from_parent_user_id: nil,
+          forwarded: nil, frequently_forwarded: nil
+        )
           @from = from
+          @from_user_id = from_user_id
+          @from_parent_user_id = from_parent_user_id
           @id = id
           @forwarded = forwarded
           @frequently_forwarded = frequently_forwarded
@@ -37,6 +56,8 @@ module Whatsapp
 
             new(
               from: data["from"],
+              from_user_id: data["from_user_id"],
+              from_parent_user_id: data["from_parent_user_id"],
               id: data["id"],
               forwarded: data["forwarded"],
               frequently_forwarded: data["frequently_forwarded"]

data/lib/ruby/whatsapp/webhook/message/edit.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    class Message
+      # A user edited a message they had sent you. Like {Revoke}, a control message: it
+      # names the message being replaced and carries the replacement content.
+      #
+      # Also arrives through {Whatsapp::Webhook::SmbMessageEchoes} when the business
+      # itself edits a message from the WhatsApp Business app.
+      # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages/edit
+      class Edit < Base
+        # @!attribute [rw] original_message_id
+        #   @return [String, nil] The wamid of the message being replaced.
+        attr_accessor :original_message_id
+
+        # @!attribute [rw] message
+        #   @return [Base, nil] The replacement content, dispatched by its own `type`
+        #     through {Message.deserialize} like any other message.
+        #
+        #     It carries *content only*. Meta's example gives the nested payload a `type`,
+        #     its type body, and a `context`, but no `from`/`id`/`timestamp` of its own —
+        #     those belong to the outer envelope, so the nested message's equivalents read
+        #     `nil`. Reach for `edit.id` and `edit.from`, not `edit.message.id`.
+        attr_accessor :message
+
+        def initialize(original_message_id: nil, message: nil, **base_attributes)
+          super(**base_attributes)
+
+          @original_message_id = original_message_id
+          @message = message
+        end
+
+        class << self
+          # @param data [Hash] The raw message hash.
+          # @return [Edit]
+          def deserialize(data)
+            edit = data["edit"] || {}
+
+            new(
+              original_message_id: edit["original_message_id"],
+              message: edit["message"] ? Message.deserialize(edit["message"]) : nil,
+              **common_attributes(data)
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/webhook/message/revoke.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    class Message
+      # A user deleted a message they had sent you. A control message rather than a
+      # content one: it names a message you already received instead of carrying a body.
+      #
+      # Also arrives through {Whatsapp::Webhook::SmbMessageEchoes} when the business
+      # itself revokes a message from the WhatsApp Business app.
+      # Source: https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages/revoke
+      class Revoke < Base
+        # @!attribute [rw] original_message_id
+        #   @return [String, nil] The wamid of the message that was deleted.
+        attr_accessor :original_message_id
+
+        def initialize(original_message_id: nil, **base_attributes)
+          super(**base_attributes)
+
+          @original_message_id = original_message_id
+        end
+
+        class << self
+          # @param data [Hash] The raw message hash.
+          # @return [Revoke]
+          def deserialize(data)
+            new(
+              original_message_id: data.dig("revoke", "original_message_id"),
+              **common_attributes(data)
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ruby/whatsapp/webhook/message/system.rb

@@ -17,16 +17,31 @@ module Whatsapp
         #   @return [String, nil] The customer's (possibly new) WhatsApp ID.
         attr_accessor :wa_id
 
+        # @!attribute [rw] user_id
+        #   @return [String, nil] The customer's new business-scoped user ID (BSUID),
+        #     set when the change was a `user_changed_user_id` event.
+        attr_accessor :user_id
+
+        # @!attribute [rw] parent_user_id
+        #   @return [String, nil] The customer's new parent BSUID, present only when enrolled.
+        attr_accessor :parent_user_id
+
         # @!attribute [rw] change_type
-        #   @return [String, nil] e.g. `"customer_changed_number"`, `"customer_identity_changed"`.
+        #   @return [String, nil] e.g. `"customer_changed_number"`, `"user_changed_user_id"`.
         attr_accessor :change_type
 
-        def initialize(body:, identity:, wa_id:, change_type:, **base_attributes)
+        def initialize(
+          change_type:,
+          body: nil, identity: nil, wa_id: nil, user_id: nil, parent_user_id: nil,
+          **base_attributes
+        )
           super(**base_attributes)
 
           @body = body
           @identity = identity
           @wa_id = wa_id
+          @user_id = user_id
+          @parent_user_id = parent_user_id
           @change_type = change_type
         end
 
@@ -38,6 +53,8 @@ module Whatsapp
               body: data.dig("system", "body"),
               identity: data.dig("system", "identity"),
               wa_id: data.dig("system", "wa_id"),
+              user_id: data.dig("system", "user_id"),
+              parent_user_id: data.dig("system", "parent_user_id"),
               change_type: data.dig("system", "type"),
               **common_attributes(data)
             )

data/lib/ruby/whatsapp/webhook/message/unknown.rb

@@ -7,9 +7,9 @@ module Whatsapp
       # type Meta added after this gem was released, or a message the Cloud API
       # itself couldn't process (carries an `errors[]` array in that case).
       class Unknown < Base
-        # @!attribute [rw] raw
+        # @!attribute [r] raw
         #   @return [Hash] The full, untyped raw message hash.
-        attr_accessor :raw
+        attr_reader :raw
 
         # @!attribute [rw] errors
         #   @return [Array<Error>]

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

@@ -22,6 +22,9 @@ module Whatsapp
         order: Order,
         system: System,
         reaction: Reaction,
+        # Control types: these name a prior message rather than carrying content of their own.
+        revoke: Revoke,
+        edit: Edit,
       }.freeze
 
       class << self

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