ruby-whatsapp 0.3.0

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    class Message
+      # Common envelope shared by every inbound message type: who sent it, its
+      # wamid, when it arrived, and (optionally) what it's replying to.
+      class Base
+        # @!attribute [rw] from
+        #   @return [String, nil]
+        attr_accessor :from
+
+        # @!attribute [rw] id
+        #   @return [String, nil] The message's wamid.
+        attr_accessor :id
+
+        # @!attribute [rw] timestamp
+        #   @return [String, nil]
+        attr_accessor :timestamp
+
+        # @!attribute [rw] type
+        #   @return [String, nil]
+        attr_accessor :type
+
+        # @!attribute [rw] context
+        #   @return [Context, nil]
+        attr_accessor :context
+
+        # @!attribute [rw] referral
+        #   @return [Referral, nil]
+        attr_accessor :referral
+
+        def initialize(from:, id:, timestamp:, type:, context: nil, referral: nil)
+          @from = from
+          @id = id
+          @timestamp = timestamp
+          @type = type
+          @context = context
+          @referral = referral
+        end
+
+        class << self
+          # Extracts the fields every message type shares, for subclasses to
+          # merge with their own type-specific payload before calling `new`.
+          # @param data [Hash] The raw message hash.
+          # @return [Hash]
+          def common_attributes(data)
+            {
+              from: data["from"],
+              id: data["id"],
+              timestamp: data["timestamp"],
+              type: data["type"],
+              context: Context.deserialize(data["context"]),
+              referral: Referral.deserialize(data["referral"]),
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    class Message
+      # An inbound tap on a template's quick-reply button.
+      class Button < Base
+        # @!attribute [rw] text
+        #   @return [String, nil] The button's display text.
+        attr_accessor :text
+
+        # @!attribute [rw] payload
+        #   @return [String, nil] The developer-defined payload configured on the template button.
+        attr_accessor :payload
+
+        def initialize(text:, payload:, **base_attributes)
+          super(**base_attributes)
+
+          @text = text
+          @payload = payload
+        end
+
+        class << self
+          # @param data [Hash] The raw message hash.
+          # @return [Button]
+          def deserialize(data)
+            new(text: data.dig("button", "text"), payload: data.dig("button", "payload"), **common_attributes(data))
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    class Message
+      class Contacts < Base
+        # A physical address entry within an inbound contact card.
+        class Address
+          # @!attribute [rw] street
+          #   @return [String, nil]
+          attr_accessor :street
+
+          # @!attribute [rw] city
+          #   @return [String, nil]
+          attr_accessor :city
+
+          # @!attribute [rw] state
+          #   @return [String, nil]
+          attr_accessor :state
+
+          # @!attribute [rw] zip
+          #   @return [String, nil]
+          attr_accessor :zip
+
+          # @!attribute [rw] country
+          #   @return [String, nil]
+          attr_accessor :country
+
+          # @!attribute [rw] country_code
+          #   @return [String, nil]
+          attr_accessor :country_code
+
+          # @!attribute [rw] type
+          #   @return [String, nil]
+          attr_accessor :type
+
+          def initialize(street: nil, city: nil, state: nil, zip: nil, country: nil, country_code: nil, type: nil)
+            @street = street
+            @city = city
+            @state = state
+            @zip = zip
+            @country = country
+            @country_code = country_code
+            @type = type
+          end
+
+          class << self
+            # @param data [Hash] A raw `addresses[]` entry.
+            # @return [Address]
+            def deserialize(data)
+              data ||= {}
+
+              new(
+                street: data["street"],
+                city: data["city"],
+                state: data["state"],
+                zip: data["zip"],
+                country: data["country"],
+                country_code: data["country_code"],
+                type: data["type"]
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    class Message
+      class Contacts < Base
+        # A single inbound contact card.
+        class Contact
+          # @!attribute [rw] name
+          #   @return [Name]
+          attr_accessor :name
+
+          # @!attribute [rw] phones
+          #   @return [Array<Phone>]
+          attr_accessor :phones
+
+          # @!attribute [rw] emails
+          #   @return [Array<Email>]
+          attr_accessor :emails
+
+          # @!attribute [rw] addresses
+          #   @return [Array<Address>]
+          attr_accessor :addresses
+
+          # @!attribute [rw] org
+          #   @return [Org, nil]
+          attr_accessor :org
+
+          # @!attribute [rw] urls
+          #   @return [Array<Url>]
+          attr_accessor :urls
+
+          # @!attribute [rw] birthday
+          #   @return [String, nil] Date in YYYY-MM-DD format.
+          attr_accessor :birthday
+
+          def initialize(name:, phones:, emails:, addresses:, urls:, org: nil, birthday: nil)
+            @name = name
+            @phones = phones
+            @emails = emails
+            @addresses = addresses
+            @org = org
+            @urls = urls
+            @birthday = birthday
+          end
+
+          class << self
+            # @param data [Hash] A raw `contacts[]` entry.
+            # @return [Contact]
+            def deserialize(data)
+              data ||= {}
+
+              new(
+                name: Name.deserialize(data["name"]),
+                phones: Array(data["phones"]).map { |phone_data| Phone.deserialize(phone_data) },
+                emails: Array(data["emails"]).map { |email_data| Email.deserialize(email_data) },
+                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"]
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    class Message
+      class Contacts < Base
+        # An email entry within an inbound contact card.
+        class Email
+          # @!attribute [rw] email
+          #   @return [String, nil]
+          attr_accessor :email
+
+          # @!attribute [rw] type
+          #   @return [String, nil]
+          attr_accessor :type
+
+          def initialize(email:, type: nil)
+            @email = email
+            @type = type
+          end
+
+          class << self
+            # @param data [Hash] A raw `emails[]` entry.
+            # @return [Email]
+            def deserialize(data)
+              data ||= {}
+
+              new(email: data["email"], type: data["type"])
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    class Message
+      class Contacts < Base
+        # The name component of an inbound contact card.
+        class Name
+          # @!attribute [rw] formatted_name
+          #   @return [String, nil]
+          attr_accessor :formatted_name
+
+          # @!attribute [rw] first_name
+          #   @return [String, nil]
+          attr_accessor :first_name
+
+          # @!attribute [rw] last_name
+          #   @return [String, nil]
+          attr_accessor :last_name
+
+          # @!attribute [rw] middle_name
+          #   @return [String, nil]
+          attr_accessor :middle_name
+
+          # @!attribute [rw] prefix
+          #   @return [String, nil]
+          attr_accessor :prefix
+
+          # @!attribute [rw] suffix
+          #   @return [String, nil]
+          attr_accessor :suffix
+
+          def initialize(formatted_name:, first_name: nil, last_name: nil, middle_name: nil, prefix: nil, suffix: nil)
+            @formatted_name = formatted_name
+            @first_name = first_name
+            @last_name = last_name
+            @middle_name = middle_name
+            @prefix = prefix
+            @suffix = suffix
+          end
+
+          class << self
+            # @param data [Hash] The raw `name` hash.
+            # @return [Name]
+            def deserialize(data)
+              data ||= {}
+
+              new(
+                formatted_name: data["formatted_name"],
+                first_name: data["first_name"],
+                last_name: data["last_name"],
+                middle_name: data["middle_name"],
+                prefix: data["prefix"],
+                suffix: data["suffix"]
+              )
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    class Message
+      class Contacts < Base
+        # The organization details of an inbound contact card.
+        class Org
+          # @!attribute [rw] company
+          #   @return [String, nil]
+          attr_accessor :company
+
+          # @!attribute [rw] department
+          #   @return [String, nil]
+          attr_accessor :department
+
+          # @!attribute [rw] title
+          #   @return [String, nil]
+          attr_accessor :title
+
+          def initialize(company: nil, department: nil, title: nil)
+            @company = company
+            @department = department
+            @title = title
+          end
+
+          class << self
+            # @param data [Hash, nil] The raw `org` hash.
+            # @return [Org]
+            def deserialize(data)
+              data ||= {}
+
+              new(company: data["company"], department: data["department"], title: data["title"])
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    class Message
+      class Contacts < Base
+        # A phone number entry within an inbound contact card.
+        class Phone
+          # @!attribute [rw] phone
+          #   @return [String, nil]
+          attr_accessor :phone
+
+          # @!attribute [rw] type
+          #   @return [String, nil]
+          attr_accessor :type
+
+          # @!attribute [rw] wa_id
+          #   @return [String, nil]
+          attr_accessor :wa_id
+
+          def initialize(phone:, type: nil, wa_id: nil)
+            @phone = phone
+            @type = type
+            @wa_id = wa_id
+          end
+
+          class << self
+            # @param data [Hash] A raw `phones[]` entry.
+            # @return [Phone]
+            def deserialize(data)
+              data ||= {}
+
+              new(phone: data["phone"], type: data["type"], wa_id: data["wa_id"])
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    class Message
+      class Contacts < Base
+        # A URL entry within an inbound contact card.
+        class Url
+          # @!attribute [rw] url
+          #   @return [String, nil]
+          attr_accessor :url
+
+          # @!attribute [rw] type
+          #   @return [String, nil]
+          attr_accessor :type
+
+          def initialize(url:, type: nil)
+            @url = url
+            @type = type
+          end
+
+          class << self
+            # @param data [Hash] A raw `urls[]` entry.
+            # @return [Url]
+            def deserialize(data)
+              data ||= {}
+
+              new(url: data["url"], type: data["type"])
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    class Message
+      # An inbound shared contact card (or cards).
+      class Contacts < Base
+        # @!attribute [rw] contacts
+        #   @return [Array<Contact>]
+        attr_accessor :contacts
+
+        def initialize(contacts:, **base_attributes)
+          super(**base_attributes)
+
+          @contacts = contacts
+        end
+
+        class << self
+          # @param data [Hash] The raw message hash.
+          # @return [Contacts]
+          def deserialize(data)
+            new(
+              contacts: Array(data["contacts"]).map { |contact_data| Contact.deserialize(contact_data) },
+              **common_attributes(data)
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    class Message
+      # Present when an inbound message replies to a previous one (e.g. a reply
+      # swipe, or a tap on an interactive button/list from an earlier message).
+      class Context
+        # @!attribute [rw] from
+        #   @return [String, nil]
+        attr_accessor :from
+
+        # @!attribute [rw] id
+        #   @return [String, nil] The wamid of the message being replied to.
+        attr_accessor :id
+
+        # @!attribute [rw] forwarded
+        #   @return [Boolean, nil]
+        attr_accessor :forwarded
+
+        # @!attribute [rw] frequently_forwarded
+        #   @return [Boolean, nil]
+        attr_accessor :frequently_forwarded
+
+        def initialize(from:, id:, forwarded: nil, frequently_forwarded: nil)
+          @from = from
+          @id = id
+          @forwarded = forwarded
+          @frequently_forwarded = frequently_forwarded
+        end
+
+        class << self
+          # @param data [Hash, nil] The raw `context` hash.
+          # @return [Context, nil]
+          def deserialize(data)
+            return if data.nil?
+
+            new(
+              from: data["from"],
+              id: data["id"],
+              forwarded: data["forwarded"],
+              frequently_forwarded: data["frequently_forwarded"]
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    class Message
+      # An inbound document message.
+      class Document < Media
+        # @!attribute [rw] filename
+        #   @return [String, nil]
+        attr_accessor :filename
+
+        def initialize(filename: nil, **media_and_base_attributes)
+          super(**media_and_base_attributes)
+
+          @filename = filename
+        end
+
+        class << self
+          # @param data [Hash] The raw message hash.
+          # @return [Document]
+          def deserialize(data)
+            new(
+              filename: data.dig("document", "filename"),
+              **media_attributes(data, "document"),
+              **common_attributes(data)
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    class Message
+      # An inbound image message.
+      class Image < Media
+        class << self
+          # @param data [Hash] The raw message hash.
+          # @return [Image]
+          def deserialize(data)
+            new(**media_attributes(data, "image"), **common_attributes(data))
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    class Message
+      # An inbound reply to an interactive message — a button tap (`button_reply`)
+      # or a list row selection (`list_reply`).
+      class Interactive < Base
+        # @!attribute [rw] interactive_type
+        #   @return [String, nil] Either `"button_reply"` or `"list_reply"`.
+        attr_accessor :interactive_type
+
+        # @!attribute [rw] reply_id
+        #   @return [String, nil] The id of the tapped button/row.
+        attr_accessor :reply_id
+
+        # @!attribute [rw] title
+        #   @return [String, nil]
+        attr_accessor :title
+
+        # @!attribute [rw] description
+        #   @return [String, nil] Only present for `list_reply`.
+        attr_accessor :description
+
+        def initialize(interactive_type:, reply_id:, title:, description: nil, **base_attributes)
+          super(**base_attributes)
+
+          @interactive_type = interactive_type
+          @reply_id = reply_id
+          @title = title
+          @description = description
+        end
+
+        class << self
+          # @param data [Hash] The raw message hash.
+          # @return [Interactive]
+          def deserialize(data)
+            interactive_type = data.dig("interactive", "type")
+            reply = data.dig("interactive", interactive_type) || {}
+
+            new(
+              interactive_type:,
+              reply_id: reply["id"],
+              title: reply["title"],
+              description: reply["description"],
+              **common_attributes(data)
+            )
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Whatsapp
+  module Webhook
+    class Message
+      # An inbound shared location.
+      class Location < Base
+        # @!attribute [rw] latitude
+        #   @return [Float, nil]
+        attr_accessor :latitude
+
+        # @!attribute [rw] longitude
+        #   @return [Float, nil]
+        attr_accessor :longitude
+
+        # @!attribute [rw] name
+        #   @return [String, nil]
+        attr_accessor :name
+
+        # @!attribute [rw] address
+        #   @return [String, nil]
+        attr_accessor :address
+
+        def initialize(latitude:, longitude:, name: nil, address: nil, **base_attributes)
+          super(**base_attributes)
+
+          @latitude = latitude
+          @longitude = longitude
+          @name = name
+          @address = address
+        end
+
+        class << self
+          # @param data [Hash] The raw message hash.
+          # @return [Location]
+          def deserialize(data)
+            new(
+              latitude: data.dig("location", "latitude"),
+              longitude: data.dig("location", "longitude"),
+              name: data.dig("location", "name"),
+              address: data.dig("location", "address"),
+              **common_attributes(data)
+            )
+          end
+        end
+      end
+    end
+  end
+end