ruby-whatsapp 0.4.2 → 0.6.1

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

@@ -10,13 +10,33 @@ module Whatsapp
       #   @return [String, nil]
       attr_accessor :profile_name
 
+      # @!attribute [rw] username
+      #   @return [String, nil] Set only if the user has adopted a username. Read from
+      #     `profile.username`, where Meta's App Dashboard test payloads put it, falling
+      #     back to a flat top-level `username` — `user_id`/`parent_user_id` arrive flat
+      #     on this same hash and Meta publishes no reference schema for the contact
+      #     object, so both locations are read rather than betting on one.
+      attr_accessor :username
+
       # @!attribute [rw] wa_id
-      #   @return [String, nil]
+      #   @return [String, nil] Omitted once the user adopts a username, unless a
+      #     recent interaction or the contact book still allows sharing the phone number.
       attr_accessor :wa_id
 
-      def initialize(profile_name:, 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
+
+      def initialize(profile_name: nil, username: nil, wa_id: nil, user_id: nil, parent_user_id: nil)
         @profile_name = profile_name
+        @username = username
         @wa_id = wa_id
+        @user_id = user_id
+        @parent_user_id = parent_user_id
       end
 
       class << self
@@ -27,7 +47,10 @@ module Whatsapp
 
           new(
             profile_name: data.dig("profile", "name"),
-            wa_id: data["wa_id"]
+            username: data.dig("profile", "username") || data["username"],
+            wa_id: data["wa_id"],
+            user_id: data["user_id"],
+            parent_user_id: data["parent_user_id"]
           )
         end
       end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    class History
+      # A single `history[]` entry: one chunk of a chat-history sync, plus the counters
+      # that tell you how far through the sync it is.
+      class Chunk
+        # @!attribute [rw] phase
+        #   @return [Integer, nil] Which sync phase this chunk belongs to.
+        attr_accessor :phase
+
+        # @!attribute [rw] chunk_order
+        #   @return [Integer, nil] This chunk's position within its phase.
+        attr_accessor :chunk_order
+
+        # @!attribute [rw] progress
+        #   @return [Integer, nil] Percent complete, 0-100.
+        attr_accessor :progress
+
+        # @!attribute [rw] threads
+        #   @return [Array<Thread>]
+        attr_accessor :threads
+
+        def initialize(phase: nil, chunk_order: nil, progress: nil, threads: [])
+          @phase = phase
+          @chunk_order = chunk_order
+          @progress = progress
+          @threads = threads
+        end
+
+        class << self
+          # @param data [Hash, nil] A raw `history[]` entry.
+          # @return [Chunk]
+          def deserialize(data)
+            data ||= {}
+            metadata = data["metadata"] || {}
+
+            new(
+              phase: metadata["phase"],
+              chunk_order: metadata["chunk_order"],
+              progress: metadata["progress"],
+              threads: Array(data["threads"]).map { |thread_data| Thread.deserialize(thread_data) }
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    class History
+      # One conversation within a history {Chunk}: who it is with, and the messages in it.
+      #
+      # Named for Meta's `threads[]` key. Nested under {History}, so it never shadows
+      # `::Thread` for anything outside this class.
+      class Thread
+        # @!attribute [rw] id
+        #   @return [String, nil] The thread's identifier — the user's phone number, omitted
+        #     if they had already adopted a username when the sync was requested and their
+        #     number was no longer shareable. Use {#context} to identify them instead.
+        attr_accessor :id
+
+        # @!attribute [rw] context
+        #   @return [Contact, nil] Who the thread is with (`wa_id`, `user_id`,
+        #     `parent_user_id`, `username`). Deserialized with the same
+        #     {Whatsapp::Webhook::Contact} as every other contact entry — its `username`
+        #     read already falls back to a flat key, which is where Meta puts it here, and
+        #     its `profile_name` is simply `nil` since a thread context carries no profile.
+        attr_accessor :context
+
+        # @!attribute [rw] messages
+        #   @return [Array<Message::Base>] The synced messages, dispatched by `type` like
+        #     any inbound message.
+        #
+        #     Each one also carries a `history_context.status` (its delivery state at sync
+        #     time), which is **not** modelled: it would put a history-only field on
+        #     `Message::Base`, the envelope shared by every inbound message type, where it
+        #     could never appear. Read it from {#raw} instead.
+        attr_accessor :messages
+
+        # @!attribute [r] raw
+        #   @return [Hash] The untouched thread hash, so the unmodelled per-message
+        #     `history_context` stays reachable. Read-only; not a copy.
+        attr_reader :raw
+
+        def initialize(id: nil, context: nil, messages: [], raw: {})
+          @id = id
+          @context = context
+          @messages = messages
+          @raw = raw
+        end
+
+        class << self
+          # @param data [Hash, nil] A raw `threads[]` entry.
+          # @return [Thread]
+          def deserialize(data)
+            data ||= {}
+
+            new(
+              id: data["id"],
+              context: data["context"] ? Contact.deserialize(data["context"]) : nil,
+              messages: Array(data["messages"]).map { |message_data| Message.deserialize(message_data) },
+              raw: data
+            )
+          end
+        end
+      end
+    end
+  end
+end

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